If the data item source value is of type FLOAT BINARY(p1), it is converted to FLOAT DECIMAL(p2), where:

For OpenVMS VAX systems:

p2 = min(ceil(p1/3.32),34)

For OpenVMS Alpha systems:

p2 = min(ceil(p1/3.32),15)

For a value of type FLOAT DECIMAL(p), where p is less than or equal to 34, the intermediate string is of length p+6; this allows extra characters for the sign of the number, the decimal point, the letter E, the sign of the exponent, and the 2-digit exponent.

If the number is negative, the first character is a minus sign; otherwise, the first character is a space. The subsequent characters are a single digit (which can be 0), a decimal point, p-1 fractional digits, the letter E, the sign of the exponent (always + or -), and the exponent digits. The exponent field is of fixed length, and the zero exponent is shown as all zeros in the exponent field.

Examples

CONCH: PROCEDURE OPTIONS(MAIN); DECLARE OUT PRINT FILE; OPEN FILE(OUT) TITLE('CONCH.OUT'); PUT SKIP FILE(OUT) EDIT('''',25E25,'''') (A); PUT SKIP FILE(OUT) EDIT('''',-25E25,'''') (A); PUT SKIP FILE(OUT) EDIT('''',1.233325E-5,'''') (A); PUT SKIP FILE(OUT) EDIT('''',-1.233325E-5,'''') (A); END CONCH;

The program CONCH produces the following output:

' 2.5E+26' '-2.5E+26' ' 1.233325E-05' '-1.233325E-05'

The PUT statement converts its output sources to character strings, following the rules described in this section. (The output strings are surrounded with apostrophes to make the spaces distinguishable.) In each case, the width of the quoted output field (that is, the length of the converted character string) is the precision of the floating-point constant plus 6.

6.4.8.2 Pictured to Character-String Conversion

If the source value is pictured, its internal, character-string representation is used without conversion as the intermediate character string.

6.4.8.3 Bit-String to Character-String Conversion

When PL/I converts a bit string to a character string, it converts each bit in the bit string (as represented by PUT LIST) to a 0 or 1 character in the corresponding position of the intermediate character string.

If the bit string is a null string, the intermediate character string is also a null string.

Examples

DECLARE STRING_1 CHARACTER (4), STRING_2 CHARACTER (8); STRING_1 = '1010'B; /* STRING_1 = '1010' */ STRING_2 = '1010'B; /* STRING_2 = '1010 ' */ STRING_1 = '010011'B; /* STRING_1 = '0100' */

6.4.9 Assignments to Pictured Variables

A source expression of any computational type can be assigned to a pictured variable. The target pictured variable has a precision (p), which is defined as the number of characters in the picture specification that specify decimal digits. The target also has a scale factor (q), which is defined as the number of picture characters that specify digits and occur to the right of the V character in the picture specification. If the picture specification contains no V character, or if all digit-specification characters are to the left of V, then q is zero.

The source expression is converted to a fixed-point decimal value v of precision (p,q), following the PL/I rules for the source data type. This value is then edited to a character string s, as specified by the picture specification, and the value s is assigned to the pictured target.

When the value v is being edited to the string s, the CONVERSION condition is signaled if the value of v is less than zero and the picture specification does not contain one of the characters S, +, -, T, I, R, CR, or DB. The value of s is then undefined. FIXEDOVERFLOW is signaled if the value v has more integral digits than are specified by the picture specification of the target.

6.4.10 Conversions Between Offsets and Pointers

Offset variables are given values by assignment from existing offset values or from conversion of pointer values. Pointer variables are given values by assignment from existing pointer values or from conversion of offset values.

The OFFSET built-in function converts a pointer value to an offset value. The POINTER built-in function converts an offset value to a pointer.

PL/I also automatically converts a pointer value to an offset value, and vice versa, in an assignment statement. The following assignments are valid:

• pointer-variable = pointer-value;
• offset-variable = offset-value;
• pointer-variable = offset-variable;
• offset-variable = pointer-value;

In the third and fourth assignments above, the offset variable must have been declared with an area reference.

A procedure is the basic executable program unit in PL/I. It consists of a sequence of statements, headed by a PROCEDURE statement and terminated by an END statement, that define an executable set of program instructions. There are three kinds of procedures:

• A MAIN procedure is the procedure where program execution begins.
• A subroutine procedure is invoked with a CALL statement and returns values to the invoking procedure by means of a parameter list.
• A function procedure is invoked by a function reference and returns a scalar value to the invoking procedure. It can also return values through a parameter list.

Subroutines and function procedures can be passed data from the invoking procedure by means of an argument list.

This chapter discusses the following topics:

• The PROCEDURE statement which defines the beginning of a procedure block
• Built-in and user-written functions
• The ENTRY statement and how to specify entry points
• The CALL statement which transfers control to an entry point
• Parameters and argument passing
• Calling external and internal procedures
• Terminating procedures
• Passing Arguments to non-PL/I procedures

The PROCEDURE statement defines the beginning of a procedure block and specifies the parameters, if any, of the procedure. If the procedure is invoked as a function, the PROCEDURE statement also specifies the data type attributes of the value that the function returns to its point of invocation. The PROCEDURE statement can denote the beginning of either an internal or an external subroutine or function.

The format of the PROCEDURE statement is as follows:

entry-name

A 1- to 31-character identifier denoting the entry label of the procedure. The label cannot be subscripted. The PROCEDURE statement declares the entry name as an entry constant. The scope of the name is INTERNAL if the procedure is contained in any other block, and EXTERNAL if the procedure is not contained in any other block.

parameter,...

One or more parameters (separated by commas) that the procedure expects when it is activated. Each parameter specifies the name of a variable declared in the procedure headed by this PROCEDURE statement. The parameters must correspond, one-to-one, with arguments specified for the procedure when it is invoked with a CALL statement or in a function reference.

OPTIONS (option,...)

An option that specifies one or more options, separated by commas:

• IDENT(string)

  
  An option specifying a character-string constant giving the module ident for the listing and the object files. Only the first 31 characters of the string are recognized.
  Each module should contain only one procedure with the IDENT option. Should there be more than one, the last specified indent will be the one used.

• MAIN

  
  An option specifying that the named procedure is the initial procedure in a program. The identifier of the procedure is the primary entry point for the program. The MAIN option is not allowed on internal procedures, and only one procedure in a program can have the MAIN option.
  A program must have one procedure with OPTIONS(MAIN) in order for condition handling to work properly.

• UNDERFLOW

  
  An option that requests that the run-time system signal underflow conditions when they occur. By default, the run-time system does not signal these conditions.

RECURSIVE or NONRECURSIVE

An option that indicates (for program documentation) that the procedure will or will not be invoked recursively. In standard PL/I, the RECURSIVE option must be specified for a procedure to be invoked recursively. However, any procedure can be invoked recursively, and the RECURSIVE and NONRECURSIVE options are ignored by the compiler.

RETURNS (returns-descriptor)

An option specifying that the procedure is invoked by a function reference, as well as specifying the attributes of the function value returned. One of the possible attributes is TYPE. The syntax of the TYPE attribute is:

[(TYPE (reference)];

RETURNS must be specified for functions. It is invalid for procedures that are invoked by CALL statements.

For valid return descriptors, see the RETURN statement section of Section 7.7.

A function is a procedure that returns a value and that receives control when its name is referenced in an expression. There are two types of functions:

• PL/I built-in functions
• User-written functions

A user-written function must have the following elements:

• The RETURNS option on the PROCEDURE statement
• A value on the RETURN statement; the value must be of a data type that is valid for conversion to the one specified in the RETURNS option

For example:

ADDER: PROCEDURE (X,Y) RETURNS (FLOAT); DECLARE (X,Y) FLOAT; RETURN (X+Y); END;

The function ADDER has two parameters, X and Y. They are floating-point binary variables declared within the function. When the function is invoked by a function reference, it must be passed two arguments to correspond to these parameters. It returns a floating-point binary value representing the sum of the arguments. The function ADDER can be referenced as follows:

TOTAL = ADDER(5,6);

The arguments in the reference to ADDER are converted to FLOAT.

If a function has no parameters, you must specify a null argument list; otherwise, the compiler treats the reference as a reference to an entry constant. Specify a null argument list as follows:

GETDATE = TIME_STAMP();

This assignment statement contains a reference to the function TIME_STAMP, which has no parameters.

This rule applies to PL/I built-in functions as well; however, if you declare a PL/I built-in function explicitly with the BUILTIN attribute, you need not specify the empty argument list. For example:

DECLARE P POINTER, NULL BUILTIN; . . . P = NULL;

This example assigns a null pointer value to P. Without the declaration of NULL as a built-in function, the assignment statement would have been as follows:

P = NULL();

7.3 ENTRY Statement

The ENTRY statement defines an alternate entry point to a procedure. Its format is as follows:

entry-name

A 1- to 31-character label for the entry point. Specifying the entry name declares the name as an entry constant. The scope of the name is external if the ENTRY statement is contained in an external procedure, and is internal if it is contained in an internal procedure.

parameter,...

One or more parameters that the procedure requires at this entry point. Each parameter specifies the name of a variable declared in the block to which this ENTRY statement belongs. The parameters must correspond, one to one, with arguments specified for the procedure when it is invoked via the ENTRY statement.

RECURSIVE or NONRECURSIVE

An option that indicates (for program documentation) that the procedure will or will not be invoked recursively. In standard PL/I, the RECURSIVE option must be specified for a procedure to be invoked recursively. However, any procedure can be invoked recursively, and the RECURSIVE and NONRECURSIVE options are ignored by the compiler.

RETURNS (returns-descriptor)

For an entry that is invoked as a function reference, an option giving the data type attributes of the function value returned.

One of the possible attributes is TYPE. The syntax of the TYPE attribute is:

[(TYPE (reference)];

For entry points that are invoked by function references, the RETURNS option is required; for procedures that are invoked by CALL statements, the RETURNS option is invalid.

Restrictions

An ENTRY statement is not allowed in a begin block, in an ON-unit, or in a DO group except for a simple DO.

You should avoid unnecessary use of ENTRY statements, because their effect is detrimental to the overall optimization of the program and they make debugging more complicated.

7.3.1 Specifying Entry Points

The entry points of a procedure are the points at which it can be invoked. The PROCEDURE statement specifies one entry point. You can specify additional entry points with ENTRY statements within the procedure block. ENTRY statements are allowed anywhere except as specified in the restrictions described in Section 7.3.

The labels used on PROCEDURE and ENTRY statements declare those names as entry constants. The scope of the declarations is internal if the PROCEDURE and ENTRY statements appear in internal procedures, and external if they appear in external procedures.

You declare an entry name in the block containing the procedure to which the entry point belongs. For example:

P: PROCEDURE; DECLARE E: ENTRY; Q: PROCEDURE; DECLARE E FIXED BINARY; END Q; END P;

The entry names E and Q are declared in procedure P. Within procedure Q, E is declared as a fixed-point binary variable. This does not conflict with the declaration of E as an entry in procedure P.

You can invoke an entry point by using the appropriate entry constant as the reference in a CALL statement or function reference. Invoking an entry point enters a procedure at the specified point and activates the procedure block that contains the entry point.

If the CALL statement or function reference invokes an entry point in an external procedure, the entry constant must be declared with the ENTRY attribute, as in Example 7-3. The declaration of an external constant must also describe the parameters for that entry point, if any. For example:

DECLARE PITCH ENTRY (CHARACTER(*), FIXED BINARY(15));

The identifier PITCH is declared as an entry constant. When the procedure containing this declaration is linked to other procedures, one of the external procedures must define an entry point named PITCH, either as the label of a PROCEDURE statement or as the label of an ENTRY statement.

The data type attributes in parentheses (known as "parameter descriptors") are the data types of the parameters that are defined elsewhere for the entry point PITCH. Arguments of these types must be supplied when PITCH is invoked.

If PITCH is to be used as a function, the DECLARE statement must also include a RETURNS attribute to describe the attributes of the returned value, as in the following example:

DECLARE PITCH ENTRY (CHARACTER(*), FIXED BINARY(15)) RETURNS(FIXED);

Within the scope of this DECLARE statement, the entry constant PITCH must be used in a function reference. The function reference will invoke the external entry point, and a returned fixed-point binary value will become the value of the function reference.

7.3.2 Multiple Entry Points

A procedure can be entered at more than one point. However, only one entry point can be specified by a PROCEDURE statement; additional entry points are declared with ENTRY statements.

The rules governing the declaration of multiple entry points follow:

• A particular parameter need not be specified in all of a procedure's entry points (including the point defined by the PROCEDURE statement). However, a reference to the parameter is valid only if the procedure was invoked through one of the entries specifying the parameter.
• In a procedure that has multiple entry points, a RETURN statement must be compatible with the entry point by which the procedure was invoked. If the entry point does not have a RETURNS option, the RETURN statement must not specify a return value. (In addition, it must be invoked as a "subroutine"-that is, with the CALL statement.) If the entry point has a RETURNS option, the RETURN statement must specify a return value that is valid for conversion to the data type specified in the RETURNS option.
• An ENTRY statement is not executable. If control reaches it sequentially, control immediately continues to the next statement.

The following example shows a procedure with two alternative entry points:

QUEUES: PROCEDURE(ELEMENT,QUEUE_HEAD); . . . ADD_ELEMENT: ENTRY(ELEMENT); . . . REMOVE_ELEMENT: ENTRY(ELEMENT);

This procedure can be entered by CALL statements that reference QUEUES, ADD_ELEMENT, or REMOVE_ELEMENT. If invoked at QUEUES, the procedure must be passed two parameters. If invoked at either of the alternative entries ADD_ELEMENT or REMOVE_ELEMENT, the procedure must be passed only one parameter.

When this procedure is entered at either alternative entry point, the entire block beginning at QUEUES is activated, but execution begins with the first executable statement following the entry point.

7.4 CALL Statement

The CALL statement transfers control to an entry point of a procedure and optionally passes arguments to the procedure. The format of the CALL statement is as follows:

CALL entry-name [(argument,...)];

entry-name

The name of an external or internal procedure that does not have the RETURNS attribute. The entry name can also be an entry variable or a reference to a function that returns an entry value.

[(argument,...)]

The argument list to be passed to the called procedure. If specified, the arguments must correspond to the parameters specified in the PROCEDURE or ENTRY statement that identifies the entry name of the called procedure.

You must enclose arguments in parentheses. Multiple arguments must be separated by commas.

You can use the CALL statement to call an internal or external procedure. The following example illustrates a main procedure, CALLER, and a call to an internal procedure, PUT_OUTPUT. PUT_OUTPUT has two parameters, INSTRING and OUTFILE, that correspond to the arguments LINE and DEVICE specified in the CALL statement.

CALLER: PROCEDURE OPTIONS(MAIN); . . . CALL PUT_OUTPUT(LINE,DEVICE); . . . PUT_OUTPUT:PROCEDURE(INSTRING,OUTFILE); . . . END PUT_OUTPUT; END CALLER;

7.5 Parameters and Arguments

A PL/I procedure can invoke other procedures, as well as pass values to and receive them from the invoked procedure. Values are passed to an invoked procedure by means of arguments written in the procedure invocation. Values are returned to the invoking procedure by means of parameters and also, in the case of functions, by specifying a value in the function's RETURN statement.

You can specify arguments for a subroutine (invoked by a CALL statement) or for a function (invoked by a function reference). Subroutines and functions return values by different means.

• A subroutine can return values only through a list of parameters. A subroutine must not specify a return value in its RETURN statement, and the declaration of an external entry point must not include the RETURNS attribute if the entry point is to be invoked as a subroutine. Instead, you can return values by assigning them, within the invoked subroutine, to the variables listed as parameters.
• A function can return values through its parameter list like a subroutine and, in addition, must return a single value that becomes the value of the function reference in the invoking procedure; this value is specified in the function's RETURN statement. The attributes of this returned value are specified within the invoking procedure, in the function's PROCEDURE or ENTRY statement, or in the declaration of the external entry constant or entry variable used to invoke the function.

Example 7-1 illustrates the relationship between arguments (specified in a CALL statement) or function reference and parameters (specified in a PROCEDURE or ENTRY statement).

Example 7-1 Parameters and Arguments

CALLER:PROCEDURE; DECLARE COMPUTER EXTERNAL ENTRY (1) (FIXED BINARY (7), CHARACTER (80) VARYING); CALL COMPUTER (5,'ABC'); (2) END CALLER; COMPUTER:PROCEDURE (X,Y); (3) DECLARE X FIXED BINARY (7); (4) DECLARE Y CHARACTER (80) VARYING; END COMPUTER;