This chapter contains detailed descriptions of the commands and functions that pertain to RSF clients or requesters.
An iSeries machine that contacts other AS/400s, requesting to retrieve objects, send objects, initiate pass-through or call remote programs is an RSF requester. The machine receiving, processing, and fulfilling the requests is an RSF server. The requester is always the initiator of the transaction.
Since a single machine may be receiving and processing requests from remote sites, while at the same time sending its own requests to other sites, it follows that a given machine may be simultaneously acting as a requester and a server.
The Work With RSF Servers (WRKRSFSRV) command is used to work with a list of RSF servers, or to print a list of RSF servers. You make servers known to your machine by adding server directory entries.
The server directory on your machine functions like an on-line phone book. You can store phone numbers and other connection information in the server directory so you don't have to key it in with every request.
See Adding Server Directory Entries for more information about the details of server directory entries.
While working with servers, you can easily add, remove, change, copy, and rename server directory entries. You can also work with catalogs of RSF packages that are available from each server.
In addition, the Work With Servers display provides a convenient point from which you can initiate requests to remote machines to start pass-through, or transmit objects and files.
The prompted version of the WRKRSFSRV command is shown below.
The parameters for the WRKRSFSRV command are described below.
Indicate which entries to include in the list.
The possible values are:
*ALL: No entries are excluded based on name.
generic-name: Enter a generic name for the servers to be included in the list. Case is significant. An asterisk (*) in the generic specification will match any string of zero or more characters in the name. An underscore (_) in the generic specification will match any single character in the name.
Enter characters to compare to entry text to determine which entries should be included in the list. An entry is included in the list if the entry text contains the string specified. Case is not significant.
The possible values are:
*ALL: No entries are excluded based on text.
String: Enter any text string of up to 50 characters.
Indicates whether the list should be displayed or printed.
The possible values are:
*: Display the list.
*PRINT: Print the list.
Controls the amount of detail shown when printing the list.
The possible values are:
*BASIC: A subset of the total information is shown for each directory entry. Multiple entries are printed per page.
*FULL: All information is shown for each directory entry. One entry is printed per page.
The display that is presented when you specify OUTPUT(*) on the WRKRSFSRV command is shown below.
The following function keys may be used with this display:
F3: Exit without updating.
F5: Refresh the display.
F6: Add a new server directory entry.
F12: Cancel.
F13: Change user defaults.
F21: Present a system command line window.
The fields on the Work With RSF Servers display are explained below.
Enter a value in the "Position to" field and press Enter to position the list to a specific entry. The cursor is positioned to the first entry in the list that is greater than or equal to the "Position to" value you specify.
Enter an option number in the "Opt" column beside a list entry, and press Enter to perform a function on the list entry. You may enter options beside several list entries before pressing Enter. The options for the list entries are processed in turn when you press Enter. The following is a list of options and their functions.
2=Change: The CHGRSFSDE command prompt is displayed with the current values for the entry filled in.
3=Copy: A display is presented with which you specify the new names for entries to be copied.
4=Delete: A display is presented allowing you to confirm your choices for delete. When you press Enter a second time, the entries are deleted.
5=Display: Detailed information about the entry is displayed.
7=Rename: A display is presented with which you specify new names for the entries to be renamed.
12=Work with RSF catalog: The WRKRSFCAT display is presented for the selected server. The WRKRSFCAT display allows you to view a list of RSF packages available from the server and easily retrieve any package.
15=Start pass-through: A pass-through session is started with the server machine. The server must grant your machine permission to pass-through, by adding an entry to the requester directory on their machine. See Adding Requester Directory Entries for more information about adding and changing requester directory entries.
user-defined-option: You may key a user-defined option. To define new options, select option 9 from the Start PDM (STRPDM) menu.
See the on-line help text for this display for more information about user-defined options.
The unique server ID is shown in this column.
Text describing the server is shown. Type over the text and press Enter to change the text.
When you press F13, the Change User Defaults panel is presented. (Click here for more information.)
The following command is discussed elsewhere in this manual:
Add Server Directory Entry (ADDRSFSDE)
For more information about the following commands, prompt the command and press F1 to view the on-line help text:
Change Server Directory Entry (CHGRSFSDE)
Remove Server Directory Entry (RMVRSFSDE)
Rename Server Directory Entry (RNMRSFSDE)
The Add Server Directory Entry (ADDRSFSDE) command is used to add entries to the server directory on your machine.
The server directory functions like an on-line phone book. You can store phone numbers and other connection information in the server directory so that you won't have to key the information for every request.
The prompted version of the ADDRSFSDE command is shown below. Click on the image to jump to a particular command parameter description.
The parameters for the ADDRSFSDE command are described below in the order that they appear on the command prompt.
The name of the server directory entry to be added. This is a required parameter.
The possible values are:
name: Enter a valid system name for the new directory entry.
Specify the type of connection to use to communicate with the server machine.
The possible values are:
*SDLCDIAL: Use APPC over an SDLC dial-up connection. This is the easiest method to use for an SDLC dial-up network. RSF automatically creates the line, controller and device description at the beginning of the request and deletes them at the end of the request. Configuration objects are created according to the values specified in the RSF defaults for "Requester Configuration". See Setting Product Defaults for more information .
Note: The RSF server function (SDLC option) must be started on the server machine for this type of connection. (Click here for more information.)
*SDLC: Use APPC over a pre-configured connection. This option lets you use RSF over SDLC leased lines, Token Ring, Ethernet, X.25 and other connections that you have configured yourself.
*TCPDIAL: Use PPP and Sockets over a dial-up TCP/IP connection. This is the easiest method to use for a TCP/IP dial-up connection. RSF automatically creates the PPP profile as well as the line, controller and device descriptions at the beginning of the request and deletes them at the end of the request. Configuration objects are created according to the values specified in the RSF defaults for "PPP Requester Info". See Setting Product Defaults for more information .
Note: RSF release 7.0 or later must be installed on the server machine and the RSF server function (PPP and TCP/IP options) must be started on the server machine for this type of connection. (Click here for more information.)
*TCPIP: Use Sockets over a TCP/IP connection. This option allows you to connect to another AS/400 over any TCP/IP link, including the Internet.
Note: RSF release 6.0 or later must be installed on the server machine and the RSF server function (TCP/IP option) must be started on the server machine for this type of connection. (Click here for more information.)
The number to dial to reach the server's AS/400. This is a required parameter if either *SDLCDIAL or *TCPDIAL are specified for "Connection method".
The possible values are:
*NONE: No phone number is specified.
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 a leading 9 for accessing an outside line where necessary.
A free-form description of the server directory entry.
The possible values are:
Characters: Enter up to 50 characters of information describing the server directory entry.
The phone number to pass to remote machines when requesting that they call your machine back. This call-back phone number will be used any time a request is initiated from your machine that references this server ID, and specifies CALBCKNBR(*SERVER) for the "Call-back phone number" parameter.
If the call-back request is accepted by the remote machine, the initial connection is dropped and your job waits for the remote 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.
This parameter is ignored unless *SDLCDIAL or *TCPDIAL is specified for "Connection method".
The possible values are:
*NONE: Call-back 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 viewing or changing the RSF defaults.
*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.
This parameter is used to associate the RSF server with a pre-configured line on your machine. When you specify a value other than *NONE for this parameter, the value specified for the "Server's RSF phone number" is ignored by RSF commands that initiate a request; an attempt is made to communicate with the server machine over a specific line that is already configured on your machine.
The communications line used must be compatible with APPC. The valid link types are SDLC, X.25, Token Ring, and Ethernet. See the Communications Users Guide for information about configuring communications lines on your machine. See "Using the Location Parameters" in the Advanced Program to Program Communications Programmer's Guide for more information about how the five elements of this parameter are used to select a communications device.
This is a required parameter if *SDLC is specified for "Connection method".
See Appendix C for step-by-step instructions for using your existing pre-configured lines with RSF.
*NONE: No pre-configured line is associated with this server.
location name: The name of a remote location associated with the server. The remote location name you specify is checked against the remote location name specified for device descriptions on your machine as the first step in selecting a communications device to use.
*LOC: Device names are ignored. The remote location name is used to select the device to use. This is the recommended value.
device name: The name of the device you want to use to communicate with the server machine. The device you name is selected if it is compatible with the remote location name, local location name and remote network id specified. Otherwise, the request will end in error.
*LOC: For non-APPN devices, any local location name will match. For APPN devices, *NETATR is used. This is the recommended value for this parameter.
*NETATR: The value specified for local location name in the network attributes of your machine is used.
location name: The name to use for your location. The local location name you specify is checked against the local location name specified for device descriptions on your machine as a step in selecting a communications device to use.
The name of a mode description to use for the communications session. The mode specified must be valid for the communications device selected on your machine and on the server machine.
The possible values are:
BLANK: The system supplied mode of BLANK is used. This is the recommended value.
*NETATR: The default mode specified in the network attributes of your machine is used.
Name: The name of a mode to use for the communications session.
*LOC: For non-APPN devices, any remote network id will match. For APPN devices, *NETATR is used. This is the recommended value for this parameter.
*NETATR: The value specified for local network id in the network attributes of your machine is used.
*NONE: For non-APPN devices, any remote network id will match. For APPN devices, *NETATR is used.
remote network id: The name of the remote network containing the server machine. The remote network id you specify is checked against the remote network id specified for device descriptions on your machine as a step in selecting a communications device to use.
Specify the name of an existing controller that RSF should vary on and off with each transaction.
This parameter is ignored unless *SDLC is specified for "Connection method".
The possible values are:
*NONE: No controller is varied on and off by RSF. If you are using a pre-configured connection, the line controller and device must be in a varied on state.
controller-name: The name of a controller to be varied on and off by RSF. The controller specified must exist and should be the controller to which the device specified in the CNNDEV parameter is attached. RSF will vary the controller off before the transaction, vary the controller on to begin the transaction, and vary the controller off at the completion of the transaction. RSF keeps track of active RSF connections using the controller and only varies the controller when it is not already in use by RSF.
Specify the name of an existing line that RSF should vary on and off with each transaction.
This parameter is ignored unless *SDLC is specified for "Connection method".
The possible values are:
*NONE: No line is varied on and off by RSF. If you are using a pre-configured connection, the line controller and device must be in a varied on state. If you specified *NONE for "Vary existing controller", you must also specify *NONE for this parameter.
line-name: The name of a line to be varied on and off by RSF. The line specified must exist and should be the line to which the device specified in the CNNDEV parameter is attached. RSF will vary the line off before the transaction, vary the line on to begin the transaction, and vary the line off at the completion of the transaction. RSF keeps track of active RSF connections using the line and only varies the line when it is not already in use by RSF.
Specify a requester line group to use when contacting this server.
See Requester Configuration for more information about assigning requester lines to groups.
This parameter is ignored unless *SDLCDIAL or *TCPDIAL is specified for "Connection method".
The possible values are:
*ANY: Any requester line can be used to contact this server.
*BLANK: Only requester lines that are not assigned to a specific group can be used to contact this server.
group-name: The name of the requester line group to use. Only lines in the specified group are used to contact this server.
Specify the network name or IP address of the remote system to connect to. If a name is specified, it must map to a valid IP address (Internet address) using the TCP/IP host table on this machine, or using a name server.
This parameter is required if *TCPIP or *TCPDIAL is specified for "Connection method".
The possible values are:
*INTNETADR: This value is provided for compatibility with earlier releases. An address is specified, using the Internet Address (INTNETADR) parameter instead of specifying a system name or IP address here. When *INTNETADR is specified for this parameter, you must specify a value for the INTNETADR parameter.
Name: Enter the fully qualified name of the remote system.
IP-address: Specify the Internet address of the remote machine in the form nnn.nnn.nnn.nnn, where nnn is a number from 0 to 255.
Enter the address of the remote machine.
This parameter is ignored unless *INTNETADR is specified for the "Remote system" parameter.
The possible values are:
Address: Specify the Internet address of the remote machine. The address should be specified in the form nnn.nnn.nnn.nnn, where nnn is a decimal number from 0 to 255.
Specify the TCP/IP port to connect to on the remote machine for RSF functions. The value specified for this parameter must match the value specified for the PORT parameter on the Start Server Function (STRRSFSRV) command on the server machine. (Click here for more information.)
This parameter is ignored unless *TCPIP or *TCPDIAL is specified for "Connection method".
The possible values are:
602: A default port of 602 is used.
Port-number: Specify a valid port number from 1 to 65534.
Specify the TCP/IP port to use when connecting with telnet to the remote machine. The Start Pass-Through Using RSF (STRPASRSF) command uses telnet under the covers for TCP/IP connections.
This parameter is ignored unless *TCPIP or *TCPDIAL is specified for "Connection method".
The possible values are:
23: A default port of 23 is used.
Port-number: Specify a valid port number from 1 to 65534.
Specify the TCP/IP port to use for broadcasting to the remote machines. Only machines listening on this port will receive the broadcast. (The value specified for this parameter must match the value specified for the BPORT parameter on the Start Server Function (STRRSFSRV) command on the server machine.)
This parameter is ignored unless *BROADCAST is specified for "Connection Method".
The possible values are:
603: A default port of 603 is used.
Port-number: Specify a valid port number from 1 to 65534.
Specify the broadcast group IP address. Only machines monitoring the specified IP address on the specified port will receive the broadcast. (The value specified for this parameter must match the value specified for the GRPADR parameter on the Start Server Function (STRRSFSRV) command on the server machine.)
This parameter is ignored unless *BROADCAST is specified for "Connection Method".
A valid multicast group address must be in the range of 224.0.0.0 to 232.255.255.255. Addresses from 224.0.0.0 to 224.0.0.255 are intended for intra-network transmissions. Therefore, transmissions to these addresses are typically not forwarded by multicast-capable routers. See RFC1700 for a list a list of reserved multicast group addresses.
The possible values are:
group-address: Specify the broadcast group IP address in the form nnn.nnn.nnn.nnn, where nnn is a number from 0 to 255.
Specify the IP address of the interface on this machine that will be used to send broadcast transmissions. You can use option 1 on the NETSTAT display to list the available interfaces.
This parameter is ignored unless *BROADCAST is specified for "Connection Method".
The possible values are:
interface-address: Specify the broadcast interface IP address in the form nnn.nnn.nnn.nnn, where nnn is a number from 0 to 255.
Specify the number of bytes to broadcast before pausing to let the receiving machines catch up.
Depending on your network, broadcast messages may arrive at one or more target machines more quickly than they can be processed. If the receive buffer gets full on the target machine, additional messages my be discarded by the system, invalidating the transmission for that system.
Setting the appropriate block size and inter-block delay can help ensure that the complete transmission gets through to the maximum number of target systems, while not excessively impacting performance.
A smaller block size and/or longer inter-block delay increases transmission integrity. A larger block size and/or smaller inter-block delay improves performance.
This parameter is ignored unless *BROADCAST is specified for "Connection Method".
The possible values are:
63500: A default block size of 63500 bytes is used.
number: Enter a integer, greater than zero.
Specify the number of hundredths of a second to pause after sending each block of broadcast data. This parameter works in conjunction with the Broadcast Block Size (BBLOCK) parameter to ensure that the complete transmission gets through to the maximum number of target systems, while not excessively impacting performance.
A smaller block size and/or longer inter-block delay increases transmission integrity. A larger block size and/or smaller inter-block delay improves performance.
This parameter is ignored unless *BROADCAST is specified for "Connection Method".
The possible values are:
50: A default of 50 (half a second) is used.
number: Enter a number from zero to 100.
Specify the maximum number of gateways that a broadcast message may pass through before the message is discarded. This helps prevent looping.
This number should be at least as large as the number of gateways between the sending and receiving machines.
This parameter is ignored unless *BROADCAST is specified for "Connection Method".
The possible values are:
10: A default of 10 is used.
number: Enter a number from 1 to 255.
Specify the type of encryption to use for TCP/IP connections. When a value other than *NONE is specified, all information passed between the client and server is encrypted, including control information, user profiles, passwords and data.
This parameter is ignored unless *TCPIP or *TCPDIAL is specified for "Connection method".
The possible values are:
*BASIC: Basic symmetric encryption is used. When this option is used, the encryption key specified using the "Encryption Key Data Area" parameter must match the encryption key that was specified on the server machine using the Change RSF Defaults (CHGRSFDFT) command. See Setting Product Defaults for more information about changing defaults.
This option provides enough security for private networks and for those Internet transmissions where maximum secrecy and confidentiality are not required.
*NONE: The transmission is not encrypted. This option provides slightly better transmission performance.
*SSL: The Secure Sockets Layer protocol is used to encrypt the transmission. This option provides maximum security, allowing for the safe transmission of the most confidential information.
Note:: In order to use this option:
1. The Internet Connection Secure Server licensed program must be installed on
your machine and the server machine. (US version: 5769NC1. International
version: 5769NCE.) Contact your IBM sales representative for more information.
2. RSF's SSL support must be enabled on your machine and the server machine.
This is done with the Change Defaults (CHGRSFDFT) command. See
Setting Product Defaults for more information. See Appendix G for
information about configuring SSL,
Enter the qualified name of a data area containing the encryption key to use. The data area must be at least 128 bytes long.
This parameter is ignored unless *TCPIP or *TCPDIAL is specified for the "Connection Method" parameter, and *BASIC is specified for the "Encryption" parameter.
The first 128 bytes of the data area are used as the encryption key. Trailing blanks in the key are ignored. The key can be from 1 to 128 bytes long and may contain any valid hex or character data. Longer keys provided greater security.
The data area does not need to exist at the time this command is run but it must exist when a transmission is started.
The possible values are:
*NONE: No data area is used. A default key is supplied by RSF.
data-area name: The name of a data area to use
The possible library values are:
*LIBL: The job library list is used to locate the data area.
library-name: The name of the library containing the data area.
Indicate whether to compress data as it is transmitted to this location.
The goal of compression is to get data from point A to point B more quickly. Since compression uses more CPU resources, run-time compression is most effective over slower connections, where the transmission speed is significantly slower than the processor speed.
When compression is selected, an informational message is sent to the job log at the completion of the transmission indicating the amount of compression achieved.
Note: This parameter only effects TCP/IP connections. Use the Change Mode Description (CHGMODD) command for mode BLANK to set run-time compression options for SDLC connections.
The possible values are:
*NONE: The data is not compressed.
*BASIC: A simple TERSE algorithm is used to compress data as it is transmitted. This requires more CPU than *NONE, but less CPU than the *MAX option.
*MAX: The LZ1 algorithm is used to compress data as it is transmitted. This requires more CPU than the *NONE or *BASIC options, but the best compression ratio is achieved.
For dial-up TCP/IP connections (PPP), indicate the protocol to use when sending user ID and password information to the remote machine.
This parameter is ignored if a value other than *TCPDIAL is specified for "Connection Method", or if *DFT is specified for the "Remote Signon" parameter.
The possible values are:
*CHAP: The user ID and password are encrypted before they are sent. You should specify this value whenever the remote machine is an iSeries or AS/400 running RSF, or whenever the server supports the CHAP protocol.
*PAP: The user ID and password are sent as plain text. Many Internet service providers only support this option. Check with your ISP to determine which password protocols are supported.
For dial-up TCP/IP connections (PPP), indicate if RSF should define a default route or specific static routes to the remote location for the duration of the connection.
Routes are useful if you want to use the remote machine as a gateway to connect to other machines. See option 2 on the CFGTCP menu for more information about TCP/IP routes.
This parameter is ignored if a value other than *TCPDIAL is specified for Connection Method.
The possible network address values are:
*NONE: No static routes to the remote system are defined.
*DFT: A default route to the remote system is defined for the duration of the connection. When the iSeries is asked to connect to any unknown IP address, it will try to find a route to that address beginning with the connection designated as the default route.
Note: The iSeries allows only one default route to be active at a time. When you specify *DFT for this parameter, a connection to the remote system will fail if:
Another default route is defined in your TCP/IP configuration.
A connection to a different RSF server is already active which has *DFT specified for Static Routes.
*IP-address: Enter the address of the remote network to which you wish to establish a route. The address should be formatted as a valid IP network address. Network addresses end in 0 for a subnet mask of 255.255.255.0. Network addresses end in 0 or 128 for a subnet mask of 255.255.255.128.
The possible Subnet Mask values are:
255.255.255.0: This common subnet mask is the default.
mask: Enter a valid subnet mask.
Specify the qualified name of a data area to use to send default messages to this server. The data area must be at least 128 bytes long
If a data area is specified for this parameter, and if the user specifies *SERVER for the "Message for server" (MSG) parameter on one of the RSF commands that initiates a request, the first 128 bytes of the data area are sent to the server as message data.
Message data sent via the MSG parameter is accessible by pre- and post-processing programs on the server machine. Associating a message data area with a server directory entry allows the server location to receive customized information with every request.
For example: A data area could be created on the requester machine to track different software features and releases installed. Then, by tying the data area to the server location using this parameter, the server receives the feature and release information with every request.
The possible values are:
*NONE: No data area is associated with this server. If *SERVER is specified for the "Message for server" parameter on an RSF command that initiates a request and the command references this server, no message is sent.
data-area name: The name of a data area to use. The data area must be at least 128 bytes long.
The possible library values are:
*LIBL: The job library list is used to locate the data area.
library-name: The name of the library containing the data area.
Indicate whether this machine should relay transmissions to this server when the server is in the list of machines to receive the distribution.
For a relay distribution, machines that successfully receive a transmission participate in sending the transmission on to other locations in a list that is specified by the original sender.
Note: More than one machine can be set to forward distributions to a given server. This ensures that there are multiple paths to that server. If one machine is unable to contact the server, another may be able to get through. RSF ensures that only one copy of the distribution is ultimately sent to the server.
This parameter is ignored for non-relay distributions.
The possible values are:
*YES: During a relay distribution, this machine will attempt to send the transmission this server.
*NO: This server will not be contacted by this machine for a relay distribution. Some other machine must relay to this server.
Fallback support allows you to specify alternate connection information for a given server. If a connection cannot be made using the connection information specified in this server ID, RSF will attempt to connect using the connection information specified in the fallback server ID, if one is specified.
The fallback server may have its own fallback server ID specified. In this way, you can chain together as many server IDs as you like. Care should be taken to ensure that the chain of fallback servers is not recursive--no entry should point an earlier entry in the chain.
The different server IDs that make up the fallback chain may have completely different connection methods defined. Or, one entry may be simply a variation of an earlier entry in the chain, with a different connection phone number or IP address, for example.
The possible values are:
*NONE: No fallback server ID is defined for this server.
server-ID: Enter the name of an existing server ID to use as a fallback. If a connection cannot be made to this server directly, an attempt will be made to connect using the fallback server ID.
Specify the preferred time for contacting this location. This information may be used by other RSF functions to schedule transmissions.
The possible single values are:
*ANY: The location can be contacted any time. This is the same as entering 00:00:00 to 23:59:59 for the time range.
The other possible values are:
time-range: Enter start and end times for the optimal transmit window, using a 24-hour clock. If a start time is not specified, 00:00:00 is assumed. If an end time is not specified, 23:59:59 is assumed. If the end time is less than the start time, the window spans midnight.
Specify the user profile and password to use when connecting to the remote machine.
For SDLC connections (Connection Method *SDLCDIAL or *SDLC), this parameter determines the user ID and password to use to sign on to the remote machine. The RSF job on the target machine runs under the specified user ID.
For TCP/IP dial-up connections (Connection Method *TCPDIAL), this parameter determines the user ID and password to pass to the target PPP profile. The actual user profile under which the target job runs, however, is determined by job description RSF/RSFTCP.
The possible single values are:
*DFT: For SDLC connections, RSFSRV is used for the profile and password.
This is the recommended value for SDLC connections as it will allow you to connect to most machines with RSF. However, if the password
for the RSFSRV profile on the target machine was changed from the default value, the connection will fail with message RSF4041 or
RSF4011. See
Security Considerations for more information about using the default profile and password.
For PPP connections (Connection Method *TCPDIAL), a value of *DFT for this parameter passes no user ID or password to the remote
machine at connection time.
The other possible values are:
profile-and-password: Specify a user profile and password to use to initiate the RSF
server job on the target machine.
For SDLC connections, both values must be ten or fewer characters, without embedded
blanks. Case is not significant. The profile/password combination must be valid for the remote machine,
otherwise the connection will fail with message RSF4041 or RSF4011.
For PPP/TCPIP connections, the user ID and password may each be up to thirty characters long and may include
imbedded blanks. Case is significant. The user ID/password combination must match an entry
in the validation list specified in the server configuration on the target machine.
The following command is discussed elsewhere in this manual:
Work With Servers (WRKRSFSRV)
For more information about the following commands, prompt the command and press F1 to view the on-line help text:
Change Server Directory Entry (CHGRSFSDE)
Remove Server Directory Entry (RMVRSFSDE)
Rename Server Directory Entry (RNMRSFSDE)
The Work With RSF Catalog (WRKRSFCAT) command is used to work with a list of RSF packages available from a given server, or to print a list of packages available from a given server.
While working with an RSF catalog, you can easily display and delete catalog entries, retrieve packages, and retrieve catalog updates.
The prompted version of the WRKRSFCAT command is shown below.
The parameters for the WRKRSFCAT command are described below.
The name of the server whose catalog is to be worked with. This is a required parameter.
The possible values are:
Name: Enter the name of an existing server directory entry.
Indicates whether the list should be displayed or printed.
The possible values are:
*: Display the list.
*PRINT: Print the list.
Controls the amount of detail shown when printing the list.
The possible values are:
*BASIC: A subset of the total information is shown for each catalog entry. Multiple entries are printed per page.
*FULL: All information is shown for each catalog entry. One entry is printed per page.
The display that is presented when you specify OUTPUT(*) on the WRKRSFCAT command is shown below.
The following function keys may be used with this display:
F3: Exit without updating.
F4: Prompt.
F5: Refresh the display.
F12: Cancel.
F13: Change defaults that effect this display.
F15: Retrieve the latest catalog.
F21: Present a system command line window.
The fields on the Work With RSF Catalog display are explained below.
The name and text for the server whose catalog is being worked with are shown.
Enter a value in the "Position to" field and press Enter to position the list to a specific entry. The cursor is positioned to the first entry in the list that is greater than or equal to the "Position to" value you specify.
Enter an option number in the "Opt" column beside a list entry, and press Enter to perform a function on the list entry. You may enter options beside several list entries before pressing Enter. The options for the list entries are processed in turn when you press Enter. The following is a list of options and their functions.
4=Delete: A display is presented allowing you to confirm your choices for delete. When you press Enter a second time, the entries are deleted.
5=Display: Detailed information about the entry is displayed.
8=Retrieve package: Retrieve the package from the server. Press Enter to retrieve the package. Press F4 to be prompted for parameters before retrieving the package. The package is retrieved interactively or in batch, depending on the values specified for defaults. Press F13 to view or change the defaults.
10=Install: The selected package is installed on your system. The package status must be RTV or OPN.
The names of the packages available from the server are shown in this column.
The package status is shown. The possible values are:
blank: The package has not been retrieved or installed.
RTV: The package has been retrieved but not installed.
INL: The package has been installed.
OPN: The package has been retrieved again after it was installed.
Text describing each package is shown in this column.
Press F15 to retrieve the latest catalog from the server. The catalog is retrieved interactively or in batch, depending on the values specified for defaults. Press F13 to view or change the defaults.
The display that is presented when you press F13 to change defaults from the WRKRSFCAT display is shown below. You can also access this display by running the Change User Options (CHGRSFUO) command from any command line. Click on the image to see parameter descriptions.
The following function keys may be used with this display:
F3: Exit without updating.
F12: Cancel.
The fields on the Change Defaults display are explained below.
The qualified name of a save file on your machine where retrieved packages should be placed. If the save file specified does not exist when the package is retrieved, it will be created.
The possible values are:
*PKG: Use the name of the package being retrieved for the save file name.
name: Enter the name of the save file to contain retrieved packages.
The possible library values are:
QGPL: Library QGPL is used.
*CURLIB: Your current library is used.
library name: Enter the name of a library to contain the save file.
Specify the action to take when the specified save file already exists.
The possible values are:
*YES: Replace an existing save file.
*NO: End in error if the specified save file already exists.
Specify whether to automatically install retrieved packages.
The possible values are:
*YES: RSF runs program RSFINST if it is included within a retrieved package.
*NO: Package save files are not automatically installed.
Specify whether to retrieve packages that are already flagged as installed on your system.
The possible values are:
*NO: A request to retrieve an installed package ends in error.
*YES: Installed packages may be retrieved again.
Specify whether to submit requests to batch.
The possible values are:
*NO: Run requests interactively.
*YES: Submit requests to batch.
Enter the qualified name of a job description to use when submitting requests to batch.
The possible values are:
name: Enter the name of the job description to use.
The possible library values are:
*LIBL: The job description is found using the library list.
*CURLIB: The job description in the current library is used.
library-name: Enter the name of the library containing the job description.
Enter the earliest date to include in the catalog list. Only catalog entries that were created or changed on or after the date specified are included.
The possible values are:
*FIRST: No minimum date is used to filter catalog entries.
*NEW: Only new entries that were added to the catalog since the last time the catalog was retrieved are included.
date: Enter the earliest date to include in the list.
Enter the latest date to include in the catalog list. Only catalog entries that were created or changed on or before the date specified are included.
The possible values are:
*LAST: No maximum date is used to filter catalog entries.
date: Enter the latest date to include in the list.
Use this parameter to select entries to include by status.
The possible single values are:
*ALL: All entries are included regardless of status.
*NOTBLANK: Entries with any status other than blank are included.
*NOTINL: Entries for packages that have not been installed are included.
The other possible values are:
*BLANK: Entries for packages that have not been retrieved or installed are included.
*RTV: Entries for packages that have been retrieved but not installed are included.
*INL: Entries for packages that have been installed are included.
*OPN: Entries for packages that have been retrieved again after they were last installed are included.
Enter characters to compare to catalog entry text to determine which entries should be included in the list. An entry is included in the list if the entry text contains the string specified.
The possible values are:
*ALL: Include all entries regardless of their text.
string: Enter a text compare string to use.
Enter the qualified name of a user option file to use when checking user-defined options.
The possible values are:
file-name: Enter the name of an existing option file.
The possible library values are:
*CURLIB: The file is found in the job's current library.:
*LIBL: The file is found using the library list.:
library-name: Enter the name of the library containing the option file.:
Enter the name of the option file member to use.
The possible values are:
*FIRST: The first member in the file is used.
member-name: Enter a valid member name.
Specify a default server ID to use to replace the &SERVER variable in user-defined options. This value is only used with the Work With Packages display.
The possible values are:
*NONE: No default is specified.
server-ID: Enter a valid server ID.
Specify a default package to use to replace the &PKG variable in user-defined options. This value is only used with the Work With Servers and Work With Catalog displays.
The possible values are:
*NONE: No default is specified.
package-name: Enter a valid package name.
The following commands are discussed elsewhere in this manual:
Retrieve Package (RTVRSFPKG)
Send Package (SNDRSFPKG)
Create Package (CRTRSFPKG)
For more information about the following commands, prompt the command and press F1 to view the on-line help text:
Change Package (CHGRSFPKG)
Delete Package (DLTRSFPKG)
Rename Package (RNMRSFPKG)
The Retrieve RSF Package (RTVRSFPKG) command is used to retrieve a package of objects from another machine.
With this command, you can only retrieve objects that have been included in an RSF package on the remote machine. Use the commands in RSFTOOLS (Appendix B) to retrieve objects that have not been defined by an RSF package. Use the Copy File Using RSF (CPYFRSF) command to send and retrieve database file members that are not part of a package. You can also use the Retrieve IFS Objects (SNDIFSRSF) to retrieve objects that are not part of a package.
If a set of objects will be retrieved from a given machine multiple times, it is most efficient to define a package for the objects and retrieve them using this command. Click here for more information about creating packages of objects.
The prompted version of the RTVRSFPKG command is shown below. Click on the image to see parameter descriptions.
The parameters for the RTVRSFPKG command are described below.
The name of the package you want to retrieve from the server machine. The package must exist on the server machine. This is a required parameter.
The possible values are:
name: The name of a specific package to access from the server.
*CATALOG: A special request is sent to the server to download a catalog of RSF packages available on their machine. When *CATALOG is specified for "Package", you cannot specify *NONE for "Server id".
*NONE: No package is retrieved. An ad hoc message is sent to the server. When *NONE is specified for "package", you cannot specify *NONE for "Message for server".
The qualified name of a save file on your machine to receive the RSF package. This is a required parameter.
The possible values are:
name: The name of a save file to contain the received package. If the file does not exist, it will be created. A save file name must be provided unless *CATALOG is specified for "Package" or a value other than *ALL or *DATA is specified for "Type of data requested".
*NONE: No target save file is used. *NONE must be specified when *CATALOG is specified for "Package", or when a value other than *ALL or *DATA is specified for "Type of data requested".
The possible library values are:
*CURLIB: The current library is used to locate the save file.
library name: The name of an existing library which contains or will contain the save file.
Specify whether RSF should replace the contents of the save file if it already exists.
The possible values are:
*NO: If the save file already exists, the request ends in error.
*YES: The contents of the save file are replaced with the data being downloaded. When *RETRY is specified for "Type of data requested", the new data is appended to the existing save file.
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.
The possible values are:
*CURRENT: Reference 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.
name: The name of an entry in the server directory on your machine.
The type of data you wish to download
The possible values are:
*ALL: All data associated with the RSF package is downloaded to your machine.
*CVRLTR: Only the cover letter is retrieved.
*DATA: Only the save file data is retrieved.
*MSG: No data is retrieved. A message is sent to the server machine. When you specify *MSG for "Type of data requested", you cannot specify *NONE for "Message for server".
*RETRY: Specify *RETRY to resume the download for a package that was previously interrupted. When you specify *RETRY, Remote Software Facility determines where the previous download attempt left off, and resumes the transmission at that point. Cover letter data is not retrieved. Only the save file data for the package is retrieved. You must specify the same save file for "Target save file" that was used in the previously interrupted transaction.
Specify whether RSF should hang up the phone connection at the completion of the transaction. This parameter is ignored for non-switched connections.
The possible values are:
*YES: The line is disconnected at the completion of the transaction.
*NO: 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.
When HANGUP(*NO) is specified by both the requester and server machines, the line remains active until one of the following occurs:
Another request from your machine to the same server
specifies HANGUP(*YES)
The requester explicitly hangs up using the ENDRSFCNN
(End RSF Switched Connection) command. See Hang up: End
RSF Switched Connection for more information.
The time limit expires on the server machine and the server hangs up. The time limit is set with the SRVDSC parameter on the Change RSF Defaults (CHGRSFDFT) command. See Setting Product Defaults for more information about changing RSF defaults.
Specify whether RSF should attempt to install a package once it has been retrieved.
For automatic installation, RSF attempts to restore program RSFINST to library QTEMP from the save file that was transmitted with the package.
If program RSFINST can be restored, it is called with the following parameter list:
A data structure describing the request. CHAR(*). See Appendix A for a complete description of the data structure.
Return message data. CHAR(128)
Return message type. CHAR(7)
Saved library. CHAR(10)
Save command used. CHAR(10)
It is the server's responsibility to write installation program RSFINST and include it in the save file for the package if automatic installation for this package is to be supported. See Automatic Installation Programs for more information.
The possible values are:
*TRY: Automatic installation is attempted. The request ends normally if no automatic installation program is found. If you know automatic installation does not apply, it is more efficient to specify *NO for this parameter.
*YES: Automatic installation is attempted. The request ends in error if no automatic installation program is found.
*NO: No attempt is made to automatically install the package.
The phone number to pass to the server machine when requesting that the server call your machine back.
Your call-back 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.
If the call-back 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 for about two minutes for the server machine to call back before signaling an error.
The possible values are:
*NONE: Call-back is not requested.
*RSFDFT: Call-back 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 viewing or changing the RSF defaults.
*SERVER: Call-back is requested. The call-back phone number specified in the server directory entry named in the "Server id" parameter is used. If no call-back phone number is specified in the server directory entry, a value of *NONE is assumed for this parameter.
*MANUAL: Call-back is requested, but the return call is placed manually by an operator at the remote site. Manual call-back 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 call-back with the Call Back Using RSF (CALBCKRSF) command.
phone number: Call-back is requested. Enter
up to 32 characters for the call-back 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 a 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.
Indicate whether to compress data as it is transmitted.
The goal of compression is to get data from point A to point B more quickly. Since compression uses more CPU resources, run-time compression is most effective over slower connections, where the transmission speed is significantly slower than the processor speed.
When compression is selected, an informational message is sent to the job log at the completion of the transmission indicating the amount of compression achieved.
Note: This parameter only effects TCP/IP connections. Use the Change Mode Description (CHGMODD) command for mode BLANK to set run-time compression options for SDLC connections.
The possible values are:
*SERVER: The compression option specified in the server directory entry named in the "Server id" (SERVER) parameter is used. See Adding Server Directory Entries for more information.
*NONE: The data is not compressed.
*BASIC: A simple TERSE algorithm is used to compress data as it is transmitted. This requires more CPU than *NONE, but less CPU than the *MAX option.
*MAX: The LZ1 algorithm is used to compress data as it is transmitted. This requires more CPU than the *NONE or *BASIC options, but the best compression ratio is achieved.
Specify whether to retrieve the package if it is flagged as installed on your system.
The possible values are:
*NO: The request to retrieve an installed package ends in error.
*YES: An installed package may be retrieved again.
An ad hoc message to be sent to the server along with the RSF request.
The possible values are:
*NONE: No message is sent to the server.
*SERVER: Get the message data from the data area specified in the server directory entry named in the "Server id" parameter. If no message data area is specified in the server directory entry, a value of *NONE is assumed for this parameter.
Message text: Enter up to 128 characters of message text.
When you prompt for command parameters with F4, default name, address and telephone information are filled in for you. These are the same defaults the system uses to send PTF orders via Electronic Customer Support.
The possible values are:
contact information: Enter the appropriate information for contact name, address, and phone.
The following commands are discussed elsewhere in this manual:
Send Package (SNDRSFPKG)
Work With Catalog (WRKRSFCAT)
Copy File Using RSF (CPYFRSF)
Retrieve Objects (RTVOBJRSF)
Send Objects (SNDOBJRSF)
Retrieve Documents (RTVDOCRSF)
Send Documents (SNDDOCRSF)
Create Package (CRTRSFPKG)
For more information about the following commands, prompt the command and press F1 to view the on-line help text:
Change Package (CHGRSFPKG)
Delete Package (DLTRSFPKG)
Rename Package (RNMRSFPKG)
The Send RSF Package (SNDRSFPKG) command is used to send an RSF package to a remote server.
With this command, you can only send objects that have been included in an RSF package on your machine. Use the commands in RSFTOOLS (Appendix B) to send objects that have not been defined by an RSF package. Use the Copy File Using RSF (CPYFRSF) command to send and retrieve database file members that are not part of a package. You can also use the Send IFS Objects (SNDIFSRSF) to send objects that are not part of a package.
If a set of objects will be sent from a given machine multiple times, it is most efficient to define a package for the objects and send them using this command. Click here for more information about creating packages of objects.
The prompted version of the SNDRSFPKG command is shown below. Click on the image to see parameter descriptions.
The parameters for the SNDRSFPKG command are described below.
The name of the package you want to send. The package must exist on your machine. See Creating Packages for more information about creating RSF packages. This is a required parameter.
The possible values are:
name: The name of a specific package to send.
*NONE: No package is sent. An ad hoc message is sent to the server. When *NONE is specified for "Package", you cannot specify *NONE for "Message for server".
*SAVF: No predefined package definition is used. In stead, you use the "Save file" parameter to indicate the save file to send.
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.
The possible values are:
*CURRENT: Reference 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.
Notes:
*CURRENT is not valid for Server ID for RSF
commands run in a target Telnet session. *CURRENT is allowed within other RSF
server jobs that connect via TCP/IP.
For SNA/APPC connections, the user profile and password used to connect back to the *CURRENT machine are taken from the server entry that is associated with the job in which this command is run. If no server entry is associated with the job, the default RSF signon is used. Use the WRKRSFRQS command to view or change the server IDs that are associated with requests sent to this machine.
*LIST: All locations in a list of servers are contacted. When you specify *LIST for this parameter, you must also specify a value for the Location List (LIST) parameter.
RSF begins contacting the locations in the list a soon as this command is run. Use the Schedule RSF Transmission (SCDRSFTNS) command if you want to schedule the transmission for a later time.
name: Enter the name of an entry in the server directory on your machine.
The type of data you wish to send to the server machine.
The possible values are:
*ALL: All data associated with the package is sent to the server machine.
*CVRLTR: Only the cover letter is sent.
*DATA: Only the save file data is sent.
*MSG: No data is sent. A message is sent to the server machine. When you specify *MSG for "Type of data to send", you cannot specify *NONE for "Message for server".
*RETRY: Specify *RETRY to resume sending a package that was previously interrupted. When you specify *RETRY, Remote Software Facility determines where the previous transmission left off, and resumes the transmission at that point. Cover letter data is not sent. Only the save file data for the package is sent.
Specify the name of a program to call on the remote machine once the package has arrived.
The value you specify will be ignored by the server machine unless an entry referring to your machine exists in the requester directory of the server machine and specifies *YES or *PARTIAL for "Allow remote program calls". See Adding Requester Directory Entries for more information about requester directory entries.
The possible values are:
*DFT: The value specified for "Post-Processing program" in the requester directory of the server machine is used. The server machine controls which program, if any, is called.
*INSTALL: Automatic installation program RSFINST is called. For automatic installation, RSF attempts to restore program RSFINST to library QTEMP from the save file that was transmitted with the package.
If program RSFINST can be restored, it is called with the following parameter list:
A data structure describing the request. CHAR(*). See Appendix A for a complete description of the data structure.
Return message data. CHAR(128)
Return message type. CHAR(7)
Saved library. CHAR(10)
Save command used. CHAR(10)
It is the user's responsibility to write installation program RSFINST and include it in the save file for the package if automatic installation for this package is to be supported. See Automatic Installation Programs for more information.
*NONE: No program is called on the server machine once the data arrives.
Name: Enter the qualified name of a program to call on the server machine. See Post-Processing Programs for more information about how to write these programs.
The possible library values are:
*LIBL: The job library list is used to locate the program.
library name: The name of the library on the server machine containing the program to be called.
Specify whether to invoke the pre-processing program associated with the package. This parameter is ignored if no pre-processing program is associated with the package. See Pre-Processing Programs for more information.
The possible values are:
*YES: Invoke the pre-processing program associated with the package, if one exists, before sending the package to the server.
*NO: Ignore any pre-processing program associated with the package.
Specify whether access information for the RSF package should be updated upon successful completion of the request.
The possible values are:
*YES: Access information is updated.
*NO: Access information is not updated.
Specify whether the communications session with the server should be ended before any post-processing program is called.
The possible values are:
*NO: If the server has specified that a user-written program be called to process the received RSF data, and if the server has specified *NO for the DROP parameter on the requester directory entry, the session remains active while the post-processing program is called. Status messages reporting the progress of the post-processing program are returned to your machine.
*YES: The session with the server is ended after the package is received by the server. If the server has specified that a user-written program be called to process the received RSF data, the session is ended before the program is called. The post-processing program is executed asynchronously by the server.
Whether RSF should hang up the phone connection at the completion of the transaction. This parameter is ignored for non-switched connections. 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.
Indicate whether to compress data as it is transmitted. Click here for a complete description of this parameter.
An ad hoc message to be sent to the server along with the RSF request. Click here for a complete description of this parameter.
Enter the qualified name of the save file to send to the remote machine.
This is a required parameter if *SAVF is specified for "Package".
The possible save file values are:
save-file-name: Enter the name of an existing save file.
The possible library values are:
*LIBL: The job library list is used to locate the save file.
*CURLIB: The save file is found in the current library.
library-name: The name of the library containing the save file.
Enter the qualified name of the location list to reference. Location lists are stored as physical file members
Note: If you plan to use the relay distribution option (RELAY(*YES)) or you are sending to a broadcast server ID (Connection method of *BROADCAST), you should ensure that the location list is stored in a library that can be accessed by batch jobs initiated by remote machines as they report the distribution status.
This is a required parameter if *LIST is specified for the Server ID (SERVER) parameter.
The possible values are:
location-list-name: Enter the name of an existing location list.
The possible library values are:
*LIBL: The job library list is used to locate the list.
*CURLIB: The list is found in the current library.
library-name: The name of the library containing the list.
Enter the name of the member containing the location list.
The possible values are:
*FIRST: The location list stored in the first member of the file is used.
member-name: Enter the name of the member containing the location list.
Specify whether to reset the access count and status for all entries in the location list before beginning any transmissions.
This parameter is ignored unless *LIST is specified for the Server ID (SERVER) parameter.
The possible values are:
*YES: The location list is reset.
*NO: The location list is not reset.
Specify whether machines that receive the transmission successfully should forward the transmission on to other locations.
Using relay distribution can greatly reduce the total time required to send a transmission to many locations. Each receiving machine becomes an additional sending machine, while central control remains with the machine on which the send command was originally run.
Notes:
If *YES is specified for this parameter, this
machine will only send to machines that have *YES specified for "Relay to this
machine" (RELAY) in the server directory entry.
If *YES is specified for this parameter, you should ensure that any post-processing or installation procedure on the target machine does not delete the transmitted save file, thus ensuring that the save file is available to be relayed to other locations when the transmission completes. The request data structure passed to post processing programs contains a 1-byte field which indicates whether relay processing was requested or not. (Y = Yes.) See physical file RSDS002 for the layout of the data structure.
This parameter is ignored unless *LIST is specified for the Server ID (SERVER) parameter.
The possible values are:
*NO: Relay distribution is not used. All locations are contacted directly by this machine.
*YES: Relay distribution is used. Receiving machines participate in sending the transmission on to other machines.
When you prompt for command parameters with F4, default name, address and telephone information is filled in for you. These are the same defaults the system uses to send PTF orders via Electronic Customer Support.
The possible values are:
contact information: Enter the appropriate information for contact name, address, and phone.
The following commands are discussed elsewhere in this manual:
Retrieve Package (RTVRSFPKG)
Work With Catalog (WRKRSFCAT)
Copy File Using RSF (CPYFRSF)
Retrieve Objects (RTVOBJRSF)
Send Objects (SNDOBJRSF)
Retrieve Documents (RTVDOCRSF)
Send Documents (SNDDOCRSF)
Create Package (CRTRSFPKG)
For more information about the following commands, prompt the command and press F1 to view the on-line help text:
Change Package (CHGRSFPKG)
Delete Package (DLTRSFPKG)
Rename Package (RNMRSFPKG)
The Send Spooled File (SNDSPLFRSF) command is used to send one or more spooled files to a remote server. The Retrieve Spooled File (RTVSPLFRSF) command is used to retrieve one or more spooled files from a remote server. All spooled file attributes are preserved.
The prompted version of the SNDSPLFRSF command is shown below. Click on the image to see parameter descriptions.
The parameters for the SNDSPLFRSF command are described below.
The name of a server directory entry to be referenced. The entry must have been previously added to the server directory on your machine. This is a required parameter. Click here for a complete description of this parameter.
The name of the spooled file to send. This is a required parameter.
The possible values are:
*ALL: All spooled files are sent that meet the criteria specified by the other parameters for this command.
name: The name of a specific spooled file to send.
The qualified name of a job containing the spooled file to be sent.
The possible values are:
*: The spooled file is found in the current job.
*ALL: Spooled files for all jobs are sent. *ALL is not valid for this parameter unless *ALL is also specified for "Spooled file".
name: The name of the job containing the spooled file.
User
name: The user id associated with the job.
Number
000000-999999: The number for the job.
Enter the number of the spooled file to be sent. This parameter is ignored if *ALL is specified for "Spooled file name".
The possible values are:
*LAST: The last spooled file created with the specified name in the specified job is sent.
*ONLY: The only spooled file created with the specified name in the specified job is sent.
1-9999: Enter the number of the spooled file to send.
Enter the qualified name of the output queue to which the spooled files should be sent.
The possible values are:
*DFT: The spooled files are sent to the server's default output queue, specified in the requester directory entry that refers to your machine. See Adding Requester Directory Entries for more information.
output-queue: Enter the name of the output queue on the server machine to which the spooled files should be sent.
The possible library values are:
*LIBL: The job library list is used to locate the output queue.
library name: The name of the library containing the output queue.
Specify whether to delete the original spooled files after they have been sent.
The possible values are:
*NO: The original spooled files are not deleted.
*YES: The original spooled files are deleted after they have been sent.
Indicate whether to compress data as it is transmitted. Click here for a complete description of this parameter.
The name of the user for which spooled files are sent. This parameter is ignored unless *ALL is specified for "Spooled file".
The possible values are:
*CURRENT: Spooled files for the current user are sent.
*ALL: Spooled files for all users are sent.
name: The name of the user whose spooled files are to be sent.
The qualified name of the output queue containing the spooled files to be sent. This parameter is ignored unless *ALL is specified for "Spooled file".
The possible values are:
*ALL: Spooled files for all output queues are sent.
name: The name of the output queue containing the spooled files to be sent.
The possible library values are
*LIBL: The job library list is used to locate the output queue.
*CURLIB: The current library is used to locate the output queue.
library name: The name of the library containing the output queue.
The form type for spooled files to be sent. This parameter is ignored unless *ALL is specified for "Spooled file".
The possible values are:
*ALL: All spooled files are sent, regardless of their form type.
*STD: Only spooled files with form type *STD are sent.
characters: Only spooled files that match the specified form type are sent.
Select spooled files to be sent which match the specified user data. This parameter is ignored unless *ALL is specified for "Spooled file".
The possible values are:
*ALL: All spooled files are sent, regardless of their user data attribute.
characters: Only spooled files that match the specified user data are sent.
Whether RSF should hang up the phone connection at the completion of the transaction. This parameter is ignored for non-switched connections. 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.
An ad hoc message to be sent to the server along with the RSF request. Click here for a complete description of this parameter.
When you prompt for command parameters with F4, default name, address and telephone information is filled in for you. These are the same defaults the system uses to send PTF orders via Electronic Customer Support.
The possible values are:
contact information: Enter the appropriate information for contact name, address, and phone.
The following command is discussed elsewhere in this manual:
Monitor Output Queue (STRMONOUTQ)
For more information about the following command, prompt the command and press F1 to view the on-line help text:
Retrieve Spooled Files (RTVSPLFRSF)
The Send IFS Objects (SNDIFSRSF) command can be used to send objects in the Integrated Files System (IFS) to another machine. The objects can be sent to the same or to a different directory on the target machine.
User-written exit programs can be called both before and after the objects are sent to further customize the object distribution process.
The prompted version of the SNDIFSRSF command is shown below. Click on the image to see parameter descriptions.
The parameters for the SNDIFSRSF command are described below.
Enter up to 15 specifications defining the objects to be sent. There are three parts to each specification:
The path and name of the objects to send. This can be a path
to a specific object or directory, or a generic name which includes pattern matching characters.
Whether to include or omit the specified objects.
The path and name to use when restoring the objects on the target machine.
This is a required parameter.
The possible Object values are:
*: Objects in the current directory are sent.
~/: Objects in the home directory of the current user are sent.
~user-name/: Objects in the home directory of the specified user are sent.
relative-path-name: A relative path is one that does not begin with a slash. The path is assumed to start in the user's current directory.
full-path-name: A full path begins with a slash. The path specification starts at the root.
generic-name: You may include wild card characters in the last part of the path name to define a pattern that will select multiple objects. An asterisk (*) will match any number of characters. A question mark (?) will match any single character. You must enter two asterisks together to begin the path specification with an asterisk.
The possible Include/Omit values are:
*Include: The specified objects are included.
*OMIT: The specified objects are omitted. You can use an *OMIT specification after an *INCLUDE specification to omit a few objects from the previous specification.
The possible Restore To values are:
*Same: The objects are restored to the same names and directories on the target machine that they had on the source machine.
path-name: Enter the new path and name for the objects.
Note: Only the last directory or file in the path name will be created on the target machine. If any directory in the middle of the path name does not exist on the target, the send will fail.
The name of a server directory entry to be referenced. The entry must have been previously added to the server directory on your machine. This is a required parameter. Click here for a complete description of this parameter.
Specify whether sub-directories should be included with the selection.
The possible values are:
*ALL: All sub-directories in the specified paths are included.
*DIR: The sub-directories within each matching directory are included, but lower-level directories are not included.
*NONE: No sub-directories are included.
*OBJ: Only the specified objects are included. If a directory is specified, objects within the directory are not included.
Specify whether to transmit objects that are currently in use.
The possible values are:
*NO: The request ends in error if any of the objects to be transmitted are currently in use by another job.
*YES: All selected objects are transmitted, whether or not they are in use. The object checkpoints can occur at different times.
*SYNC: All selected objects are transmitted, whether or not they are in use. All object checkpoints occur at the same time.
Enter the OS/400 release level of the target machine, relative to the source machine.
The possible values are:
*CURRENT: The remote server machine is at the same OS/400 release level as the local machine.
*PRV: The target machine is one OS/400 release behind the source machine.
release-level: Enter the OS/400 release level of the remote machine, in the form VxRyMz, where x, y and z are the version, release and mod level respectively. For example: V4R4M0.
Indicate whether to compress data as it is transmitted. Click here for a complete description of this parameter.
Enter the qualified name of the location list to reference. Click here for a complete description of this parameter.
Enter the name of the member containing the location list. Click here for a complete description of this parameter.
Specify whether to reset the access count and status for all entries in the location list before beginning any transmissions. Click here for a complete description of this parameter.
Specify whether machines that receive the transmission successfully should forward the transmission on to other locations. Click here for a complete description of this parameter.
Specify one or more exit programs to call at various points in the
transmission.
Exit programs can be used to customize the way in which IFS objects are handled during the transmission. Exit programs can be used, for example, to set object authorities and owners, to create JAVA programs from JAVA class files, etc.
The following parameters are passed to the exit programs. All parameters are input only:
Exit type, CHAR(10). See the values for "When to Call" below.
Error indicator , CHAR(1). '1' if any errors have been encountered so far, otherwise '0'.
User space, CHAR(10). The name of the user space that
contains the path specifications for the objects being transmitted.
User space library, CHAR(10). The name of the library containing the user space.
The user space conforms to the standard format for list APIs outlined in section 1.2.3 of the OS/400 System API Reference manual. Each list entry has the following format:
Save path name, CHAR(256).
Include/Omit indication, CHAR(8). Blanks indicates *INCLUDE.
Otherwise the field will equal "*OMIT".
Restore path name, CHAR(256). "*SAME" for this field indicates that the restore path is the same as the save path.
Exit programs can use the List IFS Objects (LSTIFSRSF) command to produce a detailed list of IFS files to a user space. See the on-line help text for the LSTIFSRSF command for more information.
The possible single values are:
*NONE: No exit programs are called.
The possible Program values are:
*program-name: Enter the name of the program to call.
The possible Library values are:
*LIBL: The job library list is used to locate the program.
*CURLIB: The program is found in the job's current library.
library-name: Enter the name of the library containing the program.
The possible When To Call values are:
*BEFORESAV: The program is called on the source machine before the objects are saved.
*AFTERSAV: The program is called on the source machine after the objects are saved.
*BEFORERST: The program is called on the target machine before the objects are restored.
*AFTERRST: The program is called on the target machine after the objects are restored.
Whether RSF should end the session after the data is sent, without waiting to see whether the objects are restored successfully on the target machine. Click here for a complete description of this parameter.
Whether RSF should hang up the phone connection at the completion of the transaction. This parameter is ignored for non-switched connections. 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.
The following commands are discussed elsewhere in this manual:
Send Package (SNDRSFPKG)
Copy File Using RSF (CPYFRSF)
Send Objects (SNDOBJRSF)
Send Documents (SNDDOCRSF)
For more information about the following commands, prompt the command and press F1 to view the on-line help text:
Retrieve IFS Objects (RTVIFSRSF)
List IFS Objects (LSTIFSRSF)
The Start Pass-Through Using RSF (STRPASRSF) command is used to start a pass-through or telnet session with a remote server.
When you run the STRPASRSF command, the server machine is contacted and a sign-on display is presented.
Note: To end the pass-through session, specify ENDCNN(*YES) when entering the SIGNOFF command on the remote machine.
The prompted version of the STRPASRSF command is shown below. Click on the image to see parameter descriptions.
The parameters for the STRPASRSF command are described below.
The name of a server directory entry to be referenced. The entry must have been previously added to the server directory on your machine. See Adding Server Directory Entries for more information. This is a required parameter.
The possible values are:
name: The name of an entry in the server directory on your machine.
Specify a user profile to use for automatic sign-on to the remote system.
If a valid password is supplied, and if the remote system allows automatic sign-on, you can use this parameter to bypass the sign-on display on the remote system.
This parameter is ignored for TCP/IP connections.
The possible values are:
*NONE: Automatic sign-on is not requested.
*CURRENT: The user profile of the user executing this command is used.
user-profile-name: Enter a valid user profile name.
Specify a password to send to the remote system along with the user profile for automatic sign-on.
The possible values are:
*NONE: No password is sent.
password: Enter the password for the specified user profile.
Specify, for TCP/IP connections, whether to encrypt the password when initiating the connection.
This value is ignored unless:
A value other than *NONE was specified for the
Remote User Profile (RMTUSRPRF) parameter.
The operating system release level of the source and target machines is V5R1M0 or greater.
The possible values are:
*DES7: The default encryption method is used. If the remote operating system level is V5R1M0 or greater, a value of '0' or '1' must be specified for the QPWDLVL system value on the remote system.
*SHA1: SHA-1 encryption is used. The remote operating system level must be at V5R1M0 or later, and a value of '2' or greater must be specified for the QPWDLVL system value on the remote system.
*NONE: No password encryption is used.
Specify the name of an initial program to call when starting the session on the target system.
This value is ignored unless:
A value other than *NONE was specified for the
Remote User Profile (RMTUSRPRF) parameter.
System value QRMTSIGN on the target system is set
to *SAMEPRF or *VERIFY.
For TCP/IP connections, the operating system release level of the source and target machines is V5R1M0 or greater.
The possible values are:
*RMTUSRPRF: The initial program specified in the user profile on the target machine is used.
*NONE: No initial program is called.
program-name: Enter the name of the initial program to call. The program must be found in the target job's initial library list.
Specify the name of an initial menu to call when starting the session on the target system.
This value is ignored unless:
A value other than *NONE was specified for the
Remote User Profile (RMTUSRPRF) parameter.
System value QRMTSIGN on the target system is set
to *SAMEPRF or *VERIFY.
For TCP/IP connections, the operating system release level of the source and target machines is V5R1M0 or greater.
The possible values are:
*RMTUSRPRF: The initial menu specified in the user profile on the target machine is used.
*SIGNOFF: The job is signed off after the initial program completes.
menu-name: Enter the name of the initial menu to use. The menu must be found in the target job's initial library list.
Specify the name of the current library to use when starting the session on the target system.
This value is ignored unless:
A value other than *NONE was specified for the
Remote User Profile (RMTUSRPRF) parameter.
System value QRMTSIGN on the target system is set
to *SAMEPRF or *VERIFY.
For TCP/IP connections, the operating system release level of the source and target machines is V5R1M0 or greater.
The possible values are:
*RMTUSRPRF: The current library specified in the user profile on the target machine is used.
library-name: Enter the name of the initial current library to use.
Whether RSF should hang up the phone connection at the completion of the transaction. This parameter is ignored for non-switched connections. 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.
An ad hoc message to be sent to the server along with the start pass-through request. Click here for a complete description of this parameter.
When you prompt for command parameters with F4, default name, address and telephone information is filled in for you. These are the same defaults the system uses to send PTF orders via Electronic Customer Support.
The possible values are:
contact information: Enter the appropriate information for contact name, address, and phone.
The Copy File Using RSF (CPYFRSF) command is used to copy database file members between machines
The prompted version of the CPYFRSF command is shown below. Click on the image to see parameter descriptions.
Note: Error messages generated from this command that refer to file RSFCOPY actually refer to the remote file to/from which you are copying. Error messages that refer to library QTEMP may actually refer to the remote library to/from which you are copying.
The parameters for the CPYFRSF command are described below.
Specify whether you are sending or retrieving data. This is a required parameter.
The possible values are:
*SND: Data is sent to the remote machine.
*RTV: Data is retrieved from the remote machine.
Enter the qualified name of the file to copy data from. This is a required parameter.
If *SND is specified for "Send or retrieve data", this file must be on the local machine. Otherwise, the file must be on the remote machine.
The possible values are:
file-name: Enter the name of an existing file to copy data from.
The possible library values are:
*LIBL: Use the library list to locate the file
*CURLIB: The file is in the current library.
library-name: Enter the name of the library containing the file.
The name of a server directory entry to be referenced. The entry must exist in the server directory on your machine. This is a required parameter. Click here for a complete description of this parameter.
Enter the name or generic name of the member to copy from.
The possible values are:
*FIRST: The first member in the file is copied.
*ALL: All members in the file are copied.
member-name: Enter the name of the member to be copied. To specify a generic name, end your specification with an asterisk (*).
Enter the qualified name of the file to copy data to. If the file does not exist, it will be created.
If *SND is specified for "Send or retrieve data", this file will be on the remote machine. Otherwise, the file will be on the local machine.
The possible values are:
*FROMFILE: The data is copied to a file with the same name and library as specified in the "From file" parameter.
file-name: Enter the name of the file to copy data to.
The possible library values are:
*FROMLIB: The "To file" is in the same library as the "From file".
library-name: Enter the name of the library to contain the file.
Enter the name of the member to copy to.
The possible values are:
*FROMMBR: Data is copied to a member in the "To file" that has the same name as the member copied from.
*FIRST: Data is copied to the first member in the "To file".
member-name: Enter the name of the member to copy to.
Specify whether to add to or replace an existing member when copying data.
The possible values are:
*REPLACE: Copied data replaces the data in an existing member.
*ADD: Copied data is added to the data in an existing member.
Specify the method to use to transmit the data. When a TCP/IP connection is used, a value of *SPEED is assumed for this parameter, regardless of the value specified. .
The possible values are:
*SPACE: No work space is use to prepare or compress the data before it is transmitted. DDM is used to transmit the data, so this option is not available for TCP/IP connections.
For large files, this method requires more transmission time because the data is not compressed.
*SPEED: The data is compressed before it is sent. Work spaces are used on the source and target machines to pack/unpack the data. The temporary work space required may be equal in size to the data being transmitted. DDM is not used to transmit the data, so this option is always used with TCP/IP connections.
This method uses the system save/restore facilities, so data can only be transmitted between machines with compatible OS/400 release levels.
This method is faster for large files, where the transmission time saved more than makes up for the time spent packing and unpacking the data.
Note: In order to use this option, the server machine must be running RSF release 6.0 or greater.
Indicate whether to compress data as it is transmitted. Click here for a complete description of this parameter.
Specify the OS/400 release level of the remote machine, relative to your machine.
This parameter is ignored unless *SEND is specified for "Send or retrieve data", and *SPEED is specified (or assumed, as with TCP/IP connections) for the "Optimize for" parameter.
The possible values are:
*CURRENT: The remote server machine is at the same OS/400 release level as your machine:
*PRV: The remote server machine is one OS/400 release level behind your machine.:
release-level: Enter the OS/400 release level of the remote machine, in the form VxRyMz, where x, y and z are the version, release and mod level respectively. For example: V4R1M0.:
Enter the qualified name of a user program to call on the remote machine once the data has been copied to the target file.
The value you specify will be ignored by the server machine unless an entry referring to your machine exists in the requester directory of the server machine and specifies *YES or *PARTIAL for "Allow remote program calls". See Adding Requester Directory Entries for more information.
The possible values are:
*NONE: No program is called on the server machine after the file is copied. You must specify *NONE for this parameter if you specified *RTV for "Send or retrieve data".
*DFT: The value specified for "Post-Processing program" in the requester directory of the server machine is used. The server machine controls which program, if any is called.
program-name: Enter the name of a program to call on the server machine to process the received data.. See Post-Processing Programs for more information about how to write these programs.
The possible library values are:
*LIBL: The job library list is used to locate the program.
*CURLIB: The program is found in the current library.
library-name: Enter the name of the library containing the program.
Enter a user id and password to use on the remote system. The user id and password you specify will be used to determine your authority to files on the remote machine.
The possible single values are:
*RSFDFT: The default profile RSFSRV is used on 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 copy files from SYSTEMA to SYSTEMB and will have USER1's authority to the objects on SYSTEMA:
CPYFRSF ACTION(*RTV) FROMFILE(MYLIB/QCLSRC) SERVER(*CURRENT) FROMMBR(A*) USER(*REQUESTER)
The possible user id values are:
user-id: Enter a valid user id for the remote system.
The possible password values are:
password: Enter the appropriate password for the user id specified.
Specify whether the communications session with the server should be ended before any post-processing program is called.
The possible values are:
*NO: If the you have specified that a user-written program be called to process the received RSF data, and if the server has specified *NO for the DROP parameter on the requester directory entry, the session remains active while the post-processing program is called. Status messages reporting the progress of the post-processing program are returned to your machine.
*YES: The session with the server is ended after the data is received by the server. If the you have specified that a user-written program be called to process the received data, the session is ended before the program is called. The post-processing program is executed asynchronously on the server machine.
Whether RSF should hang up the phone connection at the completion of the transaction. 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.
An ad hoc message to be sent to the server along with the star pass-through request. Click here for a complete description of this parameter.
When you prompt for command parameters with F4, default name, address and telephone information is filled in for you. These are the same defaults the system uses to send PTF orders via Electronic Customer Support.
The possible values are:
contact information: Enter the appropriate information for contact name, address, and phone.
The following commands are discussed elsewhere in this manual:
Retrieve Package (RTVRSFPKG)
Send Package (SNDRSFPKG)
Retrieve Objects (RTVOBJRSF)
Send Objects (SNDOBJRSF)
Retrieve Documents (RTVDOCRSF)
Send Documents (SNDDOCRSF)
Create Package (CRTRSFPKG)
For more information about the following commands, prompt the command and press F1 to view the on-line help text:
Change Package (CHGRSFPKG)
Delete Package (DLTRSFPKG)
Rename Package (RNMRSFPKG)
The Schedule RSF Transmission (SCDRSFTNS) command is used to schedule an RSF transmission to one or more remote locations.
The transmission can be scheduled to occur immediately, or at some future date and time. The transmission can consist of sending a package of objects, retrieving a package of objects, or performing any combination of RSF functions for each location to be contacted.
The prompted version of the SCDRSFTNS command is shown below. Click on the image to see parameter descriptions.
The parameters for the SCDRSFTNS command are described below in the order that they appear on the command prompt.
Indicate the action to perform for each location being contacted. This is a required parameter.
The possible values are:
*SND: An RSF package is sent to each location. When you specify *SND for this parameter, you must also specify a value for the "Package" parameter.
*RTV: An RSF package is retrieved from each location. When you specify *RTV for this parameter, you must also specify a value for the "Package" parameter.
The save file retrieved will be placed in library QGPL and will have the same name as the server id from which it was retrieved. The SCDRSFTNS command does not delete the save file. You must delete the save file after installing the objects. You can manually delete the save file, or use an automatic installation program that will delete the save file after installation. Click here for more information about automatic installation programs.
*PGM: A user written program is called to process each location. When you specify *PGM for this parameter, you must also specify a value for the "User transmit program" parameter.
Enter a server id for the location to be contacted. This is a required parameter.
The possible values are:
*LIST: No specific server id is referenced. Instead, a location list is used to contact several remote locations. When you specify *LIST for this parameter, you must also specify a value for the "Location list" parameter. Click here for more information about location lists.
server-id: Enter a server id to reference from the server directory on your machine.
Enter the date the transmission should begin.
The possible values are:
*CURRENT: The transmission begins on the current date.
date: Enter a valid future date on which to begin the transmission.
Enter the time the transmission should begin.
The possible values are:
*CURRENT: The transmission begins at the current time.
time: Enter a valid future time on which to begin the transmission.
Specify whether RSF should attempt to install a package once it has been sent or retrieved.
This parameter is ignored if *PGM is specified for "Action to perform".
For automatic installation, RSF attempts to restore program RSFINST to library QTEMP from the save file that was transmitted with the package.
If program RSFINST can be restored, it is called with the following parameter list:
A data structure describing the request, CHAR(*). See Appendix A for a complete description of the data structure.
Return message data. CHAR(128).
Return message type. CHAR(7).
Saved library. CHAR(10).
Save command used. CHAR(10).
It is the user's responsibility to write installation program RSFINST and include it in the save file for the package if automatic installation for this package is to be supported. See Automatic Installation Programs for more information.
The possible values are:
*TRY: Automatic installation is attempted. The request ends normally if no automatic installation program is found. If you know automatic installation does not apply, it is more efficient to specify *NO for this parameter.
*YES: Automatic installation is attempted. The request ends in error if no automatic installation program is found.
*NO: No attempt is made to automatically install the package.
Enter the name of an RSF package to reference for sending or retrieving objects. This parameter is required if a value other than *PGM is specified for the "Action to perform" parameter.
If *RTV is specified for "Action to perform", the package must exist on the remote machine. If *SND is specified for "Action to perform", the package must exist on the local machine.
The possible values are:
package-name: Enter the name of an RSF package. The save file associated with the package will be sent to or retrieved from each remote location.
Enter the qualified name of a user program to call. This is a required parameter if *PGM is specified for the "Action to perform" parameter.
The program specified is called once for each remote location to be contacted. The program can send objects to, retrieve objects from, or perform any combination of valid RSF functions for the remote location.
The possible values are:
program name: Enter the name of a user-written program to call.
The possible library values are:
*LIBL: The library list is used to find the program.
*CURLIB: The program is found in the current library.
library-name: Enter the name of the library containing the program.
The user program is passed the following parameters:
Server id: CHAR(10): The server id to be contacted.
Control data: CHAR(1024): A data structure containing control information about the location to be contacted. All fields are in character format. The layout of the control data structure is as follows:
1-10: The name of the location list being used, if any.
11-20: The library containing the location list.
21-30: The member containing the location list.
31-40: The current status for the entry to be contacted.
41-50: The current step for the entry to be contacted.
51-53: The maximum number of tries for the entry.
54-56: The current try number.
57-1024: Reserved.
Enter the qualified name of the location list you want to reference. This is a required parameter if *LIST is specified for the "Server id" parameter. Click here for more information about location lists.
The possible values are:
location-list-name: Enter the name for the file containing the location list.
The possible library values are:
*LIBL: The library list is used to find the location list.
*CURLIB: The location list is found in the current library
library-name: Enter the name of the library containing the location list.
Enter the name of the member containing the location list.
The possible values are:
*FIRST: The location list stored in the first member of the file is used.
member-name: Enter the name of the member containing the location list
Specify whether to reset the access count and status for all entries in the location list. This parameter is ignored unless *LIST is specified for the "Server id" parameter.
The possible values are:
*YES: The location list is reset. Entries in the list are reset by the first job submitted by this command to begin execution.
*NO: The location list is not reset.
Specify the number of simultaneous jobs to submit to process the request.
The possible values are:
*DFT: The value specified for the "Number of jobs to submit" parameter on the Create Location List (CRTRSFLL) command for the location list being referenced is used. If no location list is referenced, 1 is assumed.
1-255: Specify the number of simultaneous jobs to submit to process the list. You should not submit more jobs than lines available for use by RSF.
Specify the job descriptions to use when submitting jobs to process the request. The job descriptions determine the job queues to which jobs are submitted, and other job attributes.
You may specify up to 255 job descriptions. When multiple jobs are submitted to process the request, the first job uses the first job description, the second job uses the second job description, and so on. If more jobs are submitted than the number of job descriptions specified, the job description list is used repeatedly until all jobs have been submitted.
The possible single values are:
*DFT: The value specified for the "Job description" parameter on the Create Location List (CRTRSFLL) command for the location list being referenced is used. If no location list is referenced, *USRPRF is assumed.
*USRPRF: The job description specified in the user profile of the user executing this command is used.
job-description: Enter the name of an existing job description
The possible library values are:
*LIBL: The job description is found using the library list.
*CURLIB: The job description is found in the current library.
library-name: Enter the name of the library containing the job description.
The following commands are discussed elsewhere in this manual:
Create Location List (CRTRSFLL)
Retrieve Location List Entry (RTVRSFLLE)
Change Location List Entry (CHGRSFLLE)
For more information about the following commands, prompt the command and press F1 to view the on-line help text:
Change Location List (CHGRSFLL)
Location lists can be used in conjunction with the Schedule RSF Transmission (SCDRSFTNS) command to schedule an automatic transmission to several remote locations.
You can also use location lists in your own CL programs. Once a list has been created, use the Retrieve RSF Location List Entry (RTVRSFLLE) command to retrieve the next location to be contacted from the list. Use the Change Location List Entry (CHGRSFLLE) command to update the status of an entry after contacting the remote location.
Multiple jobs can be retrieving entries off the same location list at the same time. Each entry in the list will only be returned to one job at a time. You can use this feature to submit multiple batch jobs to work through a single list.
The Create Location List (CRTRSFLL) command is used to create a working list of remote server locations that you wish to contact. You can use the list created with this command to retrieve objects from each location in the list, send objects to each location in the list or perform any combination of RSF functions for each location.
The prompted version of the CRTRSFLL command is shown below. Click on the image to see parameter descriptions.
The parameters for the CRTRSFLL are described below.
You can create complex location lists by executing this command repeatedly for the same location list and specifying *ADD for "Replace or add records".
Enter the qualified name of the location list you are creating. Location lists are stored as physical file members. This is a required parameter.
The possible values are:
location-list-name: Enter the name for the file to contain the location list. If the file does not exist, it will be created.
The possible library values are:
*CURLIB: The location list is created in the current library
library-name: Enter the name of the library to contain the location list.
Enter the name of the member to contain the location list.
The possible values are:
*FIRST: The location list is stored in the first member in the file.
member-name: Enter the name of the member to contain the location list. If the member doesn't exist, it will be added.
Specify whether to add to or replace an existing location list.
The possible values are:
*REPLACE: If a location list exists with the same file, library and member name, it is replaced.
*ADD: Add to an existing location list.
Specify which entries from the server directory on your machine to include in the list.
The possible values are:
*ALL: All entries from the server directory on your machine are included in the list.
generic-server-id: Specify a specific server id to include in the list, or key * anywhere in the name to match any substring of 0 or more characters. Key _ anywhere in the name to match any single character.
For example: Specify *B* to select all server ids containing the letter B.
Specify data to compare to the server id text to selectively include entries in the list.
Specify a value to compare to.
The possible values are:
character-string: Specify any string from 0 to 50 characters in length.
Specify the starting position for the comparison.
The possible library values are:
1-50: Specify a starting position from 1 to 50.
Specify a relational operator to use for the comparison.
The possible library values are:
*EQ: Server ids are included in the list if their text, at the starting position specified, is equal to the compare value specified.
*NE: Server ids are included in the list if their text, at the starting position specified, is not equal to the compare value specified.
*GT: Server ids are included in the list if their text, at the starting position specified, is greater than to the compare value specified.
*LT: Server ids are included in the list if their text, at the starting position specified, is less than to the compare value specified.
*GE: Server ids are included in the list if their text, at the starting position specified, is greater than or equal to the compare value specified.
*LE: Server ids are included in the list if their text, at the starting position specified, is less than or equal to the compare value specified.
*NG: Server ids are included in the list if their text, at the starting position specified, is not greater than the compare value specified.
*NL: Server ids are included in the list if their text, at the starting position specified, is not less than the compare value specified.
*CT: Server ids are included in the list if their text, anywhere from the starting position specified to the end of the text, contains the compare value specified.
Specify the number of times you want to attempt to contact a given location. Repeated attempts will be made to contact each location until the transmission to the location is successful, or the transmission to the location has been attempted the number of times specified in this parameter.
When you use the RTVRSFLLE command to retrieve entries from a location list, entries that have not been contacted are returned first, followed by entries where the previous contact ended in error. The value you specify for this parameter determines the number of times the RTVRSFLLE command will return a given server id to your program when the previous attempt to contact the server ended in error. When all locations have been contacted successfully or have been tried the number of times specified by this parameter, the RTVRSFLLE command returns *NONE for server id.
The possible values are:
2: A maximum of two attempts will be made to contact each location.
1-50: Specify the maximum number of times to try to contact each remote location.
Specify the default number of jobs to submit to process the location list. This value is used by the Schedule RSF Transmission (SCDRSFTNS) command when scheduling transmissions using this location list.
The possible values are:
1: One job is submitted to process the list.
1-255: Specify the number of simultaneous jobs to submit to process the list. You should not submit more jobs than lines available for use by RSF.
Specify the default job description to use when submitting jobs to process the location list. This value is used by the Schedule RSF Transmission (SCDRSFTNS) command when scheduling transmissions using this location list.
The possible single values are:
*USRPRF: The job description specified in the user profile of the user executing the SCDRSFTNS command is used.
The possible job description values are:
job-description: Enter the name of an existing job description.
The possible library values are:
*LIBL: The job description is found using the library list.
*CURLIB: The job description is found in the current library.
library-name: Enter the name of the library containing the job description.
The following commands are discussed elsewhere in this manual:
Schedule Transmission (SCDRSFTNS)
Retrieve Location List Entry (RTVRSFLLE)
Change Location List Entry (CHGRSFLLE)
For more information about the following commands, prompt the command and press F1 to view the on-line help text:
Change Location List (CHGRSFLL)
Display Location List (DSPRSFLL)
Use the Retrieve RSF Location List Entry (RTVRSFLLE) command within a CL program to retrieve the next location to be contacted from an RSF location list.
The prompted version of the RTVRSFLLE command is shown below. Click on the image to see parameter descriptions.
The parameters for the RTVRSFLLE command are described below in the same order that they appear on the command prompt.
Enter the qualified name of the location list to reference. This is a required parameter.
The possible values are:
location-list-name: Enter the name for the file containing the location list.
The possible library values are:
*LIBL: The location list is found using the library list.
*CURLIB: The location list is found in the current library.
library-name: Enter the name of the library containing the location list.
Enter the name of the member containing the location list.
The possible values are:
*FIRST: The location list is stored in the first member in the file.
member-name: Enter the name of the member containing the location list.
Specify the server id for the entry to be retrieved.
The possible values are:
*NEXT: The next server to be contacted is retrieved. When you specify *NEXT for this parameter, a single entry is returned. Entries that have not yet been retrieved are returned first, followed by entries with a status of *ERROR that have not yet been retrieved the maximum number of times specified on the Create RSF Location List (CRTRSFLL) command.
If there are no more entries to retrieve, *NONE is returned for the RTNSERVER parameter. When a value other than *NONE is returned, the status for the entry is set to *INUSE and the number of tries for the entry is incremented by 1.
*FIRST: The first entry in the list is retrieved.
server-id: Enter the server id for the entry to be retrieved.
Enter the name of a CL variable to receive the returned server id. This is a required parameter.
The possible values are:
variable-name: Enter the name of a CL variable. The variable should be declared as TYPE(*CHAR) LEN(10).
Enter the name of a CL variable to receive the current status for the entry being retrieved.
The possible values are:
variable-name: Enter the name of a CL variable. The variable should be declared as TYPE(*CHAR) LEN(10).
Enter the name of a CL variable to receive the current user-defined step for the entry being retrieved.
The possible values are:
variable-name: Enter the name of a CL variable. The variable should be declared as TYPE(*CHAR) LEN(10).
Enter the name of a CL variable to receive the maximum number of tries specified for the entry being retrieved.
The possible values are:
variable-name: Enter the name of a CL variable. The variable should be declared as TYPE(*DEC) LEN(3 0).
Enter the name of a CL variable to receive the current try number for the entry being retrieved.
The possible values are:
variable-name: Enter the name of a CL variable. The variable should be declared as TYPE(*DEC) LEN(3 0).
Enter the name of a CL variable to receive the default number of jobs to submit to process the location list.
The possible values are:
variable-name: Enter the name of a CL variable. The variable should be declared as TYPE(*DEC) LEN(3 0).
Enter the name of a CL variable to receive the default job description associated with the location list.
The possible values are:
variable-name: Enter the name of a CL variable. The variable should be declared as TYPE(*CHAR) LEN(10).
Enter the name of a CL variable to receive the library for the default job description associated with the location list.
The possible values are:
variable-name: Enter the name of a CL variable. The variable should be declared as TYPE(*CHAR) LEN(10).
The following commands are discussed elsewhere in this manual:
Schedule Transmission (SCDRSFTNS)
Create Location List (CRTRSFLL)
Change Location List Entry (CHGRSFLLE)
For more information about the following commands, prompt the command and press F1 to view the on-line help text:
Change Location List (CHGRSFLL)
Display Location List (DSPRSFLL)
Use the Change Location List Entry (CHGRSFLLE) command to change a location list entry.
The prompted version of the CHGRSFLLE command is shown below. Click on the image to see parameter descriptions.
The parameters for the CHGRSFLLE command are described below in the same order that they appear on the command prompt.
Enter the qualified name of the location list to reference. This is a required parameter.
The possible values are:
location-list-name: Enter the name of the file containing the location list.
The possible library values are:
*LIBL: The location list is found using the library list.
*CURLIB: The location list is found in the current library.
library-name: Enter the name of the library containing the location list.
Enter the name of the member containing the location list.
The possible values are:
*FIRST: The location list is stored in the first member in the file.
member-name: Enter the name of the member containing the location list.
Specify the server id for the entry to be updated. This is a required parameter.
The possible values are:
server-id: Enter the server id for the location list entry to be updated.
Specify the new status setting for the location list entry.
The possible values are:
*SAME: The current value is not changed.
*COMPLETE: The entry is flagged as complete.
*ERROR: Contact with the remote location ended in error. If the maximum number of attempts to contact this location (as specified on the Create Location List command) has not been reached, this entry can be retrieved from the location list again with the Retrieve RSF Location List Entry command.
*QUIT: Contact with the remote location ended in error. No further attempt will be made to contact the location.
*RESET: The status, step and access count for the entry are reset to their initial values.
*INUSE: If the entry is not already in use, does not have a status of *COMPLETE, and has not yet been contacted the maximum number of times, the status is set to *INUSE. Otherwise, the operation ends in error.
Specify a new value for the user-defined step field. You can use this field to keep track of individual steps within a complex transmission.
The possible values are:
*SAME: The current value is not changed.
character-value: Specify a new step value.
The following commands are discussed elsewhere in this manual:
Schedule Transmission (SCDRSFTNS)
Create Location List (CRTRSFLL)
Retrieve Location List Entry (RTVRSFLLE)
For more information about the following commands, prompt the command and press F1 to view the on-line help text:
Change Location List (CHGRSFLL)
Display Location List (DSPRSFLL)
Location lists can be used with the Schedule RSF Transmission (SCDRSFTNS) command, or within your own CL programs. The following example illustrates how you might use a location list within your own CL programs.
This example bypasses the SCDRSFTNS command and sends RSFTOOLS to all servers known to the local machine whose names contain the letter B.
DCL VAR(&SERVER) TYPE(*CHAR) LEN(10) DCL VAR(&STATUS) TYPE(*CHAR) LEN(10) /* Create the location list */ CRTRSFLL LIST(QTEMP/TEST) SERVER('*B*') /* Send the library to each location */LOOP: RTVRSFLLE LIST(QTEMP/TEST) SERVER(*NEXT) RTNSERVER(&SERVER)
IF (&SERVER = '*NONE') THEN(GOTO CMDLBL(ENDLOOP)) CHGVAR VAR(&STATUS) VALUE('*COMPLETE') SNDRSFPKG PKG(RSFTOOLS) SERVER(&SERVER) /* Handle transmission error */ MONMSG MSGID(CPF0000 RPG0000 RSF0000) EXEC(DO) CHGVAR VAR(&STATUS) VALUE('*ERROR') ENDDO /* Note status */ CHGRSFLLE LIST(QTEMP/TEST) SERVER(&SERVER) STATUS(&STATUS) GOTO CMDLBL(LOOP)ENDLOOP:
The End RSF Switched Connection (ENDRSFCNN) command is used to explicitly hang up a phone connection with a remote server. Remote Software Facility automatically hangs up after each transaction, unless HANGUP(*NO) was specified. Where HANGUP(*NO) was specified for a previous request, the line will remain active until another request for the same server specifies HANGUP(*YES), or the ENDRSFCNN command is used to explicitly end the connection.
The prompted version of the ENDRSFCNN command is shown below.
The parameters for the ENDRSFCNN command are described below.
The name of the server with whom you want to end the connection. The name must correspond to an existing entry in the server directory on your machine. See Adding Server Directory Entries for more information about server directory entries. This is a required parameter.
The possible values are:
*ALL: All inactive RSF requester phone lines are disconnected. A line is considered to be inactive if RSF's internal log shows no active conversations for the line, or if the line is not currently in an active state.:
name: The name of an entry in the server directory on your machine.:
The Start Message Queue Monitor (STRRSFMSGM) command is used to monitor remote message queues from a central AS/400.
This function is often called Remote Console Support because it allows you to forward system console messages from remote machines to a central machine.
Messages forwarded from remote machines are directed to a message queue on the central machine. Answering forwarded inquiry messages on the central machine causes the specified reply to be sent automatically to the originating machine.
The prompted version of the STRRSFMSGM command is shown below. Click on the image to see parameter descriptions.
The parameters for the STRRSFMSGM command are described below.
Specify whether to send messages from your machine to a central AS/400, or whether to retrieve messages from a message queue on a remote machine.
To monitor messages on satellite machines from a central site, there are two strategies you can employ:
Each method has its advantages and disadvantages. The Push method makes the most efficient use of communication resources by only contacting the central machine when there are actually messages to be sent. However, the Push method puts the remote machines in control. If an error occurs on a remote that prevents messages from being sent, the central machine will never know it.
The Pull method puts the central machine in control, but wastes communication resources as the central machine polls remotes that infrequently have messages to send. The Pull method also uses greater machine resources on the central AS/400 because one job must be active in batch for each remote being polled.
The possible values are:
*SND: Send messages from your machine to another machine.
*RTV: Retrieve messages from a remote machine.
Enter the qualified name of the message queue to be monitored. If *SND is specified for "Send or Retrieve Messages", this message queue is on the local AS/400. Otherwise, this message queue is on the remote machine.
The possible values are:
message queue name: Enter the name of the message queue to be monitored.
The possible library values are:
*LIBL: Use the library list to locate the message queue.
*CURLIB: Find the message queue in the job's current library.
library name: Enter the name of the library containing the message queue.
Enter the qualified name of the message queue to which messages should be sent. If *SND is specified for "Send or Retrieve Messages", the message queue is on the remote AS/400. Otherwise, the message queue is on the local machine.
The possible values are:
message queue name: Enter the name of the message queue to receive the forwarded messages.
The possible library values are:
*LIBL: Use the library list to locate the message queue.
*CURLIB: Find the message queue in the job's current library.
library name: Enter the name of the library containing the message queue.
The name of a server directory entry to be referenced. The entry must exist in the server directory on your machine. Click here for a complete description of this parameter.
Specify the number of seconds to wait before looking for more messages.
When *SND is specified for "Send or Retrieve Messages", this parameter indicates the number of seconds to wait before contacting the central machine again to check for replies to outstanding inquiry messages.
When *RTV is specified for "Send or Retrieve Messages", this parameter indicates the number of seconds to wait before contacting the remote machine again to check for new messages.
The possible values are:
900: Check every 15 minutes.
seconds: Enter the number of seconds to wait before checking again.
Specify the number of seconds to wait for new messages before ending the connection. For switched connections, this is the number of seconds to wait for new messages before hanging up.
This timer is reset each time a new message to be transmitted is found.
The possible values are:
180: Keep the connection active for 3 minutes after transmitting a message to wait for new messages.
seconds: Enter the number of seconds to wait for new messages before ending the connection.
Specify the lowest severity for messages to be transmitted. Messages are transmitted if the message severity is greater than or equal to the severity filter specified.
The possible values are:
0: All messages are transmitted, regardless of the message severity.
1-99: Enter a severity filter from 1 to 99.
Specify one or more message IDs to omit. Messages with omitted message IDs are not transmitted. You can specify up to 50 values for this parameter. Specifications ending in zeros are treated as generics. For example, OMIT(MCH0000) would omit all messages beginning with "MCH".
The possible single values are:
*NONE: No message IDs are omitted.
The other possible values are:
message-ID: Enter message IDs to omit.
Specify whether a header message should be sent with each transmitted message. Header messages are sent to the target message queue immediately preceding each transmitted messages. The first level text for the header message indicates the machine of origin for the transmitted message. The second level text contains information about the sender of the original message.
When header messages are sent, a trailing blank message is also placed in the queue after the message being transmitted.
The possible single values are:
*YES: Header messages are sent.
*NO: Header messages are not sent.
Specify the name of a job description to use to submit the monitor job to batch.
The possible values are:
*USRPRF: The monitor job is submitted to batch using the job description from your user profile.
*NONE: The request is not submitted to batch. The request is run immediately.
job-description: Enter the name of an existing job description to use to submit the monitor job to batch.
The possible library values are:
*LIBL: Use the library list to locate the job description.
*CURLIB: Find the job description in the job's current library.
library name: Enter the name of the library containing the job description.
The following commands are discussed elsewhere in this manual:
Send Message Using RSF (SNDMSGRSF)
For more information about the following commands, prompt the command and press F1 to view the on-line help text:
End Message Queue Monitor (ENDRSFMSGM)
RSF Events can be used to coordinate dependent processes running on one or multiple machines, allowing you to condition the execution of one function on the successful completion of other functions.
Events are logged to a data base file. You can retrieve the status of an event by using the Retrieve Event Attributes (RTVEVTRSF) command in a CL program. (See the on-line help text for more information.) You can schedule a function to execute when one or more events attain a specific status by using the Wait For Events (WAITEVTRSF) command.
The Log Event (LOGEVTRSF) command is used to log a user-defined event.
The prompted version of the LOGEVTRSF command is shown below. Click on the image to see parameter descriptions.
The parameters for the LOGEVTRSF are described below.
Enter the name of the group containing the event. Event IDs are unique within the group for a given log file member.
This is a required parameter.
The possible values are:
name: Enter the group name.
Enter the ID for the event being logged.
This is a required parameter.
The possible values are:
*ALL: All events for the specified group will be set to the specified status. When *ALL is specified for this parameter, at least one event must already be defined for the group.
event-ID: Enter the ID of the event to be logged. If the event is already defined for the specified group in the specified log file member, the existing event is changed. If the event is not yet defined, it is added.
Enter the status value for the event. This value can be retrieved later using the Retrieve Event Attributes (RTVEVTRSF) command. The status of an event can also be used to trigger an action with the Wait For Event (WAITEVTRSF) command.
This is a required parameter.
The possible values are:
*BLANK: The event status is set to all blanks.
*START: Set the event status to *START to indicate that a process has started.
*COMPLETE: Set the event status to *COMPLETE to indicate that a process has completed successfully.
*ERROR: Set the event status to *ERROR to indicate that a process has ended abnormally.
character-value: Specify a user-defined status.
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.
The possible values are:
*CURRENT: Send the package 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.
*LOCAL: The request is directed to the local machine without using communications.
Specifying *LOCAL differs from specifying LOCAL (no preceding asterisk) in that LOCAL refers a specific server ID while *LOCAL tells RSF to bypass communications altogether and send the request directly to the local machine.
LOCAL (without an asterisk) can also be used to direct the request to the local machine but in this case, APPC communications is used, though the source and target machines are both the local machine.
name: The name of an entry in the server directory on your machine.
Enter the qualified name of the log file to use on the server machine.
The possible values are:
LOGEVTRSF: The default log file name is used.
file-name: Enter the name of the log file to use.
The possible library values are:
QGPL: The default library is used.
library-name: Enter the name of the library on the server machine containing the log file to be used.
Enter the name of the member in the log file to use.
The possible values are:
*GROUP: A member with the same name as the event group is used.
*FIRST: The first member in the specified log file is used.
member-name: Specify a member name to use.
Specify whether RSF should automatically create the log file and member when necessary.
The possible values are:
*NO: The request ends in error if either the log file or member does not exist.
*YES: If either the log file or member does not exist, they are created.
Specify whether the log file member should be cleared before logging this event.
The possible values are:
*ADD: The log member is not cleared.
*REPLACE: The log member is cleared before logging this event.
Specify whether the link to the remote machine should be ended after this request. This parameter is ignored if *LOCAL is specified for Server id.
The RSFLINK API is used to establish the connection to the remote machine. Some overhead is involved in first making the connection and establishing the link. If you plan to direct multiple requests to the same location, end the link with the last request. See chapter 9, Calling Remote Programs for more information about RSFLINK.
The possible values are:
*YES: The link is ended after this request.
*NO: The link remains active after this request.
Specify whether RSF should hang up the phone connection at the completion of the transaction. This parameter is ignored for non-switched connections. 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.
The following commands are discussed elsewhere in this manual:
Wait For Events (WAITEVTRSF)
For more information about the following commands, prompt the command and press F1 to view the on-line help text:
Retrieve Event Attributes (RTVEVTRSF)
The Wait For Events (WAITEVTRSF) command can be used to perform some function when one or more RSF events attain a particular status. Because RSF events can be logged to any machine, from any other machine, this command provides a means of coordinating functions across machines.
Events are logged to a data base file. You can retrieve the status of an event by using the Retrieve Event Attributes (RTVEVTRSF) command in a CL program. (See the on-line help text for more information.) You can log an event or change its status with the Log Event (LOGEVTRSF) command.
The prompted version of the WAITEVTRSF command is shown below. Click on the image to see parameter descriptions.
The parameters for the WAITEVTRSF are described below.
Enter the name of the group containing the event. Event IDs are unique within the group for a given log file member.
This is a required parameter.
The possible values are:
name: Enter the group name.
Specify the names and status for the events to be checked. Up to 50 events may be specified.
This is a required parameter.
The possible event values are:
*ALL: All existing events in the group are checked. When *ALL is specified for this parameter, an error is returned if no events are defined for the group.:
event-ID: Enter the ID of the event to be checked.:
The possible status values are:
*COMPLETE: The wait condition for this event is satisfied when the event is logged with a status of *COMPLETE.
*BLANK: The wait condition for this event is satisfied when the event is logged with a status of all blanks.
*START: The wait condition for this event is satisfied when the event is logged with a status of all *START.
*ERROR: The wait condition for this event is satisfied when the event is logged with a status of all *ERROR.
*ANY: The wait condition for this event is satisfied when the event is logged with any status.
character-value: The wait condition for this event is satisfied when the event is logged with the user-defined status specified.
Enter a valid CL command to run when all of the event conditions have been satisfied. The command can be up to 1000 characters long.
This is a required parameter.
The possible event values are:
DLYJOB 1: Use this command string if you do not want to perform any meaningful function after waiting for the event conditions to be met. This string will cause the job to delay for one second.
command-string: Enter a valid CL command.
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.
The possible values are:
*CURRENT: Send the package 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.
*LOCAL: The request is directed to the local machine without using communications.
Specifying *LOCAL differs from specifying LOCAL (no preceding asterisk) in that LOCAL refers a specific server ID while *LOCAL tells RSF to bypass communications altogether and send the request directly to the local machine.
LOCAL (without an asterisk) can also be used to direct the request to the local machine but in this case, APPC communications is used, though the source and target machines are both the local machine.
name: The name of an entry in the server directory on your machine.
Enter the qualified name of the log file to use on the server machine.
The possible values are:
LOGEVTRSF: The default log file name is used.
file-name: Enter the name of the log file to use.
The possible library values are:
QGPL: The default library is used.
library-name: Enter the name of the library on the server machine containing the log file to be used.
Enter the name of the member in the log file to use.
The possible values are:
*GROUP: A member with the same name as the event group is used.
*FIRST: The first member in the specified log file is used.
member-name: Specify a member name to use.
Specify the maximum amount of time the job should wait for the event conditions to be met.
The possible values are:
0: The job does not wait. An error is signaled if the event conditions are not met immediately.
*NOMAX: There is no limit to the amount of time that the job will wait for the event conditions to be met.
2-32767: The maximum number of seconds the job should wait for the event conditions to be met.
Specify the amount of time the job should delay between successive checks to see if the event conditions are met. Shorter delay times require the job to use more system resources but will result in a quicker response to changes in event status.
The possible values are:
20: Wait 20 seconds between successive checks.
2-32767: The number of seconds to wait between successive checks.
Specify a status value to which all events being tested should be set at the beginning of the request. If this command is submitted to batch, the events are not reset until the batch job begins execution.
The possible event values are:
*NONE: The events are not reset.
*BLANK: The events are initially reset to a status of all blanks.
*START: The events are initially reset to a status *START.
*COMPLETE: The events are initially reset to a status *COMPLETE.
*ERROR: The events are initially reset to a status *ERROR.
character-value: The events are initially reset to the user-defined status specified.
Specify the name of a job description to use to submit the request to batch.
The possible values are:
*USRPRF: The request is submitted to batch using the job description from your user profile.
*NONE: The request is not submitted to batch. The request is run immediately.
job-description: Enter the name of an existing job description to use to submit the request to batch.
The possible library values are:
*LIBL: Use the library list to locate the job description.
*CURLIB: Find the job description in the job's current library.
library name: Enter the name of the library containing the job description.
Specify whether the link to the remote machine should be ended after this request. This parameter is ignored if *LOCAL is specified for Server id.
The RSFLINK API is used to establish the connection to the remote machine. Some overhead is involved in first making the connection and establishing the link. If you plan to direct multiple requests to the same location, end the link with the last request. See chapter 9, Calling Remote Programs for more information about RSFLINK.
The possible values are:
*YES: The link is ended after this request.
*NO: The link remains active after this request.
Specify whether RSF should hang up the phone connection at the completion of the transaction. This parameter is ignored for non-switched connections. 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.
The following commands are discussed elsewhere in this manual:
Log Event (LOGEVTRSF)
For more information about the following commands, prompt the command and press F1 to view the on-line help text:
Retrieve Event Attributes (RTVEVTRSF)