Verbs and Built-in Functions › &CALL › &CALL program

&CALL program

These formats invoke a user program developed at your site for performing specialized processing:

&CALL progname
    [ data1 data2 ... datan ]

&CALL PGM=pgmname
    [ PARMLIST={ OLD | NEW } ]
    [ data1 data2 ... datan ]

&CALL SUBSYS=ssname
    [ data1 data2 ... datan ]

While NCL can perform many functions, individual installations can have particular processing requirements that need a unique facility for that function. 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.

Data returned from a called program is always returned in variables &1, &2, through to &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 after the &CALL statement. This return code is in the range 0 through 99. Anything outside this range is an error, and either aborts the process or sets &SYSMSG. In this case, &RETCODE is set to 100.

The program can also return 4 bytes of information (termed a correlator) that are saved and passed to any program called later within the NCL process.

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.

If pgmname is 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 for progname except 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. Specifying progname causes 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.

Note: 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 (xxxx is length of data)
ADDR2 ----> xxxxdata (xxxx is length of data)
 .
 .
ADDRn ----> xxxxdata (xxxx is length of data)

All passed parameters are padded with blanks to 256 characters. The program can return up to the number of passed parameters, by resetting the values and lengths.

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
  

• A(NCPF) points to an area that contains function code information, mapped as follows:

      NCPF     DESECT
      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)
  

  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 as follows:

      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
  

• 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 maps as follows:

      NCPS     DSECT
      NCPSNAME DS    CL8 subsystem name or asterisk (*)
                         if not a subsys call
      NCPSPGMN DS    CL8 program name
      NCPSSCOR DS    F   subsystem correlator
  

• 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 as follows:

      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.
  

• 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 maps as follows:

      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
  

• 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 maps as follows:

      NCPC    DSECT
      NCPCCNT DS    F Number of passed user parameters
                      (0 to n)
  

  Following the pointer to the NCPC, is a list of n pointers to user parameters. Each points to a 4-byte (binary) length (0 through 256), followed by the data, padded with blanks to 256 characters. As for old-format parameter lists, these values can be updated for return in &1, &2, &3, and so on. Only as many parameters as are passed are returned.

A macro, $NMNCPL, is distributed with your product. This macro maps out the new format parameter list.

data1 data2 ... 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

No complex substitution is allowed. The variable can contain any hexadecimal values. These values are passed unchanged. Similarly, the returned data is placed, unchanged, in the returned variables &1, &2, through to &n.

Examples: &CALL

&CALL &PROCNAME USERID &2
&CALL &DATECONV &MYDATE

Notes:

Variables passed to and from the called program can contain any hexadecimal values, 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.

&CALL always returns variables named &1, &2 through to &n. If the procedure has already defined variables with these names, the contents of those variables are replaced with the information returned from &CALL. Therefore, be careful when using such variable names with &CALL.

In z/OS and z/VM environments, 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. If storage is GETMAINed for subsequent calls to this or another program, the &CALL correlator is used to remember its address.

However, 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, you can remove this restriction with the SYSPARMS CALLSHR0=YES command.

If the program terminates abnormally, the invoking NCL procedure terminates with an appropriate error message which includes the failure reason.

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_name command 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_name command to delete previously loaded programs from storage.

Complex variables cannot be used in &CALL statements.

See also UTIL0005 in the distribution library.