| Previous | Contents | Index |
The INPUT file description attribute indicates that the associated file is to be an input file. The format of the INPUT attribute is:
INPUT |
Specify the INPUT attribute on a DECLARE statement for a file constant or on an OPEN statement to access the file for reading.
You can specify the INPUT attribute with either the STREAM or the RECORD attribute. For a stream file, INPUT indicates that the file will be accessed with GET statements. For a record file, INPUT indicates that the file will be accessed only with READ statements.
For example:
DECLARE INFILE RECORD INPUT; OPEN FILE(INFILE); READ FILE(INFILE) INTO(RECORD_BUFFER); |
These statements declare, open, and access the first record in the input file INFILE.
For a description of the attributes that can be applied to files, see Table 9-2.
The INPUT attribute can be supplied by default for a file, depending on the context of its opening. See Section 9.1.3.3 for more information.
The INPUT attribute conflicts with the OUTPUT, UPDATE, and PRINT
attributes and with any data-type attribute other than FILE.
2.2.27 INTERNAL Attribute
The INTERNAL attribute limits the scope of an identifier to the block in which the identifier is declared and its dynamic descendents.
The format of the INTERNAL attribute is:
You only need to use the INTERNAL attribute to explicitly declare the scope of a file constant as internal. File constants, by default, have the EXTERNAL attribute.
The INTERNAL attribute directly conflicts with the EXTERNAL, GLOBALDEF,
and GLOBALREF attributes.
2.2.28 KEYED Attribute
The KEYED file description attribute indicates that you can randomly access records in the specified file. The KEYED attribute implies the RECORD attribute.
Specify KEYED in a DECLARE statement to identify a file or in an OPEN statement to open the file. For a description of the attributes that can be applied to files, see Table 9-2.
The KEYED attribute conflicts with the STREAM attribute and with any
data-type attributes other than FILE.
2.2.29 LABEL Attribute
The LABEL attribute declares a label variable; it indicates that values given to the variable will be statement labels. The format of the LABEL attribute is:
LABEL |
You cannot specify the LABEL attribute with any other data-type
attribute, the INITIAL attribute, or any file description attributes.
2.2.30 LIKE Attribute
The LIKE attribute copies the member declarations contained within a major or minor structure declaration into the structure variable to which it is applied. The format of the LIKE attribute is:
level-number identifier [attributes] LIKE reference |
level-number
The level number to which the declarations in the reference are copied.identifier
The variable to which the declarations in the reference are to be copied. The identifier must be preceded by a level number.attributes
Storage class or dimensions appropriate for the level number. You can specify a storage class and dimensions with a major structure, or you can specify dimensions with a minor structure.reference
The name of a major or minor structure that is known in the current block.
The LIKE attribute causes the structuring and member declarations of its reference to be copied, but not the name, storage class, or dimensioning (if any) of the reference. The exception to this rule is that the UNION attribute is propagated in a LIKE declaration. While logical structuring is copied, the level numbers themselves are not copied.
You can use the LIKE attribute on a structure already containing the
LIKE attribute.
2.2.31 LIST Attribute
The LIST attribute is used in the declaration of a formal parameter to indicate that the parameter can accept a list of actual parameters of arbitrary length. This list must contain at least one argument. To allow a list of zero or more arguments, you must declare the formal parameter with both the TRUNCATE attribute and the LIST attribute. The format of the LIST attribute is:
LIST |
The LIST attribute is valid only on formal parameters of external procedures. It is not supported for PL/I procedures. (To simulate list parameters in PL/I, use asterisk-extent arrays.)
You can only use the LIST attribute for the last formal parameter in an argument list.
DCL NUMBER FIXED BINARY; DCL LIST_PROC1 ENTRY (FIXED BINARY,FIXED BINARY LIST); DCL LIST_PROC2 ENTRY (FIXED BINARY,FIXED BINARY LIST TRUNCATE); CALL LIST_PROC1 (NUMBER,NUMBER); CALL LIST_PROC1 (NUMBER,NUMBER,NUMBER); CALL LIST_PROC2 (NUMBER); CALL LIST_PROC2 (NUMBER,NUMBER,NUMBER,NUMBER); |
You can optionally specify the MEMBER attribute in the declaration of a structure member (minor structure). A structure member has the MEMBER attribute implicitly. The format of the MEMBER attribute is:
MEMBER |
The MEMBER attribute cannot be used with a major structure (that is, a
structure variable with level 1).
2.2.33 NONVARYING Attribute
The NONVARYING attribute keyword explicitly states that a bit-string or character-string variable has a fixed length, not a varying length. Because NONVARYING is the default for bit and character strings, it need not be specified. The format of the NONVARYING attribute is:
2.2.34 OFFSET Attribute
The OFFSET attribute declares a variable that will be used to reference
a based variable within an area. The format of the OFFSET attribute is:
OFFSET [(area-reference)] |
area-reference
The name of a variable with the AREA attribute. The value of the offset variable will be interpreted as an offset within the specified area.
DECLARE MAP_SPACE AREA (40960),
MAP_START OFFSET (MAP_SPACE),
MAP_LIST(100) CHARACTER(80) BASED (MAP_START);
|
These declarations define an area named MAP_SPACE, an offset variable that will contain offset values within that area, and a based variable whose storage is located by the value of the offset variable MAP_START.
The area reference must be omitted if the OFFSET attribute is specified
within a returns descriptor, parameter declaration, or a parameter
descriptor. The OFFSET attribute conflicts with all other data-type
attributes.
2.2.35 OPTIONAL Attribute
The OPTIONAL attribute indicates that an actual parameter need not be specified in a call. If the actual parameter is not specified, a placeholder for it must be specified, and PL/I will pass a longword zero as the actual parameter in that position. There is an exception if there are no further actual parameters that are being supplied in the call. For that case, the programmer does not need to supply commas, although she may choose to do so to make the program more readable by humans. The format of the OPTIONAL attribute is:
OPTIONAL |
DCL E ENTRY (FIXED,FIXED OPTIONAL); CALL E(1,2); CALL E(1,); CALL E(1); |
The OUTPUT file description attribute indicates that data is to be written to, and not read from, the associated external device or file. The format of the OUTPUT attribute is:
OUTPUT |
Specify the OUTPUT attribute on a DECLARE statement for a file constant or on an OPEN statement to access the file for writing. You can specify the OUTPUT attribute with either the STREAM or the RECORD attribute. For a stream file, OUTPUT indicates that the file will be accessed with PUT statements. For a record file, OUTPUT indicates that the file will be accessed with only WRITE statements.
DECLARE OUTFILE RECORD OUTPUT; OPEN FILE(OUTFILE); WRITE FILE(OUTFILE) FROM(RECORD_BUFFER); |
These statements declare, open, and write a record to the output file OUTFILE.
For a description of the attributes that you can apply to files and the effects of combinations of these attributes, see Chapter 9.
The OUTPUT attribute conflicts with the INPUT and UPDATE attributes and
with any data-type attributes other than FILE. The OUTPUT attribute
also conflicts with ENVIRONMENT(INDEXED).
2.2.37 PARAMETER Attribute
A variable occurring in the parameter list of a PROCEDURE or ENTRY statement has the PARAMETER attribute implicitly. You can optionally use the PARAMETER keyword in the declaration of a variable name to state explicitly that it is a parameter. The format of the PARAMETER attribute is:
The following example uses the PARAMETER keyword:
TEST: PROC( A, B );
DCL A CHAR(*) PARAMETER;
DCL B FIXED BIN PARM;
.
.
.
|
Refer to Section 7.5 for a discussion on parameters.
2.2.38 PICTURE Attribute
The PICTURE attribute is used to declare a pictured variable. Pictured variables have fixed-point decimal attributes, but values of the variable are stored internally as character strings. The character string contains decimal digits representing the numeric value of the variable, plus special editing symbols described in the picture. The format of the PICTURE attribute is:
picture
A string of picture characters that define the representation of the variable.
See Section 3.2.5.1 for detailed information about picture characters, syntax, and examples.
The PICTURE attribute conflicts with all other data-type attributes.
2.2.39 POINTER Attribute
The POINTER attribute indicates that the associated variable will be used to identify locations of data. The format of the POINTER attribute is:
The POINTER attribute conflicts with all other data-type attributes.
2.2.40 POSITION Attribute
The POSITION attribute specifies the character or bit position in a defined variable's base at which the defined variable begins. The format of the POSITION attribute is:
expression
An integer expression that specifies a position in the base. A value of 1 indicates the first character or bit.
You can specify the POSITION attribute only in connection with DEFINED
and only when the defined variable satisfies the rules for string
overlay defining (see Section 5.8.2).
2.2.41 PRECISION Attribute
The PRECISION attribute specifies the maximum number of decimal or binary digits in a number. You can specify the precision of an arithmetic variable in any of the following formats, depending on the numeric base of the data item. The formats of the PRECISION attribute are:
precision
You can abbreviate the keyword PRECISION to PREC, or you can omit it entirely. If you use the keyword, the precision (and scale factor, if used) must immediately follow the keyword, which can be placed before or after any other attributes in the declaration. If you omit the keyword, the precision (and scale factor, if used) must follow the other attributes. For example, the following declarations are equivalent:
DCL A FIXED BIN(31); DCL A FIXED BIN PRECISION(31); DCL B FLOAT BIN(53); DCL B PREC(53) FLOAT BIN; DCL C FIXED DEC(5,2); DCL C FIXED DEC PREC(5,2);The precision of a floating-point data item is the number of decimal or binary digits in the mantissa of the floating-point representation.
scale-factor
The scale factor is the number of digits to the right of the decimal or binary point in fixed-point decimal or binary data. If no scale factor is specified with fixed-point data, the default is zero.
The ranges of values you can specify for the precision of each
arithmetic data-type, and the defaults applied if you do not specify a
precision, are summarized Section 3.2.1.
2.2.42 PRINT Attribute
The PRINT attribute is used to declare a print file. The file SYSPRINT, used as the default output by PUT statements, is a print file. The format of the PRINT attribute is:
|
|
Print files are stream output files with special formatting characteristics. The PRINT attribute implies the OUTPUT and STREAM attributes.
The PRINT attribute conflicts with the INPUT, RECORD, UPDATE, KEYED,
SEQUENTIAL, and DIRECT attributes.
2.2.43 READONLY Attribute
You can apply the READONLY attribute to any static computational variable whose value does not change during program execution. The format for the READONLY attribute is:
READONLY |
When you specify READONLY in conjunction with the declaration of a static variable, the PL/I compiler allocates storage for the variable based on the fact that its value does not change. A static variable with the READONLY attribute is given an initial value with the INITIAL attribute.
You can apply the READONLY attribute only to static computational variables. You must declare the variables with the EXTERNAL, STATIC, GLOBALREF, or GLOBALDEF attribute.
The value of a variable with the READONLY attribute cannot be modified. An attempt to modify a variable declared with the READONLY attribute will result in a run-time error.
The READONLY attribute conflicts with the ENTRY, FILE, LABEL, POINTER,
and VALUE attributes.
2.2.44 RECORD Attribute
The RECORD file description attribute indicates that data in an input or output file consists of separate records and that the file will be processed by record I/O statements. The format of the RECORD attribute is:
RECORD |
The RECORD attribute is implied by the DIRECT, SEQUENTIAL, KEYED, and UPDATE attributes.
You can specify this attribute in a DECLARE statement for a file constant or in the OPEN statement that accesses the file.
The RECORD attribute conflicts with the STREAM and PRINT attributes.
2.2.45 REFER Attribute
The REFER attribute defines dynamically self-defining structures. The format of the REFER attribute is:
REFER |
See Section 4.2.6.3 for more information on the REFER option.
2.2.46 REFERENCE Attribute
The REFERENCE attribute forces a parameter to be passed by reference. The format of the REFERENCE attribute is:
By default, most parameters are passed by reference in PL/I. However, the REFERENCE attribute is needed for passing an asterisk-extent array or character string by reference, because asterisk-extent parameters are passed by descriptor by default.
DECLARE E ENTRY((*) FIXED BIN(31) REFERENCE, FIXED BIN(31)); |
This is a declaration of a non-PL/I entry point that takes an asterisk-extent parameter by reference. The first parameter of the external procedure is an arbitrarily large array of longwords, and the second parameter is the size of the array. The external procedure should have some method of determining the size of the array being passed.
Note that you can only use the REFERENCE attribute in parameter
descriptors.
2.2.47 RETURNS Attribute
The RETURNS option must be specified on the PROCEDURE or ENTRY statement if the corresponding entry point is invoked as a function. The RETURNS attribute is specified with the ENTRY attribute to give the data-type of a value returned by an external function. The format of the RETURNS option and attribute is:
RETURNS (returns-descriptor...) |
returns-descriptor
One or more attributes that describe the value returned by the function to its point of invocation. The returned value becomes the value of the function reference in the invoking procedure. The attributes must be separated by spaces, except for attributes (the precision, for example) that are enclosed in parentheses.
The data types you can specify for a returns descriptor are restricted to scalar elements of either computational or noncomputational types. Areas are not allowed.
You can specify the extent of a character-string value as an asterisk (*) to indicate that the string can have any length. Otherwise, extents must be specified with restricted expressions.
You cannot use the RETURNS option or the RETURNS attribute for procedures that are invoked by the CALL statement.
The attributes specified in a returns descriptor in a RETURNS attribute must correspond to those specified in the RETURNS option of the PROCEDURE statement or ENTRY statements in the corresponding procedure. For example:
CALLER: PROCEDURE OPTIONS (MAIN);
DECLARE COMPUTER ENTRY (FIXED BINARY)
RETURNS (FIXED BINARY); /* RETURNS attribute */
DECLARE TOTAL FIXED BINARY;
.
.
.
TOTAL = COMPUTER (A+B);
|
The first DECLARE statement declares an entry constant named COMPUTER. COMPUTER will be used in a function reference to invoke an external procedure, and the function reference must supply a fixed-point binary argument. The invoked function returns a fixed-point binary value, which then becomes the value of the function reference.
The function COMPUTER contains the following:
COMPUTER: PROCEDURE (X) RETURNS (FIXED BINARY); /* RETURNS option */
DECLARE (X, VALUE) FIXED BINARY;
.
.
.
RETURN (VALUE); /* RETURN statement */
|
In the PROCEDURE statement, COMPUTER is declared as an external entry
constant, and the RETURNS option specifies that the procedure return a
fixed-point binary value to the point of invocation. The RETURN
statement specifies that the value of the variable VALUE be returned by
COMPUTER. If the data-type of the returned value does not match the
data-type specified in the RETURNS option, PL/I converts the value to
the correct data-type according to the rules given under Section 6.4.
2.2.48 SEQUENTIAL Attribute
The SEQUENTIAL file description attribute indicates that records in the file will be accessed in a sequential manner. The format of the SEQUENTIAL attribute is:
If you specify SEQUENTIAL, the RECORD attribute is implied.
Specify the SEQUENTIAL attribute in a DECLARE statement for a file constant or in the OPEN statement that accesses the file.
You can apply the SEQUENTIAL attribute to files with sequential, relative, or indexed sequential file organizations.
The SEQUENTIAL attribute conflicts with the DIRECT, STREAM, and PRINT attributes.
| Previous | Next | Contents | Index |