This chapter describes how to use the RSFLINK application programming interface (API) to call programs on remote machines.
RSFLINK is an API that allows you to easily call any program on a remote machine. Up to 10 parameters can be passed to the remote program, and changed parameter values can be returned to your program. Diagnostic, information and escape messages generated by the remote program call can be returned to your program as well. Each parameter passed to the remote program can be up to 1024 bytes long.
The types of things you can do with RSFLINK include:
RSFLINK handles the communications link for you, under the covers, allowing you to call programs on remote machines as easily as calling a program on your local machine.
Note: Your attempt to call a remote program will be rejected by the server machine unless a requester directory entry exists on the server machine which refers to your machine, and specifies *YES or *PARTIAL for "Allow remote program calls". See Adding Requester Directory Entries for more information.
Examples of how to use RSFLINK are included in library RSFTOOLS. See Appendix B for more information about RSFTOOLS.
There are two ways to access RSFLINK:
Whichever method you choose, you specify the qualified name of the remote program to be called as well the server ID or phone number to use to connect to the remote machine.
The methods for accessing RSFLINK are discussed in detail in the following sections.
Program RSFLINK can be called from any language.
The following parameters are required:
|
Parameter |
Usage |
Type/Length |
|---|---|---|
|
Program to call |
Input |
CHAR(20) |
|
Return code |
Output |
CHAR(1) |
|
Server ID |
Input |
CHAR(10) |
|
Server's RSF phone number |
Input |
CHAR(32) |
|
Request type |
Input |
CHAR(1) |
|
Return values flag |
Input |
CHAR(1) |
|
Return messages flag |
Input |
CHAR(1) |
|
User ID and password |
Input |
CHAR(20) |
|
Hang up flag |
Input |
CHAR(1) |
|
Call-back phone number |
Input |
CHAR(32) |
The following parameters are optional:
|
Parameter |
Usage |
Type/Length |
|
Parameter to pass |
Input/Output |
CHAR(*) |
|
Parameter 1 length |
Input |
PACKED(5,0) |
|
. |
. |
. |
|
Parameter to pass |
Input/Output |
CHAR(*) |
|
Parameter n length |
Input |
PACKED(5,0) |
Specify the name of the remote program you want to call in the first 10 characters. Specify the library name in the next 10 characters. You may specify *LIBL for library name.
Specify a character variable to receive the return code. If an attempt to call a remote program ends in error, this is communicated to your program through the return code.
The possible return codes are:
'0': The request was successful.
'1': The request ended in error.
The name of a server directory entry to be referenced. The entry must exist in the server directory on your machine. See Adding Server Directory Entries for more information.
A new RSFLINK session is started each time you specify a different server ID. You can have up to 99 simultaneously active sessions within a single job. To end an active session for a particular server, you must specify the server ID for this parameter and either *END or *ALL for the "Request type" parameter.
The possible values are:
*NONE: No server directory entry is referenced.
*CURRENT: Direct the request to the server that is currently associated with the job. For pass-through target jobs, *CURRENT refers to the source machine. For an RSF pre-processing program running on a server machine, *CURRENT refers to the requester machine. *CURRENT is only valid for this parameter if the job executing the command is an RSF target pass-through job, an RSF pre-processing program executing on the server machine, or a batch job submitted from one of the above two job types. See Starting Pass-Through for more information about RSF pass-through jobs. See Pre-Processing Programs for more information about pre-processing programs.
*ALL: All active RSFLINK sessions for the job will be ended. If you specify *ALL for this parameter, you must specify *END for "Request type".
name: The name of an entry in the server directory on your machine.
The number to dial to reach the server's AS/400.
Note: This parameter is only used to establish a connection to the remote machine. This parameter is ignored if an RSFLINK connection is already active for the server ID specified
The possible values are:
*SERVER: Get connection information from the server directory entry named in the "Server ID" parameter.
phone: number: Enter up to 32 characters for the phone number. The number should include all digits necessary to make the phone connection, including a leading 1 plus area code, and leading 9 for accessing an outside line where necessary. Note: If a value other than *SERVER is entered for this parameter, the connection to the server is assumed to be *SDLCDIAL.
Specify the action you would like RSFLINK to perform.
The possible values are:
'1': Start the link only. The connection to the remote machine is established and your authority to call remote programs is verified. No remote program is called.
'2': Establish the link if necessary, and call the remote program specified. The link remains active after the program is called, even if the remote program ends in error.
'3': End the link only. No remote program is called. If the link is active, it is ended.
'4': Establish the link if necessary, call the remote program specified, and then end the link.
Indicate whether you would like changed parameter values returned to your program.
The possible values are:
Y: Parameters passed to the remote program are returned to your program. Both parameters that were changed and those that were not changed are sent back over the link and returned to your program. Changed parameter values are not returned if the remote program terminates abnormally.
N: Changed parameter values are not returned to your program. Specifying 'N' may provide a small performance improvement.
Indicate whether you would like messages generated by the remote program call to be returned to your program. When messages are returned, they are returned to the caller of RSFLINK with the same type as the original message.
The possible values are:
Y: Messages are returned to your program.
N: Messages are not returned to your program. Specifying 'N' may provide a small performance improvement.
Specify the user ID to use when establishing contact with the remote system in the first 10 characters of this parameter. Specify the password to use in the next 10 characters. Specify *RSFDFT for user ID to connect using the default user profile of RSFSRV. Specify *REQUESTER for user ID from an RSF server job to use the original requester's profile. Click here for more information.
Note: This parameter is only used to establish a connection to the remote machine. This parameter is ignored if an RSFLINK connection is already active for the server ID specified
Whether RSF should hang up the phone connection at the completion of the transaction. This parameter is ignored for non-switched connections.
For RSFLINK, the transaction is considered complete when all active links for the job have been ended.
The possible values are:
Y: The line is disconnected at the completion of the transaction.
N: The server is notified that you would like the line to remain active at the completion of the transaction. The line will remain active if the server has specified HANGUP(*NO) for a requester directory entry on the server machine that refers to your machine. Otherwise, the server hangs up at the end of the transaction. See Adding Requester Directory Entries for more information about requester directory entries. When HANGUP(*NO) is specified by both the requester and server machines, the line remains active until one of the following occurs:
The phone number to pass to the server machine when requesting that the server call your machine back.
Your callback request will be rejected by the server unless a requester directory entry exists on the server machine which refers to your machine, and specifies *YES for "Allow call-back". See Adding Requester Directory Entries for more information about requester directory entries.
If the callback request is accepted by the server, the initial connection is dropped and your job waits for the server machine to call back. Your job will wait up to 120 seconds plus the job default wait time for the server machine to call back before signaling an error.
The possible values are:
*NONE: Callback is not requested.
*RSFDFT: Callback is requested. The phone number specified in the RSF defaults for the line currently being used is passed to the server. See Setting Product Defaults for more information about RSF defaults.
*SERVER: Callback is requested. The callback phone number specified in the server directory entry named in the "Server ID" parameter is used. If no callback phone number is specified in the server directory entry, a value of *NONE is assumed for this parameter.
*MANUAL: Callback is requested, but the return call is placed manually by an operator at the remote site. Manual callback is useful if the remote server machine is attached to a phone line that is answered by a receptionist. When you specify *MANUAL for "Call-back phone number", RSF does not dial the server and request a call back. Instead, RSF immediately resets the line and gets ready for the server machine to call back. You must contact the remote location by voice and have an operator initiate the callback with the Call Back Using RSF (CALBCKRSF) command.
phone number: Callback is requested. Enter up to 32 characters for the callback phone number. The number should include all digits necessary to dial your machine from the server machine, including a leading 1 plus area code, and leading 9 for accessing an outside line where necessary.
If you imbed the special value &DFT anywhere in the phone number string, RSF will insert the default call-back number for the line currently being used at that point in the string. Only the first occurrence of &DFT in the string is replaced. Subsequent occurrences of &DFT are ignored. The special values &dft and &DFT are treated equivalently.
The following parameters are optional with program RSFLINK. These parameters specify parameter data to be passed to the remote program. If you specify any optional parameters, you must specify them in pairs (parameter data/parameter length). Up to 10 parameters can be passed to a remote program. Each parameter can be up to 1024 bytes long.
The parameter is passed as a bit string so packed, zoned, binary and character data types are all supported.
Specify the length of the parameter being passed, in bytes. For example, if the parameter being passed to the remote program is formatted as PACKED(11,2), the parameter data takes up 6 bytes.
Command RSFLINK can only be used within a CL program.
The prompted version of the RSFLINK command is shown below. Click on the image to see command parameter descriptions.
The parameters for the RSFLINK command are described below.
The qualified name of the program to call on the remote machine. This is a required parameter.
The possible values are:
*NONE: No remote program is called. *NONE is only valid if *START or *END is specified for "Request type".
name: The name of the program to call.
The possible library values are:
*LIBL: The library list of the server job is used to locate the program.
library name: The name of the library on the server machine containing the program to be called.
Specify a one-character CL variable to receive the return code.
If an attempt to call a remote program ends in error, this is communicated to your program through the return code. A value of '0' is returned if the call was successful, otherwise '1' is returned.
The possible values are:
variable-name: Enter the name of a CL variable to receive the return code.
The name of a server directory entry to be referenced. The entry must exist in the server directory on your machine. See Adding Server Directory Entries for more information.
A new RSFLINK session is started each time you specify a different server ID. You can have up to 99 simultaneously active sessions within a single job. To end an active session for a particular server, you must specify the server ID for this parameter and either *END or *ALL for the "Request type" parameter.
The possible values are:
*NONE: No server directory entry is referenced.
*CURRENT: Direct the request to the server that is currently associated with the job. For pass-through target jobs, *CURRENT refers to the source machine. For an RSF pre-processing program running on a server machine, *CURRENT refers to the requester machine. *CURRENT is only valid for this parameter if the job executing the command is an RSF target pass-through job, an RSF pre-processing program executing on the server machine, or a batch job submitted from one of the above two job types . See Starting Pass-Through for more information about RSF pass-through jobs. See Pre-processing Programs for more information about pre-processing programs.
*ALL: All active RSFLINK sessions for the job will be ended. If you specify *ALL for this parameter, you must specify *END for "Request type".
name: The name of an entry in the server directory on your machine.
Specify the action you would like RSFLINK to perform.
The possible values are:
*ALL: Establish the link if necessary, call the remote program specified, and then end the link.
*START: Start the link only. The connection to the remote machine is established and your authority to call remote programs is verified. No remote program is called.
*CALL: Establish the link if necessary, and call the remote program specified. The link remains active after the program is called, even if the remote program ends in error.
*END: End the link only. No remote program is called. If the link is active, it is ended.
Indicate whether you would like changed parameter values returned to your program.
The possible values are:
*YES: Parameters passed to the remote program are returned to your program. Both parameters that were changed and those that were not changed are sent back over the link and returned to your program. Changed parameter values are not returned if the remote program terminates abnormally.
*NO: Changed parameter values are not returned to your program. Specifying *NO may provide a small performance improvement.
Indicate whether you would like messages generated by the remote program call to be returned to your program. When messages are returned, they are returned to the caller of RSFLINK with the same type as the original message.
The possible values are:
*YES: Messages are returned to your program.
*NO: Messages are not returned to your program. Specifying *NO may provide a small performance improvement.
Specify a parameter to be passed to the remote program. If you specify a parameter, you must also specify its length in the following command parameter.
Specify the length of the parameter being passed, in bytes. For example, if the parameter being passed to the remote program is formatted as PACKED(11,2), the parameter data takes up 6 bytes.
Specify the user ID and password to use to sign on to the remote system.
Note: This parameter is only used to establish a connection to the remote machine. This parameter is ignored if an RSFLINK connection is already active for the specified server ID.
The possible single values are:
*RSFDFT: The default user profile of RSFSRV is used to sign on to the remote system.
*REQUESTER: The profile used to check authority on the remote machine is the same as the original profile on that machine that was used to initiate the RSF request which connected to this machine. The job in which this command is run must be an RSF server job and *CURRENT must be specified for the "Server ID" (SERVER) parameter.
For example, USER1 on SYSTEMA uses the STRPASRSF command to connect to SYSTEMB. User profile USER2 is used to sign on to SYSTEMB. Now the following command, executed in the target pass-through job on SYSTEMB, will call a program on SYSTEMA and will have USER1's authority to the objects on SYSTEMA:
RSFLINK PGM(MYLIB/MYPGM) RTNCODE(&RTNCODE) SERVER(*CURRENT) USER(*REQUESTER)
The possible user ID values are:
user-ID: Enter a valid user ID for connecting to the remote system.
The possible password values are:
password: Enter the password that corresponds with the user ID specified.
Specify whether RSF should hang up the phone connection at the completion of the transaction. This parameter is ignored for non-switched connections.
For RSFLINK, the transaction is considered complete when all active links for the job have been ended. Click here for a complete description of this parameter.
The phone number to pass to the server machine when requesting that the server call your machine back. Click here for a complete description of this parameter.
Consider the following when using RSFLINK with your programs: