IBM Support

SI45985 - OSP-CL-RUN-UNPRED Support calling exit program after a CL co

PTF Cover Letter


PTF ( Program Temporary Fixes ) Cover letter


Order this fix

Abstract

OSP-CL-RUN-UNPRED Support calling exit program after a CL co


Pre/Co-Requisite PTF / Fix List

REQ  LICENSED      PTF/FIX  LEVEL

TYPE PROGRAM  REL  NUMBER   MIN/MAX  OPTION
---- -------- ---  -------  -------  ------
NONE



NOTICE:
-------
Application of this PTF may disable or render ineffective programs that
use system memory addresses not generated by the IBM translator,
including programs that circumvent control technology designed to limit
interactive capacity to purchased levels.  This PTF may be a prerequisite
for future PTFs.  By applying this PTF you authorize and agree to the
foregoing.

This PTF is subject to the terms of the license agreement which
accompanied, or was contained in, the Program for which you are obtaining
the PTF.  You are not authorized to install or use the PTF except as part
of a Program for which you have a valid Proof of Entitlement.

SUBJECT TO ANY WARRANTIES WHICH CAN NOT BE EXCLUDED OR EXCEPT AS EXPLICITLY
AGREED TO IN THE APPLICABLE LICENSE AGREEMENT OR AN APPLICABLE SUPPORT
AGREEMENT, IBM MAKES NO WARRANTIES OR CONDITIONS EITHER EXPRESS OR IMPLIED,
INCLUDING BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OR CONDITIONS OF
MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE, AND NON INFRINGEMENT,
REGARDING THE PTF.

The applicable license agreement may have been provided to you in printed
form and/or may be viewed using the Work with Software Agreements (WRKSFWAGR)
CL command.





APAR Error Description / Circumvention

-----------------------------------------------
IBM i allows an exit program to be registered for the
QIBM_QCA_RTV_COMMAND exit point for a particular control
language (CL) command and that program will be called before the
command runs.  However, there is no capability to run an exit
program after a particular CL command runs.

CORRECTION FOR APAR SE50882 :
-----------------------------
The program data for the QIBM_QCA_RTV_COMMAND exit point will be
extended to support calling the registered exit program either
before or after the associated CL command runs.  If the exit
program data length is 30 and bytes 21-30 contain the value
*AFTER, the exit program will be run after the CL command runs.
Otherwise, the exit program will be run before the CL command
runs.

The following information for the QIBM_QCA_RTV_COMMAND exit
point will be updated in the IBM i Information Center web
version for 7.1 release and in all versions of the IBM i
Information Center for the following release:

Command Analyzer Retrieve Exit Program

Required Parameter Group:

1 Retrieve command exit information Input Char(*)

QSYSINC Member Name: ECARTCMD

Exit Point Name: QIBM_QCA_RTV_COMMAND

Exit Point Format Name: RTVC0100

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:

* CALLPRC
* CALLSUBR
* CHGVAR
* CLOSE
* CNLRCV
* COPYRIGHT
* DCL
* DCLF
* DCLPRCOPT
* DO
* DOFOR
* DOUNTIL
* DOWHILE
* ENDDO
* ENDPGM
* ENDRCV
* ENDSELECT
* ENDSUBR
* GOTO
* IF
* INCLUDE
* 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(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


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

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

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.

>>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.<<
Exit program introduced: V4R5


CIRCUMVENTION FOR APAR SE50882 :
--------------------------------
None.


Activation Instructions


None.




Special Instructions


None.


Default Instructions

THIS PTF CAN BE APPLIED IMMEDIATE OR DELAYED.



Supersedes

PTF/FIX NO(S).  APAR TITLE LINE
--------------  ------------------------------------------------------------
   SI45304      OSP-CL-RUN-MSGCPD0084Lower case letters in special values in
   SI44935      OSP-OTHER-MSGCPD0020 NL CHARACTERS NOT HANDLED CORRECTLY WHE
   SI44865      OSP-CL-RUN-UNPRED Provide more details in CD audit record
   SI41525      OSP-OTHER-UNPRED JOBS GETTING EXCLUSIVE LOCKS ON COMMAND OBJ
   SI37577      OSP-CL-RUN-UNPRED Change algorithm for proxy commands and re
   SI41719      OSP-CL-CMPL-F/QCLENTR-T/QUOCMD-MSGCPF0815 CPF8015 ON CL COMP
   SI42406      OSP-CL-RUN-MSGCPD0012 SUBMITTING A COMPILE FAILS IF THE SOUR

Summary Information

System..............................i
Models..............................
Release.............................V7R1M0
Licensed Program...............5770SS1
APAR Fixed..........................View details for APAR SE50882
Superseded by:......................View fix details for PTF SI67705
Recompile...........................N
Library.............................QSYS
MRI Feature ........................NONE
Cum Level...........................C2115710


System i Support

IBM disclaims all warranties, whether express or implied, including, but not limited to, the implied warranties of merchantability and fitness for a particular purpose. By furnishing this document, IBM grants no licenses to any related patents or copyrights. Copyright © 1996,1997,1998, 1999, 2000, 2001, 2002, 2003, 2004, 2005, 2006, 2007, 2008, 2009, 2010, 2011, 2012, 2013, 2014, 2015, 2016, 2017, 2018 IBM Corporation. Any trademarks and product or brand names referenced in this document are the property of their respective owners. Consult the Terms of use link for trademark information.

[{"Business Unit":{"code":"BU054","label":"Systems w\/TPS"},"Product":{"code":"SG15V","label":"PTF Cover Letters - OS\/400 General"},"Component":"","ARM Category":[],"Platform":[{"code":"PF012","label":"IBM i"}],"Version":"V7R1M0","Edition":""},{"Business Unit":{"code":"BU054","label":"Systems w\/TPS"},"Product":{"code":"SG16D","label":"PTF Cover Letters - IBM i 7.1 environment"},"Component":"","ARM Category":[],"Platform":[{"code":"PF012","label":"IBM i"}],"Version":"V7R1M0","Edition":""}]

Document Information

Modified date:
17 February 2012