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