| Previous | Contents | Index |
The ALIGNED attribute controls the storage boundary of bit-string data in storage. The format of the ALIGNED attribute is:
ALIGNED |
You can specify the ALIGNED attribute in conjunction with the BIT attribute in a DECLARE statement to request alignment of a bit-string variable on a byte boundary. If you specify ALIGNED for an array of bit-string variables, each element of the array is aligned.
You can specify ALIGNED in the declaration of a nonvarying character-string variable. Specifying ALIGNED is not recommended with character strings, as all character strings are byte-aligned.
The ALIGNED attribute conflicts with the VARYING attribute and is
invalid with all data-type attributes other than BIT and CHARACTER. You
must specify either BIT or CHARACTER with the ALIGNED attribute.
2.2.2 ANY Attribute
The ANY attribute specifies that an entry's corresponding argument can be of any data type. This attribute is applicable only to the declaration of entry names denoting non-PL/I procedures. The format of the ANY attribute is:
If you specify ANY for a parameter, you cannot specify any data-type attributes for that parameter except CHARACTER(*). If ANY is used by itself, the parameter is passed by reference. If ANY is used with VALUE, the parameter is passed by immediate value. If ANY is used with CHARACTER(*), the parameter is passed by character descriptor.
DECLARE SYS$SETEF ENTRY (ANY VALUE); |
This statement identifies the system service procedure SYS$SETEF and
indicates that the procedure accepts a single argument, which can be of
any data type, to be passed by value.
(Note that PLI$STARLET contains declarations for all system services,
RTL routines, and utility routines.)
2.2.3 AREA Attribute
The AREA attribute defines an area variable. The format of the AREA attribute is:
AREA [(extent)] |
extent
The size of the area in bytes. The extent must be a nonnegative integer. The maximum size is 500 million bytes. The rules for specifying the extent are:
- If AREA is specified for a static variable declaration, extent must be a restricted integer expression. A restricted integer expression is one that yields only integral results and has only integral operands. Such an expression can use only the addition (+), subtraction ( - ), and multiplication (*) operators.
- If AREA is specified in the declaration of a parameter or in a parameter descriptor, you can specify extent as an integer constant or as an asterisk (*).
- If AREA is specified for an automatic or based variable, you can specify extent as an integer constant or as an expression. For automatic variables, the extent expression must not contain any variables or functions declared in the same block, except for parameters.
- If no extent is specified for the area, a default of 1024 bytes is provided. Kednos recommends explicitly specifying a size, because the default varies considerably between PL/I implementations.
The AREA attribute is not allowed in a returns descriptor. The AREA
attribute conflicts with all other data-type attributes.
2.2.4 AUTOMATIC Attribute
The AUTOMATIC attribute specifies, for one or more variables, that PL/I is to allocate storage only for the duration of a block. An automatic variable is not allocated storage until the block that declares it is activated. The storage is released when the block is deactivated. The format of the AUTOMATIC attribute is:
AUTOMATIC explicitly defines the storage-class of a variable, array, or major structure in a DECLARE statement. Because AUTOMATIC is the default for internal variables, you need not specify it.
The AUTOMATIC attribute conflicts with the following attributes (the specification of which implies that storage allocation is not to be automatic):
| BASED | GLOBALREF |
| CONTROLLED | PARAMETER |
| DEFINED | READONLY |
| EXTERNAL | STATIC |
| GLOBALDEF |
The AUTOMATIC attribute cannot be applied to minor structures, members of structures, parameters, or descriptions in an ENTRY or RETURNS attribute.
For a discussion of PL/I storage allocation, see Chapter 5.
2.2.5 BASED Attribute
The BASED attribute defines a based variable, that is, a variable whose actual storage will be denoted by a pointer or offset reference. The format of the BASED attribute is:
BASED [ (reference) ] |
reference
A reference to a pointer or offset variable or pointer-valued function. If the reference is to an offset variable, that variable must be declared with a base area. Each time a reference is made to a based variable without an explicit pointer or offset qualifier, the reference is evaluated to obtain the pointer or offset value.
The following attributes conflict with the BASED attribute:
| AUTOMATIC | GLOBALREF |
| CONTROLLED | PARAMETER |
| DEFINED | READONLY |
| EXTERNAL | STATIC |
| GLOBALDEF | VALUE |
The BASED attribute cannot be applied to minor structures, members of structures, parameters, or descriptions in an ENTRY or RETURNS attribute.
See Section 5.5 for more information on the BASED variable.
2.2.6 BINARY Attribute
The BINARY attribute specifies that an arithmetic variable has a binary base. The format of the BINARY attribute is:
When you specify the BINARY attribute for an identifer, you can also specify one of the following attributes to define the scale and precision of the data:
FIXED [(precision[,scale])] FLOAT [(precision)] |
FIXED indicates a fixed-point binary value and FLOAT indicates a floating-point binary value.
For a fixed-point binary value, the precision specifies the number of bits representing an integer and must be in the range 1 through 31. For a fixed-point binary value, the scale factor represents the number of bits to the right of the binary point and must be in the range -31 through 31. The magnitude of the scale factor must be less than or equal to the specified precision.
For a floating-point value, the precision specifies the number of bits representing the mantissa of a floating-point number and must be in the range:
The maximum floating-point binary precision is always 113 for OpenVMS VAX and 53 for OpenVMS Alpha. The default values applied to the BINARY attribute are:
| Attributes Specified | Defaults Supplied |
|---|---|
| BINARY | FIXED (31,0) |
| BINARY FIXED | (31,0) |
| BINARY FLOAT | (24) |
The BINARY attribute directly conflicts with any other data-type
attribute.
2.2.7 BIT Attribute
The BIT attribute identifies a variable as a bit-string variable. The format of the BIT attribute is:
BIT[(length)] |
length
The number of bits in the variable. If you do not specify a length, the default length is 1 bit. The length must be in the range 0 through 32,767.The rules for specifying the length are:
- If the attribute is specified for a static variable declaration or in a returns descriptor, length must be a restricted integer expression. A restricted integer expression is one that yields only integral results and has only integral operands. Such an expression can use only the addition (+), subtraction ( - ), and multiplication (*) operators.
- If the attribute is specified in the declaration of a parameter or in a parameter descriptor, you can specify length as a restricted integer expression or as an asterisk (*).
- If the attribute is specified for an automatic, based, controlled, or defined variable, you can specify length as an expression. In the case of automatic or defined variables, the expression must not contain any variables or functions that are declared in the same block except for parameters.
If specified, the length in parentheses must follow the keyword BIT.
If you give a variable the BIT attribute, you can also specify the ALIGNED attribute to request alignment of the variable on a byte boundary in storage.
The BIT attribute directly conflicts with any other data-type attribute.
2.2.8 BUILTIN Attribute
The BUILTIN attribute indicates that the name declared is the name of a PL/I built-in function. Within the block in which the name is declared, all references to the name will be interpreted as references to the built-in function or pseudovariable of that name. The format of the BUILTIN attribute is:
BUILTIN |
Use the BUILTIN attribute when you want to refer to a built-in function within a block in which the function's name has been used to declare a variable.
You also use the BUILTIN attribute when you want to invoke a built-in function that takes no arguments (such as the DATE function) and you do not want to include a null argument list.
When you specify the BUILTIN attribute, you cannot specify any other attributes.
OUTER: PROCEDURE;
DECLARE MAX FIXED BINARY STATIC INITIAL (10);
.
.
.
INNER: PROCEDURE;
DECLARE MAX BUILTIN;
TEST = MAX(A,B);
.
.
.
END INNER;
END OUTER;
|
The keyword MAX is used here as a variable name. In the internal procedure INNER, the MAX built-in function is invoked. Because the scope of the name MAX includes the internal procedure, the function must be redeclared with BUILTIN.
You can also use the BUILTIN attribute to declare PL/I built-in functions that have no arguments, if you want to invoke them without the empty argument list. For example:
DECLARE DATE BUILTIN; PUT LIST(DATE); |
Without the declaration, the PUT LIST statement would have to include an empty argument list for DATE:
PUT LIST(DATE()); |
The CHARACTER attribute identifies a variable as a character-string variable. The format of the CHARACTER attribute is:
length
The number of characters in a fixed-length string or the maximum length of a varying-length string. If not specified, a length of 1 is assumed. The length must be in the range 0 through 32,767 characters.The rules for specifying the length are:
- If the attribute is specified for a static variable declaration or in a returns descriptor, length must be a restricted integer expression.
- If the attribute is specified in the declaration of a parameter or in a parameter descriptor, you can specify length as a restricted integer expression or as an asterisk (*).
- If the attribute is specified for an automatic, based, or defined variable, you can specify length as an expression. In the case of automatic or defined variables, the expression must not contain any variables or functions that are declared in the same block except for parameters.
If specified, the length must immediately follow the keyword CHARACTER, and it must be enclosed in parentheses.
If you give a variable the CHARACTER attribute, you can also specify the attribute VARYING, NONVARYING, ALIGNED, or UNALIGNED.
The CHARACTER attribute directly conflicts with any other data-type
attribute.
2.2.10 CONDITION Attribute
You can optionally use the CONDITION attribute in a declaration to specify that the variable name is a condition name. You can specify INTERNAL or EXTERNAL scope attributes with the CONDITION attribute. The default scope is external. The format of the CONDITION attribute is:
condition-name
Name used for ON units to handle programmer-defined conditions.
The CONTROLLED attribute causes a variable's actual storage to be allocated and freed dynamically in generations, only the most recent of which is accessible to the program. The format of the CONTROLLED attribute is:
The following attributes conflict with the CONTROLLED attribute:
The CONTROLLED attribute cannot be applied to minor structures, members of structures, parameters, or descriptions in an ENTRY or RETURNS attribute.
See Section 5.6 for more information on the CONTROLLED variable.
2.2.12 DECIMAL Attribute
The DECIMAL attribute specifies that an arithmetic variable has a decimal base. The format of the DECIMAL attribute is:
When you specify the DECIMAL attribute for a variable, you can also specify the following attributes to define the scale factor and precision of the data:
FIXED (precision[,scale-factor]) FLOAT (precision) |
FIXED indicates a fixed-point value, and FLOAT indicates a floating-point decimal value.
(precision[,scale-factor])
The precision of a fixed-point decimal value is the total number of integral and fractional digits. The precision of a floating-point decimal value is the total number of digits in the mantissa. The precision for a fixed-point decimal value must be in the range 1 through 31; the scale factor, if specified, must be greater than or equal to 0 and less than or equal to the specified precision.The precision for a floating-point decimal value must be in the range:
- For OpenVMS VAX systems: 1 through 34
- For OpenVMS Alpha systems: 1 through 15
The default values applied to the DECIMAL attribute are:
| Attributes Specified | Defaults Supplied |
|---|---|
| DECIMAL | FIXED (10,0) |
| DECIMAL FIXED | (10,0) |
| DECIMAL FIXED (n) | (n,0) |
| DECIMAL FLOAT | (7) |
The DECIMAL attribute conflicts with any other data-type attribute.
2.2.13 DEFINED Attribute
The DEFINED attribute indicates that PL/I is not to allocate storage for the variable, but is to map the description of the variable onto the storage of another base variable. The DEFINED attribute provides a way to access the same data using different names. The format of the DEFINED attribute is:
variable-reference
A reference to a variable that has storage associated with it. The variable must not have the BASED, CONTROLLED, or DEFINED attribute. The variable and the declared variable must satisfy the rules given for defined variables in Section 5.8.
The DEFINED attribute can optionally specify a position within the referenced variable at which the definition begins. For example:
DECLARE ZONE CHARACTER(10)
DEFINED(ZIP) POSITION(4);
|
The following attributes conflict with the DEFINED attribute:
| AUTOMATIC | BASED | CONTROLLED |
| EXTERNAL | GLOBALDEF | GLOBALREF |
| INITIAL | PARAMETER | READONLY |
| STATIC | UNION | VALUE |
The DEFINED attribute cannot be applied to minor structures, members of structures, parameters, or descriptions in an ENTRY or RETURNS attribute.
See Section 5.8 for more information on defined variables.
2.2.14 DESCRIPTOR Attribute
The DESCRIPTOR attribute forces a parameter to be passed by descriptor to a non-PL/I procedure.
The format of the DESCRIPTOR attribute is:
You can use the DESCRIPTOR attribute only in parameter descriptors
See Section 7.5.1 for more information on rules for specifying
parameters.
2.2.15 DIMENSION Attribute
The DIMENSION attribute defines a variable as an array. It specifies the number of dimensions of the array and the bounds of each dimension. The format of the DIMENSION attribute is:
bound-pair
One or two expressions that indicate the number of elements in a single dimension of the array. You must specify the list of bound pairs immediately following the name of the identifier in the array declaration if the optional keyword DIMENSION or DIM is omitted; otherwise, you must specify the list of bound pairs immediately following the keyword DIMENSION or DIM. See the following examples.The maximum number of dimensions allowed is eight.
A bound pair can be specified:
- [lowerbound:]upperbound
This format of a bound pair specifies the minimum and maximum subscripts that can be used for the dimension. The number of elements is:
(upperbound - lowerbound) + 1
If the lower bound is omitted, it is assumed to be 1.- *
This format of a bound pair, when used to define a parameter for a procedure or function, indicates that the bounds are to be determined from the associated argument. If one bound pair is specified as an asterisk, all bound pairs must be specified as asterisks.
The following two declarations are exactly equivalent:
DECLARE A(10) FIXED BIN; DECLARE A FIXED BIN DIMENSION(10); |
The following two declarations are also equivalent:
DECLARE B(1:5,1:5) FLOAT DEC; DECLARE B DIM(1:5,1:5) FLOAT DEC; |
The DIRECT file description attribute indicates that a file will be accessed only in a nonsequential manner, that is, by key or by relative record number.
The format of the DIRECT attribute is:
DIRECT |
The DIRECT attribute implies the RECORD and KEYED attributes.
Specify the DIRECT attribute on a DECLARE statement for a file constant or on an OPEN statement to access the file. A file declared with the DIRECT attribute must be one of the following:
To to access a file both randomly and sequentially, use the SEQUENTIAL attribute instead of DIRECT.
The DIRECT attribute conflicts with the SEQUENTIAL, STREAM, and PRINT
attributes.
2.2.17 ENTRY Attribute
The ENTRY attribute 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. The format of the ENTRY attribute is:
parameter-descriptor
A set of attributes describing a parameter of the entry. Attributes describing a single parameter must be separated by spaces; sets of attributes (each set describing a different parameter) must be separated by commas. Parameter descriptors are not allowed if the ENTRY attribute is within a RETURNS descriptor.The following rules apply to the specification of a parameter descriptor for an array or structure:
- If the parameter is a structure, the level number must precede the attributes for each member.
- You must specify extents for a parameter using only integer constants, restricted integer expressions, or asterisks (*) .
- You cannot specify storage-class attributes.
OPTIONS (VARIABLE)
An option indicating that you can invoke the specified external procedure with a variable number of arguments. At least one parameter descriptor must be specified following the ENTRY keyword if OPTIONS(VARIABLE) is specified.This option is provided for use in calling non-PL/I procedures. For complete details on using OPTIONS (VARIABLE), see the Kednos PL/I for OpenVMS Systems User Manual.
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. For entry points that are invoked by function references, the RETURNS attribute is required; for procedures that are invoked by CALL statements, the RETURNS attribute is invalid.
The ENTRY attribute without the VARIABLE attribute implies the EXTERNAL attribute (and implies that the declared item is a constant), unless the ENTRY attribute is used to declare a parameter.
You must declare all external entry constants with the ENTRY attribute.
You cannot declare internal entry constants with the ENTRY attribute in the procedure to which they are internal. Internal entry constants are declared implicitly by the labels on the PROCEDURE or ENTRY statements of an internal procedure.
The ENTRY attribute conflicts with all other data-type attributes.
DECLARE COPYSTRING ENTRY (CHARACTER (40) VARYING,
FIXED BINARY(7))
RETURNS (CHARACTER(*));
|
This declaration describes the external entry COPYSTRING. This entry has two parameters: a varying-length character string with a maximum length of 40 and a fixed-point binary value. The RETURNS attribute indicates that COPYSTRING is invoked as a function and that it returns a character string of any length.
| Previous | Next | Contents | Index |