%P=
|
|
|
Each %P= command applies only to the next
call, and the call options are reset unconditionally on return from the
call.
Therefore it is highly recommended to code the
%P= directly before the relevant CALL
statement.
Note:
To set the CALL option permanently, use the profile
parameter PGP or the
corresponding parameter macro
NTPGP.
When the Natural CICS Interface is used, the commands
%P=S(C), %P=V,
%P=C(C), %P=U and
%P=UT may be used to set special options which apply
when a Natural program calls a non-Natural program (via a
CALL statement). In all
other environments, these commands are ignored.
When the Natural IMS TM interface is used, the command
%P=I may be used to set special options which apply
when a Natural program calls a non-Natural program (via a
CALL statement). In all
other environments, this command is ignored.
For details on calling non-Natural programs, see the
CALL statement in the
Statements documentation.
The following command options are covered below:
%P=SQ - Standard Linkage for Call of Quasi-Reentrant Subprograms
%P=UT - Separate Unit of Work for Called Program, Tolerate Transaction Backout
This command only applies if the Natural CICS Interface is used.
Normally, when a Natural program calls a non-Natural program under CICS,
the address of the CALL
statement parameter address list is passed in the COMMAREA. If you wish the
parameter values themselves, rather than the address of their address list, to
be passed in the COMMAREA, issue the terminal command
%P=C before the call.
This makes it possible, for example, to use DPL for called CICS
programs: A CICS program that resides in another CICS region can only be called
with %P=C; as addresses within the
"calling" region cannot be accessed by the "called"
region, the parameter values have to be passed instead.
When %P=C is used, no parameters are passed
in the TWA, but only parameter values in the CICS COMMAREA. All parameters of
the CALL statement
parameter list are copied adjacent to one another, regardless of their
alignment. The resulting COMMAREA length is the sum of the individual parameter
lengths (this has to be taken into consideration when determining the number of
array occurrences to be passed). On return from the called program, the
parameters are copied back.
When overlapping fields are passed or the same field is passed more than once, these fields should be made "read-only" for the called program; otherwise, unpredictable results may occur when parameter values are returned to the calling program.
For %P=C, the restriction applies that group
arrays cannot be passed:
01 #GROUP (2) 02 #FIELD1 (A1) 02 #FIELD2 (P7)
Either pass them as individual arrays:
01 #GROUP 02 #FIELD1 (A1/2) 02 #FIELD2 (P7/2)
Or redefine them:
01 #GROUP 01 REDEFINE #GROUP 02 #ARRAY (A1/10)
and specify the array name in the CALL statement.
Notes:
%P=S and
%P=C are issued for a call,
%P=C will be ignored.
CNTCALL is set to
ON in the macro
NTCICSP,
a CICS container is passed rather than a COMMAREA if the parameter value data
length exceeds 32 KB.
IF LENGTH OF DFHCOMMAREA GREATER THAN EIBCALEN …
(in COBOL) or IF SIZE (DFHCOMMAREA) > EIBCALEN … (in
PL/1).
This command only applies if the Natural CICS Interface is used.
This functionality requires CICS Transaction Server for z/OS version 3.1 or above.
The difference between %P=C and
%P=CC is that the parameter values are passed in a
CICS container right away. All restrictions except the length limitation of 32
KB still apply.
This command only applies if the Natural IMS TM interface is used.
%P=I indicates to Natural that PCB addresses
are to passed to the 3GL program in the following
CALL statement. As it is
not possible to pass the address of a PCB from Natural to the 3GL program
directly, a special convention is used to indicate to Natural that parameters
passed to the 3GL program may contain either the position or the name of a PCB.
For fields that satisfy this convention, Natural will pass the address of the
PCB to the called 3GL program instead of the address of the specified
parameter.
Only scalar fields of either format A8 or A12 are checked for a PCB specification. The fields that contain a PCB specification must comply with the following conventions:
An A8 field must contain the string
'PCB=nnnn' where
nnnn is a four digit number that represents the
position of the PCB in the PSB address list.
An A12 field must contain the string
'PCB=name' where
name is the eight character name for a PCB that has
been defined with the NTIMSPT macro when the Natural IMS TM interface was
installed.
Example:
After %P=I has been executed, for the
statement
CALL 'MY3GL' USING 'PCB=MYPCB ' 'PCB=0004' PARAM
the following parameters are passed to the 3GL program MY3GL:
address of the PCB with the name "MYPCB" as specified with macro NTIMSPT,
address of the fourth PCB in the PSB address list,
address of the Natural field PARAM.
The following return codes are returned by the
RET system function if the PCB specification is
invalid:
| Return Code | Explanation |
|---|---|
| -4 | The specified value nnnn
for format 'PCB=nnnn' is not
numeric.
|
| -8 | The specified PCB name has not been defined with the macro NTIMSPT. |
| -12 | The specified PCB with position
nnnn does not exist in the PSB address
list.
|
This command only applies if the option for the support of the IBM Language Environment (LE) calling conventions has been set when Natural was installed.
This command causes control to be returned to Natural after a call to an LE dynamic main program.
By default, when an LE dynamic main program is invoked, control is not
returned to Natural after the invoked program has been processed. For control
to be returned after that program has been processed, you have to use
%P=L before invoking the program.
For information on how Natural supports IBM Language Environment (LE) subprograms, see LE Subprograms (in the Operations documentation).
Note:
Under CICS %P=L and
%P=LS are equivalent, as LE main programs are not
supported.
This command only applies if the option for the support of the IBM Language Environment (LE) calling conventions has been set when Natural was installed.
This command causes that a dynamic or static non-Natural program is invoked using LE calling conventions, that is, via standard linkage conventions with Register 12 holding the address of the LE CAA.
For information on how Natural supports IBM Language Environment (LE) subprograms, see LE Subprograms (in the Operations documentation).
This command only applies if the Natural CICS Interface is used.
Normally, when a Natural program calls a non-Natural program under CICS,
the call is accomplished by an EXEC CICS LINK
request.
If standard linkage is to be used for the call instead, issue the
terminal command %P=S. In this case, the called
program must adhere to standard linkage conventions with standard register
usage.
This command only applies if the Natural CICS Interface is used.
Normally, when a Natural program calls a non-Natural program under CICS,
the call is accomplished by an EXEC CICS LINK
request.
When this terminal command is used, the Natural CICS Interface invokes
the non-Natural program using standard linkage conventions, but passing
parameters as a CICS LINK does, that is, Register 1
points to a parameter list holding addresses of CICS EIB and a CICS COMMAREA.
Notes:
%P=SC can be combined with
%P=C.
EXEC CICS RETURN. Assembler programs must return
via DFHEIRET macro call. COBOL programs must return via
GOBACK statement.
This command only applies if Natural CICS Interface is used.
%P=SQ is functionally equivalent to the
terminal command %P=S. If Natural is running in a
threadsafe environment under an OTE TCB which requires full reentrancy,
%P=SQ ensures that the called program executes under
the QR TCB, which guarantees that the program is quasi-reentrant. This is
accomplished by the CICS command EXEC CICS LINK
PROGRAM('NCILINKQ') which performs during the call. For this purpose,
the supplied assembler program NCILINKQ must be installed in CICS
as quasi-reentrant.
This command only applies if the Natural CICS Interface is used.
This command specifies that a CICS program called by Natural via DPL has its own unit of work, which is committed on return to Natural; that is, changes to recoverable resources made by the called program are committed or rolled-back independent of changes to recoverable resources made by Natural. In terms of CICS: This command causes an EXEC CICS LINK with the SYNCONRETURN option.
This command has almost the same meaning as
%P=U, with one exception:
For %P=U, all CICS conditions on return from
the called program other than NORMAL will result in a Natural NAT0920 error
message with the reason code being the response code of the EXEC CICS LINK
command.
For %P=UT, a CICS ROLLEDBACK response code
does not result in an error, but is tolerated and treated as NORMAL.
This command applies to Natural environments where several sessions share threads in the same region, such as the Natural CICS Interface and the Natural batch server environments in z/OS, z/VSE and BS2000.
Normally, when a Natural programs calls a non-Natural program and the called program issues a conversational terminal I/O, the Natural thread is blocked until the user has entered data.
%P=V can be used to prevent the Natural
thread from being blocked: if this terminal command is specified, the parameter
data passed from the Natural program to the called program are copied out of
the Natural thread, and the thread is rolled out before the call. The thread is
then available for another user. Upon return from the called program to the
calling Natural program, the thread is rolled back in again, the (modified)
data area is copied into the thread, and Natural processing continues.
Note:
Only the parameters specified in the CALL statement are copied out of
and back into the thread.