Set up RFA connection
Component: | RFA |
Functional area: | Pubset and MRSCAT management |
Domain: | MULTI-CATALOG-AND-PUBSET-MGMT |
Privileges: | STD-PROCESSING |
This command is available only to users who have the RFA software product (see also the “RFA” manual [31]).
Function
This command sets up an RFA connection. The first time a connection to a remote system is set up, a partner task is generated under the specified user ID. This command can also be used for a local catalog. In that case, an RFA connection is set up within the local system; a partner task is not generated.
The user can issue the SHOW-RFA-CONNECTIONS command to get information on all existing RFA connections.
The REMOVE-RFA-CONNECTION command is used to clear down an RFA connection. For each SET-RFA-CONNECTION command, a corresponding REMOVE-RFA-CONNECTION must be given. A partner task on a remote system is not terminated until the last connection is cleared. When the local user task is terminated, all existing RFA connections are automatically cleared down by the system.
Prerequisite
Each processor on which the command will be given must have an entry for the specified catalog ID with the appropriate processor name in the MRS catalog. The user can check up on entries in the MRS catalog with the aid of the SHOW-MASTER-CATALOG-ENTRY command.
Format
SET-RFA-CONNECTION | ||||||||||||||||||||||||||||||||||||||||||||||||||
| ||||||||||||||||||||||||||||||||||||||||||||||||||
Operands
CATALOG-ID = <cat-id 1..4>
Catalog ID to which the RFA connection is to be set up.
If the catalog ID is not entered in the MRS catalog, or the entry is incorrect or incomplete or the catalog is not accessible, the command is rejected.
The user can issue the command SHOW-MASTER-CATALOG-ENTRY to find out if the catalog ID is entered in the MRS catalog.
If the catalog ID refers to a remote processor, and if the SET-RFA-CONNECTION command is the first for this processor, a partner task will be generated on this processor. If the catalog ID refers to the local system, no partner task is generated.
PROCESSING-ADMISSION = *PARAMETERS(...)
Specifications concerning the partner task to be created.
These specifications are only evaluated if the RFA connection to a remote processor is being set up for the first time. In this case, a partner task is generated and the specifications checked for LOGON authorization.
For subsequent SET-RFA-CONNECTIONS to other catalogs of the remote processor these specifications are ignored. (For exception, see notes for shared pubset "SET-RFA-CONNECTION".) The already-generated partner task is used for access to additional catalogs of this remote processor.
USER-IDENTIFICATION = *SAME / <name 1..8>
User ID under which the partner task is to run.
USER-IDENTIFICATION = *SAME
The user’s own user ID (under which the command is issued) applies.
ACCOUNT = *SAME / <alphanum-name 1..8>
Account number under which the partner task is to run.
ACCOUNT = *SAME
The account number of the current user task (under which the command was issued) applies.
PASSWORD = *NONE / <c-string 1..8> / <c-string 9.32>/ <x-string 1..16> / *SECRET
Password of the user ID under which the partner task is to run.
The long password mechanism is supported (<c-string 9..32>). See the MODIFY-USER-PROTECTION command description for details of the long password mechanism.
If the PASSWORD operand is defined as “secret”:
The value which is input will not be logged.
In guided dialog, the input field is automatically blanked out.
In unguided dialog and in foreground procedures, *SECRET or ^ allows for concealed input of the required value. SDF requests the input of the “secret” value and provides a blanked input field for this purpose.
The password must be specified even if it is the same as the one for the current user task. The user ID, account number and password are all checked by the remote system. The other LOGON parameters (JOB-NAME and LOGGING) for the partner task are taken from the current user task.
CONNECTION =
Specifies whether the attempt to set up a connection is to be made only once or more than once within a defined period.
CONNECTION = *IMMEDIATE
The attempt to set up an RFA connection is made just once. If it is unsuccessful, the user is issued an error message.
CONNECTION = *WITHIN(...)
Specification of a period within which the system attempts to set up the RFA connection.
SECONDS = <integer 32..99999999 seconds>
Period in seconds within which the system attempts to set up the connection every 32 seconds (if repetition is reasonable).
If the attempts were unsuccessful, an error message is issued.
ANSWER = *STD / N / Y / *SYSDTA
This operand is evaluated only in procedures or batch operation.
After the LOGON is processed, the first information block of the bulletin file, containing systems support information, is output. If the prompt CONTINUE Y/N is issued, the user can see the next information block by entering “Y”, or answer “N” to decline.
This operand specifies how prompts concerning continued output of the information blocks output by the remote system during connection setup are to be answered.
ANSWER = *STD
In interactive operation, the prompts of the remote system are sent to the local processor and are to be answered there from the terminal. The responses are sent to the remote system and evaluated there.
In procedure mode and batch mode, ANSWER=N applies, i.e. all prompts are answered with “N”.
ANSWER = N
All prompts from the remote system are answered with “N”.
ANSWER = Y
All prompts from the remote system are answered with “Y”.
ANSWER = *SYSDTA
All prompts from the remote system are sent to the local processor, where the responses are expected from SYSDTA. The responses are sent to the remote system and evaluated there.
Responses from SYSDTA make sense only if the user knows the number of information blocks in the remote bulletin file, i.e. when the user knows exactly which information blocks he or she wants to receive.
Return codes
(SC2) | SC1 | Maincode | Meaning |
|---|---|---|---|
0 | RFA0002 | Command executed | |
1 | RFA0026 | Command for shared pubset rejected | |
64 | RFA0016 | BS2000 version of remote system not supported | |
64 | RFA0023 | RFA connection faulty | |
64 | RFA0024 | No additional RFA connections possible | |
64 | RFA0027 | Configuration error |
Notes
Setting up a connection to a target processor by means of RFA is subject to the following restrictions:
RFA does not support user authentication via the Kerberos LOGON, i.e. no user ID protected by the Kerberos LOGON may be specified in the target processor in the SET-RFA-CONNECTION command.
RFA does not support the entry of a personal user ID (SET-PERSONAL-ATTRIBUTES command, see the “SECOS” manual [35]). RFA connection setup to a target ID protected with a “personal LOGON” is only possible if PASSWORD-CHECK=*NO is set for the user ID, but the password is specified anyway in the SET-RFA-CONNECTION command.
The REMOVE-RFA-CONNECTION command clears down the RFA connection. When the task is terminated, the system automatically clears down any RFA connections which still exist.
Procedure nesting: if two or more SET-RFA-CONNECTION commands are issued for the same catalog ID (of the remote system), there must be as many REMOVE-RFA-CONNECTION commands as there were SET-RFA-CONNECTION commands in order to clear this connection.
Shared pubsets
A pubset entered in the MRSCAT in conjunction with SHARED-PUBSET=*YES in the ADD-MASTER-CATALOG-ENTRY or MODIFY-MASTER-CATALOG-ENTRY command can be used as a shared pubset.
If there is not yet an RFA connection to the processor associated with this pubset, an RFA connection can be set up to the pubset
if the user ID in the SET-RFA-CONNECTION command matches the user ID of the RFA task;
if the user ID in the SET-RFA-CONNECTION command is not the same as the user ID of the RFA task, and the pubset is not imported as a shared pubset and not locally accessible.
If there already is an RFA connection to the processor associated with this pubset, an RFA connection to the pubset can only be set up if the user ID in the SET-RFA-CONNECTION command matches the user ID of the RFA task and the AFR partner task.
In all other cases, a SET-RFA-CONNECTION command for this pubset is rejected. Due to this restriction, SHARED-PUBSET=*YES should only be defined for pubsets which are really used as shared pubsets.
An RFA connection to a shared pubset with the catalog ID catid will not be set up if catid is entered in the user catalog as the default catalog ID for the user ID of the local task.