Using PL/I in the Common Language Environment

When you write a parameter descriptor for a non-PL/I procedure, you can specify the ANY attribute without the VALUE attribute to describe an argument being passed by reference. The argument can be of any addressable data type known to PL/I. For example:

DECLARE MEMSET ENTRY (ANY, CHAR(1) VALUE,
                                               FIXED BIN(31) VALUE);

The first parameter descriptor in the ENTRY attribute specifies that the argument can have any data type and is being passed by reference. When you specify ANY for an argument to be passed by reference, you cannot specify data type attributes. Note that if you specify the VALUE attribute in conjunction with the ANY attribute, PL/I passes the argument by value.

The ANY attribute is especially useful when you must specify a data structure as an argument. You need not declare the structure within the parameter descriptor, only the ANY attribute.

When PL/I passes an argument by reference, it puts either the address of the actual argument or the address of a dummy argument in the argument list of the called procedure. PL/I creates a dummy argument in the following cases:

In the last case of the previous list, PL/I issues an informational or warning message and, for scalar arguments, creates a dummy argument of the data type of the parameter. It places the address of this dummy argument in the argument list. If the argument is an aggregate, PL/I issues an error message and does not create a dummy argument for the array or structure.

In creating a dummy argument, PL/I does the conversions listed in Table 10.1, “Converted Data Types of Arguments Passed by Reference”:

In all other cases, the data type of the dummy argument is the same as the data type of the written argument.

When you pass an argument by reference, PL/I puts the address of the actual argument in the argument list. This address can be interpreted as a pointer value. In fact, you can explicitly specify a pointer value as an argument for data to be passed by reference. For example:

DECLARE MEMSET (POINTER VALUE, CHAR(1) VALUE,
                               FIXED BIN(31) VALUE);

When MEMSET is invoked with the following statement at the procedure invocation, PL/I places the pointer value returned by the ADDR built-in function directly in the argument list.

CALL MEMSET(ADDR(EMPLOYEE_RECORD), '', 100);

In FORTRAN, you must always pass arrays by reference; the array extents are, by custom, passed as separate arguments. The REFERENCE attribute provides a convenient way to express an array parameter for FORTRAN. For example:

FTNARRAY: PROCEDURE(X);
DECLARE SUM ENTRY ((*) FLOAT REFERENCE, FIXED BINARY(31))
               RETURNS (FLOAT);

DECLARE (S, X(*)) FLOAT;

S = SUM(X, DIM(X));

SUM is a FORTRAN routine that sums the elements of a one-dimensional array of floating-point numbers. Its second parameter is the number of elements in the array.

For arguments to be passed by value, PL/I always creates a dummy argument directly in the argument list for the called procedure. If the parameter descriptor is specified with the ANY and VALUE attributes, PL/I creates dummy arguments the data types shown in Table 10.2, “Assignment of Data Type to Dummy Arguments”:

If a parameter descriptor is specified as VALUE with a particular data type (as opposed to being specified as ANY), a dummy argument of that data type is always created, and the written argument is assigned to the dummy. The written argument must be valid for conversion to the data type specified in the corresponding parameter descriptor.

This option is provided for use in calling non-PL/I procedures and can only be used for that purpose. If you declare an external entry with OPTIONS(VARIABLE), you can omit an optional argument and let the compiler pass a zero for the argument. The called procedure usually provides a default value. You must, however, enter the correct number of commas ton ensure that the argument list contains the correct number of longwords.

Some PL/I and non-PL/I routines with fixed-length argument lists accept optional arguments and provide a default action if no value is specified for the optional argument. When an optional argument is not specified, its corresponding argument list longword is filled with a value of zero passed by immediate value.

In PL/I, you can omit the specification of an optional argument in a written argument list as long as you enter the correct number of commas to ensure that the argument list will have the correct number of longwords. You can indicate that you are not specifying an optional argument in either of the following ways:

For example, an argument list that has three optional arguments can be written as follows:

(,,)

The called procedure must detect and interpret the optional parameters in the argument list. The following example illustrates optional arguments omitted from an argument list:

DECLARE ASCTIM ENTRY (
               FIXED BINARY(15) OPTIONAL,
               CHARACTER(*),
               ANY OPTIONAL,
               BIT(1) ALIGNED VALUE OPTIONAL),
       TIME_STRING CHARACTER(24);
⋮
CALL ASCTIM(,TIME_STRING,,);

This call to the service ASCTIM specifies only the second argument; the argument list contains four arguments. When you specify a null argument, as in the previous example, PL/I always places a zero in the argument list passed to the called procedure.

Some routines may allow an argument list to be truncated in a specified location. For example:

DECLARE GET_INPUT ENTRY (ANY CHARACTER(*),
               ANY CHARACTER(*) OPTIONAL TRUNCATE,
               FIXED BINARY(15) OPTIONAL TRUNCATE);

This declaration routine (GET_INPUT) specifies that the argument list may vary in length. In fact, GET_INPUT has three parameters, but the last two parameters are optional.

When you invoke such a routine omitting trailing arguments, you do not have to account for all the arguments in the procedure invocation argument list. For example, the GET_INPUT routine can be invoked with trailing arguments omitted:

CALL GET_INPUT(GET_STRING);

The variable GET_STRING is specified for the first argument. The other two arguments are not specified.