RUNRMTCMD (Run Remote Command)

RUNRMTCMD Command syntax diagram

 

Purpose

The Run Remote Command (RUNRMTCMD) command, also known as AREXEC when an SNA address is specified for the remote location name, allows iSeries 400 users to run a command on a remote system that is running the target portion of this function.

The target portion of this function can be a rexecd (remote executing) daemon if you specify *IP for the address type, or an AREXECD (APPC remote executing) daemon when an SNA address is specified for the remote location name. If you want to run a command on a Client Access/400 client that supports this function, you will need to specify an SNA address for the remote location name.

When the command is sent to the remote system, the local system waits for the command to complete and the output from the remote command will be sent back to the local system and placed in a spooled file.

 

Required Parameters

CMD

Specifies a character string of up to 2000 characters that represents a command that is run on the target system. The maximum length supported by the target system may be less than 2000 characters. If you specify a command string that exceeds the maximum length supported by the target system, the command will fail.

The command must be enclosed in apostrophes if it contains embedded blanks or special characters.

Note:

The normal rule of pairing apostrophes in quoted strings on the local system must be doubled when the same string is submitted to a remote system on this CMD parameter; this is required because the user is coding a quoted string within another quoted string. Therefore, when this parameter is being coded, wherever a single apostrophe would normally be paired with another apostrophe, each occurrence in the inside set of apostrophes must be doubled to produce the same results at the target system.

RMTLOCNAME

If using the AREXEC command, RMTLOCNAME must be a single-element value containing an SNA address. The second element value *SNA is implied and cannot be specified.

Specifies the name of the target system and the type of address used to connect to the target system.

Element 1: Name or address

When the address type is *SNA, specify the name of the target system using the format nnnnnnnn.cccccccc, where nnnnnnnn is the network ID and cccccccc is the remote location name. If no network ID is specified, the command uses the network attributes to determine the default network ID.

When the address type is *IP, specify a host name or an Internet address to identify the target system. Host names must follow these conventions:

• The first character must be either A through Z or 0 through 9.
• The last character must be either A through Z or 0 through 9.
• Uppercase and lowercase characters are allowed, but no significance is attached to the case.
• Blanks ( ) are not allowed.
• The special characters, period (.) and minus (-), are allowed.
• Parts of the name separated by periods (.) cannot exceed 63 characters in length.
• Names must be from 1 to 255 characters in length.

The internet address is specified in the form nnn.nnn.nnn.nnn, where nnn is a decimal number ranging from 0 through 255. An internet address is not valid if it has a value of all binary ones or all binary zeros for the network identifier (ID) portion or the host ID portion of the address. If the internet address is entered from a command line, the address must be enclosed in apostrophes.

Element 2: Type

Specifies the address type for the target system that the command is to be run on.

*SNA: The target system is accessed using a Systems Network Architecture (SNA) address and protocol.

*IP: The target system is found using a host name or an Internet address over a TCP/IP connection.

 

Optional Parameters

RMTUSER

Specifies the user identifier (ID) for the target system. If a user ID is specified for this parameter and password security is active on the target system, RMTPWD(*NONE) is not valid.

*NONE: No user ID is sent. If security on the target system is configured to require a user ID, the command will fail.

*CURRENT: The user ID of the job (signed-on user) using this command is sent.

remote-user-identifier: Specify a user ID to use that exists on the target system. If a user ID is specified and password security is active on the target system, a password must be specified, even if the profile specified is the same as the current profile.

RMTPWD

Specifies the password sent to the target system.

*NONE: The system does not pass a password. If a user identifier (ID) is specified on the RMTUSER parameter and password security is active on the target system, the command will fail.

password: Specify a password sent to the target system to verify the sign-on of the user ID specified in the RMTUSER parameter. If a address type of *IP is specified, the password sent is not substituted across the communication line; if *SNA is specified, the password may or may not be substituted, depending on whether the remote system supports password substitution.

MODE

Specifies the mode used when sending the command to the target system. This parameter is allowed only when the address type value is *SNA.

*NETATR: The mode in the network attributes is used.

mode-name: Specify a mode name. Specify BLANK for a mode name consisting of eight blank characters.

Note: SNASVCMG and CPSVCMG are reserved names and cannot be specified.

CCSID

Specifies the coded character set identifier (CCSID) that will be used for conversions. When data is sent to the remote system, the data is converted using the CCSID of the job to the CCSID specified on the CCSID parameter. Similarly, when data is received from the remote system, the data is converted from the CCSID that was specified on the CCSID parameter to the CCSID of the job.

Note:

If the CCSID of the job is 65535 (indicating no conversion), the default CCSID of the job will be used. This command uses the round-trip conversion method when converting data from the source CCSID to the target CCSID and back. For more information about CCSID conversion methods, see the Globalization topic in the Information Center.

*CALC: The CCSID value sent from the target system is used if it is available. If a value is not provided from the target system, a default value of 00819 (ISO 8859-1 8-bit ASCII) is used.

coded-character-set-identifier: The requested CCSID value is used. This value is validated to ensure a valid CCSID has been requested.

WAITTIME

Specifies the time in seconds to wait for the response before declaring the remote location to be unreachable. This parameter is allowed only when the address type value is *SNA.

*NOMAX: The system waits indefinitely.

*NOWAIT: The system returns immediately if there is not a conection ready and available.

wait-time: Specify the wait time in seconds. Valid values are 2 to 3600 seconds.

Examples for RUNRMTCMD

Example 1: Run Remote Command (RUNRMTCMD) using SNA address type

RUNRMTCMD CMD('dir') RMTLOCNAME((APPN.RMTSYS *SNA))

This command runs the 'dir' command on the system specified by 'RMTLOCNAME' using an SNA address type.

Example 2: Run Remote Command (AREXEC) using SNA address type

 
    AREXEC CMD('dir') RMTLOCNAME(APPN.RMTSYS)

This command is equivalent to the command in example 1.

Example 3: Run Remote Command Using IP Address Type and Host Name to Specify Target System

RUNRMTCMD CMD('ls') RMTLOCNAME((MYSYS.NET1.LOCAL *IP))

This command runs the 'ls' command on the system specified by host name MYSYS.NET1.LOCAL.

Example 4: Run Remote Command Using IP Address Type and Internet Address to Specify Target System

RUNRMTCMD CMD('ls') RMTLOCNAME(('9.5.1.94' *IP))

This command runs the 'ls' command on the system specified by Internet address '9.5.1.94'.

Example 5: Run Remote Command With Multiple Commands Using IP Address Type and Internet Address to Specify Target System

RUNRMTCMD CMD('ls; cat myfile; date')
RMTLOCNAME(('9.5.1.94' *IP))

This command runs multiple commands, first 'ls', then 'cat myfile', then 'date' on system specified by Internet address '9.5.1.94'.

Example 6: Run Remote Command With a Wait Time Expiration Value

                                                                  
RUNRMTCMD CMD('dir') RMTLOCNAME((APPN.RMTSYS *SNA)) WAITTIME(15)        

This command runs the 'dir' command on the specified system. The maximum wait time for the remote location to respond is 15 seconds. Only allowed using *SNA address type value.

Error messages for RUNRMTCMD

*ESCAPE Messages

CPF91CB

Problems occurred on the command, but the command completed.

CPF91CC

Command did not complete successfully.

CPF91CF

Command failed on remote system.

CPF91C9

MODE value not allowed when *IP specified for RMTLOCNAME address type.