Spaces, Tabs, and Line-End Characters

In addition to punctuation marks, PL/I accepts spaces, tabs, and line-end characters between identifiers, constants, and keywords.

The rules for entering spaces are:

• Between any identifiers, keywords, or constants
• Preceding or following punctuation marks that normally serve as delimiters, for example, tabs or commas

The line-end character is a valid punctuation mark between items in a PL/I statement except when it is embedded in a string constant. In a string constant, the line-end character is ignored. For example:

A = 'THIS IS A VERY LONG STRING THAT MUST BE CONTI

NUED ON MORE THAN ONE LINE IN THE SOURCE FILE';

This assignment statement gives the variable A the value of the specified character-string constant. (The line-end character in the constant is ignored.) Note that any tabs or spaces preceding NUED in the previous example will be included in the string.

The body of the statement consists of user-specified identifiers, literal constants, or PL/I keywords. Each element must be properly separated, either by special characters that punctuate the statement or by spaces or comments.

Keyword Statements

Keyword statements are identified by the PL/I keyword that requests a specific action. Examples of keyword statements are:

READ FILE (A) INTO (B);

GOTO LOOP;

DECLARE COUNTER FIXED BINARY (7);

In these examples, READ, GOTO, and DECLARE are keywords that identify these statements to PL/I.

Assignment Statements

PL/I identifies an assignment statement by syntax: an assignment statement consists of an identifier followed by an equal sign (=) , followed by an identifier or expression. For example:

A = B;

TOTAL = TOTAL + PRICE;

COUNTER = 0;

Null Statements

A null statement consists of only a semicolon (;). It indicates that PL/I is to perform no operation. For example:

IF A < B THEN GOTO COMPUTE;

ELSE;

This IF statement shows a common use of the null statement: as the target of an ELSE clause.

Data Definition and Assignment Statements

The DECLARE statement defines variable names:

DECLARE identifier [attribute ...];

Input/Output Statements

These statements identify files and data formats and perform input and output operations:

Program Structure Statements

These statements define the organization of the program into procedures, blocks, and groups:

Flow Control Statements

These statements change or interrupt the normal sequential flow of execution in a PL/I program:

Storage Allocation Statements

These statements acquire and control the use of storage in a PL/I program:

ALLOCATE

FREE

See . Summary of PL/I Statements gives a summary of the PL/I statements and their uses.

. Relationship of Block Activations

In the immediate dynamic descendance relationship, a block activation is the immediate dynamic descendant of the block that invoked it. At a given time, the chain of immediate dynamic descendants includes all existing block activations, starting with the activation of the main procedure and terminating in the current block activation. For example, in See . Relationship of Block Activations , the begin block is the immediate dynamic descendant of procedure B; the complete chain is B, begin block, A, Q. This chain is used for finding the applicable ON-unit when a condition is signaled.

The other relationship shown in See . Relationship of Block Activations applies to activations of nested blocks. An activation of a block X that is a begin block or internal procedure has an immediate parent activation, which is an activation of the block that immediately contains X. The chain of immediate parent activations extends back to an activation of the external procedure containing X. In See . Relationship of Block Activations , the parent chain for the begin block, procedure A, and procedure Q leads directly back to the activation of B, because each of these blocks is immediately contained in B. This chain is used in interpreting references.

When a block is activated, its immediate parent activation is determined as follows:

• If the block is an external procedure, it has no parent activation.
• If the block is a begin block, its immediate parent activation is the activation that invoked it. Therefore, the begin block is the immediate dynamic descendant of its immediate parent.
• If the block is an internal procedure invoked in block activation B by a reference to an entry constant (such as A in See . Relationship of Block Activations ) declared in block B, then the immediate parent of the new block activation of A is the activation of A in the parent chain starting at B.
• If the block is an internal procedure invoked by an entry variable, the parent activation is taken from the entry value. It was originally set when the complete entry value was generated by the assignment of an entry constant to an entry variable ( See Entry Data discusses entry data).

identifier

