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:
- Use the keyword format for the command string just as you would on the command line.
- Do not include the command name and the key parameters in the command string.
- Precede each keyword with a selective prompt character to define how to
display the parameter and what value to pass to the CPP.
When using selective prompts, do the following:
- If a parameter is defined as MIN(1) in the command definition source (that is, the parameter is required), you must use the ?? selective prompt character for that keyword in the command string from the prompt override program.
- Do not use the ?- selective prompt character in the prompt override program command string.
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') - Make sure that the specified value in the first two bytes of the space
the program passes is the actual hexadecimal length of the command string.
- Include only the parameters in the command string whose current values you want displayed when the command is prompted. Parameters not included in the command string have their defaults displayed.
- Use character form for any numbers that appear in the command string. Do not use binary or packed form. Do not include any hexadecimal numbers in the command string.
- Do not put blank spaces between the library and the qualifier or the qualifier
and the object. For example:
- ??KWD1(library /object)
- Not valid
- ??KWD1(library/ object)
- Not valid
- ??KWD1(library/object)
- Valid
- ??KWD1( library/object )
- Valid
- If you use special values or single values, make sure they are translated
into the from-value defined in the command definition source.
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.
- Define the length of fields used to retrieve text as follows:
(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.
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.
- Make sure that you double any embedded apostrophes, for example:
?<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.