Execute Command (QCMDEXC) API


  Required Parameter Group:

1 Command string Input Char(*)
2 Length of command string Input Packed (15,5)

  Optional Parameter:

3 IGC process control INPUT Char(3)

  Default Public Authority: *USE

  Threadsafe: Yes.

   See Usage Notes for command considerations.

The Execute Command (QCMDEXC) API runs a single command. It is used to run a command from within a high-level language (HLL) program or from within a CL program where it is not known at compile time what command is to be run or what parameters are to be used.

QCMDEXC is called from within your HLL program and the command it runs is passed to it as a parameter on the CALL command.

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

Notes:

  1. Command strings in System/38™ syntax can use the QCAEXEC API. The QCAEXEC API accepts the same parameters as QCMDEXC.
  2. The Process Commands (QCAPCMD) API also provides similar functions.
  3. If the command to be executed is a proxy command, the QCMDEXC API will resolve to the target command. If the target command is also a proxy, the process repeats until either a non-proxy command is found, or the proxy chain becomes greater than the allowed maximum. Once a non-proxy command is found, the resolved command will replace the proxy command in the command string to be executed.
  4. Proxy commands will be resolved before the command exit points QIBM_QCA_CHG_COMMAND and QIBM_QCA_RTV_COMMAND are called.


Authorities and Locks

Any Command
*USE

Required Parameter Group

Command string
INPUT;CHAR(*)

The command you want to run entered as a character string. If the command contains blanks, it must be enclosed in apostrophes. The maximum length of the character string is 32,702 characters; delimiters (the apostrophes enclosing the string) are not counted as part of the string.

Length of command string
INPUT;PACKED(15,5)

The maximum length being passed. If the command string is passed as a quoted string, the command length is exactly the length of the quoted string. If the command string is passed in a variable, the command length is the length of the 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.


Optional Parameter Group

IGC process control
INPUT;CHAR(3)

The IGC process control instructs the system to accept double-byte data. The only value supported is IGC. IGC must be entered using all uppercase letters.


Usage Notes

While this API is threadsafe, it should not be used to run a command that is not threadsafe in a job that has multiple threads. Use the Display Command (DSPCMD) command to determine whether a command is threadsafe.


Error Messages

Message ID Error Message Text
CPF0005 E Returned command string exceeds variable provided length
CPF0006 E Errors occurred in command.
CPF3C90 E Literal value cannot be changed.
CPF9872 E Program or service program &1 in library &2 ended. Reason code &3.
xxxnnnn E Any escape message issued by any command may be returned. The messages listed previously are those issued by this API. Once the API has called the command analyzer, any message issued as an escape message may appear.

API in existance prior to V1R3

[ Back to top | Program and CL Command APIs | APIs by category ]