QCMDEXC program

The Execute Command (QCMDEXC) API is an IBM-supplied program that runs a single command.

This API is used to activate another command:

From within a high-level language (HLL) program.
From within a CL procedure.
From a program where it is not known at compile time what command is to be run or what parameters are to be used.

The QCMDEXC program is called from within the HLL or CL procedure or program. The command that is to be run is passed as a parameter on the CALL command.

After the command runs, control returns to your HLL or CL procedure or program.

The command runs as if it was not in a program. Therefore, variables cannot be used on the command because values cannot be returned by the command to CL variables. Additionally, commands that can only be used in CL procedures or programs cannot be run by the QCMDEXC program. The format of the call to the QCMDEXC program is the following:


CALL PGM(QCMDEXC) PARM(command command-length)

Enter the command you want to run as a character string on the first parameter. You must specify the command library.


CALL PGM(QCMDEXC )  PARM('QSYS/CRTLIB LIB(TEST)' 22)

Remember that you must enclose the command in single quotation marks if it contains blanks. The maximum length of the character string is 32,702 characters; never count the delimiters (the single quotation marks ) as part of the string. The length that is specified as the second value on the PARM parameter is the length of the character string that is passed as the command. Length must be a packed decimal value of length 15 with 5 decimal positions.

Thus, to replace a library list, the call to the QCMDEXC program would look like this:


CALL PGM(QCMDEXC) PARM('CHGLIBL LIBL(QGPL NEWLIB QTEMP)' 31)

It is possible to code this statement into the HLL or CL program to replace the library list when the program runs. The QCMDEXC program does not provide runtime flexibility when used this way.

Providing runtime flexibility is accomplished by:

Substituting variables for the constants in the parameter list, and
Specifying the values for the variables in the call to the HLL or CL program.

For instance, examine the following figure.

Example of Call PGM — Figure 1. Example of call PGM

The command length, passed to the QCMDEXC program on the second parameter, is the maximum length of the passed command string. Should the command string be passed as a quoted string, the command length is exactly the length of the quoted string. Should the command string be passed in a variable, the command length is the length of the CL variable. It is not necessary to reduce the command length to the actual length of the command string in the variable, although it is permissible to do so.

Not all commands can be run using the QCMDEXC program. The command passed on a call to the QCMDEXC program must be valid within the current environment (interactive or batch) in which the call is being made. The command cannot be one of the following:

An input stream control command (BCHJOB, ENDBCHJOB, and DATA)
A command that can be used only in a CL program

You can precede the CL command with a question mark (?) to request prompting or use selective prompting when you call QCMDEXC in an interactive job.

If an error is detected while a command is being processed through the QCMDEXC program, an escape message is sent. You can monitor for this escape message in your CL procedure or program using the Monitor Message (MONMSG) command.

If a syntax error is detected, message CPF0006 is sent. If an error is detected during the processing of a command, any escape message sent by the command is returned by the QCMDEXC program. You monitor for messages from commands run through the QCMDEXC program in the same way you monitor for messages from commands contained in CL procedures and programs.

See the appropriate high-level language reference book for information about how high-level language programs handle errors on calls.