Kednos PL/I for OpenVMS Systems
Reference Manual


Previous Contents Index

2.2.18 ENVIRONMENT Attribute

The ENVIRONMENT file description attribute is used in DECLARE, OPEN, and CLOSE statements to specify options that define file characteristics specific to the OpenVMS file system and options that request special processing not available in the standard PL/I language. The format of the ENVIRONMENT attribute is:


option,...

One or more keyword options separated by commas.

Summary of Options

The following items with asterisks (*) are options you can specify in a CLOSE statement.
APPEND  
BACKUP_DATE(variable-reference)  
BATCH*  
BLOCK_BOUNDARY_FORMAT  
BLOCK_IO  
BLOCK_SIZE(expression)  
BUCKET_SIZE(expression)  
CARRIAGE_RETURN_FORMAT  
CONTIGUOUS  
CONTIGUOUS_BEST_TRY  
CREATION_DATE(variable-reference)  
CURRENT_POSITION  
DEFAULT_FILE_NAME(character-expression)  
DEFERRED_WRITE  
DELETE*  
EXPIRATION_DATE(variable-reference)  
EXTENSION_SIZE(expression)  
FILE_ID(variable-reference)  
FILE_ID_TO(variable-reference)  
FILE_SIZE(expression)  
FIXED_CONTROL_SIZE(expression)  
FIXED_CONTROL_SIZE_TO(variable-reference)  
FIXED_LENGTH_RECORDS  
GROUP_PROTECTION(character-expression)  
IGNORE_LINE_MARKS  
INDEX_NUMBER  
INITIAL_FILL  
MAXIMUM_RECORD_NUMBER(expression)  
MAXIMUM_RECORD_SIZE(expression)  
MULTIBLOCK_COUNT(expression)  
MULTIBUFFER_COUNT(expression)  
NO_SHARE  
OWNER_GROUP(expression)  
OWNER_ID(expression)  
OWNER_MEMBER(expression)  
OWNER_PROTECTION(character-expression)  
PRINTER_FORMAT  
READ_AHEAD  
READ_CHECK  
RECORD_ID_ACCESS  
RETRIEVAL_POINTERS(expression)  
REVISION_DATE(variable-reference)*  
REWIND_ON_CLOSE*  
REWIND_ON_OPEN  
SCALARVARYING  
SHARED_READ  
SHARED_WRITE  
SPOOL*  
SUPERSEDE  
SYSTEM_PROTECTION(character-expression)  
TEMPORARY  
TRUNCATE  
USER_OPEN(entry-name)  
WORLD_PROTECTION(character-expression)  
WRITE_BEHIND  
WRITE_CHECK  

The previous list of options to the ENVIRONMENT attribute are described in detail in the Kednos PL/I for OpenVMS Systems User Manual.

You can specify all ENVIRONMENT options in OPEN statements. You can also specify all ENVIRONMENT options except those that require variable references in DECLARE statements. Certain disposition options (noted in the list) can be specified in CLOSE statements.

Some ENVIRONMENT options require you to specify a value. In a DECLARE statement, you must use a literal constant to supply the value required. In OPEN and CLOSE statements, however, you can use expressions (including but not limited to literal constants) to supply the values.

Any option that does not require a value can optionally be specified with a Boolean expression that indicates whether the option is to be enabled (if true) or disabled (if false). For example:


DECLARE IFDELETE BIT(1); 
   .
   .
   .
OPEN FILE (XYZ) ENVIRONMENT(DELETE(IFDELETE)); 

This DELETE option specifies a Boolean variable whose value can be true or false at run time. Boolean values must be specified as constants in DECLARE statements. You can specify Boolean values as expressions (including constants) in OPEN statements and CLOSE statements.

2.2.19 EXTERNAL Attribute

The EXTERNAL attribute declares an external name, that is, a name whose value can be known to blocks outside the block in which it is declared. The format of the EXTERNAL attribute is:


The EXTERNAL attribute is implied by the FILE, GLOBALDEF, and GLOBALREF attributes. EXTERNAL is also implied by declarations of entry constants (declarations that contain the ENTRY attribute but not the VARIABLE attribute). For variables, the EXTERNAL attribute implies the STATIC attribute.

Restrictions

The EXTERNAL attribute directly conflicts with the AUTOMATIC, BASED, and DEFINED attributes.

The EXTERNAL attribute cannot be applied to minor structures, members of structures, parameters, or descriptions in an ENTRY or RETURNS attribute.