A 1- to 31-character user-supplied name. The name must be unique within the current block.

An identifier can consist of any of the alphanumeric characters A through Z, a through z, 0 through 9, dollar signs ($), underscores (_), pound sign (#) and at sign (@), but must begin with an alphabetic letter, dollar sign, underscore, pound sign or at sign.

attribute

One or more attributes of the name. Attribute keywords must be separated by spaces. They can appear in any order.

See Attributes for a list of the valid attribute keywords and their meanings.

The following are examples of simple declarations:

DECLARE COUNTER FIXED BINARY (7);

DECLARE TEXT_STRING CHARACTER (80) VARYING;

DECLARE INFILE FILE;

If you do not give a name specific attributes in a DECLARE statement or you reference an undeclared name, the name has the default attributes FIXED BINARY (31) AUTOMATIC. Note that the compiler issues a warning message whenever it gives default attributes to a name.

When you use this format, place names that share common attributes in parentheses and separate them with commas. The attributes that follow the parenthetical list of names are applied to all the named identifiers.

The following examples show factored declarations:

DECLARE (COUNTER, RATE, INDEX) FIXED BINARY (7) INITIAL (0);

DECLARE (INPUT_MESSAGE, OUTPUT_MESSAGE, PROMPT)

CHARACTER (80) VARYING;

In these declarations, the variables COUNTER, RATE, and INDEX share the attributes FIXED BINARY (7) and are given the initial value of zero. The variables INPUT_MESSAGE, OUTPUT_MESSAGE, and PROMPT share the attributes CHARACTER (80) VARYING.

You can also specify attributes, within the parentheses, attributes that are unique to specific variable names within the parenthetical list. Use the following format:

DECLARE (declaration-item, declaration-item [,declaration-item]) attribute ...

For example:

DECLARE (INFILE INPUT RECORD,

OUTFILE OUTPUT STREAM) FILE;

The DECLARE statement declares INFILE as a RECORD INPUT file and OUTFILE as a STREAM OUTPUT file.

You can nest parentheses, as shown in the following example:

DECLARE ( (INFILE INPUT, OUTFILE OUTPUT) RECORD,

SYSFILE STREAM ) FILE;

The DECLARE statement declares INFILE as a RECORD INPUT file, OUTFILE as a RECORD OUTPUT file, and SYSFILE as a STREAM file.

where each bound pair has the following format:

Specify one bound pair for each dimension of the array. The number of elements per dimension is defined by the bound pair. The extent of an array is the product of the numbers of elements in its dimensions. If you omit the lower bound, the lower bound for that dimension is 1 by default.

For example:

DECLARE SALARIES(100) FIXED DECIMAL(7,2);

This statement declares a 100-element array with the identifier SALARIES. Each element is a fixed-point decimal number with a total of seven digits, two of which are fractional. The identifier in the statement can be replaced with a list of declarations, to declare several objects with the same attributes. For instance:

DECLARE (SALARIES,PAYMENTS) (100) FIXED DECIMAL(7,2);

This declares SALARIES and another array, PAYMENTS, with the same dimensions and other attributes.

You can use an asterisk (*) as the bound pair when you declare arrays as parameters of a procedure. The asterisk indicates that the parameter can accept array arguments with any number of elements. If you specify one array dimension with an asterisk, you must specify all dimensions of that array with asterisks. See See Rules for Specifying Parameters for more information and examples.

For further details on how to specify the bounds of an array, and for examples of array declarations, see See Array Declarations .

See . Alphabetic Summary of PL/I Attributes lists the PL/I attributes. The sections following this table describe each attribute in detail.

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.

Restriction

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.

Restrictions

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.

Example

DECLARE EXT_ROUTINE ENTRY (ANY VALUE);

This statement identifies the procedure EXT_ROUTINE and indicates that the procedure accepts a single argument, of any data type, passed by value.

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.

Restrictions

The AREA attribute is not allowed in a returns descriptor. The AREA attribute conflicts with all other data-type attributes.

Restriction

The AUTOMATIC attribute conflicts with the following attributes (the specification of which implies that storage allocation is not to be automatic):

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 See , See Storage Classes .

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.

Restriction

The following attributes conflict with the BASED attribute:

The BASED attribute cannot be applied to minor structures, members of structures, parameters, or descriptions in an ENTRY or RETURNS attribute. See See Based Variables for more information.

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 floating-point value, the precision specifies the number of bits representing the mantissa of a floating-point number and must be in the range 1 through 53

The maximum floating-point binary precision is always 53. The default values applied to the BINARY attribute are listed in See . Default Values for BINARY Attribute :

Restrictions

The BINARY attribute directly conflicts with any other data-type attribute.

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.

Restriction

The BIT attribute directly conflicts with any other data-type attribute.

Restriction

The BUFFERED attribute conflicts with the UNBUFFERED attribute. Buffering only applies to RECORD files.

Restriction

When you specify the BUILTIN attribute, you cannot specify any other attributes.

Examples

OUTER: PROCEDURE;

DECLARE MAX FIXED BINARY STATIC INITIAL (10);

INNER: PROCEDURE;

DECLARE MAX BUILTIN, /* supersedes the variable */

(A,B,TEST) FIXED BIN(15);

A = 10;

B = 20;

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());

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.

