&CALL program
Use the &CALL program function to invoke custom programs that perform specialized NCL processing for your installation.
While NCL can perform many functions, individual installations can have particular processing requirements that need a unique facility for that function. The &CALL program enables the facility, and allows you to expand upon NCL by calling custom programs. The called program receives data and the contents of variables by including them on the &CALL statement. The called program updates this data and returns the updated data for further NCL processing.The &CALL program uses the following formats to invoke custom user programs:
&CALLprogname[data1data2...datan] &CALL PGM=pgmname[ PARMLIST={OLD| NEW } ] [data1data2...datan] &CALL SUBSYS=ssname[data1data2 ...datan]
You can try the &CALL program functionality with UTIL0005, a sample program designed to be callled with an &CALL statement. It is included as part of the AC2DSAMP distribution library, in the CC2DSAMP target library.
When using an &CALL program, keep in mind the following guidelines:
Functional Considerations:
- Data returned from a called program is always returned in variables &1, &2, through &n, regardless of the variable names that have been specified in the &CALL statement itself.
- The number of variables available after the &CALL statement matches the number of data fields specified on the &CALL statement.
- Variables with null values when the &CALL statement was issued always return a variable (for example, &5) equivalent to their position on the &CALL statement. This variable has a null value unless data is supplied from the called program.
- The called program or subsystem can set a return code (in Register 15 if written in Assembler) in the &RETCODE system variable when processing resumes at the statement that follows the &CALL statement. This return code can be anywhere in the range of 0 through 99. Any return code outside this range is an error that will either abort the process or set &SYSMSG. If &SYSMSG is set, the &RETCODE is set to 100.
- If the program terminates abnormally, the invoking NCL procedure terminates with an appropriate error message that includes the failure reason.
- The program can return 4 bytes of information, known as a correlator, that are saved and passed to any program called later in the NCL process
Operational Considerations:
- The specified program is attached to your product region as a subtask, and can therefore issue waits or I/O requests without affecting the rest of the system.
- The called program executes in an APF authorized environment. The program must adhere to standard integrity guidelines in order to avoid compromising the security and integrity of the system.
- The specified program must be available in the standard load module libraries available to your product region.
- If many concurrent users of the program are anticipated, consider making the program reentrant and loading it into your product region in advance. You can use the LOAD MOD=module_namecommand to specify the name of a module to load into your product region.
- When the loaded module has the RENT or REUS attributes, subsequent references to this module from &CALL use the loaded copy, avoiding further retrieval. The LOAD commands are typically placed in the NMINIT initialization procedure. If these modules are link edited with the reentrant attribute, they must be reentrant. Otherwise, unpredictable results occur when they are invoked. Use the UNLOAD MOD=module_namecommand to delete previously loaded programs from storage.
Storage Considerations:
- If storage is GETMAINed for subsequent calls to this or another program, the &CALL correlator is used to remember its address.
- You should obtain the storage in subpool 50 to avoid freeing it automatically when the program returns to your product region. The program is responsible for ensuring that any storage obtained in subpool 50 is freed when no longer required.
- By default, subpool zero is not shared between your product region and the &CALL subtask. If you are using operating system functions in the subtask (for example, native VSAM) that require sharing subpool zero, use the SYSPARMS CALLSHR0=YES command to remove the restriction.
Operands:
- progname
- Indicates the &CALL target. If the program abends or returns a code greater than 100, the NCL process is terminated with an error.
- Ifpgmnameis equal to the name of a subsystem, which was defined with the CALLREPL=YES option, the call is rerouted to that subsystem.
- PGM=pgmname
- Causes the call to be performed as forprognameexcept that, if the program abends or returns an invalid return code, the NCL process is not terminated. Instead, &RETCODE is set to 100 and &SYSMSG contains the error message that would have been issued.
- No SUBSYS replacement takes place for PGM=pgmname. A one-time attach always occurs.
- This operand must be specified if you want to use the new format parameter list. Specifyingprognamecauses a default to PARMLIST=OLD.
- SUBSYS=ssname
- Queues the call to the nominated subsystem. If it is not found, the process is aborted. Other errors result in &RETCODE of 100 and &SYSMSG being set. PARMLIST= is not permitted in this case. If specified, it is treated as the first parameter to the subsystem program. The subsystem definition defines the parameter list format.
- PARMLIST={OLD| NEW }
- Indicates the format of the parameter list to use. The operand is not recognized if specified with SUBSYS=ssname, but is treated as the first user-program parameter.
- Default:OLD
- PARMLIST=OLD
- Specifies to use the old-format parameter list.
- This format parameter list is not compatible with high-level-language programs.
- The format of this type of parameter list is:
- SECURITY EXIT CORRELATOR &CALL CORRELATOR AREA Register 1 ----> COUNT ADDR1 ---->xxxxdata(xxxxis length of data) ADDR2 ---->xxxxdata(xxxxis length of data) . . ADDRn---->xxxxdata(xxxxis length of data)
- All passed parameters are padded with blanks to 256 characters. By resetting the values and lengths, the program can return the count of passed parameters.
- PARMLIST=NEW
- Specifies to use the new-format parameter list. This parameter list contains much new information.
- The parameter list is as follows:
- R1 ---> A(parmlist) (that is, a word that points to itself) A(NCPF) A(NCPE) A(NCPS) A(NCPU) A(NCPN) A(NCPZ) A(NCPC) A(data1)--->f'len',cl256'data' A(data2)--->f'len',cl256'data'
- Each of the parameter areas is as follows:
- A(parmlist) points to the parameter list itself.This area is the key to allowing a program to determine whether the parameter list is in the old or new formats. Recall that the old format parameter list had as the first parameter the number of passed parameters.This value is a binary fullword in the range from 0 to approximately 1000 (maximum with a 1024-byte statement buffer).In the new format, the first parameter points to itself. Because a parameter list cannot start in the first 4096 bytes of storage (page 0), the following simple test allows you to determine easily whether the PARMLIST is old or new format:
- C R1,0(,R1) BE NEWFORMAT B OLDFORMAT NCPF DSECT NCPFFUNC DS F function code NCPFFCAL EQU 00 00 - &CALL NCPFFTRM EQU 04 04 - NCL proc terminate (SUBSYS only) NCPFFSIN EQU 08 08 - SUBSYS initialize NCPFFSTM EQU 12 12 - SUBSYS terminate NCPFFSST EQU 16 16 - system shutdown (SUBSYS only) NCPE DSECT NCPEVERS DS CL4 version, for example, 'V5.1' NCPEID DS CL12 NMID NCPEDMN DS CL4 domain ID NCPEACB DS CL8 ACBNAME NCPESSCP DS C8 SSCP name NCPENETI DS CL8 NETID name NCPS DSECT NCPSNAME DS CL8 subsystem name or asterisk (*) if not a subsys call NCPSPGMN DS CL8 program name NCPSSCOR DS F subsystem correlator NCPU DSECT TNCPUID DS CL8 User ID NCPULU DS CL8 Logical unit (terminal name) NCPUWIND DS F Window number (0 to 1) NCPUSECC DS F Security correlator NCPUTOKN DS F Address of Security Exit User Token supplied by security exit. NCPN DSECT NCPNPROC DS CL8 Procedure name (that issued this &CALL) DS CL4 Reserved NCPNNCLI DS F NCLID (in binary) 1-999999 NCPNSCOR DS F Correlator shared with all other &CALLS for proc NCPNPCOR DS F SUBSYS only private correlator for this proc NCPC DSECT NCPCCNT DS F Number of passed user parameters (0 to n)
- A(NCPF) points to an area that contains function code information. It is mapped by the NCPF DSECT.Only defined subsystems ever receive any code other than 0.
- A(NCPE) points to an area that contains environment information. This information is used to find out about your product region. Some VTAM information is also provided.The NCPE is mapped by the NCPE DSECT.
- A(NCPS) points to an area containing subsystem environment information. If this call is not to a defined subsystem, this area is still provided. The code can detect that a subsystem is not defined by testing NCPSNAME. If not a subsystem, the value CL8'*' is inserted. The subsystem can use the correlator field to anchor subsystem-related control blocks across calls (for example, to preserve complete reentrancy).The NCPS is mapped by the NCPS DSECT.
- A(NCPU) points to an area that maps user ID information. This information is about the user ID that is executing the procedure that issues the &CALL.The NCPU is mapped by the NCPU DSECT.
- A(NCPN) points to information about the NCL process that issued this &CALL. This information includes the name of the current procedure, and the NCL ID. Also, a shared correlator and a private correlator (SUBSYS only) are provided.The NCPN is mapped by the NCPN DSECT.
- A(NCPZ) points to a null area. This area is reserved for future expansion. The pointer is set (it is not 0). In a high-level language define it as a single binary number (S9(9) COMP in COBOL, FIXED BIN(31) in PL/1).
- A(NCPC) points to the count area. This section contains the count of the number of user parameters passed.The NCPC is mapped by the NCPC DSECT.
- data1data2 ...datan
- (Optional) Specifies other parameters to pass on the call. Each is a constant, a simple variable name, or constant data followed by a variable name:
- constant
- &variable
- constant&variable
- Variables passed to and from the called program can contain any hexadecimal values, either printable or non-printable. No translation is made of the data returned by the program - it is the responsibility of the NCL procedure to determine any meaning for data passed to and from the program. The program returns data, unchanged, in the returned variables &1, &2, through &n.Complex variables cannot be used in &CALL statements.As noted, an &CALL program always returns variables named &1, &2 through to &n. If a procedure has variables with the same names, the contents of those variables are replaced with the information returned from &CALL. If you plan to use an &CALL statement, ensure that the procedures do not contain the same variable names as used by the &CALL program.
Examples: &CALL
&CALL &PROCNAME USERID&2 &CALL &DATECONV &MYDATE