Command Analyzer Retrieve Exit Program

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 immediately before transferring control to 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:

• CALLPRC
• CALLSUBR
• CHGVAR
• CNLRCV
• COPYRIGHT
• DCL
• DCLF
• DO
• DOFOR
• DOUNTIL
• DOWHILE
• ENDDO
• ENDPGM
• ENDRCV
• ENDSELECT
• ENDSUBR
• GOTO
• IF
• ITERATE
• LEAVE
• MONMSG
• OTHERWISE
• PGM
• RCVF
• RETURN
• RTNSUBR
• SELECT
• SNDF
• SNDRCVF
• SUBR
• TFRCTL
• WAIT
• WHEN

In addition, exit programs may not be registered for these commands:

• CALL command
• Commands that are restricted to use by the CL compiler when compiling for a previous release.
• Commands in libraries QSYS38 and QUSER38.

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.

Authorities and Locks

You must have *ALLOBJ and *SECADM special authorities to register an exit program for the QIBM_QCA_RTV_COMMAND exit point.

Required Parameter Group

Retrieve command exit information

INPUT; CHAR(*)

Information about the command that the command analyzer was called to process.

RTVC0100 Format

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(4)	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

Field Descriptions

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:

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.

Usage Notes

Registration considerations.

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 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 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.

Runtime considerations.

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.