Restriction

The CHARACTER attribute directly conflicts with any other data-type attribute.

condition-name

Name used for ON units to handle programmer-defined conditions.

Restrictions

The following attributes conflict with the CONTROLLED attribute:

AUTOMATIC

BASED

DEFINED

GLOBALDEF

GLOBALREF

READONLY

STATIC

VALUE

PARAMETER

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

See See Controlled Variables for more information.

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 1 through 15.

The default values applied to the DECIMAL attribute are listed in See . Default Values for the DECIMAL Attribute. .

Restrictions

The DECIMAL attribute conflicts with any other data-type attribute.

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 in See Defined Variables .

The DEFINED attribute can optionally specify a position within the referenced variable at which the definition begins. For example:

DECLARE ZIP CHARACTER(20),

ZONE CHARACTER(10)

DEFINED(ZIP) POSITION(4);

Restrictions

The following attributes conflict with the DEFINED attribute:

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

See See Defined Variables for more information.

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 defaults to 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 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:

• A relative file
• An indexed sequential file
• A sequential disk file with fixed-length records
• A sequential file opened with ENVIRONMENT(BLOCK_ID)

To to access a file both randomly and sequentially, use the SEQUENTIAL attribute instead of DIRECT.

Restriction

The DIRECT attribute conflicts with the SEQUENTIAL, STREAM, and PRINT attributes.

For a description of the attributes that are applied to files, see See Establishing the File's Attributes .

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) (dec and ansi dialects only)

Indicates 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.

OPTIONS(VARIABLE) conflicts with OPTIONS(C).

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 UNIX User's Manual.

OPTIONS (C)

Indicates that the called routine is written in C and should be called using the C language calling and return conventions. OPTIONS(C) conflicts with OPTIONS(VARIABLE).

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.

Restrictions

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.

Example

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.

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

F, FB, FS, or FBS (IBM Dialect Only)

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)

V, VB, VS, or VBS (IBM Dialect Only)

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 UNIX User's 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.

Note that IBM's implementation of PL/I lets you specify the ENVIRONMENT option only in a DECLARE statement. Keep this in mind when using ENVIRONMENT options if you require compatibility with IBM's implementation of PL/I.

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.

For a description of the attributes that are applied to files, see See Establishing the File's Attributes .

