ENTRY

ENTRY is a data type attribute that declares a constant or variable whose value is an entry point, and describes the attributes of the parameters, if any, that are declared for the entry point. Its format is:

ENTRY [([parameter-list])]

where parameter-list is:

()|parameter-descriptor[,parameter-descriptor]...

where parameter-descriptor is:

attribute[attribute] ... |*|,|structure-descriptor

where structure-descriptor is:

1 [attribute] ... ,level[attribute] ... [,level[attribute]] ...

An arbitrary parameter-descriptor can be indicated by use of an asterisk ( * ) or by a blank parameter-descriptor position, as indicated by the commas. For example,

ENTRY(FIXED BIN, , FLOAT  /* Three parameters. The
                          second is of any data type. */
ENTRY(FIXED BIN, * ,FLOAT)/* Three parameters. The
                          second is of any data type. */
ENTRY(, , ,)   /* Four parameters of any data type. */
ENTRY()        /* No parameters allowed. */
ENTRY          /* Any number of parameters is allowed. */

The ENTRY attribute without the RETURNS option has an implicit RETURNS data type. It is determined by the I–n rule. External entries with the implicit RETURNS can be called as functions or procedures.

Open PL/I does not require that if any entry statement in a multiple entry procedure has a RETURNS option, then all entries must have one.

ENTRY can be used with or without the VARIABLE attribute. Used without the VARIABLE attribute, the ENTRY attribute declares a constant that is the name of an external procedure. In this case, each p is a list of attributes that is either identical to the attributes specified for the corresponding parameter in the external procedure, or is ANY. For example:

DECLARE E ENTRY(FIXED BINARY(15), POINTER);

In this example, E refers to a procedure that accepts a fixed binary and a pointer argument.

Used with the VARIABLE attribute, the ENTRY attribute specifies that the declared name is a variable of the data type entry, which can be assigned any procedure name. When the entry variable is called, it must hold an entry value that designates a PROCEDURE statement whose parameters have attributes that are identical (unless the attribute is ANY) to the corresponding attributes given by p1, p2, and so forth. Using the declaration for E from the previous example, a compatible procedure declaration would be as follows:

E: PROCEDURE(X,Y);
   DECLARE X FIXED BINARY(15); 
   DECLARE Y POINTER;

If a PROCEDURE statement has one or more parameters that are structures, the ENTRY attribute used to declare the procedure name must have a set of attributes for each member of the structure, including all substructures, as shown in the following example:

DECLARE E ENTRY(1,2 FIXED, 2 FLOAT, POINTER);

In the previous example, E is a procedure having two parameters; the first parameter is a structure with two members, and the second parameter is a pointer. The parameter attributes given in the ENTRY attribute include the level numbers and attributes of all members, as well as the level number and attributes of the parameter structure.

All string lengths or array bounds given in an ENTRY attribute must be exactly the same as those given in the parameters of the PROCEDURE statement. Programs that violate this rule may produce unpredictable results.

The ENTRY attribute can be used with the ANY, OPTIONS(VARIABLE), RETURNS(returns_descriptor), and VALUE options according to the following format:

DECLARE 
   entry_nameENTRY[(parameter_descriptor[VALUE]…)] 
        [OPTIONS(VARIABLE)] 
        [RETURNS(returns_descriptor)];

The RETURNS attribute is required for entry points that are invoked by function references and is invalid for procedures invoked by CALL statements. Parameter descriptors are not allowed if the ENTRY attribute is within a RETURNS descriptor.

The LIMITED attribute indicates that the values for the ENTRY variable can only be non-nested entry constants. When LIMITED is omitted, the ENTRY variable value can have any entry constants. The functionality of ENTRY LIMITED is equivalent to a C Function Pointer or a COBOL Procedure-Pointer.

The parameter descriptor lists attributes for each parameter and must include either the data type of the parameter or the attribute ANY. The VALUE attribute indicates that the corresponding argument is to be passed by immediate value. The OPTIONS(VARIABLE) option indicates that the specified external procedure can be invoked with a variable number of arguments. The following options can be specified as part of the OPTIONS(VARIABLE) attribute when declaring an ENTRY:

ASSEMBLER NOMAP [map-list]
COBOL NOMAPIN [map-list]
FORTRAN NOMAPOUT [map-list]
INTER NOEXECOPS
TASK RETCODE

The RETURNS(retums_descriptor) option gives the data type attributes of the function value returned for an entry invoked as a function reference. The VARIABLE attribute is not valid in a parameter descriptor or in a RETURNS descriptor.

The VALUE attribute can be used in an ENTRY declaration in conjunction with the data types Fixed Binary, Pointer, Character, Aligned Bit, Entry, or Float Binary. For more information, see the section VALUE.

If the ANY attribute is included as a parameter descriptor, the argument that corresponds to that parameter descriptor can be of any data type. If the argument is a variable, its address is passed to the called procedure. If the argument is a constant or an expression, a dummy argument is created and its address is passed to the called procedure. The following conversions take place when creating the dummy argument:

Written Data Type	Dummy Data Type
Bit (Unaligned)	Bit(`n`) Aligned, where `n` is the length of the string
Fixed Binary or Fixed Decimal(`p`,`O`)	Fixed Binary(31)
Char Varying	Char(`n`), where `n` is the length of the string

For more information, see the chapter Storage Classes and your Open PL/I User's Guide.

The OPTIONS(VARIABLE) attribute is used to indicate that it is valid for a discrepancy to exist between the number of parameter descriptors in the declaration of the procedure and the number of arguments in the argument list used to call the procedure.

The following rules apply when using the OPTIONS(VARIABLE) option:

If a procedure is called with more arguments than there are parameter descriptors, the trailing arguments are passed using the attributes of the last parameter descriptor. In this case, use of at least one parameter descriptor is required.
If a procedure is called with some arguments omitted, a null pointer is passed to the called routine in place of the missing argument. (The null pointer indicates an omitted argument.) An argument is considered to be omitted if two commas are found adjacent to one another in a call to a procedure, or if a comma comes after the left parenthesis or before the right parenthesis; that is, ( , a, ) indicates two missing arguments.
If a procedure is called with more arguments than there are parameter descriptors, and the trailing arguments are omitted (as indicated by adjacent commas), a null pointer is passed for each of the omitted arguments.

The following examples show how the ENTRY attribute can be used with the VALUE, ANY, OPTIONS(VARIABLE), and RETURNS(retums_descriptor) options. For a further description of these options, refer to each option by name within this chapter.

The following example causes the value of A to be converted to Fixed Binary(31) and the immediate value (25) to be passed directly to P5, followed by an immediate value representing the address of A:

DECLARE
   P5 ENTRY (FIXED BIN(31) VALUE, POINTER VALUE), 
   A FIXED BIN(15),
   B POINTER;
   A = 25;
   B = ADDR (A); 
   CALL P5(A,B);

The following example illustrates the use of the ENTRY attribute with the OPTIONS( VARIABLE) and ANY options:

DECLARE
   P1 ENTRY (FIXED BINARY(15), ANY) OPTIONS(VARIABLE),
   A FIXED BINARY(15),
   B FLOAT BINARY(23),
   C CHARACTER(1);
CALL P1(A, B);
CALL P1(A, C, B);

In the previous example, the second parameter descriptor is declared as ANY. In the first call to P1, B, a Float Binary(23) variable is the second argument passed; in the second call to P1, C, a Char(1) variable is passed. In both calls, the variable is passed by reference. Since the OPTIONS(VARIABLE) attribute is used, the second call to P1 passes argument three, B, using the attribute for parameter descriptor two, ANY. In the second call, the variable B is passed by reference.

The following example illustrates a procedure called with some arguments omitted.

DECLARE
   P2 ENTRY (FIXED BINARY(15), FIXED BINARY(15), 
      FIXED BINARY(15)) OPTIONS(VARIABLE),
   (A,B) FIXED BINARY(15);

CALL P2(A, ,B);

In the previous example, the arguments to be passed are A, a missing argument, and B. This configuration causes the address of A to be passed, followed by a null value, followed by the address of B.

The following example illustrates a procedure called with more arguments than there are parameter descriptors:

DECLARE
   P3 ENTRY (FIXED BINARY(15),FIXED BINARY(15)) 
      OPTIONS(VARIABLE),
   (A,B) FIXED BINARY(15),
   C FLOAT BINARY(31);
CALL P3 (A, B, ,);
CALL P3 (A, B, C);

In the previous example, the first call to P3 is declared with two parameter descriptors and called with four arguments, the last two being null. The addresses of the last two arguments will be represented by null values. The second call to P3 passes C as a Fixed Binary(15), since it is a trailing argument and is passed with the attribute of the last parameter descriptor. This configuration requires that C be converted from Float Binary to Fixed Binary, and that the address of the resulting temporary be passed.

The following example illustrates constants and expressions being passed with the ANY option:

DECLARE P4 ENTRY (ANY,ANY), 
   ( A, B ) FIXED BINARY(15); 
CALL P4( 3, 'ABC');
CALL P4( '1'B, AB );

In the first call to P4, the constant 3 will be converted to Fixed Binary(31) and the address of the temporary variable containing the converted value will be passed as the first argument; the character-string constant 'ABC' will be converted to Character(3) and its temporary address passed as the second argument. In the second call to P4, the bit-string constant '1' B will be converted to Bit(1) Aligned, AB will be converted to Fixed Binary(31), and the respective addresses of the temporaries will be passed to P4.

The following example illustrates the use of the RETURNS(retums_descriptor) option:

DECLARE F ENTRY(FIXED) RETURNS(POINTER); 
DECLARE G ENTRY(FLOAT)
   RETURNS(CHARACTER(32)VARYING);

In this example, F is declared as the name of a function procedure that returns pointer values. G is declared as the name of a function procedure that returns varying character-string values whose maximum length is 32 characters.