%P=

C CC I L LS S SC SQ U UT V

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.

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=C - Pass Parameter Values instead of Address

• %P=CC - Pass Parameter Values in a CICS Container

• %P=I - Pass PCB Addresses to Callee

• %P=L - Call of LE Dynamic Main Program

• %P=LS - Call of LE Subroutine Program

• %P=S - Standard Linkage for Call

• %P=SC - Standard Linkage Call Simulating EXEC CICS LINK

• %P=SQ - Standard Linkage for Call of Quasi-Reentrant Subprograms

• %P=U - Separate Unit of Work for Called Program

• %P=UT - Separate Unit of Work for Called Program, Tolerate Transaction Backout

• %P=V - Roll-Out for Call

---

%P=C - Pass Parameter Values instead of Address

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:

1. If both %P=S and %P=C are issued for a call, %P=C will be ignored.
2. CICS COMMAREAs are restricted to 32 KB.
3. If the parameter 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.
4. Avoid storage violations in CICS by ensuring that a called program checks whether the length of the data area to be passed really matches the internal data structure. This is achieved by checking EIBCALEN against the COMMAREA length: IF LENGTH OF DFHCOMMAREA GREATER THAN EIBCALEN … (in COBOL) or IF SIZE (DFHCOMMAREA) > EIBCALEN … (in PL/1).

%P=CC - Pass Parameter Values in a CICS Container

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.

%P=I - Pass PCB Addresses to Callee

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.

%P=L - Call of LE Dynamic Main Program

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

%P=LS - Call of LE Subroutine Program

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

%P=S - Standard Linkage for Call

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.

%P=SC - Standard Linkage Call Simulating EXEC CICS LINK

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:

1. %P=SC can be combined with %P=C.
2. A CICS program invoked via standard linkage call must not return to the caller via EXEC CICS RETURN. Assembler programs must return via DFHEIRET macro call. COBOL programs must return via GOBACK statement.

%P=SQ - Standard Linkage for Call of Quasi-Reentrant Subprograms

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.

%P=U - Separate Unit of Work for Called Program

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.

%P=UT - Separate Unit of Work for Called Program, Tolerate Transaction Backout

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.

%P=V - Roll-Out for Call

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.