Pointer (Indirection)

Indirect data, where a pointer to the data is passed rather than the data itself, is declared using two entries in the template file. The first entry in the following example specifies a data type of PTR and a length of 4 bytes (the parameter type is 31-bit address). The second entry defines the type of the data pointed to and does not declare an actual parameter in the parameter list.
    PTR     4    INPUT
    CHAR   80    INPUT
Valid data types for indirection are:
  • CHAR
  • SBIN
  • UBIN
  • BIT
  • LEN

Note that the FCHR, PTR, TABLE, RTNV, RTNC, and RTNR data types are not supported for indirection.

If the direction of the second template entry is INPUT, the direction of the first must also be INPUT. If the direction of the second is OUTPUT, the first also can be OUTPUT, indicating that the called routine will set it, or it can be INPUT, indicating that the address of the area for the output value is passed by the caller. The two entries together specify a single parameter, a 4-byte pointer to a data area of the format identified by the second declaration.

A LEN data type following a PTR data type does not specify the length of the pointer, but rather the length of the preceding parameter. For instance, suppose we had a table with 3 columns, the first an array of pointers to buffers to be filled by the calling routine, the second an array of pointers to 2-byte binary maximum length values, and the third an array of 4-byte signed binary elements to contain the actual length of each value placed in the buffer by the called routine. The template file definition would be:
     TABLE        *  INOUT    Table definition
       LEN        4  INPUT      Maximum number of rows
       LEN        4  OUTPUT     Used number of rows
       C.PTR      4  INPUT      Pointers to buffers
           CHAR   *  OUTPUT       Buffers
       C.PTR      4  INPUT      Pointers to buffer lengths
           LEN    2  INPUT        Maximum lengths
       C.LEN      4  OUTPUT     Used lengths for buffers

The call parameters for this template would be:

     maxrows,usedrows,bufaddrs,lenaddrs,lengths

where:

maxrows
indicates the maximum number of buffers usable
usedrows
returns the number used on call completion
bufaddrs
is an array of pointers to buffers with maxrows elements
lenaddrs
is an array of pointers to 2-byte binary values specifying the lengths of the buffers
lengths
is an array with maxrows elements, the first usedrows elements of which will be filled in by the called routine with the 4-byte binary lengths of the records placed in the corresponding buffers.

REXX does not support pointers. For REXX CSL calls, the actual variable name must be specified in the parameter list. The REXX CSL interface adds the pointer to the data for input parameters and uses the pointer to find the value to return in the variable for output parameters.