Note on usage
Function: Execute remote command
User group: FT user
Alias name: FTEXEC
Functional description
With the EXECUTE-REMOTE-CMD command, you can execute operating system commands in the remote system. In the local system, the resulting standard and standard error output can be sent to *SYSLST, *SYSOUT or to a file.
EXECUTE-REMOTE-CMD is only available for openFT partners and FTAM partners from Fujitsu Technology Solutions.
The exit code, i.e. the result of the command is output in the local system as subcode 2 of the EXECUTE-REMOTE-CMD command. If the received exit code exceeds the value range of the local exit code (BS2000 systems only have a 1-byte exit code whereas Windows systems have 4-byte exit codes), then the content of the lower-order byte is output.
If the command is not executed in the remote system then a transfer command exit code is output at STDOUT and EXECUTE-REMOTE-CMD terminates with exit code 255. The meaning of the exit code is system-specific.
In the case of output to *SYSLST, it is possible to specify character sets.
In the case of output to *SYSOUT, the character set specified in the local system is used.
Format
EXECUTE-REMOTE-CMD / FTEXEC |
PARTNER = <text 1..200 with-low> ,CMD= *NOT-SPECIFIED / <c-string 1..400 with-low> (...) CODED-CHARACTER-SET = *STD / <name 1..8> ,TRANSFER-ADMISSION = *NONE / <alphanum-name 8..32> / <c-string 8..32 with-low> / <x-string 15..64> / *SECRET / *PARAMETERS(...) *PARAMETERS(...) USER-IDENTIFICATION = <name 1..8> / <c-string 1..67 with-low> ,ACCOUNT = *NONE / <c-string 1..64 with-low> / <text 1..64> ,PASSWORD = *NONE / <c-string 1..64 with-low> / <x-string 1..128> / <alphanum-name 1..19> / *SECRET ,OUTPUT = *SYSOUT / *SYSLST / *FILE(...) *FILE(...) FILE-NAME = <filename 1..54> ,CODED-CHARACTER-SET = *STD / <alphanum-name 1..8> ,DATA-TYPE = *CHAR ACTER / *BINARY ,DATA-ENCRYPTION = *NO / *YES ,FILE-NAME-ENCODING = *TRANSPARENT / *CHARACTER |
Operands
PARTNER = <text 1..200 with-low>
Name of the partner system as defined in the partner list by the FT administrator or the partner system address. For more information on address specifications, see section “Specifying partner addresses”.
CMD =
Command in the syntax of the remote FT partner system. A command sequence in the remote system can only be processed if the remote system is using an FT product that supports this function.
CMD = *NOT-SPECIFIED
No command string is passed. *NOT-SPECIFIED must be used if an admission profile is specified in TRANSFER-ADMISSION for which a command sequence has been preset.
CMD = <c-string 1..400 with-low>
Command sequence. This command sequence may be a maximum of 400 characters in length, with special characters being counted double (as two characters).
CODED-CHARACTER-SET =
Coding (character set) to be used when reading the data from the standard output of the remote command.
CODED-CHARACTER-SET = *STD
The character set defined as standard in the remote system is used.
CODED-CHARACTER-SET = <name 1..8>
The specified character set (CCS) is used. This must be known in the remote system. This specification must not be combined with DATA-TYPE=*BIN.
TRANSFER-ADMISSION =
Contains specifications about the transfer admission in the remote system.
TRANSFER-ADMISSION = *NONE
The remote system does not require or does not know any user admissions.
TRANSFER-ADMISSION = <alphanum-name 8..32> / <c-string 8..32 with-low> / <x-string 15..64>
If FTAC functionality is used in the remote system then the transfer admission for the remote system can be defined via an admission profile. In this case, only the TRANSFER-ADMISSION defined in the admission profile is used here. In the case of alphanumeric input, uppercase is converted to lowercase internally.
TRANSFER-ADMISSION = *SECRET
The system prompts you to input the transfer admission. However, this is not visible on the screen.
TRANSFER-ADMISSION = *PARAMETERS(...)
Specifies the user's identification, account number and password in the remote system. The operands in the brackets can also be used as positional operands without the associated keywords.
USER-IDENTIFICATION = <name 1..8> / <c-string 1..67 with-low>
Identification of the user in the remote system. The identification must be specified in the syntax of the remote system and must adhere to the conventions used in the remote system.
ACCOUNT = *NONE / <c-string 1..64 with-low> / <text 1..64>
Account number of the user in the remote system. The account number must be specified in the syntax of the remote system and must adhere to the conventions used in the remote system.
PASSWORD =
Password allowing the user to access the remote system.
PASSWORD = *NONE
Access is possible without a password.
PASSWORD = <c-string 1..64 with-low> / <x-string 1..128> / <alphanum-name 1..19>
Password allowing the user to access the remote system. The password must be specified in the syntax of the remote system, must adhere to the conventions used in the remote system and must be known there.
PASSWORD = *SECRET
The system prompts you to enter the password. However, your input is not displayed on the screen.
OUTPUT =
Specifies where the data generated by the command should be output following transfer in the local system.
If the partner is a BS2000 system, output to SYSLST from the remote command is redirected to the channel specified here. Output to SYSOUT is always shown locally on SYSOUT.
OUTPUT = *SYSOUT
The data is written to *SYSOUT.
OUTPUT = *SYSLST
The data is written to *SYSLST.
OUTPUT = *FILE(...)
The data is written to a file. Please note that only the data which the command specified with CMD outputs to *SYSLST (BS2000) or *STDOUT (on z/OS) or stdout (on a Unix/Windows system) is written to file.
FILE-NAME = <filename 1..54>
Name of the output file.
CODED-CHARACTER-SET =
Coding (character set) that is to be used to write the data.
CODED-CHARACTER-SET = *STD
The character set predefined by XHCS is used.
CODED-CHARACTER-SET = <alphanum-name 1..8>
Name of the character set (CCS) that is to be used. This character set must be known in the local system.
This specification must not be combined with DATA-TYPE=*BIN.
DATA-TYPE =
Transfer format for the data.
DATA-TYPE = *CHARACTER
The data is transferred as a text file.
DATA-TYPE = *BINARY
The data is transferred in binary form.
DATA-ENCRYPTION =
Specifies whether the data is to be transferred in encrypted form. The encryption of the request description data is not affected by this operand.
DATA-ENCRYPTION = *NO
The data is transferred unencrypted.
DATA-ENCRYPTION = *YES
The data is transferred encrypted.
FILE-NAME-ENCODING =
Specifies the encoding mode for the commands to be executed in the remote system.
FILE-NAME-ENCODING = *TRANSPARENT
Specification of the commands to be executed in the remote system in transparent mode (compatible to the previous versions).
FILE-NAME-ENCODING = *CHARACTER
Specification of the commands to be executed in the remote system in character mode. The commands are interpreted according to the character code of the remote system, i.e. for Unix partners according to the openFT operating parameter option (ftmodo -fnccs) that has been set there.
FILE-NAME-ENCODING=*CHARACTER is only permitted for openFT partners as of openFT V12.1.
Command return codes
(SC2) | SC1 | Maincode | Meaning/Guaranteed messages |
108 | 128 | FTR0108 | Request rejected. Remote system not accessible. |
4 | 1 | CMD0202 | The selected parameters could not be specified simultaneously. |
33 | 32 | CMD0221 | Request rejected. Internal error. |
36 | 32 | CMD0221 | Request rejected. Inconsistent request data. |
83 | 32 | CMD0221 | Internal error. |
51 | 64 | FTR2051 | Encryption not possible for this request. |
125 | 128 | FTR2125 | Request rejected. Transport connection lost. |
169 | 64 | FTR2169 | Request rejected. Remote system: Transfer admission invalid. |
170 | 64 | FTR2170 | Request rejected. Remote system: Function not supported. |
rc | 64 | FTR2207 | The command returned an error in the remote system. The |
SC1/2 = subcode 1/2 in decimal format For additional information refer to the section “Command return codes”. | |||
Examples
The partner is a BS2000 system, output to the local file ex.out:
FTEXEC BS2PART,'/SH-FT-LOG ,3 ,OUTPUT=SYSLST',(userId,acct,'passw'),OUTPUT=*FILE(ex.out),DATA-TYPE=*CHARThe partner is a Unix system, output to *STDOUT:
FTEXEC PARTUX,'ftshwl -nb=10',uxtransadm,,*CHAR