| 1 | Change command exit information | Input | Char(*) |
| 2 | Replacement command | Output | Char(*) |
| 3 | Length of replacement command string | Output | Binary(4) |
The Command Analyzer Change exit program is called when the command for which it is registered is processed. The command analyzer calls the Change Command exit program for a command once through the registration facility before performing any of the following steps:
The exit program is not called if the command analyzer was called to syntax check the command, but not run it. The exit point supports one change command exit program for each command.
The exit program is called, but the command cannot be changed if any of the following occur:
If changing the command is allowed, the exit program can change the command string so that the command analyzer processes a command from a different library or a completely different command. It also can change any or all of the parameters specified on the command. When a changed command string is returned to the command analyzer, the command analyzer will not prompt the replaced command or call the validity checking program, any exit programs registered for the QIBM_QCA_RTV_COMMAND exit point, or the command processing program for the replaced command. The command analyzer will start over with the changed command instead of the original one. It will do a full validation of the new command, including prompting if prompting was requested for the replaced command. If the changed command string specifies a different command in a different library and there is an exit program registered for the QIBM_QCA_CHG_COMMAND exit point for the new command, it will be called, but it will not be allowed to change the command. Exit programs registered for the QIBM_QCA_RTV_COMMAND exit point for the new command will be called. If the command is not changed, the command analyzer will continue with normal processing of the original command, including calling any exit programs registered for the QIBM_CA_RTV_COMMAND exit point.
The replaced command string will be logged to the job log only when the original command was logged. For commands entered on a command line, the original command will be logged as a request message, and the substitute will be logged as a command message. This will allow users to retrieve their original command with the Retrieve function key.
If the exit program sends any escape messages to the command analyzer, the message will be left in the job log and ignored by the command analyzer. The command analyzer will continue processing the original command.
Exit programs may not be registered for the following system commands:
In addition, exit programs may not be registered for these commands:
If the exit program uses the registered CL command, a recursive loop may occur. Recursive loops may also occur if two or more exit programs use each other's CL commands. For example, if the exit program for CMDA uses CMDB and the exit program for CMDB uses CMDA, a recursive loop will occur.
You must have *ALLOBJ and *SECADM special authorities to register an exit program for the QIBM_QCA_CHG_COMMAND exit point.
Information about the command that the command analyzer was called to process.
A string containing the command string that is to be substituted for the one the command analyzer was called to process. This will be ignored if the command is not allowed to be changed. The maximum length of the changed command string is 32000 bytes.
Commands that should not be specified as the replacement command by an exit program include:
If any of these commands are used as replacement commands, the command analyzer will send a diagnostic message, followed by escape message CPF0001, and processing of the command will end.
The length of the replacement command string (0 - 32000) in bytes. If the length is 0, the original command string will be run, and the replacement command will be ignored.
| Offset | Type | Field | |
|---|---|---|---|
| Dec | Hex | ||
| 0 | 0 | CHAR(20) | Exit point name |
| 20 | 14 | CHAR(8) | Exit point format name |
| 28 | 1C | CHAR(10) | Command name |
| 38 | 26 | CHAR(10) | Library name |
| 48 | 30 | CHAR(1) | Change allowed indicator |
| 49 | 31 | CHAR(1) | Prompt indicator |
| 50 | 32 | CHAR(2) | Reserved |
| 52 | 34 | BINARY(4) | Offset to command string |
| 56 | 38 | BINARY(4) | Length of command string |
| 60 | 3C | BINARY(4) | Offset to proxy chain |
| 64 | 41 | BINARY(4) | Number of entries in proxy chain |
| CHAR(*) | Command string | ||
| Proxy commands and libraries. These fields repeat in the order listed. | CHAR(10) | Proxy command name | |
| CHAR(10) | Proxy command library name | ||
| 1 | The command may be changed. |
| 0 | The command may not be changed. |
If a replacement command is returned to the command analyzer, it will be ignored.
Command name. The name of the command that is being processed.
Command string. The command string that the command analyzer is processing. The command name will be library qualified, and the parameter values will be enclosed in parentheses and preceded by the keyword names. Any parameter that was defined as DSPINPUT(*NO) or DSPINPUT(*PROMPT) when the command was created will be formatted without the parameter value (for example, "PASSWORD()") to prevent the exit programs from getting passwords and similar secure data. This command string may not be correct syntactically because required parameters may be missing, interparameter checking has not been done, and the validity checking program for the command has not been called.
Exit point name. The name of the exit point that calls the exit program.
Exit point format name. The format name for the Change Command exit program. The possible format name is:
| CHGC0100 | The format name that is used to supply the exit information. |
Length of command string. The length of the command string being processed.
Library name. The name of the library for the command being processed.
Number of entries in proxy chain. The number of proxy commands chained to this command.
Offset to command string. The offset to the beginning of the command string.
Offset to proxy chain. The offset to the beginning of the proxy chain information.
Prompt indicator. Whether prompting was requested on the original command string. Possible values are:
| 0 | Prompting was not requested for the original command. |
| 1 | Prompting was requested for the original command. |
Proxy command name. Name of the proxy command.
Proxy command library name. Name of the proxy command library.
Reserved. Reserved area.
Use the Add Exit Program command (ADDEXITPGM) or API (QUSADDEP, QusAddExitProgram) to register an exit program for a command. You must specify 20 bytes of exit program data. The first 10 characters specify the command name; the second 10 characters specify the library name.
Any exit programs registered for commands in library QSYS also will be called for commands in the secondary language libraries. For example, if an exit program is registered for the DSPJOB command in library QSYS, it will also be called for the DSPJOB command in library QSYS2962.
If you rename the command or the library or move the command to another library, you also must have an exit program registered using the new command and library names.
Only one exit program can be registered for each command for the QIBM_QCA_CHG_COMMAND exit point. If two applications on the same system, however, need to replace the same command, they can do it by registering a single exit program, which replaces the command with one that is qualified with *LIBL instead of replacing it with their own specific commands. The QCARPLCM program in library QSYS may be used to do this. Applications using QCARPLCM must ensure that their application library is at the beginning of the system part of the library list.
Any exit program registered for this exit point must be threadsafe if it will be called in a job that has multiple threads.
This exit point is a command analyzer exit point that is called during the processing of individual commands. This does not imply that command usage by the system or by individual applications will not change or even be eliminated in the future. For example, if some system function, X, uses the CRTLIB CL command, you should not assume that X will always use the CRTLIB command. X's use of CL commands may change without any warning to use an API or some other interface. Therefore, you should not create any dependencies based on the assumption that a specific function is implemented using a CL command.
If a command is qualified with special value *SYSTEM, only library QSYS will be searched for the command. The change exit program will be allowed to change the command.
If a command is qualified with special value *NLVLIBL, only the national language version (NLV) libraries in the library list and QSYS will be searched for the command. The change exit program will be allowed to change the command.
Adopted authority from previous call levels will be used to determine authority to the exit program, but will not be propagated to the exit program. The exit program will have all of the authorities available to the user profile under which the job is currently running; this may be a profile which has been swapped to, rather than the user profile under which a job was started.
All users with at least *USE authority to the command also should have *OBJOPR and *EXECUTE authority to the exit program and *EXECUTE authority to the exit program's library. The command will fail if the user does not have sufficient authority to the exit program.
[ Back to top | Program and CL Command APIs | APIs by category ]