The EXTERNAL attribute is invalid for variables that are the parameters of a procedure.

If a variable is declared as EXTERNAL STATIC INITIAL:

2.2.20 FILE Attribute

The FILE attribute declares a file constant or file variable. The format of the FILE attribute is:

FILE 

The FILE attribute is implied by any of the following file description attributes:
DIRECT OUTPUT SEQUENTIAL
ENVIRONMENT PRINT STREAM
INPUT RECORD UPDATE
KEYED    

See Table 9-2 for definitions of these file description attributes.

If the VARIABLE attribute is not specified, the FILE attribute declares a file constant. If the INTERNAL attribute is not specified, the file has the EXTERNAL attribute by default. All external declarations of a file constant are associated with the same file.

Restrictions

The FILE attribute conflicts with all other data-type attributes. If the FILE attribute is used to declare a variable or parameter, no file description attributes may be specified. If the VARIABLE attribute is not specified, no storage-class attributes are allowed.

2.2.21 FIXED Attribute

The FIXED attribute indicates that the variable so declared is arithmetic with a fixed number of fractional digits. Such variables are called fixed-point (as opposed to floating-point) variables because the decimal point and binary point are fixed relative to the representation of the value. The format of the FIXED attribute is:

FIXED [(precision[,scale-factor])] 

precision

The precision is the number of decimal or binary digits used to represent values of the variable.

scale-factor

Scale factor indicates how much of the precision is to be used for fractional digits.

When you specify the FIXED attribute in a DECLARE statement, you can specify either the BINARY or the DECIMAL attribute to indicate a binary or decimal fixed-point variable. For example, the attributes FIXED BINARY(31,5) define a variable that takes fixed-point binary values of up to a maximum of 31 bits, 5 of which are fractional. The attributes FIXED DECIMAL(10,2) define a variable that takes fixed-point decimal values of up to 10 decimal digits, 2 of which are fractional. PL/I supplies default attributes for attributes that you do not specify (as shown in the following table).

You normally use fixed-point binary data to represent integers. The precision of a fixed-point binary variable must be in the range 1 through 31. The scale factor can be in the range -31 through 31.

You can also use fixed-point decimal data, which can represent larger absolute values. You use fixed-point data whenever arithmetic values must be precise to a specified number of fractional digits. For a fixed-point decimal value, the precision must be in the range 1 through 31 (decimal digits). The scale factor, if specified, must be greater than or equal to zero and less than or equal to the specified precision.

If the scale factor is omitted, zero is used (that is, an integer variable is declared).

The default values given for unspecified related attributes are:
Attributes Specified Defaults Supplied
FIXED BINARY (31,0)
FIXED BINARY (31,0)
FIXED DECIMAL (10,0)

Restriction

The FIXED attribute directly conflicts with all data-type attributes except BINARY and DECIMAL.

2.2.22 FLOAT Attribute

The FLOAT attribute indicates that a variable is a floating-point arithmetic item. The format of the FLOAT attribute is:

FLOAT [(precision)] 

precision

You can specify the precision within the following ranges:

When you specify the FLOAT attribute in a DECLARE statement, you can specify either the BINARY or the DECIMAL attribute. The default values given for unspecified related attributes are:
Attributes Specified Defaults Supplied
FLOAT BINARY (24)
FLOAT BINARY (24)
FLOAT DECIMAL (7)

Restriction

The FLOAT attribute directly conflicts with all data-type attributes except BINARY and DECIMAL.

2.2.23 GLOBALDEF Attribute

The GLOBALDEF attribute declares an external variable or an external file constant. It can optionally control the program section in which the data is allocated. The format of the GLOBALDEF attribute is:

GLOBALDEF [ (psect-name) ] 

psect-name

The name of a program section. A program section name can have up to 31 characters, which can consist of the alphanumeric characters, dollar signs ($), and underscores (_). The first character cannot be numeric (0 through 9). PL/I converts all lowercase letters to uppercase when it compiles a source program. The names abc, ABC, Abc, and so on all refer to the same program section.

If you do not specify a program section name, PL/I places the definition for the name in the default program section associated with the variable.

The GLOBALDEF attribute implies the EXTERNAL attribute. The GLOBALDEF attribute also implies STATIC except when used for file constants.

Restrictions

The GLOBALDEF attribute conflicts with the GLOBALREF and INTERNAL attributes. GLOBALDEF cannot be used with ENTRY constants.

Only one procedure in a program can declare a particular external variable with the GLOBALDEF attribute.

