%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). For further
information, see Threadsafe Considerations in the TP Monitor
Interfaces documentation. 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 more information about how Natural supports IBM Language Environment (LE) subprograms, see LE Subprograms in the Operations documentation.
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
, and the parameter value data length exceeds 32KB, a CICS
container is passed instead of a COMMAREA.
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 and if the Natural CICS Interface version installed at your site supports this command.
This command does not apply if a called non-Natural subprogram is
defined to Natural with the CSTATIC
or
RCA
profile
parameter.
%P=SQ
is functionally equivalent to the
terminal command %P=S
.
If Natural is defined with the CICS CONCURRENCY(REQUIRED)
attribute and uses the
CICS open transaction environment (OTE), all subprograms called using standard linkage
conventions must be fully reentrant.
If a non-Natural subprogram is called that is quasi-reentrant but
not threadsafe and fully reentrant while Natural runs on an open TCB,
%P=SQ
ensures that the called program is executed
under the CICS QR TCB. Natural then issues the CICS command EXEC
CICS LINK PROGRAM('NCILINKQ')
to switch to the QR TCB and execute
the NCILINKQ
program which calls the subprogram using standard
linkage conventions.
This command also applies to LE subprograms. For more information about 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.
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 environment.
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.