(`name')

The exact, case-sensitive, name of the external variable.

Unless you specify -m upper or --case=upper as an option to the pl1 command, do not declare a procedure or any other external symbol that will map to " main" (in lowercase). This will conflict with the library function "main" supplied in the Kednos PL/I for UNIX run-time library.

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, all blocks that declare the variable must initialize the variable with the same value.

The FILE attribute is implied by any of the following file description attributes:

See See . Summary of File Description Attributes 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.

For a description of the attributes that are applied to files, see See Establishing the File's Attributes .

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.

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) define a variable that takes fixed-point binary integer values of up to a maximum of 31 bits. 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 use fixed-point binary data to represent integers. The precision of a fixed-point binary variable must be in the range 1 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 listed in See . Default Values for Unspecified FIXED Attributes .

Restriction

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

precision

The range for a floating-point binary variable is 1 through 53. The range for a floating-point decimal variable is 1 through 15.

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 listed in See . Default Values for Unspecified FLOAT Attributes .

Restriction

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

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 ($), pound signs (#), at signs (@), and underscores (_). The first character cannot be numeric (0 through 9).

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 See External Variables .

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 See External Variables for information about using this attribute.

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:

• string-constant
• (replication-factor) string-constant
• (iteration-factor) (string-constant)
• (iteration-factor) (replication-factor) (string-constant)
• [(iteration-factor)] arithmetic-constant
• [(iteration-factor)] scalar-reference
• [(iteration-factor)] (scalar-expression)
• [(iteration-factor)] *

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.

The following initial value is interpreted as a string replication factor, not an iteration factor, and cannot be used to initialize a whole array:

INITIAL ((10)'ABC')

(*) 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:

• (string-constant)
• ((replication-factor) string-constant)
• arithmetic-constant
• scalar-reference
• (scalar-expression)
• (aggregate-expression)
• *

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 can specify the INITIAL attribute for an automatic structure variable only if you initialize the structure through an aggregate valued function. For example:

DECLARE 1 TEST_STRUC,

2 FIRST_MEMBER CHARACTER (8),

2 SEC_MEMBER FIXED BINARY(15);

DECLARE INIT_FUNCTION ENTRY(FIXED,FIXED)

RETURNS(1 LIKE TEST_STRUC);

DECLARE INPUT_STRUC LIKE TEST_STRUC

INITIAL (INIT_FUNCTION(X,Y));

In this example, INIT_FUNCTION is an external function that returns a structure matching TEST_STRUC.

To initialize a structure without using an aggregate valued function, 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:

DEFINED

ENTRY

FILE

LABEL

PARAMETER

UNION

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.

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 See . Summary of File Description Attributes .

The INPUT attribute can be supplied by default for a file, depending on the context of its opening. See See Establishing the File's Attributes for more information.

Restriction

The INPUT attribute conflicts with the OUTPUT, UPDATE, and PRINT attributes and with any data-type attribute other than FILE.

Restriction

The INTERNAL attribute directly conflicts with the EXTERNAL, GLOBALDEF, and GLOBALREF attributes.

Restriction

The KEYED attribute conflicts with the STREAM attribute and with any data-type attributes other than FILE.

Restriction

You cannot specify the LABEL attribute with any other data-type attribute, the INITIAL attribute, or any file description attributes.

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.

Restriction

The MEMBER attribute cannot be used with a major structure (that is, a structure variable with level 1).

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.

Examples

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.

Restriction

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.

Example

DCL E ENTRY (FIXED,FIXED OPTIONAL);

CALL E(1,2);

CALL E(1,);

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.

Examples

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 See , See Input and Output .

Restriction

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).

Example

The following example uses the PARAMETER keyword:

TEST: PROC( A, B );

DCL A CHAR(*) PARAMETER;

DCL B FIXED BIN PARM;

Refer to See Parameters and Arguments for a more information.

picture

A string of picture characters that define the representation of the variable.

See See Picture Characters for detailed information about picture characters, syntax, and examples.

Restriction

The PICTURE attribute conflicts with all other data-type attributes.

Restriction

The POINTER attribute conflicts with all other data-type attributes.

expression

An integer expression that specifies a position in the base. A value of 1 indicates the first character or bit.

Restriction

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 See Rules for Overlay Defining ).

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 See Precision and Scale of Arithmetic Data Types .

Print files are stream output files with special formatting characteristics. The PRINT attribute implies the OUTPUT and STREAM attributes.

For a description of the attributes that are applied to files, see See Establishing the File's Attributes .

Restriction

The PRINT attribute conflicts with the INPUT, RECORD, UPDATE, KEYED, SEQUENTIAL, and DIRECT attributes.

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.

Restrictions

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.

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.

For a description of the attributes that are applied to files, see See Establishing the File's Attributes .

Restriction

The RECORD attribute conflicts with the STREAM and PRINT attributes.

See See Using the REFER Option for more information.

Restriction

Note that you can only use the REFERENCE attribute in parameter descriptors.

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.

Restrictions

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 See Data Type Conversion of Operands and Expressions .

Restriction

The SEQUENTIAL attribute conflicts with the DIRECT, STREAM, and PRINT attributes.

The STATIC attribute is implied by the EXTERNAL attribute. For more information on STATIC and on other storage-class attributes, see See , See Storage Classes .

Restriction

The STATIC attribute directly conflicts with the BASED, CONTROLLED, DEFINED, and parameter attributes. The STATIC attribute cannot be applied to members of structures, parameters, or descriptions in an ENTRY or RETURNS attribute.

The STREAM attribute is implied by the PRINT attribute. It is also supplied by default for a file that is implicitly opened with a GET or PUT statement.

Specify the STREAM attribute in a DECLARE statement for a file identifier or in the OPEN statement that opens the file.

For a description of the attributes that are applied to files, see See Establishing the File's Attributes .

Restriction

The STREAM attribute directly conflicts with the RECORD, KEYED, DIRECT, SEQUENTIAL, and UPDATE attributes.

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 type declaration that is known in the current block. You can optionally enclose this name in parentheses.

The TYPE attribute causes the declaration 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 TYPE declaration. While logical structuring is copied, the level numbers themselves are not copied.

You can use the TYPE attribute on a declaration already containing the TYPE attribute.

Restrictions

A TYPE definition cannot be:

• A pointer-qualified variable
• A subscripted variable
• An entry variable
• A variable declaration that leads to direct or indirect circular declarations

The following examples show circular declarations. Do not use these types of declarations.

DECLARE 1 S11,

2 F1 CHARACTER(10),

2 F2 TYPE(S11); /* Direct circular */

DECLARE V1 TYPE(V2); /* Indirect circular */

DECLARE V2 TYPE(V3);

DECLARE V3 TYPE(V1);

DECLARE A1(10) TYPE(A2); /* Indirect circular */

DECLARE A2(10) TYPE(A3);

DECLARE A3(10) TYPE(A1);

DECLARE 1 S31,

2 F1 CHARACTER(10),

2 F2 TYPE(S32); /* Indirect circular */

DECLARE 1 S32,

2 F1 CHARACTER(10),

2 F2 TYPE(S33);

DECLARE 1 S33,

2 F1 CHARACTER(10),

2 F2 TYPE(S31);

• A structure variable with the BASED attribute and declarations with the REFER option if the TYPE variable does not have a BASED attribute.

For example:

DECLARE N FIXED BINARY;

DECLARE 1 VARIABLE_X BASED,

2 SIZE FIXED BINARY(15),

2 ITEMS (N REFER (VARIABLE_X.SIZE)) CHARACTER(80);

DECLARE VARIABLE_Y TYPE (VARIABLE_X); /* Error */

/* VARIABLE_Y not BASED */

When the actual call is made, the actual parameter list can stop at the parameter before the one declared with the TRUNCATE attribute. It is possible to pass an actual parameter in a position with the TRUNCATE attribute. Note that in this case, all remaining parameters must also be specified unless they have the TRUNCATE attribute.

Example

DCL E ENTRY (FIXED,FIXED TRUNCATE,FIXED);

CALL E(1);

CALL E(1,2,3);

The following call, however, will be invalid:

CALL E(1,2);

This call is invalid because the second parameter has the TRUNCATE attribute, so the third parameter must be specified.

Restriction

The UNALIGNED attribute conflicts with all data-type attributes other than BIT and CHARACTER.

level-number

The level number of the variable with which the declarations in the reference share storage.

identifier

Names the variable with which the declarations in the reference share storage. A variable declared with the UNION attribute must be a major or minor structure.

*

You can specify an asterisk (*) in place of the identifier name.

storage-class

The storage class specified for the structure. You can specify the storage class only on level 1.

Example

The following example uses the UNION attribute to acquire a date from the DATE built-in function and display it as three separate variables containing the year, month, and day. The major structure uses an asterisk (*) in place of the identifier name.

MAIN PROCEDURE OPTIONS(MAIN);

DECLARE 1 * UNION STATIC,

2 MC_DATE CHARACTER(6),

2 S_PARTS,

3 YEAR CHARACTER(2),

3 MONTH CHARACTER(2),

3 DAY CHARACTER(2);

MC_DATE = DATE();

PUT SKIP LIST (YEAR, MONTH, DAY);

END MAIN;

Specify the UPDATE attribute on a DECLARE statement for a file constant or on an OPEN statement to access the file for update. The UPDATE attribute implies the RECORD attribute.

For a description of the attributes that are applied to files, see See Establishing the File's Attributes .

Restriction

The UPDATE attribute directly conflicts with the INPUT, OUTPUT, STREAM, and PRINT attributes and with any data-type attribute other than FILE.

If you specify the FILE or ENTRY attribute in a DECLARE statement without the VARIABLE attribute, the defined object is assumed to be a file or entry constant.

The VARIABLE attribute is implied by the LABEL attribute. You can declare label constants only by using the label identifier in the program; you cannot define a label constant in a DECLARE statement.

Restriction

The VARIABLE attribute is not valid in a returns descriptor or in a parameter descriptor.

Restriction

The VARYING attribute directly conflicts with any data-type attribute other than CHARACTER.

Examples

DECLARE STRING CHARACTER(80) VARYING;

A variable named STRING is declared as a varying-length character string with a maximum length of 80 characters.

S: PROCEDURE OPTIONS(MAIN);

DECLARE STRING CHARACTER(80) VARYING;

STRING = 'PIE';

PUT LIST (LENGTH(STRING));

PUT LIST (MAXLENGTH(STRING));

PUT LIST (SIZE(STRING));

END;

The value returned by the built-in function LENGTH is 3, the length of the current value of the string. The value returned by the built-in function MAXLENGTH is 80, the maximum declared length. The value returned by the built-in function SIZE is 82, the maximum declared length plus two (for the two bytes that hold the value of the current length).

Attributes of Constants

Constants have attributes implied by the characters used to specify them. The following list describes the expression of constants and their attributes:

• A series of characters enclosed in apostrophes is assumed to be a string constant:
• If the letter B, which can be lowercase, is appended after the closing apostrophe, the constant is a bit-string constant, for example, '00010101'B. If the integer 2, 3, or 4 is appended to the letter B, the constant is a bit-string constant with the base 4, 8, or 16, respectively. Each digit occupies 2, 3, or 4 bits. For example, '17777'B3 is an octal constant that is represented internally as a string of 15 bits.
• If the constant does not have the letter B appended, it is a character-string constant even when it contains only the characters 0 and 1. (However, a character string of 0s and 1s can be converted by a simple assignment to a bit string.)
• If the constant is an integer, it has the attributes FIXED DECIMAL(n,0), where n is the number of digits in the integer. For example, the constant 1777 is a constant of type FIXED DECIMAL(4,0).
• Constants with an appended or embedded decimal point, but with no following exponent, are of type FIXED DECIMAL(p,q), where p is the total number of digits and q is the number of digits to the right of the decimal point.
• Consider this example where a fixed-point decimal constant has the following appended characters:

E digit ...

It is of type FLOAT DECIMAL(p), where p is the total number of digits in the fixed-point constant (that is, the total number to the left of the letter E).

Note that PL/I has no constants with the attributes FIXED BINARY, FLOAT BINARY. However, this presents no problems in programming because you can assign constants of any computational type to variables of any computational type and they are converted automatically to the target type.

You usually give values to binary variables by assigning decimal constants to them. For example:

I = 1;

This converts the decimal integer 1 and assigns the converted value to a fixed-point binary variable I. Consider the following example:

F = 1.333E-12;

This converts the floating-point decimal constant 1.333E-12 and assigns the converted value to a floating-point binary variable F.

Picture variables are usually given values by assigning fixed-point decimal constants. For example:

PAY_PIC = 123.44;

This assigns the fixed-point decimal value 123.44 to a picture variable PAY_PIC. The value of PAY_PIC is a pictured value, which is stored internally as a character string containing the characters 1, 2, 3, 4, and 4, along with any special formatting symbols defined for PAY_PIC.

Arithmetic Operands

The implied data types of constants are important primarily because of PL/I's rules for converting operands in an arithmetic operation. (Bit-string and character-string operations must have bit- and character-string operands, respectively.) All operations, including arithmetic operations, must be performed in a single data type, and automatic conversions are performed on arithmetic operands to make this possible. For example:

DECLARE X FLOAT DECIMAL (6);

X = X + 1.3;

In this example, the fixed-point decimal constant 1.3 is converted to floating-point decimal before the addition is performed. The rules for operand conversion are discussed in detail in See Derived Data Types for Arithmetic Operations .

For information about arithmetic operators, operands, and data conversions, see See , See Expressions and Data Type Conversions .

There is no form for a fixed-point binary constant, although constants of other computational types are convertible to fixed-point binary. A fixed-point binary variable usually receives given values by being assigned to an expression of another computational type or another fixed-point binary variable.

Internal Representation of Fixed-Point Binary Data

See . Internal Representation of Fixed-Point Binary Data shows the internal representation of fixed-point binary data. Storage for fixed-point binary variables is always allocated in a byte, word, or longword. For any fixed-point binary value:

• If p is in the range 1 through 7, a byte is allocated.
• If p is in the range 8 through 15, a word is allocated.
• If p is in the range 16 through 31, a longword is allocated.

The binary digits of the stored value go from right to left in order of increasing significance; for example, bit 6 of a FIXED BINARY (7) value is the most significant bit, and bit 0 is the least significant.

In all cases, the high-order bit (7, 15, or 31) represents the sign.

Fixed-Point Decimal Constants

A fixed-point decimal constant can have between 1 and 31 of the decimal digits 0 through 9 with an optional decimal point or sign, or both. If there is no decimal point, PL/I assumes it to be immediately to the right of the rightmost digit.

Some examples of fixed-point decimal constants are:

12

4.56

12345.54

-2

01.

The precision of a fixed-point decimal value is the total number of digits in the value. The scale factor is the number of digits to the right of the decimal point, if any. The scale factor cannot be greater than the precision.

Fixed-Point Decimal Variables

The attributes FIXED and DECIMAL are used to declare fixed-point decimal variables. The FIXED attribute is implied by DECIMAL.

If you do not specify the precision and the scale factor, the default values are 10 and 0, respectively.

The format of a declaration of a single fixed-point decimal variable is:

DECLARE identifier [FIXED] DECIMAL [(p[,q])];

Use in Expressions

You cannot use fixed-point decimal data with a nonzero scale factor in calculations with binary integer variables. If you must use the two types of data together, use the DECIMAL built-in function to convert the binary value to a scaled decimal value before attempting an arithmetic operation. For example:

DECLARE I FIXED BINARY,

SUM FIXED DECIMAL (10,2);

SUM = SUM + DECIMAL (I);

Internal Representation of Fixed-Point Decimal Data

Fixed-point decimal data is stored in packed decimal format. Each digit is stored in a half-byte, as shown in See . Fixed-Point Decimal Data Representation . Bits 0 through 3 of the last half-byte contain a value indicating the sign. Normally, the hexadecimal value C indicates a positive value and the hexadecimal value D indicates a negative value. (PL/I also supports using the hexadecimal values A, E, and F for positive values and the hexadecimal value B for negative values.)

Floating-Point Constants

A floating-point constant can have one or more of the decimal digits 0 through 9 (with an optional decimal point), followed by the letter E and from one to five decimal digits representing a power of 10. The floating-point value and the integer exponent can both be signed. The first portion of the value, to the left of the letter E, is called the mantissa. The value to the right of the letter E is called the exponent.

Some examples of floating-point constants are:

2E10

-3E8

32E-8

.45632E16

The decimal precision of each of these values is the number of digits in the mantissa.

If you write a constant without the E and the exponent, it is considered to be fixed-point decimal. However, you can use such constants anywhere in expressions involving floating- point data.

All floating-point constants are decimal.

Floating-Point Variables

The keyword FLOAT identifies a floating-point variable in a declaration.

A floating-point value can be either binary or decimal. Because the internal representation of floating-point variables is binary, it is recommended that you use FLOAT BINARY (which is the default) to declare variables, unless you need the properties of FLOAT DECIMAL. (The difference between FLOAT BINARY and FLOAT DECIMAL appears only when a conversion to another type, such as character, for doing I/O is necessary.) You should declare all floating-point variables using the same base.

To declare a single floating-point binary variable, specify a DECLARE statement as follows:

DECLARE identifier FLOAT [BINARY] [(p)];

Using Floating-Point Data in Expressions

You can use both integer and scaled decimal constants in floating-point expressions. An arithmetic constant is always converted to the appropriate internal representation for use in a floating-point operation. The target type for the conversion depends on the context. For example:

DECLARE X FLOAT BINARY (53);

X = X + 1.3;

Here, the constant 1.3 is converted to floating point when the expression is evaluated.

Such a conversion is normally done during compilation, but in some cases the constant is maintained in decimal until run time.

Floating-Point Data Formats

PL/I supports the IEEE standards of floating point formats -- the S (single precision) and T (double precision) types. See . Ranges of Floating-Point Formats summarizes the approximate ranges of the floating-point formats.

See . Ranges of Precision for Floating-Point Types summarizes the ranges of precision (sign bits, exponent bits, and fractional bits of accuracy) for each type. See IEEE S_floating Format and See IEEE T_floating Format describe the internal representation of floating-point data.

The PL/I compiler selects the appropriate floating-point type based on the precision you specify. The types are selected as shown in See . Floating-Point Types Used by PL/I , where p indicates precision.

IEEE S_floating Format

The following PL/I types are represented using S_floating data, which occupies four contiguous bytes:

• FLOAT BINARY (P) where P 24
• FLOAT DECIMAL (P) where P 7

Bits are labeled from the right, 0 through 31, as shown in See . IEEE S_floating Data Representation .

. IEEE S_floating Data Representation

The form of S_floating data is sign magnitude, with bit 31 the sign bit (0 for positive numbers, 1 for negative numbers), bits 30:23 an exponent, and bits 22:0 a normalized 24-bit fraction including the redundant most significant fraction bit not represented. The value of data is in the range 1.17549435E-38 (normalized) to 3.40282347E38. The precision is approximately one part in 2**23; that is, typically seven decimal digits.

When loaded into a 64-bit register, the S_floating value resides in bits 29-63.

IEEE T_floating Format

The following PL/I types are represented using T_floating data, which occupies eight contiguous bytes:

• FLOAT BINARY (P) where 24 < P 53
• FLOAT DECIMAL (P) where 7 < P 15

Bits are labeled from the right, 0 through 63, as shown in See . IEEE T_floating Data Representation

Character Picture Characters

lists the PL/I character picture characters and describes their meaning in a character pictured data item:

Examples of Character Picture Variable Definitions

The following examples show valid and invalid pictures given the following declaration for EMPLOYEE_NUMBER:

DECLARE EMPLOYEE_NUMBER PICTURE 'AAA999999X';

Picture Characters

See . Picture Characters summarizes the PL/I picture characters, their meaning, and whether they effect numeric interpretation and internal representation. The paragraphs following the table describe the picture characters and syntax. All picture characters are shown here in uppercase, but their lowercase equivalents can be used.