For complete details on using the GLOBALDEF attribute to declare global external symbols, see Section 5.4.

2.2.24 GLOBALREF Attribute

The GLOBALREF attribute indicates that the declared name is a global symbol defined in an external procedure. The format of the GLOBALREF attribute is:

GLOBALREF 

The GLOBALREF attribute implies the EXTERNAL attribute. The corresponding name must be declared in another procedure with the GLOBALDEF attribute or, if the external procedure is written in another programming language, with its equivalent in that language.

Restriction

The GLOBALREF attribute conflicts with the INITIAL, GLOBALDEF, and INTERNAL attributes. If GLOBALREF is specified with the FILE attribute, you cannot specify any other file description attributes.

See Section 5.4 for information about using this attribute.

2.2.25 INITIAL Attribute

The INITIAL attribute provides an initial value for a declared variable. The format of the INITIAL attribute is:


initial-element

A construct that supplies a value for the initialized variable. The value must be valid for assignment to the initialized variable. If the initialized variable is an array, a list of initial elements separated by commas is used to initialize individual elements. The number of initial elements must be 1 for a scalar variable and must not exceed the number of elements of an array variable. Each initial element must have one of the following forms:

The iteration factors are nonnegative integer-valued expressions that specify the number of successive array elements to be initialized with the following value.

An asterisk ( * ) following the iteration factor specifies that the corresponding array elements are to be skipped during the initialization.

You can use a replication factor in combination with an iteration factor in initializing a string constant. For example, the following two statements are equivalent:


INITIAL ((10)('ABCABC')) 
 
INITIAL ((10)((2)'ABC')) 

The first statement uses an iteration factor exclusively; the second statement combines an iteration factor of 10 with a replication factor of 2.

A string constant must be parenthesized if it is used with an iteration factor, because this set of parentheses prevents the iteration factor from being interpreted as a string replication factor.


INITIAL ((10)'ABC') 

For example, the initial value is interpreted as a string replication factor, not an iteration factor, and cannot be used to initialize a whole array.

(*) valid-expression

A construct that initializes all elements of an array to the same value by means of the asterisk iteration factor. The expression must evaluate to a value that is valid for assignment to the initialized array. If the expression is a string constant, it must be parenthesized so that the asterisk iteration factor is not interpreted as a string replication factor. The possible expressions are:

An asterisk following the asterisk iteration factor results in no initializations being performed.

Examples

The following are examples of declarations that include the INITIAL attribute:


DECLARE RATE FIXED DECIMAL (2,2) STATIC INITIAL (.04); 
 
DECLARE SWITCH BINARY STATIC INITIAL ('1'B); 
 
DECLARE BELL_CHAR BINARY STATIC INITIAL ('07'B4); 
 
DECLARE OUTPUT_MESSAGE CHARACTER(20) STATIC 
            INITIAL ('GOOD MORNING'); 
 
DECLARE (A INITIAL ('A'), B INITIAL ('B'), 
      C INITIAL ('C')) STATIC CHARACTER; 
 
DECLARE QUEUE_END POINTER STATIC INITIAL(NULL()); 
 
DECLARE X(10,5) FIXED BIN(31) INITIAL ((*) -2);  /* Initializes all 50 
                                                    elements to -2    */ 
 
DECLARE 1 A(10), 
          2 B(10), 
            3 C(10) FIXED BIN(31) INITIAL ((*) 4);  /* Initializes all 
                                                       1000 elements 
                                                       to 4           */ 
 
DECLARE A(10) FIXED INIT ((5) 1,(5) 2);          /* Initializes the first 
                                                    5 elements to 1 and 
                                                    the second 5 elements 
                                                    to 2              */ 

The following declaration is not valid, because the asterisk iteration factor cannot be used to initialize part of an array; it can only be used to initialize all elements of the array to the same value:


DECLARE A(10) FIXED INIT ((5) 1,(*)2);           /* Invalid use of asterisk 
                                                    iteration factor  */ 

Restrictions

You cannot specify the INITIAL attribute for a structure variable. You must individually initialize the members of the structure.

You cannot specify the INITIAL attribute for a variable or member of a structure that has any of the following attributes:

If the initialized variable is STATIC, only constants, restricted expressions, and references to the NULL or EMPTY built-in functions are allowed. You can use these initial values with a constant iteration factor.

Variables and functions (except for parameters) occurring in an initial element (for automatic variables) must not be declared in the same block as the variable being initialized.


Previous Next Contents Index