Some application programming interface programs can be used with commands.

QCAPCMD program

The Process Commands (QCAPCMD) API performs command analyzer processing on command strings. You can use this API to do the following:

• Check the syntax of a command string before running it.
• Prompt the command and receive the changed command string.
• Use a command from a high-level language.
• Display the help for a command.

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)

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)

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.

QCMDEXC program with DBCS data:

You can use the Execute Command (QCMDEXC) API to request double-byte character set (DBCS) input data to be entered with a command.

The command format used for QCMDEXC to prompt double-byte data is:

CALL QCMDEXC (’command’ command-length IGC)

The third parameter of the QCMDEXC program, IGC, instructs the system to accept double-byte data. For example, the following CL program asks a user to provide double-byte text for a message. Then the system sends the following message:

PGM
CALL QCMDEXC (’?SNDMSG’ 7 IGC)
ENDPGM

An explanation of the system message follows:

• The ? character instructs the system to present the command prompt for the Send Message (SNDMSG) command.
• The value 7 is the length of the Send Message (SNDMSG) command plus the question mark.
• The value IGC allows you to request double-byte data.

The following display is shown after running the QCMDEXC program. You can use double-byte conversion on this display:

QCMDCHK program

The Check Command Syntax (QCMDCHK) API is an IBM-supplied program that performs syntax checking for a single command, and optionally prompts for the command.

The command is not run. If prompting is requested, the command string is returned to the calling procedure or program with the updated values as entered through prompting.

The QCMDCHK program can be called from a CL procedure or program or an HLL procedure or program.

Typical uses of QCMDCHK are:

• Prompt the user for a command and then store the command for later processing.
• Determine the options the user specified.
• Log the processed command.

First, prompt with QCMDCHK, run with QCMDEXC, and then log the processed command. The format of the call to QCMDCHK is:

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

The first parameter passed to QCMDCHK is a character string containing the command to be checked or prompted. If the first parameter is a variable and prompting is requested, the command entered by the workstation user is placed in the variable.

The second parameter is the maximum length of the command string being passed.

In the following example, control is passed to the label ERROR within the program, because the value 123 is not valid for the PGM parameter of the Create CL Program (CRTCLPGM) command.

CALL QCMDCHK (’CRTCLPGM PGM(QGPL/123)’ 22) MONMSG CPF0006 EXEC(GOTO ERROR)

If no errors are detected during checking and prompting for the command, the updated command string is placed in the variable specified for the first parameter. The prompt request characters are removed from the command string.

This is shown in the following example:

DCL &CMD *CHAR 2000
.
.
CHGVAR &CMD ’?CRTCLPGM’
CALL QCMDCHK (&CMD 2000)

After the call to the QCMDCHK program is run, variable &CMD contains the command string with all values entered through the prompter. This might be something like:

CRTCLPGM PGM(PGMA) SRCFILE(TESTLIB/SOURCE) USRPRF(*OWNER)

Note that the question mark preceding the command name is removed.

Prompting for user input at run time

With most CL programs and procedures, the workstation user provides input by specifying command parameter values that are passed to the program or by typing into input-capable fields on a display prompt.

You can prompt the workstation user for input to a CL procedure or program in the following ways:

• If you enter a ? before the CL command in the CL source program, the system displays a prompt for the CL command. Parameter values you have already specified in your source program are filled in and cannot be changed by the workstation user.
• If you call the QCMDEXC program and request selective prompting, the system displays a prompt for a CL command, but you need not specify in the CL source program which CL command is to be used at processing time.

Using the IBM i prompter within a CL procedure or program

You can request prompting within the interactive processing of a CL procedure or program.

For example, the following procedure can be compiled and run:

PGM
.
.
.
?DSPLIB
.
.
.
ENDPGM

In this case, the prompt for the Display Library (DSPLIB) command appears on the display during processing of the program. Processing of the Display Library (DSPLIB) command waits until you have entered values for required parameters and pressed the Enter key.

Any values specified in the source program cannot be changed directly by the operator (or user). For example:

PGM
.
.
.
?SNDMSG TOMSGQ(WS01 WS02)
.
.
.
ENDPGM

When the procedure is called and the prompt for the Send Message (SNDMSG) command appears, the operator (or user) can enter values on the MSG, MSGTYPE, and RPYMSGQ parameters, but cannot alter the values on the TOMSGQ parameter. For example, the operator (or user) cannot add WS03 or delete WS02.

Prompting cannot be used in batch jobs.

Using selective prompting for CL commands

Selective prompting for CL commands is especially helpful when you are using some of the longer commands and do not want to be prompted for certain parameters.

Selective prompting can be used during interactive prompting or entered as source (in SEU) for use within a CL procedure or program.

You can enter the source for selective prompting with SEU but you cannot use selective prompting while entering commands in SEU.

The following restrictions apply to selective prompting:

– The command name or label must be preceded by a ? (question mark):

– When one or more of the selective prompt options is ?- (question mark, minus).

If a CL procedure contains the following:

OVRDBF ?*FILE(FILEA) ??TOFILE(&FILENAME) ??MBR(MBR1)

the three parameters, FILE, TOFILE, and MBR is shown on the prompt display. 

The value specified for the FILE parameter cannot be changed by you, but the values for the TOFILE and MBR parameters can be changed. Assume that the CL variable &FILENAME has a value of FILE1, and you change it to FILE2.

call TEST

Using QCMDEXC with prompting in CL procedures and programs

The Execute Command (QCMDEXC) program can be used to call the prompter. This use of QCMDEXC with prompting in CL procedures and programs allows you to alter all values on the command except the command name itself.

This is more flexible than direct use of the prompter, where you can only enter values not specified in the source (see previous section). If the prompter is called directly with a command such as:

?OVRDBF FILE(FILEX)

you can specify a value for any parameter except FILE. However, if the command is called during processing of a program using the QCMDEXC program, such as in the following example, you can specify a value for any parameter, including FILE. In this example, FILEX is the default.:

CALL QCMDEXC PARM(’?OVRDBF FILE(FILEX)’ 19)