CL Programming

Procedure for Using Prompt Override Programs

To use a prompt override program, do the following:

  1. Specify any parameters that are to be key parameters on the PARM statement in the command definition source. For information about the KEYPARM parameter, see the following section, Identifying Key Parameters.
  2. Write a prompt override program. For information about creating prompt override programs, see Writing a Prompt Override Program.
  3. Specify the name of the prompt override program on the PMTOVRPGM parameter when you create or change the command. For information about creating or changing commands that use the prompt override program, see Specifying the Prompt Override Program When Creating or Changing Commands.

Identifying Key Parameters

The number of key parameters should be limited to the number of parameters needed to uniquely define the object to be changed.

To ensure a key parameter is coded correctly in the command definition source, do the following:

Writing a Prompt Override Program

A prompt override program needs to be passed certain information to return current values when a command is prompted. You must consider both the passed information and the returned values when you write a prompt override program.

For an example of CL source for a prompt override program, see CL Sample for Using the Prompt Override Program.

Parameters Passed to the Prompt Override Program

The prompt override program is passed the following parameters:

Information Returned from the Prompt Override Program

Based on the values passed, the prompt override program retrieves the current values for the parameters that are not key parameters. These values are placed into a command string, where the length of the string is determined and returned.

Use the following guidelines to ensure your command string is correctly defined:

Some commands can only be run in certain modes (such as DEBUG) or job status (such as *BATCH) but can still be prompted for from other modes or job statuses. When the command is prompted, the prompt override program is called regardless of the user's environment. If the prompt override program is called in a mode or environment that is not valid for the command, the defaults are displayed for the command and a value of 0 is returned for the length. Using the debug commands Change Debug (CHGDBG) and Add Program (ADDPGM) when not in debug mode are examples of this condition.

Allowing for Errors in a Prompt Override Program

If the prompt override program detects an error, it should do the following:

For example, if you need a message saying that a library does not exist, add a message description similar to the following:

ADDMSGD      MSG('Library &2 does not exist') +
             MSGID(USR0012) +
             MSGF(QGPL/ACTMSG) +
             SEV(40) +
             FMT((*CHAR 4) (*CHAR 10))
Note:
The substitution variable &1 is not in the message but is defined in the FMT parameter as 4 characters. &1 is reserved for use by the system and must always be 4 characters. If the substitution variable &1 is the only substitution variable defined in the message, you must ensure that the fourth byte of the message data does not contain a blank when you send the message. The fourth byte is used by the system to manage messages during command processing and prompting.

This message can be sent to the calling program of the prompt override program by specifying the following in the prompt override program:

SNDPGMMSG    MSGID(USR0012) MSGF(QGPL/ACTMSG) +
             MSGDTA('0000' || &libname) MSGTYPE(*DIAG)

After the prompt override program sends all the necessary diagnostic messages, it should then send message CPF0011. To send message CPF0011, use the Send Program Message (SNDPGMMSG) command as follows:

SNDPGMMSG    MSGID(CPF0011) MSGF(QCPFMSG) +
             MSGTYPE(*ESCAPE)

When message CPF0011 is received, message CPD680A is sent to the calling program and displayed on the prompt screen to indicate that errors have been found. All diagnostic messages are placed in the user's job log.

Specifying the Prompt Override Program When Creating or Changing Commands

To use a prompt override program for a command you want to create, specify the program name when you use the Create Command (CRTCMD) command. You can also specify the program name when you change the command using the Change Command (CHGCMD) command. For both commands, specify the name of the prompt override program on the PMTOVRPGM parameter.

If key parameters are defined in the command definition source but the prompt override program is not specified when the command is created or changed, warning message CPD029B results. The key parameters are ignored, and when the command is prompted, it is displayed using the defaults specified in the command definition source.

Sometimes a prompt override program is specified when a command is created but when no key parameters are defined in the command definition source. In these cases, the prompt override program is called before the command is prompted; informational message CPD029A is sent when the command is created or changed.


[ Top of Page | Previous Page | Next Page | Table of Contents | Index ]