INCLUDE-CMD Call command sequence from program

Domain: PROCEDURE

Command description

The INCLUDE-CMD command is used to include a command or command sequence from a program for execution. The command can be executed only in the CMD macro (TU program) and in EXECUTE-SYSTEM-CMD statements.

You should make a note of the following: during execution of INCLUDE-CMD, the system rejects a number of operations, such as program start, restart and termination, in order to avoid possible inconsistencies since the command is called in program mode (see notes below for more details).

Output of the command to SYSOUT is divided into two parts:

• Output of the result of the analysis of the INCLUDE-CMD command: this can be saved in the SYSOUT buffer of the CMD macro (error report or other types of information).

• Output of command execution currently contained in SYSOUT: it is independent of the CMD call parameter.
  Output of this command to SYSOUT can be influenced by means of the ASSIGN-SYSOUT command provided ASSIGN-SYSOUT is contained in the command list specified with CMD=... . .

Format

INCLUDE-CMD                                    Alias: INCMD

CMD = <text 0..1800 with-low>

Operands

CMD = <text 0...1800 with-low>
Command or command sequence to be executed. Commands in a sequence must be separated by semicolons and must be enclosed in parentheses. A leading slash (/) is not permitted.

Execution of the command list specified in the CMD operand is identical to execution of an include procedure containing the same commands, albeit with certain restrictions:

• Commands normally specified in the procedure head must not be specified in the CMD operand. The commands SET-PROCEDURE-OPTIONS, BEGIN-PARAMETER-DECLARATION, END-PARAMETER-DECLARATION and DECLARE-PARAMETER will therefore be rejected.

• The default values for the logging options apply. These can be modified with MODIFY-PROCEDURE-OPTIONS.

• If the EXIT-PROCEDURE command was specified in the command list for CMD (at the top level), INCLUDE-CMD ends with this command. No subsequent commands are executed.

• The commands DO, ENDP, END-PROCEDURE, ENDP-RESUME cannot be specified in the command sequence in the CMD operand.

• If INCLUDE-CMD is specified in a list of command inputs in the buffer of the CMD macro, any subsequent commands are ignored.
  Example: CMD ’cmd1;cmd2;INCLUDE-CMD CMD=(PRINT-DOCUMENT X);cmd3’The input “cmd3” in this example is ignored and is therefore superfluous.

Notes

• The commands specified in the CMD operand are executed in the same manner as input in an S procedure called with INCLUDE-PROCEDURE. They have implicit access to the variables of the current procedure level (just as if they had been called with INCLUDE-PROCEDURE and as if they inherited the system files of the current procedure level (SYSTEM-FILE-CONTEXT=*STD).

• In contrast to INCLUDE-PROCEDURE, INCLUDE-CMD does not terminate a program when it was called by the CMD macro. The program is also not terminated when a procedure is called in the command sequence that is specified in the CMD operand (see the example).

• INCLUDE-CMD may be executed in the CMD macro (TU program) and also in EXECUTE-SYTEM-CMD statements.

• During execution of INCLUDE-CMD, the system rejects the following operations in order to avoid possible inconsistencies since the command is called in program mode:

  • Start and terminate program: START utility, LOAD-/START-EXECUTABLE-PROGRAM (or LOAD-/START-PROGRAM), RESTART-PROGRAM (see CALL-PROCEDURE ...UNLOAD-ALLOWED=*NO).

  • Resume program: AID commands, RESUME-PROGRAM, EXIT-PROCEDURE RESUME-PROGRAM=*YES, ENDP-RESUME, INFORM-PROGRAM, SEND-MSG with TO=*PROGRAM.

  • Abort procedure: CANCEL-PROCEDURE, when prompted for parameters.

  • Call INCLUDE-CMD recursively.

  • BEGIN-BLOCK PROGRAM-INPUT=*MIXED-WITH-CMD

  • SET-JOB-STEP if a program is loaded.

Command return codes

(SC2)	SC1	Maincode	Meaning
	0	CMD0001	No error
	1	CMD0202	Syntax error
	1	SDP0138	Error during procedure preanalysis
	3	CMD2203	Incorrect syntax file
	32	CMD0221	System error (internal error)
	64	SDP0091	Semantic error
	130	SDP0099	No further address space available

Example

CMD 'INCLUDE-CMD CMD=(DECLARE-VARIABLE A; 
                       CALL-PROCEDURE MYPROC,(RET=A); 
                       IF(A = ''OKAY'');
                       WRITE-TEXT ''SUCCESSFULL''
                       ELSE
                       WRITE-TEXT ''ERROR''
                       END-IF)'
"RETURN TO PROGRAM MODE"