Domain: PROCEDURE
Command description
The EXECUTE-CMD command passes the command specified with the operand CMD=… on for execution and writes the command output (messages, output information) to a specified variable. Both structured and unstructured output can be generated, depending on the capabilities of the command server. The reaction to errors occurring in command execution can be controlled by evaluation of the return code, which can be assigned to a variable.
Most SHOW commands supply structured outputs. The output structures are described in in the manual “Commands” [3] or in the relevant product manual.
Guaranteed messages can be rerouted to variables as structured output.
Notes
Commands such as LOAD-/START-EXECUTABLE-PROGRAM (or LOAD-/START-PROGRAM), and similar ones, should not be specified with EXECUTE-CMD. If such commands are nevertheless specified, then all the operands of /EXECUTE-CMD will be ignored, and error message SDP0229 will be returned. The commands will then be executed as though outside EXECUTE-CMD.
EXECUTE-CMD cannot be used to execute AID commands.
Format
EXECUTE-CMD |
CMD = <c-string 0..1800 with-low> / <text 0..1800 with-low> ,TEXT-OUTPUT = *SYSOUT / *NONE / <composed-name 1..255>(...) <composed-name 1..255>(...) WRITE-MODE = *REPLACE / *EXTEND ,STRUCTURE-OUTPUT = *NONE / <composed-name 1..255>(...) <composed-name 1..255>(...) WRITE-MODE = *REPLACE / *EXTEND ,MSG-STRUCTURE-OUTPUT = *NONE / <composed-name 1..255>(...) <composed-name 1..255>(...) WRITE-MODE = *REPLACE / *EXTEND / ,RETURNCODE = *STD / *NONE / *VARIABLE(...) *VARIABLE(...) SUBCODE1 = *NONE / <composed-name 1..255> ,SUBCODE2 = *NONE / <composed-name 1..255> ,MAINCODE = *NONE / <composed-name 1..255> |
Operands
CMD = <c-string 0..1800 with-low> / <text 0...1800 with-low>
Command to be executed (enclosed in parentheses and without a slash).
TEXT-OUTPUT =
Output in the form of a text string. If the command to be executed is implemented by a
TU (Task Unprivileged) program or by a procedure, it is not possible to ignore the SYSOUT outputs or to reroute them into a variable.
TEXT-OUTPUT = *SYSOUT
Output to SYSOUT.
TEXT-OUTPUT = *NONE
Unstructured output is not to take place.
TEXT-OUTPUT = <composed-name 1..255> (...)
Output to a list variable. Designates the list variable to which output is to take place; the list variable must be declared with MULTIPLE-ELEMENTS = *LIST in the DECLARE-
VARIABLE command. An output line of the SYSOUT layout thus corresponds to a list element. The SYSOUT layout is version-dependent and can therefore not be guaranteed.
WRITE-MODE = *REPLACE / *EXTEND
Specifies whether the list is to be overwritten or extended. *REPLACE means that the list is overwritten.
STRUCTURE-OUTPUT =
Structured output with messages.
No error message is returned if STRUCTURE-OUTPUT is specified for a command that cannot produce structured output, with the exception of the commands SHOW-USER-STATUS and SHOW-SYSTEM-STATUS.
STRUCTURE-OUTPUT = *NONE
No structured output is to be generated. This also excludes structured output to an
S variable stream for the specified command, irrespective of any assignment made with the ASSIGN-STREAM command.
STRUCTURE-OUTPUT = <composed-name 1.255> (...)
Name of the variable into which the structured output is to be made. This variable must be declared as a list variable (MULTIPLE-ELEMENTS = *LIST in the DECLARE-VARIABLE command).
WRITE-MODE = *REPLACE / *EXTEND
Specifies whether the list is to be overwritten or extended.*REPLACE means that the list is overwritten.
MSG-STRUCTURE-OUTPUT =Structured output of the messages.
MSG-STRUCTURE-OUTPUT = *NONE
No structured output is to be generated. This also excludes structured output to an
S variable stream for the specified command, irrespective of any assignment made with the ASSIGN-STREAM command.
MSG-STRUCTURE-OUTPUT = <composed-name 1..255>(...)
Name of the variable into which the structured message output is to be made. This variable must be declared as a list variable (MULTIPLE-ELEMENTS = *LIST in the DECLARE-VARIABLE command).
For further details, see section “Structured output in S variables”.
WRITE-MODE = *REPLACE / *EXTEND
Specifies whether the list is overwritten or extended.If *REPLACE is specified, the list is overwritten.
RETURNCODE =
This operand is only evaluated if EXECUTE-CMD succeeds in executing the specified command. In this case it specifies how the result (i.e. the command return code and the spin-off indicator) of the executed command is handled.
RETURNCODE = *STD
EXECUTE-CMD discards its own, successful result. Instead, it returns the result of the executed command.
RETURNCODE = *NONE
EXECUTE-CMD returns its own, successful result. The result of the executed command is discarded.
RETURNCODE = *VARIABLE(...)
EXECUTE-CMD returns its own, successful result. The command return code of the executed command is stored in the specified variables, its spin-off indicator is discarded.
SUBCODE1 = *NONE / <composed-name 1..255>
Designates a variable in which subcode1 is output
(subcode1 = error class).
The variable must be declared with TYPE = *ANY or TYPE = *INTEGER.
SUBCODE2 = *NONE / <composed-name 1..255>
Designates a variable in which subcode2 is output
(subcode2 = additional information on subcode1).
The variable must be declared with TYPE = *ANY or TYPE = *INTEGER.
MAINCODE = *NONE / <composed-name 1..255>
Designates a variable in which the error code is output
(maincode = error code).
The variable must be declared with TYPE = *ANY or TYPE = *STRING.
Note
The default value for STRUCTURE-OUTPUT and MSG-STRUCTURE-OUTPUT is in each case *NONE. This means that if these operands are not explicitly specified in an EXECUTE-CMD command, or if this value is assigned to them, no variables will be written to SYSINF and/or SYSMSG, even if an ASSIGN-STREAM command was used to assign a destination to these streams before EXECUTE-CMD was issued. This is because any such assignment is overwritten by “*NONE” (i.e. with a *DUMMY value) as part of the EXECUTE-CMD command.
Command return codes
The return codes depend on the setting of the RETURNCODE operand.
The following return codes are possible if RETURNCODE = *STD:
(SC2) | SC1 | Maincode | Meaning |
| 0 | CMD0001 | No error | |
| 1 | CMD0202 | Syntax error | |
| 3 | CMD2203 | Incorrect syntax file | |
| 32 | CMD0221 | System error (internal error) | |
| 64 | SDP0091 | Semantic error | |
| 130 | SDP0099 | No further address space available | |
| xx | xx | xxxxxxx | other return codes from the executed commands |
The following return codes are possible if RETURNCODE = *NONE / *VARIABLE(...):
(SC2) | SC1 | Maincode | Meaning |
| 0 | CMD0001 | No error (but only in EXECUTE-CMD) | |
| 1 | CMD0202 | Syntax error | |
| 3 | CMD2203 | Incorrect syntax file | |
| 32 | CMD0221 | System error (internal error) | |
| 64 | SDP0091 | Semantic error | |
| 130 | SDP0099 | No further address space available |