| 1 | Retrieve command exit information | Input | Char(*) |
The Command Analyzer Retrieve exit program is called when the command for
which it is registered is processed. This program is called by the command
analyzer through the registration facility
either before transferring control to the command processing program
or after control returns from the command processing program.
Exit programs will not be called if
the command analyzer was called to syntax-check the command without running it.
The exit point supports a maximum of ten retrieve command exit programs for
each command.
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.
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 also may 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_RTV_COMMAND exit point.
Information about the command that the command analyzer was called to process.
The following table shows the format of the information supplied to a retrieve command exit program. For a description of the fields in this format, see Field Descriptions.
| 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(2) |
Reserved |
| 50 |
32 |
CHAR(1) |
Before or after indicator |
| 51 |
33 |
CHAR(1) |
Reserved |
| 52 | 34 | BIN(4) | Offset to original command string |
| 56 | 38 | BIN(4) | Length of original command string |
| 60 | 3C | BIN(4) | Offset to replacement command string |
| 64 | 40 | BIN(4) | Length of replacement command string |
| 68 | 44 | BINARY(4) | Offset to proxy chain |
| 72 | 48 | BINARY(4) | Number of entries in proxy chain |
| CHAR(*) | Original command string | ||
| CHAR(*) | Replacement command string | ||
| Proxy commands and libraries. These fields repeat in the order listed. | CHAR(10) | Proxy command name | |
| CHAR(10) | Proxy command library name | ||
Before or after indicator. Whether the exit program was
called before the command processing program has run or after the command
processing program has run. Possible values are:| 0 | The exit program was called before the command processing program has run. |
| 1 | The exit program was called after the command processing program has run. |
Command name. The name of the command that is being processed.
Exit point format name. The format name for the Retrieve Command exit program. The possible format name is:
| RTVC0100 | The format name that is used to supply the exit information. |
Exit point name. The name of the exit point that calls the exit program (QIBM_QCA_RTV_COMMAND).
Length of original command string. The length of the original command string being processed.
Length of replacement command string. The length of the replacement command string from the user exit program that was called at exit point QIBM_QCA_CHG_COMMAND. This will be 0 if there is no exit program for exit point QIBM_QCA_CHG_COMMAND or if the exit program did not change the command.
Library name. The name of the library of the command being processed.
Number of entries in proxy chain. The number of proxy commands chained to this command.
Offset to original command string. The offset to the beginning of the original command string.
Offset to proxy chain. The offset to the beginning of the proxy chain information.
Offset to replacement command string. The offset to the beginning of the replacement command string. This will be 0 if there is no exit program for exit point QIBM_QCA_CHG_COMMAND or if the exit program did not change the command.
Original command string. The command string that was originally submitted to the command analyzer for 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 has DSPINPUT(*NO) or DSPINPUT(*PROMPT) will be formatted without the parameter value (for example, "PASSWORD()") to prevent exit programs from getting passwords and similar secure data. If the original command string was replaced by an exit program called at the QIBM_QCA_CHG_COMMAND exit point, this may not be syntactically correct because required parameters may be missing, interparameter checks have not been done, and the validity checking program has not been called.
Replacement command string. The replacement command string from the user exit program that was called at exit point QIBM_QCA_CHG_COMMAND. The command name will be library qualified and the parameter values will be enclosed in parentheses and preceded by the keyword names.
Reserved. Reserved area.
Use the Add Exit Program command (ADDEXITPGM) or the Add Exit Program (OPM, QUSADDEP; ILE, QusAddExitProgram) API to register an exit program for a command.
You must specify at least 20 bytes of exit program data. The first 10
characters specify the command name; the second 10 characters specify the
library name. If bytes 21-30 contain the value *AFTER, the exit program will be
called after the command processing program has run.
If bytes 21-30 contain a value other than *AFTER, or if only 20 bytes of
program data were specified, the exit program will be called before the command processing program is run.
Any exit programs registered for commands in 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 must have an exit program registered for the new command and library names.
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.
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.
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 should also 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.
If an exit program is called after the command processing program runs and the command being run
has a product library or current library, the exit program is called after the product library and
current library have been restored to the library values that were in effect before
the command was run.
[ Back to top | Program and CL Command APIs | APIs by category ]