To use a prompt override program, do the following:
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:
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.
The prompt override program is passed the following parameters:
For example, when defining two key parameters for a command, four parameters pass to the prompt override program as follows:
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:
When using selective prompts, do the following:
The following example shows a command string returned from a prompt override program:
??Number(123456) ?<Qualifier(CLIB/CFILE) ?<LIST(ITEM1 ITEM2 ITEM3) ?<TEXT('Carol's file')
For example, a keyword has a special value defined as SPCVAL(*SPECIAL *) in the command definition source. *SPECIAL is the from-value and * is the to-value. When the current value is retrieved for this keyword, * is the value retrieved, but *SPECIAL must appear in the command string returned from the prompt override program. The correct from-value must be placed into the command string since more than one special value or single value can have the same to-value. For example, if KWD1 SPCVAL((*SPC *) (*SPECIAL *)) is specified, the prompt override program must determine whether * is the to-value for *SPC or *SPECIAL.
(2*(field length defined in command definition source)) + 2
This length allows for the maximum number of quotation marks allowed in the text field. For example, if the TEXT parameter on the CHGxxx command is defined in the command definition source as LEN(50), then the parameter is declared as CHAR(102) in its prompt override program. For an example of how to define the length of fields used to retrieve text, see CL Sample for Using the Prompt Override Program.
If the parameter for a text field is not correctly defined in the prompt override program and the text string retrieved by the prompt override program contains a quote, the command does not prompt correctly.
?<TEXT('Carol''s library')
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.
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))
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.
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.
(C) Copyright IBM Corporation 1992, 2005. All Rights Reserved.