File No. S360-29 OS GC28-8201-2
IBM Systems Reference Library
IBM System/360 Operating System
PL/I (F) Language Reference Manual
This publication is a companion volume to IBM System/360 Operating System: PL/I (F) Programmer's Guide Form C28-6594. Together the two books form a guide to the writing and execution of PL/I programs under the control of an IBM System/360 Operating System that includes the PL/I (F) compiler. Third Edition (October, 1969) This is a major revision of, and obsoletes, Form C28-8201-1 and Technical Newsletters N33-6008, N33-6011. In addition to incorporating information from Technical Newsletters this new edition describes additional language implemented by Version 5 of the PL/I (F) Compiler. The contents of chapters 8 and 9 have been reorganized and now appear as three chapters: Chapter 8, Input and Output; Chapter 9, Stream-oriented Transmission; and Chapter 10, Record- oriented Transmission. In Chapter 11, Editing and String Handling, the section headed "The Picture Specification" has been completely rewritten. A new chapter, entitled "Optimization and Efficient Performance", has taken the place of Chapter 13 "Efficient Performance". The new chapter contains optimization information, and "Programming Techniques", previously part of the PL/I (F) Programmers Guide. Information on Data Mapping, extracted from the PL/I (F) Programmers Guide, now appears as Section K in Part II of this manual. Other changes to the text, and small changes to illustrations, are indicated by a vertical line to the left of the change; changed or added illustrations are denoted by the symbol • to the left of the caption. This edition applies to Release 18 of IBM System/360 Operating System, and to all subsequent releases until otherwise indicated in new editions or Technical Newsletters. Changes are continually made to the specification herein; before using this publication in connection with the operation of IBM systems, consult the latest IBM System/360 Bibliography SRL Newsletter, Form N20-0360, for the editions that are applicable and current. L
Requests for copies of IBM publications should be made to your IBM representative or the IBM branch office serving your locality. Address comments concerning the contents of this publication to IBM United Kingdom Laboratories Ltd., Programming Publications, Hursley Park, Winchester, Hampshire, England. C Copyright International Business Machines Corporation 1966, 1967, 1968, 1969 Preface
This publication is planned for use as a The TRKOFL and NCP options of the reference book by the PL/I programmer. It ENVIRONMENT attribute is not intended to be a tutorial publication, but is designed for the reader who already has a knowledge of the language • Abbreviations for the keywords BUFFERED and who requires a source of reference (BUF), EXCLUSIVE (EXCL), SEQUENTIAL material. (SEQL), and UNBUFFERED (UNBUF)
It is divided into two parts. Part I The following language changes are also contains discussions of concepts of the implemented: language. Part II contains detailed rules and syntactic descriptions. • Mandatory RETURNS keyword on PROOEDURE, %PROCEDURE, and ENTRY statements of Although implementation information is function procedures when the function included, the book is not a complete value attributes are explicitly specified description of the implementation environment. In general, it contains • Removal of ABNORMAL, NORMAL, USES, and information needed in writing a program; it SETS attributes does not contain all of the information required to execute a program. For further information on executing a program refer to the publication: IBM System/360 Operating System PL/I (F) Programmer's Guide. Requisite Publication
The following features, discussed in this publication, are implemented in the For information necessary to compile, fifth version of the F Compiler but are not linkage edit, and execute a program, the implemented in previous versions: reader should be familiar with the following publication: • Teleprocessing support IBM System/360 Operating System, PL/I (F) Programmer's Guide, Form C28-6594 The TRANSIENT attribute The PENDING condition Recommended Publications The G and R options of the ENVIRONMENT attribute The following publications contain other information that might be valuable to the • String-handling additions PL/I programmer or to a programmer who is learning PL/I: The TRANSLATE and VERIFY string built-in functions A PL/I Primer, Form C28-6808 The STRING pseudo-variable A Guide to PL/I for Commercial Programmers, Form C20-1651 • Adoption of halfword binary facilities for FIXED BINARY variables of precision A Guide to PL/I for FORTRAN Users, Form less than 16 C20-1637 Relaxation of REFER option restriction IBM System/360 Operating System, Queued Telecommunications Access Method • Optimization Message Processing Program Services, Form C30-2003 The ORDER and REORDER options of the PROCEDURE and BEGIN statements IBM System/360 Operating System, Queued Telecommunications Access Method • Usability improvements Message Control Program, Form O30-2005
Contents
Figures
Introduction
PL/I is a programming language designed to PL/I is much less machine dependent than cover as wide a range of programming most commonly used programming languages. applications as possible. A basic belief In the interest of efficiency, however, underlying the design of PL/I is that certain features are provided that allow programmers have common problems, machine dependence for those cases in which regardless of the different applications complete independence would be too costly. with which they may be concerned. The variety of features provided by PL/I, as well as the simplicity of the The language also is designed to reduce concepts underlying them, demonstrate the the cost of programming, including the cost versatility of the language, its of training programmers, the cost of universality, and the ease with which debugging, and, in particular, the cost of different subsets can be defined to meet program maintenance. the needs of different users.
Training programmers to use a particular language can often be expensive, Use of this Publication particularly if each programmer must be taught the entire language, even if he need use only a part of it. One of the prime This publication is designed as a reference features in the design of PL/I is book for the PL/I programmer. Its two-part modularity; in general, a programmer need format allows a presentation of the know only as much of the language as he material in such a way that references can requires to solve his problems. be found quickly, in as much or as little detail as the user needs. Another factor that contributes to Part I, "Concepts of PL/I," is composed programming cost is that a program of discussions and examples that explain frequently must be rewritten, sometimes the different features of the language and because the system under which it is used their interrelationships. To reduce the has changed, sometimes because the program need for cross references and to allow each is to be run on a new machine. It is not chapter to stand alone as a complete uncommon to find that rewriting a program reference to its subject, some information costs as much as writing it in the first is repeated from one chapter to another. place. Part I can, nevertheless, be read sequentially in its entirety. Two basic characteristics of PL/I are intended to reduce the need to rewrite Part II, "Rules and Syntactic complete programs if either the machine Descriptions," provides a quick reference environment or the application environment to specific information. It includes less changes. These characteristics are the information about interrelationships, but block structure used in the language and it is organized so that a particular its machine independence. question can be answered quickly. Part II is organized purely from a reference point A PL/I program is composed of blocks of of view; it is not intended for sequential statements called procedure blocks (or reading. procedures) and begin blocks, each of which defines a region of the program. A single For example, a programmer would read program may consist of one procedure or of Chapter 5 in Part I, "Statement several procedures and begin blocks. Classification," for information about the Either a procedure block or a begin block interactions of different statements in a can contain other blocks; a begin block program; but he would look in Section J of must be contained in a procedure block. Part II, "Statements," to find all the Each external procedure, that is, a rules for the use of a specific statement, procedure that is not contained in another its effect, options allowed, and the format procedure, is compiled separately. The in which it is written. same external procedure might be used in a number of different programs. In the same manner, he would read Consequently, a necessary change made in Chapter 4 in Part I, "Expressions and Data that one block effectively makes the change Conversion," for a discussion of the in all programs that use it. concepts of data conversion, but he would
Introduction 13 use Section F of Part II, "Problem Data those features that are required for a full Conversion and Assignment," to determine explanation of the language. For example, the exact results of a particular type of references to certain parameters of the conversion. Data Definition (DD) job control language statement are essential to an explanation An explanation of the syntax language of record-oriented input and output file used in this publication to describe organization. elements of PL/I is contained in Part II, Section A, "Syntax Notation." Implementation features identified by the phrase "for System/360 implementa- tions...* apply to all implementations for IBM System/360 computers. Features Implementation Considerations identified by the phrase "for the F Compiler..." apply specifically to the IBM F Compiler under the IBM System/360 This publication reflects features of the Operating System. fifth version of the F Compiler. No attempt is made to provide complete A separate publication, IBM System/360: implementation information; this PL/I Subset Reference Manual, Form publication is designed for use in C28-8202, provides the same type of conjunction with IBM System/360 Operating implementation information as it applies to System: PL/I (F) Programmer's Guide. the D Compiler used under the IBM Discussion of implementation is limited to System/360 Disk and Tape Operating Systems.
14 Part I Concepts of PL/I
Chapter 1: Basic Characteristics of PL/I
The modularity of PL/I, the ease with which the proper understanding of PL/I at any subsets can be defined to meet different level but the most elementary. These rules needs, becomes apparent when one examines give the programmer considerable control the different features of the language. over the degree of interaction between Such modularity is one of the most subroutines. They permit flexible important characteristics of PL/I. communication and storage allocation, at the same time allowing the definition of This chapter contains brief discussions names and allocation of storage for private of most of the basic features to provide an use within a procedure. overall description of the language. Each is treated in more detail in subsequent By giving the programmer freedom to chapters. determine the degree to which a subroutine is self-contained, PL/I makes it possible to write procedures which can freely be used in other environments, while still Machine Independence allowing interaction in procedures where interaction is desirable.
No language can be completely machine independent, but PL/I is much less machine dependent than most commonly used Multiprogramming programming languages. The methods used to achieve this show in the form of restrictions in the language. The most By means of the PL/I multitasking obvious example is that data with different facilities, the programmer can specify that characteristics cannot in general share the an invoked procedure is to be executed same storage; to equate a floating-point concurrently with the invoking procedure, number with a certain number of alphabetic thus making use of the multiprogramming characters would be to make assumptions capabilities of the system. In this way, about the representation of these data the central processing unit can be occupied items which would not be true for all with one part of the program while the machines. input/output channels are occupied with other parts of the program; this can reduce It is recognized that the price entailed the overall amount of waiting time during by machine independence may sometimes be execution. too high. In the interest of efficiency, certain features such as the UNSPEC Concurrent execution of different parts built-in function and record-oriented data of a program does not imply that the transmission, do permit a degree of machine program cannot be coordinated. The dependence. programmer can specify that execution of a procedure will be suspended at a specified point until some point in another procedure has been reached, or until an input/output Program Structure operation has been completed.
A PL/I program consists of one or more blocks of statements called procedures. A Data Types and Data Description procedure may be thought of as a subroutine. Procedures may invoke other procedures, and these procedures or The characteristic of PL/I that most subroutines may either be compiled contributes to the range of applications separately, or may be nested within the for which it can be used is the variety of calling procedure and compiled with it. data types that can be represented and Each procedure may contain declarations manipulated. PL/I deals with arithmetic that define names and control allocation of data, string data (bit and character), and storage. program control data, such as labels. Arithmetic data may be represented in a The rules defining the use of variety of ways; it can be binary or procedures, communication between decimal, fixed-point or floating-point, procedures, the meaning of names, and real or complex, and its precision may be allocation of storage are fundamental to specified.
Chapter 1: Basic Characteristics of PL/I 17 PL/I provides features to perform Storage also may be declared STATIC, in arithmetic operations, operations for which case it is allocated when the program comparisons, logical manipulation of bit is loaded; it may be declared CONTROLLED, strings, and operations and functions for in which case it is explicitly controlled assembling, scanning, and subdividing by the programmer with ALLOCATE and FREE character strings. statements, independent of the invocation of blocks; or it may be declared BASED, The compiler must be able to determine, which gives the programmer an even higher for every name used in a program, the degree of control. complete set of attributes associated with that name. The programmer may specify The existence of several storage classes these attributes explicitly by means of a enables the programmer to determine for DECLARE statement, the compiler may himself the speed, storage space, or determine all or some of the attributes by programming economy that he needs for each context, or the attributes may be assumed application. The cost of a particular by default. facility will depend upon the implementation, but it will usually be true that the more dynamic the storage Default Assumptions allocation, the greater the overhead in execution time. An important feature of PL/I is its default philosophy. If all the attributes associated with a name, or all the options permitted in a statement, are not specified by the programmer, attributes or options Expressions may be assigned by the compiler. This default action has two main consequences. First, it reduces the amount of declaration Calculations in PL/I are specified by and other program writing required; second, expressions. An expression has a meaning it makes it possible to teach and use in PL/I that is similar to that of subsets of the language for which the elementary algebra. For example: programmer need not know all possible alternatives, or even that alternatives A + B * C exist. This specifies multiplication of the value Since defaults are based on assumptions of B by the value of C and adding the value about the intent of the programmer, errors of A to the result. PL/I places few or omissions may be overlooked, and restrictions on the kinds of data that can incorrect attributes may be assigned by be used in an expression. For example, it default. To reduce the chance of this, the is conceivable, though unlikely, that A F Compiler optionally provides an attribute could be a floating-point number, B a listing, which can be used to check the fixed-point number, and C a character names in the program and the attributes string. associated with them. When such mixed expressions are specified, the operands will be converted so that the operation can be evaluated Storage Allocation meaningfully. Note, however, that the rules for conversion must be considered carefully; converted data may not have the PL/I goes beyond most other languages in same value as the original. And, of the flexibility of storage allocation that course, any conversion requires additional it provides. Dynamic storage allocation is compiler-generated coding, which increases comparatively difficult for an assembly execution time. language programmer to handle for himself; yet it is automatically provided in PL/I. The results of the evaluation of There are four different storage classes: expressions are assigned to variables by AUTOMATIC, STATIC, CONTROLLED, and BASED. means of the assignment statement. An In general, the default storage class in example of an assignment statement is: PL/I is AUTOMATIC. This class of storage is allocated whenever the block in which X = A + B * C; the variables are declared is activated. At that time the bounds of arrays and the This means: evaluate the expression on the lengths of strings are calculated. right and store the result, in X. If the AUTOMATIC storage is freed and is available attributes of X differ from the attributes for re-use whenever control leaves the of the result of the expression, conversion block in which the storage is allocated. will again be performed.
18 Data Collections Record-oriented input/output is machine dependent. It deals with collections of data, called records, and transmits these a PL/I permits the programmer many ways of record at a time without any data describing and operating on collections of conversion; the external representation is data, or data aggregates. Arrays are an exact copy of the internal collections of data elements, all of the representation. Because the aggregate is same type, collected into lists or tables treated as a whole, and because no of one or more dimensions. Structures are conversion is performed, this form of hierarchical collections of data, not input/output is potentially more efficient necessarily all of the same type. Each than stream-oriented input/output, although level of the hierarchy may contain other the actual efficiency of each class will, structures of deeper levels. The deepest of course, depend on the implementation. A levels of the hierarchy represent form of record-oriented input/output is elementary data items or arrays. used for teleprocessing applications. An element of an array may be a structure; similarly, any level of a Stream-oriented input/output usually structure may be an array. Operations can sacrifices efficiency for ease of handling. be specified for arrays, structures, or Each data item is transmitted separately parts of arrays or structures. For and is examined to determine if data example: conversion is required. Record-oriented input and output, on the other hand, A = B + C; provides faster transmission by transmitting data as entire records, In this assignment statement, A, B, and C without conversion. could be arrays or structures.
Input and Output Compile-Time Operations Facilities for input and output allow the user to choose between factors such as simplicity, machine independence, and Most programming is concerned only with efficiency. There are two broad classes of operations upon data. PL/I permits a input/output in PL/I: stream-oriented and compile-time level of operation, in which record-oriented. preprocessor statements specify operations upon the text of the source program itself. Stream-oriented input/output is almost The simplest, and perhaps the commonest completely machine independent. On input, preprocessor statement is %INCLUDE (in data items are selected one by one from general, preprocessor statements are what is assumed to be a continuous stream preceded by a percent sign). This of characters that are converted to statement causes text to be inserted into internal form and assigned to variables the program, replacing the %INCLUDE specified in a list. Similarly, on output, statement itself. A typical use could be data items are converted one by one to to copy declarations from an installation's external character form and are added to a standard set of definitions into the conceptually continuous stream of program. characters. Within the class of stream input/output, the programmer can choose different levels of control over the way Another function provided by data items are edited and selected from or compile-time facilities is the selective added to the stream. compilation of program text. For example, it might specify the inclusion or deletion For printing, the output stream may be of debugging statements. considered to be divided into lines and pages. An output stream file may be declared to be a print file with a Since a simple but powerful part of the specified line size and page size. The PL/I language is available for compile-time programmer has facilities to detect the end activity, the generation, or replacement of a page and to specify the beginning of a and deletion, of text can become more line or a page. These facilities may be elaborate, and more subtle transformations used in subroutines that can be developed can be performed. Such transformations into a report generating system suitable might then be considered to be for a particular installation or installation-defined extensions to the application. language.
Chapter 1: Basic Characteristics of PL/I 19 Interrupt Activities PL/I provides facilities for detecting a variety of exceptional conditions. It allows the programmer to specify, by means Modern computing systems provide facilities of a condition prefix, whether certain for interrupting the execution of a program interrupts will or will not occur if the whenever an exceptional condition arises. condition should arise. And, by use of an Further, they allow the program to deal ON statement, he can specify the action to with the exceptional condition and to be taken when an interrupt does occur. return to the point at which the interrupt occurred.
20
Chapter 2: Program Elements
There are few restrictions in the format of PL/I statements. Consequently, programs can be written without consideration of special ccding forms or checking to see that each statement begins in a specific column. As long as each statement is terminated by a semicolon, the format is completely free. Each statement may begin in the next column or position after the previous statement, or any number of blanks may intervene.
Character Sets
One of two character sets may be used to write a source program; either a Special characters are combined to 60-character set or a 48-character set. create other symbols. For example, <= For a given external procedure, the choice means "less than or equal to," 1 = means between the two sets is optional. In "not equal to." The combination ** denotes practice, this choice will depend upon the exponentiation (X**2 means X 2 ). Blanks are available equipment. not permitted in such composite symbols. An alphameric character is either an alphabetic character or a digit, but not a special character. 60-CHARACTER SET Note: The question mark, at present, has no specific use in the language, even though The 60-character set is composed of digits, it is included in the 60-character set. special characters, and alphabetic characters. There are 29 alphabetic characters 48-CHARACTER SET beginning with the currency symbol ($), the number sign (#), and the commercial "at" sign (s), which precede the 26 letters of The 48-character set is composed of 48 the English alphabet in the IBM System/360 characters of the 60-character set. In all collating sequence in Extended but four cases, the characters of the Binary-Coded-Decimal Interchange Code reduced set can be combined to represent (EBCDIC). For use with languages other the missing characters from the larger set. than English, the first three alphabetic For example, the percent symbol (%) is not characters can be used to cause printing of included in the 48-character set, but a letters that are not included in the double slash (//) can be used to represent standard English alphabet. it. The four characters that are not duplicated are the commercial "at" sign, There are ten digits. The decimal the number sign, the break character, and digits are the digits 0 through 9. A the question mark. binary digit is either a 0 or a 1. The restrictions and changes for this There are 21 special characters. They character set are described in Part II, are as follows: Section B, "Character Sets with EBCDIC and Card-Punch Codes."
'The break character is the same as the typewriter underline character. It can be used with a name, such as GROSS_PAY, to improve readability.
Chapter 2: Program Elements 21
USING THE CHARACTER SET
All the elements that make up a PL/I program are constructed from the PL/I character sets. There are two exceptions: character-string constants and comments may contain any character permitted by a particular machine configuration. Certain characters perform specific functions in a PL/I program. For example, many characters function as operators. The bit-string operators are There are four types of operators: arithmetic, comparison, bit-string, and string.
The string operator is:
It at.nni-inn r.rinrAfcmatinn
Figure 2-1 shows some of the functions of other special characters.
22 Identifiers The Use of Blanks
In a PL/I program, names or labels are Blanks may be used freely throughout a PL/I given to data, files, statements, and entry program. They may or may not surround points of different program areas. In operators and most other delimiters. In creating a name or label, a programmer must general, any number of blanks may appear observe the syntactic rules for creating an wherever one blank is allowed, such as identifier. between words in a statement. One or more blanks must be used to separate identifiers and constants that are An identifier is a single alphabetic not separated by some other delimiter or by character or a string of alphameric and a comment. However, identifiers, constants break characters, not contained in a (except character-string constants) and comment or constant, and preceded and composite operators (for example, 1=-) followed by a blank or some other cannot contain blanks. delimiter; the initial character of the string must be alphabetic. For System/360 Other cases that require or permit implementation, the length must not exceed blanks are noted in the text where the 31 characters. feature of the language is discussed. Some examples of the use of blanks are: Language keywords also are identifiers. A keyword is an identifier that, when used AB+BC is equivalent to AB + BC in proper context, has a specific meaning to the compiler. A keyword can specify TABLE(10) is equivalent to TABLE (10) such things as the action to be taken, the nature of data, the purpose of a name. For FIRST,SECOND is equivalent to FIRST, SECOND example, READ, DECIMAL, and ENDFILE are keywords. Some keywords can be ATOB is not equivalent to A TO B abbreviated. A complete list of keywords and their abbreviations is contained in Part II, Section C, "Keywords and Keyword Abbreviations." Comments
Note: PL/I keywords are not reserved Comments are permitted wherever blanks are words. They are recognized as keywords by allowed in a program, except within data the compiler only when they appear in their items, such as a character string. A proper context. In other contexts they may comment is treated as a blank and can be used as programmer-defined identifiers. therefore be used in place of a required separating blank. Comments do not No identifier can exceed 31 characters otherwise affect execution of a program; in length; for the F Compiler, some they are used only for documentation identifiers, as discussed in later purposes. Comments may be punched into the chapters, cannot exceed seven characters in same cards as statements, either inserted length. This limitation is placed upon between statements or in the middle of certain names, called external names, that them. may be referred to by the operating system or by more than one separately compiled The general format of a comment is: procedure. If an external name contains more than seven characters, it is truncated /* character-string *1 by the compiler, which concatenates the first four characters with the last three The character pair /* indicates the characters. beginning of a comment. The same character pair reversed, */, indicates its end. No Examples of identifiers that could be blanks or other characters can separate the used for names or labels: two characters of either composite pair; the slash and the asterisk must be A immediately adjacent. The comment itself may contain any characters except the */ FILE2 combination, which would be interpreted as terminating the comment. LOOP_3 Example: RATE_OF_PAY /* THIS WHOLE SENTENCE COULD BE #32 INSERTED AS A COMMENT */
Chapter 2: Program Elements 23 Any characters permitted for a Following are examples of the ON particular machine configuration may be statement: used in comments. ON OVERFLOW GO TO OVFIX; Basic Program Structure ON UNDERFLOW; The contained statement in the second A PL/I program is constructed from basic example is the null statement represented program elements called statements. There by a semicolon only; it indicates that no are two types of statements: simple and action is to be taken when an UNDERFLOW compound. These statements make up larger interrupt occurs. program elements called groups and blocks.
SIMPLE AND COMPOUND STATEMENTS Statement Prefixes
There are three types of simple statements: Both simple and compound statements may keyword, assignment, and null, each of have one or more prefixes. There are two which contains a statement body that is types of prefixes; the label prefix and the terminated by a semicolon. condition prefix.
A keyword statement has a keyword to A label prefix identifies a statement so indicate the function of the statement; the that it can be referred to at some other statement body is the remainder of the point in the program. A label prefix is an statement. identifier that precedes the statement and is connected to the statement by a colon. The assignment statement contains the Any statement may have one or more labels. assignment symbol (=) and does not have a If more than one are specified, they may be keyword. used interchangeably to refer to that statement. The null statement consists only of a semicolon and indicates no operation; the A condition prefix specifies whether or semicolon is the statement body. not interrupts are to result from the occurrence of the named conditions. Examples of simple statements are: Condition names are language keywords, each of which represents an exceptional GO TO LOOP_3; (GO TO is a keyword; the condition that might arise during execution blank between GO and TO of a program. Examples are OVERFLOW and is optional. The state- SIZE. The OVERFLOW condition arises when ment body is LOOP_3;) the exponent of a floating-point number exceeds the maximum allowed (representing a A = B + C; (assignment statement) maximum value of about 10 75 ). The SIZE condition arises when a value is assigned A compound statement is a statement that to a variable with loss of high-order contains one or more other statements as a digits or bits. part of its statement body. There are two compound statements: the IF statement and A condition name in a condition prefix the ON statement. The final statement of a may be preceded by the word NO to indicate compound statement is a simple statement that, effectively, no interrupt is to occur that is terminated by a semicolon. Hence, if the condition arises. If NO is used, the compound statement is terminated by there can be no intervening blank between this semicolon. The IF statement can the NO and the condition name. contain two simple statements as shown in the following example: A condition prefix consists of a list of one or more condition names, separated by IF A>B THEN A = B+C; ELSE GO TO commas and enclosed in parentheses. One or LOOP_3; more condition prefixes may be attached to a statement, and each parenthesized list This example can also be written as must be followed by a colon. Condition follows: prefixes precede the entire statement, including any possible label prefixes for IF A>B the statement. For example: THEN A=B+C; ELSE GO TO LOOP_3; (SIZE,NOOVERFLOW):COMPUTE:A = B * C ** D;
24 The single condition prefix indicates that for control purposes. A group also may be an interrupt is to occur if the SIZE called a DO-group. condition arises during execution of the assignment statement, but that no interrupt is to occur if the OVERFLOW condition arises. Note that the condition prefix A block is a sequence of statements that precedes the label prefix COMPUTE. defines an area of a program. It is used to delimit the scope of a name and for Since intervening blanks between a control purposes. A program may consist of prefix and its associated statement are one or more blocks. Every statement must ignored, it is often convenient to punch appear within a block. There are two kinds the condition prefix into a separate card of blocks: begin blocks and procedure that precedes the card into which the blocks. A begin block is delimited by a statement is punched. Thus, after BEGIN statement and an END statement. A debugging, the prefix can be easily procedure block is delimited by a PROCEDURE removed. For example: statement and an END statement. Every begin block must be contained within some (NOCONVERSION): procedure block. (SIZE,NOOVERFLOW): COMPUTE: A = B * C ** D; Execution passes sequentially into and Note that there are two condition prefixes. out of a begin block. However, a procedure The first specifies that no interrupt is to block must be invoked by execution of a occur if an invalid character is statement in another block. The first encountered during an attempted data procedure in a program to be executed is conversion. invoked automatically by the operating system. For System/360 implementations, Condition prefixes are discussed in this first procedure must be identified by Chapter 13, "Exceptional Condition Handling specifying OPTIONS (MAIN) in the PROCEDURE and Program Checkout." statement.
GROUPS AND BLOCKS A procedure block may be invoked as a task, in which case it is executed A group is a sequence of statements headed concurrently with the invoking procedure. by a DO statement and terminated by a Tasks are discussed in Chapter 15, corresponding END statement. It is used "Multitasking."
Chapter 2: Program Elements 25 Chapter 3: Data Elements
Data is generally defined as a Program control data is used by the representation of information or of value. programmer to control the execution of his program. Program control data consists of In PL/I, reference to a data item, the following types: label, event, task, arithmetic or string, is made by using locator, and area. either a variable or a constant (the terms are not exactly the same as in general A constant does more than state a value; mathematical usage). it demonstrates various characteristics of the data item. For example, 3.1416 shows A variable is a symbolic name having a that the data type is arithmetic and that value that may change during execution of a the data item is a decimal number of five program. digits and that four of these digits are to the right of the decimal point. A constant (which is not a symbolic name) has a value that cannot change. The characteristics of a variable are not immediately apparent in the name. The following statement has both Since these characteristics, called variables and constants: attributes, must be known, certain keywords and expressions may be used to specify the AREA = RADIUS**2*3.1416; attributes of a variable in a DECLARE statement. The attributes used to describe AREA and RADIUS are variables; the numbers each data type are discussed briefly in 2 and 3.1416 are constants. The value of this chapter. A complete discussion of RADIUS is a data item, and the result of each attribute appears in Part LI, Section the computation will be a data item that I, "Attributes." will be assigned as the value of AREA. The number 3.1416 in the statement is itself the data item; the characters 3.1416 also Problem Data are written to refer to the data item.
If the number 3.1416 is to be used in The types of problem data are arithmetic more than one place in the program, it may and string. be convenient to represent it as a variable to which the value 3.1416 has been assigned. Thus, the above statement could be written as: ARITHMETIC DATA PI = 3.1416; AREA = RADIUS**2*PI; An item of arithmetic data is one with a numeric value. Arithmetic data items have In this statement, only the digit 2 is a the characteristics of base, scale, constant. precision, and mode. The characteristics of data items represented by an arithmetic In preparing a PL/I program, the variable are specified by attributes programmer must be familiar with the types declared for the name, or assumed by of data that are permitted, the ways in default. which data can be organized, and the methods by which data can be referred to. The base of an arithmetic data item is The following paragraphs discuss these either decimal or binary. features. The scale of an arithmetic data item is either fixed-point or floating-point. A fixed-point data item is a number in which Data Types the position of the decimal or binary point is specified, either by its appearance in a constant or by a scale factor declared for The types of data that may be used in a a variable. A floating-point data item is PL/I program fall into two categories: a number followed by an optionally signed problem data and program control data. exponent. The exponent specifies the Problem data is used to represent values to assumed position of the decimal or binary be processed by a program. It consists of point, relative to the position in which it two data types, arithmetic and string. appears.
26 The precision of an arithmetic data item Decimal Fixed-Point Data is the number of digits the data item may contain, in the case of fixed-point, or the minimum number of significant digits A decimal fixed-point constant consists of (excluding the exponent) to be maintained, one or more decimal digits with an optional in the case of floating-point. For decimal point. If no decimal point fixed-point data items, precision can also appears, the point is assumed to be specify the assumed position of the decimal immediately to the right of the rightmost or binary point, relative to the rightmost digit. In most uses, a sign may optionally digit of the number. precede a decimal fixed-point constant.
Examples of decimal fixed-point Whenever a data item is assigned to a constants as written in a program are: fixed-point variable, the declared precision is maintained. The assigned item 3.1416 is aligned on the decimal or binary point. Leading zeros are inserted if the assigned 455.3 item contains fewer integer digits than declared; trailing zeros are inserted if it 732 contains fewer fractional digits. A SIZE error may occur if the assigned item 003 contains too many integer digits; truncation on the right may occur if it 5280 contains too many fractional digits. .0012 The keyword attributes for declaring The mode of an arithmetic data item is decimal fixed-point variables are DECIMAL either real or complex. A real data item and FIXED. Precision is stated by two is a number that expresses a real value. A decimal integers, separated by a comma and complex data item is a pair of numbers: the enclosed in parentheses. The first, which first is real and the second is imaginary. must be unsigned, specifies the total For a variable representing complex data number of digits; the second, the scale items, the base, scale, and precision of factor, may be signed and specifies the the two parts must be identical. number of digits to the right of the decimal point. If the variable is to represent integers, the scale factor and its preceding comma can be omitted. The Ease, scale, and mode of arithmetic attributes may appear in any order, but the variables are specified by keywords; precision specification must follow either precision is specified by parenthesized DECIMAL or FIXED (or REAL or COMPLEX). decimal integer constants. The precision of arithmetic constants is discussed in Following are examples of declarations greater detail below, under the heading of decimal fixed-point variables: "Precision of Arithmetic Constants." DECLARE A FIXED DECIMAL (5,4); In the following sections, the real DECLARE B FIXED (6,0) DECIMAL; arithmetic data types discussed are decimal fixed-point, sterling fixed-point, binary DECLARE C FIXED (7,-2) DECIMAL; fixed-point, decimal floating-point, and binary floating-point. Any of these, The first DECLARE statement specifies that except sterling fixed-point, can be used as the identifier A is to represent decimal the real part of a complex data item. The fixed-point items of not more than five imaginary part of a complex number is digits, four of which are to be treated as discussed in the section "Complex fractional, that is, to the right of the Arithmetic Data," in this chapter. assumed decimal point. Any item assigned to A will be converted to decimal fixed-point and aligned on the decimal Complex arithmetic variables must be point. The second DECLARE statement explicitly declared with the COMPLEX specifies that B is to represent integers attribute. Real arithmetic variables may of no more than 6 digits. Note that the be explicitly declared to have the REAL comma and the zero are unnecessary; it attribute, but it is not necessary to do could have been specified B FIXED DECIMAL so, since any arithmetic variable is (6). The third DECLARE statement specifies assumed to be real unless it is explicitly a negative scale factor of -2; this means declared complex. that the assumed decimal point is two
Chapter 3: Data Elements 27 places to the right of the rightmost digit There are no keyword attributes for of the item. declaring sterling variables, but a variable can be declared with a sterling The maximum number of decimal digits picture, or sterling values may be allowed for System/360 implementations is expressed in pence as decimal fixed-point 15. Default precision, assumed when no data. The precision of a sterling constant specification is made, is (5,0). The is the precision of its value expressed in internal coded arithmetic form of decimal pence. fixed-point data is packed decimal. Packed decimal is stored two digits to the byte, with a sign indication in the rightmost four bits of the rightmost byte. Binary Fixed-Point Data Consequently, a decimal fixed-point data item is always stored as an odd number of digits, even though the declaration of the A binary fixed-point constant consists of variable may specify the number of digits one or more binary digits with an optional (p) as an even number. When the binary point, followed immediately by the declaration specifies an even number of letter B, with no intervening blank. In digits, the extra digit place is in the most uses, a sign may optionally precede high-order position, and it participates in the constant. any operations performed upon the data item, such as in a comparison operation. Examples of binary fixed-point constants Any arithmetic overflow or assignment into as written in a program are: an extra high-order digit place can be detected only if the SIZE condition is 10110B enabled. 11111B Sterling Fixed-Point Data 101B 111.01B1011.111B PL/I has a facility for handling constants stated in terms of sterling currency value. The data may be written in a program with pounds, shillings, and pence fields, each The keyword attributes for declaring separated by a period. Such data is binary fixed-point variables are BINARY and converted and maintained internally as a FIXED. Precision is specified by two decimal fixed-point number representing the decimal integer constants, enclosed in equivalent in pence. A sterling data parentheses, to represent the maximum constant ends with the letter L, number of binary digits and the number of representing the pounds symbol. All three digits to the right of the binary point, fields (pounds, shillings, and pence) must respectively. If the variable is to be present in a sterling constant. Note represent integers, the second digit and the maximum number of digits allowed in the the comma can be omitted. The attributes pounds field of a sterling constant is 13. can appear in any order, but the precision The pence field is one or more decimal specification must follow either BINARY or digits with an optional decimal point (the FIXED (or REAL or COMPLEX). integer part must be less than 12 and cannot be omitted, and the fractional part Following is an example of declaration must not exceed 13 minus the number of of a binary fixed-point variable: digits in the pounds field). DECLARE FACTOR BINARY FIXED (20,2); Examples of sterling fixed-point constants as written in a program are: FACTOR is declared to be a variable that can represent arithmetic data items as 101.13.8L large as 20 binary digits, two of which are fractional. The decimal equivalent of that 1.10.0L value range is from -262,144.00 through +262,143.75. 0.0.2.5L The maximum number of binary digits 2.4.6L allowed for System/360 implementations is 31. Default precision is (15,0). The The third example represents internal coded arithmetic form of binary twopence-halfpenny. The last example fixed-point data is a fixed-point binary represents two pounds, four shillings, and fullword or halfword. (A fullword is 31 six pence. It is converted and stored bits plus a sign bit; a halfword is 15 bits internally as 534 (pence). plus a sign bit.) Any binary fixed-point
28 variable of precision less than 16 is Following is an example of declaration always stored as 15 digits, even though the of a decimal floating-point variable: declaration of the variable may specify fewer digits; any binary fixed-point DECLARE LIGHT_YEARS DECIMAL FLOAT(5); variable of precision greater than 15 (or any binary fixed-point constant, regardless This statement specifies that LIGHT_YEARS of precision) is always stored as 31 is to represent decimal floating-point data digits. The declared number of digits are items with an accuracy of at least five considered to be in the low-order significant digits. positions, but the extra high-order digits participate in any operations performed The maximum precision allowed for upon the data item. Any arithmetic decimal floating-point data items for overflow into such extra high-order digit System/360 implementations is (16); the positions can be detected only if the SIZE exponent cannot exceed two digits. A value condition is enabled. range of approximately 10- 78 to 10 75 can be expressed by a decimal floating-point data An identifier for which no declaration item. Default precision is (6). The is made is assumed to be a binary internal coded arithmetic form of decimal fixed-point variable, with default floating-point data is normalized precision, if its first letter is any of hexadecimal floating-point, with the point the letters I through N. assumed to the left of the first hexadecimal digit. If the declared precision is less than or equal to (6), Decimal Floating-Point Data short floating-point form is used; if the declared precision is greater than (6), long floating-point form is used. A decimal floating-point constant is written as a field of decimal digits An identifier for which no declaration followed by the letter E, followed by an is made is assumed to be a decimal optionally signed decimal integer exponent. floating-point variable if its first letter The first field of digits may contain a is any of the letters A through H, 0 decimal point. The entire constant may be through Z, or one of the alphabetic preceded by a plus or minus sign. Examples extenders, $, #, @. of decimal floating-point constants as written in a program are: 15E-23 Binary Floating-Point Data 15E23 A binary floating-point constant consists 4E-3 of a field of binary digits followed by the letter E, followed by an optionally signed 48333E65 decimal integer exponent followed by the letter B. The exponent is a string of 438E0 decimal digits and specifies an integral power of two. The field of binary digits 3141593E-6 may contain a binary point. A binary floating-point constant may be preceded by .003141593E3 a plus or minus sign. Examples of binary floating-point constants as written in a The last two examples represent the same program are: value. 101101E5B The keyword attributes for declaring decimal floating-point variables are 101.101E2B DECIMAL and FLOAT. Precision is stated by a decimal integer constant enclosed in 11101E-28B parentheses. It specifies the minimum number of significant digits to be The keyword attributes for declaring maintained. If an item assigned to a binary floating-point variables are BINARY variable has a field width larger than the and FLOAT. Precision is expressed as a declared precision of the variable, decimal integer constant, enclosed in truncation may occur on the right. The parentheses, to specify the minimum number least significant digit is the first that of significant digits to be maintained. is lost. Attributes may appear in any The attributes can appear in any order, but order, but the precision specification must the precision specification must follow follow either DECIMAL or FLOAT (or REAL or either BINARY or FLOAT (or REAL or COMPLEX). COMPLEX). Following is an example of
Chapter 3: Data Elements 29 declaration of a binary floating-point Unless a variable is explicitly declared variable: to have the COMPLEX attribute, it is assumed to represent real data items. DECLARE S BINARY FLOAT (16); This specifies that the identifier S is to represent binary floating-point data items Numeric Character Data ' with 16 digits in the binary field.
The maximum precision allowed for binary A numeric character data item (also known floating-point data items for System/360 as a numeric field data item) is the value implementations is (53); default precision of a variable that has been declared with is (21). The exponent cannot exceed three the PICTURE attribute and a numeric picture decimal digits. A value range of specification. The data item is the approximately 2-260 to 2 252 can be character representation of a decimal expressed by a binary floating-point data fixed-point or floating-point value. item. The internal coded arithmetic form of binary floating-point data is normalized A numeric picture specification hexadecimal floating-point. If the describes a character string to which only declared precision is less than or equal to data that has, or can be converted to, an (21), short floating-point form is used; if arithmetic value is to be assigned. A the declared precision is greater than numeric picture specification cannot (21), long floating-point form is used. contain either of the picture characters A or X, which are used for non-numeric picture-character strings. The basic form Complex Arithmetic Data of a numeric picture specification is one or more occurrences of the digit-specifying picture character 9 and an optional In the complex mode, an arithmetic data occurrence of the picture character V, to item is considered to consist of two parts, indicate the assumed location of a decimal the first a real part and the second a point. The picture specification must be signed imaginary part. There are no enclosed in single quotation marks. For complex constants in PL/I. The effect is example: obtained by writing a real constant and an imaginary constant. '999V99' An imaginary constant is written as a This numeric picture specification real constant of any type (except sterling describes a data item consisting of up to fixed-point) immediately followed by the five decimal digits in character form, with letter I. a decimal point assumed to precede the rightmost two digits. Examples of imaginary constants as written in a program are: Repetition factors may be used in numeric picture specifications. A 271 repetition factor is a decimal integer constant, enclosed in parentheses, that 3.968E101 indicates the number or repetitions of the immediately following picture character. 11011.01BI For example, the following picture specification would result in the same Each of these is considered to have a real description as the example shown above: part of zero. Although complex constants cannot be written with a nonzero real part, '(3)9V(2)9' PL/I provides the facility to express such values in the following form: The format for declaring a numeric character variable is: real-constant{+|-}imaginary-constant DECLARE identifier PICTURE Thus a complex value could be written as 'numeric-picture-specification'; 38+271. For example: The keyword attribute for declaring a complex variable is COMPLEX. A complex DECLARE PRICE PICTURE '999V99'; variable can have any of the attributes valid for the different types of real This specifies that any value assigned to arithmetic data. Each of the base, scale, PRICE is to be maintained as a character and precision attributes applies to both string of five decimal digits, with an fields. assumed decimal point preceding the
30 rightmost two digits. Data assigned to they were printed, they would print exactly PRICE will be aligned on the assumed point the same. They do not, however, always in the same way that point alignment is function the same. For example: maintained for fixed-point decimal data. The numeric picture specification can VALUE = PRICE; specify all of the arithmetic attributes of data in much the same way that they are specified by the appearance of a constant. COST = PRICE; Only decimal numeric data can be represented by picture character. Complex data can be declared by specifying the VALUE = COST; COMPLEX attribute along with a single picture specification that describes either a fixed-point or a floating-point data PRICE = COST; item. It is important to note that, although After the first two assignment numeric character data has arithmetic statements are executed, the value of VALUE attributes, it is not stored in coded would be 0012.28 and the value of COST arithmetic form. In System/360 would be '$12.28'. In the assignment of implementations, numeric character data is PRICE to VALUE, the currency symbol and the stored in zoned decimal format; before it decimal point are considered to be editing can be used in arithmetic computations, it characters, and they are not part of the must be converted either to packed decimal assignment; the arithmetic value of PRICE or to hexadecimal floating-point format. is converted to internal coded arithmetic Such conversions are done automatically, form. In the assignment of PRICE to COST, but they require extra execution time. however, the assignment is to a character string, and the editing characters of a Although numeric character data is in numeric picture specification always character form, like character strings, and participate in such an assignment. No although it is aligned on the decimal point conversion is necessary because PRICE is like coded arithmetic data, it is processed stored in character form. differently from the way either coded arithmetic items or character strings are processed. Editing characters can be The third and fourth assignment specified for insertion into a numeric statements would cause errors. The value character data item, and such characters of COST cannot be assigned to VALUE because are actually stored within the data item. the currency symbol in the string makes it Consequently, when the item is printed or invalid as an arithmetic constant. The treated as a character string, the editing value of COST cannot be assigned to PRICE characters are included in the assignment. for exactly the same reason. Only values If, however, a numeric character item is that are of arithmetic type, or that can be assigned to another numeric character or converted to arithmetic type, can be arithmetic variable, the editing characters assigned to a variable declared with a will not be included in the assignment; numeric picture specification. only the actual digits and the location of the assumed decimal point are assigned. Note: Although the decimal point can be an Consider the following example: editing character or an actual character in a character string, it will not cause an DECLARE PRICE PICTURE '$99V.99', error in converting to arithmetic form, COST CHARACTER (6), since its appearance is valid in an VALUE FIXED DECIMAL (6,2); arithmetic constant. The same would be true of a valid plus or minus sign, since PRICE = 12.28; arithmetic constants can be preceded by signs. COST = '$12.28'; In the picture specification for PRICE, the Other editing characters, including zero currency symbol ($) and the decimal point suppression characters, drifting (.) are editing characters. They are characters, and insertion characters, can stored as characters in the data item. be used in numeric picture specifications. They are not, however, a part of its For complete discussions of picture arithmetic value. After execution of the characters, see Part II, Section D, second assignment statement, the actual "Picture Specification Characters" and the internal character representation of PRICE discussion of the PICTURE attribute in Part and COST can be considered identical. If II, Section I, "Attributes."
Chapter 3: Data Elements 31 Precision of Arithmetic Constants in a program, must be enclosed in single quotation marks. If a single quotation mark is a character in a string, it must be For purposes of expression evaluation, an written as two single quotation marks with apparent precision is defined for real no intervening blank. The length of a arithmetic constants: character string is the number of characters between the enclosing quotation Real fixed-point constants have a marks. If two single quotation marks are precision (p,q), where p is the total used within the string to represent a number of digits in the constant and q is single quotation mark, they are counted as the number of digits specified to the right a single character. of the decimal or binary point.
The precision of a sterling constant is A null character-string constant is equivalent to the precision of its written in a program as two quotation marks corresponding value in fixed-point pence. with no intervening blank. This value is determined as follows: multiply the value of the pounds field by Examples of character-string constants 240; add the value of the shillings field are: multiplied by 12; add the value of the pence field. The precision of the result 'LOGARITHM TABLE' (with leading zeros removed) is the precision of the corresponding sterling 'PAGE 5' constant. 'SHAKESPEAR''S''''' ''''HAMLET The precision of a floating-point constant is (p), where p is the number of 'AC438-19' digits of the constant left of the F. (2)'WALLA ' Examples: '' (null character-string constant) 3.14 has precision (3,2) 0.012E5 has precision (4) The third example actually indicates 0.9.0.5L has precision (4,1) SHAKESPEARE'S "HAMLET" WITH A LENGTH OF 0000001B has precision (7,0) 24. In the last example, the parenthesized number is a repetition factor, which indicates repetition of the characters that follow. This example specifies the STRING DATA constant 'WALLA WALLA ' (the blank is included as one of the characters to be repeated). The repetition factor must be A string is a contiguous sequence of an unsigned decimal integer constant, characters (or binary digits) that is enclosed in parentheses. treated as a single data item. The length of the string is the number of characters The keyword attribute for declaring a (or binary digits) it contains. character-string variable is CHARACTER. Length is declared by an expression or a There are two types of strings: decimal integer constant, enclosed in character strings and bit strings. parentheses, which specifies the number of characters in the string. The length specification must follow the keyword CHARACTER. For example: Character-String Data DECLARE NAME CHARACTER (15); A character string can include any digit, This DECLARE statement specifies that the letter, or special character recognized as identifier NAME is to represent a character by the particular machine character-string data items, 15 characters configuration. Any blank included in a in length. If a character string shorter character string is an integral character than 15 characters were to be assigned to and is included in the count of length. A NAME, it would be left adjusted and padded comment that is inserted within a character on the right with blanks to a length of 15. string will not be recognized as a comment. If a longer string were assigned, it would The comment, as well as the comment be truncated on the right: (Note: If such delimiters (/* and */), will be considered truncation occurs, no interrupt will result to be part of the character-string data. as it might for truncation of arithmetic data, and there is no ON condition PL/I Character-string constants, when written to deal with string truncation.)
32 Character-string variables may also be characters, one character that may be any declared to have the VARYING attribute, as character, and three numeric characters. follows: Repetition factors are used in picture DECLARE NAME CHARACTER (15) VARYING; specifications differently from the way they are used in string constants. This DECLARE statement specifies that the Repetition factors must be placed inside identifier NAME is to be used to represent the quotation marks. The repetition factor varying-length character-string data items specifies repetition of the immediately with a maximum length of 15. The actual following picture character. For example, length attribute for NAME at any particular the above picture specification could be time is the length of the data item written: assigned to it at that time. The programmer need not keep track of the '(2)A(4)9X(3)9' length of a varying-length character string; this is done automatically. The The maximum length allowed for a picture length at any given time can be determined specification is the same as that allowed by the programmer, however, by use of the for character-string constants, as LENGTH built-in function, as discussed in discussed above. Chapter 11, "Editing and String Handling." Note for the F Compiler that until a Note that, for character picture varying-length string variable is given an specifications, the picture character 9 initial value, its length is set to zero. specifies a digit or a blank, while, for numeric picture specifications, the same Character-string data in System/360 character specifies only a digit. implementations is maintained internally in character format, that is, each character occupies one byte of storage. The maximum length allowed for variables declared with Bit-string Data the CHARAOTER attribute is 32,767. The maximum length allowed for a character-string constant after application A bit-string constant is written in a of repetition factors varies according to program as a series of binary digits the amount of storage available to the enclosed in single quotation marks and compiler, but it never will be less than followed immediately by the letter B. 1,007 (see IBM System/360 Operating System: PL/I (F), Programmer's Guide. The minimum A null bit-string constant is written in length for a character string is zero. a program as two quotation marks with no intervening blank, followed immediately by Character-string variables also can be the letter B. declared using the PICTURE attribute of the form: Examples of bit-string constants as written in a program are: PICTURE 'character-picture-specification' '1'B The character picture specification is a string composed of the picture '11111010110001'B specification characters A, X, and 9. The string of picture characters must be (64)'0'B enclosed in single quotation marks, and it must contain at least one A or X and no ''B other picture characters except 9. The character A specifies that the The parenthesized number in the last corresponding position in the described example is a repetition factor which field will contain an alphabetic character specifies that the following series of or blank. The character X specifies that digits is to be repeated the specified any character may appear in the number of times. The example shown would corresponding position in the field. The result in a string of 64 binary zeros. picture character 9 specifies that the corresponding position will contain a A bit-string variable is declared with numeric character or blank. For example: the BIT keyword attribute. Length is specified by an expression or a decimal DECLARE PART NO PICTURE 'AA9999X999'; integer constant, enclosed in parentheses, to specify the number of binary digits in This DECLARE statement specifies that the the string. The letter B is not included identifier PART_NO will represent in the length specification since it is not character-string data items consisting of part of the string. The length two alphabetic characters, four numeric specification must follow the keyword BIT.
Chapter 3: Data Elements 33 Following is an example of declaration of a LBLA: statement; bit-string variable: DECLARE SYMPTOMS BIT (64); LBLB: statement; Like character strings, bit strings are assigned to variables from left to right. If a string is longer than the length declared for the variable, the rightmost LBL_X = LBL_A; digits are truncated; if shorter, padding, on the right, is with zeros. A bit-string variable may be given the GO TO LBL_X; VARYING attribute to indicate it is to be used to represent varying-length bit strings. Its application is the same as that described for character-string variables in the preceding section. With System/360 implementations, bit strings are stored eight bits to a byte. LBLA and LBL_B are statement-label The maximum length allowed for a bit-string constants because they are prefixed to variable with the F Compiler is 32,767. statements. LBLX is a statement-label The maximum length allowed for a bit-string variable. By assigning LBL_A to LBL_X, the constant after application of repetition statement GO TO LBL_X causes a transfer to factors depends upon the amount of storage the LBLA statement. Elsewhere, the available to the compiler, but it will program may contain a statement assigning never be less than 8,056 (1,007 bytes). LBL_B to LBL_X. Then, any reference to The minimum length for a bit string is LBL_X would be the same as a reference to zero. LBLB. This value of LBL_X is retained until another value is assigned to it.
Program Control Data A statement-label variable must be declared with the LABEL attribute, as follows: The types of program control data are label, event, task, locator, and area. DECLARE LBL_X LABEL;
LABEL DATA
A label data item is a label constant or the value of a label variable. EVENT DATA A label constant is an identifier written as a prefix to a statement so that, Event variables are used to coordinate the during execution, program control can be concurrent execution of a number of transferred to that statement through a procedures, or to allow a degree of overlap reference to its label. A colon connects between a record-oriented input/output the label to the statement. operation and the execution of other statements in the procedure that initiated ABCDE: DISTANCE = RATE*TIME; the operation. In this example, ABCDE is the statement label. The statement can be executed A variable is given the EVENT attribute either by normal sequential execution of by its appearance in an EVENT option or a instructions or by transferring control to WAIT statement, or by explicit declaration, this statement from some other point in the as in the following example: program by means of a GO TO statement. DECLARE ENDEVT EVENT; As used above, ABCDE can be classified further as a statement-label constant. A For detailed information, see Chapter statement-label variable is an identifier 15, "Multitasking," and "The EVENT Option" that refers to statement-label constants. in Chapter 10, "Record-Oriented Consider the following example: Transmission."
34 TASK DATA AREA DATA
Task variables are used to control the Area variables are used to describe areas relative priorities of different tasks of storage that are to be reserved for the (i.e., concurrent separate executions of a allocation of based variables. An area can procedure or procedures). be assigned or transmitted complete with its contained allocations; thus, a set of based allocations can be treated as one A variable is given the TASK attribute unit for assignment and input/output while by its appearance in a TASK option, or by each allocation retains its individual explicit declaration, as in the following identity. example: A variable is given the AREA attribute either by its appearance in the OFFSET DECLARE ADTASK TASK; attribute or an IN option, or by explicit declaration, as in the following example: For detailed information, see Chapter DECLARE AREA1 AREA(2000), 15, "Multitasking." AREA2 AREA; The number of bytes of storage to be reserved can be stated explicitly, as it has been for AREA1 in the example; otherwise a default size is assumed. For LOCATOR DATA the F Compiler, this default size is 1000 bytes. There are two types of locator data: For detailed information, see Chapter pointer and offset. 14, "Based Variables and List Processing." The value of a pointer variable is effectively an address of a location in storage, and so it can be used to qualify a reference to a variable that may have been allocated storage in several different Data Organization locations, all of which are immediately accessible. Since based storage is so allocated, reference to a based variable In PL/I, data items may be sing le data must be qualified in some way; with the F elements, or they may be grouped together Compiler, this qualification must be to form data collections called arrays and provided by a pointer variable. structures. A variable that represents a single element is an element variable (also The value of an offset variable called a scalar variable). A variable that specifies a location relative to the start represents a collection of data elements is of a reserved area of storage and remains either an array variable or a structure valid when the address of the area itself variable. changes. Any type of problem data or program Locator variables can be declared as in control data can be collected into arrays the following example: or structures. DECLARE HEADPTR POINTER, FIRST OFFSET (AREA1); In this example, AREA1 is the name of the ARRAYS reserved area of storage that will contain the location specified by FIRST. Data elements having the same A variable can also be given the POINTER characteristics, that is, of the same data attribute by its appearance in the BASED type and of the same precision or length, attribute, by its appearance on the may be grouped together to form an array. left-hand side of a pointer qualification An array is an n-dimensional collection of symbol, or by its appearance in a SET elements, all of which have identical option. attributes. Only the array itself is given a name. An individual item of an array is For detailed information, see Chapter referred to by giving its relative position 14, "Based Variables and List Processing." within the array.
Chapter 3: Data Elements 35
Consider the following two declarations: items are assigned to the array LIST, as declared above: DECLARE LIST (8) FIXED DECIMAL (3); 20 5 10 30 630 150 310 70 DECLARE TABLE (4,2) FIXED DECIMAL (3); The different elements would be referred In the first example, LIST is declared to to as follows: be a one-dimensional array of eight elements, each of which is a fixed-point decimal item of three digits. In the second example, TABLE is declared to be a two-dimensional array, also of eight fixed-point decimal elements. The parenthesized number or numbers following the array name in a DECLARE statement is the dimension attribute specification. It must follow the array name, with or without an intervening blank. It specifies the number of dimensions of the array and the bounds, or extent, of each dimension. Since only one bounds specification appears for LIST, it is a one-dimensional array. Two bounds specifications, separated by a comma, are listed for TABLE; consequently, it is Each of the numbers following the name declared to be a two-dimensional array. LIST is a subscript. A parenthesized subscript following an array name, with or The bounds of a dimension are the without an intervening blank, specifies the beginning and the end of that dimension. relative position of a data item within the The extent is the number of integers array. A subscripted name, such as between, and including, the lower and upper LIST(4), refers to a single element and is bounds. If only one integer appears in the an element variable. The entire array can bounds specification for a dimension, the be referred to by the unsubscripted name of lower bound is assumed to be 1. The one the array, for example, LIST. In this dimension of LIST has bounds of 1 and 8; case, LIST is an array variable. Note the its extent is 8. The two dimensions of difference between a subscript and the TABLE have bounds of 1 and 4 and 1 and 2; dimension attribute specification. The the extents are 4 and 2. latter, which appears in a declaration, specifies the dimensionality and the number If the lower bound of a dimension is not of elements in an array. Subscripts are 1, both the upper bound and the lower bound used in other references to identify must be stated explicitly, with the two specific elements within the array. numbers connected with a colon. For example: The same data assigned to LIST_A and LIST_B, as declared above, would be DECLARE LIST_A (4:11); referred to as follows: DECLARE LIST_B (-4:3); Reference Element Reference LIST_A (4) 20 In the first example, the bounds are 4 and 11; in the second they are -4 and 3. Note LIST_A (5) 5 that the extents are the same; in each case, there are 8 integers from the lower LIST_A (6) 10 bound through the upper bound. It is important to note the difference between LIST_A (7) 30 the bounds and the extent of an array. In the manipulation of array data (discussed LIST_A (8) 630 in Chapter 4, "Expressions and Data Conversion") involving more than one array, LIST_A (9) 150 the bounds -- not merely the extents -- must be identical. Although LIST_A (10) 310 LIST, LIST_A, and LIST_B all have the same extent, the bounds are not identical. LIST_A (11) 70 The bounds of an array determine the way Assume that the same data were assigned elements of the array can be referred to. to TABLE, which is declared as a For example, assume that the following data two-dimensional array. TABLE can be
36 illustrated as a matrix of four rows and Subscripts are frequently expressed as two columns, as follows: variables or other expressions. Thus, TABLE(I,J*K) could be used to refer to the (m 2) different elements of TABLE by varying the 5 values of I, J, and K. 30 150 Cross Sections of Arrays 70 Cross sections of arrays can be referred to An element of TABLE is referred to by a by substituting an asterisk for a subscript subscripted name with two parenthesized in a subscripted name. The asterisk then subscripts, separated by a comma. For specifies that the entire extent is to be example, TABLE (2,1) would specify the used. For example, TABLE(*,1) refers to first item in the second row, in this case, all of the elements in the first column of the data item 10. TABLE. It specifies the cross section consisting of TABLE(1,1), TABLE(2,1), Note: The use of a matrix to illustrate TABLE(3,1), and TABLE(4,1). The TABLE is purely conceptual. It has no subscripted name TABLE(2,*) refers to all relationship to the way in which the items of the data items in the second row of are actually organized in storage. Data TABLE. TABLE(*,*) refers to the entire items are assigned to an array in row major array. order, that is, with the right-most subscript varying most rapidly. For Note that a subscripted name containing example, assignment to TABLE would be to asterisk subscripts represents, not a TABLE(1,1), TABLE(1,2), TABLE(2,1), single data element, but an array with as TABLE(2,2) and so forth. many dimensions as there are asterisks. Consequently, such a name is not an element Arrays are not limited to two expression, but an array expression. dimensions. The PL/I F Compiler allows as many as 32 dimensions to be declared for an array. In a reference to an element of any array, a subscripted name must contain as STRUCTURES many subscripts as there are dimensions in the array. Data items that need not have identical Examples of arrays in this chapter have characteristics, but that possess a logical shown arrays of arithmetic data. Other relationship to one another, can be grouped data types may be collected into arrays. into aggregates called structures. String arrays, either character or bit, are valid, as are arrays of statement labels. Like an array, the entire structure is given a name that can be used to refer to the entire collection of data. Unlike an Expressions as Subscripts array, however, each element of a structure also has a name. The subscripts of a subscripted name need A structure is a hierarchical collection not be constants. Any expression that of names. At the bottom of the hierarchy yields a valid arithmetic value can be is a collection of elements, each of which used. If the evaluation of such an represents a single data item or an array. expression does not yield an integer value, At the top of the hierarchy is the the fractional portion is ignored. For structure name, which represents the entire System/360 implementations, the integer collection of element variables. For value is converted, if necessary, to a example, the following is a collection of fixed-point binary number of precision element variables that might be used to (15,0), since subscripts are maintained compute a weekly payroll: internally as binary integers. Note that, although the F compiler maintains LAST_NAME fixed-point binary variables of precision FIRST_NAME less than 16 as halfwords, this does not REGULAR_HOURS apply to subscript expressions. These, OVERTIME_HOURS like most other compiler-created REGULAR_RATE fixed-point binary temporaries (see Chapter OVERTIME RATE 4, "Expressions and Data Conversion") are stored as fullwords, regardless of These variables could be collected into precision. a structure and given a single structure
Chapter 3: Data Elements 37 name, PAYROLL, which would refer to the 3 FIRST, entire collection. 2 HOURS, 3 REGULAR, PAYROLL 3 OVERTIME, 2 RATE, LAST NAME REGULAR_HOURS REGULAR RATE 3 REGULAR, 3 OVERTIME; FIRST NAME OVERTIME_HOURS OVERTIME_RATE
Any reference to PAYROLL would be a Note: In an actual declaration of the reference to all of the element variables. structure PAYROLL, attributes would be For example: specified for each of the elementary names. The pattern of indention in this example is GET DATA (PAYROLL); used only for readability. The statement could be written in a continuous string as This input statement could cause data to DECLARE 1 PAYROLL, 2 NAME, 3 LAST, etc. be assigned to each of the element variables of the structure PAYROLL. PAYROLL is declared as a major structure containing the minor structures NAME, It often is convenient to subdivide the HOURS, and RATE. Each minor structure entire collection into smaller logical contains two elementary names. A collections. In the above examples, programmer can refer to the entire LAST_NAME and FIRST NAME might make a structure by the name PAYROLL, or he can logical subcollection, as might refer to portions of the structure by REGULAR_HOURS and OVERTIME_HOURS, as well referring to the minor structure names. He as REGULAR_ RATE and OVERTIME_RATE. In a can refer to an element by referring to an structure, such subcollections also are elementary name. given names. Note that in the declaration, each level PAYROLL number precedes its associated name and is separated from the name by a blank. The NAME HOURS RATE numbers chosen for successively deeper levels need not be the immediately FIRST REGULAR REGULAR succeeding integers. They are used merely LAST OVERTIME OVERTIME to specify the relative level of a name. A minor structure at level n contains all the Note that the hierarchy of names can be names with level numbers greater than n considered to have different levels. At that lie between that minor structure name the first level is the structure name and the next name with a level number less (called a major structure name); at a than or equal to n. PAYROLL might have deeper level are the names of substructures been declared as follows: (called minor structure names); and at the deepest are the element names (called DECLARE 1 PAYROLL, elementary names). An elementary name in a 4 NAME, structure can represent an array, in which 5 LAST, case it is not an element variable, but an 5 FIRST, array variable. 2 HOURS, 6 REGULAR, The organization of a structure is 5 OVERTIME, specified in a DECLARE statement through 2 RATE, the use of level numbers. A major 3 REGULAR, structure name must be declared with the 3 OVERTIME; level number 1. Minor structures and elementary names must be declared with This declaration would result in exactly level numbers arithmetically greater than the same structuring as the previous 1; they must be decimal integer constants. declaration. A blank must separate the level number and its associated name. The maximum declared The description of a major structure level number permitted in a structure is name is terminated by the declaration of 255. The maximum true level number another item with a level number 1, by the permitted in a structure is 63. declaration of another item with no level number, or by a semicolon terminating the For example, the items of a weekly DECLARE statement. payroll could be declared as follows: Level numbers are specified with DECLARE 1 PAYROLL, structure names only in DECLARE statements. 2 NAME, In references to the structure or its 3 LAST, elements, no level numbers are used.
38 Qualified Names DECLARE 1 WEATHER(12), 2 TEMPERATURE, 3 HIGH DECIMAL FIXED(4,1), A minor structure or a structure element 3 LOW DECIMAL FIXED(3,1), can be referred to by the minor structure 2 WIND_VELOCITY, name or the elementary name alone if there 3 HIGH DECIMAL FIXED(3), is no ambiguity. Note, however, that each 3 LOW DECIMAL FIXED(2), of the names REGULAR and OVERTIME appears 2 PRECIPITATION, twice in the structure declaration for 3 TOTAL DECIMAL FIXED(3,1), PAYROLL. A reference to either name would 3 AVERAGE DECIMAL FIXED(3,1); be ambiguous without some qualification to make the name unique. Thus, a programmer could refer to the PL/I allows the use of qualified names weather data for the month of July by to avoid this ambiguity. A qualified name specifying WEATHER(7). Portions of the is an elementary name or a minor structure July weather could be referred to by name that is made unique by qualifying it TEMPERATURE(7), WIND_VELOCITY(7), and with one or more names at a higher level. PRECIPITATION(7), but TOTAL(7) would refer In the PAYROLL example, REGULAR and to the total precipitation during the month OVERTIME could be made unique through use of July. of the qualified names HOURS.REGULAR, HOURS.OVERTIME, RATE.REGULAR, and TEMPERATURE.HIGH(3), which would refer RATE.OVERTIME. to the high temperature in March, is a subscripted qualified name. The different names of a qualified name The need for subscripted qualified names are connected by periods. Blanks may or becomes more apparent when an array of may not appear surrounding the period. structures contains minor structures that Qualification is in the order of levels; are arrays. For example, consider the that is, the name at the highest level must following array of structures: appear first, with the name at the deepest level appearing last. DECLARE 1 A (6,6), 2 B (5), 3 C, Any of the names in a structure, except 3 D, the major structure name itself, need not 2 E; be unique within the procedure in which it is declared. For example, the qualified Both A and B are arrays of structures. To name PAYROLL.HOURS.REGULAR might be identify a data item, it may be necessary required to make the reference unique to use as many as three names and three (another structure, say WORK, might also subscripts. For example, A(1,1).B(2).0 have the name REGULAR in a minor structure identifies a particular C that is an HOURS; it could be made unique with the element of B in a structure in A. name WORK.HOURS.REGULAR). All of the qualifying names need not be used, although So long as the order of subscripts they may be, if desired. Qualification remains unchanged, subscripts in such need go only so far as necessary to make references may be moved to the right or the name unique. Intermediate qualifying left and attached to names at a lower or names can be omitted. The name higher level. For example, A.B.C(1,1,2) PAYROLL.LAST is a valid reference to the and A(1,1,2).B.0 have the same meaning as name PAYROLL.NAME.LAST. A(1,1).B(2).0 for the above array of structures. Unless all of the subscripts are moved to the lowest or highest level, the qualified name is said to have interleaved subscripts; thus, A.B(1,1,2).0 ARRAYS OF STRUCTURES has interleaved subscripts. An array declared within an array of A structure name, either major or minor, structures inherits dimensions declared in can be given a dimension attribute in a the containing structure. For example, in DECLARE statement to declare an array of the above declaration for the array of structures. An array of structures is an structures A, the array B is a array whose elements are structures having three-dimensional structure, because it identical names, levels, and elements. For inherits the two dimensions declared for A. example, if a structure, WEATHER, were used If B is unique and requires no to process meteorological information for qualification, any reference to a each month of a year, it might be declared particular B would require three as follows: subscripts, two to identify the specific A
Chapter 3: Data Elements 39 and one to identify the specific B within DECLARE A(20,20), that A. B(10) DEFINED A(2*1SUB,2*1SUB);
B is a subset of A consisting of every even element in the diagonal of the Other Attributes array, A. In other words, B(1) corresponds to A(2,2), B(2) corresponds to A(4,4). Keyword attributes for data variables such as BINARY and DECIMAL are discussed briefly in the preceding sections of this chapter. Other attributes that are not peculiar to one data type may also be applicable. A complete discussion of these attributes is The LIKE Attribute contained in Part II, Section I, "Attributes." Some that are especially applicable to a discussion of data type and The LIKE attribute is used to indicate that data organization are DEFINED, LIKE, the name being declared is to be given the ALIGNED, UNALIGNED, and INITIAL. same structuring as the major structure or minor structure name following the attribute LIKE. For example: The DEFINED Attribute DECLARE 1 BUDGET, 2 RENT, The DEFINED attribute specifies that the 2 FOOD, named data element, structure, or array is 3 MEAT, to occupy the same storage area as that 3 EGGS, assigned to other data. For example, 3 BUTTER, 2 TRANSPORTATION, DECLARE LIST (100,100), 3 WORK, LIST_ITEM (100,100) DEFINED LIST; 3 OTHER, 2 ENTERTAINMENT, LIST is a 100 by 100 two-dimensional array. 1 COST_OF_LIVING LIKE BUDGET; LIST_ITEM is an identical array defined on LIST. A reference to an element in This declaration for COST_OF_LIVING is the LIST_ITEM is the same as a reference to the same as if it had been declared: corresponding element in LIST. DECLARE 1 COST_OF_LIVING, The DEFINED attribute, along with the 2 RENT, POSITION attribute, can be used to 2 FOOD, subdivide or overlay a data item. For 3 MEAT, example: 3 EGGS, 3 BUTTER, DECLARE LIST CHARACTER (50), 2 TRANSPORTATION, LISTA CHARACTER(10) DEFINED LIST, 3 WORK, LISTB CHARACTER(10) DEFINED LIST 3 OTHER, POSITION(11), 2 ENTERTAINMENT; LISTC CHARACTER(30) DEFINED LIST POSITION(21); Note: The LIKE attribute copies structuring, names, and attributes of the LISTA refers to the first ten characters of structure below the level of the specified LIST. LISTB refers to the second ten name only. No dimensionality of the characters of LIST. LISTC refers to the specified name is copied. For example, if last thirty characters of LIST. BUDGET were declared as 1 BUDGET(12), the declaration of COST_OF_LIVING LIKE BUDGET The DEFINED attribute may also be used would not give the dimension attribute to to specify parts of an array through use of COST_OF_LIVING. To achieve dimensionality iSUB variables, in order to constitute a of COST_OF_LIVING, the declaration would new array. The iSUB variables are dummy have to be DECLARE 1 COST_OF_LIVING(12) variables where i can be specified as any LIKE BUDGET. decimal integer constant from 1 through n (where n represents the number of A minor structure name can be declared dimensions for the defined item). The LIKE a major structure of LIKE another value of the dummy variable (iSUB) ranges minor structure. A major structure name from the lower bound to the upper bound of can be declared LIKE a minor structure or the dimension specified by n. For example: LIKE another major structure. The ALIGNED and UNALIGNED Attributes The INITIAL Attribute
The ALIGNED and UNALIGNED attributes are The INITIAL attribute specifies an initial used to specify the positioning in storage value to be assigned to a variable at the of data elements, to influence speed of time storage is allocated for it. For access or storage economy respectively. example: DECLARE NAME CHARACTER(10) INITIAL Note: Use of the UNALIGNED attribute allows ('JOHN DOE'); data interchange with FORTRAN files. See 'Managing Programs' in the PL/I (F) DECLARE PI FIXED DECIMAL (5,4) INITIAL Programmer's Guide, Form C28-6594. (3.1416); DECLARE TABLE (100,100) INITIAL CALL ALIGNED in System/360 implementations SUBR(ALPHA); specifies that the data element is to be aligned on the storage boundary When storage is allocated for NAME, the corresponding to its data type requirement. character string 'JOHN DOE' (padded to 10 characters) will be assigned to it. When PI is allocated, it will be initialized to UNALIGNED in System/360 implementations the value 3.1416. Either value may be specifies that each data element is to be retained throughout the program, or it may stored contiguously with the data element be changed during execution. The third preceding it: a character-string item is to example illustrates the CALL option. It be mapped on the next byte boundary, a indicates that the procedure SUBR is to be bit-string item is to be mapped on the next invoked to perform the initialization. bit, and a word and doubleword item is to be mapped on the next byte boundary. For a variable that is allocated when the program is loaded, that is, a static Defaults are applied at element level. variable, which remains in allocation The default for bit-string data, throughout execution of the program, any character-string data, and numeric value specified in an INITIAL attribute is character data is UNALIGNED; for all other assigned only once. For automatic types of data, the default is ALIGNED. variables, which are allocated at each activation of the declaring block, any ALIGNED or UNALIGNED can be specified specified initialization is assigned with for element, array, or structure variables. each allocation. For controlled variables, The application of either attribute to a which are allocated at the execution of structure is equivalent to applying the ALLOCATE statements, any specified attribute to all contained elements that initialization is assigned with each are not explicitly declared ALIGNED or allocation. Note, however, that this UNALIGNED. initialization can be overridden in the ALLOCATE statement. The F Compiler does The following example illustrates the not allow the INITIAL attribute to be effect of ALIGNED and UNALIGNED specified for based variables. declarations for a structure and its elements: The INITIAL attribute cannot be given for entry names, file names, DEFINED data, DECLARE 1 STRUCTURE, entire structures, parameters, task data, 2 X BIT(2), /* UNALIGNED BY or event data. DEFAULT */ 2 A ALIGNED, /* ALIGNED EXPLICITLY */ Note: The CALL option cannot be used with 3 B, /* ALIGNED FROM A */ the INITIAL attribute for static data. 3 C UNALIGNED, /* UNALIGNED EXPLICITLY */ The INITIAL attribute cannot be used 4 D, /* UNALIGNED FROM C */ without the CALL option for pointer, 4 E ALIGNED, /* ALIGNED EXPLICITLY */ offset, or area data. An area variable is 4 F, /* UNALIGNED FROM C */ automatically initialized with the value of 3 G, /* ALIGNED FROM A */ the EMPTY built-in function, on allocation, 2 H; /* ALIGNED BY DEFAULT */ after which any specified INITIAL CALL is applied. Although UNALIGNED causes economic use of data storage, for System/360 The INITIAL attribute can be specified implementations it will increase the amount for arrays, as well as for element of code generated to access data items that variables. In a structure declaration, are not aligned on the required byte only elementary names can be given the boundaries. INITIAL attribute.
Chapter 3: Data Elements 41 An array or an array of structures can For STATIC arrays, iteration factors be partly initialized or fully initialized. must be decimal integer constants; for For example: arrays of other storage classes, iteration factors may be constants, variables, or DECLARE A(15) CHARACTER(13) INITIAL expressions. ('JOHN DOE', 'RICHARD ROW', 'MARY SMITH'), B (10,10) DECIMAL FIXED(5) INITIAL((25)0,(25)1,(50)0), 1 C(8), The iteration factor should not be 2 D INITIAL (0), confused with the string repetition factor 2 E INITIAL((8)0); discussed earlier in this chapter. Consider the following example: In this example, only the first three elements of A are initialized; the rest of DECLARE TABLE (50) CHARACTER (10) the array is uninitialized. The array B is INITIAL ((10)'A',(25)(10)'B', fully initialized, with the first 25 (24)(1)'C'); elements initialized to 0, the next 25 to 1, and the last 50 to 0. The parenthesized This INITIAL attribute specification numbers (25, 25, and 50) are iteration contains both iteration factors and factors, that specify the number of repetition factors. It specifies that the elements to be initialized. In the first element of TABLE is to be initialized structure C, where the dimension (8) has with a string consisting of 10 A's, each of been inherited by D, only the first element the next 25 elements is to be initialized of D is initialized; where the dimension with a string consisting of 10 B's, and (8) has been inherited by E, all the each of the last 24 elements is to be elements of E are initialized. initialized with the single character C. In the INITIAL attribute specification for When an array of structures is declared a string array, a single parenthesized with the LIKE attribute to obtain the same factor preceding a string constant is structuring as a structure whose elements assumed to be a string repetition factor have been initialized, it should be noted (as in (10)'A'). If more than one appears, that only the first structure in this array the first is assumed to be an iteration of structures will be initialized. For factor, and the second a string repetition example: factor. For this reason (as in (24)(1)'C'), a string repetition factor of DECLARE 1 G, 1 must be inserted if a single string 2 H INITIAL(0), constant is to be used to initialize more 2 I INITIAL(0), than one element. 1 J(8) LIKE G; The CALL option can be used to In this example, only J(1).H and J(1).I are initialize arrays, except for arrays of initialized in the array of structures. static storage class.
42 Chapter 4: Expressions and Data Conversion
An expression is a representation of a Examples of element expressions are: value. A single constant or a variable is an expression. Combinations of constants C * D and/or variables, along with operators and/or parentheses, are expressions. An A(3,2) + B(4,8) expression that contains operators is an operational expression. The constants and RATE. PRIMARY - COST.PRIMARY variables of an operational expression are called operands. A(4,4) * C RATE.SECONDARY / 4 Examples of expressions are: A(4,6) * COST.SECONDARY 27 All of these expressions are element expressions because each operand is an LOSS element variable or constant (even though some may be elements of arrays or A+B elementary names of structures); hence, each expression represents an element (SQTY-QTY)*SPRICE value. Examples of array expressions are: Any expression can be classified as an element expression (also called a scalar A + B expression), an array expression, or a structure expression. An element A * C - D expression is one that represents an element value. An array expression is one B / 10B that represents an array value. A structure expression is one that represents All of these expressions are array a structure value. expressions because at least one operand of each is an array variable; hence, each expression represents an array value. Note For the F Compiler, array variables and that the third example contains the binary structure variables cannot appear in the fixed-point constant 10B. same expression. Element variables and constants, however, can appear in either Examples of structure expressions are: array expressions or structure expressions. An elementary name within a structure or a RATE * COST subscripted name that specifies a single element of an array is an element RATE / 2 expression. Both of these expressions are structure expressions because at least one operand of Note: If an elementary name of a structure each is a structure variable; hence, each is given the dimension attribute, that expression represents a structure value. elementary name is an array variable and can appear only in array expressions. In the examples that follow, assume that the variables have attributes declared as follows: Use of Expressions DECLARE A(10,10) BINARY FIXED (31), B(10,10) BINARY FIXED (31), Expressions that are single constants or 1 RATE, 2 PRIMARY DECIMAL FIXED (4,2), single variables may appear freely 2 SECONDARY DECIMAL FIXED (4,2), throughout a program. However, the syntax 1 COST, 2 PRIMARY DECIMAL FIXED (4,2), of many PL/I statements allows the 2 SECONDARY DECIMAL FIXED (4,2), appearance of operational expressions, so C BINARY FIXED (15), long as evaluation of the expression yields D BINARY FIXED (15); a valid value.
Chapter 4: Expressions and Data Conversion 43 In syntactic descriptions used in this PROBLEM DATA CONVERSION publication, the unqualified term "expression" refers to an element expression, an array expression, or a Data conversion can be applied to all types structure expression. For cases in which of problem data, as listed below. the kind of expression is restricted, the type of restriction is noted; for example, the term "element-expression" in a syntactic description indicates that neither an array expression nor a structure Bit-string to Character-String expression is valid. The bit 1 becomes the character 1; the bit Note: Although operational expressions can 0 becomes the character 0. appear in a number of different PL/I statements, their most common occurrences are in assignment statements of the form: Character-String to Bit-string A = B + C; The character string should contain the The assignment statement has no PL/I characters 1 and 0 only, in which case the keyword. The assignment symbol (=) character 1 becomes the bit 1, and the indicates that the value of the expression character 0 becomes the bit 0. The on the right (B + C) is to be assigned to CONVERSION condition is raised by an the variable on the left (A). For purposes attempt to convert any character other than of illustration in this chapter, some 1 or 0 to a bit. examples of expressions are shown in assignment statements.
Character-String to Arithmetic
The character string must be in the form of Data Conversion in Operational Expressions a signed or unsigned arithmetic constant (or an expression representation of a COMPLEX data item). The constant may be An operational expression consists of one surrounded by blanks, but blanks must not or more single operations. A single be imbedded in a number. Any character operation is either a prefix operation (an other than those allowed in arithmetic data operator preceding a single operand) or an will raise the CONVERSION condition if infix operation (an operator between two conversion is attempted. operands). The two operands of any infix operation, when the operation is performed, Note: In the conversion, for an infix usually must be of the same data type, as operation, of a character string that specified by the attributes of a variable represents a fixed-point constant -- either or the notation used in writing a constant. decimal or binary -- any fractional portion will be lost if it is converted to The operands of an operation in a PL/I fixed-point. If the conversion is to expression are automatically converted, if floating-point, it will retain its necessary, to a common representation fractional value. Rules for the precision before the operation is performed. General of such conversion are listed in Part LI, rules for conversion of different data Section F, "Problem Data Conversion." types are discussed in the following paragraphs and in a later section of this chapter, "Concepts of Data Conversion." Detailed rules for specific cases, Arithmetic to Character-String including rules for computing the precision or length of a converted item, can be found in Part II, Section F, "Problem Data The value of an internal coded arithmetic Conversion." operand is converted to its character representation. The converted field is a Data conversion is mainly confined to character string in the form of a valid problem data. The only conversion possible arithmetic constant. The length of the with program control data is conversion character string is dependent upon the between offset and pointer types. precision of the arithmetic data item.
44 Bit-string to Arithmetic Pointer to Offset
A bit string is interpreted as an unsigned A pointer value is converted to offset by binary integer and is converted to effectively deducting the pointer value for fixed-point binary of positive value. The the start of the area from the pointer base and scale are further converted, if value to be converted. This conversion is necessary. limited to pointer values that relate to addresses within the area named in the OFFSET attribute. Arithmetic to Bit-string
The absolute value is converted, if Conversion by Assignment necessary, to a real fixed-point binary integer. Ignoring the plus sign, the integer is then interpreted as a bit In addition to conversion performed as the string. The length of the bit string is result of an operation in the evaluation of dependent upon the precision of the an expression, conversion will also occur original unconverted arithmetic data item. when a data item -- or the result of an expression evaluation -- is assigned to a variable whose attributes differ from the attributes of the item assigned. The rules Arithmetic Mode Conversion for such conversion are generally the same as those discussed above and in Part II, Section F, "Problem Data Conversion." If a complex data item is converted to a real data item, the result is the real part of the complex item. Expression Operations A real data item is converted to a complex data item by adding an imaginary part of zero. An operational expression can specify one or more single operations. The class of operation is dependent upon the class of operator specified for the operation. Arithmetic Base and Scale Conversion There are four classes of operations -- arithmetic, bit-string, comparison, and concatenation. The precision of the result of an arithmetic base or scale conversion is dependent upon the precision of the original arithmetic data item. The rules ARITHMETIC OPERATIONS are listed in Part II, Section F, "Problem Data Conversion." An arithmetic operation is one that is specified by combining operands with one of the following operators: LOCATOR DATA CONVERSION
Only offset to pointer conversion occurs as The plus sign and the minus sign can appear a result of an operational expression either as prefix operators (associated with (locator variables are restricted to = and and preceding a single operand, such as +A 1 = comparison operations), but either of or -A) or as infix operators (associated the following types of conversion can with and between two operands, such as A+B result from assignment. (See also Chapter or A-B). All other arithmetic operators 14, "Based Variables and List Processing.") can appear only as infix operators. An expression of greater complexity can be composed of a set of such arithmetic Offset to Pointer operations. Note that prefix operators can precede and be associated with any of the operands of an infix operation. For An offset value is converted ..o pointer by example, in the expression A*-B, the minus combining the offset value with the pointer sign preceding the variable B indicates value relating to the start of the area that the value of A is to be multiplied by named in the OFFSET attribute. the negative value of B.
Chapter 4: Expressions and Data Conversion 45 More than one prefix operator can exception to this rule is in the case of precede and be associated with a single exponentiation when the first operand is of variable. More than one positive prefix floating-point scale and the second operand operator will have no cumulative effect, (the exponent of the operation) is but two consecutive negative prefix fixed-point with a scale factor of zero, operators will have the same effect as a that is, a fixed-point integer constant or single positive prefix operator. For a variable that has been declared with example: precision (p,0). In such a case, no conversion is necessary, but the result -A The single minus sign has the effect will be floating-point. of reversing the sign of the value that A represents. If both operands of an exponentiation operation are fixed-point, conversions may --A One minus sign reverses the sign of occur, as follows: the value that A represents. The second minus sign again reverses the 1. Both operands are converted to sign of the value, restoring it to floating-point if the exponent has a the original arithmetic value precision other than (p,0). represented by A. 2. The first operand is converted to ---A Three minus signs reverse the sign of floating-point unless the exponent is the value three times, giving the an unsigned fixed-point integer same result as a single minus sign. constant. 3. The first operand is converted to floating-point if precisions indicate Data Conversion in Arithmetic Operations that the result of the fixed-point exponentiation would exceed the maximum number of digits allowed for The two operands of an arithmetic operation the implementation (for System/360, 15 may differ in type, base, mode, precision, decimal digits or 31 binary digits). and scale. When they differ, conversion Further details and examples of takes place according to rules listed conversion in exponentiation are below. Certain other rules -- as stated included in the section "Concepts of below -- may apply in cases of Data Conversion" in this chapter. exponentiation. TYPE: Character-string operands, numeric character field operands (digits recorded in character form), and bit-string operands Results of Arithmetic Operations are converted to internal coded arithmetic type. The result of an arithmetic operation is always in coded arithmetic The "result" of an arithmetic operation, as form. Note that type conversion is the used in the following text, may refer to an only conversion that can take place in an intermediate result if the operation is arithmetic prefix operation. only one of several operations specified in a single operational expression. Any BASE: If the bases of the two operands result may require further conversion if it differ, the decimal operand is converted to is an intermediate result that is used as binary. an operand of a subsequent operation or if it is assigned to a variable. MODE: If the modes of the two operands differ, the real operand is converted to After required conversions have taken complex mode (by acquiring an imaginary place, the arithmetic operation is part of zero with the same base, scale, and performed. If maximum precision is precision as the real part). The exception exceeded and truncation is necessary, the to this rule is in the case of truncation is performed on low-order exponentiation when the second operand (the fractional digits, regardless of base or exponent of the operation) is fixed-point scale of the operands. In some cases real with a scale factor of zero. In such involving fixed-point data, however, a case, no conversion is necessary. high-order digits may sometimes be lost when scale factors are such that point PRECISION: If only precisions differ, no alignment does not allow for the declared type conversion is necessary. number of integer digits. SCALE: If the scales of the two operands The base, scale, mode, and precision of differ, the fixed-point operand is the result depend upon the operands and the converted to floating-point scale. The operator involved.
46
For prefix operations, the result has q = maximum (q1, q2) the same base, scale, mode, and precision as the converted operand. Note that the Example: result of -A, where A is a string, is an arithmetic result, since A must first be 12354.2385 + 222.11111 converted to coded arithmetic form before A B C D the operation can be performed. The total number of digits in the result For infix operations, the result depends would be equal to 1 plus the number of upon the scale of the operands in the digits in A plus the number of digits in D. following ways: The scale factor of the result would be equal to the number of digits in D. FLOATING-POINT: If the converted operands Precision of the result would be (11,5). of an infix operation are of floating-point scale, the result is of floating-point MULTIPLICATION: The total number of digits scale, and the base and mode of the result in the result is equal to one plus the are the common base and mode of the number of digits in operand one plus the operands. The precision of the result is number of digits in operand two. The total the greater of the precisions of the two number of digits cannot exceed the maximum operands. number of digits allowed for the implementation (15 decimal, 31 binary). FIXED-POINT: If the converted operands of The scale factor of the result is the sum an infix operation are of fixed-point of the scale factors of the two operands. scale, the result is of fixed-point scale, and the base and mode of the result are the Formulas: common base and mode of the operands. The precision of a fixed-point result depends P2P =+ 1 P1+ upon operands, according to the rules listed below. q = q1 +q2 In the formulas for computing precision, Example: the symbols used are as follows: 345.432 * 22.45 p represents the total number of A B C D digits of the result The total number of digits in the result q represents the scale factor of would be equal to 1 plus the sum of the the result number of digits in A, B, C, and D. The scale factor of the result would be the sum p1represents the total number of of the number of digits in B and D. digits of the first operand Precision of the result would be (11,5).
q1 represents the scale factor of DLVLSION: The total number of digits in the first operand the quotient is equal to the maximum allowed by the implementation (15 decimal, P2 represents the total number of 31 binary). The scale factor of the digits of the second operand quotient is dependent upon the number of integer digits of the dividend (A in the q 2 represents the scale factor of example below), and the number of the second operand fractional digits of the divisor (D in the example below). The scale factor is equal ADDITION AND SUBTRACTION: The total number to the total number of digits of the result of digits in the result is equal to 1 plus minus the sum of A and D. the number of integer digits of the operand having the greater number of integer digits Formulas: plus the number of fractional digits of the operand having the greater number of p = 15 decimal, 31 binary fractional digits. The total number of positions cannot exceed the maximum number q = 15 (or 31)-((pi-q1) + q2) of digits allowed (15 decimal digits, 31 binary digits). The scale factor of the Example: result is equal to the larger scale factor of the two operands. 432.432 / 2 A B C D Formulas: The total number of digits in the quotient p = 1 + maximum (p1-g1, p2-q2) would be 15 (the maximum number allowed). + maximum (q1, q2) The scale factor would be 15 minus the sum
Chapter 4: Expressions and Data Conversion 47 of 3 (A, the number of integer digits in b. If x=0 and the real part of y <=0 the dividend) and zero (D, the number of or the imaginary part of y =0, the fractional digits in the divisor). ERROR condition is raised. Precision of the quotient would be (15,12). (As pointed out under "Data Conversion in Note that any change in the number of Arithmetic Operations," if the exponent is integer digits in the dividend or any not an unsigned real fixed-point integer change in the number of fractional digits constant, or if the total number of digits in the divisor will change the precision of of the result would exceed 15 decimal the quotient, even if all additional digits digits or 31 binary digits, the first are zeros. operand is converted to floating-point scale, and the rules for floating-point Examples: exponentiation apply.) 00432.432 / 2 Formulas: 432.432 / 2.0000 p = ((p1+1)*(value-of-exponent))-1 Precision of the quotient of the first q = q1 * (value-of-exponent) example would be (15,10); scale factor is equal to 15-(5+0). Precision of the Example: quotient of the second example would be (15,8); scale factor is equal to 15-(3+4). 32 ** 5 Caution: In the use of fixed-point The total number of digits in the result division operations, care should be taken would be 14. This is arrived at by that declared precision of variables and multiplying a number equal to one plus the apparent precision of constants will not number of digits in the first operand (1+2) give a result with a scale factor that can by the value of the exponent and force the result of subsequent operations subtracting one. The scale factor of the to exceed the maximum number of digits result would be zero (0 * 5, scale factor allowed by the implementation. of the first operand multiplied by the value of the exponent). EXPONENTIATLON:If the second operand (the 3. The expression X**(-N) for N>0 is exponent) is an unsigned nonzero real evaluated by taking the reciprocal of fixed-point constant of precision (p,0), X**N. This may cause the OVERFLOW the total number of positions in the result condition to occur as the intermediate is equal to one less than the product of a result is computed, which corresponds number that is one greater than the number to UNDERFLOW in the original of digits in the first operand multiplied expression. by the value of the second operand (the exponent). The scale factor of the result is equal to the product of the scale factor of the first operand multiplied by the BIT-STRING OPERATIONS value of the second operand (the exponent). Note: Some special cases of exponentiation A bit-string operation is one that is are defined as follows: specified by combining operands with one of the following operators: 1. Real mode, x**y & a. Lf x=0 and y>0, the result is 0. The first operator, the "not" symbol, can b. If x=0 and y<=0, the ERROR be used as a prefix operator only. The condition is raised. second and third operators, the "and" symbol and the "or" symbol, can be used as c. If x*0 and y=0, the result is 1. infix operators only. (The operators have the same function as in Boolean algebra.) d. If x<0 and y is not fixed-point with precision (p,0), the ERROR Operands of a bit-string operation are, condition is raised. if necessary, converted to bit strings before the operation is performed. If the 2. Complex mode, x**y operands of an infix operation are of unequal length, the shorter is extended on a. If x=0 and y has its real part >0 the right with zeros. and its imaginary part =0, the result is 0. The result of a bit-string operation is
48 a bit string equal in length to the length of the operands (the two operands, after conversion, always are the same length). If either is a varying-length bit string, These operators specify "less than," "not the result is of varying length. less than," "less than or equal to," "equal to," "not equal to," "greater than or equal Bit-string operations are performed on a to," "greater than," and "not greater bit-by-bit basis. The effect of the "not" than." operation is bit reversal; that is, the result of 1 1 is 0; the result of 1 0 is 1. There are three types of comparisons: The result of an "and" operation is 1 only if both corresponding bits are 1; in all 1. Algebraic, which involves the other cases, the result is 0. The result comparison of signed arithmetic values of an "or" operation is 1 if either or both in internal coded arithmetic form. If of the corresponding bits are 1; in all operands differ in base, scale, other cases, the result is 0. The precision, or mode, they are converted following table illustrates the result for according to the rules for arithmetic each bit position for each of the operations. Numeric character data is operators: converted to coded arithmetic before comparison.
2. Character, which involves left-to-right, character-by-character comparisons of characters according to the collating sequence. 3. Bit, which involves left-to-right, bit-by-bit comparison of binary digits. If the operands of a comparison are not immediately compatible (that is, if their data types are appropriate to different types of comparison), the operand of the lower comparison type is converted to conform to the comparison type of the More than one bit-string operation can operand of the higher type. The priority be combined in a single expression that of comparison types is (1) algebraic yields a bit-string value. (highest), (2) character string, (3) bit string. Thus, for example, if a bit string In the following examples, if the value were to be compared with a fixed decimal of operand A is '010111'B, the value of value, the bit string would be converted to operand B is '111111'B, and the value of arithmetic (i.e., fixed binary) for operand C is '110'B, then: algebraic comparison with the decimal value (which would also be converted to fixed binary for the comparison). If operands of a character-string comparison, after conversion, are of different lengths, the shorter operand is extended on the right with blanks. If operands of a bit-string comparison are of different lengths, the shorter is extended on the right with zeros. In the execution of PL/I programs, comparisons of character data will observe the collating sequence resulting from the representations of characters in bytes of System/360 storage, in extended library coded decimal interchange code (EBCDIC). COMPARISON OPERATIONS The result of a comparison operation always is a bit string of length one; the value is '1'B if the relationship is true, A comparison operation is one that is or '0'B if the relationship is not true. specified by combining operands with one of the following operators: The most common occurrences of
Chapter 4: Expressions and Data Conversion 49 comparison operations are in the IF strings or if both operands are bit statement, of the following format: strings, no conversion takes place. Otherwise both operands are converted to IF A = B character strings. THEN action-if-true The results of concatenation operations are as follows: ELSE action-if-false
The evaluation of the expression A = B Bit String: A bit string whose length is yields either '1'B or '0'B. Depending upon equal to the sum of the lengths of the two the value, either the THEN portion or the bit-string operands. ELSE portion of the IF statement is executed. Character String: A character string whose length is equal to the sum of the lengths Comparison operations need not be of the two character-string operands. If limited to IF statements, however. The an operand requires conversion for the following assignment statement could be concatenation operation, the result is valid: dependent upon the length of the character string to which the operand is converted. X = A < B; For example, if A has the attributes and In this example, the value '1'B would be value of the constant '010111'B, B of the assigned to X if A is less than B; constant '101'B, C of the constant 'XY,Z', otherwise, the value '0'B would be and D of the constant 'AA/BB', then assigned. In the same way, the following assignment statement could be valid: A||B yields '010111101'B X = A = B; A||A||B yields '010111010111101'B The first symbol (=) is the assignment C||D yields 'XY,ZAA/BB' symbol; the second (=) is the comparison operator. If A is equal to B, the value of D||C yields 'AA/BBXY,Z' X will be ' 1'B; if A is not equal to B, the value of X will be '0'B. B||D yields '101AA/BB' Only the comparison operations of Note that, in the last example, the bit "equal" and "not equal" are valid for string '101'B is converted to the character comparisons of complex operands, or string '101' before the concatenation is comparisons of locator operands. performed. The , result is a character Comparison operations with program control string consisting of eight characters. data other than locator data are not allowed. Note: If either of the operands of a concatenation operation has the VARYING attribute, the result will be a VARYING string. When VARYING strings are CONCATENATION OPERATIONS concatenated, the intermediate string created has a length equal to the sum of the maximum lengths. If the maximum A concatenation operation is one that is lengths are known at compile time and their specified by combining operands with the sum exceeds 32767, then a truncated concatenation symbol: intermediate string of length 32767 will be created and an error message produced. If | the maximum length of either operand is not known at compile time and their sum exceeds It signifies that the operands are to be 32767, a truncated intermediate string of joined in such a way that the last length 32767 will be created but there will character or bit of the operand to the left be no diagnostic message. will immediately precede the first character or bit of the operand to the The use of adjustable VARYING strings right, with no intervening bits or can create a similar problem. When an characters. operand of the concatenate operator or the argument of the UNSPEC function is an The concatenation operator can cause adjustable VARYING string, the length of conversion to string type since the intermediate result field is not concatenation can be performed only upon tested, and execution will fail. This strings, either character strings or bit situation can also occur with SUBSTR if the strings' If both operands are character third argument is not a constant, because
50 in this case the result is an adjustable however, depends upon the priority of the VARYING string. operators appearing in the expression. Similarly, when a VARYING string is passed as an argument to a fixed-length string parameter, the length of the temporary argument created is the maximum Priority of Operators length. If the user wishes to pass the current length of the VARYING string (in, for example, Y=X(A)), a possible method is: In the evaluation of expressions, priority of the operators is as follows: DOL ATEMP CHAR(*) CTL; ALLOCATE ATEMP CHAR(LENGTH(A)); ATEMP=A; Y=X(ATEMP); FREE ATEMP;
COMBINATIONS OF OPERATIONS If two or more operators of the highest priority appear in the same expression, the Different types of operations can be order of priority of those operators is combined within the same operational from right to left; that is, the rightmost expression. Any combination can be used. exponentiation or prefix operator has the For example, the expression shown in the highest priority. Each succeeding following assignment statement is valid: exponentiation or prefix operator to the left has the next highest priority. RESULT = A + B < C £ D; For all other operators, if two or more Each operation within the expression is operators of the same priority appear in evaluated according to the rules for that the same expression, the order of priority kind of operation, with necessary data of those operators is from left to right. conversions taking place before the operation is performed. Note that the order of evaluation of the expression in the assignment statement: Assume that the variables given above are declared as follows: RESULT = A + B < C & D; DECLARE RESULT BIT(3), is the result of the priority of the A FIXED DECIMAL(1), operators. It is as if various elements of B FIXED BINARY (3), the expression were enclosed in parentheses C CHARACTER(2), D BIT(4); as follows: • The decimal value of A would be (A) + (B) converted to binary base. (A + B) < (C) (A + B < C) & (D) • The binary addition would be performed, adding A and B. The order of evaluation (and, consequently, the result) of an expression • The binary result would be compared can be changed through the use of with the converted binary value of C. parentheses. The above expression, for example, might be changed as follows: • The bit-string result of the comparison would be extended to the length of the (A + B) < (C & D) bit string D, and the 'and" operation would be performed. The order of evaluation of this expression would yield a bit string of • The result of the "and" operation, a length one, the result of the comparison bit string of length 4, would be operation. In such an expression, those assigned to RESULT without conversion, expressions enclosed in parentheses are but with truncation on the right. evaluated first, to be reduced to a single value, before they are considered in The expression in this example is relation to surrounding operators. Within described as being evaluated the language, however, no rules specify operation-by-operation, from left to right. which of two parenthesized expressions, Such would be the case for this particular such as those in the above example, would expression. The order of evaluation, be evaluated first.
Chapter 4: Expressions and Data Conversion 51 The value of A would be converted to A + (B ** 3) fixed-point binary, and the addition would be performed, yielding a fixed-point binary (C * D) - E result (RESULT 1). The value of C would be converted to a bit string (if valid for such conversion) and the "and" operation would be performed. Array Expressions At this point, the expression would have been reduced to: An array expression is a single array RESULT1 < RESULT_2 variable or an expression that includes at least one array operand. Array expressions RESULT_2 would be converted to binary, and may also include operators -- both prefix the algebraic comparison would be and infix -- element variables and performed, yielding the bit-string result constants. of the entire expression. Evaluation of an array expression yields The priority of operators is defined an array result. All operations performed only within operands (or sub-operands). It on arrays are performed on an does not necessarily hold true for an element-by-element basis, in row-major entire expression. Consider the following order. Therefore, all arrays referred to example: in an array expression must be of identical bounds. A + (B < C) & (D || E ** F) Although comparison operators are valid The priority of the operators specifies, in for use with array operands, an array this case, only that the exponentiation operand cannot appear in the IF clause of will occur before the concatenation. It an IF statement. Only an element does not specify the order of the operation expression is valid in the IF clause, since in relation to the evaluation of the other the IF statement tests a single true or operand (A + < C)). false result.
Any operational expression (except a Note: Array expressions are not always prefix expression) must eventually be expressions of conventional matrix algebra. reduced to a single infix operation. The operands and operator of that operation For the F Compiler the level of nesting determine the attributes of the result of in array expressions is limited by the the entire expression. For instance, in following rule: the first example of combining operations (which contains no parentheses), the "and" For each level of nesting of array operator is the operator of the final infix expressions, add 2 for the maximum number operation; in this case, the result of of dimensions in the array, add 3 for each evaluation of the expression is a bit subscript or argument list in the string of length 4. In the second example expression or assignment, and finally, add (because of the use of parentheses), the 5. The total for the whole nest should not operator of the final infix operation is exceed 900. the comparison operator, and the evaluation yields a bit string of length 2. In general, unless parentheses are used PREFIX OPERATORS AND ARRAYS within the expression, the operator of lowest priority determines the operands of the final operation. For example: The result of the operation of a prefix operator on an array is an array of A+ B ** 3 || C* D E identical bounds, each element of which is the result of the operation having been In this case, the concatenation operator performed upon each element of the original indicates that the final operation will be: array. For example: (A + B ** 3) (C * D - E) If A is the array 5 3 -9
The evaluation will yield a 2 -2 7 character-string result. 6 3 -4 Subexpressions can be analyzed in the same way. The two operands of the expression can be defined as follows: then -A is the array -5 -3 9
52
-1 2 -7 Array and Array Operations -6 -3 4 If two arrays are connected by an infix operator, the two arrays must be of identical bounds. The result is an array with bounds identical to those of the original arrays; the operation is performed INFIX OPERATORS AND ARRAYS upon the corresponding elements of the two original arrays. Infix operations that include an array variable as one operand may have an element Note that the arrays must have identical or another array as the other operand. bounds. They must have the same number of dimensions, and corresponding dimensions must have identical lower bounds and identical upper bounds. For example, the bounds of an array declared X(20,6) are not Array and Element Operations identical to the bounds of an array declared Y(2:22,3:8) although the extents are the same for corresponding dimensions, The result of an operation in which an and the number of elements is the same. element and an array are connected by an infix operator is an array with bounds identical to the original array, each Examples of array infix expressions are: element of which is the result of the operation performed upon the corresponding element of the original array and the If A is the array 2 4 3 single element. For example: 6 2 7 If A is the array 5 20 8 4 8 2 22 22 3
then A*3 is the array 25 30 24 and if B is the array 2 5 7 36 33 9 8 3 4 The element of an array-element 6 3 2 operation can be an element of the same array. For example, the expression A*A(2,3) would give the same result in the case of the array A above, since the value then A+B is the array 3 9 20 of A(2,3) is 3. 24 4 22 Consider the following assignment statement: 20 22 3 A = A * A(2,2); Again, using the above values for A, the and A*B is the array 2 20 22 newly assigned value of A would be: 48 3 28 50 200 800 24 24 2 2200 2200 300 Note that the original value for A(2,2), which is 20, is used in the evaluation for only the first two elements of A. Since the result of the expression is assigned to Array and Structure Operations A, changing the value of A, the new value of A(2,2) is used for all subsequent operations. The first two elements are For the F Compiler, no reference can be multiplied by 20, the original value of made to both an array and a structure in A(1,2); all other elements are multiplied the same expression or in the same by 200, the new value of A(2,2). assignment statement.
Chapter 4: Expressions and Data Conversion 53 Data Conversion in Array Expressions PREFIX OPERATORS AND STRUCTURES
The examples in this discussion of array The result of the operation of a prefix expressions have shown only single operator on a structure is a structure of arithmetic operations. The rules for identical structuring, each element of combining operations and for data which is the result of the operation having conversion of operands are the same as been performed upon each element of the those for element operations. original structure.
Note: Since structures may contain elements of many different data types, a prefix operation in a structure expression would be meaningless unless the operation can be Structure Expressions validly performed upon every element represented by the structure variable, which is either a major structure name or a A structure expression is a single minor structure name. structure variable or an expression that includes at least one structure operand and does not contain an array operand. Element variables and constants can be operands of a structure expression. Evaluation of a structure expression yields a structure result. A structure operand can be a major INFIX OPERATORS AND STRUCTURES structure name or a minor structure name. Although comparison operators are valid Infix operations that include a structure for use with structure operands, a variable as one operand may have an element structure operand cannot appear in the or another structure as the other operand. IF clause of an IF statement. Only an element expression is valid in the IF clause, since the IF statement tests a single true or Structure operands in a structure false result. expression need not be major structure names. A minor structure name, at any All operations performed on structures level, is a structure variable. Thus, if are performed on an element-by-element M.N is a minor structure in the major basis. Except in a BY NAME assignment (see structure N, the following is a structure below), all structure variables appearing expression: in a structure expression must have identical structuring. M.N & '2020'B Identical structuring means that the structures must have the same minor structuring and the same number of contained elements and arrays and that the positioning of the elements and arrays within the structure (and within the minor Structure and Element Operations structures if any) must be the same. Arrays in corresponding positions must have identical bounds. Names do not have to be When an operation has one structure and one the same. Data types of corresponding element operand, it is the same as a series elements do not have to be the same, so of operations, one for each element in the long as valid conversion can be performed. structure. Each sub-operation involves a structure element and the single element. For the F Compiler the level of nesting in structure expressions is limited by the Consider the following structure: following rule: 2 A For each level of nesting of structure 2 B expressions, add 2 for the maximum number 3 C of dimensions in the structure, add 2 for 3 D the maximum level in a structure 3 E expression, add 3 for each subscript or 2 F argument list in the expression or 3 G assignment, and finally, add 25. The total 3 H for the whole nest should not exceed 900. 3 I
54 If X is an element variable, then A * X is 1 ONE 1 TWO 1 THREE equivalent to: 2 PART1 2 PART1 2 PART1 3 RED 3 BLUE 3 RED A.0 * X 3 ORANGE 3 GREEN 3 BLUE A.D * X 2 PART2 3 RED 3 BROWN A.E * X 3 YELLOW 2 PART2 2 PART2 A.G * X 3 BLUE 3 BROWN 3 YELLOW A.H * X 3 GREEN 3 YELLOW 3 GREEN A.I * X ONE = TWO, BY NAME; ONE.PART1 = THREE.PART1, BY NAME; ONE = TWO + THREE, BY NAME; The first assignment statement would be the same as the following: Structure and Structure Operations ONE.PART1.RED = TWO.PART1.RED; When an operation has two structure ONE.PART2.YELLOW = TWO.PART2.YELLOW; operands, it is the same as a series of element operations, one for each The second assignment statement would be corresponding pair of elements. the same as the following: ONE.PART1.RED = THREE.PART1.RED; For example, if A is the structure shown in the previous example and if M is the The third assignment statement would be the following structure: same as the following: ONE.PART1.RED = TWO.PART1.RED 1 M + THREE.PART1.RED; 2 N 3 0 ONE.PART2.YELLOW = TWO.PART2.YELLOW 3 P + THREE.PART2.YELLOW; 3 Q 2 R The BY NAME option can appear in an 3 S assignment statement only. It indicates 3 T that assignment of elements of a structure 3 U is to be made only for those elements whose names are common to both structures. then A || M is equivalent to: Except for the highest-level qualifier specified in the assignment statement, all qualifying names must be identical. If an operational expression appears in an assignment statement with the BY NAME option, operation and assignment are performed only upon those elements whose names have been declared in each of the structures. In the third assignment statement above, no operation is performed upon ONE.PART2.GREEN and THREE.PART2.GREEN, Structure Assignment BY NAME because GREEN does not appear as an elementary name in PART2 of TWO. One exception to the rule that operands of a structure expression must have the same structuring is the case in which the Operands of Expressions structure expression appears in an assignment statement with the BY NAME option. An operand of an expression can be a constant, an element variable, an array The BY NAME appears at the end of a variable, or a structure variable. An structure assignment statement and is operand can also be an expression that preceded by a comma. Examples are shown represents a value that is the result of a below. computation, as shown in the following assignment statement: Consider the following structures and assignment statements: A = B * SQRT(C);
Chapter 4: Expressions and Data Conversion 55
FUNOTION REFERENCE OPERANDS In the above example, a substring five characters in length, beginning with A function reference consists of a name character 20 of the string B, is to be and, usually, a parenthesized list of one assigned to the last five characters of the or more variables, constants, or other string A. That is, the last five expressions. The name is the name of a characters of A are to be replaced by block of coding written to perform specific characters 20 through 24 of B. The first computations upon the data represented by five characters of A remain unchanged, as the list and to substitute the computed do all of the characters of B. value in place of the function reference. All eleven of the built-in functions Assume, in the above example, that C has that can be used as pseudo-variables are the value 16. The function reference discussed in Part II, Section G, "Built-In SQRT(C) causes execution of the coding that Functions and Pseudo-Variables." No would compute the square root of 16 and programmer-written function can be used as replace the function reference with the a pseudo-variable. value 4. In effect, the assignment statement would become:
A = B * 4; Concepts of Data Conversion The coding represented by the name in the function reference is called a Data conversion is the transformation of function. The function SQRT is one of the the representation of a value from one form PL/I built-in functions. Built-in to another. PL/I makes very few functions, which provide a number of restrictions upon the use of the available different operations, are a part of the forms of data representation or upon the PL/I language. A complete discussion of mixing of different representations within each appears in Part II, Section G, an expression. "Built-In Functions and Pseudo-Variables." In addition, a programmer may write Programmers who wish to make use of this functions for other purposes (as described freedom must understand that mixed in Chapter 12, "Subroutines and expressions imply conversions. If Functions"), and the names of those conversions take place at execution time, functions can be used in function they will slow down the execution, references. sometimes significantly. Unless care is taken, conversions can result in loss of The use of a function reference is not precision and can cause unexpected results. limited to operands of operational A lack of understanding of conversions can expressions. A function reference is, in lead to logical errors and inaccuracies itself, an expression and can be used that are sometimes hard to trace. wherever an expression is allowed. It cannot be used in those cases where a This section is concerned primarily with variable represents a receiving field, such the concepts of conversion operations. as to the left of an assignment symbol. Specific rules for each kind of conversion are listed in Part II, Section F, "Problem There are, however, eleven built-in Data Conversion." Earlier sections of this functions that can be used as chapter discuss circumstances under which pseudo-variables. A pseudo-variable is a conversion can occur during evaluation of built-in function name that is used in a expressions. This section deals with the receiving field. Consider the following processes of the conversion. example: The subject of conversion can be DECLARE A CHARACTER(10), considered in two parts, first, determining B CHARACTER(30); the target attributes, and, second, the conversion operation with known source and SUBSTR(A,6,5) = SUBSTR(B,20,5); target attributes. This section deals with
56 determining target attributes. Rules for When an expression is evaluated, the conversion operations are given in Part II, target attributes usually are partly Section F, "Problem Data Conversion." derived from the source, partly from the Within each section, here and in Part II, operation being performed, and partly from arithmetic conversion and type conversion the attributes of a second operand. Some are considered separately. assumptions may be made, and some implementation restrictions (for example, maximum precision) and conventions exist. The target of a conversion is the After an expression is evaluated, the receiving field to which the converted result may be further converted. In this value is assigned. In the case of a direct case, the target attributes usually are assignment, such as A = B, in which independent of the source. Since the conversion must take place, the variable to process of determining target attributes is the left of the assignment symbol (in this different for expression operands and for case, A) is the target. Consider the the results of expression evaluation, the following example, however: two cases are dealt with separately.
DECLARE A CHARACTER(8), B FIXED DECIMAL(3,2), A conversion always involves a source C FIXED BINARY(10); data item and a target data item, that is, the original representation of the value A = B + C; and the converted representation of the value. All of the attributes of both the During the evaluation of the expression B+C source data item and the target data item and during the assignment of that result, are known, or assumed, at compile time. there are four different targets, as follows: 1. The compiler-created temporary to It is possible for a conversion to which the converted binary equivalent involve intermediate results whose of B is assigned attributes may depend upon the source value. For example, conversion from 2. The compiler-created temporary to character string to arithmetic may require which the binary result of the an intermediate conversion and, thus, an addition is assigned inter- mediate result, before final conversion is completed. The final target 3. The temporary to which the converted attributes in such cases, however, are decimal fixed-point equivalent of the always determined from the source data item binary result is assigned and are independent of the values of the variables. 4. A, the final destination of the result, to which the converted The maximum number of temporary results character-string equivalent of the which may exist during the evaluation of an decimal fixed-point representation of expression or during an assignment the value is assigned statement is 200. An estimate of the number of temporary results which may exist The attributes of the first target are during the evaluation of an expression can determined from the attributes of the be obtained from the following: source (B), from the operator, and from the attributes of the other o perand (if one At each level of parentheses, count one for operand of an arithmetic infix operator is each operator which is forced to be binary, the other is converted to binary evaluated before an inner level of before evaluation). The attributes of the parentheses. For each such operator, count second target are determined from the one for each operand which requires attributes of the source (C and the conversion before use, count one for each converted representation of B). The nested function, count one for each attributes of the third target are subscripted variable used as a target in an determined in part from the source (the assignment statement, and finally, count second target) and in part from the one for each pseudo-variable and each attributes of the eventual target (A). argument of a pseudo-variable. (The only attribute determined from the eventual target is DECIMAL, since a binary arithmetic representation must be converted to decimal representation before it can be It should be realized that constants converted to a character string.) The also have attributes; the constant 1.0 is attributes of the fourth target (A) are different from the constants 1, '1'B, '1', known from the DECLARE statement. 1B, or 1E0. Constants may be converted at
Chapter 4: Expressions and Data Conversion 57 compile time or at execution time, but in STRING TO ARITHMETIC either case, the rules are the same. In the conversion of bit-string or character-string data to arithmetic, the string must consist of digits that represent a valid arithmetic constant. The Target Attributes for Type Conversion compiler has no way of determining the attributes of the constant represented by the string; therefore, attributes must be When an expression operand requires type assumed for the target. conversion, some target attributes must be assumed or deduced from the source. Some In the case of character-string to of these assumptions can be made based on arithmetic conversion, the attributes the operator, as shown in Figure 4-1. assumed for the target are those attributes that would have been assumed if a fixed-point decimal integer of precision (15,0) had appeared in place of the string. Similarly, for a bit-string source that is to be converted to arithmetic type, the attributes of the target are the attributes that would have been given to the target if a fixed-point binary integer of precision (31,0) had appeared in place of the bit string.
Target Attributes for Arithmetic Expression Operands
Except for exponentiation, the target attributes for arithmetic conversion are assumed as follows: BINARY unless both operands are DECIMAL, in which case no base conversion is performed BIT TO CHARACTER AND CHARACTER TO BIT FLOAT unless both operands are FIXED, in which case no scale conversion is performed In the conversion of bit to character, and character to bit, the length of the target COMPLEX unless both operands are REAL, (in bits or characters) is the same as the in which case no mode length of the source (in bits or conversion is performed characters). precision unless base or scale conversion of source is performed (see Figure 4-2, "Precision for Arithmetic Conversion") ARITBMETIC TO STRING In the case of exponentiation, the base and precision are determined as for other operations. The target scale of the first In the conversion of arithmetic to operand is always FLOAT unless the first bit-string or character-string data, the operand source is FIXED and the second length of the target is deduced from the operand (the exponent) is an unsigned precision of the source. Algorithms for fixed-point integer constant with a value determining the length of the target are small enough that the result of the given below under the headings "Lengths of exponentiation will not exceed the maximum Bit-string Targets" and "Lengths of number of digits allowed (for System/360 Character-String Targets." In the case of implementations, 31, if binary, or 15, if expression operands, there is no truncation decimal). The target scale of the second of the resulting character-string value, operand is FLOAT unless it is an integer since the length of the target is the constant or a variable of precision (p,0). length of the intermediate string. If either of the operands is COMPLEX, the
58 target mode is COMPLEX for both operands maximum number of binary digits allowed is unless the second operand is a REAL integer 31. constant or variable of precision (p,0). In either case, the target mode for the second operand is REAL (that is, its mode Precision and Length of Expression Operand is not converted). Targets
In the examples of exponentiation shown The following rules apply to all below, the variables are those named in the calculations of precision and length: following DECLARE statement: 1. Precision and length specifications DECLARE A FIXED DECIMAL(2), are always integers. If any of the B FIXED DECIMAL(3,2), calculations given below produces a C FLOAT DECIMAI. (4) nonintegral value, the next largest D FLOAT DECIMAL(7), integer is taken as the resulting E FIXED DECIMAL(8), precision. In the case of scale F FIXED DECIMAL(15), factors, which can be negative, it is G COMPLEX FLOAT DECIMAL(6); the absolute (positive) value that is used to take the next largest integer; Note: If only one digit appears in the the result, of course, will be precision attribute specification for a negative if the source scale factor is fixed-point variable, the scale factor is, negative. by default, zero: the precision is (p,0). The following illustrates now D ** O No conversion necessary. Both precision would be computed in a operands are floating-point. conversion from DECIMAL FIXED (13,-4) to BINARY FIXED: A ** 4 No conversion necessary. Second operand is unsigned 1 + 13 * 3.32 = 44.16 resulting number fixed-point integer constant, of digits (p) is and the result will not exceed 45 15 digits. -4 * 3.32 = -13.28 resulting scale factor (q) is D ** 5 No conversion necessary. First -14 operand is floating-point; second is fixed-point with Thus, the resulting precision is precision (p,0). (45,-14); however, due to rule 2 below, it becomes (31,-14). D ** A No conversion necessary. First operand is floating-point; 2. There is an implementation-defined second is fixed-point with maximum for the precision of each precision (p,0). arithmetic representation. If any calculation yields a value greater E ** A First operand is converted to than the implementation-defined limit, floating-point because second then the implementation limit is used operand is not unsigned instead. In System/360 fixed-point integer constant. implementations, these limits are: Second operand is not converted because it has precision (p,0). FIXED DECIMAL -- 15 digits D ** B Second operand is converted to FIXED BINARY -- 31 digits floating-point because it does not have precision (p,0). Even FLOAT DECIMAL -- 16 digits if B had an integer value with a fractional part of zero, it FLOAT BINARY -- 53 digits still would be converted, since its declared precision is Because of the particular values for (3,2). these implementations, these limits will usually come into effect only for G ** B First operand is complex. conversions from fixed-point decimal Second operand is converted to to fixed-point binary. floating-point complex because its precision is not (p,0). The scale factor for both binary and decimal base has the range +127 to Note: All of these examples would be the -128 in System/360 implementations. same if they had been declared binary This limit will rarely concern the rather than decimal, except that the programmer.
Chapter 4: Expressions and Data Conversion 59 Precision for Arithmetic Conversions Note: If a binary data item is converted to character, it is first converted to decimal. The precision of this Figure 4-2 gives the target precision for intermediate conversion result controls the an operand if base or scale conversion length of the final character-string occurs. target. Algorithms for computing the intermediate precision of a decimal item The target precision of one operand of converted from binary are shown in Figure an expression is not affected by the 4-2. precision of the other operand. This can have a significant effect on accuracy, particularly if one of the operands is a constant.
For complex coded arithmetic sources, Lengths of Character-String Targets the target length is one greater than twice the length of the target for the corresponding real source. For complex The length of a character-string target is numeric character data, the target length related to the precision of the decimal is twice the length of the real part of the source, as shown in Figure 4-3. source.
60 Lengths of Bit-string Targets Conversion of the Value of an Expression
The result of a completely evaluated When converting arithmetic operands to bit expression may require further conversion. string, the arithmetic source is converted The circumstances in which this can occur, to a positive binary integer. The and the target attributes for each precision of the binary integer target is situation, are given in Figure 4-5. In the same as the length of the bit-string addition, certain built-in functions cause target as given in Figure 4-4. conversion. Any subscript reference is converted to binary integer.
Note that p-q represents the number of binary or decimal digits to the left of the point. This could be zero or negative, in which case no conversion is performed and, for the F Compiler, the final result is a null string. Conversion Operations
As in the case of determining target attributes, conversion operations may also be considered in two stages: type conversion and arithmetic conversion. For example, when a character-string source is converted to a coded arithmetic target, the string is first converted to an arithmetic form whose attributes are determined by the constant expressed by the string. This intermediate result is then converted (if necessary) to the attributes of the target. These two stages may not be separated in an actual implementation, but for the purpose of description it is convenient to consider them separately.
Chapter 4: Expressions and Data Conversion 61 There are six cases of type conversion: conversion, see Part II, Section F, "Problem Data Conversion." Arithmetic to character-string Character-string to arithmetic The CONVERSION, SIZE, FIXEDOVERFLOW, Arithmetic to bit-string and OVERFLOW Conditions Bit-string to arithmetic When data is converted from one Character-string to bit-string representation to another, the CONVERSION or SIZE conditions may be raised. The Bit-string to character-string OVERFLOW and FIXEDOVERFLOW conditions are raised only when the result of an For specific rules for each of the cases arithmetic operation exceeds the of type conversion and for arithmetic implementation- defined limit. When an
62 operand is converted from one Each invalid character raises the representation to another, if the value of CONVERSION condition once, so a single the result will not fit in the declared conversion operation precision for the new representation, the causes several interrupts if more than one SIZE condition is raised. invalid character is encountered. The CONVERSION condition is normally enabled, The SIZE condition is raised when so when the condition is raised, an significant digits are lost from the interrupt will occur. It can be disabled left-hand side of an arithmetic value. by a NOCONVERSION prefix, in which case an This can occur during conversion within an interrupt will not occur when the condition expression, or upon assigning the result of is raised. an expression. It is not raised in conversion to character string or bit string even if the value is truncated. It is raised on conversion to E or F format in Note that the OVERFLOW and FIXEDOVERFLOW edit-directed transmission if the field conditions are raised when an width specified will not hold the value of implementation maximum is exceeded, while the list item. The SIZE condition is the SIZE condition is raised when a normally disabled, so an interrupt will declared precision is exceeded. For occur only if the condition is raised example, if the addition of two binary within the scope of a SIZE prefix. halfword values resulted in an overflow into a sixteenth digit position, and the The CONVERSION condition is raised when result were assigned to a binary halfword the source field contains a character that variable, SIZE would be raised (if is invalid for the conversion being enabled). Note that, in such a case, SIZE performed. For example, CONVERSION would would be the only indication that an error be raised if a character string being had occurred, whereas if a similar converted to arithmetic contains any situation arose with fullword binary values character other than those allowed in (i.e., an attempted overflow past the arithmetic constants, or if a character thirty-first digit position), FIXEDOVERFLOW string that is being converted to bit would be raised during the actual contains any character other than 0 and 1. computation, before the attempt.
Chapter 4: Expressions and Data Conversion 63 Chapter 5: Statement Classification
This chapter classifies statements The DECLARE Statement according to their functions. Statements in each functional class are listed, the purpose of each statement is described, and The DECLARE statement is the principal examples of their use are shown. means of specifying the attributes of a name. A name used in a program need not A detailed description of each statement always appear in a DECLARE statement; its is not included in this chapter but may be attributes often can be determined by found in Part II, Section J, "Statements." context. If the attributes are not specifically declared and if they cannot be determined by context, then default rules are applied. The combination of default rules and context determination can make it unnecessary, in some cases, to use a DECLARE statement. Classes of Statements DECLARE statements are always needed for fixed-point decimal and floating-point Statements can be grouped into the binary variables, character- and bit-string following seven classes: variables, label variables, arrays and structures, static, controlled, and based Descriptive variables, offset variables, and all data with the PICTURE attribute. An ENTRY declaration must be made in a DECLARE Input/Output statement for the name of any function that returns a value with attributes different Data Movement and Computational from the default attributes that would be assumed for the name -- FIXED BINARY(15) if Program Structure the first letter of the name is I through N; otherwise, DECIMAL FLOAT(6). (The Control default precisions are those defined for System/360 implementations.) An ENTRY Exception Control declaration also must be made if arguments and parameters do not match exactly, as may Preprocessor be the case when constants are passed as arguments. The names of the classes have been chosen for descriptive purposes only; they have no DECLARE statements may also be an fundamental significance in the language. important part of the documentation of a Some statements are included in more than program; consequently, programmers may make one class, since they can have more than liberal use of declarations, even when one function. default attributes apply or when a contextual declaration is possible. Because there are no restrictions on the number of DECLARE statements, different DECLARE statements can be used for different groups of names. This can make DESCRIPTIVE STATEMENTS modification easier and the interpretation of diagnostics clearer. When a PL/I program is executed, it may manipulate many different kinds of data. Each data item, except a constant, is Other Descriptive Statements referred to in the program by a name. The PL/I language requires that the properties (or attributes) of data items referred to The OPEN statement allows certain must be known at the time the program is attributes to be specified for a file name compiled. There are a few exceptions to and may, therefore, also be classified as a this rule; the bounds of the dimensions of descriptive statement. The FORMAT arrays, the length of strings, and some statement may be thought of as describing file attributes may be determined during the layout of data on an external medium, execution of the program. such as on a page or an input card.
64 INPUT/OUTPUT STATEMENTS tend to be smaller, the larger processing overhead can be ignored. The principal statements of the input/output class are those that actually cause a transfer of data between internal RECORD I/O Transfer Statements storage and an external medium. Other input/output statements, which affect such transfers, may be considered input/output The READ statement transmits records control statements. directly into working storage or makes records available for processing. The In the following list, the statements WRITE statement creates new records, that cause a transfer of data are grouped transferring collections of data to the into two subclasses, RECORD L/O and STREAM output device. The LOCATE statement I/O: allocates storage for a variable within an output buffer, setting a pointer to RECORD I/O Transfer Statements indicate the location in the buffer, having previously caused any record already READ located in a buffer for this file to be written out. WRITE The REWRITE statement alters existing REWRITE records in an UPDATE file. The DELETE statement removes records from an UPDATE LOCATE file. DELETE
STREAM I/O Transfer Statements STREAM I/O Transfer Statements GET Only sequential files can be processed with PUT the GET and PUT statements. Record boundaries generally are ignored; data is I/O Control Statements considered to be a stream of individual data items, either coming from (GFT) or OPEN going to (PUT) the external medium. CLOSE The GET and PUT statements may transmit a list of items in one of three modes, UNLOCK data-directed, list-directed, or edit-directed. In data-directed An allied statement, discussed with transmission, the names of the data items, these statements, is the DISPLAY statement. as well as their values, are recorded on the external medium. In list-directed There are two important differences transmission, the data is recorded between STREAM transmission and RECORD externally as a list of constants, transmission. In STREAM transmission, each separated by blanks or commas. In data item is treated individually, whereas edit-directed transmission, the data is RECORD transmission is concerned with recorded externally as a string of collections of data items (records) as a characters to be treated character by whole. In STREAM transmission, each item character according to a format list. may be edited and converted as it is transmitted; in RECORD transmission, the Data-directed transmission is most record on the external medium is an exact useful for reading a relatively small copy of the record as it exists in internal number of values and for producing storage, with no editing or conversion self-annotated debugging output. performed. List-directed input is suitable for reading in larger volumes of data punched in free As a result of these differences, record form. Edit-directed transmission is used transmission is particularly applicable for wherever format must be strictly processing large files that are written in controlled, for example, in producing an internal representation, such as in reports and for reading cards punched in a binary or packed decimal. Stream fixed format. transmission may be used for processing keypunched data and for producing readable Note: The GET and PUT statements can also output, where editing is required. Since be used for internal data movement, by files for which stream transmission is used specifying a string name in the STRING
Chapter 5: Statement Classification 65 option instead of specifying the FILE DATA MOVEMENT AND COMPUTATIONAL STATEMENTS option. Although the facility may be used with READ and WRITE statements for moving data to and from a buffer, it is not Internal data movement involves the actually a part of the input/output assignment of the value of an expression to operation. GET and PUT statements with the a specified variable. The expression may STRING option are discussed in the section be a constant or a variable, or it may be "Data Movement and Computational an expression that specifies computations Statements," in this chapter. to be made. The most commonly used statement for internal data movement, as well as for specifying computations, is the assignment Input/Output Control Statements statement. The GET and PUT statements with the STRING option also can be used for internal data movement. The PUT statement The OPEN statement associates a file name can, in addition, specify computations to with a data set and prepares the data set be made. for processing. It may also specify additional attributes for the file. An OPEN statement need not always be written. Execution of any input or output The Assignment Statement transmission statement that specifies the name of an unopened file will result in an automatic opening of the file before the The assignment statement, which has no data transmission takes place. keyword, is identified by the assignment symbol (=). It generally takes one of two The OPEN statement may be used to forms: declare attributes for a file; for a PRINT file, the length of each printed line and A = the number of lines per page can be specified only in an OPEN statement. The A = B + C; OPEN statement can also be used to specify a name (in the TITLE option) other than the The first form can be used purely for file name, as a link between the data set internal data movement. The value of the and the file. variable (or constant) to the right of the assignment symbol is to be assigned to the The CLOSE statement dissociates a data variable to the left. The second form set from a file. All files are closed at includes an operational expression whose termination of a program, so a CLOSE value is to be assigned to the variable to statement is not always required. the left of the assignment symbol. The second form specifies computations to be The UNLOCK statement releases a record made, as well as data movement. that has been temporarily locked by the task executing the UNLOCK statement, so Since the attributes of the variable on that other concurrent tasks may resume the left may differ from the attributes of access to the record. The UNLOCK statement the result of the expression (or of the is not always required; the unlocking variable or constant), the assignment operation is automatic when the task that statement can also be used for conversion locked the record deletes or rewrites it, and editing. or closes the file, or when the task is terminated. The variable on the left may be the name of an array or a structure; the expression on the right may yield an array or structure value. Thus the assignment The DISPLAY Statement statement can be used to move aggregates of data, as well as single items.
The DISPLAY statement is used to write messages on the console, usually to the Multiple Assignment operator. It may also be used, with the REPLY option, to allow the operator to The value of the expression in an communicate with the program by typing in a assignment statement can be assigned to code or a message. The REPLY option may be more than one variable in, a statement of used merely as a means of suspending the following form: program execution until the operator acknowledges the message. A,X = B + C;
66 Such a statement is executed in exactly the This statement specifies that the character same way as a single assignment, except string assigned to BUFFER is to consist of that the value of B + C is assi gned to both the character representations of the value A and X. In general, it has the same of A multiplied by 3 and the value of the effect as if the following two statements sum of B and C. had been written: Operational expressions in the data list A = B + C; of a PUT statement are not limited to PUT statements with the STRING option. X = B + C; Operational expressions can appear in PUT statements that specify output to a file. Note: If multiple assignment is used for a structure assignment BY NAME, the elementary names affected will be only those that are common to all of the PROGRAM STRUCTURE STATEMENTS structures listed to the left of the assignment symbol. The program structure statements are those statements used to delimit sections of a program into blocks and groups, and to The STRING Option control the allocation of storage within a program. These statements are the PROCEDURE statement, the END statement, the If the STRING option appears in a GET or ENTRY statement, the BEGIN statement, the PUT statement in place of a FILE option, DO statement, the ALLOCATE statement, and execution of the statement will result only the FREE statement. The concept of blocks in internal data movement; neither input and groups is fundamental to a proper nor output is involved. understanding of PL/I and is dealt with in detail in Chapters 6, 7, and 10. Assume that NAME is a string of 30 characters and that FIRST, MIDDLE, and LAST Proper division of a program into blocks are string variables. Consider the simplifies the writing and testing of the following example: program, particularly when a number of programmers are co-operating in writing a GET STRING (NAME) EDIT single program. It may also result in more (FIRST, MIDDLE, LAST) efficient use of storage, since dynamic (A(12),A(1),A(17)); storage of the automatic class is allocated on entry to the block in which it is This statement specifies that the first 12 declared. characters of NAME are to be assigned to FIRST, the next character to MIDDLE, and the remaining 17 characters to LAST. The PROCEDURE Statement The PUT statement with the string option specifies the reverse operation, that is, that the values of the specified variables The principal function of a procedure are to be concatenated into a string and block, which is delimited by a PROCEDURE assigned as the value of the string named statement and an associated END statement, in the STRING option. For example: is to define a sequence of operations to be performed upon specified data. This PUT STRING (NAME) EDIT sequence of operations is given a name (the (FIRST,MIDDLE, LAST) label of the PROCEDURE statement) and can (A(12),A(1),A(17)); be invoked from any point at which the name is known. This statement specifies that the values of FIRST, MIDDLE, and LAST are to be Every program must have at least one concatenated, in that order, and assigned PROCEDURE statement and one END statement. to the string variable NAME. A program may consist of a number of separately written procedures linked Computations to be performed can be together. A procedure may also contain specified in a PUT statement by including other procedures nested within it. These operational expressions in the data list. internal procedures may contain Assume, for the following example, that the declarations that are treated (unless variables A, B, and C represent arithmetic otherwise specified) as local definitions data and BUFFER represents a character of names. Such definitions are not known string: outside their own block, and the names cannot be referred to in the containing PUT STRING (BUFFER) LIST (A*3,B+C); procedure. Storage associated with these
Chapter 5: Statement Classification 67 names is generally allocated upon entry to statement. Begin blocks, however, are the block in which such a name is defined, executed in the normal flow of a program, and it is freed upon exit from the block. either sequentially or as a result of a GO TO or an IF statement transfer. One of the The sequence of statements defined by a most common uses of a begin block is as the procedure can be executed at any point at on-unit of an ON statement, in which case which the procedure name is known. This it is not executed through normal flow of execution can be either synchronous (that control, but only upon occurrence of the is, the execution of the invoking procedure specified condition. It is also useful for is suspended until control is returned to delimiting a section of a program in which it) or asynchronous (that is, execution of some automatic storage is to be allocated. the invoking procedure proceeds concurrently with that of the invoked Each begin block must be nested within a procedure); for details of asynchronous procedure or another begin block. operation, see Chapter 15, "Multitasking." A procedure is invoked either by a CALL statement or by the appearance of its name in an expression, in which case the The END Statement procedure is called a function procedure. A function reference causes a value to be calculated and returned to the function The END statement is used to signify the reference for use in the evaluation of the end of a block or group. Every block or expression. A function procedure cannot be group must have an END statement. However, executed asynchronously with the invoking the END statement may be explicit or procedure. implicit; a single END statement can be applied to a number of nested blocks and Communication between two procedures is groups by the inclusion of the label of the by means of arguments passed from an containing block or group after the keyword invoking procedure to the invoked END. The other END statements are then procedure, by a value returned from an implied by the one containing the label, invoked procedure, and by names known and need not be given explicitly. If no within both procedures. A procedure may label follows END, the statement applies to therefore operate upon different data when only one group or block. (Multiple closure it is invoked from different points. A is discussed in more detail in Chapter 6, value is returned from a function procedure "Blocks, Flow of Control, and Storage to a function reference by means of the Allocation.". RETURN statement. Execution of an END statement for a block terminates the block. However, it is not the only means of terminating a block, The ENTRY Statement even though each block must have an END statement. For example, a procedure can be terminated by execution of a RETURN The ENTRY statement is used to provide an statement (see "Control Statements," alternate entry point to a procedure and, below). possibly, an alternate parameter list to which arguments can be passed, The effect of execution of an END corresponding to that entry point. It may statement for a group depends on whether or also specify the attributes of the value not the group is iterative. If the group | returned by a function procedure. is iterative, execution of the END statement causes control to return to the Note: It is important to distinguish beginning of the group until all iterations between the ENTRY statement, which are complete, unless control is passed out specifies an entry to the procedure in of the group before then. (See "Control which it occurs, and the ENTRY attribute Statements," below.) If the group is specification, which describes the noniterative, the END statement merely attributes of parameters of procedures that delimits the group (to enable the group to are invoked from the procedure in which the be treated as a single statement), and ENTRY attribute specification appears. control passes to the next statement.
The BEGIN Statement The ALLOCATE and FREE Statements
Local definitions of names can also be made As with many other conventions in PL/I, the within begin blocks, which are delimited by convention concerning storage allocation a BEGIN statement and an associated END and the scope of definitions of names can
68 be overridden by the programmer. The % null storage class attribute AUTOMATIC is assumed for most variables. However a variable can be declared STATIC, in which % PROCEDURE case it is allocated throughout the entire program; or it can be declared CONTROLLED, or BASED, in which case its allocation can RETURN be explicitly specified by the programmer.
The ALLOCATE statement is used to assign These statements are discussed in Chapter storage to controlled and based data, 16, "Compile-Time Facilities," and in Part independent of block boundaries. The II, Section J, "Statements." bounds of controlled arrays and the length of controlled strings, as well as their initial values, may also be specified at the time the ALLOCATE statement is executed. The FREE statement is used to free controlled and based storage after it has been allocated. CONTROL STATEMENTS
Statements in a PL/I program, in general, are executed sequentially unless the flow PREPROCESSOR STATEMENTS of control is modified by the occurrence of an interrupt or the execution of one of the following control statements: PL/I allows a degree of control over the contents of the source program during the GO TO compilation. The programmer can specify, for example, that any identifier appearing IF in the source program will be changed; he can select parts of the program to be DO compiled without the rest; he can include text from an external source. These CALL operations are performed by the preprocessor stage of the compiler, and are RETURN specified by preprocessor statements that appear among the other statements within END the source program itself. STOP In general, preprocessor statements are identified by a leading percent symbol EXIT before the keyword; several of them have the same keyword as standard PL/I statements, and these have a similar effect at compile-time to that of their counterpart at execution time. The GO TO Statement The complete list of preprocessor statements is as follows: The GO TO statement is most frequently used as an unconditional branch. If the % ACTIVATE destination of the GO TO is specified by a label variable, it may then be used as a % assignment switch by assigning label constants, as values, to the label variable. % DEACTIVATE If the label variable is subscripted, % DECLARE the switch may be controlled by varying the subscript. Since multidimensional label % DO arrays are allowed, and since logical values may be used as subscripts, quite % END subtle switching can be effected. It is usually true, however, that simple control % GO TO statements are the most efficient. % IF The keyword of the GO TO statement may be written either as two words separated by % INCLUDE a blank or as a single word, GOTO.
Chapter 5: Statement Classification 69 The IF Statement Note: If the THEN clause does not cause a transfer of control and if it is not followed by an ELSE clause, the next The IF statement provides the most common statement will be executed whether or not conditional branch and is usually used with the THEN clause is executed. a simple comparison expression following the word IF. For example: The expression following the IF keyword can be only an element expression; it IF A = B cannot be an array or structure expression. (The STRING built-in function can be used to concatenate the elements of a bit- or THEN action-if-true character-string array or structure into an element expression.) It can, however, be a ELSE action-if-false logical expression with more than one operator. For example: If the comparison is true, the THEN clause (the "action to be taken") is executed. After execution of the THEN IF A = B & C = D clause, control branches around the ELSE THEN GO TO R; clause (the "alternate action"), and execution continues with the next statement. Note that the THEN clause can The same kind of test could be made with contain a GO TO statement or some other nested IF statements. The following three control statement that would result in a examples are equivalent: different transfer of control. If the comparison is not true, control branches around the THEN clause, and the ELSE clause is executed. Control then continues normally. The IF statement might be as follows: IF A = B THEN C = D; ELSE C = E; If A is equal to B, the value of D is assigned to O, and control branches around the ELSE clause. If A is not equal to B, control branches around the THEN clause, and the value of E is assigned to C. The DO Statement Either the THEN clause or the ELSE clause can contain some other control The most common use of the DO statement is statement that causes a branch, either to specify that a group of statements is to conditional or unconditional. If the THEN be executed a stated number of times while clause contains a GO TO statement, for a control variable is incremented each time example, there is no need to specify an through the loop. Such a group might take ELSE clause. Consider the following the form: example: DO I = 1 TO 10; IF A = B THEN GO TO LABEL 1; END; next-statement The statements to be executed iteratively If A is equal to B, the GO TO statement of must be delimited by the DO statement and the THEN clause causes an unconditional an associated END statement. In this case, branch to LABEL 1. If A is not equal to B, the group of statements will be executed control branches around the THEN clause to ten times, while the value of the control the next statement, whether or not it is an variable I ranges from 1 through 10. The ELSE clause associated with the IF effect of the DO and END statements would statement. be the same as the following:
70
after the preceding specification has been satisfied. The control variable of a DO statement can be used as a subscript in statements within the DO-group, so that each iteration deals with successive elements of a table or array. For example: Note that the increment is made before the DO I = 1 TO 10; control variable is tested and that, in A(I) = I; general, control goes to the statement END; following the group only when the value of the control variable exceeds the limit set In this example, the first ten elements of in the DO statement. If a reference is A are set to 1,2,...,10, respectively. made to a control variable after the last iteration is completed, the value of the The increment in the iteration variable will be one increment beyond the specification is assumed to be one unless specified limit. some other value is stated, as follows:
The DO statement can also be used with DO I = 2 TO 10 BY 2; the WHILE option and no control variable, as follows: This specifies that the loop is to be executed five times, with the value of I DO WHILE (A = B); equal to 2, 4, 6, 8, and 10. This statement, heading a group, causes the g roup to be executed repeatedly so long as the value of A remains equal to the value Noniterative DO Statements of B. The WHILE option can be combined with a The DO statement need not specify repeated control variable of the form: execution of the statements of a DO-group. A simple DO statement, in conjunction with DO I = 1 TO 10 WHILE (A = P); a DO-group, can be used as follows: This statement specifies two tests. Each time that 1 is incremented, a test is made to see that I has not exceeded 10. An additional test then is made to see that A is equal to B. Only if both conditions are satisfied will the statements of the group be executed. The use of the simple DO statement in this manner merely indicates that the DO-group More than one successive iteration is to be treated logically as a single specification can be included in a single statement. It can be used to specify a DO statement. Consider each of the number of statements to be executed in the following DO statements: THEN clause or the ELSE clause of an IF statement, thus maintaining sequential DO I = 1 TO 10, 13 TO 15; control without the use of a begin block. (Only a single statement, a DO-group, or a DO I = 1 TO 10, 11 WHILE (A = B); begin block can be specified in the THEN clause or in the ELSE clause.) The first statement specifies that the DO group is to be executed a total of thirteen times, ten times with the value of I equal to 1 through 10, and three times with the The CALL, RETURN, and END Statements value of I equal to 13 through 15. The second DO statement specifies that the group is to be executed at least ten times, A subroutine may be invoked by a CALL and then (provided that A is equal to B) statement that names an entry point of the once more; if "BY 0" were inserted after subroutine. When the multitasking "11", execution would continue with I set facilities are not in use, control is to 11 as long as A remained equal to B. returned to the activating, or invoking, Note that in both statements a comma is procedure when a RETURN statement is used to separate the two specifications. executed in the subroutine or when This indicates that a succeeding execution of the END statement terminates specification is to be considered only the subroutine. If the CALL statement
Chapter 5: Statement Classification 71 contains one of the multitasking options, The ON Statement TASK, EVENT, or PRIORITY, the subroutine is executed by a subtask with its own separate flow of control; in this case, the RETURN The ON statement is used to specify action or END statement merely terminates the to be taken when any subsequent occurrence separate flow of control established for of a specified condition causes a program the subtask. (See Chapter 15, interrupt. ON statements may specify "Multitasking.") particular action for any of a number of different conditions. For all of these The RETURN statement with a conditions, a standard system action exists parenthesized expression is used in a as a part of PL/I, and if no ON statement function procedure to return a value to a is in force at the time an interrupt function reference. This form is used to occurs, the standard system action will return a value from a procedure that has take place. For most conditions, the been invoked by a function reference. standard system action is to print a message and terminate execution. Normal termination of a program occurs as the result of execution of the final END statement of the main procedure or of a The ON statement takes the form: RETURN statement in the main procedure, either of which returns control to the ON condition [SNAP]{SYSTEM;|on-unit} operating system. The "condition name" is one of the keywords listed in Part II, Section H, "ON-Conditions." The "on-unit" is a single The STOP and EXIT Statements statement or a begin block that specifies action to be taken when that condition arises and an interrupt occurs. For The STOP and EXIT statements are both used example: |to cause abnormal termination'. The STOP statement terminates execution of the ON ENDFILE(DETAIL) GO TO NEXT MASTER; entire program, including all concurrent tasks. The EXIT statement terminates only This statement specifies that when an the task that executes it, together with interrupt occurs as the result of trying to any attached tasks. (See Chapter 15, read beyond the end of the file named "Multitasking.") DETAIL, control is to be transferred to the statement labeled NEXT MASTER. When execution of an on-unit is EXCEPTION CONTROL STATEMENTS successfully completed, control will normally return to the point of the interrupt or to a point immediately The control statements, discussed in the following it, depending upon the condition preceding section, alter the flow of that caused the interrupt. control whenever they are executed. Another way in which the sequence of An important use of the ON statement is execution can be altered is by the for debugging. The CHECK condition causes occurrence of a program interrupt caused by debugging information to be printed an exceptional condition that arises. whenever the value of one of a list of specified variables is changed or whenever In general, an exceptional condition is a specified statement is executed. the occurrence of an unexpected action, such as an overflow error, or of an The effect of an ON statement, the expected action, such as an end of file, establishment of the on-unit, can be that occurs at an unpredictable time. A changed within a block (1) by execution of detailed discussion of the handling of another ON statement naming the same these conditions appears in Chapter 13, condition with either another on-unit or "Exceptional Condition Handling and Program the word SYSTEM, which re-establishes Checkout." standard system action, or (2) by the execution of a REVERT statement naming that The three exception control statements condition. On-units in effect at the time are the ON statement, the REVERT statement, another block is activated remain in effect and the SIGNAL statement. in the activated block, and in other blocks activated by it, unless another ON statement for the same condition is ¹Note that abnormal termination does not executed. When control returns to an have the same effect as the ABEND macro of activating block, on-units are the Operating System. re-established as they existed.
72 The REVERT Statement The SIGNAL Statement
The REVERT statement is used to cancel the The SIGNAL statement simulates the effect of all ON statements for the same occurrence of an interrupt for a named condition that have been executed in the condition. It can be used to test the block in which the REVERT statement coding of the on-unit established by appears. execution of an ON statement. For example:
SIGNAL OVERFLOW; This statement would simulate the The REVERT statement, which must specify occurrence of an overflow interrupt and the condition name, re-establishes the would cause execution of the on-unit on-unit that was in effect in the established for the OVERFLOW condition. If activating block at the time the current an on-unit has not been established, block was invoked. standard system action is taken.
Ohapter 5: Statement Classification 73 A
Chapter 6: Blocks, Flow of Control, and Storage Allocation
This section discusses how statements can be organized into blocks to form a PL/I program, how control flows within a program from one block of statements to another, and how storage may be allocated for data within a block of statements. The discussion in this chapter does not completely cover multitasking, which is discussed in detail in Chapter 15. However, the discussion generally applies In general, control is transferred to a to all blocks, whether or not they are procedure through a reference to the name executed concurrently. (or one of the names) of the procedure. Thus, the procedure in the above example would be given control by a reference to either of its names, A or READIN. A PL/I program consists of one r more such procedures, each of which may contain Blocks other procedures and/or begin blocks.
A block is a delimited sequence of statements that constitutes a section of a program. It localizes names declared BEGIN BLOCKS within the block and limits the allocation of variables. There are two kinds of blocks: procedure blocks and begin blocks. begin block is a set of statements headed by a BEGIN statement and ended by an END statement, as follows:
PROCEDURE BLOCKS
A procedure block, simply called a Unlike a procedure block, a label is procedure, is a sequence of statements optional for a begin block. If one or more headed by a PROCEDURE statement and ended labels are prefixed to a BEGIN statement, by an END statement, as follows: they serve only to identify the starting point of the block. (Control may pass to a begin block without reference to the name of that block through normal sequential execution, although control can be transferred to a labeled BEGIN statement by execution of a GO TO statement.) The label following END is optional. However, a label can appear after END, matching a All procedures must be named because the label of the corresponding BEGIN statement. procedure name is the primary point of (There are exceptions; see "Use of the END entry through which control can be Statement with Nested Blocks and DO-Groups" transferred to a procedure. Hence, a in this chapter.) An example of a begin PROCEDURE statement must have at least one block follows: label. A label need not appear after the keyword END in the END statement, but if one does appear, it must match the label (or one of the labels) of the PROCEDURE statement to which the END statement corresponds. (There are exceptions; see "Use of the END Statement with Nested Blocks and DO-Groups" in this chapter.) An example of a procedure follows:
74 Unlike procedures, begin blocks D: BEGIN; generally are not given control through statement- special references to them. The normal d1 statement-d2 sequence of control governing ordinary statement-d3 statement execution also governs the E: PROCEDURE; execution of begin blocks. Control passes statement-el into a begin block sequentially, following statement-e2 execution of the preceding statement. END E; statement-d4 Begin blocks are not essential to the END D; construction of a PL/I program. However, END C; there are times when it is advantageous to statement-a6 use begin blocks to delimit certain areas statement-a7 of a program. These advantages are END A; discussed in this chapter and in Chapter 7, "Recognition of Names." In the above example, procedure block A is an external procedure because it is not contained in any other block. Block B is a begin block that is contained in A; it contains no other blocks. Block C is an INTERNAL AND EXTERNAL BLOCKS internal procedure; it contains begin block D, which, in turn, contains internal procedure E. This example contains three Any block can contain one or more blocks. levels of nesting relative to A; B and C That is, a procedure, as well as a begin are at the first level, D is at the second block, can contain other procedures and level (but the first level relative to C) begin blocks. However, there can be no and E is at the third level (the second overlapping of blocks; a block that level relative to C, and the first level contains another block must totally relative to D). encompass that block. There must not be more than 50 levels of A procedure block that is contained nesting at any point in the compilation. within another block is called an internal The degree of nesting at any point is the procedure. A procedure block that is not number of PROCEDURE, BEGIN, or DO contained within another block is called an statements without a corresponding END external procedure. There must always be statement, plus the number of currently at least one external procedure in a PL/I active IF compound statements, plus the program. (Note: With System/360 number of currently unmatched left implementations, each external procedure is parentheses, plus the number of dimensions compiled separately. Entry names of in each active array expression, plus the external procedures cannot exceed seven maximum number of dimensions in each active characters.) array expression, plus the maximum number of dimensions in each active structure Begin blocks are always internal; they expression. must always be contained within another block. Internal procedure and begin blocks can Use of the END Statement with Nested Blocks also be referred to as nested blocks. and DO-Groups (Multiple Closure) Nested blocks, in turn, may have blocks nested within them, and so on. The outermost block always must be a procedure. The use of the END statement with a Consider the following example: procedure, begin block, or DO-group is governed by the following rules: A: PROCEDURE; statement-al 1. If a label is not used after END, the statement-a2 END statement closes (i.e., ends) that statement-a3 unclosed block headed by the BEGIN or B: BEGIN; PROCEDURE statement, or that unclosed statement-b1 DO-group headed by the DO statement, statement-b2 that physically precedes, and appears statement-b3 closest to, the END statement. END B; statement-a4 2. If the optional label is used after statement-a5 END, the END statement closes that C: PROCEDURE; unclosed block or DO-group headed by statement-c1 the BEGIN, PROCEDURE, or DO statement statement-c2 that has a matching label, and that
Chapter 6: Blocks, Flow of Control, and Storage Allocation 75 physically precedes, and appears Note the following example: closest to, the END statement. Any unclosed blocks or DO-groups nested CBLK: PROCEDURE; within such a block or DO-group are statement-c1 automatically closed by this END statement-c2 statement; this is known as multiple DGP: DO I = 1 TO 10; closure. statement-d1 GO TO LBL; From the second rule, it is evident that statement-d2 nested blocks sometimes make it possible LBL: END CBLK; for a single END statement to close more than one block. For example, assume that In this example, the END CBLK statement the following external procedure has been closes the block CBLK and the iterative defined: DO-group DGP. The effect is as if an unlabeled END statement for DGP appeared FRST: PROCEDURE; immediately after statement-d2, so that the statement-fl transfer to LBL would prevent all but the statement-f2 first iteration of DGP from taking place, ABLK: BEGIN; and statement-d2 would not be executed. statement-al statement-a2 SCND: PROCEDURE; statement- s1 statement-s2 Activation and Termination of Blocks BBLF: BEGIN; statement-b1 statement-b2 ACTIVATION END; END; statement-a3 Although the begin block and the procedure END ABLE; have a physical resemblance and play the END FRST; same role in the allocation and freeing of storage, as well as in delimiting the scope In this example, begin block BBLK and of names, they differ in the way they are internal procedure SCND effectively end in activated and executed. A begin block, the same place; that is, there are no like a single statement, is activated and statements between the END statements for executed in the course of normal sequential each. This is also true for begin block program flow (except when specified as an ABLE and external procedure FRST. In such on-unit) and, in general, can appear cases, it is not necessary to use an END wherever a single statement can appear. statement for each block, as shown; rather, For a procedure, however, normal sequential one END statement can be used to end BBLK program flow passes around the procedure, and SCND, and another END can be used to from the statement before the PROCEDURE end ABLE and FRST. In the first case, the statement to the statement after the END statement would be END SCND, because one statement of that procedure. The only way END statement with no following label would in which a procedure can be activated is by close only the begin block BBLK (see the a procedure reference. first rule above). In the second case, only the statement END FRST is required; A procedure reference is the appearance the statement END ABLK is superfluous. of an entry name (defined below) in one of Thus, the example could be specified as the following contexts: follows: 1. After the keyword CALL in a CALL FRST: PROCEDURE; statement statement-fl statement-f2 2. After the keyword CALL in the CALL ABLE: BEGIN; option of the INITIAL attribute (see statement-al the discussion of the INITIAL statement-a2 attribute in Part II, Section I, SCND: PROCEDURE; "Attributes," for details) statement-s1 statement-s2 3. As a function reference (see Chapter BBLK: BEGIN; 12, "Subroutines and Functions," for statement-bi details) statement-b2 END SCND; This chapter uses examples of the first statement-a3 of these; that is, with the procedure END FRST; reference of the form:
76 CALL entry-name; procedure is invoked at a secondary entry point, execution begins with the first The material, however, is relevant to the executable statement following the ENTRY other two forms as well. statement that defines that secondary entry point. Therefore, if all of the numbered An entry name is defined as either of statements in the last example are the following: executable, the statement CALL A would invoke procedure A at its primary entry 1. The label, or one of the labels, of a point, and execution would begin with PROCEDURE statement statement-1; the statement CALL ERRT would invoke procedure A at the secondary entry 2. The label, or one of the labels, of an point ERRT, and execution would begin with ENTRY statement appearing within a statement-3; either of the statements CALL procedure NEXT or CALL RETR would invoke procedure A at its other secondary entry point, and The first of these is called the primary execution would begin with statement-6. entry point to a procedure; the second is Note that any ENTRY statements encountered known as a secondary entry point to a during sequential flow are never executed; procedure. The following is an example of control flows around the ENTRY statement as a procedure containing secondary entry though the statement were a comment. points: A: PROCEDURE; statement-1 Any procedure, whether external or statement-2 internal, can always invoke an external ERRT: ENTRY; procedure, but it cannot always invoke an statement-3 internal procedure that is contained in statement-4 some other procedure. Those internal statement-5 procedures that are at the first level of NEXT: RETR: ENTRY; nesting relative to a containing procedure statement-6 can always be invoked by that containing statement-7 procedure, or by each other. For example: statement-8 END A; PRMAIN: PROCEDURE; statement-1 In this example, A is the primary entry statement-2 point to the procedure, and ERRT, NEXT, and statement-3 RETR specify secondary entry points. A: PROCEDURE; Actually, since they are both labels of the statement-al same ENTRY statement, NEXT and RETR specify statement-a2 the same secondary entry point. B: PROCEDURE; statement-b1 statement-b2 END A; When a procedure reference is executed, statement-4 the procedure containing the specified statement-5 entry point is activated and is said to be C: PROCEDURE; invoked; control is transferred to the statement-c1 specified entry point. 1 The point at which statement-c2 the procedure reference appears is called END C; the point of invocation and the block in statement-6 which the reference is made is called the statement-7 invoking block. An invoking block remains END PRMAIN; active even though control is transferred from it to the block it invokes. In this example, PRMAIN can invoke procedures A and C, but not B; procedure A can invoke procedures B and C; procedure B can invoke procedure C; and procedure C can Whenever a procedure is invoked at its invoke procedure A but not B. primary entry point, execution begins with the first executable statement in the The foregoing discussion about the invoked procedure. However, when a activation of blocks presupposes that a program has already been activated. A PL/I program becomes active when a calling I This statement does not apply when the program invokes the initial procedure. CALL statement specifies one of the This calling program usually is the multitasking options. See Chapter 15, operating system, although it could be "Multitasking." another program. For System/360
Chapter 6: Blocks, Flow of Control, and Storage Allocation 77 implementations, the initial procedure, Begin Block Termination called the main procedure, must be an external procedure whose PROCEDURE statement has the OPTIONS(MAIN) A begin block is terminated when any of the specification, as shown in the following following occurs: example: 1. Control reaches the END statement for the block. When this occurs, control CONTRL: PROCEDURE OPTIONS(MAIN); moves to the statement physically CALL A; following the END, except when the CALL B; block is an on-unit. CALL C; END CONTRL; 2. The execution of a GO TO statement within the begin block (or any block activated from within that begin In this example, CONTRL is the initial block) transfers control to a point procedure and it invokes other procedures not contained within the block. in the program. 3. A STOP or EXIT statement is executed (thereby terminating execution). The following is a summary of what has been stated, or at least implied, about the 4. Control reaches a RETURN statement activation of blocks: that transfers control out of the begin block and out of its containing procedure as well. • A program becomes active when the initial procedure is activated by the A GO TO statement of the type described operating system. in item 2 can also cause the termination of other blocks as follows: • Except for the initial procedure, external and internal procedures If the transfer point is contained in a contained in a program are activated block that did not directly activate the only when they are invoked by a block being terminated, all intervening procedure reference. blocks in the activation sequence are terminated. • Begin blocks are activated through normal sequential flow or as on-units. For example, if begin block B is contained in begin block A, then a GO TO • The initial procedure remains active statement in B that transfers control to a for the duration of the program. point contained in neither A nor B effectively terminates both A and B. This • All activated blocks remain active case is illustrated below: until they are terminated (see below). FRST: PROCEDURE OPTIONS(MAIN); statement-1 statement-2 statement-3 A: BEGIN; TERMINATION statement-al statement-a2 B: BEGIN; In general, a procedure block is terminated statement-b1 when, by some means other than a procedure statement-b2 reference, control passes back to the GO TO LAB; invoking block or to some other active statement-b3 block. Similarly, a begin block is END B; terminated when, by some means other than a statement-a3 procedure reference, control passes to END A; another active block. There are a number statement-4 of ways by which such transfers of control statement-5 can be accomplished, and their LAB: statement-6 interpretations differ according to the statement-7 type of block being terminated. END FRST; Note that when a block is terminated, After FRST is invoked, the first three any task attached by that block is statements are executed and then begin terminated (see Chapter 15, block A is activated. The first two "Multitasking"). statements in A are executed and then begin
78 block B is activated (A remaining active). A: PROCEDURE OPTIONS(MAIN); When the GO TO statement in B is executed, statement-1 control passes to statement-6 in FRST. statement-2 Since statement-6 is contained in neither A B: BEGIN; nor B, both A and B are terminated. Thus, statement-b1 the transfer of control out of begin block statement-b2 B results in the termination of intervening CALL C; block A as well as termination of block B. statement-b3 END B; statement-3 statement-4 C: PROCEDURE; statement-c1 statement-c2 Procedure Termination statement-c3 D: BEGIN; statement-d1 A procedure is terminated when one of the statement-d2 following occurs: GO TO LAB; statement-d3 1. Control reaches a RETURN statement END D; within the procedure. The execution statement-c4 of a RETURN statement causes control END C; to be returned to the point of statement-5 invocation in the invoking procedure. LAB: statement-6 If the point of invocation is a CALL statement-7 statement, execution in the invoking END A; procedure resumes with the statement following the CALL. If the point of In the above example, A activates F, invocation is one of the other forms which activates C, which activates F. In of procedure references (that is, a D, the statement GO TO LAB transfers OALL option or a function reference), control to statement-6 in A. Since this execution of the statement containing statement is not contained in D, C, or B, the reference will be resumed. all three blocks are terminated; A remains active. Thus, the transfer of control out of D results in the termination of 2. Control reaches the END statement of intervening blocks B and C as well as the the procedure. Effectively, this is termination of block D. equivalent to the execution of a RETURN statement. Program Termination 3. The execution of a GO TO statement within the procedure (or any block activated from within that procedure) A program is terminated when any one of the transfers control to a point not following occurs: contained within the procedure. 1. Control for the program reaches an EXIT statement. This is abnormal 4. A STOP or EXIT statement is executed termination. (thereby terminating execution). 2. Control for the program reaches a STOP statement. 1 This also is abnormal Items 1, 2, and 3 are normal procedure termination. terminations; item 4 is abnormal procedure termination. 3. Control reaches a RETURN statement or the final END statement in the main As with a begin block, the type of procedure. This is normal termination described in item 3 can termination. sometimes result in the termination of several procedures and/or begin blocks. 4. An on-unit for the ERROR condition is Specifically, if the transfer point executed with normal return (that is, specified by the GO TO statement is contained in a block that did not directly activate the block being terminated, all When multitasking is in operation, the intervening blocks in the activation program (i.e., the major task) is sequence are terminated. Consider the terminated when any task reaches a STOP following example: statement. See Chapter 15, "Multitasking."
Chapter 6: Blocks, Flow of Control, and Storage Allocation 79 a GO TO statement does not transfer Static Storage control out of the on-unit) or the FINISH condition is raised as a result of the standard system action for the All variables that have the STATIC ERROR condition. attribute are allocated storage before the execution of the program begins and they remain allocated for the duration of the Note: The termination of a program, program. For example: whether normal or abnormal , raises the FINISH condition. The standard system action for this condition is to return control to the operating system control program. For normal termination, the control program will then pass control to the calling program, if any. For abnormal termination, it will terminate the job. (See Part II, Section H, "ON-Conditions.")
STORAGE ALLOCATION Before the execution of a program begins, all static variables are allocated and any initial values specified for them Storage allocation is the process of are assigned. Therefore, in the above associating an area of storage with a example, the first time that procedure OUTP variable sc that the data item(s) to be is invoked, X has the value 1 and execution represented by the variable may be recorded of the PUT statement causes the item X=1 to internally. When storage has been be written. Before OUTP is terminated, the associated with a variable, the variable is assignment statement X=X+1 increases the said to be allocated. Allocation for a value of X by 1. If OUTP is invoked a given variable may take place statically, second time, and if the value of X is not that is, before the execution of the changed elsewhere in the program, X has the program, or dynamically, during execution. value 2 (X is not re-initialized to 1 A variable that is allocated statically because static variables are initialized remains allocated for the duration of the only once before execution). When the PUT program. A variable that is allocated statement is executed for the second time, dynamically will relinquish its storage the item X=2 is written into the stream, either upon the termination of the block etc. Thus, the static variable X might be containing that variable or at the request used to record the number of times that of the programmer, depending upon its OUTP is invoked. storage class. The manner in which storage is allocated for a variable is determined by the storage Automatic Storage class of that variable. There are four storage classes: static, automatic, controlled, and based. Each storage class A variable that has the AUTOMATIC attribute is specified by its corresponding storage is allocated storage upon activation of the class attribute: STATIC, AUTOMATIC, block in which that variable is declared. CONTROLLED, and BASED, respectively, The The variable remains allocated as long as last three define dynamic storage the block remains active; it is freed when allocation. the block is terminated. Once a variable is freed, its value is lost. Storage class attributes may be declared explicitly for element, array, and major structure variables. If a variable is an array or a major structure variable, the Controlled Storage storage class declared for that variable applies to all of the elements in the array or structure. A variable that has the CONTROLLED attribute is allocated storage only upon All variables that have not been the execution of an ALLOCATE statement explicitly declared with a storage class specifying that variable. Storage remains attribute are assumed to have the AUTOMATIC allocated for that variable until the attribute, with one exception: any variable execution of a FREE statement in which the that has the EXTERNAL attribute is assumed variable is specified. This allocation to have the STATIC attribute. remains even after termination of the block
80 in which it is allocated. Thus, the Based storage is the most powerful of allocation and freeing of storage for the PL/I storage classes, but it must be variables declared with the CONTROLLED used carefully; many of the safeguards attribute is directly under the control of against error that are provided for other the programmer. storage classes cannot be provided for based. A controlled variable may be stacked; that is, storage may be allocated for a For full details of based storage, see controlled variable even when a previous Chapter 14, "Based Variables and List allocation for that variable exists. In Processing." terms of ALLOCATE and FREE statements, stacking occurs when an allocated controlled variable is specified in an ALLOCATE statement without first having been specified in a FREE statement. When this occurs, the previous allocation is not Reactivation of an Active Procedure released; its value remains the same but, (Recursion) for the time being, this value is not available to the programmer. Conceptually, the new allocation is stacked on top of the An active procedure that can be reactivated previous allocation, with the result that from within itself or from within another the previous allocation is "pushed-down" in active procedure is said to be a recursive the stack. Subsequent allocations are procedure; such reactivation is called always added to the top of the stack. recursion. Any reference to a stacked controlled A procedure can be invoked recursively variable always refers to the most recent only if the RECURSIVE option has been allocation for that variable; i.e., to the specified in its PROCEDURE statement. This allocation at the top of the stack. Thus, option also applies to the names of any a FREE statement specifying a stacked secondary entry points that the procedure controlled variable will cause the might have. allocation at the top of the stack to be freed. When this occurs, the other The environment (that is, values of allocations in the stack are "popped-up", automatic variables, etc.) of every the most recent previous allocation coming invocation of a recursive procedure is to the top and being available once again. preserved in a manner analogous to the When an allocation is popped up to the top stacking of allocations of a controlled of a stack, its value is the same as it was variable. An environment can thus be when it was pushed down. thought of as being "pushed down" at a recursive invocation, and "popped up" at the termination of that invocation. Note Based Storage that a label constant always contains information identifying the current invocation of the block that contains the Based storage is similar to controlled label. Hence, if a label constant is storage in that it can be allocated by the assigned to a label variable in a ALLOCATE statement and freed by the FREE particular invocation, a GO TO statement statement; and more than one allocation can naming that variable in another invocation exist for one variable. However, the could restore the environment that existed programmer has a much greater degree of when the assignment was performed. control with based storage. For example, all current based allocations are available Consider the following example: at any time: unique reference to a particular allocation is provided by a pointer value qualifying the based variable reference. The use of based storage also allows data to be processed in an input/output buffer without it having to be moved from the buffer to a variable (i.e., to a work area). By means of the LOCATE statement and the READ statement with the SET option, the structure of the based variable is superimposed on the data in the output or input buffer respectively, so that any reference to that allocation of the based variable is a reference to that data.
Chapter 6: Blocks, Flow of Control, and Storage Allocation 81 Note the difference between recursive and reentrant procedures. A procedure is recursive only if the RECURSIVE option is specified in the PROCEDURE statement. Every procedure compiled by the F Compiler is reentrant; that is, it is a procedure that does not modify itself during its execution, so that subsequent execution of the procedure with the same data will always give the same result.
Effect of Recursion on Storage Classes In the above example, RECURS and AGN are both recursive procedures. Since X is Allocation of static variables (as static and has the INITIAL attribute, it is illustrated above) is not affected by allocated and initialized before execution recursion, because they are allocated of the program begins. storage outside the environment of a recursive procedure. However, allocation The first time that RECURS is invoked, X of automatic variables is affected, because is incremented by 1 and X=1 is transmitted they are a part of the environment of a by the PUT statement. Since X is less than particular invocation and also because 5, AGN is invoked. In AGN, X is their allocation and release is not incremented by 1 and X=2 is transmitted directly controlled by the programmer. (also by a PUT statement). AGN then Allocation of controlled variables is not reinvokes RECURS. affected, because their allocation and release is completely under the control of This second invocation of RECURS is a the programmer. This applies to based recursive invocation, because RECURS is variables also, but with the provision that still active. X is incremented as before, the storage class of the pointer variable and then X=3 is transmitted. X is still must be taken into account. less than 5, so AGN is invoked again. Since AGN is active when invoked, this Each time a procedure is invoked invocation of AGN is also recursive. X is recursively, storage for each automatic incremented once again, X=4 is transmitted, variable is reallocated, and the previous and RECURS is invoked for the third time. allocation is pushed down in a stack. Each time an activation of a recursive procedure The third invocation of RECURS results is terminated, automatic storage is popped in the transmission of X=5. But, since X up to yield the next most recent generation is no longer less than 5, GO TO LAB is of automatic storage. Hence, each executed, and then RECURS is terminated. generation of automatic storage is However, only the third invocation of preserved as part of the environment of the RECURS is terminated, with the result that corresponding recursive activation. control returns to the procedure that invoked RECURS for the third time; that is, Pointer variables, unless they are control returns to the statement following explicitly declared otherwise, are CALL RECURS in the second invocation of automatic by default, and are therefore AGN. At this point X is decremented by 1 subject to the stacking process described and X=4 is transmitted. Then the second above. Consequently, when reference is invocation of AGN is terminated, and made to a based variable in a recursive control returns to the procedure that procedure, the programmer should take care invoked AGN for the second time; that is, to ensure the validity and accuracy of the control returns to the statement following pointer qualifier. CALL AGN in the second invocation of RECURS. Here X is decremented again and X=3 is transmitted, after which the second invocation of RECURS is terminated and control returns to the first invocation of Prologues and Epilogues AGN. X is decremented again, X=2 is transmitted, the first invocation of AGN is Each time a block is activated, certain terminated, and control returns to the activities must be performed before control first invocation of RECURS. X is can reach the first executable statement in decremented, X=1 is transmitted, and the the block. This set of activities is first invocation of RECURS is terminated. called a prologue. Similarly, when a block Control then returns to the procedure that is terminated, certain activities must be invoked RECURS in the first place. performed before control can he transferred
82 out of the block; this set of activities is iteration factors, and initial values. called an epilogue. Note that if an item is referred to in an expression and the allocation or Prologues and epilogues are the initialization of a second item depends on responsibility of the compiler and not of that expression, then the first item must the programmer. They are discussed here be in no way dependent on the second item because knowledge of them may assist the for its own allocation and initialization. programmer in improving the performance of Further, the first item must be in no way his program. dependent on any other item that so depends on the second item. For example, the following declaration is invalid: Prologues DCL A(B(1)) INITIAL(2), B(A(1)) INITIAL(3); A prologue is a compiler-written routine logically appended to the beginning of a However, the following declaration is block and executed as the first step in the valid: activation of a block. In general, activities performed by a prologue are as DCL N INITIAL(3), follows: A(N), B CHAR(N); • Computing dimension bounds and string lengths for automatic and DEFINED variables and ENTRY declarations. Epilogues • Allocating storage for automatic variables and initialization, if specified. An epilogue is a compiler-written routine logically appended to the end of a block • Determining which currently active and executed as the final step in the blocks are known to the procedure, so termination of a block. In general, the that the correct generations of activities performed by an epilogue are as automatic storage are accessible, and follows: the correct on-units may be entered. • Re-establishing the on-unit environment • Allocating storage for dummy arguments existing before the block was that may be passed from this block. activated. The prologue may need to evaluate • Releasing storage for all automatic expressions defining lengths, bounds, variables allocated in the block.
Chapter 6: Blocks, Flow of Control, and Storage Allocation 83 Chapter 7: Recognition of Names
A PL/I program consists of a collection of Contained In: identifiers, constants, and special characters used as operators or delimiters. All of the text of a block, from the Identifiers themselves may be either PROCEDURE or BEGIN statement through keywords or names with a meaning specified the corresponding END statement, is by the programmer. The PL/I langua ge is said to be contained in that block. constructed so that the compiler can Note, however, that the labels of the determine from context whether or not an BEGIN or PROCEDURE statement heading identifier is a keyword, so there is no the block, as well as the labels of list of reserved words that must not be any ENTRY statements that apply to the used for programmer-defined names. Any block, are not contained in that identifier may be used as a name; the only block. Nested blocks are contained in restriction is that at any point in a the block in which they appear. program a name can have one and only one meaning. For example, the same name cannot be used for both a file and a Internal To: floating-point variable. Text that is contained in a block, but Note: The above is true so long as the not contained in any other block 60-character set is used. Certain nested within it, is said to be identifiers of the 48-character set cannot internal to that block. Note that be used as programmer-defined identifiers entry names of a procedure (and labels in a program written using the 48-character of a BEGIN statement) are not set; these identifiers are: GT, GE, NE, LT, contained in that block. NG, LE, NL, CAT, OR, AND, NOT, and PT. Consequently, they are internal to the containing block. Entry names of an It is not necessary, however, for a name external procedure are treated as if to have the same meaning throughout a they were external to the external program. A name declared within a block procedure. has a meaning only within that block. Outside the block it is unknown unless the In addition to these terms, the same name has also been declared in the different types of declaration are outer block. In this case, the name in the important. The three different types -- outer block refers to a different object. explicit declaration, contextual This enables programmers to specify local declaration, and implicit declaration -- definitions and, hence, to write procedures are discussed in the following sections. or begin blocks without knowing all the names being used by other programmers writing other parts of the program. Since it is possible for a name to have more than one meaning, it is important to Explicit Declaration define which part of the pro gram a particular meaning applies to. In PL/I a A name is explicitly declared if it name is given attributes and a meaning by a appears: declaration (not necessarily explicit). The part of the program for which the 1. In a DECLARE statement meaning applies is called the scope of the declaration of that name. In most cases, 2. In a parameter list the scope of a name is determined entirely by the position at which the name is 3. As a statement label declared within the program (or assumed to be declared if the declaration is not 4. As a label of a PROCEDURE or ENTRY explicit). There are cases in which more statement than one generation of data may exist with the same name (such as in recursion); such The appearance of a name in a parameter cases are considered separately. list is the same as if a DECLARE statement for that name appeared immediately In order to understand the rules for the following the PROCEDURE or ENTRY statement scope of a name, it is necessary to in which the parameter list occurs (though understand the terms "contained in" and the same name may also appear in a DECLARE "internal to." statement internal to the same block).
84 The appearance of a name as the label of 1. A name that appears in a CALL either a PROCEDURE or ENTRY statement is statement, in a CALL option, or the same as if it were declared in a followed by a parenthesized list in a DECLARE statement immediately preceding the function reference (in a context where PROCEDURE statement for the procedure to an expression is expected) is given which it refers. the ENTRY and EXTERNAL attributes. The appearance of a statement label prefix constitutes explicit declaration 2. A name that appears in a FILE option, equivalent to the declaration of a variable or a name that appears in an ON, in a DECLARE statement internal to the same SIGNAL, or REVERT statement for a block as the statement to which it applies. condition that requires a file name, is given the FILE and EXTERNAL attributes. SCOPE OF AN EXPLICIT DECLARATION 3. A name that appears in an ON CONDITION, SIGNAL CONDITION, or REVERT The scope of an explicit declaration of a CONDITION statement is recognized as a name is that block to which the declaration programmer-defined condition name. is internal, including all contained blocks except those blocks (and any blocks 4. A name that appears in an EVENT option contained within them) to which another or in a WAIT statement is given the explicit declaration of the same identifier EVENT attribute. is internal. 5. A name that appears in a TASK option For example: is given the TASK attribute. 6. A name that appears in the BASED attribute, in a SET option, or on the left-hand side of a pointer qualification symbol is given the POINTER attribute. 7. A name that appears in an IN option, or in the OFFSET attribute is given the AREA attribute. Note, however, that all contextually declared area variables are given the AUTOMATIC attribute. The F Compiler implementation requires that the variable named in the OFFSET attribute must be based; if a nonbased area variable is named, the offset variable will be changed to a pointer variable. Hence, unless the variable named in the OFFSET attribute is explicitly declared, OFFSET effectively becomes The lines to the right indicate the POINTER, and a severe error occurs. scope of the names. B and B' indicate the two distinct uses of the name B; C and C' 8. If an undeclared identifier appears: indicate the two uses of the name C. a. before the equal sign in an assignment statement, or Contextual Declaration b. before the assignment symbol in a DO statement (or in a repetitive specification), or When a name appears in certain contexts, some of its attributes can be determined c. in the data list of a GET without explicit declaration. In such a statement case, if the appearance of a name does not lie within the scope of an explicit and if that identifier is neither declaration for the same name, the name is enclosed within an argument list nor said to be contextually declared. immediately followed by an argument list, that identifier is contextually A name that has not been declared declared to be a variable and not a explicitly will be recognized and declared reference to a built-in function or contextually in the following cases: pseudo-variable. This rule does not
Chapter 7: Recognition of Names 85 apply to the identifiers ONCHAR, Implicit Declaration ONSOURCE, and PRIORITY.
Examples of contextual declaration are: If a name appears in a program and is not explicitly or contextually declared, it is READ FILE (PREQ) INTO (Q); said to be implicitly declared. The scope of an implicit declaration is determined as ON CONDITION (NEG) CALL CREDIT; if the name were declared in a DECLARE statement immediately following the first In these statements, PREQ is given the FILE PROCEDURE statement of the external attribute, NEG is recognized as a procedure in which the name is used. programmer-defined condition name, and CREDIT is given the ENTRY attribute. The An implicit declaration causes default EXTERNAL attribute is given to all three by attributes to be applied, depending upon default. the first letter of the name. If the name begins with any of the letters I through N it is given the attributes REAL FIXED BINARY (15,0). If the name begins with any SCOPE OF A CONTEXTUAL DECLARATION other letter including one of the alphabetic extenders $, #, or @, it is given the attributes REAL FLOAT DECIMAL The scope of a contextual declaration is (6). (The default precisions are those determined as if the declaration were made defined for System/360 implementations.) in a DECLARE statement immediately following the PROCEDURE statement of the external procedure in which the name appears. Examples of Declarations Note that contextual declaration has the same effect as if the name were declared in Scopes of data declarations are illustrated the external procedure, even when the in Figure 7-1. The brackets to the left statement that causes the contextual indicate the block structure; the brackets declarations is internal to a block (called to the right show the scope of each B, for example) that is contained in the declaration of a name. In the diagram, the external procedure. Consequently, the name scopes of the two declarations of Q and R is known throughout the entire external are shown as Q and Q' and R and R'. procedure, except for any blocks in which the name is explicitly declared. It is as P is declared in the block A and known if block B has inherited the declaration throughout A since it is not redeclared. from the containing external procedure. Q is declared in A, and redeclared in B. Since a contextual declaration cannot The scope of the first declaration is all exist within the scope of an explicit of A except B; the scope of the second declaration, it is impossible for the declaration is block B only. context of a name to add to the attributes established for that name in an explicit R is declared in block C, but a declaration. reference to R is also made in block B. The reference to R in block B results in an For example, the following procedure is implicit declaration of R in A,the external invalid: procedure. Two separate names with different scopes exist, therefore. The scope of the explicitly declared R is C; the scope of the implicitly declared R is all of A except block C. I is referred to in block C. This results in an implicit declaration in the external procedure A. As a result, this declaration applies to all of A, including the contained procedures B, C and D. The identifier F is in a parameter list and S is explicitly declared in procedure D is, therefore, explicitly declared. It is and is known only within D. given the attributes REAL DECIMAL FLOAT by default. Since F is explicitly declared, Scopes of entry name and statement label its appearance in the FILE option does not declarations are illustrated in Figure 7-2. constitute a contextual declaration. Such The example shows two external procedures. use of the identifier is in error. The names of these procedures, A and E, are
86 assumed to be explicitly declared with the in block B is executed, control is EXTERNAL attribute within the procedures to transferred to L1 in block A, and block B which they apply. In addition, E is is terminated. contextually declared in A as an EXTERNAL entry name by its appearance in the CALL statement in block C. The contextual declaration of E applies throughout block A and is linked to the explicit declaration D and B are explicitly declared in block of E that applies throughout block E. The A and can be referred to anywhere within A; scope of the name E is all of block A and but since they are INTERNAL, they cannot be all of block E. The scope of the name A is referred to in block E (unless passed as an only all of the block A, and not E. argument to E). However, it could appear in a CALL statement in E, since the CALL statement itself would provide a contextual declaration of A, which would then result in the scope of A being all of A and all of C is explicitly declared in B and can be E. referred to from within B, but not from outside B. The label L1 appears with statements internal to A and to C. Two separate declarations are therefore established; the first applies to all of block A except L2 is declared in B and can be referred block C, the second applies to block C to in block B, including C, which is only. Therefore, when the GO TO statement contained in B, but not from outside B.
Chapter 7: Recognition of Names 87 Application of Default Attributes IF SUM (P(I,*)) = Q(I) THEN GO TO B; S = S+1; The attributes associated with a name IF S = 3 THEN CALL OUT (E); comprise those explicitly, contextually, or CALL D(I); implicitly declared for that name, as well B: END; as those assumed by default. The default END C; for each attribute is given in Part II, D: PROCEDURE (N); Section I, "Attributes." PUT LIST ('ERROR IN ROW ', N, 'TABLE NAME ', S); END D; END B; The INTERNAL and EXTERNAL Attributes GO TO E; END A; The scope of a name with the INTERNAL OUT: PROCEDURE (R); attribute is the same as the scope of its DECLARE R LABEL, declaration. Any other explicit (M,L) STATIC INTERNAL declaration of that name refers to a new INITIAL (0), object with a different, non-overlapping S BINARY FIXED EXTERNAL, scope. Z FIXED DECIMAL(1); M = M+1; S=0; A name with the EXTERNAL attribute may IF M 88 DECLARE statement to establish that they, Scope of Member Names of External too, are arrays. (The asterisk notation Structures indicates that the bounds of the parameters are the same as the bounds of the arguments.) When a major structure name is declared with the EXTERNAL attribute in more than one block, the attributes of the I and M are not explicitly declared in corresponding structure members must be the the external procedure A; they are same in each case, although the therefore implicitly declared and are known corresponding member names need not be throughout A, even though I appears only identical. Members of structures always within block C. have the INTERNAL attribute, and cannot be declared with any scope attribute. Within the external procedure A, OUT and However, a reference to a member of an SET are contextually declared as entry external structure, using the member name names, since they follow the keyword CALL. known to the block containing the They are therefore considered to be reference, is effectively a reference to declared in A and are given the EXTERNAL that member in all blocks in which the attribute by default. external name is known, regardless of whether the corresponding member names are The second external procedure in the identical. For example: example has two entry names, SET and OUT. These are considered to be explicitly declared with the EXTERNAL attribute. The two entry names SET and OUT are therefore known throughout the two procedures. The label B appears twice in the program, once as the label of a begin block, which is an explicit declaration, as a label in A. It is redeclared as a label within block C by its appearance as a prefix to the END statement. The reference to B in the GO TO statement within block C therefore refers to the label of the END statement within block C. Outside block C, any reference to B would be to the label of the begin block. Note that C and D can be called from any point within B but not from that part of A In this example, if A.B is changed in outside B, nor from another external PROCA, it is also changed for PROCB, and procedure. Similarly, since E is known vice versa; if A.0 is changed in PROCA, A.D throughout the external procedure A, a is changed for PROCB, and vice versa. transfer to E may be made from any point within A. The label B within block C, however, can only be referred to from within C. Transfers out of a block by a GO Multiple Declarations and Ambiguous TO statement can be made; but such transfers into a nested block generally References cannot. An exception is shown in the external procedure OUT, where the label E Two or more declarations of the same from block A is passed as an argument to identifier internal to the same block the label parameter R. constitute a multiple declaration, unless at least one of the identifiers is declared The statement GO TO R causes control to within a structure in such a way that name pass to the label E, even though E is qualification can be used to make the names declared within A, and not known within unique. OUT. Two or more declarations anywhere in a The variables M and L are declared program of the same identifier as different within the block OUT to be STATIC, so their names with the EXTERNAL attribute values are preserved between calls to OUT. constitute a multiple declaration. In order to identify the S in the Multiple declarations are in error. procedure OUT as the same S in the procedure C, both have been declared with A name need have only enough the attribute EXTERNAL. qualification to make the name unique. Chapter 7: Recognition of Names 89 Reference to a name is always taken to only the second D; the first D would have apply to the identifier declared in the to be referred to as A.C.D. innermost block containing the reference. An ambiguous reference is a name with insufficient qualification to make the name DECLARE 1 A, 2 B, 3 C, 2 D, 3 C; unique. In this example, A.0 is ambiguous because The following examples illustrate both neither C is completely qualified by this multiple declarations and ambiguous reference. references: DECLARE 1 A, 2 A, 3 A; DECLARE 1 A, 2 C, 2 D, 3 E; BEGIN; In this example, A refers to the first A, DECLARE 1 A, 2 B, 3 C, 3 E; A.A refers to the second A, and A.A.A A.0 = D.E; refers to the third A. In this example, A.0 refers to C in the DECLARE X; inner block; D.E refers to E in the outer block. DECLARE 1 Y, 2 X, 3 Z, 3 A, 2 Y, 3 Z, 3 A; DECLARE 1 A, 2 B, 2 B, 2 C, 3 D, 2 D; In this example, X refers to the first In this example, B has been multiply DECLARE statement. A reference to Y.Z is declared. A.D refers to the second D, ambiguous; Y.Y.Z refers to the second Z; since A.D is a complete qualification of and Y.X.Z refers to the first Z. 90 Chapter 8: Input and Output Introduction because of the data conversion it involves, and more space is required on external storage devices because all data is in PL/I includes input and output statements character form. that enable data to be transmitted between the internal and external storage devices of a computer. A collection of data external to a program is called a data set. Although record-oriented transmission Transmission of data from a data set to a may demand rather more effort from the program is termed input, and transmission programmer, it is more versatile than of data from a program to a data set is stream-oriented transmission, with regard called output. to the manner in which data can be processed and the types of data set that PL/I input and output statements are can be processed. Since data is recorded concerned with the logical organization of in a data set exactly as it appears in main a data set and not with its physical storage, any data format is acceptable; no characteristics; a program can be designed conversion problems will arise, but the without specific knowledge of the programmer must have a greater awareness of input/output devices that will be used when the structure of his data. the program is executed. To allow a source program to deal primarily with the logical aspects of data rather than with its physical organization in a data set, PL/I This chapter discusses those aspects of employs a symbolic representation of a data PL/I input and output that are common to set called a file. A file can be stream-oriented and record-oriented associated with different data sets at transmission, including files and their different times during the execution of a attributes, and the relationship of files program. to data sets. Chapters 9 and 10 describe the input and output statements that can be Two types of data transmission can be used in a PL/I program, and the various used by a PL/I program. In stream-oriented data set organizations that are recognized transmission, the organization of the data in PL/I. Stream-oriented transmission is in the data set is ignored within the dealt with in Chapter 9, and program, and the data is treated as though record-oriented transmission in Chapter 10. it actually were a continuous stream of individual data items in character form; data is converted from character form to internal form on input, and from internal form to character form on output. In record-oriented transmission, the data set is considered to be a collection of discrete records. No data conversion takes Data Sets place during record transmission; on input the data is transmitted exactly as it is recorded in the data set, and on output it Data sets are stored on a variety of is transmitted exactly as it is recorded external storage media, such as punched internally. It is possible for the same cards, reels of magnetic tape, magnetic data set to be processed at different times disks, magnetic drums, and punched paper by either stream transmission or record tape. Despite their variety, these media transmission; however, all items in the have many common characteristics that data set would have to be in character permit standard methods of collecting, form. storing, and transmitting data. For convenience, the general term volume is Stream-oriented transmission is ideal used to refer to a unit of external for simple jobs, particularly those that storage, such as a reel of magnetic tape or use punched card input and have limited a disk pack, without regard to its specific output; a minimum of coding is required of physical composition. the programmer, especially for punched card input and printed output. However, compared with record-oriented transmission, stream-oriented transmission is less The data items within a data set are efficient in terms of execution time arranged in distinct physical groupings Chapter 8: Input and Output 91 called blocks.' These blocks allow the data data set, PL/I employs a symbolic set to be transmitted and processed in representation of a data set called a file. portions rather than as a unit. For This symbolic representation determines how processing purposes, each block may consist input and output statements access and of one or more logical subdivisions called process the associated data set. Unlike a records, each of which contains one or more data set, however, a file has significance data items. (Sometimes a block is called a only within the source program and does not physical record, because it is the unit of exist as a physical entity external to the data that is physically transmitted to and program. from a volume, and its logical subdivisions are called logical records.) PL/I requires a file name to be declared for a file, and allows the characteristics When a block contains two or more of the file to be described with keywords records, the records are said to be called file attributes, which are specified blocked. Blocked records often permit more for the file name. The following lists compact and efficient use of storage. show the attributes that are applicable for Consider how data is stored on magnetic each type of data transmission: tape: the data between two successive interrecord gaps is one block, or physical Stream-Oriented Record-Oriented record. If several logical records are Transmission Transmission contained within one block, the number of gaps is reduced, and much more data can be FILE FILE stored on a full length of tape. For STREAM RECORD example, on a tape of density 800 INPUT INPUT characters/inch with an interrecord gap of OUTPUT OUTPUT 0.6 inches, a card image of 80 characters EXTERNAL UPDATE would take up 0.1 inches. If the records INTERNAL SEQUENTIAL were unblocked, each record would require PRINT DIRECT 0.1 inches, plus 0.6 inches for the ENVIRONMENT TRANSIENT interrecord gap, making a total of 0.7 BUFFERED inches. 100 records would therefore take UNBUFFERED up 70 inches of tape. If the records were EXTERNAL blocked, however, at, say, 10 records to a INTERNAL block, each block of 10 records would take BACKWARDS up 1 inch, plus 0.6 inches for the gap, KEYED making a total of 1.6 inches. Thus, 100 EXCLUSIVE records would now take up only 16 inches of ENVIRONMENT tape; this is less than 25 percent of the amount needed for the unblocked records. A detailed description of each of these attributes appears in Part II, Section I, Most data processing applications are "Attributes." The discussions below give a concerned with logical records rather than brief description of each of the file blocks. Therefore, the input and output description attributes and show how these statements of PL/I generally refer to attributes are declared for a file. The logical records; this allows the programmer scope attributes, EXTERNAL and INTERNAL, to concentrate on the data to be processed, are discussed in Chapter 7, "Recognition of without being directly concerned about its Names." physical organization in external storage. THE FILE ATTRIBUTE Files The FILE attribute indicates that the To allow a source program to deal primarily associated identifier is a file name. For with the logical aspects of data rather example, the identifier MASTER is declared than with its physical organization in a to be a file name in the following statement: 'This discussion has to be slightly DECLARE MASTER FILE; modified for teleprocessing applications, where the data set is in fact a queue of The attributes associated with the FILE messages and the term "block" is not attribute fall into two categories: strictly applicable. However, a message is alternative attributes and additive similar to a block in that it may consist attributes. An alternative attribute is of one or more records. Teleprocessing is one that is chosen from a group of discussed in Chapter 10, "Record-Oriented attributes. If no explicit or implicit Transmission." declaration is given for one of the 92 alternative attributes in a group and if The STREAM attribute causes a file to be one of the alternatives is required, a treated as a continuous stream of data default attribute is assumed. items recorded only in character form. An additive attribute is one that must The RECORD attribute causes a file to be be stated explicitly or is implied by treated as a sequence of records, each another explicitly stated attribute or record consisting of one or more data items name. The additive attribute KEYED can be recorded in any internal form. implied by the DIRECT attribute. The additive attribute PRINT can be implied by DECLARE MASTER FILE RECORD, the standard output file name SYSPRINT. An DETAIL FILE STREAM; additive attribute can never be applied by default. Note: With the exception of the INTERNAL The INPUT, OUTPUT, and UPDATE Attributes and EXTERNAL scope attributes, all the alternative and additive attributes imply the FILE attribute. Therefore, the FILE The function attributes determine the attribute need not be specified for a file direction of data transmission permitted that has at least one of the alternative or for a file. The INPUT attribute applies to additive attributes already specified files that are to be read only. The OUTPUT explicitly. The FILE attribute must be attribute applies to files that are to be specified explicitly, however, if only the written only. The UPDATE attribute INTERNAL or EXTERNAL attribute is describes a file that is to be used for specified; otherwise, the identifier will both input and output; it allows records to be assumed, by default, to be an arithmetic be inserted into an existing file and other variable rather than a file name. records already in that file to be altered or deleted. DECLARE DETAIL FILE INPUT, ALTERNATIVE ATTRIBUTES REPORT FILE OUTPUT, MASTER FILE UPDATE; PL/I provides five groups of alternative file attributes. Each group is discussed individually. Following is a list of the The SEQUENTIAL, DIRECT, and TRANSIENT groups and the default for each: Attributes The access attributes apply only to a file with the RECORD attribute, and provide information regarding access to the contents of the file. The SEQUENTIAL attribute specifies that successive records in the file are to be accessed on the basis of their successive physical positions, such as they are on magnetic tape. The DIREOT attribute specifies that a record in a file is to be accessed on the The scope attributes are discussed in basis of its location in the file and not detail in Section I, "Attributes", and a on the basis of its position relative to brief description of alternative attributes the record previously read or written. The is given below. location of the record is determined by a character-string which is called a key; therefore, the DIRECT attribute implies the KEYED attribute. The associated data set The STREAM and RECORD Attributes must be in a direct-access volume. The TRANSIENT attribute, which is used The STREAM and RECORD attributes describe only for teleprocessing applications, the type of data transmission specifies that the file is associated with (stream-oriented or record-oriented) to be a data set whose contents are used in input and output operations for the re-established each time it is accessed file. (i.e., a "queue" data set; messages Chapter 8: Input and Output 93 originating from and destined for remote The PRINT Attribute terminals are held in such a data set while in transit between a message control program and a message processing program.) The PRINT attribute applies only to files The action of reading a record removes that with the STREAM and OUTPUT attributes. It record from the data set. With the F indicates that the file is eventually to be Compiler, access is sequential, but the printed, that is, the data associated with file must have the KEYED attribute since a the file is to appear on printed pages, key is used to identify the terminal although it may first be written on some concerned; a buffer is always used, and so other medium. The PRINT attribute causes the file must also have the BUFFERED the initial byte of each record of the attribute. Teleprocessing is discussed in associated data set to be reserved for a Chapter 10, "Record-Oriented Transmission." printer control character. The BUFFERED and UNBUFFERED Attributes The BACKWARDS Attribute The buffering attributes apply only to files that have the SEQUENTIAL or TRANSIENT The BACKWARDS attribute applies only to attributes. The BUFFERED attribute files with the SEQUENTIAL, RECORD, and indicates that records transmitted to and INPUT attributes and only to data sets on from a file must pass through an magnetic tape. It indicates that a file is intermediate internal-storage area. Use of to be accessed in reverse order, beginning the BUFFERED attribute enables the system with the last record and proceeding through to automatically overlap data transmission the file until the first record is with other processing. The size of a accessed. buffer is usually related to the size of the blocks (physical records) in the data set associated with the file. The UNBUFFERED attribute indicates that The KEYED Attribute a record in a data set need not pass through a buffer but may be transmitted directly to and from the internal storage The KEYED attribute indicates that records associated with a variable. Any desired in the file are to be accessed using one of overlapping of data transmission with other the key options (KEY, KEYTO, or KEYFROM) of processing is the responsibility of the data transmission statements or of the programmer, who can use the EVENT option DELETE statement. Note that the KEYED for this purpose. The blocks and records attribute does not necessarily indicate are generally the same size in a data set that the actual keys exist or are to be that is associated with an UNBUFFERED file. written in the data set; consequently, it need not be specified unless one of the key Note: Specification of UNBUFFERED does not options is to be used. The STREAM preclude the use of buffers. In some attribute cannot be applied to a file that cases, 'hidden buffers" are required. has the KEYED attribute. The nature and These cases are listed in the discussion of use of keys is discussed in detail in the BUFFERED and UNBUFFERED attributes in Chapter 10, "Record-Oriented Transmission." Part II, Section I, "Attributes." The EXCLUSIVE Attribute ADDITIVE ATTRIBUTES The EXCLUSIVE attribute applies only to The additive attributes are: files with the RECORD, DIRECT, and UPDATE attributes. It specifies that any record PRINT in the file may be automatically locked by a task while it is operating on that BACKWARDS record, to prevent interference by another concurrent task. It can be suppressed by KEYED the NOLOCK option on the READ statement. EXCLUSIVE For detailed information on the effects of operations on EXCLUSIVE files, see "The ENVIRONMENT (option-list) EXCLUSIVE Attribute," in Chapter 14. 94 The ENVIRONMENT Attribute OPEN FILE(file-name) [option-list] [,FILE(file-name) [option-list]]...; The ENVIRONMENT attribute provides information that allows the compiler to The option list of the OPEN statement can determine the method of accessing the data specify any of the alternative and additive associated with a file. It specifies the attributes, except the INTERNAL, EXTERNAL, physical organization of the data set that and ENVIRONMENT attributes. Attributes will be associated with the file, and included as options in the OPEN statement indicates how the data set is to be are merged with those stated in a DECLARE handled. statement. The same attributes need not be listed in both an OPEN statement and a The general format of the ENVIRONMENT DECLARE statement for the same file, and, attribute is of course, there must be no conflict. Other options that can appear in the OPEN ENVIRONMENT (option-list) statement are the TITLE option, used to associate the file name with the data set, The options appropriate to the two types of and the PAGESIZE and LINESIZE options, used data transmission are described in the to specify the layout of a data set. The relevant chapters: Chapter 9, TITLE option is discussed below under "Stream-Oriented Transmission," and Chapter "Associating Data Sets with Files," and the 10, "Record-Oriented Transmission." PAGESIZE and LINESIZE options, which apply only to STREAM files, in Chapter 9. The option list may precede the FILE (file name) specification. OPENING AND CLOSING FILES For the F Compiler, the OPEN statement Before the data associated with a file can is executed by library routines that are be transmitted by input or output loaded dynamically at the time the OPEN statements, certain file preparation statement is executed. Consequently, activities must occur, such as checking for execution time can be reduced if more than the availability of external storage media, one file is specified in the same OPEN positioning the media, and allocating statement, since the routines need be appropriate programming support. Such loaded only once, regardless of the number activity is known as opening a file. Also, of files being opened. Note, however, that when processing is completed, the file must such multiple opening may require be closed. Closing a file involves considerably more storage than might releasing the facilities that were otherwise be needed. established during the opening of the file. PL/I provides two statements, OPEN and For a file to be opened explicitly, the CLOSE, to perform these functions. These OPEN statement must be executed before any statements, however, are optional. If an of the input and output statements listed OPEN statement is not executed for a file, below in "Implicit Opening" are executed the file is opened automatically when the for the file. first data transmission statement for that file is executed; in this case, the automatic file preparation consists of standard system procedures that use information about the file as specified in a DECLARE statement (or assumed from a contextual declaration). Similarly, the Implicit Opening file is closed automatically on termination of the task that opened it, if it has not been explicitly closed before termination. An implicit opening of a file occurs when one of the statements listed below is executed for a file for which an OPEN statement has not already been executed. The type of statement determines which The OPEN Statement unspecified alternatives are applied to the file when it is opened. Execution of an OPEN statement causes one or more files to be opened explicitly. The The following list contains the OPEN statement has the following basic statement identifiers and the attributes format: deduced from each: Chapter 8: Input and Output 95 Statement Identifier Attributes Deduced Merged Attributes Implied Attributes GET STREAM, INPUT UPDATE RECORD PUT STREAM, OUTPUT SEQUENTIAL RECORD READ RECORD, INPUT DIRECT RECORD, KEYED (see Note) BUFFERED RECORD WRITE RECORD, OUTPUT (see Note) UNBUFFERED RECORD LOCATE RECORD, OUTPUT, PRINT OUTPUT, STREAM SEQUENTIAL, BUFFERED BACKWARDS RECORD, REWRITE RECORD, UPDATE SEQUENTIAL INPUT DELETE RECORD, UPDATE KEYED RECORD UNLOCK RECORD, DIRECT, UPDATE, EXCLUSIVE EXCLUSIVE RECORD, KEYED, DIRECT, UPDATE Note: INPUT and OUTPUT are deduced from Note: The attributes SEQUENTIAL or DIRECT READ and WRITE only if UPDATE has not been and BUFFERED or UNBUFFERED do not apply to explicitly declared. a file with the STREAM attribute. The following two examples illustrate An implicit opening caused by one of the attribute merging for an explicit opening above statements is equivalent to preceding and for an implicit opening. the statement with an OPEN statement that specifies the deduced attributes. Explicit opening: DECLARE LISTING FILE STREAM; Merging of Attributes OPEN FILE(LISTING) PRINT; There must be no conflict between the Attributes after merge due to execution of attributes specified in a file declaration the OPEN statement are STREAM and PRINT. and the attributes merged, explicitly or Attributes after implication are STREAM, implicitly, as the result of opening the PRINT, and OUTPUT. Attributes after file. For example, the attributes INPUT default application are STREAM, PRINT, and UPDATE are in conflict, as are the OUTPUT, and EXTERNAL. attributes UPDATE and STREAM. Implicit opening: After the attributes are merged, the DECLARE MASTER FILE KEYED INTERNAL; attribute implications listed below are applied prior to the application of the default attributes discussed earlier. Implied attributes can also cause a READ FILE (MASTER) INTO conflict. If a conflict in attributes (MASTER RECORD) KEYTO(MASTER KEY); exists after the application of default attributes, the UNDEFINEDFILE condition is Attributes after merge due to the opening raised. caused by execution of the READ statement are KEYED, INTERNAL, RECORD, and INPUT. Attributes after implication are KEYED, INTERNAL, RECORD, and INPUT (no additional Following is a list of merged attributes attributes are implied). Attributes after and attributes that each implies after default application are KEYED, INTERNAL, merging: RECORD, INPUT, SEQUENTIAL, and BUFFERED. 96 Associating Data Sets with Files compiler to OLDMTER for use within the program.) If statement number 3 causes implicit opening of the file DETAIL, the With the System/360 Operating System, the name DETAIL is taken to be the same as the association of a file with a specific data ddname of a DD statement in the current job set is accomplished using job control step. language1, outside the PL/I program. At the time a file is opened, the PL/I file In each of the above cases, a name is associated with the name (ddname) corresponding DD statement must appear in of a data definition statement (DD the job stream; otherwise, the statement), which is, in turn, associated UNDEFINEDFILE condition would be raised. with the name of a specific data set The three DD statements would appear, in (dsname). Note that the direct association part, as follows: is with the name of a DD statement, not with the name of the data set itself. 1. //MASTER DD DSNAME=... A ddname can be associated with a PL/I 2. //OLDMASTE DD DSNAME=... file either through the file name or through the character-string value of the 3. //DETAIL DD DSNAME=... expression in the TITLE option of the associated OPEN statement. If a file is opened explicitly by an OPEN statement that includes a TITLE If a file is opened implicitly, or if no option, the ddname is taken from the TITLE TITLE option is included in the OPEN option, and the file name is not used statement that causes explicit opening of outside the program. The TITLE option the file, the ddname is assumed to be the appears in an OPEN statement in the same as the file name. If the file name is following format: longer than eight characters, the ddname is assumed to be composed of the first eight OPEN FILE(file-name) TITLE(expression); characters of the file name. The expression in the TITLE option is Note: Since external names are limited to evaluated and, if necessary, converted to a seven characters for the F Compiler, an character string, that is assumed to be the external file name of more than seven ddname identifying the appropriate data characters is shortened into a set. If the character string is longer concatenation of the first four and the than eight characters, only the first eight last three characters of the file name. characters are used. The following OPEN Such a shortened name is not, however, the statement illustrates how the TITLE option name used as the ddname in the associated might be used: DD statement. OPEN FILE(DETAIL) TITLE('DETAIL1'); Consider the following statements: If this statement were executed, there must 1. OPEN FILE(MASTER); be a DD statement in the current job step with DETAIL1 as its ddname. It might 2. OPEN FILE(OLDMASTER); appear, in part, as follows: 3. READ FILE(DETAIL)...; //DETAIL1 DD DSNAME=DETAILA,... When statement number 1 is executed, the Thus, the data set DETAILA is associated file name MASTER is taken to be the same as with the file DETAIL through the ddname the ddname of a DD statement in the current DETAIL1. job step. When statement number 2 is executed, the name OLDMASTE is taken to be Although a data set name represents a the same as the ddname of a DD statement in specific collection of data, the file name the current job step. (The first eight can, at different times, represent entirely characters of a file name form the ddname. different data sets. In the above example Note, however, that if OLDMASTER is an of the OPEN statement, whatever data set is external name, it will be shortened by the named in the DSNAME parameter of the DD statement DETAIL1 is the one that is associated with DETAIL at the time it is 1This does not apply to TRANSIENT files; opened. the association of a TRANSIENT file with a data set is direct and does not involve job Use of the TITLE option allows a control language (except that a DD DUMMY programmer to choose dynamically, at open statement is given for each TRANSIENT time, one among several data sets to be file). See "Teleprocessing" in Chapter 10, associated with a particular file name. "Record-Oriented Transmission." Consider the following example: Chapter 8: Input and Output 97 DECLARE 1 INREC, 2 FIELD 1..., name and the ddname. During the second 2 FILE_IDENT CHARACTER(8), iteration of the group, MASTER is opened DETAIL FILE INPUT..., again. This time, however, the value of MASTER FILE INPUT...; the second element of IDENT is taken, and MASTER is associated with the ddname OPEN FILE(DETAIL); MASTER1B. Similarly, during the final iteration of the group, MASTER is READ FILE (DETAIL) INTO (INREC); associated with the ddname MASTER1C. OPEN FILE (MASTER) TITLE(FILEIDENT); Note: The character set of the job control language does not contain the break Assume that the program containing these character (_). Consequently, this statements is used to process several character cannot appear in ddnames. Care different detail data sets, each of which should thus be taken to avoid using break has a different corresponding master data characters among the first eight characters set. Assume, further, that the first of file names, unless the file is to be record of each detail data set contains, as opened with a TITLE option with a valid its last data item, a character string that ddname as its expression. The alphabetic identifies the appropriate master data set. extender characters $, 8, and #, however, The following DD statements might appear in are valid for ddnames, and can begin a the current job step: DDNAME. //DETAIL DD DSNAME=... //MASTER1A DD DSNAME=MASTER1A... The CLOSE Statement //MASTER1B DD DSNAME=MASTER1B... The basic form of the CLOSE statement is: //MASTER1C DD DSNAME=MASTER1C... CLOSE FILE (file-name) In this case, MASTER1A, MASTER1B, and [,FILE (file-name)]...; MASTER1C represent three different master files. The first record of DETAIL would Executing a CLOSE statement dissociates the contain as its last item, either specified file from the data set with which 'MASTER1A', 'MASTER1B', or 'MASTER1C', it became associated when the file was which is assigned to the character-string opened. The CLOSE statement also variable FILE_IDENT. When the OPEN dissociates from the file all attributes statement is executed to open the file established for it by the implicit or MASTER, the current value of FILE_IDENT explicit opening process. If desired, new would be taken to be the ddname, and the attributes may be specified for the file appropriate data set identified by that name in a subsequent OPEN statement. ddname would be associated with the file However, all attributes explicitly given to name MASTER. the file name in a DECLARE statement remain in effect. Another similar use of the TITLE option is illustrated in the following statements: As with the OPEN statement, closing more than one file with a single CLOSE statement DCL IDENT(3) CHAR(1) can save execution time, but it may require INIT('A', 'B', 'C'); the use of more storage than would DO I = 1 TO 3; otherwise be needed. OPEN FILE(MASTER) TITLE('MASTER1'||IDENT(I)); Note: Closing an already closed file or opening an already opened file has no effect apart from increasing the execution time of the program. CLOSE FILE(MASTER); END; In this example, IDENT is declared as a STANDARD FILES character-string array with three elements having as values the specific character strings 'A', 'B', and 'C'. When MASTER is Two standard files are provided that can be opened during the first iteration of the used by any PL/I program. One is the DO-group, the character constant 'MASTER1' standard input file SYSIN, and the other is is concatenated with the value of the first the standard output file SYSPRINT. These element of IDENT, and the associated ddname files need not be declared or opened is taken to be MASTER1A. After processing, explicitly; a standard set of attributes is the file is closed, dissociating the file applied automatically. For SYSIN, the 98 attributes are STREAM INPUT, and for declared as a file name with the STREAM and SYSPRINT they are STREAM OUTPUT PRINT. OUTPUT attributes, unless the INTERNAL Both file names, SYSIN and SYSPRINT, are attribute is declared for it. assumed to have the EXTERNAL attribute, even though SYSPRINT contains more than seven characters. Note: Special care must be taken when SYSIN or SYSPRINT is declared as anything The file names need not be explicitly other than a STREAM file. The F Compiler stated in GET and PUT statements when these causes, in effect, the identifier SYSIN to files are to be used. GET and PUT be inserted into each GET statement in statements that do not name a file are which no file name is explicitly stated and equivalent to: the identifier SYSPRINT to be inserted into each PUT statement in which no file name is GET FILE(SYSIN)...; explicitly stated. Consequently, the following would be in error: PUT FILE(SYSPRINT)...; DECLARE (SYSIN,SYSPRINT) FIXED Any other references to SYSIN and SYSPRINT DECIMAL (4,2); (such as in ON statements or in record-oriented statements) must be stated explicitly. GET LIST (A,B,C); The identifiers SYSIN and SYSPRINT are PUT LIST (D,E,F); not reserved for the specific purposes described above. They can be used for The identifier SYSIN would be inserted into other purposes than identifying standard the GET statement, and SYSPRINT in the PUT files. Other attributes can be applied to statement. In this case, however, they them, either explicitly or contextually, would not refer to the standard files, but but the PRINT attribute is applied to the fixed-point variables declared in automatically to SYSPRINT when it is the block. Chapter 8: Input and Output 99 Chapter 9: Stream-Oriented Transmission Introduction LIST-DIRECTED TRANSMISSION This chapter describes the input and output List-directed transmission permits the user statements used in stream-oriented to specify the variables to which data is transmission, which is one of the two types assigned and to specify data to be of data transmission available in PL/I. transmitted without specifying the format. Those features that apply equally to stream-oriented and record-oriented transmission, including files, file Input: In general, the data items in the attributes, and opening and closing files, stream are character strings in the form of are described in Chapter 8, which forms a optionally signed valid constants or in the general introduction to this chapter and to form of expressions that represent complex Chapter 10. constants. The variables to which the data is to be assigned are specified by a data list. Items are separated by a comma In stream-oriented transmission, a data and/or one or more blanks. set is treated as a continuous stream of data items in character form; within a Output: The data values to be transmitted program, block and record boundaries are are specified by a variable, a constant, or ignored. However, a data set is considered an expression that represents a data item. to consist of a series of lines of data, Each data item placed in the stream is a and each data set that is created or character-string representation that accessed by stream-oriented transmission reflects the attributes of the variable. has a line size associated with it. In Items are separated by a blank. Leading general, a line is equivalent to a record zeros of arithmetic data are suppressed. in the data set; however, the line size Binary fixed-point and floating-point does not necessarily equal the record size. items, however, are character strings that express the value in decimal representation. There are three modes of stream-oriented transmission: list-directed, data-directed, For PRINT files, data items are and edit-directed. The transmission automatically aligned on statements used in all three modes implementation-defined preset tab generally require the following positions. For the F Compiler, these information: positions are 1, 25, 49, 73, 97, and 121, but provision is made for the programmer to 1. The name of the file associated with alter these values (see IBM System/360 the data set from which data is to be Operating System, PL/I (F) Programmer's obtained or to which data is to be Guide). assigned. 2. A list of program variables to which data items are to be assigned during input or from which data items are to DATA-DIRECTED TRANSMISSION be obtained during output. This list is called a data list. On output, the data list can also include constants Data-directed transmission permits the user and other expressions. to transmit self-identifying data. 3. The format of each data item in the Input: Each data item in the stream is in stream. the form of an assignment statement that specifies both the value and the variable Under certain conditions all of this to which it is to be assigned. In general, required information can be implied; in values are in the form of constants. Items other cases, only a portion of it need be are separated by a comma and/or one or more stated explicitly. In list-directed and blanks. A semicolon must end each group of data-directed transmission, the formats of items to be accessed by a single GET data items are not specified in the statement. A data list in the GET statements. And in data-directed statement is optional, since the semicolon transmission, even the data list is determines the number of items to be optional. obtained from the stream. 100 Output: The data values to be transmitted that specify the origin or destination of may be specified by an optional data list. the data or indicate where it appears in Each data item placed in the stream has the the stream relative to the preceding data. form of an assignment statement without a semicolon. Items are separated by a blank. The last item transmitted by each PUT The following is a summary of the statement is followed by a semicolon. stream-oriented data transmission Leading zeros of arithmetic data are statements and their options: suppressed. The character representation of each value reflects the attributes of the variable, except for fixed-point and STREAM INPUT floating-point binary items, which appear as values expressed in decimal notation. GET [FILE (file-name)|STRING If the data list is omitted, it is (character-string-variable)] assumed to specify all variables that are data-specification [COPY] known within the block containing the [SKIP [(expression)]]; statement and are permitted in data-directed output. STREAM OUTPUT For PRINT files, data items are automatically aligned on the implementation-defined preset tab positions PUT [FILE (file-name)|STRING referred to under "List-Directed (character-string-variable)] Transmission." data-specification [SKIP [(expression)]]; EDIT-DIRECTED TRANSMISSION STREAM OUTPUT PRINT Edit-directed transmission permits the user PUT [FILE (file-name)] to specify the variables to which data is [data-specification] to be assigned or to specify data to be PAGE [LINE(expression)] transmitted, and to specify the format for SKIP[(expression)] each item on the external medium. [LINE (expression) Input: Data in the stream is a continuous string of characters; different data items The options may appear in any order, The are not separated. The variables to which data specification can have one of the the data is to be assigned are specified by following forms: a data list. Format items in a format list specify the number of characters to be assigned to each variable and describe LIST (data-list) characteristics of the data (for example, the assumed location of a decimal point). DATA [(data-list)] Output: The data values to be transmitted EDIT (data-list) (format-list) are defined by a data list. The format [(data-list) (format-list)]... that the data is to have in the stream is defined by a format list. The data specification can be omitted for STREAM OUTPUT PRINT files only if one of the control options (PAGE, SKIP, or LINE) appears. Format lists may use any of the Data Transmission Statements following format items: A,B,C,E,F, which may be used with Stream-oriented transmission uses only one P,R,X, any STREAM file input statement, GET, and one output SKIP [(w)] statement, PUT. A GET statement gets the COLUMN (w) next series of data items from the stream, and a PUT statement puts a specified set of PAGE which can be used with data items into the stream. The variables LINE (w) STREAM OUTPUT PRINT to which data items are assigned, and the files only variables or expressions from which they are transmitted, are generally specified in The statements are discussed individually a data list with each GET or PUT statement. in detail in Part II, Section The statements may also include options "Statements." Chapter 9: Stream-Oriented Transmission 101 OPTIONS OF TRANSMISSION STATEMENTS PUT LIST(X,Y,Z) SKIP(3); causes the values of the variables X, Y, The FILE and STRING Options and Z to be printed on the standard output file SYSPRINT commencing on the third line after the current line. The FILE option specifies the name of the file upon which the operation is to take place. The STRING option allows GET and PUT statements to be used to transmit data The PAGE Option between internal storage locations rather than between internal and external storage. If neither the FILE option nor the STRING The PAGE option can be specified only for option appears in a GET statement, the PRINT files. It causes a new current page standard input file SYSIN is assumed; if to be defined within the data set. The neither option appears in a PUT statement, PAGE option takes effect before the the standard output file SYSPRINT is transmission of any values defined by the assumed. data specification (if any), even if it appears after the data specification. Examples of the use of the FILE option are given in some of the statements below, Chapter 11, "Editing and String Handling," illustrates the use of the STRING option. The LINE Option The COPY Option The LINE option can be specified only for PRINT files. It causes blank lines to be inserted so that the next line will be the The COPY option may appear only in a GET wth line of the current page, where w is statement. It specifies that each data the value of the parenthesized expression item is to be written, exactly as read, when converted to an integer. The LINE into the standard output file SYSPRINT. option takes effect before the transmission For example, the statement of any values defined by the data specification (if any), even if it follows GET FILE(SYSIN) DATA(A,B,C)COPY; the data specification. If both the PAGE option and the LINE option appear in the not only transmits the values assigned to same statement, the PAGE option is applied A, B, and O in the input stream to the first. For example, the statement variables with these names, but also causes them to be printed out in data-directed PUT FILE(LIST) DATA(P,Q,R) LINE(34) PAGE; format. causes the values of the variables P, Q, and R to printed in data-directed format on a new page, commencing at line 34. The SKIP Option The SKIP option specifies a new current DATA SPECIFIOATIONS line (or record) within the data set. The parenthesized expression is converted to an integer w, which must be greater than zero Data specifications are given in GET and (unless the file is a PRINT file). The PUT statements to identify the data to be data set is positioned to the start of the transmitted. The data specifications wth line (record) relative to the current correspond to the modes of transmission. line (record). For non-PRINT files, if the expression is omitted or if w is not greater than Data Lists zero, a value of 1 is assumed. For PRINT files, if w is less than or equal to zero, the effect is that of a carriage return List-directed, data-directed, and with the same current line. edit-directed data specifications require a data list to specify the data items to be The SKIP option takes effect before the transmitted. transmission of any values defined by the data specification, even if it appears General format: after the data specification. Thus, the statement (data-list) 102 where "data list" is defined as: the control variable or pseudo-variable. Expression-3 element [,element]... represents the increment to be added to the control variable Syntax rules: after each repetition of data-list elements in the repetitive The nature of the elements depends upon specification. Expression-2 whether the data list is used for input or represents the terminating value for output. The rules are as follows: of the control variable. Expression-4 represents a second 1. On input, a data-list element for condition to control the number of edit-directed and list-directed repetitions. The exact meaning of transmission can be one of the the specification is identical to following: an element, array, or that of a DO statement with the structure variable, a pseudo-variable, same specification. When the last or a repetitive specification (similar specification is completed, to a repetitive specification of a DO control passes to the next element group) involving any of these in the data list. elements. For a data-directed data specification, a data-list element can 3. Each repetitive specification must be be an element, array, or structure enclosed in parentheses, as shown in variable. None of the names in a the general format. Note that if a data-directed data list can be repetitive specification is the only subscripted, but qualified names are element in a data list, two sets of allowed. outer parentheses are required, since the data list must have one set of 2. On output, a data-list element for parentheses and the repetitive edit-directed and list-directed data specification must have a separate specifications can be one of the set. following: an element expression, an array expression, a structure 4. As Figure 9-1 shows, the expression, or a repetitive "specification" portion of a specification involving any of these repetitive specification can be elements. For a data-directed data repeated a number of times, as in the specification, a data-list element can following form: be an element, array, or structure variable, or a repetitive DO I = 1 TO 4, 6 TO 10 specification involving any of these elements. Subscripts are allowed for Repetitive specifications can be data-directed output. nested; that is, an element of a repetitive specification can itself be 3. The elements of a data list must be of a repetitive specification. Each DO arithmetic or string data type. portion must be delimited on the right with a right parenthesis (with its 4. A data list must always be enclosed in matching left parenthesis added to the parentheses. beginning of the entire repetitive specification). REPETITIVE SPECIFICATION: The general format of a repetitive specification is When DO portions are nested, the shown in Figure 9-1. rightmost DO is at the outer level of nesting. For example, consider the Syntax rules: following statement: 1. An element in the element list of the GET LIST (((A(I,J) DO I = 1 TO 2) repetitive specification can be any of DO J = 3 TO 4)); those allowed as data-list elements as listed above. Note the three sets of parentheses, in addition to the set used to delimit 2. The expressions in the specification, the subscript. The outermost set is which are the same as those in a DO the set required by the data list; the statement, are described as follows: next is that required the outer repetitive specification. The third a. Each expression in the set of parentheses is that required by specification is an element the inner repetitive specification. expression. This statement is equivalent to the following nested DO-groups: b. In the specification, expression-1 represents the starting value of DO J = 3 TO 4: Chapter 9: Stream-Oriented Transmission 103 DO I = 1 TO 2; If, within a data list used in an input GET LIST (A (I,J)); statement for list-directed or END; edit-directed transmission, a variable is END; assigned a value, this new value is used if the variable appears in a later reference It gives values to the elements of the in the data list. For example: array A in the following order: A(1,3), A(2,3), A(1,4), A(2,4) GET LIST (N,(X(I) DO I=1 TO N), J, K, SUBSTR (NAME, J,K)); Note: Although the DO keyword is used in the repetitive specification, a corresponding END statement is not allowed. When this statement is executed, data is transmitted and assigned in the following order: TRANSMISSION OF DATA-LIST ELEMENTS: If a data-list element is of complex mode, the real part is transmitted before the 1. A new value is assigned to N. imaginary part. If a data-list element is an array 2. Elements are assigned to the array X variable, the elements of the array are as specified in the repetitive transmitted in row-major order, that is, specification in the order with the rightmost subscript of the array X(1),X(2),...X(N), with the new value varying most frequently. of N used to specify the number of items to be assigned. If a data-list element is a structure variable, the elements of the structure are transmitted in the order specified in the 3. A new value is assigned to J. structure declaration. For example, if a declaration is: 4. A new value is assigned to K. DECLARE 1 A (10), 2 B, 2 C; 5. A substring of length K is assigned to the string variable NAME, beginning at then the statement: the Jth character. PUT FILE(X) LIST(A); would result in the output being ordered as follows: LIST-DIRECTED DATA SPECIFICATION A.B(1) A.C(1) A.B(2) A.C(2) A.B(3) A.C(3)...etc. General format for a list-directed data If, however, the declaration had been: specification, either input or output is as follows: DECLARE 1 A, 2 B(10), 2 C(10); LIST (data-list) then the same PUT statement would result in the output being ordered as follows: The data list is described under "Data Lists," above. The keyword LIST must A.B(1) A.B(2) A.B(3)...A.B(10) appear to specify the list-directed mode of A.C(1) A.C(2) A.C(3)...A.C(10) transmission. 104 List-Directed Data in the Stream GET statement should follow, the first character accessed will be the character to which the file has been positioned (in Data in the stream, either input or output, other words, the next data item will begin is of character data type and has one of with the first character following the the following general forms: blank or comma that separated it from the previous data item). {+|-} arithmetic-constant character-string-constant If the data is a character-string constant, the surrounding quotation marks bit-string-constant are removed, and the enclosed characters are interpreted as a character string. {+|-} real-constant{+|-}imaginary-constant If the data is a bit-string constant, These forms correspond exactly to the forms enclosing quotation marks and the trailing used for writing optionally signed character B are removed, and the enclosed constants in a PL/I program. However, characters are interpreted as a bit string. sterling constants cannot be used. A string constant must be one of the two If the data is an arithmetic constant or permitted forms listed above; iteration and complex expression, it is converted to string repetition factors are not allowed. coded arithmetic form with the base, scale, A blank must not precede the central + or - mode, and precision implied by the in complex expressions. constant. Data type conversions follow the rules for conversion from character type, as List-Directed Input Format listed in Part II, Section F, "Problem Data Conversion." When the data named is an array, the data consists of constants, the first of which is assigned to the first element of the array, the second constant to the second List-Directed Output Format element, etc., in row-major order. A structure name in the data list The values of the element variables and represents a list of the contained element expressions in the data list are converted variables and arrays in the order specified to character representations and in the structure description. transmitted to the data stream. On input, data items in the stream must A blank separates successive data items be separated either by a blank or by a transmitted. (For PRINT files, items are comma. This separator may be surrounded by separated according to program tab an arbitrary number of blanks. A null field settings.) in the stream is indicated either by the first non-blank character in the data set The length of the data field placed in being a comma, or by two commas separated the stream is a function of the attributes by an arbitrary number of blanks. A null of the data item, including precision and field specifies that the value of the length. Detailed discussions of the associated item in the data list is to conversion rules and their effect upon remain unchanged. precision are listed in the sections covering conversion to character type in The transmission of the list of Part II, Section F, "Problem Data constants on input is terminated by Conversion." expiration of the list or by the end-of-file condition. In the former case, Fixed-point and floating-point binary positioning in the stream for the next GET data items are converted to decimal statement is always at the character notation before being placed in the stream. following the first blank or comma following the last data item transmitted. For numeric character values, the More than one blank can separate two data character-string value is transmitted. items, and a comma separator may be preceded or followed by one or more blanks. Bit strings are converted to character In such cases, a subsequent GET statement representation of bit-string constants, will ignore intervening blanks and the consisting of the characters 0 and 1, comma (if present) and will access the next enclosed in quotation marks, and followed data item. However, if an edit-directed by the letter B. Chapter 9: Stream-Oriented Transmission 105 Character strings are written out. If data list contains a name that is not the file does not have the attribute PRINT, included in the stream, the value of enclosing quotation marks are supplied, and the associated variable remains contained single quotation marks or unchanged. On output, all items in apostrophes are replaced by two quotation the assumed data list are transmitted. marks. The field width is the current length of the string plus the number of 3. On input, recognition of a semicolon added quotation marks. If the file has the or an end of file in the stream causes attribute PRINT, enclosing quotation marks transmission to cease, whether or not are not supplied, and contained single a data list is specified. On output, quotation marks or apostrophes are a semicolon is written into the stream unmodified. The field width is the current after the last data item transmitted length of the string. by each PUT statement. Examples of list-directed data specifications: Data-Directed Data in the Stream LIST (CARD, RATE, DYNAMIC FLOW) LIST ((THICKNESS(DISTANCE) The data in the stream associated with a DO DISTANCE = 1 TO 1000)) data-directed transmission statement is in the form of a list of element assignments LIST (P, Z, M, R) having the following general format (the optionally signed constants, like the LIST (A*B/C, (X+Y)**2) variable names and the equal signs, are in character form): The specification in the last example can be used only for output, since it element-variable = constant contains operational expressions. Such [{b|,}element-variable = constant]...; expressions are evaluated when the statement is executed, and the result is General rules: placed in the stream. 1. The element variable may be a subscripted name. Subscripts must be optionally signed decimal integer DATA-DIRECTED DATA SPECIFICATION constants. 2. On input, the element assignments may General format for a data-directed data be separated by either a blank (b in specification, either for input or output, the above format) or a comma. is as follows: Redundant blanks are ignored. On output, the assignments are separated DATA[(data-list)] by a blank. General rules: 3. Each constant in the stream has one of the forms described for list-directed 1. The data list is described in "Data transmission. Lists" in this chapter. It cannot include parameters, defined variables, or based variables. For input, the data list cannot contain subscripted Data-Directed Input Format names. Names of structure elements in the data list need only have enough qualification to resolve any ambiguity; full qualification is not General rules for data-directed input: required. On input, if the stream contains a name that does not have a 1. If the data specification does not counterpart in the data list, the NAME include a data list, the names in the condition is raised. stream may be any names known at the point of transmission. Qualified 2. Omission of the data list implies that names in the input stream must be a data list is assumed. This assumed fully qualified. data list contains all the names that are known to the block and are valid 2. The number of characters in a for data-directed transmission. On qualified name, must not exceed 256. input, if the stream contains a name not known within the block, the NAME 3. If a data list is used, each element condition is raised. If the assumed of the data list must be an element, 106 array, or structure variable. Names specification and input data stream cannot be subscripted, but qualified could have the following forms: names are allowed in the data list. All names in the stream should appear Data Specification Input Data Stream in the data list; however, the order DATA (CARDIN.RETAIL) CARDIN.PRICE. of the names need not be the same, and RETAIL = 4.28; the data list may include names that do not appear in the stream. 6. Interleaved subscripts cannot appear in qualified names in the stream. All For example, consider the following subscripts must be moved all the way data list, where A, B, C, and D are to the right, following the last name names of element variables: of the qualified name. For example, assume that Y is declared as follows: DATA (B, A, C, D) DECLARE 1 Y(5,5),2 A(10),3 B, This data list may be associated with 3 C, 3 D; the following input data stream: An element name would have to appear A= 2.5, B= .0047, D= 125, Z= 'ABC'; in the stream as follows: Note: C appears in the data list but Y.A.B(2,3,8)= 8.72 not in the stream; its value remains unaltered. Z, which is not in the The name in the data list could not data list, raises the NAME condition. contain the subscript. 4. If the data list includes the name of 7. The maximum number of elements an array, subscripted references to permitted in a list for data-directed that array may appear in the stream input is 320. Each element of a although subscripted names cannot structure counts as a separate list appear in the data list. The entire element. array need not appear in the stream; only those elements that actually appear in the stream will be assigned. Data-Directed Output Format Let X be the name of a two-dimensional array declared as follows: General rules for data-directed output: DECLARE X (2,3)FIXED (6,2); 1. An element of the data list may be an Consider the following data list and element, array, or structure variable, input data stream: or a repetitive specification involving any of these elements or Data List Input Data Stream further repetitive specifications. DATA (X) X(1,1)= 7.95, X(1,2)= 8085, Subscripted names can appear. The X(1,3)= 73; names appearing in the data list, together with their values, are Although the data list has only the transmitted in the form of a list of name of the array, the associated element assignments separated by input stream may contain values for blanks and terminated by a semicolon. individual elements of the array. In (For PRINT files, items are separated this case, only three elements are according to program tab settings.) assigned; the remainder of the array is unchanged. 2. Array variables in the data list are treated as a list of the contained 5. If the data list includes the names of subscripted elements in row-major structure elements, then fully order. qualified names must appear in the stream, although full qualification is Consider an array declared as follows: not required in the data list. Consider the following structures: DECLARE X (2,4)FIXED; DECLARE 1 CARDIN, 2 PARTNO, 2 DESCRP, If X appears in a data list as 2 PRICE, 3 RETAIL, 3 WHSL, follows: 1 CARDOUT, 2 PARTNO, 2 DESCRP, 2 PRICE, 3 RETAIL, 3 WHSL; DATA (X) If it is desired to read a value for on output, the output data stream CARDIN.PRICE.RETAIL, the data would have the form: Chapter 9: Stream-Oriented Transmission 107 X(1,1)= 1 X(1,2)= 2 X(1,3)= 3 the assumed point is located X(1,4)= 4 X(2,1)= 5 X(2,2)= 6 outside the field with assumed X(2,3)= 7 X(2,4)= 8; zeros intervening; that is, if for precision (p,q) p is less than q, or q is less than zero. (In this Note: In actual output, more than one case an exponent is transmitted, blank would follow the equal sign. In preceded by a letter F which is conversion from coded arithmetic to not valid for conversion to character, leading zeros are converted arithmetic type.) to blanks, and up to three additional blanks may appear at the beginning of the field. b. When the character-string value of a numeric character variable does not represent a valid optionally 3. Subscript expressions that appear in a signed arithmetic constant. For data list are evaluated and replaced example, this is always true for by the value. complex numeric character variables. 4. Items that are part of a structure appearing in the data list are transmitted with the full qualification, but subscripts follow the qualified names rather than being interleaved. If a data list is Length of Data-Directed Output Fields specified for a structure element transmitted under data-directed output as follows: The length of the data field on the external medium is a function of the attributes declared for the variable and, DATA (Y(1,-3).Q) since the name is also included, the length of the fully qualified subscripted name. The field length for output items converted the associated data field in the from coded arithmetic data, numeric output stream is of the form: character data, and bit-string data is the same as that for list-directed output data, Y.01,-3)= 3.756; and is governed by the rules for data conversion to character type as described 5. The number of characters in a in Part II, Section F, "Problem Data qualified name must not exceed 256. Conversion." 6. Structure names in the data list are For character-string data, the contents interpreted as a list of the contained of the character string are written out element or elements, and any contained enclosed in quotation marks. Each arrays are treated as above. quotation mark or apostrophe contained within the character string is represented Consider the following structure: by two successive quotation marks. DECLARE 1 A, 2 B, 3 C, 3 D; In the example shown in Figure 9-2, A is declared as a one-dimensional array of six If a data list for data-directed elements; B is a one-dimensional array of output is as follows: seven elements. The procedure calculates and writes out values for A(I) = B(I+1) + DATA (A) B(I). and the values of B and D are 2 and 17, respectively, the associated data fields in the output stream would be as follows: EDIT-DIRECTED DATA SPECIFICATION A.B= 2 A.C.D= 17; 7. In the following cases, data-directed General format for an edit-directed data output is not valid for subsequent specification, either for input or output, data-directed input: is as follows: a. When the precision attribute of a EDIT (data-list) (format-list) fixed-point variable is such that ((data-list)(format-list)]... 108 1. The data list, which must be enclosed contains five data format items and in parentheses, is described in "Data its associated data list specifies ten Lists," above. The format list, which items to be transmitted. Then the also must be enclosed in parentheses, sixth item in the data list will be contains one or more format items. associated with the first data format There are three types of format items: item, and so forth. Suppose a format data format items, which describe data list contains ten data format items in the stream; control format items, and its associated data list specifies which describe page, line, and spacing only five items. Then the sixth operations; and remote format items, through the tenth format items will be which specify the label of a separate ignored. statement that contains the format list to be used. Format lists and format items are discussed in more 5. An array or structure variable in a detail in "Format Lists," below. data list is equivalent to n items in Edit-directed transmission is the only the data list, where n is the number mode that can be used for reading or of element items in the array or writing sterling data, by use of a structure, each of which will be picture specification. associated with a separate use of a data format item. 2. For input, data in the stream is considered to be a continuous string of characters not separated into 6. If a data list item is associated with individual data items. The number of a control format item, that control characters for each data item is action is executed, and the data list specified by a format item in the item is paired with the next format format list. The characters are item. treated according to the associated format item. 7. The specified transmission is complete when the last item in the data list 3. For output, the value of each item in has been processed using its the data list is converted to a format corresponding format item. Subsequent specified by the associated format format items, including control format item and placed in the stream in a items, are ignored. field whose width also is specified by the format item. 8. On output, data items are not automatically separated, but 4. For either input or output, the first arithmetic data items generally data format item is associated with include leading blanks because of data the first item in the data list, the conversion rules and zero suppression. second data format item with the second item in the data list, and so Examples: forth. If a format list contains fewer format items than there are GET EDIT (NAME, DATA, SALARY) items in the associated data list, the (A(N), X(2), A(6), F(6,2)); format list is re-used; if there are excessive format items, they are PUT EDIT ('INVENTORY='||INUM,INVCODE) ignored. Suppose a format list (A,F(5)); Chapter 9: Stream-Oriented Transmission 109 The first example specifies that the iterations. The associated format first N characters in the stream are to be item or format list is that item or treated as a character string and assigned list of items immediately to the right to NAME; the next two characters are to be of the iteration factor. skipped; the next six are to be assigned to DATA in character format; and the next six General rule: characters are to be considered as an optionally signed decimal fixed-point There are three types of format items: constant and assigned to SALARY. data format items, control format items, and the remote format item. Data format The second example specifies that the items specify the external forms that data character string 'INVENTORY=' is to be fields are to take. Control format items concatenated with the value of INUM and specify the page, line, column, and spacing placed in the stream in a field whose width operations. The remote format item allows is the length of the resultant string. format items to be specified in a separate Then the value of INVCODE is to be FORMAT statement elsewhere in the block. converted to character to represent an optionally signed decimal fixed-point Detailed discussions of the various integer constant and is then to be placed types of format items appear in Part II, in the stream right-adjusted in a field Section E, "Edit-Directed Format Items." with a width of five characters (leading The following discussions show how the characters may be blanks). Note that format items are used in edit-directed data operational expressions and constants can specifications. appear in output data lists only. For the F Compiler the number of nested iteration factors in a format list must not exceed 20. Format Lists Data Format Items Each edit-directed data specification On input, each data format item requires its own format list. specifies the number of characters to be associated with the data item and how to General format: interpret the external data. The data item is assigned to the associated variable (format-list) named in the data list, with necessary conversion to conform to the attributes of where "format list" is defined as: the variable. On output, the value of the associated element in the data list is item , ite em converted to the character representation specified by the format item and is n item inserted into the data stream. n (format-list) , n (format-list) There are six data format items: fixed-point (F), floating-point (E), Syntax rules: complex (C), picture (P), character-string (A), and bit-string (B). They are, in 1. Each "item" represents a format item general, specified as follows: as described below. F (w[,d[,p]]) 2. The letter n represents an iteration factor, which is either an expression E(w,d[,s]) enclosed in parentheses or an unsigned decimal integer constant. If it is C (real-format-item [,real-format-item]) the latter, a blank must separate the constant and the following format P 'picture-specification' item. The iteration factor specifies that the associated format item or A [(w)] format list is to be used n successive times. A zero or negative iteration B [(w)] factor specifies that the associated format item or format list is to be In this list, the letter w represents an skipped and not used (the data list expression that specifies the number of item will be associated with the next characters in the field. The letter d format item). If an expression is specifies the number of digits to the right used to represent the iteration of a decimal point; it may be omitted for factor, it is evaluated and converted integers. The real format item of the to an integer once for each set of complex format item represents the 110 appearance of either an F, E or P format (4,2); then the above statement item. The picture specification of the P specifies that the value of TOTAL is format item can be either a numeric to be converted to the character character specification or a representation of a fixed-point number character-string specification. On output, and written into the standard output data associated with E and F format items file SYSPRINT. A decimal point is to is rounded if the internal precision be inserted before the last two exceeds the external precision. numeric characters, and the number will be right-adjusted in a field of A third specification (p) is allowed in six characters. Leading zeros will be the F format item; it is a scaling factor. changed to blanks, and, if necessary, A third specification (s) is allowed in the a minus sign will be placed to the E format item to specify the number of left of the first numeric character. digits that must be maintained in the first subfield of the floating-point number. In conversion from internal decimal These specifications are discussed in fixed-point type to character type, detail in Part II, Section E, the resultant string always is three "Edit-Directed Format Items." characters longer than p, the number of digits in the precision Note: Fixed-point binary and floating-point specification of a decimal fixed-point binary data items must always be variable. The extra characters may represented in the input stream with their appear as blanks preceding the number values expressed in decimal digits. The F in the converted string. And, since and E format items then are used to access leading zeros are converted to blanks, them, and the values will be converted to additional blanks may precede the binary representation upon assignment. On number. If a decimal point or a minus output, binary items are converted to sign appears, either will cause one decimal values and the associated F or E leading blank to be replaced. format items must state the field width and point placement in terms of the converted In edit-directed output, the field decimal number. width specification in the format item (in this case, the 6 in the F(6,2) The following examples illustrate the format item) can be used to truncate use of format items: leading zeros. In this specification, one zero is truncated. TCTAL would be 1. GET FILE (INFILE) EDIT (ITEM) (A(20)); converted to a character string of length seven. If all four digits of This statement causes the next 20 the converted number are greater than characters in the file called INFILE zero, the number, with its inserted to be assigned to ITEM. The value is decimal point, will require five digit automatically transformed from its positions; if the number is negative, character representation specified by another digit position will be the format item A(20), to the required for the minus sign. representation specified by the Consequently, the F(6,2) specification attributes declared for ITEM. will always allow all digits, the point, and a possible sign to appear, Note: If the data list and format list but will remove the extra blank by were used for output, the length of a truncation. string item need not be specified in the format item if the field width is 4. GET FILE(A) EDIT (ESTIMATE) (E(10,6)); to be the same as the length of the string, that is, if no blanks are to This statement obtains the next ten follow the string. characters from the file called A and interprets them as a floating-point 2. PUT FILE (MASKFLE) EDIT (MASK) (B); decimal number. A decimal point is assumed before the rightmost six Assume MASK has the attribute BIT digits of the mantissa. An actual (25); then the above statement writes point within the data can override the value of MASK in the file called this assumption. The value of the MASKFLE as a string of 25 characters number is converted to the attributes consisting of 0's and l's. A field of ESTIMATE and assigned to this width specification can be given in variable. the B format item. It must be stated for input. 5. GET EDIT (NAME, TOTAL) (P'AAAAA',P'9999'); 3. PUT EDIT (TOTAL) (F(6,2)); When this statement is executed, the Assume TOTAL has the attributes FIXED standard input file SYSIN is assumed. Chapter 9: Stream-Oriented Transmission 111 The first five characters must be F(7,2), COLUMN(30), F(7,2), alphabetic or blank and they are COLUMN(45), F(7,2), assigned to NAME. The next four COLUMN(60), F(7,2)); characters must be nonblank numeric characters and they are assigned to The first PUT statement specifies that TOTAL. the heading QUARTERLY STATEMENT is to be written on line two of a new page Control Format Items in the standard output file SYSPRINT. The second statement specifies that The control format items are the spacing two lines are to be skipped (that is, format item (X), and the COLUMN, LINE, "skip to the third following line") PAGE, and SKIP format items. The spacing and the value of ACCT# is to be format item specifies relative spacing in written, beginning at the first the data stream. The PAGE and LINE format character of the fifth line; the value items can be used only with PRINT files of BOUGHT, beginning at character and, consequently, can only appear in PUT position 14; the value of SOLD, statements. All but PAGE generally include beginning at character position 30; expressions. LINE, PAGE, and SKIP can also the value of PAYMENT, beginning at appear separately as options in the PUT character position 45; and the value statement; SKIP can appear as an option in of BALANCE at character position 60. the GET statement. Note: Control format items are executed at The following examples illustrate the the time they are encountered in the format use of the control format items: list. Any control format list that appears after the data- list is exhausted will have 1. GET EDIT (NUMBER, REBATE) no effect. (A(5), X(5), A(5)); Remote Format Item This statement treats the next 15 characters from the standard input The remote format item (R) specifies the file, SYSIN, as follows: the first label of a FORMAT statement (or a label five characters are assigned to variable whose value is the label of a NUMBER, the next five characters are FORMAT statement) located elsewhere; the spaced over and ignored, and the FORMAT statement and the GET or PUT remaining five characters are assigned statement specifying the remote format item to REBATE. must be internal to the same block. The FORMAT statement contains the remotely 2. GET FILE(IN) EDIT(MAN,OVERTIME) situated format items. This facility (SKIP(1), A(6), COLUMN(60), F(4,2)); permits the choice of different format specifications at execution time, as This statement positions the data set illustrated by the following example: associated with file IN to a new line; the first six characters on the line DECLARE SWITCH LABEL; are assigned to MAN, and the four GET FILE(IN) LIST(CODE); characters beginning at character IF CODE = 1 position 60 are assigned to OVERTIME. THEN SWITCH = L1; ELSE SWITCH = L2; 3. PUT FILE(OUT) EDIT (PART, COUNT) GET FILE(IN) EDIT (W,X,Y,Z) (A(4), X(2), F(5)); (R(SWITCH)); L1: FORMAT (4 F(8,3)); This statement places in the file L2: FORMAT (4 E(12,6)); named OUT four characters that represent the value of PART, then two SWITCH has been declared to be a label blank characters, and finally five variable; the second GET statement can be characters that represent the made to operate with either of the two fixed-point value of COUNT. FORMAT statements. 4. The following examples show the use of Expressions in Format Items the COLUMN, LINE, PAGE, and SKIP format items in combination with one The w, p, d, and s specifications in another. data format items, as well as the specifications in control format items, PUT EDIT ('QUARTERLY STATEMENT•) need not be decimal integer constants. (PAGE, LINE(2), A(19)); Expressions are allowed. They may be PUT EDIT variables or other expressions. (ACCT#, BOUGHT, SOLD, PAYMENT, BALANCE) On input, a value read into a variable (SKIP(3), A(6), COLUMN(14), can be used in a format item associated 112 with another variable later in the data Consider the following example: list. OPEN FILE(REPORT) OUTPUT STREAM PRINT PUT EDIT (NAME,NUMBER,CITY) PAGESIZE(55) LINESIZE(110); (A(N),A(N-4),A(10)); GET EDIT (M,STRING_A,I,STRING_B) This statement opens the file REPORT as a (F(2),A(M),X(M),F(2),A(I)); PRINT file. The specification PAGESIZE(55) indicates that each page should contain a In the first example, the value of NAME is maximum of 55 lines. An attempt to write inserted in the stream as a character on a page after 55 lines have already been string left-adjusted in a field of N written (or skipped) will raise the ENDPAGE characters; NUMBER is left-adjusted in a condition. The standard system action for field of N-4 characters; and CITY is the ENDPAGE condition is to skip to a new left-adjusted in a field of 10 characters. page, but the programmer can establish his In the second example, the first two own action through use of the ON statement. characters are assigned to M. The value of M is then taken to specify the number of The ENDPAGE condition is raised only characters to be assigned to STRING_A and once per page. Consequently, printing can also to specify the number of characters to be continued beyond the specified PAGESIZE be ignored before two characters are after the ENDPAGE condition has been raised assigned to I, whose value then is used to the first time. This can be useful, for specify the number of characters to be example, if a footing is to be written at assigned to STRING_B. the bottom of each page. For example; ON ENDPAGF(REPORT) BEGIN; PRINT FILES PUT FILE(REPORT) SKIP LIST (FOOTING); PUT FILE(REPORT) PAGE; The PRINT attribute can be applied only to N = N + 1; a STREAM OUTPUT file. It indicates that PUT FILE(REPORT) LIST the data in the file is ultimately intended ('PAGE '||N); to be printed (although it may first be PUT FILE(REPORT) SKIP (3); written on a medium other than the printed END; page). The first data byte of each record of a PRINT file is reserved for an ASA Assume that REPORT has been opened with printer control character; the compiler PAGESIZE(55), as shown in the previous causes the control characters to be example. When an attempt is made to write inserted automatically when statements on line 56 (or to skip beyond line 55), the containing the control options and format ENDPAGE condition will arise, and the begin items PAGE, SKIP, and LINE are executed. block shown here will be executed. The first PUT statement specifies that a line The layout of a PRINT file can be is to be skipped, and the value of FOOTING, controlled by the use of the options and presumably a character string, is to be format items listed in Figure 9-3. (Note printed on line 57 (when FNDPAGE arises, that LINESIZE, SKIP, and COLUMN can also be the current line is always PAGESIZE+1). used for non-PRINT files.) LINESEZE and The second PUT statement causes a skip to PAGESIZE establish the dimensions of the the next page, and the ENDPAGE counter is printed area of the page, excluding automatically reset for the new page. The headings and footings. The LINESIZE option page number is incremented, and the specifies the maximum number of characters character string 'PAGE' is concatenated to be included in each printed line; if it with the new page number and printed. The is not specified for a PRINT file, a final PUT statement causes three lines to default value of 120 characters is assumed be skipped, so that the next printing will (but there is no default for a non-PRINT be on line 4. Control returns from the file). The PAGESIZE option specifies the begin block to the PUT statement that maximum number of lines to appear in each caused the ENDPAGE condition, and the data printed page; if it is not specified, a is printed. Any SKIP option specified in default value of 60 lines is assumed. that statement is ignored, however. Chapter 9: Stream-Oriented Transmission 113 1Can also be used with non-PRINT files: see "Options of Transmission Statements" and "Control Format Items," above, and "Line Size and Record Format," below. •Figure 9-3. Options and Format Items for Controlling Layout of PRINT Files Note that SIGNAL ENDPAGE is ignored if The options applicable to there is no ENDPAGE on-unit, since it may stream-oriented transmission are: not be possible for standard system action (start a new page) to occur (for example, [F(block-size[,record-size]) if the file has not been opened). {V|VS|VBS} (maximum-block-size The specification LINESIZE(110) [,maximum-record-size]) indicates that each line on the page can contain a maximum of 110 characters. An U(maximum-block-size) attempt to write a line greater than 110 characters will cause the excess characters [BUFFERS(n)] to be placed on the next line. CONSECUTIVE LEAVE Standard File SYSPRINT REWIND Unless the standard file SYSPRINT is The options may appear in any order and declared explicitly, it is always given the are separated by blanks, The options attribute PRINT. When the file is opened, themselves cannot contain blanks. a new page is initiated automatically. If the first PUT statement that refers to the The options are discussed below under file has the PAGE option, or if the first four headings: record format, buffer PUT statement includes a format list with allocation, data set organization, and PAGE as the first item, a blank page will volume disposition. The information appear. supplied by some of the options can alternatively be specified in DD statements or by default. The DD statement is described in IBM System/360 Operating The ENVIRONMENT Attribute System: PL/I(F) Programmer's Guide. The ENVIRONMENT attribute specifies information about the physical organization RECORD FORMAT of the data set associated with a file. The information is contained in a parenthesized option list; the general Although record boundaries are ignored in format is: stream-oriented transmission, record format is important when a data set is being ENVIRONMENT (option-list) created, not only because it affects the 114 amount of storage space occupied by the The record size specified for VS-format data set and the efficiency of the program records can exceed the block size; if that processes the data, but also because necessary the records are segmented, and the data set may later be processed by the segments are placed in consecutive record-oriented transmission. Having blocks. Each block can contain only one specified the record format, the programmer record or segment of a record, and each need not concern himself with records and contains two four-byte fields, one to blocks as long as he uses only specify the block length and the other the stream-oriented transmission; he can record or segment length. For example, if consider his data set as a series of the record format is specified as characters arranged in lines, and can use VS(80,200), a record that includes 180 the SKIP option or format item (and, for a bytes of data will appear in the data set PRINT file, the PAGE and LINE options and as two blocks of 80 bytes (8 control bytes format items) to select a new line. and 72 data bytes) and one block of 44 bytes (8 control bytes and 36 data bytes). Records can be in one of three formats: fixed-length, variable-length, or undefined-length. The block size and VBS-format differs from VS-format only record size are specified in number of in that each block contains as many records bytes. The block size must be stated or segments as it can accommodate; each (unless the records are unblocked and the block is, therefore, substantially the same record size is given by means of the size (although there can be a variation of LINESIZE option); if no record size or line up to four bytes, since each segment must size is specified, the records are assumed contain at least one byte of data). For to be unblocked (that is, each block example, a block might contain the last contains only one record). segment of one record, one or more complete Undefined-length records cannot be blocked; records, and the first segment of another therefore, the record size can be specified record. for fixed-length and variable-length records only. Blocking and deblocking of VS-format and VBS-format records are fixed-length and variable-length records known as spanned records because they can are handled automatically. start in one block and be continued in the next. But the programmer is concerned only Fixed-length records are blocked and with complete records; segmentation and deblocked in accordance with the specified reassembly are handled automatically. The block size and record size. The block size use of spanned records allows the must be an exact multiple of the record programmer to select a block size, size. independently of record size, that will combine optimum usage of external storage When variable-length records are space with maximum efficiency of written, deblocking information is transmission. automatically inserted into each record and block. Four bytes are prefixed to the data For undefined-length records, all in each record to specify deblocking processing of records is the responsibility information, including two bytes for the of the programmer. If a length total record size; a further four bytes are specification is included in the record, prefixed to the first record in each block, the programmer must insert it himself, and two of which specify the total block size. he must retrieve the information himself. Variable-length records can be in one of three formats: V-format, VS-format, or Note: 1. Record format, block size, and VBS-format. record size can be specified in the DCB parameter of a DD For V-format records, the programmer statement instead of in the must specify the maximum block size and, ENVIRONMENT attribute; the for blocked records, the maximum record relevant DCB subparameters are size; in each case, he must allow an RECFM, BLKSIZE, and LRECL. additional four bytes for the deblocking information. The record size must never 2. The record size for a PRINT file exceed the block size. (For example, if must include one byte for a the maximum data length anticipated is 120 printer control character. If bytes, a block size of not less than 128 record format, block size, and bytes must be specified, whether the record size are not specified records are blocked or not, since unblocked for a PRINT file, the following records are considered to be in blocks of default assumptions are made: one record each; if the records are blocked, the record size must not be less Record format V than 124 bytes, and must be at least four bytes less than the specified block size.) Record size 125 bytes Chapter 9: Stream-Oriented Transmission 115 Line Size and Record Format computing time to be overlapped, and it may help speed up processing, especially where the data set contains V-format or U-format The record size for a STREAM OUTPUT file records or where the amount of processing can be given in the LINESIZE option of an per record is irregular. Buffers are OPEN statement. For a non-PRINT file, the essential for the automatic blocking and value specified in the LINESIZE option is deblocking of records. the actual record size for fixed-length or undefined-length records, but does not The option BUFFERS(n) in the ENVIRONMENT include the four bytes for deblocking attribute specifies the number(n) of information in variable-length records. buffers to be allocated for a data set; For a PRINT file, the value specified in this number must not exceed 255 (or such the LINESIZE option is the actual length of other maximum as was established at system the printed line; it does not include the generation). If the number of buffers is printer control character. Thus the not specified or is specified as zero, two equivalent record size is one byte more buffers are assumed. than the line size for fixed-length or undefined-length records, and five bytes The number of buffers can be specified more for variable-length records. in the BUFNO subparameter of a DD statement instead of in the ENVIRONMENT attribute. If the records are unblocked, it is not necessary to specify a block size. If the records are blocked, the block size must be compatible with the record size: for DATA SET ORGANIZATION fixed-length records, it must be an exact multiple of the record size; for variable-length (VB-format) records, it The organization of a data set determines must be at least four bytes larger than the how data is recorded in the data set, and maximum record size. how the data is subsequently retrieved so that it can be transmitted to the program. If neither line size nor block size are The F Compiler recognizes three data set specified for a PRINT file, a default line organizations, CONSECUTIVE, INDEXED, and size of 120 characters is applied; there is REGIONAL. A data set that is to be no default line size for non-PRINT files. accessed by stream-oriented transmission must have CONSECUTIVE organization; since this is the default for data set organization, it need not be specified at BUFFER ALLOCATION all for a STREAM file. The records in a CONSECUTIVE data set A buffer is an internal storage area that are arranged sequentially in the order in is used for the intermediate storage of which they were written; they can be data transmitted to and from a data set. retrieved only in the same order (unless The use of buffers allows transmission and record-oriented transmission is used). 116 | After the data set has been created, the volume is reached, or when a data set on a associated file can be opened for input (to magnetic tape volume is closed. The LEAVE read the data), or for output (to extend option prevents the tape from being the data set by adding records at the end, rewound. The REWIND option allows the or to replace the contents of the data set action at end of volume or on closing of a by new data: the effect of using an OUTPUT data set to be controlled by the DISP file to process an existing data set parameter of the associated DD statement. depends on the DISP parameter of the The effects of the options are summarized associated DD statement). in Figure 9-4, which also indicates whether an input/output channel is kept busy during the repositioning operation. VOLUME DISPOSITION The volume disposition options allow the programmer to specify the action to be taken when the end of a magnetic tape T ENVIRONMENT 1 DISP | Positioning of tape Positioning of tape option 1 subparameter | on closing of file at end of volume I LEAVE Multi-volume data No repositioning. sets: (Channel free) Wound on to end of current volume'. Other data sets: Wound on to end of data set'. (Channel busy in each case) REWIND | PASS Wound on to end of No repositioning. data set'. | (Channel free) (Channel busy) 1 KEEP Rewound to beginning of volume and CATLG unloaded. | UNCATLG (Channel free) | DELETE Rewound to beginning of volume but not unloaded. (Channel free) F Both LEAVE t REWIND is ignored. I and REWIND Neither LEAVE | 1 Rewound to beginning' Rewound to beginning ncr REWIND | of last data set. | of last data set. (Channel busy) | (Channel busy) 'Repositioned at beginning of data set for a BACKWARDS file. •Figure 9-5. Effect of LEAVE and REWIND Options Chapter 9: Stream-Oriented Transmission 117 Chapter 10: Record-Oriented Transmission Introduction The READ Statement This chapter describes the input and output The READ statement can be used with any statements used in record-oriented INPUT or UPDATE file. It causes a record transmission, which is one of two types of to be transmitted from the data set to the data transmission used for input and output program, either directly to a variable or in PL/I. Those features of PL/I that apply to a buffer. In the case of blocked equally to record-oriented and records, the READ statement causes a record stream-oriented transmission, including to be transferred from a buffer to the files, file attributes, and opening and variable; consequently, every READ closing files, are described in Chapter 8, statement may not cause actual data which forms a general introduction to this transmission from the input device. chapter and Chapter 9. In record-oriented transmission, data in The WRITE Statement a data set is considered to be a collection of records recorded in any format acceptable to the computer. No data The WRITE statement can be used with any conversion is performed during OUTPUT file, DIRECT UPDATE file, but not record-oriented transmission: on input, the with a SEQUENTIAL UPDATE file. It causes a READ statement causes a single record to be record to be transmitted from the program transmitted to a program variable exactly to the data set. For unblocked records, as it is recorded in the data set; on transmission may be directly from a output, the WRITE, REWRITE, or LOCATE variable or from a buffer. For blocked statement causes a single record to be records, the WRITE statement causes a transmitted from a program variable exactly logical record to be placed into a buffer; as it is recorded internally. Although only when the blocking of the record is data is actually transmitted to and from a complete is there actual data transmission data set in blocks, the statements used in to the output device. record-oriented transmission are concerned only with records; the records are blocked and deblocked automatically. The REWRITE Statement Data Transmission Statements The REWRITE statement causes a record to be replaced in an UPDATE file. For SEQUENTIAL UPDATE files, the REWRITE statement The following is a general description of specifies that the last record read from the record-oriented data transmission the file is to be rewritten; consequently a statements; they are described in detail in record must be read before it can be Part II, Section J, "Statements." rewritten. For DIRECT UPDATE files, any record can be rewritten whether or not it The variables involved in has first been read. record-oriented transmission must be unsubscripted, of level 1 (element and array variables not contained in structures are of level 1 by default), and may be of The LOCATE Statement any storage class. The variables cannot be parameters or defined variables. They can be label, pointer, or event variables, but The LOCATE statement can be used only with such data may lose its validity in a BUFFERED OUTPUT SEQUENTIAL or TRANSIENT transmission. file. It allocates storage within an output buffer for a based variable, setting There are four statements that actually a pointer to the location in the buffer as cause transmission of records to or from it does so. This pointer can then be used external storage. They are READ, WRITE, to refer to the allocation so that data can LOCATE, and REWRITE. A fifth statement, be moved into the buffer. The record is the DELETE statement, is used to delete written out automatically, during execution records from an UPDATE file. The of a subsequent WRITE or LOCATE statement attributes of the file determine which for the file, or when the file is closed. statements can be used. 118 The DELETE Statement The INTO Option The DELETE statement specifies that a The INTO option can be used in the READ record in an UPDATE file be deleted. (The statement for any INPUT or UPDATE file. implementation does not erase the record The INTO option specifies a variable to when a DELETE statement is executed, but which the logical record is to be assigned. flags it as "deleted.") READ FILE (DETAIL) INTO (RECORD 1); The UNLOCK Statement This specifies that the next sequential record is to be assigned to the variable The UNLOCK statement does not cause data to RECORD_1. be transmitted, but is used to unlock a record in an EXCLUSIVE DIRECT UPDATE file. When a record is read from a DIRECT UPDATE Note that the INTO option can name an file, it may subsequently be rewritten or element string variable of varying length; deleted to complete the updating operation; thus it is possible to read a record whose if the file is EXCLUSIVE, the read length is unknown to the PL/I programmer, operation automatically locks the record to and is not contained in the data. The prevent interference by other tasks during current length of the string is set to the this process. The UNLOCK statement makes length of the record. The LENGTH built-in the specified record available to tasks function can be used to find the length of other than that for which the locking READ the record. statement was issued; it therefore provides an alternative means of completing the updating operation. For further information see "Sharing Files between Tasks" in Chapter 15. The FROM Option The FROM option must be used in the WRITE OPTIONS OF TRANSMISSION STATEMENTS statement for any OUTPUT or DIRECT UPDATE file. It can also be used in the REWRITE statement for any UPDATE file. The FROM Options that are allowed for option specifies the variable from which record-oriented data transmission the record is to be written. If this statements differ according to the variable is a string of varying length, the attributes of the file and the current length of the string determines the characteristics of the associated data set. size of the record. Lists of all of the allowed combinations for each type of file are given in Figures For files other than DIRECT UPDATE or 10-5, 10-6, and 10-7, later in this SEQUENTIAL UNBUFFERED UPDATE files, the chapter. FROM option can be omitted from a REWRITE statement. If the last record was read by Each option consists of a keyword a READ statement with the INTO option, followed by a value, which is a file name, REWRITE without FROM has no effect on the a variable, or an expression. This value record in the data set; but if the last must always be enclosed in parentheses. In record was read by a READ statement with any statement, the options may appear in the SET option, the record will be updated, any order. in the buffer, by whatever assignments were made. WRITE FILE (MASTER) FROM (MAS_REC); The FILE Option REWRITE FILE (MASTER) FROM (MAS_REC); The FILE option must appear in every Both statements specify that the value of record-oriented statement. It specifies the variable MAS_REC is to be written into the name of the file upon which the the file MASTER. In the case of the WRITE operation is to take place. It consists of statement, it specifies a new record in a the keyword FILE followed by the file name SEQUENTIAL OUTPUT file. The REWRITE enclosed in parentheses. An example of the statement specifies that MAS_REC is to FILE option is shown in each of the replace the last record read from a statements in this section. SEQUENTIAL UPDATE file. Chapter 10: Record-Oriented Transmission 119 The SET Option READ FILE (STOCK) INTO (ITEM) KEY (STKEY); The SET option can be used with a READ statement or a LOCATE statement. It This statement specifies that the record specifies that a named pointer variable is identified by the character-string value of to be set to point to the location in the the variable STKEY is to be assigned to the buffer into which data has been moved variable ITEM. during the READ operation, or which has been allocated by the LOCATE statement. READ FILE (LIST) SET (P); This statement specifies that the value of The KEYFROM and KEYTO Options the pointer variable P is to be set to the location in the buffer of the next sequential record. The KEYFROM and KEYTO options apply only to KEYED files associated with data sets of INDEXED or REGIONAL organization, or to The IGNORE Option TRANSIENT files. Each option consists of the keyword KEYFROM or KEYTO followed by a parenthesized expression. For KEYFROM, the The IGNORE option can be used in a READ expression may be a character-string statement for any SEQUENTIAL INPUT or constant, a variable, or any other element UPDATE file. It includes an expression expression; if necessary, the expression is whose integral value specifies a number of evaluated and converted to a character records to be skipped over and ignored. string. For KEYTO, the expression must be a character-string variable. The rules READ FILE (IN) IGNORE (3); governing the lengths of the character strings and what they represent are This statement specifies that the next discussed below, under "INDEXED three records in the file are to be Organization" and "REGIONAL Organization" skipped. (except for TRANSIENT files, which are discussed under "Teleprocessing.") If a READ statement includes none of the options INTO, SET, and IGNORE, IGNORE(1) is The KEYFROM option specifies the assumed. location within the data set where the record is to he written, or (for TRANSIENT files) the terminal or process queue to which the message or record is to be The KEY Option transmitted. It can be used in a WRITE statement for a RECORD OUTPUT or DIRECT UPDATE file, or in a LOCATE statement. The KEY option applies only to KEYED files associated with data sets of INDEXED or WRITE FILE (LOANS) FROM (LOANREC) REGIONAL organization. (The types of data KEYFROM (LOANNO); set organization applicable to record-oriented transmission are discussed This statement specifies that the value of under "Data Set Organization," below.) The LOANREC is to be written as the next record option consists of the keyword KEY followed in the file LOANS, and that the value of by a parenthesized expression, which may be LOANNO is to be used as the key. a character-string constant, a variable, or any other element expression; if necessary, The KEYTO option specifies the name of the expression is evaluated and converted the variable to which the key (or terminal to a character string. The rules governing identifier, if the file is TRANSIENT) of the length of the character string and what the record being read is to be assigned. it represents are discussed below under It can be used in a READ statement for a "INDEXED Organization" and "REGIONAL SEQUENTIAL INPUT, SEQUENTIAL UPDATE, or Organization." TRANSIENT INPUT file. The KEY option identifies a particular READ FILE (DETAIL) INTO (INVTRY) record. It can be used in a READ statement KEYTO (KEYFLD); for an INPUT or UPDATE file, or in a REWRITE or DELETE statement for a DIRECT This statement specifies that the next UPDATE file. (The KEY option cam be used record in the file DETAIL is to be assigned in a READ statement for a SEQUENTIAL file to the variable INVTRY, and that the key of only if the associated data set has INDEXED the record is to be assigned to the organization.) variable KEYFLD. 120 The EVENT Option opening of the file, and if the UNDEFINEDFILE condition should arise because of that implicit opening, the The EVENT option is specified with the interrupt will occur at the time the keyword EVENT followed by the parenthesized UNDEFINEDFILE condition is raised. Only name of an event variable. (The appearance the four conditions TRANSMIT, KEY, RECORD, of a name in the EVENT option constitutes a and ENDFILE can be synchronized by the WAIT contextual declaration of an event statement. variable.) The option can appear in any READ, WRITE, REWRITE, or DELETE statement for an UNBUFFERED file. Once a statement containing an EVENT option has been executed, the event The EVENT option specifies that the variable named in the option is considered input or output operation is to take place to be active; while it is active, the event asynchronously (i.e., while other variable cannot be specified again in an processing continues) and that record I/O EVENT option. The event variable becomes interrupts (except for UNDEFINEDFILE) are inactive again only after execution of the not to occur until a WAIT statement, corresponding WAIT statement. specifying the same event variable, is executed by the same task. For example: An input/output event should be waited READ FILE (MASTER) INTO (REC_VAR) for only by the task that initiated the EVENT (RECORD 1); input/output operation. • The EVENT option is also used with the WAIT (RECORD_1); CALL statement to specify asynchronous execution of procedures: see Chapter 17, In this example, when the READ statement is "Multitasking." executed, the input operation is started. As soon as the input operation is commenced, in-line processing continues. The EVENT option is implemented for No I/O interrupt for RECORD, TRANSMIT, KEY, RECORD input/output statements used as or ENDFILE conditions will take place until follows: the WAIT statement is executed. If, when the WAIT statement is executed, the input operation is not complete, and if none of Access Data Set Organization the four conditions is raised, in-line processing stops, but the operation continues. When the operation is SEQUENTIAL CONSECUTIVE successfully completed, processing UNBUFFERED REGIONAL continues with the next statement following the WAIT statement. If any of the four DIRECT CONSECUTIVE INDEXED conditions arise during execution of the or REGIONAL READ statement, an interrupt will occur when the WAIT statement is executed. Note: The EVENT option should not be used On-units will be entered in the order in on a WRITE statement if V or U format which the interrupts occur (normally, records are being added to a REGIONAL(3) TRANSMIT or ENDFILE, KEY, RECORD). Then data set which is being accessed in a upon normal return from all of the on-units direct update mode. thus entered, processing continues with the next statement following the WAIT statement. Note that although the EVENT option The NOLOCK Option specifies asynchronous processing, it does not specify that interrupts will be caused asynchronously; none of the four conditions The NOLOCK option can be used in a READ can cause an interrupt until they are statement that refers to an EXCLUSIVE file. synchronized with processing by the WAIT It specifies that the record accessed by statement. the READ statement should not be locked (i.e., it will continue to be available to Other interrupts can occur, however. tasks other than that which issued the READ Any condition that arises during the statement). in-line processing will, of course, cause an interrupt if it is enabled. In For further information, refer to addition, if the I/O statement containing "Sharing Files between Tasks" in Chapter the EVENT option should cause implicit 15. Chapter 10: Record-Oriented Transmission 121 Processing Modes and FROM options can be of any storage class. Record-oriented transmission offers the programmer alternative methods of handling Consider the following example, which is his data. He can process data within the illustrated in Figure 10-1: storage area allocated to his program; this is termed the move mode because the data is NEXT: READ FILE(IN) INTO(DATA); actually moved into or out of program storage either directly or via a buffer. Alternatively, the programmer can process his data while it remains in a buffer (that WRITE FILE (OUT) FROM (DATA); is, without moving it into the storage area GO TO NEXT; allocated to his program); this is termed the locate mode, because the execution of a The first time the READ statement is data transmission statement merely executed, a block is transmitted from the identifies the location of the storage data set associated with the file IN to an allocated to a record in the buffer. The input buffer, and the first record in the locate mode is applicable only to BUFFERED block is assigned to the variable DATA; SEQUENTIAL or TRANSIENT files. Which mode further executions of the READ statement is used is determined by the data assign successive records from the buffer transmission statements and options used by to DATA. When the buffer is empty, the the programmer. next READ statement causes a new block to be transmitted from the data set. The WRITE statement is executed in a similar manner, building physical records in an MOVE MODE output buffer and transmitting them to the data set associated with the file OUT each time the buffer is filled. In the move mode, a READ statement causes a record to be transferred from external The move mode may be simpler to use than storage to the variable named in the INTO the locate mode since there are no buffer option (via an input buffer if a BUFFERED alignment problems. Furthermore, it can file is used); a WRITE or REWRITE statement result in faster execution when there are causes a record to be transferred from the numerous references to the contents of the variable named in the FROM option to same record, because of the overhead external storage (perhaps via an output incurred by the indirect addressing buffer). The variables named in the INTO technique used in locate mode. 122 Figure 10-1. Input and Output:Move Mode Chapter 10: Record-Oriented Transmission 123 LOCATE MODE buffer; any reference to the variable DATA or to any other based variable qualified by the pointer P will then in effect be a Locate mode requires the use of based reference to this first record. Further variables. A based variable is effectively executions of the READ statement set the overlaid on the data in the buffer, and pointer variable P to point to succeeding different based variables can be used to records in the buffer. When the buffer is access the same data by associating the empty, the next READ statement causes a new same pointer with each one; thus the same block to be transmitted from the data set. data can be interpreted in different ways. Locate mode can also be used to read self-defining records, in which information It is doubtful whether the use of locate in one part of the record is used to mode for both input and output in the above indicate the structure of the rest of the example would result in increased record; for example, this information could efficiency. An alternative would be to use be a count of the number of repetitions of move mode for input and locate mode for a subfield, or a code identifying which one output, for example: of a class of structures should be used to interpret the record. DCL DATA BASED(P); A READ statement causes a block of data to be transferred from the data set to an NEXT: LOCATE DATA FILE(OUT); input buffer, if necessary, and then sets READ FILE(IN) INTO(DATA); the pointer variable named in the SET option to point to the location in the buffer of the next record; the data in the record can then be processed by reference GO TO NEXT; to the based variable associated with the pointer variable. The record is available Each execution of the LOCATE statement only until the execution of the next READ reserves storage in an output buffer for a statement that refers to the same file. new allocation of the based variable DATA and sets the pointer variable P to point to Locate mode frequently provides faster this storage. The first execution of the execution than move since there is less READ statement causes a block to be movement of data, and less storage may be transmitted from the data set associated required. But it must be used carefully; with the file IN to an input buffer, and in particular, the programmer must be aware the first record in the block to be of how his data will be aligned in the assigned to the first allocation of DATA; buffer and how structured data will be subsequent executions of the READ statement mapped; structure mapping and data assign successive logical records to the alignment are discussed in Part II, Section current allocation of DATA. When the input K. buffer is empty, the next READ statement causes a new block to be transmitted from Figure 10-2 illustrates the following the data set. Each record is available for example, which uses locate mode for input processing during the period between the and move mode for output: execution of the READ statement and the next execution of the LOCATE statement. DCL DATA BASED(P); When no further space is available in the output buffer, the next execution of the LOCATE statement causes a block to be NEXT: READ FILE(IN) SET(P); transmitted to the data set associated with the file OUT, and a new buffer to be allocated. WRITE FILE(OUT) FROM(DATA); Note that, in each of the foregoing GO TO NEXT; examples, if the data set accessed in the move mode had had unblocked records and the The first time the READ statement is associated file had been declared executed, a block is transmitted from the UNBUFFERED, movement of data in internal data set associated with the file IN to an storage may have been unnecessary; if input buffer, and the pointer variable P is possible, each record would have been read set to point to the first record in the into and written from the same buffer. 124 •Figure 10-2. Locate Mode Input, Move Mode Output Chapter 10: Record-Oriented Transmission 125 The ENVIRONMENT Attribute format. The information supplied by some of the options can alternatively be specified in a DD statement or by default. The ENVIRONMENT attribute specifies The DD statement is described in IBM information about the physical organization System/360 Operating System: PL/I(F) of the data set associated with a file. Programmer's Guide. The information is contained in a parenthesized option list; the general format is: RECORD FORMAT ENVIRONMENT (option-list) The options applicable to Logical records can appear in one of three record-oriented transmission, with the formats: fixed-length (F-format), exception of teleprocessing applications, variable-length (V-format,VS-format, and are: VBS-format), or undefined-length (U-format). The block size and record size F(block-size[,record-size]){V|VS|VBS}(maximum-block-size are specified in number of bytes. The block size must always be stated; if no [,maximum-record-size]) record size is specified, the records are U(maximum-block-size) assumed to be unblocked (that is, each block contains only one record). [BUFFERS(n)] Undefined-length records cannot be blocked; therefore, the record size can be specified CONSECUTIVE for fixed-length and variable-length INDEXED records only. Blocking and deblocking of REGIONAL(1) fixed-length and variable-length records REGIONAL(2) are handled automatically. REGIONAL(3) Fixed-length records are blocked and LEAVE deblocked in accordance with the specified REWIND block size and record size. The block size must be an exact multiple of the record CTLASA size. CTL360 When variable-length records are [COBOL] written, deblocking information is automatically inserted into each record and [INDEXAREA[(index-area-size)]] block. Four bytes are prefixed to the data [NOWRITE] in each record to specify deblocking information, including two bytes for the [GENKEY] total record size; a further four bytes are prefixed to the first record in each block, [NCP(decimal-integer-constant)] two of which specify the total block size. Variable-length records can be in one of [TRKOFL] three formats: V-format, VS-format, or VBS-format. For teleprocessing applications (i.e., with TRANSIENT files), the above options do not For V-format records, the programmer apply, and one of the following options must specify the maximum block size and, must be specified: for blocked records, the maximum record size; in each case, he must allow an G(maximum-message-size) additional four bytes for the deblocking information. The record size must never R(maximum-record-size) exceed the block size. For example, if the maximum data length anticipated is 120 bytes, the maximum record size should be The options may appear in any order, and specified as 124 bytes, and a block size of are separated by blanks. The options not less than 128 bytes should be specified themselves cannot contain blanks. whether the records are blocked or not (unblocked records are considered to be in The options are discussed below under blocks of one record each). eleven headings: record format, buffer allocation, data set organization, volume The record size specified for VS-format disposition, carriage control, data records can exceed the block size; if interchange, data management optimization, necessary, the records are segmented, and key classification, asynchronous operations the segments are placed in consecutive limit, track overflow, and teleprocessing blocks. Each block can contain only one 126 record or segment of a record, and each The option BUFFERS(n) in the ENVIRONMENT contains two four-byte fields, one to attribute specifies the number (n) of specify the block length and the other the buffers to be allocated for a data set; record or segment length. For example, if this number must not exceed 255 (or such the record format is specified as other maximum as was established at system VS(80,200), a record that includes 180 generation). If the number of buffers is bytes of data will appear in the data set not specified for a BUFFERED file or is as two blocks of 80 bytes (8 control bytes specified as zero, two buffers are assumed. and 72 data bytes) and one block of 44 bytes (8 control bytes and 36 data bytes). The number of buffers can be specified in the BUFNO subparameter of a DD statement VBS-format differs from VS-format only instead of in the ENVIRONMENT attribute. in that each block contains as many records or segments as it can accommodate; each block is, therefore, substantially the same size (although there can be a variation of DATA SET ORGANIZATION up to four bytes, since each segment must contain at least one byte of data). For example, a block might contain the last The organization of a data set determines segment of one record, one or more complete how data is recorded in a data set volume, records, and the first segment of another and how the data is subsequently retrieved record. so that it can be transmitted to the program. Records are stored in and VS-format and VBS-format records are retrieved from a data set either known as spanned records because they can sequentially on the basis of successive start in one block and be continued in the physical positions, or directly by the use next. But the programmer is concerned only of keys specified in data transmission with complete records; segmentation and statements. These storage and retrieval reassembly are handled automatically. The methods provide PL/I with three general use of spanned records allows the data set organizations: CONSECUTIVE, programmer to select a block size, INDEXED, and REGIONAL; CONSECUTIVE is independently of record size, that will assumed by default if no data set combine optimum usage of external storage organization is specified. space with maximum efficiency of transmission. In a data set with CONSECUTIVE organization, records are organized solely For undefined-length records, all on the basis of their successive physical processing of records is the responsibility positions; records are retrieved only in of the programmer. If a length sequential order, and keys are not used. specification is included in the record, The records of an INDEXED data set are the programmer must insert it himself, and arranged in logical sequence according to he must retrieve the information himself. keys associated with each record; the records are arranged in ascending key Record format, block size, and record sequence, and indexes, created and size can be specified in the DCB parameter maintained by the system, are used for of a DD statement instead of in the retrieval of records. A data set with ENVIRONMENT attribute, but all three must REGIONAL organization is divided into appear together in one place or the other. regions, each of which is identified by a The relevant DCB subparameters are RECFM, region number and contains one or more BLKSIZE, and LRECL. records; for retrieval, the key supplied gives the region number at which the search for the record is to commence. CONSECUTIVE data sets are the simplest of the three types to create and use, and BUFFER ALLOCATION they have the advantage that less internal and external storage is required. However, records in a CONSECUTIVE data set can be A buffer is an internal storage area that updated only in their existing sequence, is used for the intermediate storage of and if records are to be inserted a new data transmitted to and from a data set. data set must be created. Even sequential The use of buffers allows transmission and updating is not supported for magnetic computing time to be overlapped, and it may tape. help speed up processing, especially where the amount of processing per record is Although an INDEXED data set must be irregular. Buffers are essential for the created sequentially, once it exists automatic blocking and deblocking of records can be retrieved, updated, added, records and for locate-mode transmission. or deleted at random. Sequential Chapter 10: Record-Oriented Transmission 127 processing of an INDEXED data set is slower They specify that the first character of a than that of a corresponding CONSECUTIVE record is to be interpreted as a control data set, because the records it contains character. are not necessarily arranged in physical sequence but are logically chained in order of ascending key values; furthermore, random access is less efficient for an 1. The CTLASA option specifies USASI INDEXED data set than for a REGIONAL data standard control characters. set, because the indexes must be searched to locate a record. Other disadvantages of an INDEXED data set are that it requires 2. The CTL360 option specifies IBM more internal and external storage space System/360 machine code control than either a CONSECUTIVE or a REGIONAL characters. data set, and that all volumes of a multi-volume data set must be mounted even for sequential processing. Although an INDEXED data set can contain blocked records, V-format and U-format records are not supported. Direct access of REGIONAL data sets is DATA INTERCHANGE more efficient than that of INDEXED data sets, but they have the disadvantage that sequential processing may present the The COBOL option facilitates the records in random sequence; the order of interchange of data between programs sequential retrieval is not necessarily written in PL/I and programs written in that in which the records were presented COBOL. It specifies that structures in the during sequential creation, nor need it be data set associated with the file will be related to the relative key values. mapped according to the COBOL(F) algorithm. Blocked records are not permitted in a The restrictions noted below apply to the REGIONAL data set, and only REGIONAL(3) can handling of a file with the COBOL option. accept V-format or U-format records. Figure 10-4 compares the data types used by COBOL with PL/I data types. The use of the record-oriented transmission statements to process data sets of each type of organization is discussed under appropriate headings below. A file with the COBOL option can be used only for READ INTO, WRITE FROM, and REWRITE FROM statements. The file name cannot be passed as an argument. VOLUME DISPOSITION If an ON-condition is raised during the The volume disposition options allow the execution of a READ statement, the variable programmer to specify the action to be named in the INTO option cannot be used in taken when the end of a magnetic tape the on-unit. If the completed INTO volume is reached, or when a data set on a variable is required, there must be a magnetic tape volume is closed. The LEAVE normal return from the on-unit. option prevents the tape from being rewound. The REWIND option allows the action at end of volume or on closing of a The EVENT option can be used only if the data set to be controlled by the DISP compiler can determine that the PL/I and parameter of the associated DD statement. COBOL structure maps are identical (i.e., The effects of the options are summarized all elementary items have identical in Figure 10-3, which also indicates boundaries). If the maps are not whether an input/output channel is kept identical, or if the compiler cannot tell busy during the repositioning operation. whether they are identical, an intermediate variable is created to represent the level 1 item mapped by the COBOL algorithm. The PL/I variable is assigned to the intermediate variable before a WRITE PRINTER/PUNCH CONTROL statement is executed, or assigned from it after a READ statement has been executed. Thus the input or output statement that The printer/punch control options CTLASA contains the EVENT option is not the one and CTL360 apply only to OUTPUT files that completes the operation; accordingly, associated with CONSECUTIVE data sets. the EVENT option is ignored. 128 Figure 10-3. Effect of LEAVE and REWIND options DATA MANAGEMENT OPTIMIZATION than 32,767, the compiler issues a warning message and ignores the option. The data management optimization options in the ENVIRONMENT attribute increase program The NOWRITE option can be specified only efficiency, in certain circumstances, when for DIRECT UPDATE files. It informs the DIRECT files are used to access INDEXED compiler that no records are to be added to data sets. the data set and that data management modules concerned solely with adding records are not required; it thus allows The INDEXAREA option improves the the size of the object program to be input/output speed of a DIRECT INPUT or reduced. DIRECT UPDATE file with INDEXED data set organization, by having the highest level of index placed in main storage. The "index area size" enables the programmer to limit the amount of main storage he is prepared to allow for an index area. The size, when specified, must be a decimal KEY CLASSIFICATION integer constant whose value lies within the range zero through 32,767. If an index area size is not specified, the highest The GENKEY (generic key) option applies level index is moved unconditionally into only to INDEXED data sets. It enables the main storage. If an index area size is programmer to classify keys recorded in a specified, the highest level index is held data set and to use a SEQUENTIAL KEYED in main storage, provided that its size INPUT or SEQUENTIAL KEYED UPDATE file to does not exceed that specified. If the access records according to their key specified size is less than zero or greater classes. Chapter 10: Record-Oriented Transmission 129 | In the following example, a key length | COBCL data type | PL/I data type of more than three bytes is assumed. DISPLAY |PICTURE with A land/or X picture DCL IND FILE RECORD SEQUENTIAL KEYED |characters UPDATE ENV (INDEXED GENKEY); |CHARACTER F COMPUTATIONAL Decimal length 1 to 4 FIXED BINARY READ FILE(IND) INTO(INFIELD) KEY ('ABC'); (precision < 16) • (integers only) 5 to 9 FIXED BINARY (precision >= 16) NEXT: READ FILE (IND) INTO (INFIELD); (integers only) 10 to 18 No equivalent | |COMPUTATIONAL-1 |FLOAT (n) BINARY GO TO NEXT; | (for n <= 21) ||FLOAT (n) DECIMAL The first READ statement causes the first | (for n 6) non-dummy record in the data set whose key F begins with 'ABC' to be read into INFIELD; |COMPUTATIONAL-2 |FLOAT (n) BINARY each time the second READ statement is | (for n > 21) executed, the non-dummy record with the |FIXED (n) DECIMAL | next higher key will be retrieved. | (for n > 6) Repeated execution of the second RFAD statement could result in reading records |COMPUTATIONAL-3 |FIXED DECIMAL from higher key classes since no indication | (precision and is given when the end of a key class is scale as in COBOL | reached. It is the responsibility of the | picture) programmer to check each key if he does not wish to read beyond the key class. Any •Figure 10-4. Equivalence of COBOL and PL/I subsequent execution of the first read Data statement would reposition the data set to the first record of the key class 'ABC'. A generic key is a character string that identifies a class of keys: all keys that If the data set contains no records with begin with the string are members of that keys in the specified class, or if all the class. For example; the recorded keys records with keys in the specified class 'ABCD', 'ABCE', and 'ABDF' are all members are dummy records; the KEY condition is of the classes identified by the generic raised and the data set is positioned to keys 'A' and 'AB'; and the first two are the first record. also members of the class 'ABC'; and the three recorded keys can be considered to be Note how the presence or absence of the unique members of the classes 'ABCD', GENKEY option affects the execution of a 'ABCE', and 'ABDF', respectively. READ statement that supplies a source key that is shorter than the key length The GENKEY option allows the programmer specified in the KEYLEN subparameter of the to start sequential reading or updating of DD statement. GENKEY causes the key to be an INDEXED data set from the first interpreted as a generic key, and the data non-dummy record that has a key in a set is positioned to the first non-dummy particular class; the class is identified record in the data set whose key begins by the inclusion of its generic key in the with the source key. If the GENKEY option KEY option of a READ statement.' Subsequent is not specified, a short source key is records can be read by READ statements padded on the right with blanks to the without the KEY option. No indication is specified key length, and the data set is given when the end of a key class is positioned to the record that has this reached. padded key (if such a record exists). The use of the GENKEY option does not 'Note that, although the first record affect the result of supplying a source key having a key in a particular class can be whose length is greater than or equal to retrieved by READ KEY, the actual key the specified key length. The source key, cannot be obtained unless the records have truncated on the right if necessary, embedded keys, since the KEYTO option identifies a specific record (whose key can cannot be used in the same statement as the be considered to be the only member of its KEY option. class). 130 ASYNCHRONOUS OPERATIONS LIMIT The PL/I programmer must have details of the message format in order to write a message processing program. In general, The asynchronous operations limit specifies the messages and records are treated as if the number of incomplete input/output they were V-format records. operations with the EVENT option that are allowed to exist for the file at one time. (See also "Teleprocessing," below) The decimal integer constant specified with NCP must have a value in the range 1 through 99; otherwise, 1 is assumed and an error message is issued. CONSECUTIVE Organization This option is equivalent to the NCP subparameter of the DCB parameter of the DD In a data set with CONSECUTIVE statement. organization, the records have no keys. When the data set is created, records are written consecutively in the order in which they are presented. The records can be retrieved only in the order in which they TRACK OVERFLOW were written or in the reverse order; therefore the associated file must have the SEQUENTIAL attribute. A CONSECUTIVE data The track overflow option specifies that set can have F-format, V-format, VS-format, records transmitted to a direct-access VBS-format, or U-format records. storage device can be written on overflow (VS-format and VBS-format records can be tracks if necessary. processed only by INPUT or OUTPUT files.) This option is equivalent to the Note the difference between the specification of "T" in the RECFM CONSECUTIVE option of the ENVIRONMENT subparameter of the DCB parameter of the DD attribute and the SEQUENTIAL attribute. statement. CONSECUTIVE specifies the physical organization of a data set; SEQUENTIAL specifies how a file is to be processed. A data set with CONSECUTIVE organization must TELEPROCESSING FORMAT be associated with a SEQUENTIAL file; but a data set with INDEXED or REGIONAL organization can be associated with either The teleprocessing format options are for a SEQUENTIAL or DIRECT file. use with TRANSIENT files only; teleprocessing is discussed later in this A CONSECUTIVE data set on magnetic tape chapter. One of these options must be can be read forwards or backwards. If the specified for TRANSIENT files; they cannot data set is to be read backwards, the be specified for DIRECT, SEQUENTIAL, or associated file must have the BACKWARDS STREAM files; and they cannot appear in attribute. If a data set is first read or conjunction with any other option of the written forwards and then read backwards in ENVIRONMENT attribute. the same program, the LEAVE option should be specified in the ENVIRONMENT attribute The maximum message size and maximum to prevent normal rewind when the file is record size are specified by decimal closed (or, with a multi-volume data set, integer constants. when volume-switching occurs). Variable-length records cannot be read G(maximum-message-size) specifies that backwards. execution of a data transmission statement will result in the movement of a complete Once a CONSECUTIVE data set has been message to or from the message queue. created, the file that accesses it can be opened for SEQUENTIAL INPUT or SEQUENTIAL R(maximum-record-size) specifies that OUTPUT; or it can be opened for SEQUENTIAL execution of a data transmission statement UPDATE, provided that the data set is on a will result in the movement of one record direct-access storage device. If it is of a message to or from the message queue. opened for OUTPUT, DISP=MOD must be specified in the DD statement; records can For both G and R formats, a buffer is then be added to the end of the data set. always used, and its length will depend on (If DISP=MOD is not specified, the data set the value of the specified decimal integer will be overwritten.) Figure 10-5 lists constant. The value that must be specified the data transmission statements and will depend on the message format as set up options that can be used to create and by the separate message control program. access a CONSECUTIVE data set. Chapter 10: Record-Oriented Transmission 131 Figure 10-5. Statements and options permitted for creating and accessing CONSECUTIVE data sets SEQUENTIAL UPDATE The REWRITE statement updates the record which was read by the second READ When a consecutive data set is accessed by statement. The record that was read by the a SEQUENTIAL UPDATE file, a record must be first statement cannot be rewritten after retrieved with a READ statement before it the second READ statement has been can be updated by a REWRITE statement; executed. however, every record that is retrieved need not be rewritten. A REWRITE statement will always update the last record read. Consider the following: Intervening READ statements are not permitted between a READ statement and a REWRITE statement that refer to the same record in a data set. For example, the following is not valid: 132 that record; its length cannot exceed 255 characters. A source key is the character-string value of the expression that appears in the KEY or KEYFROM option of a data transmission statement to identify the statement to which the record refers; for direct access of an INDEXED data set, each transmission statement must include a source key. The REWRITE statement will attempt to The length of the recorded keys in an update the last record read, which, in this INDEXED data set is defined by the KEYLEN instance, is the record read by the first subparameter of the DD statement that READ statement. (A record accessed by a defines the data set. If the length of a READ statement with the EVENT option is not source key differs from the specified considered to have been read until the length of the recorded keys, the source key corresponding WAIT statement has been is truncated on the right or padded with executed.) Because of the intervention of blanks on the right to the specified the second READ statement, the ERROR length. condition will be raised. The recorded keys in an INDEXED data set may be separate from, or embedded within, the logical records. If the keys are embedded within the records, the INDEXED Organization subparameter RKP must be included in the DD statement for the data set to give the A data set with INDEXED organization must location of the key. be on a direct-access device. Its records are arranged in logical sequence according The use of embedded keys obviates the to keys that are associated with each need for the KEYTO option during sequential record. A key is a character string that input, but the KEYFROM option is still usually represents an item within the required for output. (However, the data record, such as a part number, a date, or a specified by the KEYFROM option may be the name. Logical records are arranged in the embedded key itself.) In a data set with data set in ascending key sequence unblocked records, a separate recorded key according to the System/360 collating precedes each record, even when there is sequence. Indexes included in the data set already an embedded key; unblocked records are used by the operating system with embedded keys therefore require double data-management routines to locate a record space for key information. If the records when the key is supplied. V-format and are blocked, only the key of the last F-format records, blocked or unblocked, can record in each block is recorded separately be used in an INDEXED data set. in front of the block. Unlike CONSECUTIVE organization, INDEXED During the execution of a LOCATE or organization does not require every record WRITE statement that adds a record to a to be accessed in sequential fashion. An data set with embedded keys, the value of INDEXED data set must be created the expression in the KEYFROM option is sequentially; but, once it has been compared with the key embedded in the created, the associated file may have the record; if they do not match, the KEY attribute SEQUENTIAL or DIRECT as well as condition is raised. When the KEY INPUT or UPDATE. When the file has the condition is raised in this way by a LOCATE DIRECT attribute, records may be retrieved, statement, the record in the buffer cannot added, deleted, and replaced at random. be transmitted until the key embedded in the record has been changed to match the Figure 10-6 lists the data-transmission value given in the KEYFROM option; if the statements and options that can be used to file is closed1 before the key has been create and access an INDEXED data set. corrected, the key supplied in the KEYFROM option is automatically substituted for the embedded key, and the record is then transmitted. KEYS 1In these circumstances, the file could not There are two kinds of keys, recorded keys be closed explicitly (i.e., by a CLOSE and source keys. A recorded key is a statement) but only implicitly on character string that actually appears with termination of the task that opened the each record in the data set to identify file. Chapter 10: Record-Oriented Transmission 133 DUMMY RECORDS overwrite the first byte of the recorded key.) Note that the EVENT option is not supported for SEQUENTIAL access of INDEXED Records within an INDEXED data set are data sets. either actual records containing valid data or dummy records. A dummy record is During sequential access of an INDEXED identified by the constant (8)'1'B in its data set, it is possible to reposition the first byte. Dummy records can be inserted data set to a particular record by by the programmer, or they may be supplying a source key in the KEY option of substituted automatically for records that a READ statement, and to continue are deleted; they can be replaced by valid sequential reading from that record. (The data. If the subparameter OPTCD=L is associated file must have the KEYED included in the DD statement that defines attribute.) Repositioning can occur in the data set, dummy records are not either a forward or a backward direction. retrieved by READ statements. Thus, a READ statement that includes the KEY option will cause the record whose key is supplied to be read; a subsequent READ statement without the KEY option will cause CREATING A DATA SET the record with the next higher recorded key to be read. When an INDEXED data set is being created, The effect of supplying a source key the associated file must be opened for that is shorter than the recorded keys in SEQUENTIAL OUTPUT, and the records must be the data set differs according to whether presented in the order of ascending key or not the GENKEY option is specified in values. (If there is an error in the key the ENVIRONMENT attribute. In the absence sequence, the KEY condition will be of the GENKEY option, the source key is raised.) A DIRECT file cannot be used for padded on the right with blanks to the the creation of an INDEXED data set. length specified in the KEYLEN subparameter of the DD statement that defines the data Once an INDEXED data set has been set; and the record with this padded key is created, the file that accesses it can be read (if such a record exists). It the opened for SEQUENTIAL INPUT or UPDATE, or GENKEY option is specified, the source key for DIRECT INPUT or UPDATE. It cannot be is interpreted as a generic key, and the opened for OUTPUT. first record with a key in the class identified by this generic key is read. (Refer to "Key Classification;" above.) SEQUENTIAL ACCESS DIRECT ACCESS A SEQUENTIAL file that is used to access an INDEXED data set may be opened with either the INPUT or the UPDATE attribute. The A DIRECT file that is used to access an data transmission statements need not INDEXED data set may be opened with either include source keys, nor need the file have the INPUT or the UPDATE attribute. All the KEYED attribute. Sequential access is data transmission statements must include in order of ascending recorded-key values; source keys; the DIRECT attribute implies records are retrieved in this order, and the KEYED attribute. not necessarily in the order in which they were added to the data set. Dummy records A DIRECT UPDATE file can be used to are not retrieved if the DD statement that retrieve; add; delete, or replace records defines the data set includes the in an INDEXED data set according to the subparameter OPTCD=L. following conventions: The rules governing the relationship 1. Retrieval: If the DD statement that between the READ and REWRITE statements for defines the data set includes the a SEQUENTIAL UPDATE file that accesses an subparameter OPTCD=L; dummy records INDEXED data set are identical to those for are not made available by a READ a CONSECUTIVE data set (described above). statement. (The KEY condition is raised.) Additionally, records can be effectively deleted from the data set; a DELETE 2. Addition: A WRITE statement that statement marks a record as a dummy by includes a unique key causes a record putting (8)'1'B in the first byte. The to be inserted into the data set. If DELETE statement should not be used to the key is the same as the recorded process a data set with blocked records and key of a dummy record, the new record non-embedded keys. (The code (8)'1'B would replaces the dummy record. If the key 134 is the same as the recorded key of a (The code (8)'1'B would overwrite the record that is not marked as deleted, recorded keys.) or if there is no space in the data set for the record, the KEY condition 4. Replacement: The record specified by a is raised. source key in a REWRITE statement is replaced by the new record. Unblocked 3. Deletion: The record specified by the records can be replaced without being source key in a DELETE statement is read. If the data set contains retrieved, marked as deleted, and blocked records, a record must first rewritten into the data set. Deletion be retrieved with a READ statement and is possible only if OPTCD=L was then replaced with a REWRITE specified in the DD statement that statement; no further transmission defined the data set when it was statements for the same file may be created. If the data set has blocked issued between such a READ statement records with non-embedded keys and the corresponding REWRITE (RKP=0), records cannot be deleted. statement. Figure 10-6. Statements and options permitted for creating and accessing INDEXED data sets (Part 1 of 2) Chapter 10: Record-Oriented Transmission 135 1The complete file declaration would include the attributes FILE, RECORD, and ENVIRONMENT(INDEXED); if any of the options KEY, KEYFROM, and KEYTO is used, it must also include the attribute KEYED. For example: DECLARE MASTER FILE RECORD SEQUENTIAL OUTPUT BUFFERED KEYED ENVIRONMENT(INDEXED); By omitting the attributes that would be applied by default, this can be shortened to: DECLARE MASTER FILE RECORD KEYED ENVIRONMENT(INDEXED); 2If a SEQUENTIAL file associated with an INDEXED data set is declared UNBUFFERED, the compiler will change the declaration to BUFFERED. Thus, a declaration of UNBUFFERED gains nothing, but prevents the use of blocked records. Figure 10-6. Statements and options permitted for creating and accessing INDEXED data sets (Part 2 of 2) REGIONAL Organization data set, records being presented in the order of ascending region numbers; alternatively, direct access can be used, A data set with REGIONAL organization is in which records can be presented in random divided into regions, each of which is sequence and inserted directly into identified by a region number, and each of preformatted regions. Once a REGIONAL data which may contain one record or more than set has been created, it can be accessed by one record, depending on the type of a file with the attributes SEQUENTIAL or REGIONAL organization. The regions are DIRECT as well as INPUT or UPDATE. When numbered in succession, beginning with the file has the DIRECT attribute, records zero, and a record is accessed by can be retrieved, added, deleted, and specifying its region number, and perhaps a replaced at random. key, in a data transmission statement. A key is a character string that usually Records within a REGIONAL data set are represents an item such as a part number, a either actual records containing valid data date, or a name. or dummy records. The nature of the dummy records depends on the type of REGIONAL REGIONAL organization of a data set organization; the three types of REGIONAL permits the programmer to control the organization are described below. physical placement of records in the data set, and enables him to optimize the access Figure 10-7 lists the data transmission time for a particular application. Such statements and options that can be used to optimization is not available with create and access a REGIONAL data set. CONSECUTIVE or INDEXED organization, in which successive records are written either in strict physical sequence or in logical sequence depending on ascending key values; KEYS neither of these methods takes full advantage of the characteristics of direct-access storage devices. REGIONAL There are two kinds of keys, recorded keys data sets are confined to direct-access and source keys. A recorded key is a devices. character string that immediately precedes each record in the data set to identify A REGIONAL data set can be created in a that record; its length cannot exceed 255 similar manner to a CONSECUTIVE or INDEXED characters. A source key is the 136 character-string value of the expression 16777215. Only the characters 0 through 9 that appears in the KEY or KEYFROM option and the blank character are valid in the of a data transmission statement to source key; leading blanks are interpreted identify the record to which the statement as zeros. If more than eight characters refers. When a record in a REGIONAL data appear in the key; only the rightmost eight set is accessed, the source key represents are used as the region number; if there are a region number, and may also represent a fewer than eight characters; blanks recorded key. (interpreted as zeros) are inserted on the left. The length of the recorded keys in a REGIONAL data set is defined by the KEYLEN subparameter of the DD statement that defines the data set. Unlike the keys for Dummy Records INDEXED data sets, recorded keys in a REGIONAL data set are never embedded within the record. A dummy record in a REGIONAL(1) data set is identified by the constant (8)'1'B in its first byte. Although such dummy records are automatically inserted in the data set TYPES OF REGIONAL ORGANIZATION either when it is created or when a record is deleted, they are not ignored when the data set is read; the PL/I program must be There are three types of REGIONAL prepared to recognize them. Dummy records organization: can be replaced by valid data. 1. A REGIONAL(1) data set contains unblocked F-format records that do not have recorded keys. Each region in Creating Data Set the data set contains only one record; therefore, each region number corresponds with a relative record A REGIONAL(1) data set can be created position within the data set. either sequentially or by direct access. 2 A REGIONAL(2) data set contains When a SEQUENTIAL OUTPUT file is used to unblocked F-format records that have create the data set; records must be recorded keys. Each region in the presented in ascending order of region data set contains only one record. numbers; any region that is omitted from Direct access of a REGIONAL(2) data the sequence is filled with a dummy record. set employs the region number If there is an error in the sequence, or if specified in a source key to locate a duplicate key is presented, the KEY the required region. Once the region condition will be raised. When the file is has been located, a sequential search closed; any space remaining at the end of for space to add a record, or for a the data set is filled with dummy records. record that has a recorded key identical with that supplied in the If a DIRECT OUTPUT file is used to source key, can be made. create the data set, the whole of the space allocated to the data set is filled with 3. A REGIONAL(3) data set contains dummy records when the file is opened. unblocked F-format, V-format, or U-format records with recorded keys. Once a REGIONAL(1) data set has been Each region in the data set created, the file that accesses it can be corresponds with a track on a opened for SEQUENTIAL INPUT or UPDATE; or direct-access device, and can contain for DIRECT INPUT or UPDATE. It cannot be one or more records. Direct access of opened for OUTPUT. a REGIONAL(3) data set is similar to that for a REGIONAL(2) data set. Sequential Access REGIONAL(1) ORGANIZATION A SEQUENTIAL file that is used to access a REGIONAL(1) data set may be opened with In a REGIONAL(1) data set, since there are either the INPUT or for UPDATE attribute. no recorded keys, the region number serves The data transmission statements must not as the sole identification of a particular include the KEY option; but the file may record. The character-string value of the have the KEYED attribute, since the KEYTO source key must represent an unsigned option can be used. If the decimal integer that does not exceed character-string variable specified in the Chapter 10: Record-Oriented Transmission 137 KEYTO option has more than eight relative to other records is determined not characters, the value returned (the region by its recorded key, but by the region number) is padded on the left with blanks; number that is supplied in the source key if it has fewer than eight characters, it of the WRITE statement that adds the record is truncated on the left. to the data set. Sequential access is in the order of When a record is added to the data set, ascending region numbers; records are it is written with its recorded key in the retrieved in this order, and not first available space after the beginning necessarily in the order in which they were of the track that contains the region added to the data set. All records are specified. When a record is read, the retrieved, whether dummy or actual, and the search for a record with the appropriate PL/I program should be prepared to recorded key begins at the start of the recognize dummy records. track that contains the region specified. Unless it is limited by the LIMCT The rules governing the relationship subparameter of the DD statement that between READ and REWRITE statements for a defines the data set, the search for a SEQUENTIAL UPDATE file that accesses a record or for space to add a record REGIONAL(1) data set are identical with continues right through to the end of the those for a CONSECUTIVE data set (described data set and then from the beginning until above). the whole of the data set has been covered. The closer a record is to the specified region; the more quickly it can be accessed. Direct Access A DIRECT file that is used to access a REGIONAL(1) data set may be opened with Source Keys either the INPUT or the UPDATE attribute. All data transmission statements must include source keys; the DIRECT attribute The character-string value of the source implies the KEYED attribute. key can be thought of as having two logical parts, the region number and a comparison A DIRECT UPDATE file can be used to key. On output, the comparison key is retrieve; add, delete, or replace records written as the recorded key; on input; it in a REGIONAL(1) data set according to the is compared with the recorded key. following conventions: The rightmost eight characters of the 1. Retrieval: All records, whether dummy source key make up the region number, which or actual, are retrieved. The program must be an unsigned decimal integer that must be prepared to recognize dummy does not exceed 16777215. The region records. specification can include only the characters 0 through 9 and the blank 2. Addition: A WRITE statement character; leading blanks are interpreted substitutes a new record for the as zeros. A substring beginning at the existing record (actual or dummy) in left of the source key and containing the the region specified by the source number of characters specified in the key. KEYLEN subparameter of the DD statement that defines the data set is the comparison 3. Deletion: The record specified by the key; if the source key is shorter than the source key in a DELETE statement is specified key length, it is extended on the replaced by a dummy record. right with blanks. To retrieve a record, this substring must exactly match the 4. Replacement: The record specified by recorded key of the record. The comparison the source key in a REWRITE statement key can include the region number, in which whether dummy or actual, is case the source key and the comparison key overwritten. are identical; alternatively, part of the source key may be unused. The comparison key is always equal to KEYLEN; if the source key is longer than KEYLEN+8, the REGIONAL(2) ORGANIZATION characters in the source key between the comparison key and the region number are ignored. In a REGIONAL(2) data set, each record is identified by a recorded key that Consider the following examples of immediately precedes the record. The source keys (the character "b" represents a actual position of a record in the data set blank): 138 KEY ('JOHNbDOEbbbbbb12363251') require the subparameter OPTCD=L in the DD statement.) The rightmost eight characters make up the region specification. Assume that the associated DD statement has the Creating a Data Set subparameter KEYLEN=14. In retrieving a record, the search will begin with the beginning of the track containing region A REGIONAL(2) data set can be created number 12363251; and it will continue until either sequentially or by direct access. a record is found having the recorded key of JOHNbDOEbbbbbb. When a SEQUENTIAL OUTPUT file is used to create the data set, records must be If the subparameter were KEYLEN=22, the presented in ascending order or region search still would begin at the same place, numbers; any region that is omitted from but since the comparison and the source key the sequence is filled with a dummy record. are the same length, the search would be If there is an error in the sequence, for a record having the recorded key including an attempt to place more than one 'JOHNbDOEbbbbbb12363251'. record in the same region; the KEY condition will be raised. When the file is KEY ('JOHNbDOEbbbbbbDIVISIONb523bbbb35627') closed; any space remaining at the end of the data set is filled with dummy records. In this example, the rightmost eight characters contain three blanks; which are If a DIRECT OUTPUT file is used to interpreted as zeros. The search will create the data set; the whole of the space begin at record number 00035627. If allocated to the data set is filled with KEYLEN=14 is specified, the characters dummy records when the file is opened. DIVISIONb423b will be ignored. Records can be presented in random order, and no condition is raised by duplicate Assume that COUNTER is declared FIXED keys or duplicate region specifications. BINARY (21) and NAME is declared Each record is substituted for the first CHARACTER(15). The key might be specified dummy record on the track that contains the as : region specified in the source key; if there are no dummy records on the track; KEY (NAME || COUNTER) and an extended search is permitted by the LIMCT subparameter; the record is The value of COUNTER will be converted to a substituted for the first dummy record character string of eleven characters. encountered during the search. (Note that (The rules for conversion specify that a it is possible to place records with binary value of this length, when converted identical recorded keys in the data set.) to character, will result in a string of length 11, three blanks followed by eight Once a REGIONAL(2) data set has been decimal digits.) The value of the created; the file that accesses it can be rightmost eight characters of the converted opened for SEQUENTIAL INPUT or UPDATE; or string will be taken to be the region for DIRECT INPUT or UPDATE. It cannot be specification. Then if the keylength opened for OUTPUT. specification is KEYLEN=15, the value of NAME will be taken to be the comparison specification. Sequential Access Dummy Records A SEQUENTIAL file that is used to access a REGIONAL(2) data set may be opened with either the INPUT or the UPDATE attribute. A REGIONAL(2) data set can contain dummy The data transmission statements must not records which are recognizable by their include the KEY option, but the file may keys: the key of a dummy record has the have the KEYED attribute since the KEYTO constant (8) '1'B in its first byte. The option can be used. The KEYTO option first data byte of a dummy record contains specifies that the recorded key only is to the sequence number of the record on the be assigned to the specified variable. If track. the character-string variable specified in the KEYTO option has more characters than Dummy records can be replaced by valid are specified in the KEYLEN subparameter, data. They are inserted automatically the value returned (the recorded key) is either when the data set is created or when extended on the right with blanks; if it a record is deleted, and they are ignored has fewer characters than specified by when the data set is read. (Unlike INDEXED KEYLEN, the value returned is truncated on data sets, REGIONAL data sets do not the right. Chapter 10: Record-Oriented Transmission 139 Sequential access is in the order of 1. Each region number identifies a track ascending region numbers. Records are on the direct-access device that retrieved in this order, and not contains the data set; the region necessarily in the order in which they were number must not exceed 32767. added to the data set; the recorded keys do not affect the order of sequential access. 2. A region can contain one or more Dummy records are not retrieved. records. The rules governing the relationship 3. The data set can contain F-format, between READ and REWRITE statements for a V-format, or U-format unblocked SFQUENTIAL UPDATE file that accesses a records. Dummy records cannot be REGIONAL(2) data set are identical with inserted when a data set is created those for a CONSECUTIVE data set (described with V-format or U-format records above). because their lengths cannot be known before they are written; however, the operating system maintains a capacity record at the beginning of each track, Direct Access in which it records the amount of space available on that track. A DIRECT file that is used to access a Source keys for a REGIONAL(3) data set REGIONAL(2) data set may be opened with are interpreted exactly as those for a either the INPUT or the UPDATE attribute. REGIONAL(2) data set, and the search for a All data transmission statements must record, or for space to add a record; is include source keys; the DIRECT attribute conducted in a similar manner. implies the KEYED attribute. 1. Retrieval: Dummy records are not made available by a READ statement. The KEY condition is raised if an actual Dummy Records record with the specified recorded key is not found. Dummy records for REGIONAL(3) data sets 2. Addition: A WRITE statement with F-format records are identical with substitutes the new record for the those for REGIONAL(2) data sets. first dummy record on the track containing the region specified by the V-format and U-format dummy records are source key. If there are no dummy identified by the fact that they have dummy records on this track, and an extended recorded keys ((8)'1'B in the first byte). search is permitted by the LIMCT The four control bytes in each V-format subparameter, the new record replaces dummy record are retained; but otherwise the first dummy record encountered the contents of V-format and U-format dummy during the search. records are undefined. V-format and U-format dummy records are inserted in a 3. Deletion: The record specified by the data set only when a record is deleted; the source key in a DELETE statement is space they occupy cannot be used again. replaced by a dummy record. 4. Replacement: The record specified by the source key in a REWRITE statement Creating a Data Set must exist; a REWRITE statement cannot be used to replace a dummy record. A REGIONAL(3) data set can be created Note that if the data set contains either sequentially or by direct access. records with duplicate recorded keys, the record farthest from the beginning of the When a SEQUENTIAL OUTPUT file is used to data set may never be retrieved during create the data set; records must be DIRECT access. presented in ascending order of region numbers, but the same region number can be specified for successive records. If there is an error in the sequence, the KEY condition will be raised. If a track REGIONAL(3) ORGANIZATION becomes filled by records for which the same region number was specified, the region number is automatically incremented A REGIONAL(3) data set differs from a by one; an attempt to add a further record REGIONAL(2) data set (described above) only with the same region number will raise the in the following respects: KEY condition (sequence error). 140 If a DIRECT OUTPUT file is used to SEQUENTIAL UPDATE file that accesses a create the data set, the whole of the space REGIONAL(3) data set are identical with allocated to the data set is initialized those for a CONSECTIVE data set (described when the data set is opened; for F-format above). records, the space is filled with dummy records and dummy keys, and for V-format and U-format records, the capacity record for each track is written to indicate empty tracks. Records can be presented in random order, and no condition is raised by duplicate keys or duplicate region Direct Access specifications. If the data set has F-format records, each record is substituted for the first dummy record in A DIRECT file that is used to access a the region (track) specified in the source REGIONAL(3) data set may be opened with key; if there are no dummy records on the either the INPUT or the UPDATE attribute. track, and an extended search is permitted All data transmission statements must by the LIMCT subparameter, the record is include source keys; the DIRECT attribute substituted for the first dummy record implies the KEYED attribute. encountered during the search. If the data set has V-format or U-format records, the 1. Retrieval: Dummy records are not made new record is inserted on the specified available by a READ statement. The track, if space is available; otherwise, if KEY condition is raised if an actual an extended search is permitted, the new record with the specified recorded key record is inserted in the next available is not found. space. 2. Addition: In a data set with F-format records; a WRITE statement substitutes Once a REGIONAL(3) data set has been the new record for a dummy record in created, the file that accesses it can be the region (track) specified by the opened for SEQUENTIAL INPUT or UPDATE, or source key. If there are no dummy for DIRECT INPUT or UPDATE. It cannot be records on the specified track, and an opened for OUTPUT. extended search is permitted by the LIMCT subparameter, the new record replaces the first dummy record encountered during the search. If the data set has V-format or U-format Sequential Access records, a WRITE statement inserts the new record after all other records on the specified track, if space is A SEQUENTIAL file that is used to access a available; otherwise, if an extended REGIONAL(3) data set may be opened with search is permitted, the new record is either the INPUT or UPDATE attribute. The inserted in the next available space. data transmission statements must not include the KEY option, but the file may 3. Deletion: A record specified by the have the KEYED attribute since the KEYTO source key in a DELETE statement is option can be used. The KEYTO option replaced by a dummy record. The space specifies that the recorded key only is to occupied by an F-format record can be be assigned to the specified variable. If re-used; space occupied by V-format or the character-string variable specified in U-format records is not available for the KEYTO option has more characters than re-use. are specified in the KEYLEN subparameter, the value returned (the recorded key) is 4. Replacement: The record specified by extended on the right with blanks; if it the source key in a REWRITE statement has fewer characters than specified by must exist; a REWRITE statement cannot KEYLEN, the value returned is truncated on be used to replace a dummy record. the right. Note: 1. The EVENT option should be used Sequential access is in the order of with caution when V-format or ascending relative tracks. Records are U-format records are being added retrieved in this order, and not to a REGIONAL(3) data set. necessarily in the order in which they were added to the data set; the recorded keys do 2. If the data set contains records not affect the order of sequential access. with duplicate recorded keys, the Dummy records are not retrieved. record farthest from the beginning of the data set may The rules governing the relationship never be retrieved during DIRECT between READ and REWRITE statements for a access. Chapter 10: Record-Oriented Transmission 141 Figure 10-7. Statements and options permitted for creating and accessing REGIONAL data sets (Part 1 of 2) 142 1The complete file declaration would include the attributes FILE, RECORD, and ENVIRONMENT (INDEXED); if any of the options KEY, KEYFROM, and KEYTO is used, it must also include the attribute KEYED. For example: DECLARE MASTER FILE RECORD SEQUENTIAL OUTPUT BUFFERED KEYED ENVIRONMENT (REGIONAL(1)); By omitting the attributes that would be applied by default, this can be shortened to: DECLARE MASTER FILE RECORD KEYED ENVIRONMENT (REGIONAL(1)); Figure 10-7. Statements and options permitted for creating and accessing REGIONAL data sets (Part 2 of 2) program has access only to the main storage Teleprocessing queues, by means of a single intermediate buffer for each file.) The exact message The teleprocessing facilities of PL/I format depends on the MCP, but each message are provided by an extension of the basic will carry the terminal name with it. A record-oriented transmission facilities message may be a complete unit, or may with the addition of the TRANSIENT file consist of a number of records so that it attribute and the PENDING condition. The F can be split up for processing; the Compiler provides a communicating link ENVIRONMENT attribute is used to inform the between PL/I message processing programs compiler of the message format. The PL/I using these features and the QTAM (Queued programmer must have this message format Telecommunications Access Method) information to enable him to write the facilities of the operating system. message processing program. Figure 10-9, at the end of this section on teleprocessing, is a programming example designed to illustrate that the PL/I teleprocessing extension is a simple extension of the existing record-oriented transmission facilities, rather than to represent a typical user's message The "data set" associated with each processing program. TRANSIENT file is in fact an input or output message queue set up by the MCP. A A QTAM message control program 1 (MCP) READ statement for the file will take the handles messages originating from and next message (or the next record from the destined for a number of remote terminals, current message) from the associated queue, each of which is identified by a terminal assign the data part to the variable named name carried with the message. These in the INTO option (or set a pointer to messages are transmitted to and from the point to the data in the buffer), and save PL/I message processing program via queues the terminal name by assigning it to the in main storage. (These queues are variable named in the KEYTO option. (The supported by corresponding intermediate PENDING condition is raised if the input queues in a disk data set. The PL/I queue is empty when the READ statement is executed.) A WRITE or LOCATE statement will transmit the processed message or 1for more information about the message record to the output queue, using the control program, see IBM System/360 element expression specified in the KEYFROM Operating System: QTAM Message Control option to identify the destination terminal Program. or process queue. Chapter 10: Record-Oriented Transmission 143 The TRANSIENT Attribute The RECORD condition is raised in the same circumstances as for other types of transmission. (The messages and records The TRANSIENT attribute, which is an are treated as V-format records.) alternative to the DIRECT and SEQUENTIAL attributes, indicates that the contents of The ERROR condition is raised as for the data set associated with the file are other types of transmission; it is also re-established each time the data set is raised when the expression in the KEYFROM accessed. In effect, this means that option is missing or detectably invalid. records can be continually added to the Note that if the expression is data set by one program during the syntactically valid but does not represent execution of another program that a terminal name recognized by the MCP, the continually removes records from the data message may be lost in the system without set. Thus the data set can be considered indication. to be a continuous queue through which the records pass in transit between the message The PENDING condition can be raised only control program and the message processing during execution of a READ statement for a program. The queue is always accessed TRANSIENT file. It is raised when the sequentially. associated queue is empty; standard system action is to wait at the READ statement The data set associated with a TRANSIENT until a message is available. When the file differs from those associated with PENDING condition is raised, the value DIRECT and SEQUENTIAL files in that its returned by the ONKEY built-in function is contents are dynamic; reading a record a null string. removes it from the data set. Such a data set can never be created or accessed by a Note: When the R format option is specified DIRECT or SFQUENTIAL file. in the ENVIRONMENT attribute, a message is transmitted one record at a time. There is With the F Compiler, the TRANSIENT no ON-condition or other automatic means attribute can be specified only for RECORD for detecting the end of the message; the KEYED BUFFERED files with either the INPUT user is responsible for arrang ing the or the OUTPUT attribute. (Since the file indication of the end of the message must be BUFFERED, the EVENT option cannot (possibly by using the first record as a be used for teleprocessing operations.) header giving the necessary control The file must also have the ENVIRONMENT information.) attribute with one of the two teleprocessing format options (G and R); no other ENVIRONMENT options are allowed. Statements and Options For TRANSIENT INPUT files, the file name or title must be the name of a queue set up by the message control program. For The READ statement is used for input, with TRANSIFNT OUTPUT files, any name can be either the INTO option or the SET option; declared, since the file is reassociated the KEYTO option must be given. If the for each output operation with a queue message originates from a terminal; the determined by the terminal name; however, terminal name is assigned to the KEYTO the element expression specified in the option. If a processing program placed the KEYFROM option must have as its value a message on the process queue, the terminal recognized terminal or process queue name will be zeroes. In this case; the identification. Note that the DD PL/I Library assigns a blank field to the statements for both TRANSIENT INPUT and variable in the KEYTO option. If the TRANSIENT OUTPUT files are DD DUMMY terminal name is shorter than the statements, since the "data sets" are character-string variable named in the defined by the message control program and KEYTO option, it is padded on the right their association with the PL/I files is with blanks. If the KEYTO variable is a handled automatically by the system. varying-length string, its length is set to that of the terminal name. The terminal name should not be longer than the KEYTO Error Handling variable, but in any case will not be longer than 8 characters. The data part of the message or record is assigned to the The conditions that can be raised during variable named in the INTO option, or the teleprocessing transmission are TRANSMIT, pointer variable named in the SET option is RECORD, ERROR, and PENDING. set to point to the data in the buffer. The TRANSMIT condition can be raised Either the WRITE or the LOCATE statement only on input, and is as described for may be used for output; either statement other types of transmission. must have the KEYFROM option -- the first 144 eight characters of the value of the file name OUT has no significance outside KEYFROM expression are used to identify the the PL/I program. However, the file would destination terminal or process queue. The need the TRANSIENT, KEYED, and BUFFERED data part of the message is moved to the attributes, and the correct message format buffer from the variable named in the FROM in the ENVIRONMENT attribute. option of the WRITE statement; or, in the case of LOCATE, a pointer variable is set to point to the location of the data in the READ FILE(IN) SET(INPTR) KEYTO(TERM); buffer. The list of statements and options permitted for TRANSIENT files is given in WRITE FILE(OUT) FROM(MESSAGE) tabular form in Figure 10-8. Some examples KEYFROM(TERM): follow: READ FILE(IN) INTO(INREC) KEYTO(TERM); This example is similar to the previous one, except that locate mode input is used; the message data is processed in the input buffer, using the based variable MESSAGE, WRITE FILF(OUT) FROM(OUTREC) which has been declared with the pointer KEYFROM(TERM); variable INPTR. (The data of the message will be aligned on a doubleword boundary.) The above example illustrates the use of The WRITE statement moves the processed move mode in teleprocessing applications. data from the input to the output buffer; The buffer for file IN contains the next otherwise its effect is as described for message (or record from a message, the WRITE statement in the first example. depending on the message format) from the input queue. The input queue will also be named IN unless the file has been opened The technique used in this example would with a TITLE option specifying a different be useful in applications where the queue name. The message format will have differences between processed and been determined by the message control unprocessed messages were relatively program, and the file declaration for IN simple; since the maximum size of input and must include this information in the output messages would be the same. If the ENVIRONMENT attribute. length and structure of the output message could vary widely, depending on the text of The READ statement causes the message or the input message, locate mode output could record to be moved from the buffer into the be used to advantage; after the input variable INREC; if the buffer is empty when message had been read in, a suitable based the READ statement is executed (i.e., there variable could be located in the output are no messages in the queue), the PENDING buffer (using the LOCATE statement), where condition is raised, and, normally, further processing would take place. The execution will wait until a message is message would be transmitted immediately available. The name of the originating before execution of the next WRITE or terminal is assigned to TERM. LOCATE statement for the file. After processing, the message or record Note that although the EVENT option is is held in OUTREC. The WRITE statement not permitted; data transmission could be moves it to the output buffer, together overlapped with processing in an MVT with the value of TERM (which will still operating system by means of the PL/I contain the originating terminal name multitasking facilities described in unless another name has been assigned to it Chapter 15. For example, the read-in during processing). From the buffer, the routine could invoke the processing message will be automatically transmitted routines as subtasks; each subtask could to the correct queue for the destination independently invoke the write-out routine. terminal, as specified by the value of In this way, the next message would be read TERM. as soon as the last message had been passed on to a processing routine, instead of Since the output queue is determined waiting for the processing routine to from the destination terminal name, the finish. Chapter 10: Record-Oriented Transmission 145 Figure 10-8. Statements and options permitted for TRANSIENT files The program in Figure 10-9 handles two the data set (or from the last to the types of message. The format of the first if the BACKWARDS attribute has messages is a single character, 'D' or 'T' been specified). surrounded by blanks. The 'D' character causes the date to be returned to the inquiring terminal, and 'T' causes the time 2. A DIRECT file specifies that the data to be returned. Any other character is an set records may be accessed, created, error. Note that the DD statement for the or modified, in random order. The files IN and OUT would be DD DUMMY particular record of the data set to statements. be operated upon is identified by a key. In the example, each inquiry is fully serviced before control returns to 3. A data set that is accessed, created, GET MESSAGE to obtain the next message. or modified by a SEQUENTIAL file may Response could be greatly improved in an or may not have recorded keys. If it MVT system by use of the multitasking does, the keys can be ignored while facilities of PL/I. If the routines accessing sequentially, or they may be DATE_ROUTINE, TIME_ROUTINE, and ERROR were extracted from the data set or placed invoked as subtasks of CLOCK, control would into the data set by the KEYFROM and return to GET_MESSAGE as soon as the KEYTO options. In general, the most appropriate handling routine had been efficient way to create a data set invoked, rather than after it had finished. containing recorded keys is as a SEQUENTIAL OUTPUT file. It then can be accessed as a DIRECT file. Summary of Record-Oriented Transmission 4. SEQUENTIAL INPUT and SEQUENTIAL UPDATE files may be positioned to a particular record within the data set The following points cover the salient by a READ operation that specifies the features of record-oriented transmission: key of the desired record. Thereafter, successive READ statements 1. A SEQUENTIAL file specifies that the without the KEY option will access the data set records may be accessed, records sequentially. This kind of created, or modified, in a particular accessing may be used only if the data order, that is, from the first record set has INDEXED organization and if of the data set to the last record of the file has the KEYED attribute. 146 Figure 10-9. Teleprocessing Programming Example Chapter 10: Record-Oriented Transmission 147 5. Existing records of a data set in a for REGIONAL(1), an identifying key to SEQUENTIAL UPDATE file can be be recorded in the data set. rewritten, modified, ignored, or deleted. The DELETE statement used 8. Records of a SEQUENTIAL INPUT or with this type of file specifies that SEQUENTIAL UPDATE file can be skipped the last record read is to be over and ignored by use of the IGNORE deleted. 1 Operation with a DIRECT option of a READ statement. The UPDATE file, however, can specify expression of the IGNORE option which record is to be deleted by means specifies the number of records to be of a key; also, records can be added skipped. A READ statement in which to the data set by means of the WRITE only the FILE option appears indicates statement. An existing record in an that one record is to be skipped. UPDATE file can be replaced through use of a REWRITE statement. 9. Teleprocessing support is provided by an extension of the basic 6. When a file has the DIRECT UPDATE record-oriented transmission EXCLUSIVE attributes, it is possible facilities. TRANSIENT files are to protect individual records that are associated with queues of messages read from the data set. For an either incoming from or outgoing to EXCLUSIVE file, any READ statement remote terminals. Such files must be without a NOLOCK option automatically KEYED and BUFFERED, and the locks the record read. No other task ENVIRONMENT attribute must be used to operating upon the same file can specify the message format. TRANSIENT access a locked record until it is files can be accessed by READ, WRITE, unlocked by the locking task. Any and LOCATE statements, which cannot task referring to a locked record will have the EVENT option. wait at that point until the record is unlocked. A record can be explicitly unlocked by the locking task through execution of a REWRITE, DELETE, Examples of Declarations for RECORD Files UNLOCK, or CLOSE statement. Records are unlocked automatically upon completion of the locking task. The Following are examples of declarations of EXCLUSIVE attribute applies only to files, including the ENVIRONMENT attribute: the file and not the data set. Consequently, record protection is DECLARE FILE#3 INPUT DIRECT provided only if all tasks refer to ENVIRONMENT(V(328) REGIONAL(3)); the data set through use of the same file; if they refer to the same data This declaration specifies only three file set using different files, the attributes: INPUT, DIRECT, and ENVIRONMENT. protection does not apply. In Other implied attributes are FILE (implied addition, the data set to which by any of the attributes) and RECORD and reference is made by more than one KEYED (implied by DIRECT). Scope is task through the same file must be EXTERNAL, by default. The ENVIRONMENT opened by a parent of all these tasks. attribute specifies that the data set is of Note that a reference to a file the REGIONAL(3) organization and contains parameter and its associated argument unblocked varying-length records with a are references to the same file. maximum length of 328 bytes. Note that a maximum length record will contain only 320 7. A WRITE statement adds a record to a bytes of data to be used by the program, data set, while a REWRITE statement because 8 bytes are required for control replaces a record. Thus, a WRITE information in such V-format records. The statement may be used with OUTPUT KEY option must be specified in each READ files, and DIRECT UPDATE files, but a statement that refers to this file. REWRITE statement may be used with UPDATE files only. Moreover, for DECLARE INVNTRY UPDATE BUFFERED DIRECT files, a REWRITE statement uses ENVIRONMENT (F(100) the KEY option to identify the INDEXED BUFFERS(4)); existing record to be replaced; a WRITE statement uses the KEYFROM This declaration also specifies only three option, which not only specifies where file attributes: UPDATE, BUFFERED, and the record is to be written in the ENVIRONMENT. Implied attributes are FILE, data set, but also specifies, except RECORD, and SEQUENTIAL (the last two attributes are implied by BUFFERED). Scope is EXTERNAL, by default. The data set is 1If the DELETE statement is used with a of INDEXED organization, and it contains sequential file, the data set must have fixed-length records of 100 bytes each. INDEXED organization. Four buffers are to be allocated for use in 148 accessing the data set. Note that although OPEN FILE (INVNTRY) the data set actually contains recorded INPUT SEQUENTIAL KEYED; keys, the KEYTO option cannot be specified in a READ statement, since the KEYED This OPEN statement allows records to be attribute has not been specified. read with either the KEYTO or the KEYED option. Because the file is SEQUENTIAL and the data set is INDEXED, the data set is Note that for both of the above INDEXED, the data set may be accessed in a declarations, all necessary attributes are purely sequential manner; or, by means of a either stated or implied in the DECLARE READ statement with a KEY option, it may be statement. None of the attributes can be accessed randomly. A KEY option in a READ changed in an OPEN statement or in a DD statement with a file of this description statement. The second declaration might causes a specified record to be obtained. have been written: Subsequent READ statements without a KEY option access records sequentially, DECLARE INVNTRY beginning with the next record. ENVIRONMENT(F(100) INDEXED); DECLARE IN KEYED BUFFERED TRANSIENT With such a declaration, INVNTRY can be ENVIRONMENT (G(50)); opened for different purposes. It could, for example, be opened as follows: This declaration for a teleprocessing file specifies only four attributes. Implied OPEN FILE (INVNTRY) attributes are FILE and RECORD (implied by UPDATE SEQUENTIAL BUFFERED; either KEYED or BUFFERED). The INPUT attribute would be applied by default. The With this OPEN statement, the file data set associated with the file would be attributes would be the same as those a queue named IN (unless the file is opened specified (or implied) in the DECLARE with a TITLE option specifying a different statement in the second example above (the queue name). Input messages will be number of buffers would have to be stated transmitted as complete units; as specified in the associated DD statement). The file by the ENVIRONMENT attribute, with a might be opened in this way, then closed, maximum length of 50 bytes. The queue can and then later opened with a different set be accessed sequentially by a READ of attributes, for example: statement with the KEYTO option. Chapter 10: Record-Oriented Transmission 149 Chapter 11: Editing and String Handling The data manipulation performed by the If the assigned string is shorter than arithmetic, comparison, and bit-string the length declared for the receiving operators are extended in PL/I by a variety string variable, the assigned string is of string-handling and editing features. extended on the right either with blanks, These features are specified by data in the case of a character-string variable, attributes, statement options, built-in or with zeros, in the case of a bit-string functions, and pseudo-variables. variable. Assume SUBJECT still has the attributes CHARACTER (10). Then the The following discussions give general following two statements assign equivalent descriptions of each feature, along with values to SUBJECT: illustrative examples. SUBJECT = 'PHYSICS'; SUBJECT = 'PHYSICSbbb'; Editing by Assignment The letter b indicates a blank character. Let CODE be a bit-string variable with The most fundamental form of editing the attributes BIT(10). Then the following performed by the assignment statement two statements assign equivalent values to involves converting the data type of the CODE: value on the right side of the assignment symbol to conform to the attributes of the CODE = '110011'B; receiving variable. Because the assigned value is made to conform to the attributes CODE = '1100110000'B; of the receiving field, the precision or length of the assigned value may be Note, however, that the following altered. Such alteration can involve the statements do not assign equivalent values addition of digits or characters to and the to SUBJECT if it has the attributes deletion of digits or characters from the CHARACTER (10): converted item. The rules for data conversion are discussed in Chapter 4, SUBJECT = '110011'B; "Expressions and Data Conversion," and in Part II, Section F, "Problem Data SUBJECT = '1100110000'B; Conversion and Assignment." When the first statement is executed, the bit-string constant on the right is first converted to a character string and is then ALTERING THE LENGTH OF STRING DATA extended on the right with blank characters rather than zero bits. This statement is equivalent to: When a value is assigned to a string variable, it is converted, if necessary, to SUBJECT = '110011bbbb'; the same string type (character or bit) as the receiving string and also, if The second of the two statements necessary, is truncated or extended on the requires only a conversion from bit-string right to conform to the declared length of to character-string type and is equivalent the receiving string. For example, assume to: SUBJECT has the attributes CHARACTER (10), indicating a fixed-length character string SUBJECT = '1100110000'; of ten characters. Consider the following statement: A string value, however, is not extended with blank characters or zero bits when it SUBJECT = 'TRANSFORMATIONS'; is assigned to a string variable that has the VARYING attribute. Instead, the length The length of the string on the right is specification of the receiving string fifteen characters; therefore, five variable is effectively adjusted to characters will be truncated from the right describe the length of each assigned end of the string when it is assigned to string. Truncation will occur, though, if SUBJECT. This is equivalent to executing: the length of the assigned string exceeds the maximum length declared for the SUBJECT = 'TRANSFORMA'. varying-length string variable. 150 For the F Compiler the length, in PUT STRING (character-string-variable) characters or bits of a string variable or data-specification; intermediate string result is limited to 32,767. The GET statement specifies that data items to be assigned to variables in the data list are to be obtained from the specified character string. The PUT statement OTHER FORMS OF ASSIGNMENT specifies that data items of the data list are to be assigned to the specified character-string variable. The In addition to the assignment statement, "data-specification" is the same as PL/I provides other ways of assigning described for input and output. In values to variables. Among these are two general, it takes one of the following methods that involve input and output forms: statements: one in which actual input and output operations are performed, and one in DATA [(data-list)] which data movement is entirely internal. LIST (data-list) EDIT (data-list) (format-list) Input and Output Operations Although the STRING option can be used with each of the three modes of Although the assignment statement is stream-oriented transmission; it is most concerned with the transmission of data useful with edit-directed transmission; between storage locations internal to a which considers the input stream to be a computer, input and output operations can continuous string of characters. For also be treated as related forms of list-directed and data-directed GET assignment in which transmission occurs statements; individual items in the between the internal and external storage character string must be separated by facilities of the computer. commas or blanks; for data-directed GET statements; the string Record-oriented operations, however, do must also include the transmission- not cause any data conversion of items in a terminating semicolon, and each data item logical record when it is transmitted. must appear in the form of an assignment Required editing of the record must be statement. Edit-directed transmission performed within internal storage either provides editing facility by means of the before the record is written or after it is format list. read. The STRING option permits data gathering Stream-oriented operations, on the other or scattering operations to be performed hand, do provide a variety of editing with a single statement, and it allows functions that can be applied when data stream-oriented processing of character items are read or written. These editing strings that are transmitted by functions are similar to those provided by record-oriented statements. the assignment statement, except that any data conversion always involves character Consider the following statement: type, conversion from character type on input, and conversion to character type on PUT STRING (RECORD) EDIT output. (NAME; PAY#; HOURS*RATE) (A(12), A(7); P'$999V.99'); This statement specifies that the The STRING Option in GET and PUT Statements character-string value of NAME is to be assigned to the first (leftmost) 12 character positions of the string named The STRING option in GET and PUT statements RECORD, and that the character-string value allows the statements to be used to of PAY# is to be assigned to the next seven transmit data between internal storage character positions of RECORD. The value locations rather than between the internal of HOURS is then to be multiplied by the and external storage facilities. In both value of RATE, and the product is to be GET and PUT statements, the FILE option, edited into the next seven character specified by FILE (file-name), is replaced positions, according to the picture by the STRING option, as shown in the specification. following formats: Frequently, it is necessary to read GET STRING (character-string-variable) records of different formats, each of which data-specification; gives an indication of its format within Chapter 11: Editing and String Handling 151 the record by the value of a data item. of a sequence of character codes enclosed The STRING option provides an easy way to in quotation marks which is either, part of handle such records; for example: the PICTURE attribute, or part of the P (picture) format-item: READ FILE (INPUTR) INTO (TEMP): GET STRING (TEMP) EDIT (CODE) (F(1)); DECLARE PRICE PICTURE'$Z9V99'; IF CODE 1 = 1 THEN GO TO OTHER_TYPE; PUT FILE(SYSPRINT) EDIT GET STRING (TEMP) EDIT (X,Y,Z) ('PART NUMBER', PART#) (X(1), 3 F(10,4)); (A(12), P'AAA99X'); The READ statement reads a record from the Picture specifications are of two types: input file INPUTR. The first GET statement uses the STRING option to extract the code • numeric character specifications from the first byte of the record and to assign it to CODE. The code is tested to • character-string picture specifications determine the format of the record. If the code is 1, the second GET statement then A numeric character specification in a uses the STRING option to assign the items PICTURE attribute indicates that the data in the record to X,Y, and Z. Note that the item represents a numeric quantity, but second GET statement specifies that the that it is to be stored as a first character in the string TEMP is to be character-string and indicates how the ignored (the X(1) format item in the format numeric value is to be represented in the list). Each GET statement with the STRING string. A numeric character, specific in a option always specifies that the scanning P format item, indicates how a numeric is to begin at the first character of the value is; or is to be; represented as a string. Thus, the character that is character-string on the external medium. ignored in the second GET statement is the same character that is assigned to CODE by A character-string picture specification the first GET statement. is an alternative way of describing a fixed-length character string; with the In a similar way, the PUT statement with additional facility of indicating that any a STRING option can be used to create a position in the string, may only contain record within internal storage. In the characters from certain subsets of the following example, assume that the file complete set of characters available on the OUTPRT is eventually to be printed. IBM System/360 Operating System. PUT STRING (RECORD) EDIT The concepts of the two types of picture (NAME, PAY#, HOURS*RATE) specifications are described separately (X(1), A(12), X(10), A(7); X(10), below; and a detailed description of each P'$999V.99'); picture character, together with examples of its use, appears in Part II; Section D, WRITE FILE (OUTPRT) FROM (RECORD); "Picture Specification Characters". It is sufficient here to note that the presence The PUT statement specifies, by the X(1) of an A or X picture character, defines a spacing format item, that the first picture specification as a character-string character assigned to the character-string picture specification; otherwise it is a variable is to be a single blank, the ASA numeric character specification. carriage-control code that specifies a single space before printing. Following that, the values of the variables NAME and PAY# and of the expression HOURS*RATE are Numeric Character Specifications assigned. The format list specifies that ten blank characters are to be inserted between NAME and PAY# and between PAY# and A numeric character specification specifies the expression value. The WRITE statement that the associated data item has a numeric specifies that record transmission is to be value, but is to be maintained within the used to write the record into the file computer (or, is represented in the OUTPRT. external medium) as a character string. It also specifies the form the character-string is to take, and exactly how the numeric value is represented in the THE PICTURE SPECIFICATION string. For example: DCL PRICE PICTURE'$Z9V99'; Picture specifications extend the editing facilities available in PL/I, and provide This specifies that PRICE is to be the user with greater control over his data represented by a character-string of length formats. A picture specification consists 5. The first character is always $, the 152 second will be a blank or non-zero digit, The '9' Picture Character in Numeric and the third, fourth and fifth characters Character Specifications will be digits. The numeric value is the four characters which can represent digits, regarded as FIXED DECIMAL (4,2), and is The picture character '9' is the simplest always positive. 13.25 is represented as form of numeric character specification. A '$1325' and .95 as '$b095'. string of n, '9' picture characters specifies that the item is to be represented by a fixed-length The numeric character specification has character-string of length n, each two major uses: character of which is a digit (zero through nine). The numeric value is the value of the digits as an unsigned decimal number • For data items which will be concerned (i.e., FIXED DECIMAL (n,0). For example: with input/output operations, but they may be used anywhere in a program where numeric data can occur. However, on DCL DIGIT PICTURE'9' IBM System/360 Operating System, most COUNT PICTURE'999', numeric operations on pictured data are XYZ PICTURE '(10)9'; considerably less efficient than the same operations on coded numeric data. The last example shows an alternative way of writing the picture specification '9' • The second use stems from the fact that ten times. a pictured data item effectively has two values. When the item is used in a Example of use: numeric context, the numeric value is obtained from or stored into the DCL 1 CARD-IMAGE, character-string, by the conversion 2 DATA CHAR(72), process defined by the picture 2 IDENTIFICATION CHAR(3), specification; when the item is used in 2 SEQUENCE PIC'99999'; a character context the actual character-string which represents the value is used. For example: SEQUENCE = SEQUENCE + 1; DCL COUNT PICTURE'999' INITIAL(0), WRITE FILE(OUTPUT) FROM(CARD-IMAGE); STRING CHAR (3); COUNT = COUNT +1; (Note that the definition of '9' in a STRING = COUNT; character-string picture is different in that the corresponding character can be The initial representation of COUNT is blank or a digit.) '000'. In the first assignment statement this is converted to FIXED DECIMAL (3,0), the addition is performed, and the result is converted back to the pictured form '001'. In The Z * Picture Characters the second assignment statement the value of string is set to '001'. It is often preferable to replace leading Note particularly that "character zeros in numbers by blanks. In pictures context" includes defining. A numeric this is accomplished by using the Z picture character data-item may be defined on a specification character. A picture character-string and vice versa. specification containing only Z's and 9's has one or more Z's optionally followed by When a character-string value is one or more 9's. The representation of assigned to a numeric character numeric data is as for the '9' picture data-item (whether by direct specification except that if the digit to assignment, or as the result of be held would otherwise be zero and if all stream-oriented I/O), the value is digit positions to the left would also be checked for consistency with the zero, then the character-string will picture specification, and the contain a blank in this position. For CONVERSION condition is raised if it is example: inconsistent. For example: DCL PAGE-NUMBER PICTURE'ZZ9'; COUNT = STRING; The value 197 is held as '197', 69 as The CONVERSION condition will be raised 'b69', 5 as 'bb5' and zero as 'bb0'. With unless each character of STRING is a a picture specification of all Z's the digit. value zero is held as an all-blank string. Chapter 11: Editing and String Handling 153 The asterisk picture specification "Picture Specification Characters.") The character has the same effect as the 'Z' following two statements assign the same character except that an '*' is held in the character string to SUM: string instead of a blank. This can be used, for example, when printing cheques, when it is desired not be leave blank SUM = 123; spaces within fields. For example: DCL CREDIT PICTURE '$**9.99'; SUM = 123.00; (The $ and . characters are described below.) A value of 95 is held as In the first statement, two zero digits are ' $**0.95 ' ; a value of 12350 is held as added to the right of the digits 123. '$123.50'. Note the effect of the following declaration: The V Picture Character DECLARE RATE PICTURE '9V99.99'; Up to now numeric character specifications have only represented non-negative integer values. The V picture specification Let RATE be used as follows: character indicates the position of an assumed decimal point within the RATE = 7.62; character-string. For example: When this statement is executed, decimal DCL VALUE PICTURE 'Z9V999'; point alignment occurs on the character V and not on the decimal point picture The string '12345' represents the numeric character that appears in the picture value 12.345. Note that the V character in specification for RATE. If RATE were the picture specification does not specify printed, it would appear as '762.00', but a character position in the its arithmetic value would be 7.6200. character-string representation. In particular, on assignment to the data item Unlike the character V, which can appear a decimal point is not included in the only once in a picture specification; the character string. decimal point picture character can appear more than once; this allows digit groups within the numeric character data item to be separated by points, as is common in The Insertion Picture Characters: B . , / Dewey decimal notation and in the numeric notations of some European countries. A decimal point picture character(.) can Because a decimal point picture appear in a numeric picture specification. character causes a period character to be It merely indicates that a point is to be inserted into the character-string value of included in the character representation of a numeric character data item, it is called the value. Therefore, the decimal point is an insertion character. PL/I provides a part of its character-string value. The three other insertion characters: comma decimal point picture character does not (,), slash(/), and blank(B), which are used cause decimal point alignment during in the same way as the decimal point assignment; it is not a part of the picture character except that a comma, variable's arithmetic value. Only the slash, or blank is inserted into the character V causes alignment of decimal character string. Consider the following points. For example: statements: DECLARE SUM PICTURE '999V.99'; DECLARE RESULT PICTURE '9.999.999,V99'; SUM is a numeric character variable RESULT = 1234567; representing numbers of five digits with a decimal point assumed between the third and The character-string value of RESULT would fourth digits. The actual point specified be '1.234.567,00'. Note that decimal point by the decimal point insertion character is alignment occurs before the two rightmost not a part of the arithmetic value; it is, digit positions, as specified by the however, part of its character-string character V. If RESULT were assigned to a value. (The decimal point picture coded arithmetic field, the value of the character can appear on either side of the data converted to arithmetic would be character V. See Part II, Section D, 1234567.00. 154 The $ Picture Character of indicating signs in numeric data held on punched cards, by superimposing a 12-punch (to represent +) or an 11-punch (to The ($) picture character controls the represent -) on top of a column containing appearance of the currency symbol ($) in a digit (usually the last one in a field). specified positions of numeric character The resulting card-code is, in most cases, data items. For example, a dollar sign can the same as that for an alphabetic be appended to the left of a numeric character, e.g., 12-punch superimposed on 0 character item, as indicated in the through 9 gives A through I, 11-punch following statements: superimposed on 0 through 9 gives J through R. The 12-0 and 11-0 combinations are not DECLARE PRICE PICTURE '$99V.99'; characters in the PL/I set but are within the set of characters accepted by the IBM PRICE = 12.45; System/360 Operating System implementations for character data. The character-string value of PRICE is equivalent to the character-string constant '$12.45'. Its arithmetic value, however, The T picture specification character is 12.45. specifies a character in the character-string representation which will The picture specification can also hold a digit and sign, in the specify floating-point and British sterling representation described above, i.e., 12-0 formats, as well as scaling factors for or A through I for positive or zero, 11-0 fixed-point values. These formats are or J through R for negative. It can appear discussed in Part II, Section D, "Picture anywhere a '9' picture specification Specification Characters." character could have occurred. For example: DCL CREDIT PICTURE 'ZZV9T'; Sign Specification in Numeric Character Specifications The character-string representation of CREDIT is 4 characters. +21.05 is held as '210E'. -0.07 is held as 'bb0P'. There are several ways in which signed The 'I' picture specification character information may be held in a numeric specifies a character position which holds character data item. The simplest of these the representation of a digit overpunched is the S character specification. This with a 12-punch if the value is positive or specifies a character in the zero; but just a digit if the value is character-string representation which negative. contains '+' if the value is positive or zero, and '-' if the value is negative. It The 'R' picture specification character must occur either to the right or to the specifies a character position which holds left of all digit positions. For example: the representation of a digit overpunched with an 11-punch if the value is negative, DCL ROOT PICTURE 'S999'; but just a digit if the value is positive. For example: 50 is held as '+505', zero as '+000' and -243 as '-243'. Similarly the '+' picture GET EDIT (X) (P'R99'); character specifies a corresponding character position containing '+' for will set X to (+)132 on finding '132' in positive or zero, and blank for negative the next 3 positions of the input stream, values; the '-' picture character specifies but -132 on finding 'J32'. a corresponding character position containing blank for positive or zero, and '-' for negative values. Other Numeric Character Facilities Overpunched Sign Specification Characters, T I R Further details of usage of the above picture specification characters, together An alternative way of representing signed with details of picture specification values, which does not require an characters for floating signs and currency additional character in the string, is by symbols, floating point values, and an overpunched sign specification. This sterling values, appear in Part II, Section representation has arisen from the custom D, "Picture Specification Characters". Chapter 11: Editing and String Handling 155 The full list of numeric character BIT-STRING HANDLING specification characters is 9,V,Z,*,Y,(.),(,),1,B,S,+,-,$,CR,DB,T,I,R,K ,E,F,8,7,6,P,G,H,M, of which all except The following examples illustrate some of K,V,F,G,M specify the occurrence of a the facilities of PL/I that can be used in character in the character-string bit-string manipulations. representation. Character-string Picture Specifications DECLARE 1 PERSONNEL_RECORD, 2 NAME, 3 LAST CHARACTER(15), A character-string picture specification is 3 FIRST CHARACTER(10), an alternative way of describing a 3 MIDDLE CHARACTER(1), fixed-length character string, with the 2 CODE_STRING, additional facility of indicating that any 3 MALE BIT(1), position in the string, may only contain 3 SECRETARIAL BIT(1), characters from certain subsets of the 3 AGE, complete set of characters available on the 4 (UNDER_20, IBM System/360 Operating System. TWENTY_TO_30, OVER_30) BIT(1), A character-string picture specification 3 HEIGHT, is recognised by the occurrence of an A or 4 (OVER_6, X picture specification character. The FIVE_SIX_TO_6, only valid characters in a character-string UNDER_5_6) BIT(1), picture specification are A, X and 9. Each 3 WEIGHT, of these specifies the presence of one 4 (OVER_180, character position in the character which ONE_TEN_TO_180, can contain the following: UNDER_110) BIT(1), 3 EYES, 'X' any character recognised by the 4 (BLUE, particular implementation (for the BROWN, IBM System/360 Operating System, HAZEL, all 256 possible bit combinations GREY, represented by the 8-bit byte). OTHER) BIT(1), 3 HAIR, 'A' any alphabetic character, or blank. 4 (BROWN, BLACK, '9' any digit, or blank. Note the BLOND, difference from the '9' picture RED, specification character in numeric GREY, character specifications. BALD) BIT(1), 3 EDUCATION, When a character-string value is assigned, 4 (COLLEGE, or transferred, to a pictured HIGH_SCHOOL, character-string data item, the particular GRAMMAR_SCHOOL) BIT(1); character in each position is checked for validity, as specified by the corresponding picture specification character, and the CONVERSION condition is raised for an invalid character. For example: This structure contains NAME, a minor structure of character-strings, and DECLARE PART# PICTURE 'AAA99X'; CODE_STRING, a minor structure of bit-strings. By default, the elements of The following values are valid for PERSONNEL-RECORD have the UNALIGNED assignment to PART#. attribute. Consequently, CODE_STRING is mapped with eight elements per byte, that 'ABC12M' is, in the same way as a bit-string of 'bbb09/' length 25. 'XYZb13' Each of the first two bits of the string The following values are not (the invalid represents only two alternatives: MALE or characters are underscored); ¬MALE and SECRETARIAL or ¬SECRETARIAL. The other categories (at level 3) list several 'AB123M' alternatives each. (Note that the level 'ABC1/2' number 4 and the attributes BIT(1) are 'Mb#A5;' factored for each category.] 156 | The following portion of a program might The first method, if it were used, would be be used with PERSONNEL RECORD: more efficient with an ALIGNED structure. INREC: READ FILE(PERSONNEL) The tests might also be made with a INTO (PERSONNEL_RECORD); series of IF statements, either nested or unnested, in which each bit would be tested IF (,MALE & SECRETARIAL with a single IF statement. It would & UNDER_20 require a greater amount of coding, but it & UNDER_5_6 would be faster at execution time than an & UNDER_110 IF statement containing many bit-string & BLUE operators. & (HAIR.BROWN|BLOND) & HIGH SCHOOL) (MALE & SECRETARIAL & OVER_30 CHARACTER-STRING AND BIT-STRING BUILT-IN & OVER_6 FUNCTIONS & OVER_180 & EYES.GREY & BALD PL/I provides a number of built-in & COLLEGE) functions, some of which also can be used as pseudo-variables, to add power to the THEN PUT LIST (NAME); string-handling facilities of the language. Following are brief descriptions of these GO TO INREC; functions (more detailed descriptions appear in Part II, Section G, "Built-In Another way to program the same Functions and Pseudo-Variables"): information retrieval operation, as shown in the following coding, would result in The BIT built-in function specifies that considerably shorter execution time: a data item is to be converted to a bit string. The built-in function allows a DECLARE PERS_STRING BIT(25) DEFINED programmer to specify the length of the CODE STRING; converted string, overriding the length that would result from the standard rules IF PERS_STRING of data conversion. = '0110000100110000100000010'B THEN GO TO OUTP; The CHAR built-in function is exactly the same as the BIT built-in function, IF PERS_STRING except that the conversion is to a = '0110000100110000001000010'B character string of a specified length. THEN GO TO OUTP; The SUBSTR built-in function, which can IF PERS_STRING also serve as a pseudo-variable in a = '1000110010000010000001100'B receiving field, allows a specific THEN GO TO OUTP; substring to be extracted from (or assigned to, in the case of a pseudo-variable) a GO TO INREC; specified string value. OUTP: PUT LIST (NAME); The INDEX built-in function allows a string, either a character string or a bit GO TO INREC; string, to be searched for the first occurrence of a specified substring, which In this example, the bit string PERS_STRING can be a single character or bit. The is defined on the minor structure value returned is the location of the first CODE_STRING. Bit-string constants are character or bit of the substring, relative constructed to represent the values of the to the beginning of the string. The value information being sought. The bit string is expressed as a binary integer. If the then is compared, in turn, with each of the substring does not occur in the specified bit-string constants. Note that the first string, the value returned is zero. and second constants are identical except that the first tests for brown hair and the The LENGTH built-in function gives the second tests for blond hair. These two current length of a character string or bit variations are specified in the first string. It is particularly useful with example by (HAIR.BROWN|BLOND). strings that have the VARYING attribute. Note that the second method of testing The HIGH built-in function provides a PERSONNEL_RECORD could not be used if the string of a specified length that consists structure were ALIGNED (the base identifier of repeated occurrences of the highest for overlay defining must be UNALIGNED). character in the collating sequence. For Chapter 11: Editing and String Handling 157 System/360 implementations, the character The BOOL built-in function allows up to is hexadecimal FF. 16 different Boolean operations to be applied to two specified bit strings. The LOW built-in function provides a The UNSPEC built-in function, which can string of a specified length that consists also be used as a pseudo-variable, of repeated occurrences of the lowest specifies that the internal coded character in the collating sequence. For representation of a value is to be regarded System/360 implementations, the character as a bit string with no conversion. is hexadecimal 00. The TRANSLATE built-in function The REPEAT built-in function permits a translates a specified string according to string to be formed from repeated a translation table defined by two other occurrences of a specified substring. It strings. is used to create string patterns. The VERIFY built-in function verifies The STRING built-in function, which can that each character or bit in a given also be used as a pseudo-variable, source string is represented in a given concatenates all the elements in an verification string; in other words, it aggregate variable variable into a single tests the validity of each character or bit string element. according to user-specified criteria. 158 Chapter 12: Subroutines and Functions Arguments and Parameters Data can be made known in an invoked procedure by extending the scope of the names identifying that data to include the invoked procedure. This extension of scope is accomplished by nesting procedures or by specifying the EXTERNAL attribute for the names. There is yet another way in which data In procedure PRMAIN, NAME is declared as can be made known in an invoked procedure, a character string, and ITEM as a bit and that is to specify the names as string. The CALL statement in PRMAIN arguments in a list in the invoking invokes the procedure called OUTSUB, and statement. Each argument in the list is an the parenthesized list included in this expression, a file name, a statement label procedure reference contains the two constant or variable, or an entry name that arguments being passed to OUTSUB. The is to be passed to the invoked procedure. PROCEDURE statement defining OUTSUB declares two parameters, A and B. When Since arguments are passed to it, the OUTSUB is invoked, NAME is associated with invoked procedure must have some way of A and ITEM is associated with B. Each accepting them. This is done by the reference to A in OUTSUB is treated as a explicit declaration of one or more reference to NAME and each reference to B parameters in a list in the PROCEDURE or is treated as a reference to ITEM. ENTRY statement that is the entry point at Therefore, the PUT LIST (A,B) statement which the procedure is invoked. A causes the values of NAME and ITEM to be parameter is a name used within the invoked written into the standard system output procedure to represent another name (or file, SYSPRINT. expression) that is passed to the procedure as an argument. Each parameter in the Note that the passing of arguments parameter list of the invoked procedure has usually involves the passing of names and a corresponding argument in the argument not merely the values represented by these list of the invoking statement. This names. (In general, the name that is correspondence is taken from left-to-right; passed is usually the address of the value the first argument corresponds to the first or an address that can be used to retrieve parameter, the second argument corresponds the value.) As a result, storage allocated to the second parameter, and so forth. In for a variable before it is passed as an general, any reference to a parameter argument is not duplicated when the within the invoked procedure is treated as procedure is invoked. Any change of value a reference to the corresponding argument. specified for a parameter actually is a The number of arguments and parameters must change in the value of the argument. Such be the same. The maximum number of changes are in effect when control is parameters permitted at any entry point is returned to the invoking block. 64. A parameter can be thought of as indirectly representing the value that is The example below illustrates how directly represented by an argument. Thus, parameters and arguments may be used: since both the argument and the parameter represent the same value, the attributes of a parameter and its corresponding argument must agree. For example, an obvious error exists if a parameter has the attribute FILE and its corresponding argument has the attribute FLOAT. However, there are cases in which such an error may not be so obvious, for example, when an argument is a constant. Certain inconsistencies between the attributes of an argument and its associated parameter can be resolved by specifying, in an invoking procedure, the Chapter 12: Subroutines and Functions 159 ENTRY attribute for an entry name to be 1. Control reaches the final END invoked. The ENTRY attribute specification statement of the subroutine. provides the facility to specify that the Execution of this statement causes compiler is to generate coding to convert control to be returned to the first one or more arguments to conform with the executable statement logically attributes of the associated parameters. following the statement that This topic is discussed later in this originally invoked the subroutine. chapter in the sections "The ENTRY There is an exception, however: return Attribute" and "Dummy Arguments." of control from a subroutine invoked by the CALL option is to the statement A name is explicitly declared to be a containing the CALL option at the parameter by its appearance in the point immediately following that parameter list of a PROCEDURE or ENTRY option. Either of these is considered statement. However, its attributes, unless to be a normal return. defaults apply, must be explicitly stated within that procedure in a DECLARE statement. Parameters, therefore, provide the means 2. Control reaches a RETURN statement in for generalizing procedures so that data the subroutine. This causes the same whose names may not be known within such normal return caused by the END procedures can, nevertheless, be operated statement. upon. There are two types of generalized procedures that can be written in PL/I: subroutine procedures (called simply, subroutines) and function procedures 3. Control reaches a GO TO statement that (functions). transfers control out of the subroutine. (This is not permitted if the subroutine is invoked by the CALL option.) The GO TO statement may Subroutines specify a label in a containing block (the label must be known within the subroutine), or it may specify a (The discussion in this section applies to parameter that has been associated synchronous operation and does not with a label argument passed to the completely cover asynchronous operation, subroutine. Although this is although the rules apply generally to all considered to be normal termination of subroutines, whether or not the CALL the subroutine, it is not normal statement contains one of the multitasking return of control, as effected by an options. Multitasking is discussed in END or RETURN statement. Chapter 15, "Multitasking.") A subroutine is a procedure that usually requires arguments to be passed to it in an With synchronous operation, a STOP or invoking CALL statement. It can be either EXIT statement encountered in a subroutine an external or internal procedure. A abnormally terminates execution of that reference to such a procedure is known as a subroutine and of the entire program subroutine reference. The general format associated with the procedure that invoked of a subroutine reference is as follows: it. CALL entry-name [(argument[,argument]...)]; The following example illustrates how a Note that a subroutine can also be invoked subroutine interacts with the procedure through the CALL option of an INITIAL that invokes it: attribute specification. Whenever a subroutine is invoked, the A: PROCEDURE; arguments of the invoking statement are DECLARE RATE FLOAT (10), TIME FLOAT(5), associated with the parameters of the entry DISTANCE FLOAT(15), MASTER FILE; point, and control is then passed to that entry point. The subroutine is thus activated, and execution begins. CALL READCM (RATE, TIME, DISTANCE, Upon termination of a subroutine, MASTER); control normally is returned to the invoking block. A subroutine can be terminated normally in any of the following ways: END A; 160 X = Y**3+SPROD(A,B,C); contains a reference to a function called SPROD. The parenthesized list following the function name contains the arguments that are being passed to SPROD. Assume that SPROD has been defined as follows: The arguments RATE, TIME, DISTANCE, and MASTER are passed to the parameters W, X, Y, and Z. Consequently, in the subroutine, a reference to W is the same as a reference to RATE, X the same as TIME, Y the same as DISTANCE, and Z the same as MASTER. When SPROD is invoked by MAINP, the arguments A, B, and C are associated with the parameters U, V, and W, respectively. Since attributes have not been explicitly declared for the arguments and parameters, Functions default attributes of FLOAT DECIMAL (6) are applied to each argument and parameter. A function is a procedure that usually (The default precision is that defined for requires arguments to be passed to it when System/360 implementations.) Hence, the it is invoked. It cannot be executed attributes are consistent, and the asynchronously with the invoking procedure. association of the arguments with the Unlike a subroutine, which is invoked by a parameters produces no error. CALL statement or CALL option, a function is invoked by the appearance of the During the execution of SPROD, the IF function name (and associated arguments) in statement is encountered and a test is an expression. Such an appearance is made. If U is greater than V + W, the called a function reference. Like a statement associated with the THEN clause subroutine, a function can operate upon the is executed; otherwise, the statement arguments passed to it and upon other known associated with the ELSE clause is data. But unlike a subroutine, a function executed. In either case, the executed is written to compute a single value which statement is a RETURN statement. is returned, with control, to the point of invocation, the function reference. This The RETURN statement is the usual way by single value can be of arithmetic, string which a function is terminated and control (including picture data), locator, or area is returned to the invoking procedure. Its type. The maximum number of different data use in a function differs somewhat from its types or precisions returned by one use in a subroutine; in a function, not function may not exceed 256. An example of only does it return control but it also a function reference is contained in the returns a value to the point of invocation. following procedure: The general form of the RETURN statement, when it is used in a function, is as follows: RETURN (element-expression); The expression must be present and must represent a single value; i.e., it cannot be an array or structure expression. It is this value that is returned to the invoking procedure at the point of invocation. Thus, for the above example, SPROD returns either 0 or the value represented by U*V*W, along with control to the invoking expression in MAINP. The returned value then effectively replaces the function In the above procedure, the assignment reference, and evaluation of the invoking statement expression continues. Chapter 12: Subroutines and Functions 161 A function can also be terminated by an entry name. See "The ENTRY Attribute" execution of a GO TO statement. If this in this chapter for additional information. method is used, evaluation of the expression that invoked the function will not be completed, and control will go to the designated statement. As in a Attributes of Returned Values subroutine, the transfer point specified in a GO TO statement may be a parameter that has been associated with a label argument. The attributes of the value returned by a For example, assume that MAINP and SPROD function may be declared in two ways: have been defined as follows: 1. They may be declared by default MAINP: PROCEDURE; according to the first letter of the function name. 2. They may be explicitly declared in the GET LIST (A,B,C,Y); RETURNS option of the PROCEDURE (or X = Y**3+SPROD(A,B,C,LAB1); ENTRY) statement for the function. Note that the value of the expression in the RETURN statement is converted within LAB1: CALL ERRT; the function, whenever necessary, to conform to the attributes specified by one of the two methods above. END MAINP; In the previous examples of MAINP and SPROD, the PROCEDURE statement of SPROD SPROD: PROCEDURE (U,V,W,Z); contains no attributes declared for the DECLARE Z LABEL; value it returns. Thus, these attributes must be determined from the first letter of its name; S. The attributes of the returned value are therefore FLOAT and IF • U > V + W DECIMAL. Since these are the attributes THEN CO TO Z; that the returned value is expected to ELSE RETURN (U*V*W); have; no conflict exists. Note: Unless the invoking procedure provides the compiler with information to END SPROD; the contrary; the attributes assumed for the value returned by a function to the In MAINP, LAB1 is explicitly declared to invoking procedure are always determined be a statement label constant by its from the first letter of the function name. appearance as a label for the CALL ERRT statement. When SPROD is invoked, LAB1 is The RETURNS Option: The way in which associated with parameter Z. Since the attributes can be declared for the returned attributes of Z must agree with those of value in the PROCEDURE or ENTRY statement LAB1, Z is declared to have the LABEL is illustrated in the following example. attribute. When the IF statement in SPROD Assume that the PROCEDURE statement for is executed, a test is made. If U is SPROD has been specified as follows: greater than V + W, the THEN clause is executed, control returns to MAINP at the I SPROD: PROCEDURE (U,V,W,Z) RETURNS(FIXED statement labeled LAB1, and evaluation of BINARY); the expression that invoked SPROD is discontinued. If U is not greater than V + With this declaration, the value returned W, the ELSE clause is executed and a return by SPROD will have the attributes FIXED and to MAINE is made in the normal fashion. BINARY. However, since these attributes Additional information about the use of differ from those that would be determined label arguments and label parameters is from the first letter of the function name, contained in the section "Relationship of this difference must be stated in the Arguments and Parameters" in this chapter. invoking procedure to avoid a possible error. The PL/I programmer communicates Note: In some instances, a function may be this information to the compiler with the so defined that it does not require 'RETURNS attribute specified in a DECLARE arguments. In such cases, the appearance statement in the invoking procedure. of the function name within an expression will be recognized as a function reference The RETURNS Attribute: The RETURNS only if the function name has been attribute is specified in a DECLARE explicitly or contextually declared to be statement for an entry name. It specifies 162 the attributes of the value returned by Built-In Functions that function. It further specifies, by implication, the ENTRY attribute for the name; consequently, it is an entry name attribute specification. Unless default attributes for the entry name apply, any Similar to function procedures that a invocation of a function must appear within programmer can define for himself is a the scope of a RETURNS attribute comprehensive set of pre-defined functions declaration for the entry name. For an called built-in functions. internal function, the RETURNS attribute can be specified only in a DECLARE statement that is internal to the same block as the function procedure. The set of built-in functions is an intrinsic part of PL/I. It includes not only the commonly used arithmetic functions The general format of the RETURNS but also other necessary or useful attribute is: functions related to language facilities, such as functions for manipulating strings and arrays. RFTURNS (attribute-list) A RETURNS attribute specifies that within Built-in functions are invoked in the the invoking procedure the value returned same way that programmer-defined functions from the named entry point is to be treated are invoked. However, many built-in as though it had the attributes given in functions can return array or structure the attribute list. The word treated is values, whereas a programmer-defined used because no conversion is performed in function can return only an element value. an invoking block upon any value returned to it. Therefore, if the attributes of the returned value do not agree with those in the attribute list of the RETURNS Note: Some built-in functions may actually attribute, an error will probably result. be compiled as in-line code rather than as procedure invocations. All are referred to in a PL/I source program, however, by In order to specify to the compiler that function references, whether or not they coding for MAINP is to handle the FIXED result in an actual procedure invocation. BINARY value being returned by SPROD, the following declaration must be given within MAINP: Neither the ENTRY attribute nor the RETURNS attribute can be specified for any DECLARE SPROD RETURNS (FIXED BINARY); built-in function name. The use of the name in a function reference is recognized without need for any further It is important to note some of the identification; attributes of values things that are implied in the above returned by built-in functions are known by discussion. Principally, it should be the compiler. remembered that during compilation of the invoking block, there is no way for the compiler to check a function procedure to determine the attributes of the value it returns. In the absence of explicit But since built-in function names are information in a RETURNS attribute PL/I keywords, they are not reserved; the specification, the compiler can only assume same identifiers can be used as that the attributes will be consistent with programmer-defined names. Consequently, the attributes implied by the first letter ambiguity might occur if a built-in of the function name. This is true even if function reference were to be used in a the function procedure is contained in the block that is contained in another block in invoking procedure. If the returned value which the same identifier is declared for does not have the attributes that the some other purpose. To avoid this invoking procedure is prepared to receive, ambiguity, the BUILTIN attribute can be no conversion can be performed. The declared for a built-in function name in RETURNS attribute must be declared for a any block that has inherited, from a function that returns any value with containing block, some other declaration of attributes not consistent with default the identifier. Consider the following attributes for the function name. example. Chapter 12: Subroutines and Functions 163 is discussed in a later section of this chapter.) The following example illustrates use of the ENTRY attribute in conjunction with the BUILTIN attribute. Assume that in external procedure A, SQRT is neither explicitly nor contextually declared for some other use. Consequently, any reference to SQRT would refer to the built-in function of that name. In B, however, SORT is declared to be a floating-point binary variable, and it cannot be used in any other way. Finally, in C, SQRT is declared with the BUILTIN attribute so that any reference to SQRT will be recognized as a reference to the built-in function and not to the floating-point binary variable declared in B. Note that a variable having the same The use of SQRT as the label of the identifier as a built-in function can be first PROCEDURE statement is an explicit contextually declared by its appearance on declaration of the identifier as an entry the left-hand side of an assignment symbol name. Since, in this case, SQRT is not the (in an assignment statement, a DO built-in function, the entry name must be statement, or a repetitive specification) explicitly declared in A (and the RETURNS or in the data list of a GET statement, attribute is specified because the provided that it is neither enclosed within attributes of the returned value are not nor immediately followed by an argument apparent in the function name). The list. (This does not apply to the names function reference in the assignment ONCHAR, ONSOURCE, and PRIORITY which are statement in A thus refers to the pseudo-variables that do not require programmer-written SQRT function. In the arguments.) For example, if the statement begin block, the identifier SQRT is SQRT = 1 had appeared in procedure B declared with the BUILTIN attribute. instead of the explicit declaration, SQRT Consequently, the function reference in the would have been contextually declared as a assignment statement in B refers to the floating-point decimal variable. built-in SQRT function. A programmer can even use a built-in If a programmer-written function using function name as the entry name of a the name of a built-in function is programmer-written function and, in the external, any procedure containing a same program, use both the built-in reference to that function name must also function and the programmer-written contain an entry declaration of that name; function. This can be accomplished by use otherwise a reference to the identifier of the BUILTIN attribute and the ENTRY would be a reference to the built-in attribute. (The ENTRY attribute, which is function. In the above example, if the used in a DECLARE statement to specify that PROCEDURE B were not contained in A, there the associated identifier is an entry name, would be no need to specify the BUILTIN 164 attribute; so long as the identifier SQRT 4. If an argument is a variable whose is not known as some other name, the data attributes are different from the identifier would refer to the built-in data attributes declared for the function. parameter in an entry name attribute specification appearing in the If a programmer-written function using invoking block the name of a built-in function is internal, any reference to the identifier 5. If an argument is itself a function in the containing block would be a reference containing arguments reference to the programmer-written function, provided that its name is known 6. If, for the F Compiler, an argument is in the block in which the reference is a controlled array or string made. No entry name attributes would have associated with a simple parameter, to be specified if attributes to the unless the asterisk notation is used. returned value could be inferred from the entry name. In all other cases, the argument name is passed directly. The parameter becomes identical with the passed argument; thus, changes to the value of a parameter will be reflected in the value of the original Relationship of Arguments and Parameters argument only if a dummy argument is not passed. When a function or subroutine is invoked, a A task variable cannot be passed as an relationship is established between the argument if this would cause a dummy arguments of the invoking statement or argument to be created. expression and the parameters of the invoked entry point. This relationship is Note: When a dummy argument is created for dependent upon whether or not dummy an argument that is a constant, the arguments are created. attributes of the dummy argument will be those indicated by the constant. For example, if SUB is a subroutine that expects to be passed a fixed binary DUMMY ARGUMENTS argument, the statement CALL SUB(2); In the introductory discussion of arguments and parameters, it is pointed out that the will lead to error, since the dummy name of an argument, not its value, is argument will be fixed decimal. This can passed to a subroutine or function. be avoided either by assigning the value 2 However, there are times when an argument to a fixed binary variable and passing the has no name. A constant, for example, has variable name, e.g., no name; nor does an operational expression. But the mechanism that I=2; associates arguments with parameters cannot CALL SUB(I); handle such values directly. Therefore, the compiler must provide storage for such or by using the ENTRY attribute. values and assign an internal name for each. These internal names are called dummy arguments. They are not accessible to the PL/I programmer, but he should be THE ENTRY ATTRIBUTE aware of their existence because any change to a parameter will be reflected only in the value of the dummy argument and not in There is no way during compilation of a the value of the original argument from subroutine or function that the compiler which it was constructed. can know the attributes of arguments that will be passed to a parameter. The A dummy argument is always created for compiler must assume that the attributes of any of the following cases: each argument will agree with the attributes of its associated parameter. 1. If an argument is a constant (see Wherever there is disagreement, the program note, below) must provide, in the invoking procedure, an ENTRY attribute declaration for the entry 2. If an argument is an expression name of the subroutine or function being involving operators invoked. The general form of the ENTRY attribute is as follows: 3. If an argument is an expression in ENTRY [(parameter-attribute-list parentheses [,parameter-attribute-list]...)] Chapter 12: Subroutines and Functions 165 Note that the above format allows the 1. By its appearance as a label of a keyword ENTRY to be specified without PROCEDURE or ENTRY statement accompanying parameter attribute lists, as (explicit) it might be used to identify a function entry name that does not require arguments. 2. By its appearance immediately Each parameter attribute list in the following the keyword CALL ENTRY attribute specification corresponds (contextual) to one parameter of the subroutine or function involved and specifies the 3. By its appearance as the function name attributes of that parameter. In general, in a function reference that contains if the attributes of an argument do not an argument list (contextual) agree with those of its corresponding parameter (as specified in a parameter Therefore, if a reference is made to an attribute list), a dummy argument is entry name in a block in which it does not constructed for that argument if conversion appear in one of these three ways, the is possible. The dummy argument contains identifier must be given the ENTRY the value of the original argument attribute explicitly, or by implication converted to conform with the attributes of (see "Note" below), in a DECLARE statement the corresponding parameter. Thus, when within the block. For example, assume that the subroutine or function is invoked, it the following has been specified: is the dummy argument that is passed to it. If an ENTRY attribute with parameter attribute lists is not used, the compiler assumes that the arguments are compatible and acts according to the default attributes of the parameters. If the argument attributes do not agree with the attributes of the corresponding parameter, no conversion occurs, and an error probably results. For example, if a fixed decimal argument, which should be byte aligned, is Assume also that A is an external passed to a procedure which expects a fixed procedure and RANDOM is an external binary argument, then a specification function that requires no arguments and interrupt probably occurs when the argument returns a random number. As the procedure is treated as fullword binary. is shown above, RANDOM is not recognizable within A as an entry name, and the result When the above form of the ENTRY of the PUT statement therefore is attribute is used, each parameter of the undefined. In order for RANDOM to be subroutine or function must be accounted recognized within A as an entry name, it for. If there is no need to specify the must be declared to have the ENTRY attributes of a particular parameter, its attribute. For example: place must be kept by a comma. For example, the statement: DECLARE SUBR ENTRY (FIXED „FLOAT); specifies that SUBR is an entry name that has three parameters: the first and third have the attributes FIXED and FLOAT, respectively, while the attributes of the second are presumably the same as those of the argument being passed. Since the attributes of the second parameter are not stated, no assumptions are made and no Now, RANDOM is recognized as an entry conversions are performed. name, and the appearance of RANDOM in the PUT statement cannot be interpreted as As mentioned earlier, the ENTRY anything but a function reference. attribute may be specified without Therefore, the PUT statement results in the parameter attribute lists. It is used in output transmission of the random number this way to indicate that the associated returned by RANDOM. identifier is an entry name. Such an indication is necessary if an identifier is Note: The ENTRY attribute is implied -- and not otherwise recognizable as an entry therefore need not be stated explicitly -- name, that is, if it is not explicitly or for an identifier that is declared in a contextually declared to be an entry name DECLARE statement to have the RETURNS in one of the following ways: attribute. 166 Entry Names as Arguments Consider the following example: When an entry name is specified as an argument of a function or subroutine reference, one of the following applies: 1. If the entry name argument, call it M, is specified with an argument list of its own, it is recognized as a function reference; M is invoked, and the value returned by M effectively replaces M and its argument list in the containing argument list. 2. If the entry name argument appears without an argument list, but within an operational expression or within parentheses, then it is taken to be a function reference with no arguments. For example: CALL A((B)); This passes, as the argument to procedure A, the value returned by the function procedure B. 3. If the entry name argument appears without an argument list and neither within an operational expression nor within parentheses, the entry name itself is passed to the function or subroutine being invoked. In such cases, the entry name is not taken to be a function reference, even if it is the name of a function that does not In this example, assume that CALLP, require arguments. For example: SUBR, and RREAD are external. In CALLP, both RREAD and SUBR are explicitly declared CALL A(B); to have the ENTRY attribute. (Actually, the explicit declaration for SUBR is used This passes the entry name B as an principally to provide information about argument to procedure A. the characteristics of the parameters of SUBR.) Four arguments are specified in the There is an exception to this rule, CALL SUBR statement. These arguments are however: if an identifier is known as interpreted as follows: an entry name and appears as an argument and if the parameter 1. The first argument, RREAD, is attribute list for that argument recognized as an entry name (because specifies an attribute other than of the ENTRY attribute declaration). ENTRY, the entry name will be invoked This argument is not in conflict with and its returned value passed. For the first parameter as specified in example: the parameter attribute list in the ENTRY attribute declaration for SUBR in CALLP. Therefore, since RREAD is recognized as an entry name and not as a function reference, the entry name is passed at invocation. 2. The second argument, SQRT(R), is recognized as a function reference because of the argument list accompanying the entry name. SQRT is invoked, and the value returned by SQRT is assigned to a dummy argument, which effectively replaces the In this case, B is invoked and its reference to SQRT. The attributes of returned value is passed to C. the dummy argument agree with those of Chapter 12: Subroutines and Functions 167 the second parameter, as specified in simple parameters, and those that have the the parameter attribute list CONTROLLED attribute, i.e., controlled declaration. When SUBR is invoked, parameters. the dummy argument is passed to it. A simple parameter may be associated 3. The third argument, S, is simply a with an argument of any storage class. decimal floating-point element However, if more than one generation of the variable. However, since its argument exists, the parameter is attributes do not agree with those of associated only with that generation the third parameter, as specified in existing at the time of invocation. the parameter attribute list declaration, a dummy argument is A controlled parameter must always have created containing the value of S a corresponding controlled argument. Such converted to the attributes of the an argument cannot be subscripted, cannot third parameter. When SUBR is be an element of a structure, and cannot invoked, the dummy argument is passed. cause a dummy to be created. If more than one generation of the argument exists at 4. The fourth argument, LAB1, is a the time of invocation, the parameter statement-label constant. Its corresponds to the entire stack of these attributes agree with those of the generations. Thus, at the time of fourth parameter. Put since it is a invocation, a controlled parameter constant, a dummy argument is created represents the current generation of the for it. When SUER is invoked, the corresponding argument. A controlled dummy argument is passed. parameter may be allocated and freed in the invoked procedure, thus allowing the In SUBR, four parameters are explicitly manipulation of the allocation stack of the declared in the PROCEDURE statement. If no associated argument. A simple parameter further explicit declarations were given cannot be specified in an ALLOCATE or FREE for these parameters, arithmetic default statement. attributes would be supplied for each. Therefore, since NAME must represent an entry name, it is explicitly declared with the ENTRY attribute, and since TRANPT must Parameter Bounds and Lengths represent a statement label, it is explicitly declared with the LABEL attribute. X and J are arithmetic, so the If an argument is a string or an array, the defaults are allowed to apply. length of the string or the bounds of the array must be declared for the Note that the appearance of NAME in the corresponding parameter. The number of CALL statement does not constitute a dimensions and the bounds of an array contextual declaration of NAME as an entry parameter or the length of a string name. Such a contextual declaration can be parameter must be the same as that for the made only if no explicit declaration current generation of the corresponding applies, and the appearance of NAME in the argument. Usually, this can be assured PROCEDURE statement of SUER constitutes an simply by specifying actual numbers for the explicit declaration of NAME as a bounds or length of the parameter. parameter. If the attributes of a However, the actual bounds or length may parameter are not explicitly declared in a not always be known at the time that the complementary DECLARE statement, arithmetic subroutine or function is written. defaults apply. Consequently, NAME must be Whenever this is the case, bounds or length explicitly declared to have the ENTRY for a simple parameter may be specified by attribute; otherwise, it would be assumed asterisks; bounds or length for a to be a binary fixed-point variable, and controlled parameter may be specified its use in the CALL statement would result either by asterisks or by expressions. in an error. Simple Parameter Bounds and Lengths ALLOCATION OF PARAMETERS When the actual length or bounds of a A parameter cannot be declared to have any simple parameter are not known, they can be of the storage class attributes STATIC, specified in a DECLARE statement by AUTOMATIC, or BASED. It can, however, be asterisks. When an asterisk is used, the declared to have the CONTROLLED attribute. length or bounds are taken from the current Thus, there are two classes of parameters, generation of the corresponding argument; as far as storage allocation is concerned: if no current generation exists, any those that have no storage class, i.e., reference to the variable is an error. If 168 an asterisk is used to represent the bounds of one dimension of an array parameter, the bounds of all other dimensions of that parameter must be specified by asterisks. Controlled Parameter Bounds and Lengths The bounds or length of a controlled parameter can be represented in a DECLARE statement either by asterisks or by element expressions. Asterisk Notation: When asterisks are used, length or bounds of the controlled parameter are taken from the current generation of the corresponding argument. Any subsequent allocation of the controlled parameter uses these same bounds or length, unless they are overridden by a different length or bounds specification in the ALLCCATE statement. If no current generation of the argument exists, the asterisks only determine the dimensionality of the parameter, and an ALLOCATE statement in the invoked procedure must specify bounds or length for the controlled parameter before other references to the parameter can be made. Expression Notation: The bounds or length of a controlled parameter can also be specified by element expressions. These expressions are evaluated at the time of allocation. Each time the parameter is allocated, the expressions are re-evaluated to give current bounds or length for the new allocation. However, such expressions in a DECLARE statement can be overridden by a bounds or length specification in the ALLOCATE statement itself. In the procedure MAIN, the arrays A, B, C, and D are declared with the CONTROLLED If a current generation of the argument storage class attribute; NAME and I are exists at the time of invocation, the AUTOMATIC by default. expressions evaluated at invocation must give the same bounds or length as the When SUB1 is invoked, A and B, which argument. If a current generation does not have been allocated as declared, are exist, then no requirements are made on the passed. SUB1 declares its parameters with values of these expressions. They are the asterisk notation. The ALLOCATE evaluated each time the parameter is statement, however, specifies bounds for allocated, except in those cases where the the arrays; consequently, the allocated expressions are overridden by a bounds or. arrays, which are actually a second length specification in the ALLOCATE generation of A and B, have bounds statement itself. For example: different from the first generation (if no Chapter 12: Subroutines and Functions 169 bounds were specified in the ALLOCATE argument, whose bounds are those of the statement, the bounds of the new generation array parameter. The value of the element would be identical to those of the first expression then becomes the value of each generation). element of the dummy array argument. After control returns to MAIN, the first If a parameter is a structure, the FREE statement frees the second generation argument must be a structure expression or of A and B (allocated in SUB1 as an element expression. If the argument is parameters), and the second FREF statement an element expression, the corresponding frees the first generation (allocated in parameter attribute list must specify the MAIN). structure description of the structure parameter (only level numbers need be used When SUB2 is invoked, C and D are passed -- see the discussion of the ENTRY to X and Y, NAME is passed to NAMEA, and I attribute in Part II, Section I, is passed to N. In SUB2, X and Y are "Attributes," for details). This causes declared with bounds that depend upon the the construction of a dummy structure value of I (passed to N). When X and Y are argument, whose description matches that of allocated, this value determines the bounds the structure parameter. The value of the of the allocated array. element expression then becomes the value of each element of the dummy structure Although NAME (corresponding to NAMEA) argument. The relative structuring of the is not controlled, the asterisk notation argument and the parameter must be the for the length of NAMEA indicates that the same; the level numbers need not be length is to be picked up from the identical. The element value must be one declaration of the argument (NAME). that can be converted to conform with the attributes of all the elementary names of the structure. ARGUMENT AND PARAMETER TYPES If a parameter is an element label variable, the argument must be either an element label variable or a label constant. In general, an argument and its If the argument is a label constant, a corresponding parameter may be of any data dummy argument is constructed. organization and type. For example, an argument may be a statement label, provided If the parameter is an array label that the corresponding parameter is variable, the argument must be an array declared with the LABEL attribute; it may label variable, an element label variable, be an entry name, provided that the or a label constant. If the argument is corresponding parameter is an entry name, either of the latter two, the corresponding and so on. However, not all parameter attribute list must specify that parameter/argument relationships are so the parameter is a label array, giving the clear-cut. Some need further definition bounds of that array. This causes the and clarification. Such cases are given construction of a dummy array label below. argument, whose bounds are those of the label array parameter. If a parameter is an element, i.e., a variable that is neither a structure nor an If a parameter is an entry name, the array, the argument must be an element argument must be an entry name. Note that expression. If the argument is a the name of a mathematical built-in subscripted variable, the subscripts are function can be passed as an argument, but evaluated before the subroutine or function no other built-in function names can be is invoked and the name of the specified passed. element is passed. If the argument is a constant, the attributes of the If a parameter is a file name, the corresponding parameter must agree with the argument must be a file name. The attributes indicated by the constant, attributes of the file name parameter are unless the ENTRY attribute is specified for always ignored. the entry name. If a parameter is a fixed-length string If a parameter is an array, the argument variable, the argument should be a must be an array expression or an element fixed-length string. If the argument is of expression. If the argument is an element varying length, a parameter attribute list expression, the corresponding parameter describing the parameter as a fixed-length attribute list must specify the bounds of string must be given in the invoking the array parameter. (Note, however, that procedure. Similarly, if a parameter is a in this case the bounds in the parameter varying-length string variable, the attribute list cannot be asterisks.) This argument should be a varying-length string. causes the construction of a dummy array If the argument is of fixed length, a 170 parameter attribute list describing the the generic reference; it is that member parameter as a varying-length string must whose parameters match the arguments in be given in the invoking procedure. number and attributes. Whenever a varying-length string argument is passed to a non-varying string parameter A generic name must be declared with the whose length is undefined (i.e. specified GENERIC attribute. The general format of by an asterisk), the maximum length of the this attribute is as follows: argument is passed to the invoked procedure. This is true even when the generic-name GENERIC (member-declaration argument is an element; the object of (,member-declaration]...) passing the maximum length rather than the current length is to maintain a consistent Each member declaration corresponds to rule for both element and array arguments. one procedure entry point in the family. (If the argument were a varying-length It specifies the entry name of the member, string array passed to a non-varying followed by the ENTRY attribute and its undefined-length parameter, only one length associated parameter attribute list; this could be passed, and this would naturally list gives the number and attributes of the be the maximum length.) parameters for that entry name. For example, consider the following statement: Example: DECLARE CALC GENERIC DECLARE A CHARACTER(50) VARYING, (FXDCAL ENTRY(FIXED,FIXED), PROC1 ENTRY (CHARACTER(*)); FLOCAL ENTRY(FLOAT,FLOAT); MIXED ENTRY (FLOAT,FIXED)); A='123'; CALL PROC1(A); This statement defines CALC as a generic name having three members, FXDCAL, FLOCAL, PROC1: PROCEDURE (B); and MIXED. One of these three function DECLARE B CHARACTER(*), procedures will be invoked by a generic C CHARACTER(5); reference to CALC, depending on the characteristics of the two arguments in C=B || '45'; that reference. For example, consider the /* C='123bb' NOT '12345' */ following statement: Z= X + CALC(X,Y); If X and Y are floating-point and fixed-point, respectively, MIXED will be In this example, to pass A, a dummy of invoked. length 50 (i.e., the maximum length of A) is created. In the concatenation operation, '45' is concatenated at the right of the character string of length 50 (which contains '123' followed by 47 Passing an Argument to the Main Procedure blanks). The result is then truncated to fit into C, which has length 5, so that C='123bb'. A single argument can be passed using the PARM field in the EXEC statement for the If a parameter is a locator variable of step executing the PL/I program. See IBM either pointer or offset type, the argument System/360 Operating System, PL/I (F) must be a locator variable of either type. Programmer's Guide. If this facility is If the types differ, a dummy argument is used, the first argument should be declared created. (See also Chapter 14, "Based as a VARYING character string; the maximum Variables and List Processing.") length is 100, and the current length is set equal to the argument length at object time. The argument can also be a fixed-length character string. For Generic Names and References example: TOM: PROC (PARAM) OPTIONS (MAIN); A generic name represents a family of DCL PARAM CHAR(100) VARYING; procedure entry points, each member of which can be invoked by a generic reference, that is, a procedure reference using the generic name in place of the actual entry name. The member invoked is The value in the PARM field of the EXEC determined according to the number and statement for the execution job step will attributes of the arguments specified in be passed to TOM. Chapter 12: Subroutines and Functions 171 Chapter 13: Exceptional Condition Handling and Program Checkout When a PL/I program is executed, a large The programmer may specify whether or number of exceptional conditions are not some conditions are to be enabled, that monitored by the system and their is, are to be checked for so that they will occurrences are automatically detected cause an interrupt when they arise. If a whenever they arise. These exceptional condition is disabled, an occurrence of the conditions may be errors, such as overflow condition will not cause an interrupt. or an input/output transmission error, or they may be conditions that are expected All input/output conditions and the but infrequent, such as the end of a file ERROR, FINISH, and AREA conditions are or the end of a page when output is being always enabled and cannot be disabled. All printed. When checking out a program, a of the computational conditions and the programmer can also get a selective flow program checkout conditions may be enabled trace and dumps by specifying that the or disabled. The program checkout occurrence of any one of a list of conditions and the SIZE condition must be identifiers be treated as an exceptional explicitly enabled if they are to cause an condition. interrupt; all other conditions are enabled by default and must be explicitly disabled Each of the conditions for which a test if they are not to cause an interrupt when may be made has been given a name, and they occur. these names are used by the programmer to control the handling of exceptional conditions. The list of condition names is part of the PL/I language. For keyword Condition Prefixes names and descriptions of each of the conditions, see Part II, Section H, "ON-Conditions." Enabling and disabling can be specified for certain conditions by a condition prefix. A condition prefix is a list of one or more condition names, enclosed in parentheses Enabled Conditions and Established Action and separated by commas, and connected to a statement (or a statement label) by a colon. The prefix always precedes the A condition that is being monitored, and statement and any statement labels. A the occurrence of which will cause an condition name in a prefix list indicates interrupt, is said to be enabled. Any that the corresponding condition is enabled action specified to take place when an within the scope of the prefix. Some occurrence of the condition causes an condition names can be preceded by the word interrupt, is said to be established. NO, without a separating blank or connector, to indicate that the Most conditions are checked for corresponding condition is disabled. automatically, and when they occur, the system will take control and perform some standard action specified for the condition. These conditions are enabled by Scope of the Condition Prefix default, and the standard system action is established for them. The scope of the prefix, that is, the part The most common system action is to of the program throughout which it applies, raise the ERROR condition. This provides a is usually the statement to which the common condition that may be used to check prefix is attached. The prefix does not for a number of different types of errors, apply to any functions or subroutines that rather than checking each error type may be invoked in the execution of the individually. Standard system action for statement. the ERROR condition is: A condition prefix to an IF statement 1. If the condition is raised in a major applies only to the evaluation of the task, the FINISH condition is raised expression following the IF; it does not and, subsequently, the major task is apply to the statements in the THEN or ELSE terminated. clauses, although these may themselves have prefixes. Similarly, a prefix to the ON 2. If the condition is raised in any statement has no effect on the statements other task, that task is terminated. in the on-unit. A condition prefix to a DO 172 statement applies only to the evaluation of The keyword SYSTEM followed by a any expressions in the DO statement itself semicolon specifies standard system action and not to any other statement in the DO- whenever an interrupt occurs. It group. re-establishes system action for a condition for which some other action has been established. The on-unit is used by Condition prefixes to the PROCEDURE the programmer to specify an alternate statement and the BEGIN statement are action to be taken whenever an interrupt special (though commonly used) cases. A Occurs. condition prefix attached to a PROCEDURE or BEGIN statement applies to all the The SNAP option specifies that when an statements up to and including the interrupt occurs, debugging information corresponding END statement. This includes will be written in a debugging file. The other PROCEDURE or BEGIN statements nested form and content of the information depends within that block. It does not apply to upon the implementation. For the F any procedures lying outside that block, Compiler, it is a list of all active which may be invoked during execution of procedures. The information is written in the program. the standard system file SYSPRINT. If SNAP is specified, the action of the SNAP option The enabling or disabling of a condition precedes the action of the on-unit. If may be redefined within a block by SNAP SYSTEM is specified, the system action attaching a prefix to statements within the message is followed immediately by a list block, including PROCEDURE and BEGIN of active procedures. statements (thus redefining the enabling or disabling f the condition within nested The on-unit must be either a blocks). Such a redefinition applies only single,unlabeled, simple statement or an to the execution of the statement to which unlabeled begin block. The single the prefix is attached. In the case of a statement cannot be a RETURN, FORMAT, or nested PROCEDURE or BEGIN statement, it DECLARE statement. It cannot be either of applies only to the block the statement the two compound statements, IF and ON, or defines, as well as any blocks contained a DO-group. (PROCEDURE, BEGIN, END, and DO within that block. When control passes out statements can never appear as single of the scope of the redefining prefix, the statements.) The implementation limit for redefinition no longer applies. A the number of ON-units which can be active condition prefix can be attached to any at any time is 127. The begin block, if it statement except a DECLARE or ENTRY appears, can contain any statement except statement. RETURN, although the RETURN statement can appear within a procedure nested in the begin block. The single statement on-unit, or the The ON Statement begin block on-unit, is executed as though it were a procedure (without parameters) that was called at the point in the program A system action exists for every condition, at which the interrupt occurred. If the and if an interrupt occurs, the system on-unit is a single statement it behaves action will be performed unless the exactly as though it were enclosed by programmer has specified an alternate PROCEDURE and END statements; when action in an ON statement for that execution reaches the END statement of the condition, and that ON statement has been unit, control returns to the point from executed. The purpose of the ON statement which the block was invoked. Just as with is to establish the action to be taken when a procedure, control may be transferred out an interrupt results from an exceptional of an on-unit by a GO TO statement; in this condition that has been enabled, either by case, control is transferred to the point default or by a condition prefix. specified in the GO TO, and a normal return does not occur. Note: The action specified in an ON statement will not be executed during any Note: The specific point to which control portion of a program throughout which the returns from an on-unit varies for condition has been disabled. different conditions. In some cases, it returns to the point that immediately The form of the ON statement is: follows the action in which the condition arose. In other cases, control returns to ON condition-name [SNAP] on-unit the actual point of interrupt, and the SYSTEM; action is reattempted. An example of the latter case is the return from the on-unit (See Part II, Section J, "Statements" for a of an ON CONVERSION statement. When an full description.) interrupt occurs as the result of a Chapter 13: Exceptional Condition Handling and Program Checkout 173 conversion error, control returns from the If more than one ON statement for the on-unit to reattempt conversion of the same condition appears in the same block, character that caused the error (on the each subsequently executed ON statement assumption that the invalid character has permanently overrides the previously been changed during execution of the established condition. No re-establishment on-unit). If the invalid character is not is possible, except through execution of changed, the ERROR condition is raised. another ON statement with an identical action specification (or re-execution, through some transfer of control, of an overridden ON statement). The Null On-Unit A special case of an on-unit is the null statement. The effect of this is to say "when an interrupt occurs as a result of The REVERT Statement this condition, do nothing." Use of the null on-unit is not the same The REVERT statement is used to cancel the as disabling, for two reasons: first, a effect of one or more previously executed null on-unit may be specified for any ON statements. It can affect only ON condition, but not all conditions can be statements that are internal to the block disabled; and, second, disabling a in which the REVERT statement occurs and condition, if possible, may save time by which have been executed in the same avoiding any checking for this condition. invocation of that block. The effect of If a null on-unit is specified, the system the REVERT statement is to cancel the must still check for occurrence of the effect of any ON statement for the named condition, transfer control to the on-unit condition that has been executed in the whenever an interrupt occurs, and then, same block in which the REVERT statement is after doing nothing, return from the executed. It then re-establishes the on-unit. action that was in force at that time of activation of that block. This statement Note: With the F Compiler, a null on-unit has the form: for the CONVERSION condition will not cause a permanent loop if a conversion error occurs, because no conversion is REVERT condition-name; re-attempted unless the invalid character is changed in the on-unit. If it is not A REVERT statement that is executed in a changed, the ERROR condition is raised. block in which no on-unit has been established for the named condition is treated as a null statement. Scope of the ON Statement The execution of an ON statement associates The SIGNAL Statement an action specification with the named condition. Once this association is established, it remains until it is The programmer may simulate the occurrence overridden or until termination of the of an ON condition by means of the SIGNAL block in which the ON statement is statement. An interrupt will occur unless executed. the named condition is disabled. This statement has the form: An established interrupt action passes from a block to any block it activates, and SIGNAL condition-name; the action remains in force for all subsequently activated blocks unless it is The SIGNAL statement causes execution of overridden by the execution of another ON the interrupt action currently established statement for the same condition. If it is for the specified condition. The principal overridden, the new action remains in force use of this statement is in program only until that block is terminated. When checking, to test the action of an on-unit, control returns to the activating block, and to determine that the correct action is all established interrupt actions that associated with the condition. existed at that point are re-established. This makes it impossible for a subroutine If the signaled condition is not to alter the interrupt action established enabled, the SIGNAL statement is treated as for the block that invoked the subroutine. a null statement. 174 The CONDITION Condition immediately after the execution of a statement in which the value of a variable in a check list may have been altered. The ON-condition of the form: Exceptions are as follows: CONDITION (identifier) 1. With the F Compiler, during data-directed input, the interrupt allows a programmer to establish an on-unit occurs after the first checked that will be executed whenever a SIGNAL variable receives its value. statement is executed specifying CONDITION and that identifier. 2. With statement labels and entry names, the interrupt occurs immediately As a debugging aid, this condition can before the execution of the statement be used to establish an on-unit whose or the invocation of the entry name. execution results in printing information that shows the current status of the The system action for the CHECK condition program. The advantage of using this is to print the identifier causing the technique is that the statements of the interrupt and, if it is a variable (other on-unit need be written only once. They than a program control variable); to print can be executed from any point in the its new value in the form of data-directed program through placement of a SIGNAL output. For label variables and other statement. program control variables, only the variable is printed; no value is included. Following is an example of how the CONDITION condition might be included in a Thus, by preceding a block with a CHECK program: prefix, as shown in the example in Figure 11-1, the programmer can obtain selective ON CONDITION (TEST) BEGIN; dumps in a readable format by specifying • variables; he can obtain a flow trace by specifying labels and entry names. • END; The CHECK condition may also be specified in an ON statement, if other than Execution of the begin block would be system action is required. This gives the caused wherever the following statement user all the facilities of PL/I, including appears: the simplicity of data-directed output for controlling and editing his debugging SIGNAL CONDITION (TEST); information. The CONDITION condition always is enabled, but it can be raised only by the SIGNAL statement. The SUBSCRIPTRANGE Condition Another ON condition that is used The CHECK Condition principally for program checkout, but that may also be used in production, is the SUBSCRIPTRANGE condition. This condition The CHECK condition is an important tool must be enabled in a condition prefix. provided in PL/I for program testing. The When it is enabled, each subscript in an keyword CHECK in a prefix list is followed array reference is checked every time it is by a parenthesized name list. The names in evaluated to see that it lies within the the list may be statement label constants, specified bounds. The condition is raised entry names, and variables, including array if any subscript is too high or too low. and structure variables, label variables, task variables, event variables, area Since this checking involves a variables, and locator variables. substantial overhead, it usually is used Subscripted names are not allowed but only in program testing, and is removed for qualified names can be used. Parameters, production programs. and variables with the DEFINED or BASED attributes cannot be checked. The CHECK prefix may be attached only to The STRINGRANGE Condition PROCEDURE or BEGIN statements, and therefore, it always applies to an entire block. The STRINGRANGE condition is not enabled unless it appears in a condition prefix. An interrupt will generally occur It is raised by an invalid reference to the Chapter 13: Exceptional Condition Handling and Program Checkout 175 SUBSTR built-in function and out of range, the sample is ignored. If pseudo-variable, the arguments to which there is more than one subscript error or must lie within certain bounds (see "SUBSTR more than one conversion error in a batch, String Built-in Function," in Section G). that batch is then ignored. It allows execution to continue with a SUBSTR reference that has been revised either automatically (that is, by standard The numbers to the right of each line system action) or by the programmer using are card sequence numbers, which are not an on-unit. part of the program itself. The CHECK prefixes in cards 1 and 25 are included to help with debugging; in a Condition Built-In Functions and Condition production program, they would be removed. Codes The prefix in card 1 specifies that interrupts will occur at the following times: just before the statements HEADER, When an on-unit is invoked, it is as if it NEWBATCH, and BADBATCH are executed; just were a procedure without arguments. It is before the procedure INPUT is invoked; and therefore impossible to pass to the on-unit whenever the value of the variable SAMPLE any information about the interrupt (other changes. Since no ON statement has been than the name of the condition). To assist executed for the CHECK condition, system the programmer in making use of on-units, action is performed. This will result in some special functions are provided that the appropriate name being written on may be used to inquire about the cause of SYSPRINT (together with the new value in an interrupt and possibly to attempt to the case of SAMPLE). correct the error. Since the labels used within the These condition built-in functions can internal procedure INPUT are not known in be used only in on-units or in blocks DIST, they cannot be specified in a CHECK invoked by on-units. They are listed in list for DIST. A separate CHECK prefix is Part II, Section G, "Built-In Functions and therefore inserted just before the Pseudo-Variables." procedure statement heading INPUT. This check list specifies the labels in INPUT, The condition built-in functions provide and the array TABLE. information such as the name of the procedure in which the interrupt occurred, It is worth noting again that the CHECK the character or character string that condition prefix can be applied only to caused a conversion interrupt, the value of PROCEDURE and BEGIN blocks, and not to the key used in the last record individual statements. The first statement transmitted, and so on. Some can be used executed is the ON ENDFILE statement in as pseudo-variables for error correction. card 9. This specifies that the external procedure SUMMARY is to be called when an The ONCODE function provides a binary ENDFILE interrupt occurs. This action integer whose value depends on the cause of applies within DIST and within INPUT and the last interrupt. This function, used in within all other procedures called by DIST, conjunction with the ERROR condition, unless they establish their own action for allows the programmer to deal with errors ENDFILE. that may be detected by the implementation, but that are not represented by condition Throughout the procedure, any conditions names in the language. except SIZE, SUBSCRIPTRANGE, STRINGRANGE, and CHECK are enabled by default; and for all conditions except those mentioned explicitly in ON statements, the system Example of Use of ON-Conditions action applies. This system action, in most cases, is to generate a message and then to raise the ERROR condition. The The routine shown in Figure 13-1 action specified for the ERROR condition in illustrates the use of the ON statement, card 13 is to display the contents of the the SIGNAL and REVERT statements, and card being processed. When the ERROR condition prefixes. The routine reads action is completed, the FINISH condition batches of cards containing test readings. is raised, and execution of the program is Each batch has a header card with a sample terminated. number, called SNO, of zero and a trailer card with SNO equal to 9999. If a The statement in card 10 specifies conversion error is found, one retry is action to be taken whenever a CONVERSION attempted with the error character set to interrupt occurs. Since this action zero. Two data fields are used to consists of more than one statement, it is calculate a subscript; if the subscript is bracketed by BEGIN and END statements. 176 The main loop of the program starts with The card read is assumed to be a header the statement HEADER. Since the CHECK card. If it is not, the SIGNAL CONVERSION condition is enabled for HEADER, an statement causes execution of the BEGIN interrupt will occur before HEADER is block, which in turn calls a procedure (not executed. The READ statement with the INTO shown here) that reads on, ignoring cards option will cause a CHECK condition to be until it reaches a header card. The begin raised for the variable specified in the block ends with a GO TO statement that INTO option (unless, for the F Compiler, terminates the on-unit. the EVENT option is used); consequently, the input is listed in the form of The GET statement labeled NEWBATCH uses data-directed output. the STRING option to get the different test numbers that have been read into the Figure 13-1. A Program Checkout Routine Chapter 13: Exceptional Condition Handling and Program Checkout 177 character string READINGS, which is an explicitly enabled by a SUBSCRIPTRANGE element of SAMPLE. Since the variables prefix for an interrupt to occur. If an named in the data list are not explicitly interrupt does occur, the on-unit causes a declared, their appearance causes implicit transfer to ERR2, which establishes a new declaration with the attributes FLOAT on-unit for SUBSCRIPTRANGE interrupts, DECIMAL (6). overriding the action specified in the ON statement in card 35. Any subsequent The array TABLE is initialized to zero subscript errors in this batch will, before the procedure INPUT is called. This therefore, cause control to go to BADBATCH, procedure inherits the on-units already which signals the CONVERSION condition as established in DIST, but it can override it existed in the procedure DIST. Note them. that on leaving INPUT, the on-action reverts to that established in DIST, which The first statement of INPUT establishes in this case calls SKIPBCH to get to the a new action for CONVERSION interrupts. next header card. Whenever an interrupt occurs, the ONCODE is tested to check that the interrupt is due to an illegal P format input character and After establishment of a new on-unit, a that the illegal character is a blank. If message is printed, and a new sample card the illegal character is a blank, it is is read. replaced by a zero, and control is transferred to ERR1. The statement labeled IN1 reads an 80-column card image into the structure ERR1 is internal to the procedure INPUT. SAMPLE. A READ statement does not cause The statement, REVERT CONVERSION, nullifies input data to be checked for validity, so the ON CONVERSION statement executed in the CONVERSION condition cannot arise. INPUT and restores the action specified for conversion interrupts in DIST (which causes The statement IN2 checks and edits the the batch to be ignored). data in card columns 11 through 19 according to the picture format item. A non-numeric character (including blank) in these columns will cause a conversion After a routine is called to write an interrupt, with the results discussed error message, control goes to IN2, which above. retries the conversion. If another conversion error occurs, the interrupt The next statement (card 41) has a action is that specified in cards 10 and SUBSCRIPTRANGE prefix. The data just read 11. is used to calculate a double subscript. If either subscript falls outside the The second ON statement in INPUT bounds declared for TABLE, an interrupt establishes the action for a SUBSCRIPTRANGE occurs. If both fall outside the range, interrupt. This condition must be two interrupts occur. 178 Chapter 14: Based Variables and List Processing The purpose of this chapter is to describe different allocations of one based the PL/I based storage facilities currently variable. In other words, reference to the implemented by the F Compiler, and to give based variable can be qualified by a some indication of their use. pointer value. The pointer variable is one of two types of locator variable. The other type, the offset variable, is discussed later. Introduction The based variable can be a structure containing a locator for another Storage allocation is the association of allocation, which in turn can contain a the requisite amount of storage with a locator for yet another allocation, and so variable; it is effectively a two-way on. This is the fundamental concept process: the storage is associated with a underlying PL/I list processing; different variable, and the variable is associated allocations can be chained together in a with the storage. Allocation will be made specific order. In fact, they can be either statically (that is, before the chained together in several different program is executed), or dynamically (that orders at once by using several different is, during execution). A statically sets of locators. Thus, for example, it is allocated variable remains allocated for possible to sort a list without duplicating the duration of the program, but a the list items or moving them around; any dynamically allocated variable may sequence can be specified by a set of relinquish its storage before the program locators. This facility can also be used has finished. to chain like items together without necessarily implying a particular order. The storage class attributes determine which kind of allocation is to apply to a A list or chain of associated based given variable. STATIC specifies that variables could be scattered over a large allocation will be made statically; area of storage, linked only by pointers. AUTOMATIC, CONTROLLED, and BASED each However, to facilitate input/output and specify a type of dynamic allocation. assignment, the based variables can be Automatic storage is allocated collected together into a reserved area. automatically on entry to the block in The relative locations of the items can which the variable is declared, and freed then be established. The reason for this automatically when the block is terminated; provision is that the value of a pointer is once freed, the value of the variable is absolute and refers to only one allocation lost. Controlled storage allocation is of a variable; for example, if a list of under the direct control of the programmer, associated based structures containing using the ALLOCATE and FREE statements. pointers were written out and later read in Based storage allocation is also under the again, this would constitute a direct control of the programmer, but with reallocation, within which the pointer some essential differences from controlled values would be meaningless because the allocation. addresses would be different. However, another kind of locator variable, called an When the programmer reallocates a offset variable, is available, which controlled variable without first freeing establishes the location of an item it, the value of the earlier allocation is relative to the start of an area. Because not lost. All values are held, but in such it is relative, the value of an offset a way that only one value is available for variable retains its meaning across use at a given time. Effectively, the input/output and assignment. values are stacked. On the other hand, when a based variable is reallocated As well as providing a list processing without first being freed, all the values facility, based storage allows the are not only held, but are also available programmer to make more efficient use of for use at any time. record-oriented input/output. This type of input/output normally involves the use of Whenever a based variable is allocated, intermediate buffers and work areas; but a a pointer variable is set to a value based variable can be virtually overlaid on relating to the address of the allocation; a buffer, and processing can take place by including this pointer variable in a within the buffer. Several separate based reference to the based variable, the variables can be effectively overlaid on programmer can distinguish between the same buffer at once; this allows easy Chapter 14: Based Variables and List Processing 179 handling of files containing different The pointer variable must be neither types of record. (The type of record would subscripted nor based; a qualified name is be designated within the record itself; the allowed. For example: correct based variable could then be determined from a test made after the P -> X = Q -> X; record has been read into the buffer.) This type of input/output using based This statement means simply that the value variables is the PL/I form of locate mode of one allocation of X is to be assigned to input/output. another allocation of X; the X allocated in the location associated with P is to be made equal to the X allocated in the location associated with Q. The appearance Based Variables and Pointer Variables of P and Q in the statement contextually declares them as pointer variables, unless explicit declarations exist for P and Q. A based variable is a variable that can be allocated in more than one location in The arrow, or pointer qualifier, is a storage, thus simultaneously representing a composite symbol made up of a minus sign number of values, any of which can be followed by a greater-than sign. Its retrieved by specifying a pointer variable equivalent in the 48-character set is PT. associated with the relevant storage It does not signify an operation; its location. function is similar to that of the period symbol in an ordinary qualified name. When a based variable is declared, it is associated with a pointer variable. The form of the declaration is: RULES AND RESTRICTIONS identifier BASED (pointer-variable) Example: Full details of the rules governing based variables and pointer variables are given DECLARE X BASED (P); under the respective attributes in Section I, Attributes. However, the following This declaration also contextually declares points should be carefully noted: P to be a pointer variable unless an explicit declaration for P exists. Pointer 1. Based variables may not have the variables can be declared explicitly, with EXTERNAL, VARYING, or INITIAL the following format: attributes. identifier POINTER 2. The bounds of based arrays and the lengths of based strings must be When an unqualified reference is made to declared using decimal integer the based variable, the value of the constants, with the exception that the pointer variable included in the REFER option (see "The REFER Option" declaration will be used to determine which in this chapter) allows one adjustable allocation is concerned. For example: array bound, string length, or area size to be declared within a based X = X + 1; structure. In this statement, the pointer variable 3. Based label arrays cannot be used to determine the location of X will in initialized by subscripted label both cases be P; that is, the references to prefixes. X are implicitly qualified by the pointer P. Note, however, that X could have been 4. Based variables cannot be checked by explicitly qualified by other pointer means of a CHECK condition prefix. variables. Explicit pointer qualification is discussed below. 5. Based variables cannot be transmitted using data-directed input/output. 6. The pointer variable qualifying a POINTER QUALIFICATION based variable (whether implicitly or explicitly) cannot itself be based, nor can it be subscripted; it must be Reference to a based variable can be an element variable, or an element of explicitly qualified by means of the a structure; a qualified name is following format: allowed. (Arrays of pointer variables are allowed, but the value of an pointer-variable -> based-variable element of such an array would have to 180 be assigned to an element pointer variable contained within the structure variable before it could be used to itself. This variable is given a value qualify a based reference.) when the structure is allocated; the value is assigned from a variable outside the 7. Pointer variables cannot be operands structure. Note that the variable outside of any operators except the comparison the structure is used only on allocation operators = and ¬=. The value of a (either by an ALLOCATE statement or by a pointer variable can be compared with LOCATE statement); for any other reference that of any other locator variable, or to the structure (such as READ with SET, with a locator value returned by a e discuss d later in this chapter), the function. variable inside the structure will apply. 8. Assignment of a pointer variable value can be made only to another locator variable. 9. Pointer variables cannot be transmitted using STREAM input/output. The REFER Option 10. The pointer variable declared with a based variable is not given the value The REFER option is used in the declaration of the NULL built-in function by the of a based structure to specify that, on declaration. allocation of the structure, the value of a variable outside the structure is to be 11. Only the INITIAL CALL form of the assigned to an element of the structure, INITIAL attribute is allowed in and that this value will be the length, pointer declarations. size, or bound of another element of the same allocation of the structure. 12. The implementation of offsets and pointers does not support bit addressing. This restriction has no The REFER option has the following practical effect on ALIGNED bit general form: strings. With UNALIGNED bit strings belonging to arrays or structures, element-variable REFER (element-variable) however, only offsets or pointers to major structures or minor structures The element variables must be unsubscripted with byte (or higher) alignment should fixed binary integer variables, and can be be used. fullword or halfword, but must have the same precision. The variable on the Note: The allocation of a based variable left-hand side of the keyword must not will always take at least eight bytes of belong to the structure; it can be storage, even if the based variable is a qualified or pointer-qualified. The bit-string variable of length 1. variable on the right-hand side must belong to the structure. For example: Pointer Defining DCL 1 STR BASED (P), 2 Y FIXED BINARY, A pointer variable can be defined on 2 Z (B.X REFER (Y)); another pointer variable using overlay or correspondence defining. This declaration specifies that the based structure STR will consist f an array Z and an element Y; when STR is allocated, the upper bound of Z is set equal to the SELF-DEFINING DATA current value of B.X, and this value is assigned to Y. For any other reference to the variable, the bound value is taken from A self-defining record is one which Y. contains, within itself, information about its own fields, such as the length of a Note that this option can be used only string. PL/I allows the programmer to once in a declaration. If it is used to declare a based structure in a way that is specify an array bound, the bound must be designed to help manipulate such data. The the upper bound of the leading dimension of F Compiler supports this to a limited the element with which it is used, and the extent: a based structure can be declared dimension must belong to the last element in the structure declaration, or to a minor ,t o have one adjustable array bound, string length area size, governed by a structure containing the last element. Chapter 14: Based Variables and List Processing 181 For example: the element variable has a value equal to or less than the value it had when DCL 1 STR BASED (P), allocated. The number of elements or 2 A, the string length actually written 3 B FIXED BINARY, will be that indicated by the current 3 C (20), value of the variable. 2 D, 3 B FIXED BINARY, For example: 3 C (0:X REFER (D,B), 0:9); DCL 1 REC BASED (P), In this declaration, the REFER option is 2 N, used to specify an adjustable upper bound 2 A (M REFER(N)), |for the array D.C; in this case, it could M INITIAL (100); not have appeared in any place other than that shown. Note that even though the rule states that the variable on the right-hand side of the REFER keyword must belong to ALLOCATE REC; the structure containing the REFER option, this variable must still be sufficiently N = 86; qualified to avoid ambiguity with members of other structures. In this case, a WRITE FILE (X) FROM (REC); reference to B alone would not be sufficient, since structure A also contains In this example, 86 elements of REC are a member named B. This would apply even if written. It would be an error to attempt A and D were separate major structures. to free REC at this point, since N must be restored to the value it had when allocated Note: Since the adjustable bound must be (i.e. 100). If N was assigned a value part of the leading dimension of the greater than 100, an error would occur when element with which it is declared, it is the WRITE statement was encountered. not possible for that element to inherit a dimension from a higher level. (Inherited dimensions would automatically become the Pointer Setting, Based Storage Allocation, leading dimensions of the lower-level member.) and Input/Output For example: Before a reference can be made to a based variable, the qualifying pointer variable DCL 1 STR BASED (P), must have a value. This value can be set 2 D (10), in any of five different ways: 3 E (50), 3 F (50); 1. With the SET option of a READ statement; In this declaration, both E and F would have implied bounds of 1:10, inherited from 2. By a LOCATE statement; D; the REFER option could not have been used with them but could have been used 3. By an ALLOCATE statement; with D (in place of 10). 4. By assignment of the value of another If the REFER option is used to specify a locator variable, or a locator value string length, that string must be an returned by a user-defined function; element variable, and it must be the last element variable in the structure 5. By assignment of an ADDR built-in declaration. function value. If the element variable on the Note that the actual value is in all right-hand side of REFER varies during the cases set by the implementation. The program then: programmer has no direct control over addressing; he cannot, for example, assign 1. The structure must not be freed until a constant to a pointer variable. the element variable is restored to the value it had when allocated; A special form of assignment to a pointer variable is made using the NULL 2. The structure must not be written out built-in function. This assigns a special while the element variable has a value value to the pointer, that cannot be greater than the value with which it related to any address; its purpose is to was allocated. give a positive indication that the pointer does not currently identify any allocation 3. The structure may be written out when of a variable. 182 READ WITH SET The pointer variable can be any variable that represents a single pointer value. The READ statement with the SET option has the following basic format: This statement allocates storage, in an READ FILE (file-name) output buffer, for a based variable. The SET (pointer-variable); action is similar to that of the READ and SET, in that the based variable is, in The pointer variable can be any variable effect, overlaid on the buffer. In this that represents a single pointer value. case, however, data is moved (by subsequent This form of the READ statement causes a statements) into the output buffer in such record to be read into a buffer and the a way that the fields of the record are specified pointer variable to be set to located relative to the elements of the point to the buffer. A based variable based variable; the record is automatically reference, qualified by the same pointer, written onto the specified file immediately will then relate to the fields of the before execution of the next WRITE, LOCATE, record. or CLOSE statement (or implicit close operation) for the file. This means that A based variable used to describe a the programmer must assign values to the record in a buffer is effectively overlaid variable after allocation and before the on the buffer. The result of a reference next input/output operation on the file. to an element of the based variable is the same as it would be if the record had been read directly into the structure described. Again, a pointer variable is set to point to the buffer. This pointer variable If the REFER option is used in the will be that specified in the SET option, declaration of a structure, and the pointer if the option appears; if the option is to the structure is set by a READ statement omitted, the pointer variable that was with the SET option, the value for the declared with the specified based variable appropriate array bound, string length, or is set. area size is taken from the variable inside the structure (i.e., from the record itself), not from the variable outside the structure. For example: ALLOCATE WITH AND WITHOUT SET The ALLOCATE statement, as used with based variables, has the following basic format: ALLOCATE based-variable [IN(area-variable)] [SET(pointer-variable)]; The effect of this statement is similar to that of the LOCATE statement, in that it allocates storage for the based variable and sets a pointer to point to the In this example, when REC is first allocation. In this case, however, no allocated, the array A has 100 elements and output is implied; the storage is not N has the value 100. On execution of the allocated in a buffer. If the SET option READ statement, however, the number of appears, the specified pointer variable is elements in the array is specified in that set; if the option is omitted, the pointer part of the record effectively overlaid by variable that was declared with the N; the value of M has no effect. specified based variable is set. LOCATE WITH AND WITHOUT SET The IN option, if included, specifies that the allocation is to be made within the reserved area of storage named. Areas The LOCATE statement has the following are discussed in detail later in this basic format: chapter. The area variable can be any variable that represents a single area; the LOCATE based-variable FILE (file-name) pointer variable can be any variable that [SET (pointer-variable)]; represents a single pointer value. Chapter 14: Based Variables and List Processing 183 POINTER ASSIGNMENT overlaid on the third element in the second row of C. (This technique, like the other overlaying techniques made possible by the The value of a pointer variable may be use of based variables and pointers, is assigned to another pointer variable in a extremely powerful; however, such simple assignment statement. Assume that P techniques should be used only with the and Q are pointer variables and that P has understanding that the compiler has no a valid pointer value. means of recognizing incompatibilities between the attributes of the based Q = P; variable and the attributes of the variable being effectively overlaid.) This statement specifies that Q is to be set to point to the same location that P points to. A reference to a based variable Since ADDR returns a single value only, qualified by Q will then be effectively the elements of an array or structure identical to a reference to the same based argument must occupy successive locations variable qualified by P. For example in storage. For example: (assuming that X is a based variable associated with the pointer P by DCL A(10,10); declaration), the references X, P -> X, and Q -> X will be identical in effect. For the array declared above, ADDR would not be permitted for the cross-section A(*,10), because each element in the cross-section would belong to a different The ADDR Built-in Function row, and would be separated from its column neighbor by other elements in its row. ADDR would, however, be permitted for the The value returned by the ADDR built-in cross-section A(10,*); this cross-section function is a valid pointer value that consists of one entire row whose elements specifies the location of a data variable occupy successive locations in storage. named as the argument of the function reference. For example: Note also that since the F Compiler implementation of based storage does not P = ADDR (X); support bit addressing, the argument to the ADDR built-in function must be aligned on a Execution f this statement will give byte (or higher) boundary. In the case of the pointer variable P a value so that it bit strings belonging to unaligned arrays points to the location of the data variable and structures, therefore, ADDR should be X. The value of an ADDR function reference used only for the level 1 name or for minor can be assigned to a locator variable only. structures that are not composed entirely of bit strings. The argument can be a variable that represents an element, an array, a structure, an area, an element of an array, a minor structure, or an element of a structure. The value returned is always a The NULL Built-in Function pointer value. Note that if a based variable has not been allocated, its ADDR is undefined; however, the ADDR value of an The NULL built-in function requires no unallocated controlled variable is null. arguments; it returns a null pointer value (that is, a special pointer value that The ADDR of an element of an array or cannot relate to any address in storage). structure returns a value that relates to Its purpose is to provide a positive the address of the element. However, a indication that a pointer does not pointer qualifying a subscripted or currently identify any allocation of a qualified variable is assumed to point to variable. Examples of its use include the the array or structure in which the element following: is contained, not to the element itself. For example: 1. If NULL is assigned to a pointer at the start of a program, a later test DCL A (10,10) CHARACTER (20) BASED (P), of the pointer against NULL will show B CHARACTER (20) BASED (Q), whether a based variable qualified by C (10,10) CHARACTER (20); the pointer has been allocated or not. Given this declaration,if ADDR (C) is 2. A terminal pointer in a chain can be assigned to P, then A (1,1) will refer to set to the value of NULL so that the the first element of C. If ADDR (C(2,3)) beginning or end of the chain can be is assigned to Q, then B is effectively recognized. 184 Freeing Based Storage /*THIS IS IN ERROR BECAUSE STORAGE EQUIVALENT TO 40 ELEMENTS OF X IS LEFT UNFREED*/ The storage that has been associated with a based variable by one of the allocation Based storage allocated in a task cannot methods described above can be freed be freed by a FREE statement in a explicitly or, in certain cases, descendant task, unless it has been implicitly, for possible re-use. Once the allocated within an area belonging to the storage for a based variable has been descendant task (that is, an area that was freed, a reference to the associated allocated in the descendant task). pointer becomes invalid. It is an error to attempt to free based variables that have not been allocated. THE FREE STATEMENT IMPLICIT FREEING The FREE statement, as applied to based variables, has the following basic format: In certain circumstances, based storage is FREE qualified-reference freed without the use of an explicit FREE (IN(area-variable)] statement, as follows: (,qualified-reference (IN(area-variable)]]...; 1. Storage that has been allocated by the LOCATE statement is freed after the where "qualified-reference" is defined as: variable is written out. (pointer-variable ->] based-variable 2. Storage that has been effectively allocated by a READ statement with the This statement frees the storage SET option is freed by the next read associated with one or more allocations of or close operation on the file. one or wore specified based variables. The allocations are identified by the current 3. All storage is freed at the end of the values of the specified pointers. If a task in which it was allocated, unless pointer is omitted, it is assumed to be it was allocated within an area that declared with the based variable belonging to another task. (Storage concerned. allocated within an area is freed on termination of the task in which the IN (area-variable) must be specified if area was allocated.) the allocation was made within an area; otherwise, it must be omitted. Areas are discussed later in this chapter. Areas and Offsets The amount of storage freed depends on the attributes of the based variable, including the current value of any Based variables can be allocated within an adjustable bound or length specification. area of storage that has been reserved by The programmer is responsible for ensuring allocation of an area variable. This has that the amount freed coincides with the the effect of grouping the data items amount originally allocated. For example: together so that they can be easily transmitted or assigned as a single unit DECLARE 1 S BASED (P), while still retaining their individual 2 N, identities. The items stay in their 2 X(M REFER (N)); relative locations, which can be identified by offsets from a pointer that identifies the start of the area. This does not mean that pointers cannot be used within areas; M = 50; however, offsets have the advantage of ALLOCATE S; remaining valid during area transmission /*X HAS 50 ELEMENTS AND THE VALUE OF N IS and assignment. SET TO 50*/ Offsets, like pointers, can be used to build chains of data; however, they cannot be used directly as based variable M = 80; /*THIS HAS NO EFFECT ON THE qualifiers nor can they appear in a SET CURRENT ALLOCATION OF S*/ option. Assignment from pointer to offset F -> N = 10; implies conversion to offset; similarly, FREE S; assignment from offset to pointer implies Chapter 14: Based Variables and List Processing 185 conversion to pointer. Hence, an offset 3. C is an automatic area variable whose variable can be given a value by assigning size depends on the value of N current a pointer value to it; and, in order to use at the time of entry to the block. an offset as a qualifier, its value is assigned to a nonbased pointer. Rules and Restrictions AREA VARIABLES The following rules apply to area variables: The AREA attribute defines an area of storage that is to be reserved for the 1. Data of the area type cannot be allocation of based variables. It has the converted to any other data type; an following general format: area can be assigned to an area variable only. AREA ((expression)] 2. No operators can be applied to area The number of bytes of storage is variables. specified by the integral value of the expression, if present; otherwise, an 3. Only the INITIAL CALL form of the implementation defined value of 1000 bytes INITIAL attribute is allowed with area is assumed. This value is the size of the variables. area. 4. When an area is allocated, it is The implementation defined maximum size automatically given the EMPTY state of an area is 32,767 bytes. (see "The EMPTY Built-in Function" in this chapter, for explanation of The size of an area is the amount of EMPTY). storage that is reserved by the area allocation for the allocation of based variables. The amount of the reserved storage that is actually in use is known as OFFSET VARIABLES the extent of the area; it is defined as the amount of storage between the start of the reserved area and the end of that Declaration of an offset variable must be unfreed allocation which is furthest from explicit. The OFFSET attribute has the the start of the area. In addition to the following form: declared size, the implementation requires an extra 16 bytes of control information, OFFSET (variable) giving such details as the size, and the length of the current extent. These 16 The variable within the parentheses must bytes are allocated immediately before the be an unsubscripted level 1 based area start of the reserved area, and are added variable. to the area size to obtain the length of the area (that is, the actual amount of The function of an offset variable is to storage needed for the area allocation). provide a locator value that points to the The distinction between area size and location of a based variable relative to length is important to the discussion of the start of a based area. If the area input/output later in this chapter. containing area is transmitted or assigned, the offsets will still point to the correct Example: locations of the components. DECLARE A STATIC AREA(2000), Example: B AREA, C AREA (N); DECLARE A AREA BASED(P), O OFFSET(A), This statement specifies that: X BASED(Q); 1. A is a static area variable reserving This declaration specifies that A is a 2000 bytes of storage. (The size of based area variable, that the value of 0 an area of static storage class, if will point to a location relative to the specified, must be specified as an start of A, and that X is a based variable. unsigned fixed decimal integer If X were now allocated within A, the value constant.) of its pointer could be assigned to 0 to establish the location of X relative to the 2. B is an automatic area variable start of A. If A and 0 were written out reserving 1000 bytes of storage. and then read back in again, 0 would still 186 point to X relative to the start of A, bytes of storage for allocation of based although the pointer for A itself would variables, and sets V. have been reset. The second ALLOCATE statement causes B to be allocated within the area V -> A, and sets P. Rules and Restrictions The third ALLOCATE statement causes another allocation of B (different from P The following rules apply to offset -> B) to be made within the area V -> A, variables: and sets Q. 1. Offset variables cannot be used to The assignment statement causes the qualify a based reference. value of Q to be converted to offset (relative to the pointer V) and assigned to 2. Assignment of an offset value can be P -> O. Thus, the first allocation of the made only to a locator variable. When structure B contains an offset value that an offset value is assigned to an points to the second allocation of B. The offset variable, the area variables setting of offset values is discussed named in the OFFSET attributes are below. ignored. A pointer value can be assigned to an offset variable, with implicit conversion. SETTING OFFSET VALUES 3. Offset variables cannot be operands of any operators except the comparison operators = and ¬=. The value of an An offset variable can be given a value by offset variable can be compared with assignment only, since it cannot appear in that of any other locator variable, or a SET option, nor is any implicit setting with a locator value returned by any possible. In the above example, P -> 0 was function. given its value by assignment from Q. Note, however, that the reference 0 -> 4. Offset variables cannot be transmitted VALUE, for example, would be invalid, since using STREAM input/output. offsets cannot be used as qualifiers. 5. Offset variables cannot appear in any SET option. The NULLO Built-in Function ALLOCATION WITHIN AN AREA The NULLO built-in function is the offset equivalent of the NULL built-in function as used with pointers. It requires no Based variables are allocated within an arguments, and returns a null value that area by means of an ALLOCATE statement with can be assigned to offset variables only. the IN option. This sets a pointer which can be converted to offset by assignment to Note: A null offset value cannot be an offset variable. For example: converted to a null pointer value, nor can a null pointer value be converted to a null offset value. Therefore, the value of the NULLO built-in function cannot be assigned, even indirectly, to a pointer variable; nor can the value of the NULL built-in function be assigned to an offset variable. For example: The first ALLOCATE statement causes the The second and fourth assignments in the area A to be allocated, reserving 1000 above example would be invalid. They could Chapter 14: Based Variables and List Processing 187 be made valid by inserting IF statements, such as the following: AREA ASSIGNMENT AND INPUT/OUTPUT The value of an area expression can be The AREA ON-Condition assigned to one or more area variables by an assignment statement. Area-to-area assignment has the effect of freeing all The AREA condition is raised in any of the allocations in the target area and then following circumstances: assigning the extent of the source area to the target area, in such a way that all 1. When an attempt is made to allocate a allocations in the source area maintain based variable within an area that their locations relative to each other; contains insufficient free storage for that is, any gaps left by freeing the allocation to be made. operations in the source area are maintained during the assignment (such a 2. When an attempt is made to perform an gap might have been left, for example, if area assignment, and the target area the second of three contiguous allocations contains insufficient storage to had been freed; if the gaps were accommodate the extent of the source automatically closed up, some offset values area. might lose their meaning). 3. When a SIGNAL AREA statement is If a source area containing no executed. allocations is assigned to a target area, the effect is merely to free all The ONCODE built-in function can be used allocations in the target area. to determine whether the condition was raised by an allocation, an assignment, or A possible use for area assignment is to a SIGNAL statement. allow for expansion of a list of based variables beyond the bounds of its original On normal return from the on-unit, the area. When an attempt is made to allocate action is as follows: a based variable within an area that contains insufficient free storage to 1. If the condition was raised by an accommodate it, the AREA condition is allocation, the allocation is re- raised (see below). The on-unit for this attempted. If the on-unit has changed condition could be to change the value of a the value of a pointer qualifying the pointer qualifying the reference to the reference to the inadequate area so inadequate area, so that it pointed to a that it points to another area, the different area; on return from the on-unit, allocation is attempted within the the allocation would be attempted again, new area. Note that if the on-unit within the new area. Alternatively, the does not effectively correct the on-unit could write out the area and reset fault, a loop may result. it to EMPTY. 2. If the condition was raised by an area assignment, or by a SIGNAL statement, execution continues at the point of The EMPTY Built-in Function interrupt. If no on-unit is specified, the system The EMPTY built-in function requires no will comment and raise the ERROR condition. arguments and returns an area of zero size and extent. The effect is to free all allocations in the target area. Input and Output Example: The area facility is designed to allow easy input and output of complete lists of based variables as one unit, to and from RECORD files. The control information is transmitted with the area. Consequently, 188 the record length required is governed by Pointer to Pointer the area length (i.e., area size + 16): the RECORD condition is raised if the length of an area named in the INTO option of a READ No conversion is necessary when a pointer statement, or in the FROM option of a WRITE argument is passed to a pointer parameter; statement, differs from the relevant record normally, therefore, no dummy argument is length. Note that even though the RECORD created, and a change in the value of the condition is raised, incorrect control parameter will be reflected in the value of information will be transmitted; when an the argument. Note, however, that this area is written out, it must not be read reflected change could be avoided, if back into an area of different size. necessary, by passing the argument as an expression in parentheses: this causes a In the case of READ with SET, the length dummy argument to be created. For example: of the input area in the buffer is equal to the length of the area used to create the record. AREA AND OFFSET DEFINING An offset can be defined on an offset, using overlay or correspondence defining. In the declarations of the defined offset and the base offset, the variables named in the two OFFSET attributes need not be the same. Similarly, an area can be defined on an In this example, a change in the value area, using overlay or correspondence of S will be reflected in the value of Q, defining. The base area must have a size but a change in the value of R will have no equal to that of the defined area. effect on P. Communication Between Procedures Similarly to variables of other data types, Offset to Pointer locator and area variables in one procedure can be related to those in another procedure by means of arguments and Passing an offset argument to a pointer parameters, and the general rules are as parameter implies conversion to a dummy described in Chapter 12, "Subroutines and pointer argument, which is then passed to Functions." There are necessarily some the entry point. The entry must be restrictions, which will be explained in declared with the POINTER attribute in the the following discussion; but a general parameter attribute list. For example: rule is that where it is possible to assign the value of one variable to another variable, it is also possible to relate the two variables by an argument and a parameter. ARGUMENTS AND PARAMETERS A locator argument of either pointer or offset type can be passed to a locator parameter only. The parameter can be of either type, but if the argument type differs from the parameter type, a dummy argument is created by the compiler, and a change in the value of the parameter will In this example, the values of P and 0 not be reflected in the value of the are used to obtain the value of the dummy original argument. pointer argument to be passed to PROC4. Chapter 14: Based Variables and List Processing 189 Offset to Offset Area to Area When an offset argument is passed to an An area argument can be passed only to an offset parameter, variables named in the area parameter. If the size of the OFFSET attribute of the offset declarations argument differs from the size appearing in are ignored, just as they are ignored for the parameter attribute list of the offset assignment; if they differ, the fact relevant entry declaration, the argument is that they differ does not imply conversion first assigned to a dummy area argument to a dummy argument. For example: with the size specified in the entry declaration; the dummy argument is then passed to the entry point. The size of an area argument is not considered during selection of a generic entry point. RETURNS FROM ENTRY POINTS An entry point can return a locator value or an area; hence, the PROCEDURE and ENTRY statements and the RETURNS attribute may specify the POINTER, OFFSET, or AREA attributes. In this example, OA would be passed directly to OB. Locator Returns Either type of locator variable can appear Pointer to Offset in a RETURN statement in a procedure that returns a locator value. If the procedure is to return an offset value but the RETURN Passing a pointer argument to an offset statement specifies a pointer, there is parameter implies conversion to a dummy implicit conversion to offset, and vice offset argument, which is then passed to versa. For example: the entry point. The entry must be declared with the OFFSET attribute in the parameter attribute list, and the two OFFSET attribute specifications must name The values of 0 and P are used to obtain the pointer value to be returned. In this example, the values of P and Q are used to obtain the value of the dummy The values of Q and R are used to obtain offset argument to be passed to PROC8. the offset value to be returned. Note that the OFFSET attribute is specified in the The variable following the keyword PROCEDURE statement complete with the name OFFSET is not considered during selection of the relevant area variable; the keyword of a generic entry point. OFFSET alone is not sufficient. 190 Similarly, a locator value returned by a function may undergo implicit conversion. For example: The value of P and the value returned by 0 are used to obtain the pointer value to be assigned to Q. Area Returns If a return statement identifies an area that has an extent different from that specified in the relevant PROCEDURE or ENTRY statement, assignment is made to a dummy area with the correct extent, thus effectively performing a conversion. VARIABLE LENGTH PARAMETER LISTS In PL/I, a procedure can have only a fixed number of parameters, all of which must be specified. However, by passing an array of pointers as a single argument, it is possible to simulate a variable length parameter list, since the array can have adjustable bounds. The following procedure sorts a variable number of based character-string variables according to their values in relation to the collating sequence. The pointers After execution of this procedure, the qualifying these based variables are passed elements of KEYPOINTS will have been as an array argument to the procedure. rearranged so that the first element points to the based variable with the lowest value Assume that the calling procedure according to the collating sequence, the contains an array of pointers, KEYPOINTS, second element points to the based variable with one dimension, which is named as an with the next lowest value, and so on. argument in the CALL statement, and whose Thus, the based variables will have been elements each point to a based logically sorted without changing the character-string variable. physical order of the data. Examples of List Processing Technique The following examples illustrate the use of based storage, locator variables, and areas, for list processing and input/output. Chapter 14: Based Variables and List Processing 191 Figure 14-1. Example of Two-Directional Chain Example 1 /*EXAMPLE 1*/ BUILD_CHAIN: PROCEDURE(ELEMPTR); DECLARE 1 ELEMENT BASED(ELEMPTR), 2 BACK_CHAIN POINTER, This procedure builds a two-directional 2 FWD_CHAIN POINTER, chain through items that are allocated in 2 DATA CHARACTER(50), the calling procedure and identified in ELEMPTR POINTER, turn by passing a pointer parameter. Each (HEAD, TAIL) POINTER STATIC EXTERNAL; item consists of an allocation of a basic structure that contains two pointers and a /*ASSUME THAT HEAD AND TAIL ARE data value (in this case, a character INITIALLY ASSIGNED THE VALUE OF THE string). One pointer identifies the NULL BUILT-IN FUNCTION IN THE PROCEDURE preceding item, and the other identifies THAT CALLS BUILD_CHAIN*/ the following item. The ends of the chain are recognized by a null value for a IF HEAD=NULL contained pointer (for example, the THEN /*FIRST ELEMENT*/ backwards pointer in the first item is HEAD=ELEMPTR; /*SET HEAD POINTER*/ null). The locations of the ends of the chain are identified by a head pointer and ELSE /*NOT FIRST ELEMENT*/ a tail pointer. Figure 14-1 shows a TAIL->FWD_CHAIN=ELEMPTR; diagrammatic representation of the chain. /*UPDATE FWD CHAIN*/ 192 BACK_CHAIN=TAIL; variable. Since a level 2 variable cannot /*UPDATE BACK CHAIN*/ be named in the OFFSET attribute, a dummy level 1 area variable is effectively TAIL=ELEMPTR; /*UPDATE TAIL POINTER*/ overlaid on the level 2 area, and this dummy is named in the OFFSET attributes. FWD CHAIN=NULL; /*SET END INDICATOR OF FWD-CHAIN*/ The procedure sets pointers to the start END BUILD CHAIN; of the area and to each item in the area. These pointers are external, and are Note that the parameter ELEMPTR may therefore known to the calling procedure. identify a nonbased structure, provided that this structure has the same Each area allocation is in output buffer structuring and attributes as ELEMENT. space, and when filled, is written onto a data set, using locate-mode output. This Example 2 output process is controlled by an on-unit for the AREA condition. The items in the This procedure deletes an item from the area are chained by offsets to ensure that chain created by the procedure in example the chain is not invalidated by 1. The item to be deleted is identified by input/output operations on the list. It is a pointer parameter. assumed that the output file is opened and closed by the calling procedure. /* EXAMPLE 2 */ ALTER_CHAIN: PROCEDURE(ELEMPTR); /*EXAMPLE 3*/ DECLARE BUILD_LIST: PROCEDURE(N); 1 FLEMENT BASED(ELEMPTR), DECLARE 2 BACK_CHAIN POINTER, N FIXED BINARY, 2 FWD_CHAIN POINTER, 1 LIST BASED(LISTPTR), 2 DATA CHARACTER(50), 2 FIRST OFFSET(DUMMY); ELEMPTR POINTER, 2 BODY AREA, (HEAD, TAIL) POINTER STATIC EXTERNAL, 1 ELEM BASED(ELEMPTR); (PRED, SUCC) POINTER STATIC; 2 CHAIN OFFSET(DUMMY), 2 STRING, /*SET POINTERS TO PREDECESSOR AND 3 LENGTH FIXED BINARY, SUCCESSOR OF ELEMENT BEING DELETED. 3 DATA CHARACTER(N REFER PRED AND SUCC ARE USED BECAUSE (LENGTH)), BACK_CHAIN AND FWD_CHAIN, BEING BASED, (ELEMPTR, LISTPTR) POINTER STATIC CANNOT BE USED AS QUALIFIERS*/ EXTERNAL, /*THESE POINTERS ARE INITIALIZED TO NULL BY THE CALLING PRED=BACK_CHAIN; PROCEDURE*/ SUCC=FWDCHAIN; LFILE FILE RECORD SEQUENTIAL EXTERNAL, /*UPDATE FORWARD CHAIN*/ LASTELEM POINTER STATIC, IF PRED=NULL DUMMY AREA BASED(DPTR); THEN HEAD= SUCC; /*DELETE HEAD*/ ELSE PRED->FWD_CHAIN=SUCC; ON AREA BEGIN; /*ALLOCATE OUTPUT BUFFER /*UPDATE BACKWARD CHAIN*/ SPACE*/ IF SUCC=NULL LOCATE LIST FILE(LFILE) SET THEN TAIL=PRED; /*DELETE TAIL*/ (LISTPTR); ELSE SUCC->BACK_CHAIN=PRED; DPTR=ADDR(BODY); END ALTER_CHAIN; LASTELEM=NULL; /*INDICATES NEW AREA*/ Example 3 END; This procedure builds a sequential list IF LISTPTR=NULL through several allocations of an area THEN SIGNAL AREA; /*CREATE FIRST AREA*/ variable. Within each area allocation, the ALLOCATE ELEM IN (BODY); /*ELEMPTR IS procedure builds a chain of structure SET AUTOMATICALLY*/ allocations, each of which contains an IF LASTELEM=NULL /*SET FORWARD CHAIN*/ offset identifying the following item in THEN FIRST=ELEMPTR; /*FIRST FLEMENT the chain, a character string value, and a OF AREA*/ value (passed from the calling procedure) ELSE LASTELEM->CHAIN=ELEMPTR; /*OTHER indicating the length of the string. The ELEMENTS*/ location of the first item in the chain is CHAIN=NULLO; /*SET END-OF-CHAIN indicated by an offset attached to the INDICATOR*/ area. This offset is part of a structure LASTELEM=ELEMPTR; /*SAVE POINTER TO NEW containing the first offset and the area; ELEMENT*/ consequently, the area is a level 2 END BUILD_LIST; Chapter 14: Based Variables and List Processing 193 Note that LFILE in examples 3 and 4 ELEMPTR=NULL; /*ALL ELEMENTS should have a record length of 1020 to RETRIEVED*/ accommodate the records created by CLOSE FILE(LFILE); allocations of the structure LIST. This is GO TO EXIT; made up of 1000 bytes (default size for an END; area) plus 16 bytes of area control information, plus 4 bytes for the offset IF LISTPTR=NULL /*FIRST ELEMENT TEST*/ variable FIRST. THEN DO; OPEN FILE(LFILE); Example 4 GO TO READ_AREA; END; This procedure sequentially retrieves the list items created by the procedure in IF LASTELEM->CHAIN=NULLO /*END-OF-AREA example 3. The procedure sets a pointer to TEST*/ the next item in the list, or if the item THEN READ_AREA: /*READ RECORD INTO has been retrieved, sets the pointer to BUFFER*/ null. DO; READ FILE(LFILE) SET (LISTPTR); /*EXAMPLE 4*/ DPTR=ADDR(BODY); GET_ELEMENT: PROCEDURE; ELEMPTR=FIRST; /*SET PTR TO FIRST /*ASSUME THE SAME DECLARATIONS AS IN ELEMENT*/ EXAMPLE 3, AND ASSUME THAT LISTPTR IS END; INITIALIZED TO NULL BY THE CALLING ELSE ELEMPTR=LASTELEM->CHAIN; /*SET PROCEDURE*/ POINTER TO FOLLOWING ELEMENT*/ LASTELEM=ELEMPTR; /*SAVE POINTER TO NEW ON ENDFILE(LFILE) ELEMENT*/ BEGIN; EXIT: END GET_ELEMENT; 194 Chapter 15: Multitasking The use of a computing system to execute a When several procedures are executed as number of operations concurrently is asynchronous tasks, individual statements broadly termed multiprogramming. The PL/I are not necessarily executed simultaneously programmer can make use of the by different tasks; whether this occurs multiprogramming capability of the system depends on the state and resources of the by means of the multitasking facilities system. Hence, at any given time, it may described in this chapter. be necessary for the system to select its next action from a number of different tasks. Each task has a priority value associated with it, which governs this selection process. The programmer can control the priority of the task, within Introduction limits, if he wishes to do so; otherwise, the priority value is set automatically. A PL/I program is a set of one or more procedures, each of which consists of a set of PL/I statements. The execution of these statements constitutes one or more tasks, each of which can be identified by a different task name. A task is dynamic; it exists only while the program is being executed. This distinction between the program and its execution is essential to the discussion of multitasking. One set of statements could be executed several times in different tasks. When the multitasking facilities are not used, the execution of a program constitutes a single task, with a single flow of control; when a procedure invokes another procedure, control is passed to the invoked procedure, and execution of the invoking procedure is suspended until the invoked procedure passes control back to it. This serial type of operation is said to be synchronous; when the programmer is concerned only with synchronous operations, the distinction between program and task is relatively unimportant. With multitasking, the invoking procedure does not relinquish control to the invoked procedure. Instead, an additional flow of control is established, Figure 15-1. Synchronous and Asynchronous so that both procedures can be executed (in Operation effect) concurrently. This process is known as attaching a task. The attached It may be that one task is to run task is a subtask of the attaching task. independently of other concurrent tasks for Any task can attach a number of subtasks. some time, but then become dependent on The task that has control at the outset is some other task (for example, one task may called the major task. This parallel type require the result of another task before of operation is said to be asynchronous. it can be completed). To allow for this, provision has been made for one task to The diagram shown in Figure 15-1 await the completion of an operation at any illustrates the difference between stage of another task before carrying on. synchronous and asynchronous operations. This process is known as task The arrowed lines represent the control synchronization. Information about the flows. Procedures A and B are executed state of an operation can be held by an synchronously; C and D are executed event variable, to which an event name asynchronously. refers. By specifying an event name in a Chapter 15: Multitasking 195 WAIT statement, the programmer can cause input/output; if the overlap is slight, the task to wait for completion of the multitasking could be the less efficient associated operation before proceeding. method, because of the increased system overheads. The programmer can apply the EVENT option to tasks and certain input/output operations, in which case the value of the event variable is set automatically as a result of the operation concerned; or he can set the value explicitly. Specifying Use of Multitasking Facilities The EVENT option allows an input/output operation to proceed asynchronously with the task that initiated it; at any time When multitasking is to be used, the subsequent to the initiation of the keyword TASK must be specified in the input/output operation, the task can await options list of the PROCEDURE statement for its completion. For example, a task can the external procedure. OPTIONS(TASK) display a message to the operator and, cannot be specified for internal instead of waiting for a reply, can procedures; these are called as tasks by immediately proceed, pausing later to deal use of one or more of the multitasking with the reply. options on the invoking CALL statement, as explained below. In general, the rules associated with the synchronous invocation of procedures apply equally to the asynchronous attachment of tasks. For example, on-units established prior to attachment of a subtask are inherited by the subtask, just as if the initial block of the subtask had Creation of Tasks been synchronously invoked. However, asynchronous operation introduces some extra considerations, such as the fact that The programmer specifies the creation of an a number of concurrent tasks can individual task by using one or more of the independently refer to one variable. This multitasking options with a CALL statement. necessitates some extra rules, which are Once a procedure has been activated by described in this chapter. execution of such a CALL statement, all blocks synchronously activated as a result Multitasking also requires some extra of its execution become part of the created rules and provisions for input/output. For task, and all tasks attached as a result of example, without special provision, there its execution become subtasks of the would be nothing to prevent one task from created task. The created task itself is a operating on a record in a DIRECT UPDATE subtask of the task executing the CALL file while another task was operating on statement. All programmer-created tasks the same record; to cope with this, the are subtasks of the major task. EXCLUSIVE file attribute is provided. Tasks can be terminated in a number of different ways. Normal termination occurs when control for the task reaches a RETURN or END statement. The EXIT statement THE CALL STATEMENT specifies abnormal termination of the task and its subtasks, while the STOP statement specifies abnormal termination of the major The CALL statement for asynchronous task (even if STOP is executed in a operation has the same form as that for subtask). When a task is terminated, any synchronous operation, except for the of its subtasks that are still active are addition of one (or any combination) of the abnormally terminated. multitasking options, TASK, EVENT, or PRIORITY. These options, in addition to Multitasking may allow the central their individual meanings (listed below), processing unit and input/output channels all specify that the invoked procedure is to be used more efficiently, by reducing to be executed concurrently with the the amount of waiting time. It does not invoking procedure. necessarily follow that an asynchronous program will be more efficient than an The CALL statement for asynchronous equivalent synchronous program (although it operation can specify arguments to be may be easier to write). It depends on the passed to the invoked procedure, just as it amount of overlap possible between could if the operation were to be operations with varying amounts of synchronous. 196 The TASK Option cases, it allows other processing to continue while the input/output operation is being executed. The TASK option has the following format: TASK [(element-task-name)] The task name can be subscripted and/or qualified. Without the task name, the option merely specifies asynchronous The PRIORITY Option operation. If the task is to have a name, the option must appear complete with the task name, which is thus contextually When a number of tasks simultaneously declared to have the TASK attribute, unless require attention, a choice has to be made an explicit declaration exists. This is by the system. Under the operating system, the only way in which a task can acquire a this choice is based on the relative name. (Explicit declaration of a task importance of the various tasks: a task variable does not associate the task name that has a higher priority value than the with any task.) The name can be used to others will receive attention first. Note control the priority of the task at some that tasks other than those executing the other point, by means of the PRIORITY user's program may require attention from pseudo-variable and built-in function. The the system, and may have a higher priority task name has no other use to the PL/I than any of the user's tasks. programmer. The PRIORITY option has the following format: The EVENT Option PRIORITY (expression) The EVENT option has the following format: EVENT (element-event-name) If this option appears in the CALL statement, the expression is evaluated to a The event name can be subscripted and/or binary integer m, of precision (n,0), where qualified. When this option is used, the n is implementation-defined (15 for the F event name is contextually declared to have Compiler). The priority of the created the EVENT attribute (unless an explicit task is then made m relative to the task declaration exists) and is associated with executing the CALL statement. With the F the completion of the task created by the Compiler the lowest absolute priority CALL statement. Another task can then be possible is 0; the highest absolute made to wait for completion of this task by priority possible is 234. (See "Priority specifying the event name in a WAIT of Tasks," in this chapter.) statement of the other task. If the option does not appear, the An event variable has two separate priority of the attached task is equated to values: a completion value that indicates that of the task variable named in the TASK whether or not the event is complete, and a option, if any, or else equated to the status value that indicates whether the priority of the attaching task. event has been abnormally completed. The completion value is a single bit, and the Examples status value is a fixed binary number of default precision ((15,0) for the F 1. CALL PROCA TASK(T1); Compiler). When the CALL statement is executed, the completion value of the event 2. CALL PROCA TASK(T2) EVENT(ET2); variable is set to '0 ' B (for "incomplete") and the status value to zero (for "not 3. CALL PROCA TASK(T3) EVENT(ET3) abnormally completed"). On termination of PRIORITY(-2); the created task, the completion value is set to '1'B, and, in the case of abnormal 4. CALL PROCA PRIORITY(1); termination, the status value is set to 1 (if it is still zero). The CALL statements in the above examples create four different tasks that The EVENT option can also be specified execute one procedure, PROCA. In example on the READ, WRITE, REWRITE, and DELETE 3, the subtask T3 has a lower priority than statements, and on the DISPLAY statement the attaching task, while in example 4, the with the REPLY option (see Chapter 10, unnamed subtask has a higher priority than "Record-Oriented Transmission"). In these the attaching task. Chapter 15: Multitasking 197 Priority of Tasks T2, task T3 would have a priority of 2; hence, after execution of the second statement, X would have a value of 2. A priority specified in a PL/I source program is a relative value; the actual Between execution of the two statements, value depends on factors outside the source control could pass to task T1, which could program. change the priority of task T2, in which case the value of X would depend on the new Under the IBM System/360 Operating priority. For example, given the same System, the priority associated with each original priorities as before, task T3 job step is provided by the programmer, would have a priority of 26 after execution using the PRTY parameter in the JOB of the first statement. If the priority of statement, or the DPRTY parameter of the task T2 were now changed to 20 by its EXEC statement. This priority can have any attaching task, T1, execution of the second number from 0 through 14: the higher the statement would result in X having a value number, the higher the priority. The of 6. priority of the major task of the PL/I program when it is first entered is given by Coordination and Synchronization of Tasks Priority= (16*(job step priority))+10 This is the maximum priority for the The rules for scope of names apply to program; that is, the highest priority that blocks in the same way whether or not they any task of the PL/I program can have. If are invoked as, or by, subtasks; thus, data an attempt is made to create a subtask with and files can be shared between a higher priority than the maximum asynchronously executing tasks. Hence, a priority, the subtask will be executed at high degree of cooperation is possible the maximum priority. Priority can be between tasks, but this necessitates some reduced to zero, but not below (a priority coordination. Certain additional rules are of less introduced to deal with sharing of data and than zero will be treated as zero files between tasks, and the WAIT statement priority). is provided to allow task synchronization. These conventions must be interpreted carefully when the PRIORITY built-in function or pseudo-variable is used. The SHARING DATA BETWEEN TASKS effect of the statement PRIORITY(T)=N; It is the programmer's responsibility to ensure that two references to the same is to set the priority of the task T equal variable cannot be in effect at one to the priority of the current task plus instant. He can do so by including an the integral value of the expression N. If appropriate WAIT statement at a suitable the priority thus calculated would be point in his source program to force higher than the maximum priority or less temporary synchronization of the tasks than zero, the implementation ensures that involved. Subject to this qualification, the priority is set to the maximum, or and the normal rules of scope, the zero, respectively. following additional rules apply: The PRIORITY built-in function returns 1. Static variables can be referred to in the relative priority of the named task any task in which they are known. (that is, the difference between the actual priority of the named task and the actual 2. Regardless of task boundaries, an priority of the current task). Consider a automatic variable can be referred to task, T1, that attaches a subtask, T2, that in any block in which it is known, or itself attaches a subtask, T3. If task T2 to which it is passed as an argument, executes the sequence of statements or in which it is referred to using an appropriate based variable. (Note PRIORITY(T3)=3; that unless a dummy argument is X=PRIORITY(T3); created, the value of an argument can change at any time; the current value X will not necessarily have the value 3. is used when any reference is made by If, for example, task T2 had an actual any task.) priority of 24, and the maximum priority were 26, then execution of the first 3. Controlled variables can be referred statement would result in task T3 having a to in any task in which they are priority of 26, not 27. Relative to task known. However, not all allocations 198 are known in each task. When a task 1. If a subtask shares a file with its is initiated, only the latest attaching task, the subtask must not allocation, if any, of each controlled close the file. A subtask must not variable is known to the attached access a shared file after its task. Both tasks may refer to this attaching task has closed the file, allocation. Subsequent allocations in even if the attaching task reopens the the attached task are known only file beforehand. within the attached task; subsequent allocations within the attaching task are known only within the attaching 2. If a task shares a file with one of task. A task can free only its own its subtasks, it may close the shared allocations; an attempt to free file, provided that the subtask will allocations made by another task will make no subsequent attempt to access have no effect. No allocations of the the file. controlled variable need exist at the time of attaching. It is not If a file name is known to a task and permissible for a task to free a its subtask, and the associated file was controlled allocation shared with a not open when the subtask was attached, subtask if the subtask will later then the file is not shared; the effect is refer to the allocation. When a task as if the task and its subtask were is terminated, all allocations of separate tasks to which the file name were controlled storage made within that known. That is, each task may separately task are freed. open, access, and close the file. 'This type of operation is guaranteed only for 4. Based variables allocated within an files that are DIRECT in both tasks. Note area are freed when the area is freed; that if one task opens a file, no ether unless contained in an area allocated task can provide the correspondin g close by another task, all based variable operation. allocations (including areas) are freed on termination of the task that It is possible for two or more tasks to allocated them. operate simultaneously on the same record in a DIRECT UPDATE file; this can be 5. Any allocation of any variable of any avoided by use of the EXCLUSIVE file storage class can be referred to in attribute. any task by means of an appropriate based variable reference. The programmer must ensure that the required variable has been allocated at the time of reference. The EXCLUSIVE Attribute SHARING FILES BETWEEN TASKS When access to a record is restricted to one task, the record is said to be locked by that task. The EXCLUSIVE attribute, A file is shared between a task and its which can be specified for DIRECT UPDATE subtask if the file is open at the time the files only, provides a temporary locking subtask is attached. The rules concerning mechanism to prevent one task from such shared files are given below, first as interfering with an operation by another applied to the subtask, and then as applied task. Figure 15-2 shows the effects of to the attaching task. various operations on an EXCLUSIVE file. Chapter 15: Multitasking 199 | Attempted Current State of Addressed Record 1 -T | Operation Unlocked 1 Locked by this task !Locked by another task 1 READ NOLOCK Proceed Proceed 1 Wait for unlock 1 READ 11. Lock record 1 Proceed 1 Wait for unlock 1 12. Proceed 1 1 DELETE/REWRITE 11. Lock record 11. Proceed 1 Wait for unlock 1 12. Proceed 12. Unlock' record 1 1 13. Unlock' record 1 1 V UNLOCK No effect 1 Unlock record 1 No effect V 1 CLOSE FILE Unlock all locked records, and proceed with closing operation 1 Terminate Task |Unlock all records locked by task. Close file, if opened in this task 'The unlocking occurs at the end of the operation, on normal return from any on-units entered because of the operation (that is, at the corresponding WAIT statement when the EVENT option has been specified). If an abnormal return is made from such an on-unit, it is the programmer's responsibility to ensure that the record is unlocked. If the EVENT option has been specified with a READ statement, the operation is not completed until the corresponding WAIT statement is reached; in the meantime, no attempt to delete or rewrite the record should be made. I Figure 15-2. Effect of Operations on EXCLUSIVE Files THE WAIT STATEMENT 1. If transmission ends (or has ended) normally, the event variable is set complete. The WAIT statement has the following format: 2. If the transmission ends (or has WAIT (event-name [,event-name]...) ended) requiring input/output [(element-expression)]; conditions to be raised, the event variable is set abnormal (i.e., its Full details of the WAIT statement are status value is set to 1) and all the given in Part II, Section J, "Statements"; required conditions are raised. The the following is a shorter description, event variable is set complete on providing background to the present return from the last on-unit. The discussion. order in which conditions are raised does not depend on the order in which The WAIT statement specifies that the the event names appear in the list. task executing it will go into a waiting state (that is, execution f the WAIT If an abnormal return is made from an statement will be extended) until such time on-unit entered from the WAIT operation, as some or all of the named events have the associated event variable is set been completed. An event is complete when complete, the WAIT operation is terminated, its completion value is '1'B. Note that and control for the task passes to the the WAIT statement must specify event point specified by the abnormal return. names, not task names. Example The number of events to be awaited is given by the integral value of the P1: PROCEDURE; expression, if present; otherwise all the • named events have to be complete before the task can continue. CALL P2 EVENT(EP2); An event variable named in the list may CALL P3 EVENT(EP3); be associated with an input/output WAIT (EP2, EP3) (1); operation that has been initiated by the task executing the WAIT statement. In this case, execution of the WAIT statement has the following effect: END P1; 200 In this example, the task executing P1 will must not be waited for by two or more proceed until it reaches the WAIT different tasks. statement; it will then await the completion of either the task executing P2, 2. With the F Compiler, an input/output or that executing P3, before continuing. event can be awaited only by the task that initiated it. 3. The following example shows one way in TESTING AND SETTING EVENT VARIABLES which two tasks, T1 and T2, could enter an infinite waiting state: The two values, completion and status, of Task T1 Task T2 (Event E2) an event variable can be retrieved by the built-in functions COMPLETION and STATUS. COMPLETION(EV)='0'B; The COMPLETION function returns the current completion value of the event WAIT (E2); variable named in the argument. This value WAIT (EV); is '0'B if the event is incomplete, or '1'B if the event is complete. 1'B; . ' COMPLETION(EV)= The STATUS function returns the current RETURN; status value of the event variable named in the argument. This value is nonzero if the event variable has been set abnormal, or 0 if it is normal. THE DELAY STATEMENT These two built-in functions can also be used as pseudo-variables; thus, either of The DELAY statement (see Part II, the two values of an event variable can be Section J, "Statements") allows a task to set independently. Alternatively, it is wait for a specified period, without possible to assign the composite value of reference to an event variable. one event variable to another by specifying the event variables in an assignment statement. Thus, the setting of an event variable can be controlled by the programmer. By this means, he can mark the stages of a task; and, by using a WAIT Termination of Tasks statement in one task and an event assignment (from the COMPLETION built-in A task is terminated by the occurrence of function or another event variable) in one of the following: another task, he can synchronize any stage of one task with any stage of another. 1. Control for the task reaches a RETURN or END statement for the initial The programmer should not attempt to procedure of the task. assign a completion value to an event variable currently associated with an 2. Control for the task reaches an EXIT entire task or with an input/output event. statement. An input/output event is never complete until the associated WAIT statement is 3. Control for the task, or for any other executed. task, reaches a STOP statement. Other ways in which an event variable 4. The block in which the task was can be set have already been discussed attached is terminated (either (such as specifying the event name in the normally or abnormally). EVENT option of a CALL statement). Full details of event variables will be found 5. The attaching task itself is under "The EVENT Attribute" in Part II, terminated. Section I, *Attributes." See also "The EVENT Option," in Chapter 10, Termination is normal only if item (1) of "Record-Oriented Transmission." the above list applies. In all other cases, termination is abnormal. Note To avoid unintentional abnormal When tasks are being synchronized, the termination of a subtask, an attaching task following points should be kept in mind: should always wait for completion of the subtask before the task itself is allowed 1. Under the operating system, an event to be terminated. Chapter 15: Multitasking 201 When a task is terminated, the following Programming Example actions are performed: This example shows an application of 1. All input/output events that have been multitasking to a banking system. The initiated in the task and are not yet program is divided into a batch section and complete are set complete, and their a real-time section. Each section status values are set to 1; the constitutes a subtask of the major task; results of the input/output operations each subtask has other subtasks attached to are not defined. it that perform the various data processing routines necessary in each section. The 2. All files that have been opened during use of several subtasks increases the the task and have not yet been closed program efficiency by permitting overlap are closed; all input/output between the input/output operations and the conditions are disabled while this operations performed by the central action is taking place. processing unit. 3. All allocations of controlled variables made by the task are freed. The batch section of the program processes batches of cards that contain 4. All allocations of based variables account information (such as cheques made by the task are freed, except cashed, deposits made, or loan account those it has allocated within an area details) and, after a certain number of allocated by another task (these are transactions, produces a statement. freed when the area is freed). 5. All active blocks (including all The real-time section of the program active subtasks) in the task are provides a means of communication between terminated. itself and the operator, using the DISPLAY statement with the REPLY option. This 6 If the EVENT option was specified when facility permits the user to issue commands the task was attached, the completion to the program through the operator's value of the associated event variable console. These commands can: is set to '1'B. If the status value is still zero, and termination is 1. Cause management or credit abnormal, the status value is set to information, bank statements, or 1. Note, however, that termination of similar information to be made a subtask that has active subtasks has immediately available. no effect on the completion values of event variables associated with these 2. Initiate or terminate processing. active subtasks. Thus the user can initiate the processing of card batches, terminate 7. All records locked by the task are a section of processing, terminate the unlocked. entire program, or reply to a call for clarification of mispunched data. Note: If a task is terminated while it is assigning a value to a variable, the value The functions of the various tasks that of the variable is undefined after make up the program, and their relationship termination. Similarly, if a task is to each other, are shown in Figure 15-3. terminated while it is creating or updating Suggested coding for the ONLINE and PROCESS an OUTPUT or UPDATE file, the effect on the procedures is given below. These associated data set is undefined after procedures are internal to the BANKER termination. It is the responsibility of procedure, as are all the procedures in the the programmer to ensure that assignment program in this case. If they had been and transmission are properly completed external procedures, the PROCEDURE before termination of the task performing statements would have needed the OPTIONS these operations. (TASK) option. 202 ONLINE: PROCEDURE; DECLARE COMMAND CHARACTER(30) VARYING, COMTYPE(8) CHARACTER(30) VARYING, COUNT(8) FIXED BINARY INITIAL ((8)0), ID CHARACTER (72) VARYING, XL(8) LABEL, ENDBEVT EVENT EXTERNAL; COMTYPE(1) = 'CREDIT'; COMTYPE(2) = 'STATEMENT'; COMTYPE(3) = 'INFORMATION'; COMTYPE(4) = 'CALL BATCH'; COMTYPE(5) = 'END BATCH'; COMTYPE(8) = 'END PROGRAM'; START: DISPLAY ('NEXT COMMAND') REPLY (COMMAND); /*TASK IS IN WAITING STATE UNTIL REPLY IS RECEIVED*/ X: DO I = 1 TO 8; IF COMMAND = COMTYPE (I) THEN GO TO XL(I); END; DISPLAY ('UNRECOGNIZABLE COMMAND, REPEAT') REPLY (COMMAND); GC TO X; XL(1): DISPLAY ('ACCOUNT ID') REPLY (ID); COUNT(1) = COUNT(1) + 1; CALL CREDIT (ID) PRIORITY (-1); /*ATTACH CREDIT TASK*/ CO TO START; XL(2): XL(5): COMPLETION (ENDBEVT) = '1'B; /*SETS EVENT COMPLETE IN BATCH. BATCH WILL TERMINATE WHEN ALL CARDS READ IN*/ GO TO START; END ONLINE; Chapter 15: Multitasking 203 PROCESS: PROCEDURE; DECLARE ANS CHARACTER (30) VARYING, (READEVT, ENDEVT, TEVREAD, TEVUPDT, TEVRED) EVENT EXTERNAL; WS: WAIT (READEVT, ENDBEVT) (1); IF COMPLETION(READEVT)= ' 1 ' B THEN GO TO READIN; WAIT (TEVREAD, TEVUPDT, TEVRED) (3); EXS: EXIT; /*IF 'END BATCH' COMMAND WAIT FOR ASSOCIATED TASKS BEFORE BATCH IS TERMINATED*/ READIN: COMPLETION (READEVT) = '0'B; CALL READER TASK (PR1) PRIORITY (-1) EVENT (TEVREAD); CALL UPDATE TASK (PR2) PRIORITY (-2) EVENT (TEVUPDT); CALL RED TASK (PR4) PRIORITY (-3) EVENT (TEVRED); WAIT (TEVREAD, TEVUPDT, TEVRED) (3); DISPLAY ('CARDS PROCESSED') REPLY (ANS); IF ANS = 'WAIT' THEN GO TO WS; /*WAIT FOR COMMAND*/ IF ANS = 'READ' THEN GO TO READIN; /*PROCESS NEXT PATCH*/ END PROCESS; 204 Major task PRIORITY = P 1 BANKER: PROC OPTIONS(MAIN, TASK);| |CREDIT: PROC(X); | Function: r- >|What is X's credit | Initialization, e.g., open master| Subtask CONTROL PRIORITY = P-1 |rating? | files. r L J Attach on-line control task: F----> ONLINE: PROC; CALL ONLINE TASK(CONTROL) Function: PRIORITY (-1) EVENT (TEVCTRL);| DISPLAY ('Next command') 1 WAIT (for command or CONTROL <--1 REPLY (command) |STATEMENT: PROC(Y):| termination): Attach task according to command, or F–F->|Print statement for| If command, attach subtask satisfy a WAIT statement in a diff- |Y's account. BATCH, then return to WAIT F-1 erent task by completing its event I J If termination, end program | | variable. The same procedure can be J | attached several times as different tasks. r 1 Priorities should be in the range |MANIFO: PROC; | V (P-3) to (P-10). F->| Extract management | Subtask BATCH PRIORITY = P-2 |information. | I / | PROCESS: PROC; V Function: |WAIT satisfied| Initialization of card processing |CREDIT: PROC(Z); | routines. F j F-> | What is Z's credit | WAIT1 (for 'Read' or 'End batch' <--I | |rating? commands). CALL (processing tasks). F-- -1 WAIT2 (for cards to be processed) DISPLAY ('Cards processed, any V more?'). Other REPLY ('No more', 'Read', or tasks 'Wait'): If 'No more': terminate BATCH. If 'Read': return to CALL. If 'Wait': return to WAIT1. I. J V V V Subtask PR1 PRIORITY = P-11 Subtask PR2 PRIORITY = P-12 Subtask PR4 PRIORITY = P-13 r 1 r r READER: PROC; UPDATE: PROC; RED: PROC; Function: Function: Function: Read cards into array (which Process array information; check Treatment of 'RED' accounts. must have at least three that each row is full before If necessary attach task rows). When one row is processing. for treatment of 'VERY RED' filled, test for completion Update master files, transaction accounts. of processing of next row by files. subtask PR2 before con- When statement 'page' is full, tinuing to read. attach task to print statement. V L Transfer information on a 'RED' Subtask PR5 PRIORITY = P-14 account to a 'RED' array for r 1 processing by 'RED' procedure. |VERYRED: PROC; T- Function: | Print letter for account V owner, and owner's name for Subtask PR3 PRIORITY = P-15 branch manager. L- |STATEMENT: PROC(Account ID); |Function: |Print statement for the account | |identified. I. Figure 15-3. Flow Diagram for Programming Example of Multitasking Chapter 15: Multitasking 205 Chapter 16: Compile-Time Facilities Introduction This chapter is concerned with the first stage; the actual compilation of a program is not discussed. Compile tine is generally defined as that time during which a user's source program is compiled, or translated, into an executable object program. Ordinarily, Preprocessor Input and Output changes to a source program may not be made at this time. The preprocessor interprets preprocessor statements and acts upon the source program However, with PL/I, the programmer does accordingly. Input to the preprocessor is have some control over his source program a sequence of characters that is the user's during compile time. His source program source program. It contains preprocessor can contain special statements (identified statements freely intermixed with the rest by a leading %) that can cause parts of the of the user's source program. Preprocessor source program to be altered in various statements are identified by a leading ways: percent symbol ( % ) and are executed as they are encountered by the preprocessor (with the exception of preprocessor 1. Any identifier appearing in the source procedures, which must be invoked in order program can be changed. to be executed). One or more blanks may separate the percent symbol from the 2. If conditional compilation is desired, statement. the programmer can indicate which sections of his program are to be While checking the preprocessor compiled. statements for correct format and such, the preprocessor also checks the rest of the 3. Strings of text residing in a user source program text to insure that there library or a system library can be are no unmatched comment or incorporated into the source program. character-string delimiters. A percent symbol appearing within a comment or PL/I makes source program alteration at character string is considered to be part compile time possible by a somewhat of that comment or string. This is the different approach to compile time extent of the checking done at this stage processing. Compile time as defined in on all text other than preprocessor PL/I has two stages: statements. 1 The Preprocessor Stage -- During this Output from the preprocessor consists of stage, the user's source program is a new character string called the scanned for preprocessor statements, preprocessed text, which consists of the special statements that cause the altered source program and which serves as preprocessor to alter the text being input to the processor stage. Note that scanned. These statements are preprocessor statements are replaced by considered part of the source program, blanks in the preprocessed text. and appear freely intermixed with the statements and other text of the source program. The altered source program, resulting from the action of PREPROCESSOR SCAN the preprocessor statements, then serves as input to the second stage. Note that the preprocessor stage is The preprocessor starts its scan of the optional; the publication IBM input text at the beginning of the string System/360 Operating System PL/I(F) and scans each character sequentially. As Programmer's Guide, describes how this long as a preprocessor statement is not stage can be used or avoided for the encountered, the characters are placed into F-level PL/I Compiler. the preprocessed text in the same order and general form in which they were scanned. 2. The Processor Stage -- During this However, when a preprocessor statement is stage, the output from the first stage encountered, it is executed. This is compiled into an executable object execution can cause the scanning of the program. source program and the subsequent formation 206 of preprocessed text to be altered in accompanied by the assignment of a either of two ways: replacement value. 1. The executed statement may cause the For example, if the source program preprocessor to continue the scan from contained the following sequence of a different point in the program. statements: This new point may very well be one that has already been scanned. %DECLARE A CHARACTER, B FIXED; %A = 'B+C'; 2. The executed statement may initiate %B = 2; replacement activity. That is, it may X = A; cause an identifier not appearing in a preprocessor statement to be replaced then the following would be inserted into when that identifier is subsequently the preprocessed text in place of the above encountered in the scan. The sequence: replacement value will then be written into the preprocessed text in place of X = 2+C; the old identifier (see "Rescanning and Replacement" below for details). In this example, the first statement is a preprocessor DECLARE statement that The scan is terminated when an attempt activates A and B and also establishes them is made to scan beyond the last character as preprocessor variables. (An identifier in the source program. The preprocessed must be established as a preprocessor text is completed and the second stage of variable before it can be assigned a value compilation can then begin. in a preprocessor statement; it can be so established only through a preprocessor DECLARE statement.) The second and third statements are preprocessor assignment statements; the second assigns the Rescannin g and Replacement character string 'B+C' to A, and the third assigns the constant 2 to B. The fourth statement is a nonpreprocessor statement¹ For an identifier to be replaced by a new and, therefore, is not executed at this value, the identifier must first be stage. However, because this statement activated for replacement. Initially, an contains A, and A is a preprocessor identifier is activated by its appearance variable that has been activated for in a preprocessor DECLARE statement (i.e., replacement, the current value of A will a % DECLARE statement). (It can be replace it in that statement. Thus, the deactivated by appearing in a % DEACTIVATE string 'B+C' replaces A in the statement. statement and it can be reactivated by But this string contains the preprocessor appearing in a % ACTIVATE statement.) variable B. Upon checking B, the After it has been activated initially, it preprocessor finds that it has been must be given a replacement value. This is activated and that it has been assigned a usually done via the execution of a value of 2. Hence, the value 2 replaces B preprocessor assignment statement. Once an in the string. Further checking shows that identifier has been activated and been 2 cannot be replaced; scanning resumes with given a value, any occurrence of that +C which, again, cannot be replaced. Thus, identifier in text other than preprocessor the chain of replacements comes to an end statements is replaced by that value, and the resulting statement is inserted provided that the identifier is still into the preprocessed text. active when it is encountered by the scan. The new value is not immediately inserted Note that the preprocessor variable B into the preprocessed text, however; it has a default precision of (5,0) and, must be checked to see whether or not it, therefore, actually contains 2 preceded by or any part of it, is subject to four zeros. When this value replaces B in replacement by still another value (a the string 'B+C' it is converted to a rescan is made to determine this). If it character string and becomes 2 preceded by cannot be replaced, it is inserted into the seven blanks (the rules for conversion of preprocessed text; if it can be replaced, decimal fixed-point values to character replacement activity continues until no further replacements can be made. Thus, insertion of a value into preprocessed text 'For the purpose of this discussion, a takes place only after all possible nonpreprocessor statement is any statement replacements have been made. Note that the or set of one or more identifiers that deactivation of an identifier causes it to appears in the source program but is not lose its replacement capability but not its contained in a preprocessor statement, nor value. Hence, the subsequent reactivation in a preprocessor procedure, nor in a of such an identifier need not be comment. Chapter 16: Compile-Time Facilities 207 string are followed). See the section Note that each 1 is actually preceded by "Preprocessor Expressions" for details. seven blanks of its own in addition to the one replacement blank shown. Also note that each time a replacement occurs, a blank is appended to each end of The fifth statement increments the value the replacement value. Hence, in the above of I by 1 and the sixth statement, a example, the first replacement results in a preprocessor IF statement, tests the value blank being appended to each end of the of I. If I is not greater than 10, the string 'B+C', and the second replacement scan is resumed at the statement labeled results in another blank being appended to LAB; otherwise, the scan continues with the each side of the 2 that replaces the B. text immediately following the %GO TO The result, therefore, will have nine statement. Hence, for each increment of I, additional blanks immediately before the 2, up to and including 10, the assignment one additional blank immediately after the statement is rescanned and each occurrence 2, and one additional blank immediately of I is replaced by its current value. As after the C. Replacement values must not contain percent symbols, unmatched quotation marks, or unmatched comment delimiters. The following example illustrates how compile-time facilities can be used to speed up the execution of a DO-loop. A programmer might include the following loop in his program: As before, each number from 1 through 9 is preceded by seven blanks in addition to DO I=1Z(I)=X(I)+Y(I); TO 10; the replacement blank shown; 10 is preceded by six blanks in addition to the END; replacement blank shown. The following sequence would accomplish the When the value of I reaches 11, control same thing, but without the requirements of falls through to the %DEACTIVATE statement. incrementing and testing during execution This statement is interpreted as follows: of the compiled program: subsequent encounters of the identifier I in source program text are not to be %DECLARE I FIXED; replaced by the value 11 in the %I=1; preprocessed text being formed; each I will %LAB:; be left unmodified, either for the Z(I)=X(I)+Y(I); remainder of the scan or at least until I %I=I+1; is reactivated by a %ACTIVATE statement. %IF I<=10 %THEN %GO TO LAB; If I is again activated, it will still have %DEACTIVATE I; the value 11 (unless an intervening preprocessor assignment statement has The first statement activates I and established a new value for I). establishes it as a preprocessor variable. The second statement assigns the value 1 to I. This means that subsequent encounters of the identifier I in non-preprocessor Preprocessor Variables statements will be replaced by 1 (provided that I remains activated). The third statement is a preprocessor null statement A preprocessor variable is an identifier that is used as the transfer target for the that has been specified in a %DECLARE preprocessor GO TO statement appearing statement with either the FIXED or later. CHARACTER attribute. No other attributes can be declared for a preprocessor The fourth statement, not being a variable. Defaults are applied, however. preprocessor statement, is only scanned for A preprocessor variable declared with the replacement activity; it is not executed. FIXED attribute is also given the The first time that this statement is attributes DECIMAL and, for the F Compiler, scanned, I has the value 1 and has been 'precision (5,0) by default (this is also activated. Therefore, each occurrence of I the maximum precision); a CHARACTER in this statement is replaced by 1 and the preprocessor variable is given the VARYING following is inserted into the preprocessed attribute with no maximum length. No text being formed: contextual or implicit declaration of identifiers is allowed in preprocessor Z( 1 )=X( 1 )+Y( 1 ); statements. 208 The scope of a preprocessor variable integer constant. Note that the encompasses all text except those properties of the division operator preprocessor procedures that have are affected. For example, the redeclared that variable. The scope of a expression 3/5 evaluates to 0, rather preprocessor variable that has been than to 0.6. declared in a preprocessor procedure is the entire procedure (there is no nesting of 4. The conversion of a fixed-point preprocessor procedures). decimal number to a character string always results in a string of length When a preprocessor variable has been 8. (Leading zeros in the number are given a value, that value replaces all replaced by blanks and an additional occurrences of the corresponding identifier three blanks are appended to the left in text other than preprocessor statements end of the number, one of which is during the time that the variable is replaced by a minus sign if the number active. If the preprocessor variable is is negative.) inactive (or if it has no value), replacement activity cannot occur for the A character string in an expression corresponding identifier. being assigned to a preprocessor variable may include preprocessor variables, A preprocessor variable is activated references to preprocessor procedures, initially by its appearance in the %DECLARE constants, and operators; preprocessor statement. It can be deactivated and statements cannot be included in such subsequently reactivated by its appearance strings. Note that if the programmer in %DEACTIVATE and %ACTIVATE statements, desires to insert a multiple character respectively. Deactivation of a operator such as 1 = into preprocessed text, preprocessor variable does not strip it of the operator must appear in the source its value; in other words, an inactive program as an entity. For example, one preprocessor variable retains the value it cannot have a 1 A in the source program and had while it was active and can be altered expect a %A='=' statement to generate the by a preprocessor statement or procedure if operator ,= in the preprocessed text. The sc desired. reason is that all replacements cause a blank to be appended to each end of the replacement value. Thus, the hypothetical case cited would result in b=b (where each Preprocessor Expressions b represents a blank) being inserted into the preprocessed text. Preprocessor expressions are written and evaluated in the same way as source program expressions, with the following exceptions: Preprocessor Procedures 1 The operands of a preprocessor expression can consist only of A preprocessor procedure is an internal preprocessor variables, references to function procedure that can be executed preprocessor procedures, decimal only at the preprocessor stage. Its syntax integer constants, bit-string differs from other function procedures in constants, character-string constants, that its PROCEDURE and END statements must and references to the built-in each have a leading percent symbol. The function SUBSTR. Repetition factors format of a preprocessor procedure is as are not allowed with the string follows: constants and the arguments of a reference to SUBSTR must be %label: [label:]... PROCEDURE [(identifier preprocessor expressions. [,identifier] ...)] {RETURNS(CHARACTER|FIXED)}; 2. The exponentiation symbol (**) cannot be used as an arithmetic operator. 3. For arithmetic operations, only [label:]...RETURN decimal integer arithmetic of (preprocessor-expression); precision (5,0) is performed; that is, each operand is converted to a decimal • fixed-point value of precision (5,0) before the operation is performed, and % [label:] ... END [label]; the decimal fixed-point result is converted to precision (5,0) also. More than one RETURN statement may Any character string being converted appear. The general rules governing the to an arithmetic value must be in the statements that can appear within a form of an optionally signed decimal preprocessor procedure are given in the Chapter 16: Compile-Time Facilities 209 description of the %PROCEDURE statement in ARGUMENTS AND PARAMETERS FOR PREPROCESSOR Part II, Section J, "Statements." One FUNCTIONS thing should be noted, however: no statement appearing within a preprocessor procedure can have a leading percent The number of arguments in a preprocessor symbol. function reference must always agree with the number of parameters accounted for in the ENTRY attribute specified for that INVOCATION OF PREPROCESSOR PROCEDURES function in a %DECLARE statement. If parameters are not accounted for, the preprocessor assumes that the corresponding A preprocessor procedure is invoked by a procedure has none and no arguments are function reference in the usual sense; passed. If, however, parameters are i.e., by the appearance of the entry name accounted for, the preprocessor expects to and its associated argument list (if any) find a parenthesized list of arguments, in an expression. The function reference separated by commas and equal in number to can appear in a preprocessor statement or the parameters accounted for in the in a nonpreprocessor statement. However, procedure reference. The number of at least one condition must be met for the parameters accounted for in the ENTRY function to be invoked: regardless of where attribute and the actual number of the reference appears, the function can be parameters in the %PROCEDURE statement, invoked if and only if the entry name used however, need not be the same. The in that reference has been explicitly arguments are interpreted according to the declared with the ENTRY and RETURNS type of statement (preprocessor or attributes in a %DECLARE statement. This, nonpreprocessor) in which the function and not its appearance as a label of a reference appears. The arguments in the %PROCEDURE statement, is what establishes argument list are evaluated before any it as an entry name; in fact, it is not match is made with the parameter list. If even necessary for the preprocessor there are more arguments than parameters, procedure to have been scanned before the the excess arguments on the right are reference is encountered (the procedure has ignored. (Note that for a function only to be in the source program somewhere reference argument, the function is invoked -- anywhere -- when the reference is and executed, even if the argument is encountered). This is the only condition ignored later.) If there are fewer that must be met for a preprocessor arguments than parameters, the excess procedure to be invoked by a reference in a parameters on the right are given values of preprocessor statement. zero, for FIXED parameters, or the null string, for CHARACTER parameters. The A second condition must be met if the usual rules concerning the creation of reference to the preprocessor procedure is dummy arguments apply if the function made in a nonpreprocessor statement: the reference is in a preprocessor statement, entry name used in the reference must be but dummy arguments are always created if active at the time the reference is the function reference occurs in a encountered. Entry names of preprocessor nonpreprocessor statement. functions are the same as preprocessor variables as far as activation and If the function reference appears in a deactivation is concerned; i.e., they must nonpreprocessor statement, the arguments be activated initially by a %DECLARE are interpreted as character strings and statement and they can be deactivated and are delimited by the appearance of a comma reactivated thereafter by %DEACTIVATE and or a right parenthesis occurring outside of %ACTIVATE statements. Thus, since the balanced parentheses. For example, the first condition requires that the entry argument list (A(B,C),D) has two arguments, name appear in a %DECLARE statement, this namely, the string A(B,C) and the string D. second condition would be restrictive only Each argument is then scanned for possible if the entry name had later appeared in a replacement activity. Both the procedure %DEACTIVATE statement. name and its argument list must be found at one replacement level. Thus, only the The value returned by a preprocessor commas and parentheses seen in the text function (i.e., the value of the being scanned when the procedure name is preprocessor expression in the RETURN encountered are considered in this context. statement) always replaces the function After all replacements have been made, each reference and its associated argument list. resulting argument is converted to the type Note that for a reference made in a indicated by the corresponding parameter preprocessor statement, the replacement is attribute in the ENTRY attribute only for that particular execution of the declaration for the function entry name statement; a subsequent scanning of the (i.e., the ENTRY attribute declaration in statement would again result in the the %DECLARE statement). No conversion is invocation of the function. performed if a corresponding parameter 210 Returned Value The value returned by a preprocessor When the scan encounters the last function to the point of invocation is statement, A is active and is thus eligible represented by the preprocessor expression for replacement. Since VALUE is also in the RETURN statement of that function. active, the reference to it in the last Before being returned, this value is statement causes the preprocessor to invoke converted (if necessary) to the attribute the preprocessor function procedure of that (CHARACTER or FIXED) specified in the name. However, before the arguments A and RETURNS option of the function's %PROCEDURE 3 are passed to VALUE, A is replaced by its statement. The attribute of the returned value Z (assigned to A in a previous value must be consistent with the attribute assignment statement), and 3 is converted specified with the RETURNS attribute in the to fixed-point to conform to the attribute ENTRY attribute specification of the of its corresponding parameter. VALUE then %DECLARE statement for the entry name. If performs a concatenation of these arguments the point of invocation is in a and the parentheses and returns the nonpreprocessor statement, the value is concatenated value, that is, the string Z scanned for replacement activity after it (3), to the point of invocation. The has replaced the function reference. The returned value replaces the function replacement of a function reference in a reference and the result is inserted into nonpreprocessor statement involves the preprocessed text. Thus, the surrounding the replacement value by blanks preprocessed text generated by the above (one blank on each end) in the same way sequence is as follows (replacement blanks that it does for the replacement of an are not shown): identifier by the value of the preprocessor variable. Note that the rules for preprocessor expressions do not permit the value DECLARE (Z(10),Q) FIXED; returned by a preprocessor procedure to Q = 6+Z(3); contain preprocessor statements. The preprocessor function procedure GEN Examples of Preprocessor Functions defined in the following example can generate GENERIC declarations for up to 99 parameters. Only four are generated in In the statements below, VALUE is a this example, however. preprocessor function procedure that returns a character string of the form arg1(arg2), where arg1 and arg2 represent Assume that the source program contains Chapter 16: Compile-Time Facilities 211 the following sequence: built-in function SUBSTR can be activated only by a %ACTIVATE statement. If the identifier SUBSTR is given the ENTRY %DCL GEN ENTRY (CHAR, FIXED, FIXED, attribute in a %DECLARE statement, it is CHAR) RETURNS (CHAR); assumed to refer to a user-defined preprocessor procedure of that name. The arguments in a nonpreprocessor statement reference to the built-in function SUBSTR DCL A GEN (A,2,5,FIXED),...; are interpreted in the same way that arguments in any nonpreprocessor statement reference to a preprocessor function are interpreted, that is, as character strings. %GEN: PROC (NAME,LOW,HIGH,ATTR) RETURNS(CHAR); A preprocessor statement reference to DCL (NAME, SUFFIX, ATTR, STRING) SUBSTR is always valid. CHAR, (LOW, HIGH, I,J) FIXED; STRING='GENERIC('; DO I=LOW TO HIGH; /* ENTRY DCL LOOP */ The Preprocessor DO-Group IF I>9 THEN SUFFIX=SUBSTR(I, 7, 2); /* 2 DIGIT*/ The preprocessor DO-group can provide ELSE SUFFIX=SUBSTR(I, 8, 1); iterative execution of the preprocessor /*1 DIGIT*/ statements contained within the group. The STRING=STRING||NAME||SUFFIX|| format of the preprocessor DO-group is as ' ENTRY ('; follows: DO J=1 TO I; /* PAR ATTR LIST*/ STRING=STRING||ATTR; %[label:]... DO i=m1 TO m2[BY m3]]; IF J A reference to SUBSTR in a nonpreprocessor The example below results in the same statement is executed by the preprocessor expansion generated for the example of only if the name SUBSTR is active. The preprocessor loop expansion in the section 212 "Rescanning and Replacement" in this DECLARE 1 PAYROLL, chapter: 2 NAME, 3 LAST CHARACTER (30) VARYING, 3 FIRST CHARACTER (15) VARYING, %DECLARE I FIXED; 3 MIDDLE CHARACTER (3) VARYING, %DO I=1 TO 10; 2 MAN_NO FIXED DECIMAL (6,0), Z(I)=X(I)+Y(I); 3 REGLR FIXED DECIMAL (8,2), %END; 3 OVERTIM FIXED DECIMAL (8,2), %DEACTIVATE I; 2 RATE, 3 REGLAR FIXED DECIMAL (8,2), 3 OVERTIME FIXED DECIMAL (8,2); The second example under "Returned Value" shows how preprocessor DO-groups can Then the following sequence of be used within a preprocessor procedure preprocessor statements: (percent symbols must be omitted, of course). %DECLARE PAYROLL CHARACTER; %PAYROLL='CUM_PAY'; %INCLUDE PAYRL; %DEACTIVATE PAYROLL; %INCLUDE PAYRL; will generate two identical structure declarations into the preprocessed text, Inclusion of External Text the only difference being their names, CUM_PAY and PAYROLL. Execution of the first %INCLUDE statement causes the text in Strings of external text can be PAYRL to be incorporated into the source incorporated into the source program at the program. When the scan encounters the preprocessor stage by use of the %INCLUDE identifier PAYROLL in this included text, statement. Such text, once incorporated, it replaces it by the current value of the is called included text and may consist of active preprocessor variable PAYROLL, both preprocessor and nonpreprocessor namely, CUM_PAY. Further scanning of the statements. Hence, included text can included text results in no additional contribute to the preprocessed text being replacements. The scan then encounters the formed. %DEACTIVATE statement. Execution of this statement deactivates the preprocessor variable PAYROLL and makes the identifier ineligible for replacement. When the The general format and the rules second %INCLUDE statement is executed, the governing the use of the %INCLUDE statement text in PAYRL once again is incorporated are presented in Part II, Section J, into the source program. This time, "Statements." however, scanning of the included text results in no replacements whatsoever, because none of the identifiers in the The text specified by a %INCLUDE included text are active. Thus, two statement is incorporated into the source structure declarations, differing in name program immediately after the point at only, are inserted into preprocessed text. which the statement is executed. The scan therefore continues with the first character in the included text. All preprocessor statements in this text are Preprocessor Statements executed and replacements are made where required. This section lists those statements that can be used at the preprocessor stage and Preprocessor procedures whose briefly discusses those preprocessor declarations appear in external text can be statements that have not yet been explained invoked only after that external text in this chapter. All of the preprocessor becomes included text. The result of a statements, their formats, and the rules preprocessor procedure reference governing their use are described in the encountered before that procedure has been section "Preprocessor Statements" in Part incorporated into the source program is II, Section J, "Statements." undefined. But first, some unrelated comments pertaining to preprocessor statements in Assume that PAYRL is a member of the general should be made: data set SYSLIB and contains the following structure declaration: 1. Some keywords appearing in Chapter 16: Compile-Time Facilities 213 preprocessor statements can be % assignment abbreviated as shown in Part II, % GO TO Section C, "Keywords and % IF Abbreviations." % null 2. Comments can appear within preprocessor statements wherever The preprocessor assignment statement is blanks can appear; however, such used to evaluate preprocessor expressions comments are never inserted into and to assign the result to a preprocessor preprocessed text. variable. All, of the examples shown in this section make use of this statement. 3. All preprocessor statements can be labeled. Such labels must appear immediately following the % (only The % GO TO statement causes the blanks can intervene). All labels preprocessor to interrupt its sequential must be unsubscripted statement label scanning and continue it elsewhere in the constants. (Labels on %DECLARE source program, specifically at the label statements are ignored.) specified in the % GO TO. Thus, it can be useful for rescanning or avoiding text. The functions performed by the following preprocessor statements have already been discussed in this chapter: The % IF statement can be used to control the sequence of the scan according % ACTIVATE to the value of a preprocessor expression. % DEACTIVATE It must have a THEN clause and it can have % DECLARE an ELSE clause. Each clause, as well as % DO each preprocessor statement within the % END clause, must be preceded by a %. Nesting % INCLUDE of %IF statements is allowed and must % PROCEDURE follow the same rules that apply for the RETURN nesting of nonpreprocessor IF statements. Note that the preprocessor RETURN statement cannot have a leading % because The preprocessor null statement is the it can be used only within a preprocessor same as a nonpreprocessor null statement procedure, and all percent symbols must be (except for the %). It can be used to omitted therein. provide transfer targets for %GO TO statements or it can be used in nested %IF Four other statements can be executed at statements to balance the %ELSE clauses. the preprocessor stage: For example, %ELSE%; is a null ELSE clause. 214 Chapter 17: Optimization and Efficient Performance This chapter is concerned with general execution speed). It also provides a list efficiency. It provides information on the of the errors most likely to be encountered ways in which execution speed, compilation by a programmer when he is first using speed, and storage use can be improved, and PL/I. it includes a list of common errors to avoid. Effect of Compilation on Object Program Efficiency Introduction The fifth version of the F Compiler is For a given application, several object capable of optimizing loops and subscripts programs are possible, each of which would (see below). This optimization requires produce the required result. However they the use of extra compiler phases, with a would have varying degrees of efficiency in consequent increase in compilation time; terms of machine time and storage use. The moreover, the results are not guaranteed in efficiency of a PL/I object program depends certain cases of error. For this reason, on two basic factors: provision is made for the programmer to control the degree of optimization by using 1. The way in which the programmer writes the ORDER and REORDER options on the blocks the source program within the PL/I program itself and by using the OPT compiler option in the EXEC 2. The way in which the compiler treats statement for a particular compilation of the source program the program. These two factors are interrelated. The compiler will also, as part of its Firstly, the compiler can perform a limited normal function (i.e., without the use of amount of optimization (i.e., briefly, it special optimization phrases), select the can alter the program during compilation so more efficient of two methods for many that the object program uses less machine operations, provided that the nature of the time but still gives the required result); data allows it to do so. Such operations but the programmer can control the degree include simple assignments, evaluation of of optimization, using the PL/I options string built-in functions, and data ORDER and REORDER and the OPT compiler conversions. option. Secondly, the compiler does not necessarily generate identical object code for a given PL/I item (such as an assignment) every time that item appears in PL/I OPTIONS: ORDER AND REORDER a source program. For example, an assignment may be made either directly or via a compiler-created temporary variable; Strictly speaking, the order in which the data conversion may be performed by in-line statements of a PL/I source program are to code or may require a library call. The be executed is specified by the order in method selected depends on the nature of which they appear in the source program, the data. A knowledge of the circumstances even if the code could be reordered so as in which the compiler generates more to produce the same result more efficient object code can be borne in mind efficiently. The order of execution is by the programmer while he is writing the normally sequential except where modified source program. by a control statement such as GO TO. (See "Control Statements" in Chapter 5, The remainder of this chapter is "Statement Classification.") organized in two main sections. The first, headed "Effect of Compilation on Object The programmer can vary the degree of Program Efficiency," deals primarily with language stringency imposed on the compiler the compiler and the circumstances in which by using the ORDER and REORDER options on it generates more efficient code. The the PROCEDURE and BEGIN statements. second section, headed "Programming REORDER specifies a partial relaxation of Techniques," provides lists of hints that the rules to allow the compiler more the programmer can follow to obtain freedom in optimization. This relaxation different types of efficiency (e.g., is such that if computational or system reduced storage requirements; increased action interrupts occur during execution of Chapter 17: Optimization and Efficient Performance 215 the block, the result is not necessarily execution of the block, the values of the same as it would be under the strict variables modified, allocated, or rules. freed in the block are guaranteed only after normal return from an on-unit or The selected option applies to all when accessed by the ONCHAR and nested blocks unless overridden; if neither ONSOURCE built-in functions. option is specified, the option that applies to the containing block will be assumed. If the block is an external 2. The values of variables modified, procedure, it will be assumed to have the allocated, or freed in an on-unit for ORDER option unless REORDER is explicitly a computational or system action specified. condition (or in a block activated by such an on-unit) are not guaranteed on return from the on-unit into the block, except for values modified by The ORDER Option the ONCHAR and ONSOURCE pseudo-variables. The ORDER option specifies that the normal language rules are not to be relaxed; i.e., A program is in error if a computational any optimization must be such that the or system action interrupt occurs during execution of a block always produces a the execution of the block and this result that is in accordance with the interrupt is followed by a reference to a strict definition of PL/I. This means that variable whose value is not guaranteed in the values of variables set by execution of such circumstances. all statements prior to computational or system action interrupts are guaranteed in an on-unit entered as a result of the interrupt, or anywhere in the program afterwards. Note that the strict definition now Effect of ORDER and REORDER Options -- allows the compiler to optimize common Example expressions,' where safely possible, by evaluating them once only and saving the result, rather than re-evaluating for each reference. Consequently object programs The following example illustrates the produced by the fifth version of the effect of the ORDER and REORDER options: compiler may differ from those produced by previous versions in respect of the number X: PROCEDURE ORDER; of computational or system action DECLARE (A,B,C) (10,10); conditions raised during execution. ON UFL PUT LIST ('UFL WHEN M=',M); ON OFL BEGIN; PUT LIST ('OFL WHEN M=',M); GO TO RESTART; The REORDER Option END; RESTART: GET DATA(M,B,C,D,K); The REORDER option specifies that execution CALL Y; of a block must produce a result that is in PUT DATA(M,A); accordance with the strict definition of GO TO RESTART; PL/I unless a computational or system action interrupt occurs during execution of Y: PROCEDURE REORDER; the block; the result is then allowed to DO I = 1 TO 10; deviate as follows: DO J = 1 TO 10; A(I,J)=B(I+K,J)*C(J,I+K)+D/I+D/K; 1. After a computational or system action END; END; interrupt has occurred during END Y; END X; 'A common expression is an expression that occurs more than once in a program but is In this example, since the values of D and obviously intended to result in the same K are not modified anywhere in procedure Y, value each time that it is evaluated, i.e., the language permits a compiler to keep I if a later expression is identical to an and J in registers, move the computation of earlier expression, with no intervening the expression D/K out of both loops, and modification to any operand, the move the computation of the expressions expressions are said to be common. (D/I and I+K out of the inner loop; thus if 216 this movement was carried out, 2 the LOOP AND SUBSCRIPT OPTIMIZATION expression DIK would be evaluated once instead of 100 times, and the expressions D/I and I+E would be evaluated ten times Four types of loop' and subscript instead of 100 times. Any attempt to use optimization are attempted by the compiler A, I, or J after an overflow interrupt in when the compiler option OPT=2 is procedure Y, and before another value has specified. However, the compiler will not been assigned to them, would be an error. necessarily be able to perform the optimization in every case; its ability to do so is affected by several factors, such as the use of subscripts nested within subscripts, the use of loops containing procedure or begin blocks, or the choice of ORDER and REORDER options. The section headed "Methods of Improvement when OPT=2," under "Improving Speed of Execution," later in this chapter, gives a list of rules that the programmer should follow, when using OPT=2, so as to COMPILER OPTION: OPT=N give the compiler the best chance of carrying out the loop and subscript optimization. In the descriptions of the The OPT compiler option, specified in the four types of optimization, below, the PARM field of the EXEC statement for a indicated choice of block option should be compilation, allows the programmer to interpreted as follows: where it is control the optimization for a particular indicated that optimization will be compilation. For the fifth version of the effected for both ORDER and REORDER, the F Compiler, the option can be specified specification of REORDER will probably with one of three values: result in the greater degree of optimization; however, even where REORDER is stated to be necessary for a particular type of optimization, there will usually be OPT=0 requests fast compilation and, as a some optimization when ORDER is specified. secondary consideration, reduction of the storage space required by The four types of loop and subscript the object program at the expense optimization are as follows: of execution time. 1. Loop control mechanism: The object code for loop control (i.e., the necessary comparison and branching OPT=1 requests fast compilation and, as a instructions generated by the secondary consideration, reduction compiler) will be simplified wherever of object program execution time at possible, The block option may be the expense of storage space. ORDER or REORDER. 2. Loop control variables: The object code for control variables used as OPT=2 requests reduction of object subscripts will be simplified wherever program execution time at the possible. The block option should be expense of compilation time. REORDER. 3. Array expressions: Array expressions (which are effectively a type of loop, The extra optimization phases of the since the specified operation is compiler (i.e., those concerned mainly with performed on each element in turn) loop and subscript optimization) are will be optimized by a combination of invoked only when OPT=2 is specified. the two techniques mentioned above. 'For the purpose of this discussion, a loop is considered to be either an iterative DO-group or an array expression. The discussion does not apply to loops 2The (F) Compiler only optimizes subscript specified by GO TO statements or to expressions, so the expressions DIE and D/I repetitive specifications in data lists for will not be moved out of the loops. stream-oriented transmission. Chapter 17: Optimization and Efficient Performance 217 The block option may be ORDER or IN-LINE OPERATIONS REORDER Operations are performed at execution time 4. Subscript lists: Common expressions in two different ways: they may be handled appearing in subscript lists will be by calls to PL/I library routines or they evaluated at the point of the first may be handled directly by in-line code. occurrence of the common expressions, The saving in execution time for an and the result will be saved for other operation performed in-line can be of the occurrences of the expression. (This order of ten to one or more in relation to applies both inside and outside of a similar operation handled by a library loops.) Subscript expressions that call; the overall effect on program occur within a loop, but whose values execution will depend on the number of never change during the execution of times these operations are used in a the loop, will be evaluated outside of program. It will repay the user, the loop. The block option should be therefore, to recognize those operations REORDER. (Note the difference between that are performed in-line and those that the two types of expression and their require a library call, and to arrange his treatment: a common expression, which program to use the former wherever appears more than once in the program, possible. The majority of the in-line is evaluated at its first occurrence; operations are concerned with data the ether type of expression, which conversion and string handling. occurs within a loop and has a value that remains constant throughout all the iterations of the loop, is evaluated before it occurs. In the latter case, therefore, the compiler Data Conversion reorders the code.) The data conversions performed in-line are shown in Figure 17-1. A conversion outside the range or condition given, or marked "Not done," is performed by a library call. ASSIGNMENT HANDLING Note all of the picture characters available can be used in a picture specification involved in an arithmetic When the expression on the right-hand side conversion. The only ones permitted are: of an assignment statement is an operational expression, or where data 1. V and 9 conversion is necessary, the assignment is usually made via an intermediate temporary 2. Drifting or nondrifting characters $, which holds the result of the expression. S, +, - (See Chapter 4, "Expressions and Data Conversion.") However, the fifth version of 3. Zero suppression characters Z, * the F Compiler produces optimized code that does not use temporary storage in the 4. Insertion characters „ /, B following cases, provided that the FIXEDOVERFLOW and SIZE conditions are For in-line conversions, picture disabled or cannot be raised, and provided specifications with this subset of that the operands are of suitable scale and characters are divided into three types: precision: Picture type 1: Picture specifications consisting entirely of 9s with (optionally) 1. Simple fixed decimal assignments (for a V and a leading or trailing sign or example, A = A + constant; X = A + B ; currency symbol and up to four insertion X = A * B + C;). characters. Examples of type 1 pictures are '99V999', '99', 'S99V9', '99V+', '$99.99' 2. Simple expressions and assignments that involve only character-string Picture type 2: Picture specifications with variables and character-string zero suppression characters and constants (for example, X = A||B;). (optionally) insertion characters and a sign or currency symbol character. Also, type 1 pictures with more than four The block option may be ORDER or REORDER, insertion characters. Examples of type 2 and the OPT compiler option may have any of pictures are 'ZZZ', '**/**9', 'ZZ9V.99', the three possible values. '+ZZ.ZZ', '$/////99' 218 Picture type 3: Picture specifications target. (For example a conversion with drifting strings and (optionally) from FIXED DECIMAL (6,8) or FIXED insertion characters and a sign or currency DECIMAL (5,-3) to PIC '999V99' will symbol character. Examples of type 3 require a library call.) pictures are '$$$$', '-,--9', 'S/SS/S9', '+++9.V9', '$$$9-' 4. The picture specification may have Sometimes a conversion involving a certain characteristics that make the pictured item is not performed in-line even conversion difficult to handle though the picture specification conforms in-line: tc one of the above types. This may be positions in the source and the example, 'ZZV.ZZ', '++V++'). Chapter 17: Optimization and Efficient Performance 219 r Conversion Comments and Conditions | Source Target FIXED BINARY FIXED DECIMAL If either scale factor = 0 and the other scale factor <= 0, then the opt. code may be 0 FIXED BINARY FLOAT If source scale factor = 0, then the opt. code may be 0(whether SIZE is enabled or not) Bit string String must be fixed-length, aligned, and with length <256 Character string Source scale factor must be 0 or Picture String must be fixed-length with length <256 Picture types 1, 2 or 3 FIXED BINARY If source and target scales have the same sign and are non-zero, then the opt. code (SIZE disabled) must be 1 FIXED DECIMAL FIXED DECIMAL FLOAT Source precision must be <10 Bit String Source scale factor must be zero String must be fixed-length, aligned, and with length <256 Character string Source scale factor must be >= 0 String must be fixed-length and length <256 Picture Picture types 1, 2 and 3 For picture types 1 and 2 with no sign, the Opt. code may be 0 |. +- FIXED BINARY Scale factor must = 0 FIXED DECIMAL Target precision must be <=9 and scale factor must = 0 FLOAT FLOAT Source and target may be single or double length Bit string String must be fixed-length, aligned, and with length <256 +- FIXED BINARY Source string must be nonbased, fixed length, aligned, and with length <256 Bit string FIXED DECIMAL Source must be nonbased, fixed-length, length aligned, and and FLOAT with length <32 Bit string Source must be nonbased, and source and target must be aligned with <2040 L1___ _1_ 1 1 J •Figure 17-1. Implicit Data Conversions Performed In-Line 220 Conversion Minimum Opti- | mization Code Comments and Conditions Source Target Disabled|EnabledSIZE | SIZE 1— +- +- + 1 Target length must be <=256 0 0 <=256Source and target lengths must be 0 0 Source and target lengths must be O 0 <=256 1— -1 Character string String must be fixed-length with 0 length <256 Picture Pictures must be identical 0 Source precision must be <10 1 Not done If picture has a sign, then the opt. O Not done code must be 1 Source precision must be <10 1 Not done Picture Picture types 1, 2 or 3 1 Not done +- 1 Label Label O | 0 F +- 1 | Pointer/Offset |Pointer/Offset 0 | .a. •Figure 17-1. Implicit Data Conversions Performed In-Line (continued) String Handling another, depending largely on the method of implementation of the language features concerned. However, it should be realized The string operations and built-in at the outset that a primary cause of functions performed in-line are shown in program inefficiency occurs at the problem Figures 17-2 and 17-3. Note that even the definition stage, before any actual string functions indicated as always being programming is done: PL/I cannot be used to performed in-line may sometimes require a full advantage unless the problem is library call. For example, if the defined in terms of PL/I. expression in the BIT or CHAR function requires an implicit conversion not handled The third part deals with the use of in-line, the appropriate library routine storage. Then follows a list of common will be called. errors to avoid, and finally a short list of additional hints. a. Improving the speed of compilation Programming Techniques b. Improving the speed of execution. In PL/I there are often several different The purpose of this section is to help ways of producing a given effect. One of the programmer make the best use of the these ways will usually be more efficient PL/I (F) Compiler. The first two parts are from a particular point of view than presented from two different viewpoints: Chapter 17: Optimization and Efficient Performance 221 String Operation Comments and Conditions T -+ Assign Non-adjustable, aligned, fixed- Non-adjustable, aligned, fixed- length bit string <2048 bits long length bit string <2048 bits long Non-adjustable, aligned, bit Non-adjustable, aligned, VARY- string <2048 bits long ING bit string <2048 bits long (OPT=0) Non-adjustable, unaligned, fixed- Non-adjustable, unaligned, fixed- length bit string that is a length bit string that is a scalar element of an AUTOMATIC, scalar element of an AUTOMATIC, BASED or STATIC structure with no BASED or STATIC structure with no adjustable bounds or extents adjustable bounds or extents. The string must be 1 bit long. Note: The assign- Fixed-length or VARYING Fixed-length or VARYING character ment VARYING string character string <256 characters string <256 characters long to fixed-length long string is not handled in-line 'And', 'Not', 'Or' Non-adjustable, ALIGNED, fixed-length or VARYING bit strings, with length: fixed-length - <2048 bits VARYING - 532 bits Compare Non-adjustable fixed-length character strings <256 characters long Non-adjustable, ALIGNED, fixed-length or VARYING bit strings, with length: fixed-length - <2048 bits VARYING - <=32 bits Concatenate Non-adjustable fixed-length or VARYING character strings <256 characters long Non-adjustable, aligned, fixed-length or VARYING bit strings <=32 bits long STRING function Scalars and non-adjustable contiguous array or structure variables | Notes: 1. Operations with VARYING strings require OPT=1. 2. If the expression in an IF statement is a bit string satisfying the conditions for the source string when OPT=0, then, if the string is <10 bits long, in-line code is generated to test the value of the string. •Figure 17-2. Conditions under which the String Operations are Handled In-Line 222 r procedures to a minimum. Do not use | String Comments and Conditions BEGIN-END to effect statement Function grouping; this is more simply obtained +- by use of DO-groups. BIT Always 3 Try to avoid using the ATR, XREF, BOOL Non-adjustable, ALIGNED bit LIST, DECK, and CHAR48 compiler strings, where the third options, and specify OPT=0 or 1 rather argument is one of the logical than 2. operators 'and', 'not', 'or' or exclusive 'or' 4. Avoid features which give rise to large dictionary entries and large CHAR Always amounts of text. For example, INDEX Second argument must be a DCL A PIC '(4000)X'; non-adjustable character string <256 characters long occupies one complete dictionary block. LENGTH Always 5. Use of the following features causes SUBSTR STRINGRANGE must be disabled optional compiler phases to be loaded: ALLOCATE, LIKE, CHECK, iSUB defining, TRANSLATE First argument must be a built-in functions with aggregate fixed-length character string arguments, GENERIC entry names, of length <= 256. If a third DELAY/DISPLAY. If any of these argument is given, both second features can be completely avoided and third arguments must be without extensively increasing the character-string constants; if source code, there will be a a third argument is not given, corresponding increase in compilation the second argument may be any speed. fixed-length character-string argument, including constants. 6. On re-runs, further slight increases in efficiency can be obtained by UNSPEC Always a. removing all unreferenced labels VERIFY The first and second arguments and data; must be fixed-length character strings of length <= 256 and <= b. correcting all source errors, and, 4096 respectively. If second where possible, minimizing the argument is a constant, the number of diagnostic messages function is partially performed produced, including such messages at compile time. If both as "FILE/STRING option missing in arguments are variables, the GET/PUT statement"; function is performed at execution time. In both cases, c. subdividing the program if the no library call is necessary. auxiliary storage has been used; •Figure 17-3. Conditions under which the d. specifying the NOSOURCE option; String Functions are Handled In-Line e. specifying the FLAGS option. See also "Compiler Storage," under "Reducing Storage Requirements," below. IMPROVING SPEED OF COMPILATION The following measures are suggested for IMPROVING SPEED OF EXECUTION use where compilation time is an important factor. By using the OPT=2 compiler option and the 1. Allocate as much storage to the REORDER block option, the programmer allows compiler as possible, using the the compiler to optimize loops and SIZE=999999 option on the EXEC subscripts (see "Effect of Compilation on statement. This reduces the chances Object Program Efficiency," above). of bringing the spill mechanism into However, there is a significant increase in operation. compilation time and results are not guaranteed in certain cases of error. The 2. Keep the number of BEGIN blocks and recommended procedure is to specify REORDER Chapter 17: Optimization and Efficient Performance 223 where possible in the program but to more efficient object code is produced suppress the optimization phases in the by the GO TO if it refers to a label early stages of developing the program, by within the same block rather than to a using OPT=0 or 1; when the program is fully label outside the block. developed it can be compiled during OPT=2. 5. Keep IF clauses simple; separate any Even when OPT=0 or 1 is specified, the multiple conditions into a series of programmer can increase the execution speed simple IF statements. For example: by following certain rules; and when OPT=2 is specified, he can increase the amount of IF A=B optimization by following another set of THEN IF C=D rules. For this reason, the information in THEN IF E=F this part is given first in terms of OPT=0 THEN GO TO M; or 1, and then in terms of OPT=0. 6. Avoid extensive use of adjustable arrays and/or CONTROLLED storage. Methods of improvement when OPT=0 or 1 7. Use constants wherever possible instead of expressions. The following measures are suggested for 8. Exercise care in specifying precision. use where both compilation time and For example, execution time are important factors. Note that while some of these measures may slow DCL A FIXED DEC(8,4), down the compilation, this is offset by the B FIXED DEC(10,0), fact that others will accelerate it. In C FIXED DEC(10,1); the main, there should be no serious increase in compilation time. 1. If the use of storage is not as C=A+B; important as speed of execution, use OPT=1. Avoid the STMT option as code This requires almost twice as much will be generated. Use of the code as it would if P had been statement/offset table is more declared (10,4), because the efficient since no code is generated. evaluation of A+B requires a scale factor of 4. 2. Avoid unnecessary program segmentation and block structure; all procedures, 9. Use the PICTURE attribute only when ON-units and BEGIN blocks need necessary. For example, use FIXED prologues and epilogues, the DECIMAL(5,0) instead of PIC'999V99'. initialization and housekeeping for If a picture field is used in more which carry a considerable overhead. than one arithmetic operation, convert (Prologues and epilogues are described it once and then use the new form in in Appendix C of this publication.) each operation. This holds for any Whenever possible, use GOTO or IF conversion required more than once. statements to control program logic, rather than the CALL statement. If it is necessary to use data with the PICTURE attribute in arithmetic 3. Branching in IF statements can be expressions, use pictures that will be improved by using DO and END handled in-line, as this considerably statements to bracket a THEN clause, reduces execution time. Pictures with rather than using a GOTO statement in all 9s, a V and a non-drifting sign the THEN clause. For example: are particularly useful. For example: IF A=B THEN DO; '999' C=D; '$99v99' E=F; 's99' END; 'V999' L: etc. 10. Internal switches and counters, and is more efficient than data involved in substantial computation or used for subscripts, IF A=B THEN GO TO L; should be declared BINARY; data C=D; required for output should be kept in E=F; DECIMAL form. L: etc. Note: On model 50 machines and above 4. When GO TO is used in an IF statement, half-word binary instructions are 024 slower than full-word binary. Key Bit strings used as logical switches variables should therefore be declared should be specified according to the full-word binary, but not precision 31 number of switches required. In the as this inhibits certain types of examples below, (a) is preferable to optimization. Precisions of (16,0) or (b), and (b) to (c): (17,0) are recommended. 11. Keep data conversions to a minimum. Some possible methods follow: 1. Single Switches a. Use additional variables. For example, if a problem specifies that a character variable has to (a) DCL SW BIT(1) INIT ('1'B); be regularly incremented by 1, • DCL CTLNO CHAR(18); IF SW THEN DO; • CTLNO = CTLNO+1; • (b) DCL SW BIT(8) INIT('1'B); requires two conversions, while • DCL CTLNO CHAR(8), DCTLNO DEC FIXED; IF SW THEN DO; • • DCTLNO=DCTLNO+1; (c) DCL SW BIT(8) INIT('1'B); CTLNO=DCTLNO; requires only one conversion. IF SW = '10000000'B THEN DO; b. Take special care to make structures match when it is intended to move data from one structure to another. c. Avoid mixed mode arithmetic, especially the use of character strings in arithmetic 2. Multiple Switches calculations. 12. Declare arrays in the procedure in (a) DCL B BIT(8); which they are used, instead of • passing them as arguments. Declare subscript variables in the block in which they are used, as FIXED BINARY B = '11100000'B; (16,0). 13. In multiple assignments to subscripted • variables, restrict the assignment to IF B = '11100000' THEN DO; three variables. 14 If a subscripted item is referred to • more than once with the same (b) DCL B BIT(3); subscript, assign the element to a • scalar variable: • R=(A(I)+1/A(I))+A(I)**A(I); B = '111'; • should be replaced by • • ASUB=A(I); IF B = '111'B THEN DO; R=(ASUB+1/ASUB)+ASUB**ASUB; 15. Bit strings should, if possible, be specified as multiples of eight bits. Chapter 17: Optimization and Efficient Performance 225 (c) DCL (SW1,SW2,SW3) BIT(1); 26. Consider the use of overlay defining to simplify transmission to or from a character string structure. For example: SW1, SW2, SW3, = '1'B; DCL 1 IN, 2 TYPE CHAR(2), 2 REC, IF SW1&SW2&SW3 THEN DO; 3 A CHAR(5), 3 B CHAR(7), 3 C CHAR(66); GET EDIT(IN) (A(2),A(5),A(7),A(66)); In the above example, each If bit string data is to be held in format-item/data-field pair is matched structures, such structures should be separately, code being generated for declared ALIGNED. each matching operation. It would be more efficient to define a character 16. Note that concatenation operations are string on the structure and apply the time-consuming. GET statement to the string: 17. Varying-length strings are not as DCL STRNG CHAR(80) DEF IN; efficient as fixed-length strings. 18. Fixed-length strings are not efficient if their length is not known at GET EDIT (STRNG) (A(80)); compile time, as in the following example: 27. If a file is declared DIRECT, INDEXED, then the ENVIRONMENT options INDEXAREA DCL A CHAR(N); and NOWRITE should be applied if possible. 19. Avoid using the SIZE, SUBSCRIPTRANGE, STRINGRANGE and CHECK ON-conditions, 28 If storing and restoring of registers except during debugging. Debugging can be omitted, a call to an ENTRY aids should be removed from the which is declared as REDUCIBLE will be program before running it as a optimized. If string and restoring of production job. registers cannot be omitted, and thereby optimization cannot be carried 20. Do not refer to the DATE built-in out, a call to an ENTRY should be function more than once in a run; it declared IRREDUCIBLE. is expensive. Instead, refer to the function once and save the value in a variable for subsequent use; e.g. instead of Methods of Improvement when OPT=2 PAGEA= TITLEA||DATE; PAGEB= TITLEB||DATE; When it is intended that OPT=0 will be used it is more efficient to write for the final compilation, the programmer should use REORDER wherever possible and DTE=DATE; should observe the following points while PAGEA=TITLEA||DTE; writing the program. (Note that this PAGEB=TITLEB||DTE; information is given for guidance only: full optimization may not necessarily take 21. Allocate sufficient buffers to prevent place if the advice is followed; the program becoming I/O bound. conversely, some optimization may take place if the advice is not followed.) The 22. Use blocked output records. following items obstruct loop and subscript optimization, and should be avoided 23. Open a number of files in a single wherever possible: OPEN statement. 1. Subscript expressions that are not 24. In STREAM input/output, use long data fixed-point binary or that contain lists instead of splitting up nested subscripts or function input/output statements. references. 25. Use EDIT-directed input/output in 2. The SUBSCRIPTRANGE condition; this preference to LIST- or DATA-directed. should be enabled only when necessary. 226 3. DO statements that have more than one to one such procedure is an iterative specification and/or a WHILE internal pointer. clause. 10. If storing and restoring of registers 4. Control variables that are not real can be omitted, a call to an ENTRY fixed-point binary integer element which is declared as REDUCIBLE will be variables. optimized. If storing and restoring of registers cannot be omitted, and 5. Expressions in TO and BY clauses other thereby optimization cannot be carried than decimal integer constants or out, a call to an ENTRY should be single variables and expressions of declared IRREDUCIBLE. real fixed-point binary integer type. 6. The SIZE condition when enabled for iterative DO statements. Use of Storage 7. Loops that contain any of the following: If object program storage saving is to be given precedence over execution speed, the a. GET DATA statements OPT=0 compiler option should be applied to the compilation. Apart from this, the b. References to programmer-defined programmer can bear the following functions information in mind while writing his program: c. Procedure calls 1. Wherever possible, data for d. Procedures or begin blocks computation should be binary, rather than decimal. Note that fixed binary e. Statements that are likely to variables of precision less than 16 raise conditions other than (including those with default computational or system action precision) require only two bytes per conditions if the compilation element against four bytes for those contains on-units for such with precision greater than 15. conditions. (For example, if the compilation contains an on-unit 2. If a file declared as INDEXED is to be for an input/output condition, the used for DIRECT UPDATE but will not use of input/output statements have records added to it, the use of within loops should be avoided the ENVIRONMENT option NOWRITE will wherever possible.) save data management about 5000 bytes of storage. 8. Arrays that are parameters and/or do not have constant bounds. 3. The Alignment Attributes: These allow the user to provide alignment for 9. Any of the following types of string and arithmetic data as follows: variable: ALIGNED: Arithmetic: a. Variables with the EXTERNAL FIXED DECIMAL: byte attribute FLOAT(DOUBLE): doubleword Other: word b. Based variables and variables that String: byte are either defined or defined upon UNALIGNFD: Arithmetic and character c. Variables that are parameters. string: byte Bit string: bit d. Variables used as arguments to either the ADDR built-in function Thus the UNALIGNED attribute can be or a programmer-defined function used to obtain denser packing of data returning a pointer value. in main storage, with the minimum of padding. e. Variables used as arguments to an internal procedure when there are Area, pointer, offset, label, task and any pointers in the compilation event data are always aligned on word or doubleword boundaries (see Figure f. Variables used as arguments to K-1). They can never be UNALIGNED. external procedures (other than built-in functions: when there are In data aggregates, the explicitly any external pointers in the declared alignment for the aggregate compilation or when any argument applies to each element in the Chapter 17: Optimization and Efficient Performance 227 aggregate. In structures, however, inherited from D, but it is this alignment can be overridden by an also the default for F if D had alignment specified for a particular not been declared ALIGNED) base element. G is CHAR UNALIGNED For example: The user must take care that the alignment attributes are correct when DCL 1 STR UNALIGNED, matching variables for: 2 A, 2 B ALIGNED, 1. Use of the DEFINED attribute 2 C; 2. Arguments and associated Here A and C will be UNALIGNED and B parameters will be ALIGNED. 3. Accessing different generations Default attributes now depend on the of a based variable. data type of the element concerned, both for data items and for data (In a multiprogramming environment, the agg regates. These defaults are: storage used by object programs can be reduced by use of the shared library UNALIGNED All string data and facility described in the PL/I (F) PICTURE items Programmer's Guide. The effect of this facility will vary between different ALIGNED All arithmetic data i.e., installations, since the shareable library BINARY is built selectively at system generation DECIMAL time.) FIXED FLOAT COMPLEX AVOIDING COMMON ERRORS For example: DCL A PIT(4), This is a list of the errors and pitfalls most likely to be encountered when writing (B CHAR(10), X) UNALIGNED, a PL/I source program. Some of the items (C BIT(12), Y FIXED) ALIGNED; concern misunderstood or overlooked language rules, while others result from Here A is UNALIGNED by default, I is failure to observe the implementation ALIGNED by default, and B, C, X and Y, conventions and restrictions of the PL/I are as explicitly declared. (F) compiler, and are indicated by (I) appearing after the item. DCL (A1(80) CHAR(6), A2(80) BINARY) ALIGNED, B1 (3,3) BIT(2), C1 (3,3) CHAR(4), Source Program and General Syntax Dl (100) DECIMAL; Here A1 and A2 are as explicitly declared, B1 and C1 are UNALIGNED by 1. Keypunch transcription errors may default, and D1 is ALIGNED by default. occur unless particular care is taken when writing the following characters: DCL 1 A, 2 B, 1 (numeral), I (letter), | (or), 2 C BIT(4) UNALIGNED, / (slash), ' (quotation mark); 2 D ALIGNED, 3 E BIT(2), (not), 7 (seven), 3 F, > (greater than); 2 G CHAR(10); L (letter), < (less than). Here A i s a major structure B is FLOAT DECIMAL ALIGNED by O (letter), 0 (zero); default C is explicitly UNALIGNED S (letter), 5 (five); D is a minor structure E is BIT ALIGNED (inherited from Z (letter), 2 (two); D) F is FLOAT DECIMAL ALIGNED by (break character), default(here ALIGNED is - (minus sign); 228 following type are therefore likely to lead to unpredictable storage requests: 2. Ensure that the source program is completely contained within the A: PROC; margins specified by the SORMGIN N=4; option. (I) DCL B(N) FIXED; 3. Inadvertent omission of certain symbols may give rise to errors that • are difficult to trace. Common errors END; are: unbalanced quotation marks; unmatched parentheses; unmatched 2. Missing commas in DECLARE statements comment delimiters (e.g., /* punched are a common source of error. For instead of */ when closing a comment); example, a comma must follow the entry and missing semicolons. for each element in a structure declaration. 4. Reserved keyword operators in the 48-character set (e.g., GT, CAT) must 3. External identifiers should neither in all cases be preceded and followed contain more than seven characters, by a blank or comment. nor start with the letters IHE. (I) 5. Care should be taken to ensure that 4. In a PICTURE declaration, the V END statements correctly match the character indicates the scale factor, appropriate DO, BEGIN, and PROCEDURE but does not in itself produce a statements. decimal point on output. The point picture character produces a point on 6. In some situations, parentheses are output, but is purely an editing required when their necessity is not character and does not indicate the immediately obvious. In particular, scale factor. In a decimal constant, the expression following WHILE and however, the point does indicate the RETURN must be enclosed in scale factor. For example: parentheses. DCL A PIC'99.9', B PIC'99V9', C PIC'99.V9'; Program Control A,B,C=45.6; PUT LIST (A,B,C); This will cause the following values 1. The procedure to be given initial to be put out for A, B, and C, control at execution time must have respectively: the OPTIONS(MAIN) attribute. If more than one procedure has the MAIN 04.5 456 45.6 option, the first one gets control. (I) If these values were now read back into the variables by a GET LIST 2. When a procedure of a program is statement, A, B, and C would be set to invoked while it is still active, it the following respective values: is said to be used recursively. Attempting the recursive use of a 004 56.0 45.6 procedure that has not been given the RECURSIVE attribute may result in a If the PUT statement were then program interrupt after exit from the repeated, the result would be: procedure. This will occur if reference is made to AUTOMATIC data of 00.4 560 45.6 an earlier invocation of the procedure. 5. Separate external declarations of the same identifier must not specify conflicting attributes, either explicitly or by default. If this Declarations and Attributes occurs the compiler will not be able to detect the conflict. PL/I also requires that if an INITIAL value is specified in one declaration of a 1. DECLARE statements for AUTOMATIC STATIC EXTERNAL variable, the same variables are in effect executed at INITIAL value should appear in every entry to a block; sequences of the declaration of that variable. Chapter 17: Optimization and Efficient Performance 229 6. An identifier cannot be used for more DCL X RETURNS (CHAR(4)); than one purpose within its scope. DCL A CHAR(4); Thus, the use of X in the following sequence of statements would be in error: X: PROC CHAR(4); RETURN (I*J*K); PUT FILE (X) LIST (A,B,C); X=Y+Z; END X; X: M=N; 7. It is advisable to declare all entry A=X; points, associated parameter lists, and any return values, to avoid The precision of decimal integer inadvertent clashes of attributes. constants should be taken into account when such constants are passed. For If the attributes of the data items in example: an argument list do not match those declared for the ENTRY, a dummy CALL ALPHA(6); argument is created with the correct attributes, and the data item is ALPHA: PROCEDURE(X); converted into the dummy. For DCL X FIXED DECIMAL; example: END; DCL X ENTRY (FIXED, CHAR(4)), The above example is incorrect because Y FIXED, Z FIXED(1,0); X will be given a default precision, Y=45; while the constant, 6, will be passed Z=0; with precision (1,0). CALL X(Y,Z); 8 When a data item requires conversion X:PROC(A,B); to a dummy, and the called procedure DCL A FIXED, alters the value of the parameter, B CHAR(4); note that the dummy is altered, not END; the original argument. For example: In the above example, a dummy DCL X ENTRY (FIXED, FIXED), is created for the second argument, Z, A FIXED, and is passed to X as 'bbb0' B FLOAT; CALL X(A,B); If the attributes declared for X in the entry name declaration were incompatible with the attributes of the arguments in the CALL statement, the compiler would issue a diagnostic message, and at execution time no conversion would take place. However, if the attributes declared for X in END X; the entry name declaration conflicted with the attributes of the 9. When the attributes for a given corresponding parameters in the identifier are incompletely declared, PROCEDURE statement, the compiler the rest of the required attributes would not detect the disagreement, and are supplied by default. The at execution time the consequences of following default assumptions should such an error would, in general, be be carefully noted. unpredictable. For example, if X were declared FLOAT DECIMAL REAL is assumed for implicitly declared arithmetic DCL X ENTRY (FLOAT, CHAR(4)); variables, unless the initial letter is in the range I through N, when then 45 would be passed as FLOAT, but FIXED BINARY REAL is assumed. would be interpreted by X as FIXED, possibly with disastrous results. If a variable is explicitly declared and any of the base, scale, or mode Similarly, attributes declared for attributes is specified, the others RETURN values must agree in the are assumed to be from the set invoking and invoked procedures; FLOAT/DECIMAL/REAL. For example: however, the actual expression returned may be of any data type and DCL I; /*I IS FIXED BINARY will be converted to that declared. (15,0) REAL For example: AUTOMATIC*/ 230 DCL J REAL; /*J IS FLOAT DECIMAL P AUTO, (6) REAL AUTOMATIC*/ DCL K STATIC; /*K IS FIXED BINARY (15,0) REAL P is first contextually declared to be STATIC*/ a pointer and then, by default, to be FLOAT DECIMAL. DCL L FIXED; /*L IS FIXED DECIMAL (5,0) REAL 16. BASED variables cannot be used as AUTOMATIC*/ arguments or parameters. (I) 10 The precision of complex expressions 17. Offsets must be declared with a level is not obvious. For example, the 1 unsubscripted based area. precision of 1 + 1I is (2,0), that is, the precision follows the rules for expression evaluation. Assignments and Initialization 11 When a procedure contains more than one entry point, with different parameter lists on each entry, make sure that no references are made to 1. When a variable is accessed, it is parameters other than those associated assumed to have a value which has been with the point at which control previously assigned to it and which is entered the procedure. For example: consistent with the attributes of the variable. If this assumption is A: PROCEDURE(P,Q); incorrect, either the program will P=Q+8; RETURN; proceed with incorrect data or a B: ENTRY(R,S); program interrupt will occur. Such a R=P+S; /*THE REFERENCE TO P situation can result from failure to IS AN ERROR*/ initialize the variable, or it can END; occur as a result of the variable having been set in one of the 12. Based storage is allocated in terms of following ways: doublewords; therefore, even for the smallest item, at least eight bytes a. by the use of the UNSPEC are required. (I) pseudo-variable 13. The variable used in the REFER option b. by RFCORD-oriented input must be referred to unambiguously. For example: c. by overlay defining a picture on a character string, with subsequent DCL 1 A, assignment to the character string 2 Y FIXED BIN, and then access to the picture 2 Z FLOAT, 1 B, d. by passing as an argument a 2 Y FIXED BIN variable assigned in a different 2 T(1:N REFER(B.Y)); procedure, without matching the attributes of the parameter. In any references to this declaration, Y must be fully qualified to prevent a Failure to initialize a variable will possible ambiguity. result in the variable having an unpredictable value at execution time. 14. A pointer qualifier (explicit or Do not assume this value to be zero. implicit) may not be based or subscripted. (I) Failure to initialize a subscript can be detected by checking for subscripts 15. Conflicting contextual declarations out of range, when debugging the must be avoided. P is often used as program. the name of a pointer and it must not then assume by default the 2. Any attempt to write out a variable or characteristics of another data type. array that has not been initialized For example: may well cause a data interrupt to occur. For example: B BASED (P), DCL A(10) FIXED; A(1)=10; PUT LIST (A); Chapter 17: Optimization and Efficient Performance 231 To avoid the data interrupt, the array precision is even, an extra digit may should be initialized before the be inserted in the high-order byte. assignment statement, thus: A=0; Note that this problem can also occur Arithmetic and Logical Operations as a result of CHECK system action for an uninitialized array. If the CHECK condition were enabled for the array in the above example, and system 1. The rules for expression evaluation action were taken, the results, and should be carefully noted, with the way in which the program particular reference to priority of terminates, would be unpredictable. operations. The following examples The same problem arises when PUT DATA show the kind of mistake that can is used. occur: 3. Note the distinction between X>Y|Z is not equivalent to X>Y|X>Z = (assignment) and = (comparison). but is equivalent to (X>Y)|Z The statement X>Y>Z is not equivalent to X>Y&X>Z A=B=C; but is equivalent to (X>Y)>Z means "compare B with C and assign the The clause IF A=B||C is equivalent result (either '1'B or '0'B) to A, to IF A= (B||C) ,not to IF (A=B) ||C performing type conversion if necessary." All operation sequences of equal priority are evaluated left to right, 4. Assignments that involve conversion except for **, prefix +, prefix -, and should be avoided if possible. 1 , which are evaluated right to left. Thus, the statement 5. In the case of initialization of or assignment to a fixed length string: A=B**-C**D; if the assigned value is shorter than the string, it is extended on the is equivalent to right with blanks (for a character string) or zeros (for bit strings). A=B**(-(C**D)); For example: The normal use of parentheses is to DCL A CHAR(6), modify the rules of priority; however, B CHAR(3) INIT('CR'); it may be convenient to use redundant A=B; parentheses as a safeguard or to clarify the operation. After the execution of the above statements, B would contain CRb, and A 2. Conversion is governed by would contain CRbbbb. comprehensive rules which must be thoroughly understood if unnecessary 6. It is not possible to assign a cross trouble is to be avoided. Some section of an array of structures in a examples of the effect of conversion single statement; the whole of an follow. array of structures, or a single element may be referenced, but not a a. DECIMAL FIXED to BINARY FIXED can cross section. (I) cause unexpected results if fractions are involved: 7. When SIZE is disabled, the result of an assignment which would have raised DCL I FIXED BIN(31,5) INIT(1); SIZE is unpredictable: I = I+.1; FIXED BINARY: The result of an The value of I is now 1.0625. assignment here -- which includes, for This is because .1 is converted to instance, source language assignments FIXED BINARY(5,4), so that the and the conversions implied by nearest binary approximation is parameter matching -- may be to raise 0.0001B (no rounding occurs). The FIXEDOVERFLOW. decimal equivalent of this is .0625. A better result would have FIXED DECIMAL: Truncation to the been achieved by specifying .1000 nearest byte may occur, without in place of .1. (See also item f. raising an interrupt. If the target below.) 232 b. If arithmetic is performed on conversion according to the rules character string data, the for LIST-directed output. intermediate results are held in the maximum precision: Example 1 DCL A CHAR(6) INIT('123.45'); DCL A CHAR(4), DCL B FIXED(5,2); B CHAR(7); B=A; /*B HAS VALUE 123.45*/ A='0'; /*A HAS VALUE '0bbb'*/ B=A+A; /*B HAS VALUE 246.00*/ A=0; /*A HAS VALUE 'bbb0'*/ B=1234567; /*B HAS VALUE c. The rules for arithmetic to bit 'bbb1234'*/ string conversion affect assignment to a bit string from a Note: The three blanks are decimal constant: necessary to allow for the possibility of a minus sign and/or DCL A BIT(1), a decimal or binary point, with D BIT(5); provision for a single leading A=1; /*A HAS VALUE '0'*/ zero before the point. D=1; /*D HAS VALUE '00010'B*/ D='1'B; /*D HAS VALUE Example 2 '10000'*/ IF A=1 THEN GO TO Y; DCL CTLNO CHAR(8) INIT('0'); ELSE GO TO X; DO I=1 TO 100; CTLNO=CTLNO+1; The branch will be to X, because the assignment to A resulted in the following sequence of actions: END; • (1) The decimal constant, 1, is assumed to be FIXED DECIMAL In this example, a conversion (1,0) and is assigned to error occurs because of the temporary storage with the following sequence of actions: attributes FIXED BINARY(4,0), taking the value '0001'; (1) The initial value of CTLNC, that is, '0bbbbbbb', is (2) This value is now treated as a converted to FIXED bit string of length (4), so DECIMAL(5,0) for the addition, that it becomes '0001'B; giving a temporary value of 00000. (3) The resultant bit string is assigned to A. Since A has a declared length of 1, and the value to be assigned has (2) The decimal constant, 1, acquired a length of 4, assumed to be FIXED truncation occurs at the DECIMAL(1,0), is added; in right, and A has a final value accordance with the rules for of '0'B. addition, the precision of the result is (6,0), giving a To perform the comparison value of 000001. operation in the IF statement, '0' and 1 are converted to FIXED BINARY and compared arithmetically. They are unequal, (3) This value is now converted to giving a result of "false" for the a character string of length relationship A=1. 9, value 'bbbbbbbbl', in preparation for the assignment In the first assignment to D, a back to CTLNO. sequence of actions similar to that described for A takes place, except that the value is extended at the right with a zero, because (4) Because CTLNO has a length of D has a declared length that is 1 S, the assignment causes greater than that of the value to truncation at the right; thus, be assigned. CTLNO has a final value that consists entirely of blanks. d. Assignment of arithmetic values to This value cannot be character strings involves successfully converted to Chapter 17: Optimization and Efficient Performance 233 arithmetic type for the second C=A; /*WILL NOT RAISE CONV iteration of the loop. CONDITION*/ A=C; /*WILL RAISE CONV*/ e. FIXED division can result in Note also (A, B, C as declared unexpected overflows or above): truncation. For example, the expression A=123456; /*A HAS VALUE 123456*/ /*B HAS VALUE 25+1/3 '123456'*/ C=123456; /*C HAS VALUE 'bbb123'*/ C=A; /*C HAS VALUE '123456'*/ would yield a value of 5.33...3. To obtain a result of 25.33...3, g. A decimal fixed-point element with it would be necessary to write a declared even precision (P,Q) may have an effective precision of (P+1,Q), as the high-order byte may not be non-zero. The SIZE 25+01/3 condition can be used to eliminate this effect: DCL (A,B,C) FIXED DECIMAL (6,0); The explanation is that constants ON SIZE; have the precision and scale factor with which they are written, while FIXED division • results in a value of maximum (SIZE): A = B + C; implementation- defined precision. The results of the two evaluations This ensures that the high-order are reached as follows: byte of A is zero after the assignment. DO-groups 1. The scope of a condition prefix applied to a DO statement is limited to execution of the statement itself; it does not apply to execution of the entire group. 2. An iterative DO group is not executed if the terminating condition is satisfied at initialization: I=6; DO J=I TO 4; X=X+J; END; X is not altered by this group, since f. Checking of a picture is performed BY 1 is implied. Iterations can step only on assignment into the backwards, and if BY -1 had been picture variable: specified, three iterations would have taken place. DCL A PIC'999999', 3. Expressions in a DO statement are B CHAR(6) DEF A, assigned to temporaries with the same C CHAR(6); characteristics as the expression, not B='ABCDEF'; the variable. For example: 234 DCL A DECIMAL FIXED(5,0); 1. DCL (P, IA, IB, IC) POINTER; A=10; DO I=1 TO A/2; DO P=IA,IB,IC; END; 2. DCL (P, IA) POINTER; This loop will not be executed, because A/2 has decimal precision DO WHILE(P=IA); (15,10), which, on conversion to binary (for comparison with I), becomes binary (31,34). Data Aggregates Five iterations would result if the DO statement were replaced by 1. Array arithmetic should be thought of ITEMP=A/2; as a convenient way of specifying an DO I=1 TO ITEMP; iterative computation. For example: 4. DO-groups cannot be used as ON-units. DCL A(10,20); • 5. Upper and lower bounds of iterative DO-groups are computed once only, even if the variables involved are A=A/A(1,1); reassigned within the group. This applies also to the BY expression. has the same effect as Any new values assigned to the DCL A(10,20); variables involved would take effect only if the DO-group was started again. DO I=1 TO 10; 6. In a Do-group with both a control DO J=1 TO 20; variable and a WHILE clause, the A(I,J)=A(I,J)/A(1,1); evaluation and testing of the WHILE END; END; expression is carried out only after determination (from the value of the Note that the effect is to change the control variable) that iteration may value of A(1,1) only, since the first be performed. For example, the iteration would produce a value of 1 following group would be executed at for A(1,1). If the programmer wished most once: to divide each element of A by the original value of A(1,1), he could DO I=1 WHILE(X>Y); write B=A(1,1); A=A/B; END; or alternatively, 7. I is frequently used as the control variable in a DO-group, for example: DCL A(10,20), B(10,20); DO I=1 TO 10; Within the scope of this implicit declaration, I might be contextually B=A/A(1,1); declared as a pointer, for example: 2. Note the effect of array DCL X BASED(I); multiplication: The two statements are in conflict and DCL (A,B,C) (10,10); will produce a diagnostic message. • When I is a pointer variable, it can only be used in a DO-group in one of • the following ways: A=B*C; Chapter 17: Optimization and Efficient Performance 235 This does not effect matrix would result in the ERROR condition multiplication; it is equivalent to: being raised in the event of a transmission error during the first DCL (A,B,C) (10,10); GET operation, and the required branch would not be taken (assuming that no previous ON statement applies). Furthermore, the ON statement would be DO I=1 TO 10; executed after each execution of the DO J=1 TO 10; GET statement. A(I,J)=B(I,J)*C(I,J); END; END; 2. An on-unit cannot be entered by means of a GOTO statement. To execute an on-unit deliberately, the SIGNAL Strings statement can be used. 3. CONVERSION on-units entered as a result of an invalid conversion (as 1. Assignments made to a varying string opposed to SIGNAL) should either by means of the SUBSTR pseudo-variable change the invalid character (by means do not set the length of the string. of the ONSOURCE or ONCHAR A varying string initially has an pseudo-variable), or else terminate undefined length, so that if all with a GOTO statement. Otherwise, the assignments to the string are made system will print a message and raise using the SUBSTR pseudo-variable, the the ERROR condition. string still has an undefined length and cannot be successfully assigned to 4. At normal exit from an AREA on-unit, another variable or written out. The the standard system action is to try SUBSTR pseudo-variable cannot be again to make the allocation. Unless applied to a numeric picture. the on-unit makes the allocation possible, therefore, the on-unit will 2. The user must ensure that the lengths be entered again and an indefinite of intermediate results of string loop will be created. To avoid this, expressions do not exceed 32767 bytes. the amount allocated should be This applies particularly to variable modified in the on-unit; for example, string lengths, as there is no the EMPTY built-in function could be object-time length checking. (I) used, or a pointer variable could be changed. Functions and Pseudo-Variables Input/Output 1. When UNSPEC is used as a pseudo-variable, the expression on the 1. The UNDEFINEDFILE condition may be right is converted to a bit string. raised if a STREAM file is reopened Consequently, the expression must not with attributes or options that be invalid for such conversion; for conflict with attributes, options, or example, if the expression is a parameters previously specified for character string containing characters it. For example, if a file originally other than 0 or 1, a conversion error opened with a LINESIZE of 100 is will result. subsequently reopened with a LINESIZE of 131, the UNDEFINEDFILE condition will be raised if the DCB subparameter BLKSIZE is not specified on the DD ON-conditions and ON-units card, or if it is specified as less than 132. Difficulties of this nature can be avoided by the use of different file names, or by using the same file 1. Note the correct positioning of the ON name with different TITLE option statement. If the specified action is specifications. (I) to apply when the named condition is raised by a given statement, the ON 2. The UNDEFINEDFILE condition is raised statement must be executed before that not only by conflicting language statement. The statements: attributes (such as DIRECT with PRINT), but also by the following: GET FILE (ACCTS) LIST (A,B,C); ON TRANSMIT (ACCTS) GO TO TRERR; a. Block size smaller than record 236 size. This condition is not open the file will not raise this raised if spanned (VS- or condition again. VBS-format) records are used. (I) b. LINESIZE exceeding the permitted maximum. 3. If a file is to be used for both input and output, it must not be declared c. Blocked records specified for with either the INPUT or the OUTPUT REGIONAL organization. attribute. The required option can be specified on the OPEN statement. d. U- or V-format records specified There must be no conflict between file for INDEXED, REGIONAL(1), or attributes specified in the REGIONAL(2) organizations. declaration and those specified by the OPEN statement. e. KEYLEN not specified for creation of INDEXED, REGIONAL(2), or 4. Input/output lists must be surrounded REGIONAL(3) data sets. by a pair of parentheses; so must iteration lists. Therefore, two pairs f. Attempting to open an INDEXED data of outer parentheses are required in set for DIRECT OUTPUT. GET LIST ((A(I) DO I=1 TO N)); g. Attempting to open a CONSECUTIVE data set with DIRECT or KEYED 5. The last eight bytes of a source key attributes. to access a regional data set must be the character string representation of h. Specifying an RKP option, for an a fixed decimal integer. When INDEXED data set, with a value generating the key, the rules for resulting in KEYLEN+RKP exceeding arithmetic to character string LRECL. conversion should be considered. For example, the following group would be i. Specifying a V-format logical in error: record length of less than 18 bytes for STREAM data sets. DCL KEYS CHAR(S); DO I=1 TO 10; J . Specifying, for F-format blocked KEYS=I; records, a block size which is not WRITE FILE(F) FROM (R) an integral multiple of the record KEYFROM (KEYS); size. END; k. Specifying, for V-format records, The default for I is FIXED a logical record length that is BINARY(15,0), which requires not 8 but not at least four bytes smaller 9 characters to contain the character than the specified block size. string representation of the arithmetic values. 1. Attempting to open a paper-tape reader for OUTPUT or UPDATE. 6. Note that the file must have the KEYED attribute if the KEY, KEYFROM, or m. Attempting to open a file with the KEYTO options are to be used in any UNBUFFERED attribute for blocked input/output statement referring to records. that file. n. Attempting to use blocked records 7. The standard file names SYSIN and in the system input stream (SYSIN SYSPRINT are implicit only in GET and DD DATA or SYSIN DD *) with an PUT statements. Any other reference, UNBUFFERED file. The default such as those in ON statements or record format for the system input RECORD-oriented input/output stream is FB-format. Since this statements, must be explicit. stream is not checked on input, the presence of FB-format records 8. PAGESIZE and LINESIZE are not file will not be detected until an attributes, that is, they cannot be attempt is made to open the file, included in a DECLARE statement for when UNDEFINEDFILE will be raised. the file; they are options on the OPEN statement. Note: If the UNDEFINEDFILE condition is raised because either the key 9. When an edit-directed data list is length or the block size is not exhausted, no further format items specified, a subsequent attempt to will be processed, even if the next Chapter 17: Optimization and Efficient Performance 237 format item does not require a data list). Firstly, its use with an matching data item. For example: ON statement is restricted because the data known to PUT DATA would be the DCL A FIXED(5), data known at the point of the B FIXED(5,2); on-unit. Secondly, and more serious, GET EDIT (A,B) (F(5),F(5,2),X(70)); the data will be put out as normal data-directed output, which means that The X(70] format item will not be any unallocated or unassigned data may processed. To read a following card raise a CONVERSION or other condition. with data in the first ten columns only, the SKIP option can be used: If the on-unit GET EDIT (A,B) (F(5), F(5,2)) SKIP; ON ERROR PUT DATA; 10. The number of data items represented by an array or structure name is used in an outer block, it must be appearing in a data list is equal to remembered that variables in inner the number of scalar elements in the blocks are not known and therefore array or structure; thus if more than will not be dumped. It would be a one format item appears in the format good practice, therefore, to repeat list, successive elements will be the on-unit in all inner blocks during matched with successive format items. debugging. For example: If an error does occur during DCL 1 A, execution of the PUT DATA statement, 2 B CHAR(5), and this statement is within an ERROR 2 C FIXED(5,2); on-unit, the program will recursively enter the ERROR on-unit until no more storage remains for the operation. Since this could be wasteful of PUT EDIT (A) (A(5),F(5,2)); machine time and printout, the ERROR on-unit should be turned off once it B will be matched with the A(5) item, is activated. Instead of: and C will be matched with the F(5,2) item. ON ERROR PUT DATA; 11. Arrays are transmitted in row major better code would be: order (e.g., A(1,1), A(1,2), A(1,3), ... A(2,1), ... etc.) ON ERROR BEGIN; ON ERROR SYSTEM; 12. Strings used as input data for GET PUT DATA; DATA and GET LIST must be enclosed in END; quotation marks. When PUT DATA is used without a 13. The 48-character representation of a data-list every variable known at that semicolon (,.) is not recognized as a point in the program is transmitted in semicolon if it appears in a data-directed output format to the DATA-directed input stream; the 11-S-6 specified file. Users of this punch must be used. (I) facility, however, should note that: 14 If a new record is added by direct a) Uninitialized decimal access to an INDEXED data set whose fixed-point data may raise the overflow areas are already full, a CONVERSION condition or a data record will be irretrievably lost. interrupt. The position of the new record, in relation to the existing records on b) Unallocated controlled data will the track, will determine whether it cause arbitrary values to be is the new record or an existing one printed and, in the case of that is lost. If the new record would decimal fixed-point, may raise follow the last existing record on the the CONVERSION condition or a track, the new record will be lost data interrupt. Otherwise, the last existing record on the track will be lost. In either 16. Use of locate mode I/O. A pointer set case, the KEY condition will be in READ SET or LOCATE SET may not be raised. valid beyond the next operation on the file, or beyond a CLOSE statement. In 15. The user must be aware of two OUTPUT files, WRITE and LOCATE limitations of PUT DATA; (i.e., no statements can be freely mixed. 238 For UPDATE files, the REWRITE the second case, the embedded key statement with no options must be used is overwritten with the KEYFROM if it is required to rewrite an string, and the record is updated record. The result of this transmitted. REWRITE is always to rewrite the contents of the last buffer onto the Thus the condition may be raised data set. by a CLOSE statement or by an END statement that causes implicit For example: closing. Until the error is corrected, the record cannot be 3 READ FILE (F) SET (P); transmitted and no further • operation can be carried out on • the file. 5 P->R = S; If a LOCATE statement was used in the addition of KEYED records to any type of REGIONAL data set • then, if the RECORD condition is 7 REWRITE FILE (F); raised, the key value presented at • subsequent operations must not be less than the current one. 11 READ FILE (F) INTO (X); 17. Allocation and freeing of based variables: If a reference is made, at object time, to a BASED variable that has not been allocated storage, an 15 REWRITE FILE (F); unpredictable interrupt (protection, addressing or specification) may occur. 19 REWRITE FILE (F) FROM (X); 18. Areas, pointers, offsets and structures containing any of these Notes: cannot be used with STREAM I/O. PUT DATA cannot be used with BASED Statement 7 will rewrite a record variables. updated in the buffer. Statement 15 will only rewrite When a based variable is freed, the exactly what was read, i.e., it associated pointer no longer contains will not change the data set at useful information. This pointer can all. only be used again if: Statement 19 will raise ERROR, since there is no preceding 1. It is re-allocated with the same READ statement. or another based variable, or, There are two cases where it is not 2. A value is assigned to it from an possible to check for the KEY offset or another pointer condition on a LOCATE statement until transmission of a record is attempted. A based variable allocated in an (This will generally occur on area must be freed in that area. execution of the next PL/I output For example: statement for this file.) DCL A AREA, B BASED (X); These are: ALLOCATE B IN (A); 1. When there is insufficient room in the specified region to output the record on a REGIONAL(3) V- or FREE B; /* ILLEGAL */ U-format file. Neither the record FREE B IN (A); /* LEGAL */ raising the condition nor the current record are transmitted. 2. When the embedded key differs from ADDITIONAL HINTS the KEYFROM in an ISAM file. If this LOCATE statement is to transmit the last record before Declarations and Attributes the file is closed, in case 1, the record is not transmitted, and in 1. Do not rely too heavily on default Chapter 17: Optimization and Efficient Performance 239 attributes. Explicit declarations As a result of this assignment, help to clarify the source program the values of the various elements logic, and in some cases (for will be: example, precision) reduce the chance of error. C '0'B D 'b' 2. Variables declared FIXED BINARY or E 'bbb0' FLOAT BINARY are automatically aligned on the proper word Do-groups boundary, regardless of whether they are single or part of an Iterations can step backwards, and the aggregate. FIXED DECIMAL expression in the WHILE clause can refer to variables are stored in packed the control variable, e.g., decimal format and the System/360 decimal instructions are used in DO I=N+2*L BY -X WHILE (I>0); operations involving them. FLOAT END; DECIMAL variables are stored in floating-point format; operations The control variable can be modified within involving them are carried out the loop. using the floating-point instruction set. It is possible to transfer from within a DO-loop to a label on the END statement for Assignments and Initialization the group. This has the effect of incrementing the control variable without 1. High order zeros will be inserted intermediate processing; control will not if required on assignment to or fall through. It is also possible to initialization of an arithmetic transfer out of an iterative DO group variable: before the terminating value of the control variable is reached. DCL A FIXED DECIMAL (5,2) INIT (12); /*A HAS VALUE 012.00*/ Functions DCL B FIXED BINARY (15,0); The arguments in a function reference can B=12; be modified by the function. /*B HAS VALUE 000000000001100B*/ ON-conditions and On-units 2. Arrays may be initialized by assignment from an element Note the scope of condition prefixes: expression: (SIZE):A:PROC; DCL A(10); A=0; The value will be assigned to each (NOSIZE):IF M>N THEN DO; element of the array. Similarly, J=E+F; when an element expression is END; assigned to a structure, its value will be assigned to each element of the structure: END A; DCL 1B, 2 C BIT(1), In the above example, SIZE is disabled 2 D CHAR(1), only during the evaluation of the 2 E CHAR(4); expression M>N; SIZE is enabled for the B=0; assignment J=E+F. 240 Part II Rules and Syntactic Descriptions Section A: Syntax Notation Throughout this publication, wherever a 2. A notation constant denotes the PL/I statement -- or some other combination literal occurrence of the characters of elements -- is discussed, the manner of represented. A notation constant writing that statement or phrase is consists either of all capital letters illustrated with a uniform system of or of a special character. notation. This notation is not a part of PL/I; it is a standardized notation that may be used to describe the syntax -- or construction -- of any programming language. It Example: provides a brief but precise explanation of the general patterns that the language permits. It does not describe the meaning DECLARE identifier FIXED; of the language elements, merely their structure; that is, it indicates the order This denotes the literal occurrence of in which the elements may (or must) appear, the word DECLARE followed by the the punctuation that is required, and the notation variable "identifier," which options that are allowed. is defined elsewhere, followed by the literal occurrence of the word FIXED The following rules explain the use of followed by the literal occurrence of this notation for any programming language; the semicolon (;). only the examples apply specifically to PL/I: 3. The term "syntactic unit," which is used in subsequent rules, is defined 1. A notation variable is the name of a as one of the following: general class of elements in the programming language. A notation a. A single notation variable or variable must consist of: notation constant. a. Lower-case letters, decimal b. Any collection of notation digits, and hyphens and must begin variables, notation constants, with a letter. syntax-language symbols, and keywords surrounded by braces or b. A combination of lower-case and brackets. upper-case letters. There must be one portion in all lower-case 4. Braces {} are used to denote grouping letters and one portion in all of more than one element into a upper-case letters, and the two syntactic unit. portions must be separated by a hyphen. Example: All such variables used are defined in {FIXED} the manual either syntactically, using identifier this notation, or are defined FLOAT semantically. The vertical stacking of syntactic Examples: units indicates that a choice is to be made. The above example indicates a. digit. This denotes the that the variable "identifier" must be occurrence of a digit, which may followed by the literal occurrence of be 0 through 9 inclusive. either the word FIXED or the word FLOAT. b. file-name. This denotes the occurrence of the notation 5. The vertical stroke | indicates that a variable named file name. An choice is to be made. explanation of file name is given elsewhere in the manual. Example: c. DO-statement. This denotes the identifier {FIXED|FLOAT} occurrence of a DO statement. The upper-case letters are used to This has exactly the same meaning as indicate a language keyword. 242 the above example. Both methods are Example: used in this manual to display alternatives. [digit] ... 6. Square brackets [ denote options. The variable "digit" may or may not Anything enclosed in brackets may occur since it is surrounded by appear one time or may not appear at brackets. If it does occur, it may be all. Brackets can serve the repeated one or more times. additional purpose of delimiting a syntactic unit. Vertical stacking within brackets means that no more than one of the stacked syntactic units can appear. 8. Underlining is used to denote an element in the language being described when there is conflict Example: between this element and one in the syntax language. {[lower-bound:] upper-bound} | * This denotes the occurrence of either Example: a literal asterisk or the variable "upper-bound," but not both. If "upper-bound" appears, it can operand {&||} operand optionally be preceded by the syntactic unit composed of the This denotes that the two occurrences variable "lower-bound" and the literal of the variable "operand" are colon. separated by either an "and" (&) or an "or" (|). The constant | is underlined in order to distinguish the 7. Three dots ... denote the occurrence "or" symbol in the PL/I language from of the immediately preceding syntactic the "or" symbols in the syntax unit one or more times in succession. language. Section A: Syntax Notation 243 Section B: Character Sets with EBCDIC and Card-Punch Codes 60-CHARACTER SET 244 48-CHARACTER SET Note: When using the 48-character set, the following rules should be observed: 1. The two periods that replace the colon must be immediately preceded by a blank if the preceding character is a period. 2. The two slashes that replace the percent symbol must be immediately preceded by a blank if the preceding character is an asterisk, or immediately followed by a blank if the following character is an asterisk. 3. The sequence "comma period" represents a semicolon except when it occurs in a comment or character string, or when it is immediately followed by a digit. 4. When the F Compiler option CHAR48 is specified on the EXEC statement for the compilation (see IBM System/360 Operating System, PL/I (F) Programmer's Guide), 60-character set symbols may be freely intermixed with 48-character set symbols and will be accepted by the compiler as valid input. 5. The semicolon, which is not in the 48-character set, must always be represented by the proper 11-8-6 punch (i.e., the character sequence ,. is not recognized as a semicolon). 6. 48-character set "reserved" words (e.g.,GT,LE,CAT,etc.,) must be preceded and followed by a blank or a comment. If they are not, the interpretation by the compiler is undefined and may not therefore, be what the user intended. A record containing.part or all of a 48-character set reserved word must be 3 characters or more in length. Section B: Character Sets With EBCDIC and Card-Punch Codes 245 Section C: Keywords and Keyword Abbreviations Keyword Abbreviation Use of Keyword ABS (x) built-in function %ACTIVATE %ACT preprocessor statement ADD(x,y,p[,q]) built-in function ADDR(x) built-in function ALIGNED attribute ALL(x) built-in function ALLOCATE statement ALLOCATION(x) built-in function ANY(x) built-in function AREA condition AREA[(size)] attribute ATAN(x[,y]) built-in function ATAND(x[,y]) built-in function ATANH(x) built-in function AUTOMATIC AUTO attribute BACKWARDS attribute, option of OPEN statement BASED(pointer-variable) attribute BEGIN statement BINARY BIN attribute BINARY(x[,p[,q]]) BIN(x[,p[,q]]) built-in function BIT(length) attribute BIT(expression[,size]) built-in function BOOL(x,y,w) built-in function BUFFERED BUF attribute BUFFERS(n) option of ENVIRONMENT attribute BUILTIN attribute BY clause of DO statement BY NAME option of the assignment statement CALL entry-name statement or option of INITIAL attribute CEIL(x) built-in function CHAR(expression[,size]) built-in function CHARACTER(length) CHAR(length) attribute CHECK (name-list) condition CLOSE statement COBOL option of ENVIRONMENT attribute COLUMN(w) COL (w) format item COMPLETION(event-name) built-in function, pseudo-variable COMPLEX CPLX data attribute COMPLEX(a,b) CPLX(a,b) built-in function, pseudo-variable CONDITION(name) condition CONJG(x) built-in function CONSECUTIVE option of ENVIRONMENT attribute CONTROLLED CTL attribute CONVERSION CONV condition COPY option of GFT statement COS(x) built-in function COSD(x) built-in function CCSE(x) built-in function COUNT(file-name) built-in function CTLASA option of ENVIRONMENT attribute CTL360 option of ENVIRONMENT attribute DATA STREAM I/O transmission mode DATAFIELD built-in function DATE built-in function %DEACTIVATE %DEACT preprocessor statement DECIMAL DEC attribute DECIMAL(x[,p[,q]]) DEC(x[,p[,q]]) built-in function DECLARE DCL statement %DECLARE %DCL preprocessor statement DEFINED DEF attribute DELAY(n) statement DELETE statement DIM(x,n) built-in function 246 Keyword Abbreviation Use of Keyword DIRECT attribute DISPLAY statement DIVIDE(x,y,p[,q]) built-in function DO statement %DO preprocessor statement EDIT STREAM I/O transmission mode ELSE clause of IF statement %ELSE clause of %IF statement EMPTY built-in function END statement %END preprocessor statement ENDFILE(file-name) condition ENDPAGE(file-name) condition ENTRY attribute or statement ENVIRONMENT ENV attribute ERF(x) built-in function ERFC(x) built-in function ERROR condition EVENT option of CALL, READ, WRITE, REWRITE, and DELETE statements, attribute EXCLUSIVE EXCL attribute EXIT statement EXP(x) built-in function EXTERNAL EXT attribute F(block-size[,record-size]) option of ENVIRONMENT attribute FILE attribute FILE(file-name) option of GET and PUT statements, specification of RECORD I/O statements FINISH condition FIXED attribute FIXED(x[,p[,q]]) built-in function FIXEDOVERFLOW FOFL condition FLOAT attribute FLOAT(x[,p]) built-in function FLOOR(x) built-in function FORMAT(format-list) statement FREE statement FROM(variable) option of WRITE or REWRITE statements G(max-message-size) option of ENVIRONMENT attribute GENERIC attribute GENKEY option of ENVIRONMENT attribute GET statement GO TO GOTO statement %GO TO %GOTO preprocessor statement HBOUND(x,h) built-in function HIGH(i) built-in function IF statement %IF preprocessor statement IGNORE(n) option of READ statement IMAG(x) built-in function, pseudo-variable IN option of ALLOCATE and FREE statements %INCLUDE preprocessor statement INDEXAREAINDEX(string,config) built-in function [(index-area-size)] option of ENVIRONMENT attribute INDEXED option of ENVIRONMENT attribute INITIAL INIT attribute INPUT attribute, option of the OPEN statement INTERNAL INT attribute INTO(variable) option of READ statement KEY(file-name) condition KEY(x) option of READ, DELETE, and REWRITE statements KEYED attribute, option of OPEN statement KEYFROM(x) option of WRITE statement KEYTO(variable) option of READ statement LABEL attribute Section C: Keywords and Keyword Abbreviations 247 Keyword Abbreviation Use of Keyword LENGTH(string) built-in function LBOUND(x,n) built-in function LEAVE option of ENVIRONMENT attribute LIKE attribute LINE(w) format item, option of PUT statement LINENO(file-name) built-in function |LINESIZE(w) option of OPEN statement LIST STREAM I/O transmission mode LOCATE statement LOG (x) built-in function LOG2(x) built-in function LOG10(x) built-in function LOW(i) built-in function MAIN option of PROCEDURE statement MAX(xi,x2...xn) built-in function MIN(x1,x2...xn) built-in function MOD(x1,x2) built-in function MULTIPLY(x1,x2,p[,q]) built-in function NAME(file-name) condition |NCP(n) option of ENVIRONMENT attribute NOCHECK condition prefix identifier (disables CHECK) NOCONV condition prefix identifier NOCONVERSION (disables CONVERSION) NOFIXEDOVERFLOW NOFOFL condition prefix identifier (disables FIXEDOVERFLOW) NOLOCK option of READ statement NOOVERFLOW NOOFL condition prefix identifier (disables OVERFLOW) NOSIZE condition prefix identifier (disables SIZE) NOSTRINGRANGE NOSTRG condition prefix identifier (disables STRINGRANGE) NOSUBSCRIPTRANGE NOSUBRG condition prefix identifier (disables SUBSCRIPTRANGE) NOUNDERFLOW NOUFL condition prefix identifier (disables UNDERFLOW) NOWRITE option of ENVIRONMENT attribute NOZERODIVIDE NOZDIV condition prefix identifier (disables ZERODIVIDE) NULL built-in function NULLO built-in function OFFSET(area-name) attribute ON statement ONCHAR built-in function, pseudo-variable ONCOUNT built-in function ONCODE built-in function ONFILE built-in function ONKEY built-in function ONLOC built-in function ONSOURCE built-in function, pseudo-variable OPEN statement OPTIONS(list) option of PROCEDURE statement I ORDER option of PROCEDURE and BEGIN statements OUTPUT attribute, option of the OPEN statement OVERFLOW OFL condition PAGE format item, option of PUT statement PAGESIZE(w) option of the OPEN statement |PENDING(file-name) condition PICTURE PIC attribute POINTER PTR attribute POLY(a,x) built-in function POSITION(i) POS (i) attribute PRECISION(x,p[,q]) PREC(x,p[,q]) built-in function PRINT attribute, option of OPEN statement PRIORITY(x) option of CALL statement 248 Keyword Abbreviation Use of Keyword PRIORITY[(task-name)] built-in function, pseudo-variable PROCEDURE PROC statement %PROCEDURE %PROC preprocessor statement PROD(x) built-in function PUT statement R(max-record-size) option of ENVIRONMENT attribute READ statement REAL attribute REAL(x) built-in function, pseudo-variable RECORD attribute, option of OPEN statement RECURSIVE option of PROCEDURE statement REENTRANT option of PROCEDURE statement REFER option of BASED attribute REGIONAL(1|2|3) option of ENVIRONMENT attribute !REORDER option of PROCEDURE and BEGIN statements REPEAT(string,i) built-in function REPLY(c) option of DISPLAY statement RETURN statement RETURNS attribute, option of PROCEDURE and ENTRY statements REVERT statement REWIND option of ENVIRONMENT attribute REWRITE statement ROUND(x,n) built-in function SEQUENTIAL SEQL attribute SET(pointer-variable) option of ALLOCATE, LOCATE, and READ statements SIGN(x) built-in function SIGNAL statement SIN(x) built-in function SIND(x) built-in function SINH (x) built-in function SIZE condition SKIP[(x)] format item, option of GET and PUT statements SNAP option of ON statement SQRT(x) built-in function STATIC attribute STATUS(event-name) built-in function, pseudo-variable STOP statement STREAM attribute, option of OPEN statement | STRING (x) built-in function, pseudo-variable STRINGRANGE STRG condition STRING(string-name ) option of GET and PUT statements iSUB dummy variable of DEFINED attribute SUBSCRIPTRANGE SUBRG condition SUBSTR(string,i[,j]) built-in function, pseudo-variable SUM(x) built-in function SYSIN name of standard system input file SYSPRINT name of standard system output file SYSTEM option of the ON statement TAN(x) built-in function TAND(x) built-in function TANH(x) built-in function TASK attribute, option of PROCEDURE statement TASK[(task-name)] option of CALL statement THEN clause of IF statement %THEN clause of %IF statement TIME built-in function TO clause of DO statement TITLE(x) option of OPEN statement TRANSIENTTRANSLATE(s,r[,p]) attribute built-in function TRANSMIT condition TRKOFL option of ENVIRONMENT attribute TRUNC(x) built-in function U(max-block-size) option of ENVIRONMENT attribute Section C: Keywords and Keyword Abbreviations 249 Keyword Abbreviation Use of Keyword UNALIGNED UNAL attribute UNBUFFERED UNBUF attribute, option of OPEN statement UNDEFINEDFILE(file-name) UNDF(file-name) condition UNDERFLOW UFL condition UNLOCK statement UNSPEC(x) built-in function, pseudo-variable UPDATE attribute, option of OPEN statement V(max-block-size [,max-record-size]) option of ENVIRONMENT attribute VARYING VAR attribute VBS(max-block-size [,max-record-size]) option of ENVIRONMENT attribute VERIFY(expr-1,expr-2) built-in function VS(max-block-size [,max-record-size]) option of ENVIRONMENT attribute WAIT statement WHILE clause of DO statement WRITE statement ZERODIVIDE ZDIV condition 250 Section D: Picture Specification Characters Picture specification characters appear in Numeric character data to be read using either the PICTURE attribute or the P the P format item must conform to the format item for edit-directed input and specification contained in the P format output. In either case, an individual item, including editing characters. If the character has the same meaning. A indicated character does not appear in the discussion of the concepts of picture input stream, the CONVERSION condition is specifications appears in Part I, Chapter raised. 11, "Editing and String Handling." Data assigned to a variable declared with a character-string picture Picture characters are used to describe specification (or data to be written with a the attributes of the associated data item, character-string picture format item) whether it is the value of a variable or a should conform, character by character (or data item to be transmitted between the be convertible, character by character) to program and external storage. the picture specification; if it does not, the CONVERSION condition is raised. A picture specification always describes Figures in this section illustrate how a character representation that is either a different picture specifications affect the character-string data item or a numeric representation of values when assigned to a character data item. A character-string pictured variable or when printed using the pictured item is one that can consist of P format item. Each figure shows the alphabetic characters, decimal digits, and original value of the data, the attributes other special characters. A numeric of the variable from which it is assigned character pictured item is one in which the (or written), the picture specification, data itself can consist only of decimal and the character-string value of the digits, a decimal point and, optionally, a numeric character or pictured plus or minus sign. Other characters character-string variable. generally associated with arithmetic data, such as currency symbols, can also be specified, but they are not a part of the arithmetic value of the numeric character variable, although the characters are stored with the digits and are considered Picture Characters for Character-String Data to be part of the character-string value of the variable. Only three picture characters can be used Arithmetic data assigned to a numeric in character-string picture specifications: character variable is converted to character representation. Editing, such as X specifies that the associated position zero suppression and the insertion of other can contain any character whose internal characters, can be specified for a numeric bit configuration can be recognized by character data item. Editing cannot be the computer in use. specified for pictured character-string data. A specifies that the associated position can contain any alphabetic character or Data assigned to a variable declared a blank character. with a numeric picture specification (or data to be written with a numeric picture 9 specifies that the associated position format item) must be either internal coded can contain any decimal digit or a blank arithmetic data or data that can be character. converted to coded arithmetic. Thus, assigned data can contain only digits and, No insertion characters can be specified. optionally, a decimal point and a sign. It At least one A or X must appear. should not contain any other character, even though that character (for example, a Figure D-1 gives examples of currency symbol) is specified in the character-string picture specifications. picture specification and is to be inserted In the figure, the letter b indicates a into the data as part of its blank character. Note that assignments are character-string value; if it does, the left-adjusted, and any necessary padding CONVERSION condition is raised. with blanks is on the right. Section D: Picture Specification Characters 251 Figure D-1. Pictured Character-String Examples Picture Characters for Numeric Character character-string expression operation or in Data an assignment to a character-string variable, whenever the data is printed using list-directed or data-directed Numeric character data must represent output, or whenever a reference is made to numeric values; therefore, the associated a character-string variable that is defined picture specification cannot contain the on the numeric character variable. In such characters X or A. The picture characters cases, no data conversion is necessary. for numeric character data can specify detailed editing of the data. The picture characters for numeric A numeric character variable can be character specifications may be grouped considered to have two different kinds of into the following categories: value, depending upon its use. They are (1) its arithmetic value and (2) its character-string value. • Digit and Decimal-Point Specifiers The arithmetic value is the value • Zero Suppression Characters expressed by the decimal digits of the data item, the assumed location of a decimal • Insertion Characters point, and possibly a sign. The arithmetic value of a numeric character variable is • Signs and Currency Symbol used whenever the variable appears in an expression that results in a coded • Credit, Debit, and Overpunched Signs arithmetic value or whenever the variable is assigned to a coded arithmetic, numeric • Exponent Specifiers character, or bit-string variable. In such cases, the arithmetic value of the numeric • Scaling Factor character variable is converted to internal coded arithmetic representation. • Sterling Pictures The character-string value is the value The picture characters in these groups expressed by the decimal digits of the data may be used in various combinations. item, as well as all of the editing and Consequently, a numeric character insertion characters appearing in the specification can consist of two or more picture specification. The parts such as a sign specification, an character-string value does not, however, integer subfield, a fractional subfield include the assumed location of a decimal and, for floating-point, an exponent field. point, as specified by the picture A sterling picture specification contains character V. The character-string value of separate fields for pounds, shillings, and a numeric character variable is used pence; the pence field can have an integer whenever the variable appears in a subfield and a fractional subfield. 252 A major requirement of the picture V specifies that a decimal point is specification for numeric character data is assumed at this position in the that each field must contain at least one associated data item. However, it does picture character that specifies a digit not specify that an actual decimal point position. This picture character, however, is to be inserted. The integer and need not be the digit character 9. Other fractional parts of the assigned value picture characters, such as the zero are aligned on the V character; suppression characters (Z or * or Y), also therefore, an assigned value may be specify digit positions. At least one of truncated or extended with zero digits these characters must be used to define a at either end. (Note that if numeric character specification. significant digits are truncated on the left, the result is undefined and a SIZE interrupt will occur, if SIZE is For the F Compiler the maximum length of enabled.) If no V character appears in a picture describing a numeric field, after the picture specification of a expansion of iteration factors, is 255. fixed-point decimal value (or in the first field of a picture specification of a floating-point decimal value), a V is assumed at the right end of the field specification. This can cause the assigned value to be truncated, if DIGIT AND DECIMAL-POINT SPECIFIERS necessary, to an integer. The V character cannot appear more than once in a picture specification. The V is The picture characters 9 and V are used in considered to be a subfield delimiter in the simplest form of numeric character the picture specification; that is, the specifications that represent fixed-point portion preceding the V and the portion decimal values. following it (if any) are each a subfield of the specification. Figure D-2 gives examples of numeric character specifications. 9 specifies that the associated position in the data item is to contain a decimal digit. Figure D-2. Pictured Numeric Character Examples Section D: Picture Specification Characters 253 ZERO SUPPRESSION CHARACTERS nonleading, in the associated position to be replaced by a blank character. When the associated position does not The zero suppression picture characters contain a zero digit, the digit in the specify conditional digit positions in the position is not replaced by a blank character-string value and may cause character. leading zeros to be replaced by asterisks or blanks and nonleading zeros to be Note: If one of the picture characters Z replaced by blanks. Leading zeros are or * appears to the right of the picture those that occur in the leftmost digit character V, then all fractional digit positions of fixed-point numbers or in the positions in the specification, as well as leftmost digit positions of the two parts all integer digit positions, must employ of floating-point numbers, that are to the the Z or * picture character, respectively. left of the assumed position of a decimal When all digit positions to the right of point, and that are not preceded by any of the picture character V contain zero the digits 1 through 9. The leftmost suppression picture characters, fractional nonzero digit in a number and all digits, zeros of the value are suppressed only if zeros or not, to the right of it represent all positions in the fractional part significant digits. Note that a contain zeros and all integer positions floating-point number can also have a have been suppressed. The entire leading zero in the exponent field. character-string value of the data item will then consist of blanks or asterisks. Figure D-3 gives examples of the use of No digits in the fractional part are zero suppression characters. In the replaced by blanks or asterisks if the figure, the letter b indicates a blank fractional part contains any significant character. digit. Z specifies a conditional digit position and causes a leading zero in the associated data position to be replaced INSERTION CHARACTERS by a blank character. When the associated data position does not contain a leading zero, the digit in the The picture characters comma (,), point position is not replaced by a blank (.), slash (/), and blank (B) are insertion character. The picture character Z characters; they cause the specified cannot appear in the same subfield as character to be inserted into the the picture character *, nor can it associated position of the numeric appear to the right of a drifting character data. They do not indicate digit picture character or any of the picture positions, but are inserted between digits. characters 9, T, I, or P in a field. Each does, however, actually represent a character position in the character-string specifies a conditional digit position value, whether or not the character is and is used the way the picture suppressed. The comma, point, and slash character Z is used, except that leading are conditional insertion characters; zeros are replaced by asterisks. The within a string of zero suppression picture character * cannot appear with characters, they, too, may be suppressed. the picture character Z in the same The blank (B) is an unconditional insertion subfield, nor can it appear to the right character; it always specifies that a blank of a drifting picture character or any is to appear in the associated position. of the picture characters 9, T, I, or R in a field. Note: Insertion characters are applicable only to the character-string value. They Y specifies a conditional digit position specify nothing about the arithmetic value and causes a zero digit, leading or of the data item. 254 Figure D-3. Examples of Zero Suppression Figure D-4 gives examples of the use of upon the first picture character that insertion characters. In the figure, the both precedes the comma position and letter b indicates a blank character. specifies a digit position: • If this character position is an causes a comma to be inserted into the asterisk, the comma position is associated position of the numeric assigned an asterisk. character data when no zero suppression occurs. If zero suppression does occur, • If this character position is a the comma is inserted only when an drifting sign or a drifting currency unsuppressed digit appears to the left symbol (discussed later), the of the comma position, or when a V drifting string is assumed to include appears immediately to the left of it the comma position, which is assigned and the fractional part contains any the drifting character. significant digits.' In all other cases where zero suppression occurs, one of • If this character position is not an three possible characters is inserted in asterisk or a drifting character, the place of the comma. The choice of comma position is assigned a blank character to replace the comma depends character. is used the same way the comma picture 'In the special case of a conditional character is used, except that a point insertion character that is preceded either (.) is assigned to the associated by nothing or only by characters that do position. This character never causes not specify digit positions, the point alignment in the picture conditional position will always contain specifications of a fixed-point decimal the conditional insertion character. number and is not a part of the Section D: Picture Specification Characters 255 arithmetic value of the data item. That inserted only if a significant digit function is served solely by the picture appears to the left of the V, even if character V. Unless the V actually all fractional digits are significant. appears, it is assumed to be to the If the point immediately follows the V, right of the rightmost digit position in it will be suppressed if all digits to the field, and point alignment is the right of the V are suppressed, but handled accordingly, even if the point it will appear if there are any insertion character appears elsewhere. significant fractional digits (along The point (or the comma or slash) can be with any intervening zeros). used in conjunction with the V to cause insertion of the point (or comma or slash) in the position that delimits the is used the same way the comma picture end of the integer portion and the character is used, except that a slash beginning of the fractional portion of a (/) is inserted in the associated fixed-point (or floating-point) number, position. as might be desired in printing, since the V does not cause printing of a B specifies that a blank character always point. The point must immediately be inserted into the associated position precede or immediately follow the V. If of the character-string value of the the point precedes the V, it will be numeric character data. 256 Figure D-4. Examples of Insertion Characters SIGNS AND CURRENCY SYMBOL position immediately to the left of the first significant digit. The picture characters S, +, and - specify The static use of these characters signs in numeric character data. The specifies that a sign, a currency symbol, picture character $ specifies a currency or a blank always appears in the associated symbol in the character-string value of position. The drifting use specifies that numeric character data. leading zeros are to be suppressed. In this case, the rightmost suppressed position associated with the picture These picture characters may be used in character will contain a sign, a blank, or either a static or a drifting manner. A a currency symbol. drifting character is similar to a zero suppression character in that it can cause A drifting character is specified by zero suppression. However, the character multiple use of that character in a picture specified by the drifting string is always field. Thus, if a field contains one inserted in the position specified by the currency symbol (0, it is interpreted as end of the drifting string or in the static; if it contains more than one, it is Section D: Picture Specification Characters 257 interpreted as drifting. The drifting character. character must be specified in each digit position through which it may drift. The position in the data associated with Drifting characters must appear in the characters slash, comma, point, and B strings. A string is a sequence of the appearing in a string of drifting same drifting character, optionally characters will contain one of the containing a V and one of the insertion following: characters comma, point, slash, or B. Any of the insertion characters slash, comma, • slash, comma, point, or blank if a point, or B following the last drifting significant digit has appeared to the symbol of the string is considered part of left the drifting string. However, a following V terminates the drifting string and is not • the drifting symbol, if the next part of it. A field of a picture position to the right contains the specification can contain only one drifting leftmost significant digit of the field string. A drifting string cannot be preceded by a digit position. The picture • blank, if the leftmost significant digit characters * and Z cannot appear to the of the field is more than one position right of a drifting string in a field. to the right Figure D-5 gives examples of the use of If a drifting string contains the drifting picture characters. In the drifting character n times, then the string figure, the letter b indicates a blank is associated with n-1 conditional digit •Figure D-5. Examples of Drifting Picture Characters 258 positions. The position associated with - specifies the minus sign character (-) the leftmost drifting character can contain if the data value is <0, otherwise it only the drifting character or blank, never specifies a blank. The character may be a digit. If a drifting string is specified drifting or static. The rules are for a field, the other potentially drifting identical to those for the currency characters can appear only once in the symbol. field, i.e., the other character represents a static sign or currency symbol. CREDIT, DEBIT, AND OVERPUNCHED SIGNS If a drifting string contains a V within it, the V delimits the preceding portion as a subfield, and all digit positions of the The character pairs CR (credit) and DB subfield following the V must also be part (debit) specify the signs of real numeric of the drifting string that commences the character data items and usually appear in second subfield. business report forms. Only one type of sign character can Any of the picture characters T, I, or R appear in each field. An S, +, or - used specifies an overpunched sign in the as a static character can appear to the associated digit position of numeric left of all digits in the mantissa and character data. An overpunched sign is a exponent fields of a floating-point 12-punch (for plus) or an 11-punch (for specification, and either to the right or minus) punched into the same column as a left of all digit positions of a digit. It indicates the sign of the fixed-point specification. arithmetic data item. Only one overpunched sign can appear in a specification for a In the case in which all digit positions fixed-point number. A floating-point after the V contain drifting characters, specification can contain two, one in the suppression in the subfield will occur only mantissa field and one in the exponent if all of the integer and fractional digits field. The overpunch character can, are zero. The resulting edited data item however, be specified for any digit twill then be all blanks. If there are any position within a field. The overpunched significant fractional digits, the entire number then will appear in the specified fractional portion will appear digit position. unsuppressed. Note: When an overpunch character occurs $ specifies the currency symbol. If this in a P format item for edit-directed input, character appears more than once, it is the corresponding character in the input a drifting character; otherwise it is a stream may contain an overpunched sign. static character. The static character specifies that the character is to be Figure D-6 gives examples of the CR, DH, placed in the associated position. The and overpunch characters. In the figure, static character must appear either to the letter b indicates a blank character. the left of all digit positions in a field of a specification or to the right CR specifies that the associated positions of all digit positions in a will contain the letters CR if the specification. See details above for value of the data is less than zero. the drifting use of the character. Otherwise, the positions will contain two blanks. The characters CR can S specifies the plus sign character (+) if appear only to the right of all digit the data value is >=0, otherwise it positions of a field. specifies the minus sign character (-). The character may be drifting or static. DB is used the same way that CR is used The rules are identical to those for the except that the letters DB appear in currency symbol. the associated positions. + specifies the plus sign character (+) if T specifies that the associated position, the data value is >=0, otherwise it on input, will contain a digit specifies a blank. The character may be overpunched with the sign of the data. drifting or static. The rules are It also specifies that an overpunch is identical to those for the currency to be indicated in the character-string symbol. value. Section D: Picture Specification Characters 259 Figure D-6. Examples of CR, DB, T, I, and R Picture Characters I specifies that the associated position, Note: The picture characters CR, DB, T, I, on input, will contain a digit and R cannot be used with any other sign overpunched with + if the value is >=0; characters in the same field. otherwise, it will contain the digit with no overpunching. It also specifies that an overpunch is to be indicated in the character-string value EXPONENT SPECIFIERS if the data value is >=0. The picture characters K and E delimit the R specifies that the associated position, exponent field of a numeric character on input, will contain a digit specification that describes floating-point overpunched with - if the value is <0; decimal numbers. The exponent field is otherwise, it will contain the digit always the last field of a numeric with no overpunching. It also character floating-point picture specifies that an overpunch is to be specification. The picture characters K indicated in the character-string value and E cannot appear in the same if the data value is <0. specification. Figure D-7. Examples of Floating-Point Picture Specifications 260 Figure D-7 gives examples of the use of Figure D-8 shows examples of the use of exponent delimiters. In the figure, the the scaling factor picture character. letter b indicates a blank character. K specifies that the exponent field appears to the right of the associated position. It does not specify a character in the numeric character data STERLING PICTURES item. E specifies that the associated position The following picture characters are used contains the letter E, which indicates in picture specifications for sterling the start of the exponent field. data: The value of the exponent is adjusted in the character-string value so that the 8 specifies the position of a shilling first significant digit of the first field digit in BSI single-character (the mantissa) appears in the position representation. Ten shillings is associated with the first digit specifier represented by a 12-punch (&) and of the specification (even if it is a zero eleven through nineteen shillings are suppression character). represented by the characters A through I, respectively. 7 specifies the position of a pence SCALING FACTOR digit in BSI single-character representation. Ten pence is represented by a 12-punch (&) and The picture character F specifies a scaling eleven pence is represented by an factor for fixed-point decimal numbers. It 11-punch (-). appears at the right end of the picture specification and is used in the following 6 specifies the position of a pence digit format: in IBM single-character representation. Ten pence is represented by an 11-punch F ([+|-] decimal-integer-constant) (-) and eleven pence is represented by a 12-punch (&). F specifies that the optionally signed decimal integer constant enclosed in P specifies that the associated position parentheses is the scaling factor. The contains the pence character D. scaling factor specifies that the decimal point in the arithmetic value G specifies the start of a sterling of the variable is that number of picture. It does not specify a places to the right (if the scaling character in the numeric character data factor is positive) or to the left (if item. negative) of its assumed position in the character-string value. H specifies that the associated position contains the shilling character S. For System/360 implementations, the scaling factor cannot specify a M specifies the start of a field. It fixed-point number that contains more does not specify a character in the than 15 digits. numeric character data item. Figure D-8. Examples of Scaling Factor Picture Characters Section D: Picture Specification Characters 261 Figure D-9 gives examples of the use of One of the nines can be replaced by T, I, sterling picture specifications. or R, if no other sign indicator appears in any of the fields of the specification. Sterling data items are considered to be real fixed-point decimal data. When involved in arithmetic operations, they are "Separator 2" can be one or more of the converted to a value representing picture characters: fixed-point pence. Sterling pictures have the general form: The "pence field" takes the form: One of the nines can be replaced by T, I, or R, if no other sign indicator appears in any of the fields of the specification. "Editing character 1" can be one or more of the following static picture characters: "Editing character 2" can be one or more of the static picture characters $, +, -, or S and one or more of B, P, CR, or DB. A sign character or CR or DB can appear only The "pounds field" can contain the if no other sign indicator appears in any following picture characters: of the fields of the specification. The pounds, shillings, and pence fields must each contain at least one digit The last four characters ($ + - S) must position. be drifting characters. The comma can be used as an insertion character. Zero suppression in sterling pictures is performed on the total data item, not "Separator 1" can be one or more of the separately on each of the pounds, following picture characters: shillings, and pence fields. The Z picture character is not allowed to the right of a 6, 7, 8, or 9 picture character in a sterling specification. In sterling The "shillings field" can be: pictures, the field separator characters slash (/), point (.), B, and H are never suppressed. Figure D-9. Examples of Sterling Picture Specifications 262 Section E: Edit-Directed Format Items This section describes each of the converted field. Leading blanks will not edit-directed format items that can appear appear in the stream, however, unless the in the format list of a GET or PUT specified field width allows for them. statement. Truncation, due to inadequate field-width specification is on the left for arithmetic There are three categories of format items, on the right for string items. items: data format items., control format items, and the remote format item. Note that the value of binary data both on input and output is always represented In this section, the three categories in decimal form for edit-directed are discussed separately and the format transmission. items are listed under each category. The remainder of the section contains detailed Following is a list of data format discussions of each of the format items, items: with the discussions appearing in alphabetic order. Fixed-point F(specification) format item Floating-point E(specification) Data Format Items format item Complex format C(specification) A data format item describes the external item format of a single data item. Picture format P'picture-specification' For input, the data in the stream is item considered to be a continuous string of characters; all blanks are treated as Bit-string B(specification) characters in the stream, as are quotation format item marks. Each data format item in a GET statement specifies the number of Character-string A(specification) characters to be obtained from the stream format item and describes the way those characters are to be interpreted. strings should not be enclosed in quotation marks, nor should the letter B be used to identify bit strings. If the characters in the stream cannot be Control Format Items interpreted in the manner specified, the CONVERSION condition is raised. The control format items specify the layout For output, the data in the stream takes f the data set associated with a file. the form specified by the format list. The following is a list of control format Each data format item in a PUT statement items: specifies the width of a field into which the associated data item in character form Paging format PAGE is to be placed and describes the format item that the value is to take. Enclosing quotation marks are not inserted, nor is Line skipping SKIP[(specification)] the letter B to identify bit strings. format item Leading blanks are not inserted Line position LINE (specification) automatically to separate data items in the format item output stream. String data is left-adjusted in the field, whose width is Column position COLUMN(specification) specified. Arithmetic data is right-adjusted. Because of the rules for conversion of arithmetic data to character Spacing X(specification) type, which can cause up to three leading format item blanks to be inserted (in addition to any blanks that replace leading zeros), there A control format item has no effect generally will be at least one blank unless it is encountered before the data preceding an arithmetic item in the list is exhausted. Section E: Edit-Directed Format Items 263 The PAGE and LINE format items apply Alphabetic List of Format Items only to output and only to files with the PRINT attribute. The SKIP and COLUMN format items apply to both input and The A Format Item output. The A format item is: The PAGE, SKIP, and LINE format items have the same effect as the corresponding A [(field-width)] options of the PUT statement (and of the GET statement, in the case of SKIP), except The character-string format item that the format items take effect only when describes the external representation of a they are encountered in the format list, string of characters. while the options take effect before any data is transmitted. General rules: 1. The "field width" is an expression The COLUMN format item positions the that is evaluated and converted to an file to the specified character position in integer each time the format item is the current line. used. It specifies the number of character positions in the data stream that contain (or will contain) the The spacing format item specifies string. relative horizontal spacing. On input, it specifies a number of characters in the 2. On input, the specified number of stream to be skipped over and ignored; on characters is obtained from the data output, it specifies a number of blanks to stream and assigned, with any be inserted into the stream. necessary conversion, truncation, or padding, to the associated element in the data list. The field width is always required on input, and if it has a value less than or equal to zero, a null string is assumed. If Remote Format Item quotation marks appear in the stream, they are treated as characters in the string. The remote format item specifies the label of a FORMAT statement that contains a 3. On output, the associated element in format list which is to be taken to replace the data list is converted, if the remote format item. necessary, to a string of characters and is truncated or extended with The remote format item is: blanks on the right to the specified field width before being placed into R(statement-label-designator) the data stream. If the field width is less than or equal to zero, the The "statement label designator" is a format item and its associated element label constant or an element label in the data list are skipped, and no variable. characters are placed into the data stream. Enclosing quotation marks are never inserted. If the field width is not specified, it is assumed to be equal to the character-string length of the element named in the data list Use of Format Items (after conversion, if necessary, according to the rules given in Section F, "Problem Data Conversion"). The "specification" that is listed above for all but the picture, PAGE, and remote format items can contain one or more expressions. Such expressions can be The B Format Item specified as decimal integer constants, as element variables, or as other element expressions. The value assigned to a The B format item is: variable during an input operation can be used in an expression in a format item that B [(field-width)] is associated with a later data item. An expression is evaluated and converted to an The bit-string format item describes the integer each time the format item is used. external representation of a bit string. 264 Each bit is represented by the character 0 The P format item must describe or 1. fixed-point or floating-point numeric character data; it cannot describe General rules: sterling or character-string data. 1. The "field width" is an expression 2. On input, the complex format item that is evaluated and converted to an describes the real and imaginary parts integer each time the format item is of the complex data item within used. It specifies the number of adjacent fields in the data stream. data-stream character positions that If the second real format item is contain (or will contain) the bit omitted, it is assumed to be the same string. as the first. The letter I will cause the CONVERsION condition to be raised. 2. On input, the character representation of the bit string may occur anywhere 3. On output, the real format items within the specified field. Blanks, describe the forms of the real and which may appear before and after the imaginary parts of the complex data bit string in the field, are ignored. item in the data stream. If the Any necessary conversion occurs when second real format item is omitted, it the bit string is assigned to the is assumed to be the same as the associated element in the data list. first. The letter I is never appended The field width is always required on to the imaginary part. If the second input, and if it is less than or equal real format item (or the first, if to zero, a null string is assumed. only one appears) is an F or F item, Any character other than 0 or 1 in the the internal sign will be printed only string, including embedded blanks, if the value of the imaginary part is quotation marks, or the letter B, will less than zero. If the real format raise the CONVERSION condition. item is a P item, the sign will be printed only if the s or - or + 3. On output, the character picture character is specified. If representation of the bit string is the I is to be appended, it must be left-adjusted in the specified field, specified as a separate data item in and necessary truncation or extension the data list, immediately following with blanks occurs on the right. Any the variable that specifies the necessary conversion to bit-string is complex item. The I, then, must have performed. No quotation marks are a corresponding format item (either A inserted, nor is the identifying or P). letter B. The field width need not be specified when the associated element in the data list is a bit string; in The COLUMN Format Item this case, the current length of the associated string is used, and the data item completely fills the field. The COLUMN format item is: The field width is always required if the data-list item is arithmetic or COLUMN (character-position) pictured. If the field width is less than or equal to zero, the format item The column position format item and its associated element in the data positions the file to a specified character list are skipped, and no characters position within the line. It can be used are placed into the data stream. with either input or output files. General rules: The C Format Item 1. The "character position" can be specified by an expression, which is evaluated and converted to an integer The C format item is: each time the format item is used. C(real-format-item[,real-format-item]) 2. The file is positioned to the specified character position in the The complex format item describes the current line. On input, intervening external representation of a complex data character positions are ignored; on item. output, they are filled with blanks. If the file is already positioned General rules: after the specified character position, the current line is completed and a 1. Each "real format item" is specified new line , is started; the format item by one of the F, E, or P format items. is then applied to the new line. Section E: Edit-Directed Format Items 265 3. If the specified character position located anywhere within the specified lies beyond the rightmost character field. If the data item is a position of the current line, or if fixed-point number, an exponent of the value of the expression for the zero is assumed. character position is less than one, then the character position is assumed The external form of a floating-point to be one. number is: Note: The rightmost character position is determined as follows: a. For output files, it is determined The mantissa must be a decimal by the line size; fixed-point constant. b. For input files, the F Compiler a. The number can appear anywhere uses the length of the current within the specified field; blanks logical record to determine the may appear before and after the line size and, hence, the number in the field and are rightmost character position. In ignored. If the entire field is the case of V-format records, this blank, the CONVERSION condition is line size is equal to the logical raised. When no decimal point record length minus the number of appears, the expression for the bytes containing control number of fractional digits information. specifies the number of character positions in the mantissa to the 4. The COLUMN format item has no effect right of the assumed decimal unless it is encountered before the point. If a decimal point does data list is exhausted. appear in the number, it overrides the specification of the number of the fractional digits. The E Format Item The value expressed by "field width" includes trailing blanks, the exponent position, the The E format item is: positions for the optional plus or minus signs, the position for the E(field-width,number-of-fractional-digits optional letter E, and the [,number-of-significant-digits]) position for the optional decimal point in the mantissa. The floating-point format item describes the external representation of decimal b. The exponent is a decimal integer arithmetic data in floating-point format. constant. Whenever the exponent and preceding sign or letter E are General rules: omitted, a zero exponent is assumed. 1. The "field width," "number of fractional digits," and "number of 3. On output, the internal data is significant digits" can be represented converted to floating-point, and the by expressions, which are evaluated external data item in the specified and converted to integers when the field has the following general form: format item is used. "Field width" specifies the total number of characters in the field. In this form, s represents the number "Number of fractional digits" of significant digits, and d specifies the number of digits in the represents the number of fractional mantissa that follow the decimal digits. The value is rounded if point. necessary. "Number of significant digits" a. The exponent is a two-digit specifies the number of digits that decimal integer constant, which must appear in the mantissa. may be two zeros. The exponent is automatically adjusted so that the 2. On input, the data item in the data leading digit of the mantissa is stream is the character representation nonzero. When the value is zero, of an optionally signed decimal zero suppression is applied to all floating-point or fixed-point constant digit positions (except the first) 266 to the left of the decimal point. General rules: All other digit positions contain zero. 1. The "field width," "number of fractional digits," and "scaling b. If the above form of the number factor" can be represented by element does not fill the specified field expressions, which are evaluated and on output, the number is converted to integers when the format right-adjusted and extended on the item is used. left with blanks. If the number of significant digits is not 2. On input, the data item in the data specified, it is taken to be 1 stream is the character representation plus the number of fractional of an optionally signed decimal digits. For System/360 fixed-point constant located anywhere implementations, the field width within the specified field. Blanks for non-negative values of the may appear before and after the number data item must be greater than or in the field and are ignored. If the equal to 5 plus the number of entire field is blank, it is significant digits. For negative interpreted as zero. values of the data item, the field width must be greater than or The number of fractional digits, if equal to 6 plus the number of not specified, is assumed to be zero. significant digits. However, if the number of fractional digits is If no scaling factor is specified and zero, the decimal point is not no decimal point appears in the field, written, and the above figures for the expression for the number of the field width are reduced by 1. fractional digits specifies the number of digits in the field to the right of c. The rounding of internal data is the assumed decimal point. If a as follows: if truncation causes a decimal point actually does appear in digit to be lost from the right, the data, it overrides the expression and this digit is greater than or for the number of fractional digits. equal to 5, then 1 is added to the digit to the left of the truncated If a scaling factor is specified, it digit. effectively multiplies the value of the data item in the data stream by 10 d. If the field width is such that raised to the integral value (p) of significant digits or the sign is the scaling factor. Thus, if p is lost, the SIZE condition is positive, the number is treated as raised. though the decimal point appeared p places to the right of its given 4. When using the E format item E(w,d,s), position. If p is negative, the s must be less than 17 digits. When number is treated as though the using E(w,d), d must be less than 16 decimal point appeared p places to the digits. If the number of significant left f its given position. The given digits in E format data is greater position of the decimal point is that than 16, then: indicated either by an actual point, if it appears, or by the expression E format input: CONVERSION condition for the number of fractional digits, raised in the absence of an actual point. E format output: ERROR condition raised 3. On output, the internal data is converted, if necessary, to fixed-point; the external data is the character representation of a decimal fixed-point number, rounded if necessary, and right-adjusted in the specified field. The F Format Item If only the field width is specified in the format item, only the integer The F format item is: portion of the number is written; no decimal point appears. F(field-width[,number-of-fractional-digits [,scaling-factor]]) If both the field width and number of fractional digits are specified, but The fixed-point format item describes the scale factor is not, both the the external representation of a decimal integer and fractional portions of the arithmetic data item in fixed-point format. number are written. If the value (d) Section E: Edit-Directed Format Items 267 of the number of fractional digits is 3. If the specified line has already been greater than zero, a decimal point is passed on the current page, or if the inserted before the rightmost d specified line is beyond the limits digits. Trailing zeros are supplied set by the PAGESIZE option of the OPEN when the number of fractional digits statement (or by default), the ENDPAGE is less than d (the value d must be condition is raised. less than the field width). Suppression of leading zeros is 4. If "line number" is less than or equal applied to all digit positions (except to zero, it is assumed to be one. the first) to the left of the decimal point. 5. The LINE format item has no effect unless it is encountered before the The rounding of internal data is as data list is exhausted. follows: if truncation causes a digit to be lost from the right, and this digit is greater than or equal to 5, The P Format Item then 1 is added to the digit to the left of the truncated digit. The P format item is: The integer value (p) of the scaling factor effectively multiplies the P 'picture-specification' value of the associated element in the data list by 10 raised to the power of The picture format item describes the p, before it is edited into its external representation of numeric external character representation. character data and of character-string When the number of fractional digits data. is zero, only the integer portion of the number is used. The "picture specification" is discussed in detail in Section D, "Picture On output, if the value of the Specification Characters" and in the fixed-point number is less than zero, discussion of the PICTURE attribute in a minus sign is prefixed to the Section I, "Attributes." external character representation; if it is greater than or equal to zero, On input, the picture specification no sign appears. Therefore, for describes the form of the data item negative values of the fixed-point expected in the data stream and, in the number, the field width specification case of a numeric character string, how its must include a count of both the sign arithmetic value is to be interpreted. and the decimal point. Note that the picture specification should accurately describe the data in the input If the field width is such that stream, including characters represented by significant digits or the sign is editing characters. If the indicated lost, the SIZE condition is raised. character does not appear in the stream, the CONVERSION condition is raised. The LINE Format Item On output, the value of the associated element in the data list is edited to the form specified by the picture specification The LINE format item is: before it is written into the data stream. LINE (line-number) The line position format item specifies The PAGE Format Item the particular line on a page of a PRINT file upon which the next data item is to be printed. The PAGE format item is: General rules: PAGE 1. The "line number" can be represented The paging format item specifies that a by an expression, which is evaluated new page is to be established. It can be and converted to an integer each time used only with PRINT files. the format item is used. General rules: 2. The LINE format item specifies that blank lines are to be inserted so that 1. The establishment of a new page the next line will be the specified implies that the next printing is to line of the current page. be on line one. 268 2. The PAGE format item has no effect General rules: unless it is encountered before the data list is exhausted. 1. The "relative position of next line" can be specified by an element expression, which is evaluated and converted to an integer each time the format item is used. It must be The R Format Item greater than zero for non-PRINT files. If it is not, or if it is omitted, 1 is assumed. The R format item is: 2. The new line is the specified number R (statement-label-designator) of lines beyond the present line. The remote format item allows format 3. If the value of the relative position items in a FORMAT statement to replace the is greater than one, then on input, remote format item. one or more lines will be ignored; on output, one or more blank lines will General rules: be inserted. 1. The "statement label designator" is a 4. The value of the relative position may label constant or an element label be less than or equal to zero for variable that has as its value the PRINT files only; the effect is that statement label of a FORMAT statement. of a carriage return without line The FORMAT statement includes a format spacing. Characters previously list that is taken to replace the written may be overprinted. format item. 5. If the SKIP format item is not 2. The R format item and the specified specified at the end of a line, then FORMAT statement must be internal to SKIP (1) is assumed, that is, single the same block. (If the procedure is spacing. executed recursively, they must be in the same invocation.) 6. For PRINT files, if the specified relative position is beyond the limit 3. There can be no recursion within a set by the PAGESIZE option of the OPEN FORMAT statement. That is, a remote statement (or the default), the FORMAT statement cannot contain an R ENDPAGE condition is raised. format item that names itself as a statement label designator, nor can it 7. The SKIP format item has no effect name another remote FORMAT statement unless it is encountered before the that will lead to the naming of the data list is exhausted. original FORMAT statement. Avoidance of recursion can be assured if the FORMAT statement referred to by a remote format item does not itself The X Format Item contain a further remote format item. 4. Any conditions enabled for the GET or The X format item is: PUT statement must also be enabled for the remote FORMAT statement(s) that X (field-width) are referred to. The spacing format item controls the 5. If the GET or PUT statement is the relative spacing of data items in the data single statement of an on-unit, it stream. It is not limited to PRINT files. cannot contain a remote format item. General rules: 1. The "field width" can be represented The SKIP Format Item by an expression, which is evaluated and converted to an integer each time the format item is used. The integer The SKIP format item is: specifies the number of blanks before the next field of the data stream, SKIP[(relative-position-of-next-line)] relative to the current position in the stream. The line skipping format item specifies that a new line is to be defined as the 2. On input, the specified number of current line. characters is spaced over in the data Section E: Edit-Directed Format Items 269 stream and not transmitted to the 4. If the field width is less than zero, program. it is assumed to be zero. 3. On output, the specified number of 5. The spacing format item has no effect blank characters are inserted into the unless it is encountered before the stream. data list is exhausted. 270 Section F: Problem Data Conversion This section lists the rules for arithmetic represented in binary. The magnitude of conversion and for conversion of problem such changes in value depends upon the data types. Each type conversion is listed precisions of the target and source. In under a separate heading. In addition to expression evaluation, the precision of the the text, 14-figures appear: target is derived from the precision of the source. In order to estimate and to • Figures F-3 through F-6 show the data understand the errors that can occur, the type of the result of an operation precision rules must be understood; and involving two operands of possibly since the rules also leave some latitude differing types. Note that although for the implementation, it is helpful to the figures are for two operands, these have some knowledge of the way in which operands could themselves be the result conversions are implemented. of other operations: any expression involving a number of infix operators will be eventually reduced, during evaluation, to a single infix operation with two operands. Note also that the result is the result of the expression only, and may be converted on Floating-Point Conversion subsequent assignment. • Figure F-7 states the rules for In System/360 implementations, both decimal computing the precision of the result and binary floating-point numbers are of an arithmetic conversion. maintained in the internal hexadecimal form used in System/360. If the specified • Figure F-8 states the rules for precision is more than 6 decimal digits, or computing the length of the result of 21 binary digits, the number is maintained an arithmetic to character-string in long floating-point form (14 hexadecimal conversion. digits with a hexadecimal exponent). If the precision is 6 decimal digits or less, • Figure F-9 states the rules for or 21 binary digits or less, the number is computing the length of the result of maintained in short floating-point form (6 an arithmetic to bit-string conversion. hexadecimal digits and a hexadecimal exponent). • Figure F-10 can be used to find the ceiling (CEIL) of any value between 1 No actual conversions between binary and and 15 when that value is multiplied by decimal are performed on floating-point 3.32 or it can be used to find the data. The only precision changes are from ceiling (CEIL) of any value between 1 long to short, which is done by truncation, and 56 when that value is divided by and from short to long, which is done by 3.32. extending with zeros. The declared precision of floating-point data and the • Figures F-11 through F-14 illustrate base, however, do affect the calculation of conversion in arithmetic expression target attributes, as well as the operations, and they give attributes of attributes of intermediate forms that are the results based upon the operator determined from the source. specified and the attributes of the two operands. Mode Conversion ARITHMETIC CONVERSION If a complex value is converted to a real The rules for arithmetic conversion specify value, the result is the real part of the the way in which a value is transformed complex value. from one arithmetic representation to another. It can be that, as a result of If a real value is converted to a the transformation, the value will change. complex value, the result is a complex For example, the number .2, which can be value that has the value of the real source exactly represented as a decimal as the real part and zero as the imaginary fixed-point number, cannot be exactly part. Section F: Problem Data Conversion 271 Precision Conversion constant is derived from the way in which it is written. Care should therefore be taken when writing noninteger constants Precision conversion occurs if the that will be converted to fixed-point specified target precision is different binary. from the source precision. In particular, there always is a precision change when the The following examples illustrate how source and target are of different bases. the representation of a decimal constant It is also possible that there is an actual (.1) is converted when used in an change in precision when converting from arithmetic expression (such as A+.1). floating-point to fixed-point, because of Target attributes are derived from the the way in which floating-point numbers are attributes of A, the operator, and the represented. Precision changes are attributes of the constant, which are, in performed by truncation or by padding with this case, DECIMAL FIXED (1,1). zeros. Floating-point numbers are converted from short precision to long Attributes of A: FIXED BIN(10,2) precision by extending with zeros on the Value: .1 right, and from long precision to short Target: FIXED BIN(5,4) precision by truncation on the right. Final Value: .0625 Fixed-point numbers maintain decimal or Attributes of A: FLOAT BIN(50) binary point alignment and may be truncated Value: .1 on the left or right, or extended with Target: FLOAT BIN(4) zeros on the left or right. Final Value: .1>value>.0625 No indication is given of loss of significant digits on the right. Loss of digits on the left can be checked for if the SIZE condition is enabled. In Coded Arithmetic to Numeric Character System/360 implementations, binary fixed-point numbers are stored in words of 31 bits, whatever the declared width. Coded arithmetic data being converted to Decimal numbers are always stored as an odd numeric character is converted, if number of digits, since they are maintained necessary, to a decimal value whose scale in System/360 packed decimal format, with and precision are determined by the PICTURE the rightmost four bits of the rightmost attribute of the numeric character item. byte expressing the sign. Base Conversion Numeric Character to Coded Arithmetic Changes in base will usually affect only Numeric character data being converted to the value of noninteger fixed-point coded arithmetic is first interpreted as a numbers. Some decimal fractions cannot be decimal item of the scale and precision expressed exactly in binary, and some determined by the corresponding PICTURE errors will then occur due to truncation. attribute. This item is then converted to Some binary fractions will also require the base, scale, and precision of the coded more decimal digits for exact arithmetic target. representation than are automatically generated by the conversion rules, and this may also cause errors resulting from truncation. DATA TYPE CONVERSION Since the range of binary fixed-point numbers is smaller than the range of decimal fixed-point numbers, it is possible Character-String to Arithmetic for significant digits to be lost on the left in conversion from decimal to binary. This will raise the SIZE condition, but an The source string must represent a valid interrupt will not occur unless the arithmetic constant or complex expression. condition is explicitly enabled by a SIZE The constant may optionally be signed, and prefix. may be surrounded by blanks, but cannot contain blanks between the sign and the The natural notation for constants is value of the constant, or between the end decimal and, therefore, most constants are of the real part and the sign of the written in decimal. The precision of a imaginary part in a complex expression. 272 The permitted forms are: In the case of the conversion of expression results, the intermediate string [+|-]arithmetic-constant is assigned to the target string, and may be truncated or padded with zeros on the [+I-]real-constant{+|-}imaginary-constant right. A null string gives the value zero. Since the rules of arithmetic to character-string conversion are also used for list-directed and data-directed output, The constant will itself have the and for evaluating keys {even for REGIONAL attributes of base, scale, mode, and files) this type of conversion will be precision. It will be converted to conform found in most programs, and should be with the attributes of the target. thoroughly understood. Even when converting from character string to numeric character field, the Numeric Character to Character-String source must still contain a constant which is valid according to the rules for Real numeric character fields are constants in PL/I source programs. The treated as character strings and assigned value of this constant is then converted to the target string from left to right and edited to the picture representation. according to the rules for character-string assignment. The following example will therefore result in a conversion error: The real and imaginary parts of complex numeric character fields are concatenated, DCL A PICTURE '$$$9V.99'; and the resulting string is assigned to the target. No character, including I or A='$17.95'; blank, is inserted between or following the two parts. The currency symbol makes the character-string constant invalid for conversion to the arithmetic value of the Fixed-Point to Character-String numeric character variable, even though its character-string value contains a currency A binary fixed-point source is first symbol. converted to decimal, and the decimal precision is derived from the precision of Correct examples are: the binary source (see Figure F-7, "Precision for Arithmetic Conversions"). A='17.95'; A decimal fixed-point source with A=17.95; • precision (p,q) is converted to character-string representation as follows: either of which would result in A having the character-string value b$17.95. 1. If p>=q>= 0 (that is, if the assumed decimal point lies within the field of For conversion from character string to the internal representation) then: arithmetic, the attributes assumed for the target are those attributes that would have • The constant is right adjusted in a been assumed if a fixed-point decimal field of width p+3. integer of precision (15,0) had appeared in place of the string. (The precision given • Leading zeros are replaced by is that for the F Compiler.) blanks, except for a single zero that immediately precedes the decimal point of a fractional number. Arithmetic to Character-String • If the value is negative, a minus sign precedes the first significant digit (or the zero before the point The arithmetic value is converted to a of a fractional number). Positive decimal arithmetic constant. The constant values are unsigned. is inserted in an intermediate character string whose length is derived from the • Unless the source is an integer, attributes of the source (see Figure F-8, the constant has q fractional "Lengths of Converted Character Strings"). digits. If the source is an Except for the base and precision, the integer, there is no decimal point. attributes of the constant are the same as the attributes of the source. 2. If q is negative or greater than p, a Section F: Problem Data Conversion 273 Figure F-1. Examples of Conversion from Fixed-Point to Character-String scaling factor is appended to the Floating-Point to Character-String right of the constant. The constant itself is of the same form as an If the source is binary, its binary integer. The scaling factor has the precision is converted to the equivalent form: decimal precision (see Figure F-7, "Precision for Arithmetic Conversions"). F{+|-}nnn The decimal source with precision p is converted as if it were transmitted by an E where {+|-}nnn has the value -q. format item of the form E(w,d,s) where: w, the length of the intermediate The number of digits in the scaling string, is p+6 (for the F Compiler) factor is just sufficient to contain the value of q without leading zeros. d, the number of fractional digits, is p-1 The length of the intermediate string is: s, the number of significant digits, is p p+3+k For the F Compiler, an E format item generates a floating-point decimal constant where k is the number of digits with a signed two-digit exponent. (See necessary to represent the value of q Part II, Section E, "Edit-Directed Format (not including a sign or the letter Items.") F). For example, given: The following examples illustrate the DCL A FIXED(4,-3), intermediate string generated for a C CHAR(10); floating-point to character-string A=1234.0E3; conversion: C=A; Source Attributes: FLOAT DEC(6) The intermediate string generated in Source Value: 1735x105 converting A would be: Intermediate String: b1.73500E+08 b1234F+3 Source Attributes: FLOAT BIN(20) Source Value: -91882x102 which, when assigned to C, would give: Intermediate String: -9.188200E+06 b1234F+3bb Source Attributes: FLOAT DEC(5) Source Value: -.0016632 Other examples are shown in Figure F-1. Intermediate String: -1.6632E-03 274 Complex to Character-String If the source bit string is shorter than the target character string, the remainder of the target is padded with blanks. The intermediate string that is generated contains a complex expression. Its length is 1 plus twice the length of The following are examples of bit-string the character string generated by a real to character-string conversion: source with corresponding attributes. The intermediate string consists of two concatenated strings. The left-hand, or real, part consists of a string generated exactly as for a real source. The right-hand, or imaginary, part is always signed, and it has an I appended. The string length of the imaginary part is one Source Value: '101011B CHAR(10) VAR character longer than the real part (to Target Attributes: allow for the I). The resulting string is Result: '10101' a complex expression, with a sign but no blanks between its elements. Source Value: '10101'B Target Attributes: CHAR(10) The following examples illustrate the Result: '10101bbbbb' intermediate string that results from a complex to character-string conversion: Source Value: '0001'B Target Attributes: CHAR(1) Result: '0' Source: COMPLEX DEC FLOAT(5) Value: 17.3+1.5I Result: b1.7300E+01+1.5000E+001 The CONVERSION condition cannot be raised on conversion from bit to character; Source: COMPLEX DEC FIXED(4,3) however, a character string created by conversion from a bit string can cause a Value: 0.133+0.007I Result: bbb0.133+0.007I conversion error when reconverted if blanks have been inserted. Character-String to Bit-string Arithmetic to Bit-string The character 1 in the source string becomes the bit 1 in the target string. The absolute arithmetic value is first The character 0 in the source string converted to a real binary integer, whose becomes the bit 0 in the target string. precision is the same as the length of the Amy character other than 0 and 1 in the bit-string target as given in Figure F-9. source string will raise the CONVERSION This integer, without a sign, is then condition. A null character string becomes treated as a bit string. This intermediate a null bit string. string is then assigned to the target. If the source string is longer than the Examples are shown in Figure F-2. target, excess characters on the right are ignored (so that excess characters other than 0 or 1 will not raise the CONVERSION condition). If the target is longer than the source, the target is padded on the Bit-string to Arithmetic right with zeros. For the F Compiler, the effect is as if the bit string were interpreted as an unsigned binary integer of maximum precision (56,0). Bit-string to Character-String If the string is longer than 56 bits, bits on the left are ignored: the SIZE condition will be raised if nonzero bits are lost, The bit 0 becomes the character 0, and the provided that SIZE is enabled. Note that bit 1 becomes the character 1. A null bit truncation is on the left, not on the string becomes a null character string. right. The null string gives the value The generated character string, which has zero; otherwise, the result of a bit-string the same length as the source bit string, to arithmetic conversion is always is assigned to the target. positive. Section F: Problem Data Conversion 275 Figure F-2. Examples of Conversion From Arithmetic to Bit-string Figure F-3. Data Type of Result of Bit-string Operation Figure F-4. Data Type of Result of Concatenation Operation Figure F-5a. Data Type of Result of Comparison Operation 276 Figure F-5b. Data Type of Intermediate Operands of Comparison Operation Figure F-6. Data Type of Result of Arithmetic Operation Figure F-7. Precision for Arithmetic Conversions Section F: Problem Data Conversion 277 Figure F-8. Lengths of Converted Character Strings (Arithmetic To Character-String) Figure F-9. Lengths of Converted Bit Strings (Arithmetic to Bit-Strings) Figure F-10. Ceiling Values 278 CEILING VALUES RESULTS OF ARITHMETIC OPERATIONS Figure F-10 is intended to aid the Figures F-11 through F-14 give the programmer in computing the ceiling values attributes of the results of arithmetic used to determine precisions and lengths in operations, based on the operator specified conversions. It gives the ceiling for the and the attributes of the two operands. In result of a multiplication by 3.32 of any these figures, the target precisions (i.e., value {x) between 1 and 15. It also gives the precisions of the converted operands) the ceiling for the result of a division by can never exceed the implementation-defined 3.32 of any value {y) between 1 and 56. maximums, which, for System/360 implementations, are: 15 for FIXED DECIMAL, 31 for FIXED BINARY, 16 for FLOAT DECIMAL, and 53 for FLOAT BINARY. Figure F-11. Attributes of Result in Addition and Subtraction Operations Section F: Problem Data Conversion 279 Figure F-12. Attributes of Result in Multiplication Operations Figure F-13. Attributes of Result in Division Operations 280 Figure F-14. Attributes of Result in Exponentiation Operations Section F: Problem Data Conversion 281 Section G: Built-In Functions and Pseudo-Variables All of the built-in functions and Mathematical: pseudo-variables that are available to the ATAN LOG10 PL/I programmer are given in this section. ATAND LOG2 The general organization of this section is ATANH SIN as follows: COS SIND COSD SINH 1. Computational Built-in Functions COSH SQRT ERF TAN ERFC TAND a. String-handling built-in functions EXP TANH LOG b. Arithmetic built-in functions Array Manipulation: c. Mathematical built-in functions ALL LBOUND ANY POLY DIM PROD d. Array manipulation built-in HBOUND SUM functions 2. Condition Built-in Functions The condition built-in functions allow the PL/I programmer to investigate interrupts arising from enabled 3. Based Storage Built-in Functions ON-conditions. The condition built-in functions are: 4. Multitasking Built-in Functions 5. Miscellaneous Built-in Functions DATAFIELD ONFILE 6. Pseudo-Variables ONCHAR ONKEY ONCODE ONLOC The computational built-in functions, ONCOUNT ONSOURCE shown above, provide string handling, arithmetic operations (addition, division, etc.), mathematical operations (trig- onometric functions, square root, etc.), The based storage built-in functions are and array manipulation. The computational designed to facilitate list processing and built-in functions are: the use of based storage. They mainly return special values which can be assigned String Handling: to locator and area variables. The based BIT REPEAT storage built-in functions are: BOOL STRING CHAR SUBSTR HIGH TRANSLATE ADDR NULL INDEX UNSPEC EMPTY NULLO | LENGTH VERIFY LOW Arithmetic: The multitasking built-in functions ABS IMAG allow the programmer to investigate the ADD MAX current state of a task or asynchronous BINARY MIN input/output operation, or the current CEIL MOD priority of a task. The multitasking COMPLEX MULTIPLY built-in functions are: CONJG PRECISION DECIMAL REAL DIVIDE ROUND FIXED SIGN COMPLETION FLOAT TRUNC PRIORITY FLOOR STATUS 282 The miscellaneous built-in functions BIT String Built-in Function perform various duties; for example, one function provides the current date, another provides a count of data items transmitted Definition: BIT converts a given value to during a STREAM input/output operation, a bit string and returns the result to the while another provides an indication of point of invocation. This function allows whether or not a controlled variable is in the programmer to control the size of the an allocated state. The miscellaneous result of a bit-string conversion. built-in functions are: Reference: BIT (expression (, size ]) ALLOCATION LINENO COUNT TIME Arguments: The argument "expression" DATE represents the quantity to be converted to a bit string. The argument "size," when specified, must be a decimal integer The section on pseudo-variables gives a constant giving the length of the result. short discussion for each of the PL/I If "size" is not specified, it is pseudo-variables. A more complete determined according to the type conversion description can be found in the discussion rules given in Section F, "Problem Data of the corresponding built-in function. Conversion." If "expression" is an array The pseudo-variables are: expression, "size" applies to each element of the array. All of the built-in functions and pseudo-variables are presented in alphabetical order under their proper BOOL String Built-in Function headings. Definition: BOOL produces a bit string whose bit representation is a result of a given boolean operation on two given bit strings. Computational Built-In Functions Reference: BOOL (x,y,w) STRING HANDLING BUILT-IN FUNCTIONS Arguments: Arguments "x" and "y" are the two bit strings upon which the boolean operation specified by "w" is to be The functions described in this section may performed. If "x" and "y" are not bit be used for manipulating strings. Unless strings, they are converted to bit strings. it is specifically stated otherwise, any If "x" and "y" differ in length, the argument can be an element expression or an shorter string is extended with zeros on array expression. If an argument is an the right to match the length of the longer array, the value returned by the built-in string. function is an array with bounds identical to that argument (the function having been Argument "w" represents the boolean performed for each element of the array). operation. It is a bit string of length 4 For those functions where two or more array and is defined as n1 n 2 n3 n 4 , where each n arguments are allowed, the arguments must is either 0 or 1. There are 16 possible have identical bounds. Except where bit combinations and thus 16 possible otherwise stated an argument that is boolean operations. As for "x" and "y," specified as "string" can be an expression "w" is converted to a bit string {of length of any data type, but if it is arithmetic, 4) before the function is invoked, if it is converted to bit-string {if binary necessary. base) or character-string (if decimal base) before the function is invoked. If more than one argument is an array, the arrays must have identical bounds. All conversions mentioned in this Note that if only "w" is an array, the section are made according to the rules for returned value is an array with identical the conversion of expression operands as bounds, each element of which is the result specified in Section F, "Problem Data of the corresponding boolean operation Conversion." performed on "x" and "y." Section G: Built-In Functions and Pseudo-Variables 283 Result: The value returned by this and "y" as follows: the ith bit of z is set function is a bit string, z, whose length to the value of n2, n3 , or n4 depending is equal to the longer of "x" and "y." on the combination of the ith bits of "x" Each bit of z is determined by the boolean and "y" as shown in the following boolean operation on the corresponding bits of "x" table: third bit of Z is 1. Therefore, the value returned to the point of invocation is the bit string '101'B. CHAR String Built-in Function Definition: CHAR converts a given value to a character string and returns the result to the point of invocation. This function allows the programmer to control the size of the result of a character-string conversion. Example: In the following assignment statement, assume that U and ID have been Reference: CHAR (expression(, size]) declared as bit strings, XXX is the string '011'B, YYY is the string '110'B, and the Arguments: The argument "expression" boolean operator is '0110'B: represents the quantity to be converted to a character string. The argument "size," U=ID||BOOL (XXX, YYY, '0110'B); when specified, must be a decimal integer constant giving the length of the result. Further, assume that Z represents the value If "size" is not specified, it is returned to the point at which BOOL is determined according to the type conversion invoked (that is, Z is a bit string of on rules given in Section F, "Problem Data length 3 that is to be concatenated with Conversion." If "expression" is an array ID), then the boolean table for this expression, "size" applies to each element invocation of BOOL can be defined as: of the array. Result: The value returned by this function is "expression" converted to a character string. The length of this character string is determined by "size," as described above. HIGH String Built-in Function Definition: HIGH forms a character string of a given length from the highest character in the collating sequence; that is, each character in the constructed string is the highest character in the which is interpreted as follows: collating sequence. Whenever the ith bits of XXX and YYY are Reference: HIGH (i) 0 and 0, respectively, the ith bit of Z is 0; whenever the ith bits of XXX and Argument: The argument, "i," must be a YYY are 0 and 1, respectively, the ith decimal integer constant specifying the bit of Z is 1, and so on. length of the string that is to be formed. Thus, since the first bits of XXX and YYY Result: The value returned by this are 0 and 1, respectively, the first bit of function is a character string of length Z is 1; since the second bits of XXX and "i;" each character in the string is the YYY are 1 and 1, respectively, the second highest character in the collating bit of Z is 0; and since the third bits of sequence. For System/360 implementations, XXX and YYY are 1 and 0, respectively, the this character is stored as hexadecimal FF. 284 INDEX String Built-in Function LENGTH String Built-in Function Definition: INDEX searches a specified Definition: LENGTH finds the string length string for a specified bit or character of a given value and returns it to the string configuration. If the configuration point of invocation. is found, the starting location of that configuration within the string is returned Reference: LENGTH (string) to the point of invocation. Argument: The argument, "string," represents a character string or a bit Reference: INDEX {string, config) string whose length is to be found. The argument need not represent a string; if it does not, it is converted before the Arguments: Two arguments must be function is invoked to a character string specified. The first argument, "string," (if the argument is DECIMAL) or a bit represents the string to be searched; the string (if the argument is BINARY). second argument, "config," represents the bit or character string configuration for Result: The value returned by this which "string" is to be searched. If both function is a fixed binary integer of arguments are bit-string, no conversion is default precision giving the current length performed. If both arguments are binary, of "string." If "string " is an array or if one argument is bit and one binary, expression, an array of identical bounds is both arguments are converted to bit. returned. Otherwise both arguments are converted to character. Example: If XYZ is a varying-length character string whose maximum length is 30, but whose current length is 25, then If both arguments are arrays, the arrays the statement: must have identical bounds. I = LENGTH(SUBSTR(XYZ,4)); Result: The value returned by this will assign a binary value of 22 to I. function is a binary integer of default precision. This binary integer is either: LOW String Built-in Function 1. The location in "string" at which "config" has been found. If more than one "config" exists in "string," the Definition: LOW forms a character string location of the first one found (in a of specified length from the lowest left-to-right sense) will be returned. character in the collating sequence; i.e., each character of the formed string will be 2. The value 0, if "config" does not the lowest character in the collating exist within "string" or if either of sequence. the arguments has a length of zero. Reference: LOW (i) Example: If ASTRING is a character string Argument: The argument, "i" must be an containing: unsigned decimal integer constant specifying the length of the string being '912NAMEA,1,FIRST,2,SECOND' formed. then the statement: Result: The value returned by this function is a character string of length I = INDEX(ASTRING,'1,'); "i"; each character in the string is the lowest character in the collating sequence. will return a binary value of ten to the For System/360 implementations, this point of invocation. This binary value character is stored as hexadecimal 00. represents the location of the configuration '1,' within ASTRING. However, if the statement had been: REPEAT String Built-in Function I = INDEX(ASTRING,'1'); then a binary value of two would be Definition: REPEAT takes a given string returned to the point of invocation. This value and forms a new string consisting of value is the location of the first '1' the given string value concatenated with appearing within ASTRING. itself a specified number of times. Section G: Built-In Functions and Pseudo-Variables 285 Reference: REPEAT (string,i) varying string. For the F Compiler there is no implementation if x is an element of Arguments: The argument "string" an interleaved array of varying strings, or represents a character string or bit string a cross-section of array of structures to from which the new string will be formed. STRING built-in function. The concatenated The argument need not represent a string, string in the result has a maximum length however; if an argument other than a bit of 32,767 bytes. string or character string is specified, it is converted, before the function is invoked, to a bit or character string. SUBSTR String Built-in Function The argument "i" must be an optionally signed decimal integer constant. It Definition: SUBSTR extracts a substring of represents the number of times that user-defined length from a given string and "string" is to be concatenated with itself. returns the substring to the point of invocation. (SUBSTR can also be used as a If "string" is an array expression, the pseudo-variable.) value of "i" is applied to each element. Reference: SUBSTR (string,i[,j]) Result: The value returned by this function is "string" concatenated with Arguments: The argument "string" itself "i" times. In other words, the represents the string from which a returned value will be a string containing substring will be extracted. If this (1+1) occurrences of the value "string." argument is not a string, it will be If "i" is less than or equal to zero, the converted to a string. Argument "i" returned value is identical to the argument represents the starting point of the (i.e., the converted argument, if the substring and "j" represents the length of ori g inal argument was not a string). the substring. Arguments "i" and "j" must be integers or expressions that can be Example: If BSTR is a bit string converted to integers. containing '101'B, the statement If more than one argument is an array, A = REPEAT(BSTR,6); the arrays must have identical bounds. will cause the following value to be Assuming that the length of "string" is returned to the point of invocation: k, arguments "i" and "j" must satisfy the following conditions: '101101101101101101101`B 1. j must be less than or equal to k and greater than or equal to 0. STRING String Built-in Function 2. i must be less than or equal to k and greater than or equal to 1. Definition: STRING concatenates all the 3. The value of i+j-1 must be less than elements in an aggregate variable into a or equal to k. single string element. (STRING can also be used as a pseudo-variable.) Thus, the substring, as specified by "i" and "j" must lie within "string." Reference: STRING(x) If "j" is not specified, it is assumed Argument: The argument, "x," is an to be equal to the value of k-i+1. In element, array, or structure variable, other words, it is assumed to be the length composed either entirely of character of the remainder of "string," beginning at strings and/or numeric character data, or the ith position in "string." entirely of bit strings. If "x" is an element variable, the value returned is When these conditions are not satisfied, identical to the value of the variable. the SUBSTR reference causes the STRINGRANGE The argument, "x", cannot be an operational condition to be raised, if it is enabled. expression. "x" can be ALIGNED or If STRINGRANGE is not enabled, the result UNALIGNED; if it is ALIGNED, padding is not of the erroneous reference is undefined. included in the result. Result: The value returned by this Result: The value returned by this function is a varying-length string whose function is an element bit string or current length is defined as follows: character string, the concatenation of all the elements in "x." If "x" contains one 1. If j=0, the returned value is the null or more varying strings, the result is a string. 286 2. If j is greater than 0, the returned Result: The value returned by this value is that substring beginning at function is a string identical in length the ith character or bit of the first and value to the source string "s," except argument and extending j characters or that if any character/bit position of "s" bits. contains a character or bit that has been specified for replacement (by inclusion of 3. If j is not specified, the returned that value in the position string "p"), value is that substring beginning at that value will be replaced by the the ith character or bit and extending corresponding value from the replacement to the end of "string." string "r." The correspondence is by position: character/bit positions 1,2,3,... Example: If AAA is a character string of n of "p" correspond respectively to length 30, the statement: character/bit positions 1,2,3 ... n of "r." ITEM = SUBSTR(AAA, 7, 14); Example: will cause a 14-character substring to be extracted from AAA, starting at the seventh DECLARE (S,T) CHAR(10), character of AAA. The extracted string is (P,R) CHAR(3); then returned to the point of invocation, after which it is assigned to ITEM. P='.$'; R='.,D'; TRANSLATE String Built-in Function A: GET DATA(S); T=TRANSLATE(S,R,P); PUT DATA(T); Definition: TRANSLATE returns the GO TO A; translated value of a specified string to the point of invocation. The translation The above sequence reads in data from is performed in accordance with a SYSIN, translates commas to periods, translation table supplied in the form of periods to commas, and dollar signs to the two arguments to the function. character 'D', and writes out the result on SYSPRINT. Thus, if the string Reference: TRANSLATE(s,r[,p]) S='$12,345.50' were read in, the string T='D12.345,50' would be written out. (For Arguments: The argument "s" represents the the F Compiler, precisely the same result source string, i.e., the string that could be achieved by omitting P altogether supplies the value to be translated. and making R consist of the EBCDIC sequence Arguments "r" and "p" represent the except for the replacement of the comma, replacement and position strings period, and dollar-sign characters by the respectively; these strings correspond to period, comma, and 'D' characters each other to provide the translation respectively.) table. If "p" is not specified, an implementation-defined character string is provided; for the F Compiler, this string UNSPEC String Built-in Function consists of the 256 possible EBCDIC characters arranged in ascending order (i.e., from hexadecimal 00 through FF). Definition: UNSPEC returns a bit string that is the internal coded representation Arguments, where conversion is of a given value. (UNSPEC can also be used necessary, are converted according to the as a pseudo-variable.) following rules: If all arguments are bit-strings, or all arguments Reference: UNSPEC (x) character-strings, there is no conversion. If all arguments are binary, or the Argument: The argument, "x," may be an arguments comprise a mixture of binary and arithmetic or string constant, variable, or bit-string items only, the binary arguments expression, or an area, pointer, or offset are converted to bit-strings, and no variable, whose internal coded further conversion takes place. Otherwise, representation is to be found. all arguments that are not already character-strings are converted to Result: The value returned by this character-strings. The above conversions function is the internal coded are carried out according to standard PL/I representation of "x." This representation data conversion rules. If "r" is shorter is in bit-string form. The length of this than "p," it is padded on the right (with string depends upon the attributes of "x," blanks or zeros, depending on the string and is defined by System/360 type) to the length of "p." implementations as follows; Section G: Built - In Functions and Pseudo -Variables 287 1. If "x" is FIXED BINARY of precision source and verification strings (p,q), the length is as follows: respectively. Arguments, where conversion is necessary, are converted according to a. If p < 16, and the argument is a the following conversions: If both single variable the length is 16. arguments are bit-string, or character-strings, there is no conversion. b. If p < 16, and the argument is not If both arguments are binary, or if one a single variable the length is argument is bit-string and the other 32. binary, the binary arguments are converted to bit-strings, and no further conversion c. If p > 15 the length is 32. takes place. Otherwise, both arguments, if not already character-strings, are 2. If "x" is FIXED DECIMAL of precision converted to character-strings. The above (p,q), the length is defined as conversions are carried out according to 8*FLOOR ((p+2)/2). standard PL/I data conversion rules. | 3. If "x" is FLOAT BINARY of precision p, Result: The value returned by this the length is function is a fixed binary integer of default precision ((15,0) for the F a. 32, if p is less than or equal to Compiler), determined as follows: 21. Each character or bit, c, of the source b. 64, if p is greater than 21. string is examined to see if it is represented anywhere in the verification 4. If "x" is FLOAT DECIMAL of precision string, i.e., to determine if p, the length is INDEX(string-2,c)=0 a. 32, if p is less than or equal to 6. The characters or bits of the source string are examined from left to right. If an b. 64, if p is greater than 6. examined character or bit is not represented in the verification string, the 5. If "x" is a character-string of length index of that character or bit in the n or a numeric character data item source string is returned. If each whose character-string value is of character or bit in the source string is length n, the length is 8*n. represented in the verification string, the returned value is zero. If string-1 is 6. If "x" is a bit-string of length n, null the value 0 will be returned. If the length is n. string-2 is null and string-1 is not null the value 1 will be returned. 7. If "x" is complex, the length is twice that of the corresponding real value. Example: Assume that B is a character string of length 48, containing the 48 8. If "x" is a pointer, the length is 32. characters permitted in the 48-character set. The expression 9. If "x" is an offset, the length is 32. VERIFY(A,B) 10. If "x" is an area of size n, the length is 8*(n+16). will then return a value of zero for any value of A that consists solely of characters from the 48-character set, but will index the first character in a value VERIFY String Built-in Function of A that does not conform to the 48-character set (e.g., if A = 'P GT X' the returned value is zero; if A = 'P > X', the Definition: VERIFY examines two given returned value is 3). strings to verify that each character or bit in the first string is represented in the second string, returning a fixed binary value of 0 if this is the case; otherwise, ARITHMETIC BUILT-IN FUNCTIONS the value returned is the index of the first character (in the first string) that is not represented in the second string. All values returned by arithmetic built-in functions are in coded arithmetic form. Reference: VERIFY{string-1,string-2) The arguments of these functions should also be in that form. If an argument is Arguments: The arguments "string-1" and not coded arithmetic, then, before the "string-2" are expressions representing the function is invoked, it is converted to 288 coded arithmetic according to the rules short floating-point form is used; if the stated in Section F, "Problem Data precision is greater than (21), long Conversion.* Note, therefore, that in the floating-point form is used. function descriptions below, a reference to an argument always means the converted argument, if conversion was necessary. ABS Arithmetic Built-in Function In some function descriptions, the phrase "converted to the highest characteristics" is used; this means that Definition: ABS finds the absolute value the rules for mixed characteristics are of a given quantity and returns it to the followed (these rules are stated in the point of invocation. section "Data Conversion in Arithmetic Operations" in Part I, Chapter 4, Reference: ABS (x) "Expressions and Data Conversion.") Argument: The quantity whose absolute In general, an argument of an arithmetic value is to be found is given by "x." built-in function may be an element or array expression. If an argument is an Result: The value returned by this array, the value returned by the built-in function is the absolute value of "x." If function is an array of the same dimension "x" is real, the result is the positive and bounds as the argument (the function value of "x"; if "x" is complex, the result having been performed once for each element is the positive square root of the sum of of the array). Thus, for example, if an squares of the real and imaginary parts of array argument is passed to the absolute "x." The mode of the result is real, while value function ABS, the returned value is the base, scale, and precision are the same an array, each element of which is the as those of "x," with one exception: if "x" absolute value of the corresponding element is a complex fixed-point value of precision in the argument array. (p,q), the precision of the result is: Unless it is specifically stated (MIN(N,p+1),q) otherwise: 1. The mode of an argument may be real or complex. ADD Arithmetic Built-in Function 2. The base, scale, mode, and precision of the returned value are determined Definition: ADD finds the sum of two given according to the rules for the values and returns it to the point of conversion of expression operands as invocation. This function allows the given in Section F, "Problem Data programmer to control the precision of the Conversion." result of an add operation. In many of these built-in functions, the Reference: ADD (x,y,[,q]) symbol N is used. "This symbol represents the maximum precision that a value may Arguments: Arguments "x" and "y" represent have. It is defined, for System/360 the values to be added. Arguments "p" and implementations, as follows: "q" must be decimal integer constants specifying the precision of the result; "q" N is 15 for FIXED DECIMAL values may be signed. If the scale of the result is fixed-point, both "p" and "q" must be 16 for FLOAT DECIMAL values specified; if the scale of the result is floating-point, only "p" must be specified. 31 for FIXED BINARY values In either case, "p" must not exceed N. 53 for FLOAT BINARY values Result: The value returned by this function is the sum of "x" and "y." The The precision of decimal and binary precision of the result is determined by floating-point items should be noted when "p" and "q"; this precision is maintained using the built-in functions ADD, BINARY, throughout the execution of the function. DECIMAL, DIVIDE, FLOAT, MULTIPLY, and PRECISION. For decimal floating-point items: if the precision is less than or equal to (6), short floating-point form is BINARY Arithmetic Built-in Function used; if the precision is greater than {6), long floating-point form is used. For binary floating-point items: if the Definition: BINARY converts a given value precision is less than or equal to (21), to binary base and returns the converted Section G: Built-In Functions and Pseudo-Variables 289 value to the point of invocation. This Result: The value returned by this function allows the programmer to control function is the complex number that has the precision of the result of a binary been formed from "x" and "y." conversion. Reference: BINARY (x[,p[,q]]) CONJG Arithmetic Built-in Function Arguments: The first argument, "x," represents the value to be converted to binary base. Arguments "p" and "q," when Definition: CONJG finds the conjugate of a specified, must be decimal integer complex value and returns it to the point constants giving the precision of the of invocation. (The conjugate of a complex binary result; "q" may be signed. The number is the complex number with the sign precision of a fixed-point result is (p,q); of the imaginary part reversed.) the precision of a floating-point result is (p). If both "p" and "q" are omitted, the Reference: CONJG (x) precision of the result is determined according to the rules given for base Argument: The argument, "x," is the value conversion in Section F, "Problem Data whose conjugate is to be found; it must be Conversion." Note that "q" must be omitted complex. for floating-point arguments. Result: The value returned by this Result: The value returned by this function is the conjugate of "x." The function is the binary equivalent of "x." base, scale, mode, and precision of the The scale and mode of this value are the conjugate are the same as those of the same as those of "x." The precision is argument. given by "p" and "q." CEIL Arithmetic Built-in Function DECIMAL Arithmetic Built-in Function Definition: CEIL determines the smallest Definition: DECIMAL converts a given value integer that is greater than or equal to a to decimal base and returns the converted given real value and returns that integer value to the point of invocation. This to the point of invocation. function allows the programmer to control the precision of the result of a decimal Reference: CEIL (x) conversion. Argument: The argument, "x," must not be Reference: DECIMAL (x[,p[,q]]) complex. Arguments: The first argument, "x," Result: The value returned by this represents the value to be converted to function is the smallest integer that is decimal base. Arguments "p" and "q," when greater than or equal to "x." The base, specified, must be decimal integer scale, mode, and precision are the same as constants giving the precision of the those of "x," with one exception: if "x" is decimal result; "q" may be signed. The a fixed-point value of precision (p,q), the precision of a fixed-point result is (p,q); precision of the result is defined as: the precision of a floating-point result is (p). If both "p" and "q" are omitted, (MIN(N,MAX(p-q+1,1)),0) however, the precision of the result is determined according to the rules given for base conversion in Section F, "Problem Data Conversion." Note that "q" must be omitted COMPLEX Arithmetic Built-in Function for floating-point arguments. Result: The value returned by this Definition: COMPLEX forms a complex number function is the decimal equivalent of the from two given real values and returns it argument "x"; its precision is given by "p" to the point of invocation. (COMPLEX can and "q." also be used as a pseudo-variable.) Reference: COMPLEX (x,y) DIVIDE Arithmetic Built-in Function Arguments: Arguments "x" and "y" must both be real; "x" represents the real part of the complex number to be formed and "y" Definition: DIVIDE divides a given value represents the imaginary part. by another given value and returns the 290 quotient to the point of invocation. This Arguments: The first argument, "x," function allows the programmer to control represents the value to be converted to the precision of the result of a divide floating-point scale. The second argument, operation. "p," when specified, must be a decimal integer constant giving the precision of Reference: DIVIDE (x,y,p[,q]) the result. For System/360 implementations, if "p" is omitted, it is Arguments: The argument, "x," is the assumed to be 21 for binary "x" and 6 for dividend and argument "y" is the divisor. decimal "x." Arguments "p" and "q" ("q" is optional and may be signed) must be decimal integer Result: The value returned by this constants specifying the precision of the function is the floating-point equivalent result. If the result is a fixed-point of "x"; its precision is "p." value, "p" and "q" must both be specified; if the result is a floating-point value, only "p" must be specified. In either case, "p" must not exceed N. FLOOR Arithmetic Built-in Function Result: The value returned by this function is the quotient resulting from the Definition: FLOOR determines the largest division of "x" by "y." The precision of integer that does not exceed a given value the result is determined by "p" and "q" as and returns that integer to the point of described above; this precision is invocation. maintained throughout the execution of the function. Reference: FLOOR (x) Argument: The argument, "x," must not be complex. FIXED Arithmetic Built-in Function Result: The value returned by this function is the largest integer that does Definition: FIXED converts a given value not exceed "x." The base, scale, mode, and to fixed-point scale and returns the precision of this value are the same as converted value to the point of invocation. those of "x," with one exception: if "x" is This function allows the programmer to a fixed-point value of precision (p,q), the control the precision of the result of a precision of the result is: fixed-point conversion. (MIN(N,MAX(p-q+1,1)),0) Reference: FIXED (x[,p[,q]]) Argument: The first argument, "x," represents the value to be converted to IMAG Arithmetic Built-in Function fixed-point scale. Arguments "p" and "q," when specified, must be decimal integer constants ("q" can be signed) giving the Definition: IMAG extracts the imaginary precision of the result, (p,q). For part of a given complex number and returns System/360 implementations, if "p" and "q" it to the point of invocation. (IMAG can are omitted, "p" is assumed to be 15 for also be used as a pseudo-variable.) binary "x" and 5 for decimal "x"; "q" is assumed to be 0. Reference: IMAG (x) Result: The value returned by this Argument: The argument, "x," is the function is the fixed-point equivalent of complex value whose imaginary part is to be the argument "x"; its precision is (p,q). extracted. Result: The value returned by this function is the imaginary part of "x." The FLOAT Arithmetic Built-in Function base, scale, and precision of the imaginary part are unchanged. The mode of the returned value is real. Definition: FLOAT converts a given value to floating-point scale and returns the converted value to the point of invocation. This function allows the programmer to MAX Arithmetic Built-in Function control the precision of the result of a floating-point conversion. Definition: MAX extracts the Reference: FLOAT (x[,p]) highest-valued expression from a given set Section G: Built-In Functions and Pseudo-Variables 291 of two or more expressions and returns that Arguments: Two arguments must be given. value to the point of invocation. They must not be complex. Before the function is invoked, the base and scale of Reference: MAX (x1,x2,...,xn) each argument are converted according to the rules for the conversion of expression Arguments: Two or more arguments must be operands, as given in Section F, "Problem given. The arguments must not be complex. Data Conversion." Result: The value returned by MAX is the Result: Division is done ignoring the value of the maximum-valued argument. The signs. If there is no remainder, the value' returned value is converted to conform to returned is zero. the highest characteristics of all the arguments that were specified. If the If there is a remainder, and the signs arguments are fixed-point values and have of the dividend and the divisor are the precisions: same, the value returned is that remainder. (P1,q1), (P2,q2),•... (Pn.qn) If there is a remainder and the signs of the dividend and the divisor are then the precision of the result is as different, the value returned is the follows: difference between the remainder and the divisor ignoring any signs. (MIN(N,MAX(p1-q1,....pn-qn)+ MAX(q1,...,qn)),MAX(q1,...qn)) For example: MOD(29,6) returns the value 5, while MIN Arithmetic Built-in Function MOD(-29,6) returns the value 1. Definition: MIN extracts the lowest-valued If the result is in floating-point scale, expression from a given set of two or more its precision is the higher of the expressions and returns that value to the precisions of the arguments; if the result point of invocation. is in fixed-point scale, its precision is defined as follows: Reference: MIN (x1,x2,...,xn) (MIN(N,p2-q2+MAX(q1,q2)),MAX(q1,q2)) Arguments: Two or more arguments must be given. The arguments must not be complex. where (p1,q1) and (p2 ,q2 ) are the precision of "x1" and "x 2 ," respectively. Result: The value returned by MIN is the value of the lowest-valued argument. The If the value of the second argument is returned value is converted to conform to zero, the ZERODIVIDE condition is raised. the highest characteristics of all the arguments that were specified. If the Note: When the MOD function is used with arguments are fixed-point values and have FIXED arguments of different scale factors, precisions: the results may be truncated. If SIZE is enabled, an error message will be printed; (p1,q1), (p2,q2),...,(pn,qn) if SIZE is disabled, no error message will be printed and the result is undefined. then the precision of the result is as follows: (MIN(N,MAX(p1-q1,....Pn-qn)+ MULTIPLY Arithmetic Built-in Function MAX(q1,...qn)),MAX(q1,...,qn)) Definition: MULTIPLY finds the product of two given values and returns it to the point of invocation. This function allows MOD Arithmetic Built-in Function the programmer to control the precision of the result of a multiplication operation. Definition: MOD extracts the remainder Reference: MULTIPLY (x1,x2,p[,q]) resulting from the division of one real quantity by another and returns it to the Arguments: Arguments•"x1" and "x2" point of invocation. represent the values to be multiplied. Arguments "p" and "q" ("q" is optional and Reference: MOD (x1,x2) may be signed) are decimal integer 292 constants specifying the precision of the ROUND Arithmetic Built-in Function result. If the result is a fixed-point value, "p" and "q" must both be specified; if the result is a floating-point value, Definition: ROUND rounds a given value at only "p" must be specified. In either a specified digit and returns the rounded case, "p" must not exceed N. value to the point of invocation. Reference: ROUND (expression,n) Result: The value returned by this function is the product of "x," and "x2." Arguments: The first argument, The precision of the result is as "expression," is an element or array specified; this precision is maintained representing the value (or values, in the throughout the execution of the function. case of an array expression) to be rounded; the second argument, "n," is a signed or unsigned decimal integer constant specifying the digit at which the value of "expression" is to be rounded. If "n" is PRECISION Arithmetic Built-in Function positive, rounding occurs at the nth digit to the right of the decimal (or binary) point in the value of "expression"; if "n" Definition: PRECISION converts a given is zero, rounding occurs at the first digit value to a specified precision and returns to the left of the decimal (or binary) the converted value to the point of point in the value of "expression"; if "n" invocation. is negative, rounding occurs at the nth+1 digit to the left of the decimal (or binary) point in the value of "expression." Reference: PRECISION (x,p[,q]) Note that the decimal (or binary) point is assumed to be at the left for floating-point values. Arguments: The first argument, "x," represents the value to be converted to the Result: For fixed-point values, ROUND specified precision. Arguments "p" and "q" returns the value of "expression" rounded ("q" is optional and may be signed) are at the nth digit to the right of the decimal integer constants specifying the decimal (or binary) point for positive "n", precision of the result. If "x" is a or at the first digit to the left of the fixed-point value, "p" and "q" must be decimal (or binary) point for zero "n", or specified; if "x" is a floating-point at the nth+1 digit to the left of the value, only "p" must be specified. 'decimal (or binary) point for negative or 'zero "n." Thus, when "n" is negative, the returned value is an integer. Result: The value returned by this function is the value of "x" converted to If "expression" is a floating-point the specified precision. The base, scale, expression, the second argument is ignored, and mode of the returned value are the same and the rightmost bit in the internal as those of "x." floating-point representation of the expression's value is set to 1 if it is 0. If the rightmost bit is 1, it is left unchanged. REAL Arithmetic Built-in Function If "expression" is a string, the returned value is the same string unmodified. Definition: REAL extracts the real part of a given complex value and returns it to the The base, scale, and mode of the point of invocation. (REAL can also be returned value are those of the value of used as a pseudo-variable.) "expression". The precision of the returned value for Reference: REAL (x) floating-point expressions is that of "expression"; the precision of the returned Argument: The argument, "x," must be a value for fixed-point expressions is complex expression. (MIN(p+1,N),q). The extra digit (p+1) of the returned value for fixed-point Result: The value returned by this expressions is to allow for those cases in function is the real part of the complex which rounding would give a result that value represented by "x." The base, scale, could not be expressed in "p" digits, for and precision of the real part are example, ROUND(9.999,2) would result in unchanged. 10.000. Section G: Built-In Functions and Pseudo-Variables 293 Note that the rounding of a negative MATHEMATICAL BUILT-IN FUNCTIONS quantity results in the rounding of the absolute value of that quantity. All arguments to the mathematical built-in functions should be in coded arithmetic form and in floating-point scale. Any argument that does not conform to this rule SIGN Arithmetic Built-in Function is converted to coded arithmetic and floating-point before the function is invoked, according to the rules stated in Definition: SIGN determines whether a Section F, "Problem Data Conversion." value is positive, negative, or zero, and Note, therefore, that in the function it returns an indication to the point of descriptions below, a reference to an invocation. argument always means the converted argument, if conversion was necessary Reference: SIGN (x) In general, an argument to a mathematical built-in function may be an element or array expression. If an Argument: The argument, "x," must not be argument is an array, the value returned by complex. the built-in function is an array of the same dimension and bounds as the argument Result: This function returns a real (the function having been performed once fixed-point binary value of default for each element of the array). Thus, for precision according to the following rules: example, an array to the cosine function COS results in an array, each element of 1. If the argument is greater than 0, the which is the cosine of the corresponding returned value is 1. element in the argument array. 2. If the argument is equal to zero, the Unless it is specifically stated returned value is 0. otherwise, an argument may be real or complex. Figure G-1 at the end of this 3. If the argument is less than zero, the section provide a quick reference for those returned value is -1. mathematical functions that accept either real or complex arguments and those that accept only real arguments. All of the mathematical built-in TRUNC Arithmetic Built-in Function functions return coded arithmetic floating-point values. The mode, base, and precision of these values are always the Definition: TRUNC truncates a given value same as those of the arguments. to an integer as follows: first, it determines whether a given value is positive, negative, or equal to zero. If the value is negative, TRUNC returns the 'smallest integer that is not less than that ATAN Mathematical Built-in Function value; if the value is positive or equal to zero, TRUNC returns the largest integer that does not exceed that value. Definition: ATAN finds the arctangent of a given value and returns the result Reference: TRUNC (x) expressed in radians, to the point of invocation. Argument: The argument, "x," must not be complex. Reference: ATAN (x[,y]) Result: If "x" is less than zero, the Arguments: The argument, "x," must always value returned by TRUNC is CEIL(x). If "x" be specified; the argument "y" is optional. is greater than or equal to zero, the value If "y" is omitted, "x" represents the value returned by TRUNC is FLOOR(x). In either whose arctangent is to be found; in such a case, the base, scale, and mode of the case, "x" may be real or complex, but if it result are the same as those of "x." If is complex, it must not be equal to ±1i. "x" is a floating-point value, the precision remains the same. If "x" is a If "y" is specified, then the value fixed-point value of precision (p,q), the whose arctangent is to be found is taken to precision of the result is: be the expression x/y. In this case, both "x" and "y" must be real, and both cannot (MIN(N,MAX(p-q+1,1)),0) be equal to 0 at the same time. 294 Result: When "x" alone is specified, the If "y" is specified, the value returned value returned by ATAN depends on the mode by this function is ATAN (x,y), except that of "x." If "x" is real, the returned value the value is expressed in degrees and not is the arctangent of "x," expressed in in radians (see "ATAN Mathematical Built-in radians, where: Function" in this section); that is, the returned value is defined as: -pi/2 If "x" is complex, the arctangent function is multiple-valued, and hence only the ATANH Mathematical Built-in Function principal value can be returned. The principal value of ATAN for a complex argument "x" is defined as follows: Definition: ATANH finds the inverse hyperbolic tangent of a given value and -i*ATANH(i*x) returns the result to the point of invocation. If both "x" and "y" are specified, the possible values returned by this function Reference: ATANH (x) are defined as follows: Argument: The value whose inverse 1. If y>0, the value is arctangent (x/y) hyperbolic tangent is to be found is in radians. represented by "x." If "x" is real, the absolute value of "x" must not be greater 2. If x>0 and y=0, the value is (pi/2) than or equal to 1; that is, for real "x," radians. it is an error if ABS(x)>=1. If "x" is complex, it must not be equal to ±1. 3. If x>=0 and y<0, the value is (pi+ arctangent (x/y)) radians. Result: If "x" is real, the value returned by this function is the inverse hyperbolic 4. If x<0 and y=0, the value is (-pi/2) tangent of "x." For complex "x," the radians. inverse hyperbolic tangent is defined as follows: 5. If x<0 and y<0, the value is (-pi+ arctangent (x/y)) radians. (LOG((1+x)/(1-x)))/2 COS Mathematical Built-in Function ATAND Mathematical Built-in Function Definition: COS finds the cosine of a Definition: ATAND finds the arctangent of given value, which is expressed in radians, a given real value and returns the result, and returns the result to the point of expressed in degrees, to the point of invocation. invocation. Reference: COS (x) Reference: ATAND (x[,y]]) Argument: The value whose cosine is to be found is given by "x"; this value can be real or complex and must be expressed in Arguments: Arguments "x" and "y" ("y" may radians. be omitted) must be real values. If "y" is omitted, "x" represents the value whose Result: The value returned by this arctangent is to be found. If "y" is function is the cosine of "x." For complex specified, the value whose arctangent is to argument "x," the cosine of "x" is defined be found is represented by the expression below, where x = y1+iy2: x/y; in this case, both "x" and "y" cannot be equal to 0 at the same time. cos(x)=cos(y1)*cosh(y2)-i*sin(y1)*sinh(y2) Result: If "y" is not specified, the value returned by this function is simply the COSD Mathematical Built-in Function arctangent of "x," expressed in degrees, where: Definition: COSD finds the cosine of a -90 Section G: Built-In Functions and Pseudo-Variables 295 degrees, and returns the result to the the value whose error function complement point of invocation. is to be found; "x" must be real. Reference: COSD (x) Result: The value returned by this function is defined as follows: Argument: The value whose cosine is to be found is given by "; this value must be ERFC(x) = 1-ERF(x) real and must be expressed in degrees. Result: The value returned by this EXP Mathematical Built-in Function function is the cosine of "x." Definition: EXP raises e (the base of the natural logarithm system) to a given power and returns the result to the point of COSH Mathematical Built-in Function invocation. Reference: EXP (x) Definition: COSH finds the hyperbolic cosine of a given value and returns the Argument: The argument, "x," specifies the result to the point of invocation. power to which e is to be raised. Reference: COSH (x) Result: The value returned by this function is e raised to the power of x." Argument: The value whose hyperbolic cosine is to be found is given by "x." Result: The value returned by this LOG Mathematical Built-in Function function is the hyperbolic cosine of x." For complex argument "x," the hyperbolic cosine of "x" is defined below, where x = Definition: LOG finds the natural logarithm (i.e., base e) of a given value and returns it to the point of invocation. Reference: LOG (x) Argument: The argument, "x," is the value ERF Mathematical Built-in Function whose natural logarithm is to be found. If "x" is real, it must not be less than or equal to 0; if "x" is complex, it must not Definition: ERF finds the error function be equal to 0+0i. of a given real value and returns it to the point of invocation. Result: The value returned by this function is the natural logarithm of "x." Reference: ERF (x) However, if "x" is complex, the function is multiple-valued; hence, only the principal Argument: The value for which the error value can be returned. The principal value function is to be found is represented by has the form w = u±i*v, where v lies in the "x"; this value must be real. range: Result: The value returned by this -pi LOG10 Mathematical Built-in Function ERFC Mathematical Built-in Function Definition: LOG10 finds the common logarithm (i.e., base 10) of a given real value and returns it to the point of Definition: ERFC finds the complement of invocation. the error function (ERF) for a given real value and returns the result to the point Reference: LOG10 (x) of invocation. Argument: The argument, x," represents Reference: ERFC (x) the value whose common logarithm is to be found; this value must be real and it must Argument: The argument, x," represents not be less than or equal to 0. 296 Result: The value returned by this SINH Mathematical Built-in Function function is the common logarithm of "x." Definition: SINH finds the hyperbolic sine of a given value and returns the result to the point of invocation. LOG2 Mathematical Built-in Function Reference: SINH (x) Definition: LOG2 finds the binary (i.e., base 2) logarithm of a given real value and returns it to the point of invocation. Argument: The argument, x," is the value whose hyperbolic sine is to be found. Reference: LOG2 (x) Result: The value returned by this function is the hyperbolic sine of "x." Argument: The argument, x," is the value For complex argument x," the hyperbolic whose binary logarithm is to be found; it sine of "x" is defined below, where x = must be real and it must not be less than or equal to 0. Result: The value returned to this function is the binary logarithm of "x." SQRT Mathematical Built-in Function SIN Mathematical Built-in Function Definition: SQRT finds the square root of a given value and returns it to the point of invocation. Definition: SIN finds the sine of a given value, which is expressed in radians, and returns it to the point of invocation. Reference: SQRT (x) Reference: SIN (x) Argument: The argument, x," is the value Argument: The argument, x," is the value whose square root is to be found. If x" whose sine is to be found; it must be is real, it must not be less than 0. expressed in radians. Result: If "x" is real, the value returned Result: The value returned by this by this function is the positive square function is the sine of "x." For complex root of "x." If x" is complex, the square argument "x," the sine of x" is defined root function is multiple-valued; hence, below, where x = y1+i*y2: only the principal value can be returned to the user. The principal value has the form w = u±i*v, where either u>0, or u=0 and v>=0. SIND Mathematical Built-in Function TAN Mathematical Built-in Function Definition: SIND finds the sine of a given real value, which is expressed in degrees, Definition: TAN finds the tangent of a and returns the result to the point of given value, which is expressed in radians, invocation. and returns it to the point of invocation. Reference: SIND (x) Reference: TAN (x) Argument: The argument, x," is the value Argument: The argument, x," represents whose sine is to be found; "x" must be real the value whose tangent is to be found; x" and it must be expressed in degrees. must be expressed in radians. Result: The value returned by this Result: The value returned by this function is the sine of "x." function is the tangent of "x." Section G: Built-In Functions and Pseudo-Variables 297 TAND Mathematical Built-in Functions 1. A complex argument, "x," is defined as x = y1+i*y2. Definition: TAND finds the tangent of a given real value which is expressed in degrees, and returns the result to the 2. The value returned by each function is point of invocation. always in floating-point. Reference: TAND (x) Argument: The argument, x," represents 3. The error conditions are those defined the value whose tangent is to be found; "x" by the PL/I Language. Additional must be expressed in degrees. error conditions detected by the F-Compiler are described in the Result: The value returned by this publication IBM System/360 Operating function is the tangent of x." System, PL/I Subroutine Library, Computational Subroutines, Form C28-6590. TANH Mathematical Built-in Function 4. All arguments must be coded arithmetic and floating-point scale, or such that Definition: TANH finds the hyperbolic they can be converted to coded tangent of a given value and returns the arithmetic and floating-point. result to the point of invocation. Reference: TANH (x) Argument: The argument, x," represents the value whose hyperbolic tangent is to be found. Result: The value returned by this ARRAY MANIPULATION BUILT-IN FUNCTIONS function is the hyperbolic tangent of "x." The built-in functions described here may be used for the manipulation of arrays. Summary of Mathematical Functions All of these functions require array arguments (which may be expressions) and return single element values. Note that Figure G-1 summarizes the mathematical since these functions return element built-in functions. In using it, the values, a function reference to any of them reader should be aware of the following: is considered an element expression. 298 Figure G-1. Mathematical Built-In Functions Section G: Built-In Functions and Pseudo-Variables 299 Figure G-1. Mathematical Built-In Functions (continued) ALL Array Manipulation Function Argument: The argument, "x," is an array of bit strings. If the elements are not bit strings, they are converted to bit Definition: ALL tests all bits of a given strings. bit-string array and returns the result, in the form of an element bit-string, to the point of invocation. The element bit-string indicates whether or not the Result: The value returned by this corresponding bits of given array elements function is a bit string whose length is are all ones. equal to the length of the longest element in "x" and whose bit values are determined Reference: ALL (x) by the following rule: 300 If the ith bits of all of the elements HBOUND Array Manipulation Function in "x" exist and are 1, then the ith bit of the result is 1; otherwise, the ith bit of the result is 0. Definition: HBOUND finds the current upper bound for a specified dimension of a given array and returns it to the point of invocation. ANY Array Manipulation Function Reference: HBOUND (x,n) Arguments: The argument "x" is the array Definition: ANY tests the bits of a given to be investigated; "n" is the dimension of bit-string array and returns the result, in "x" for which the upper bound is to be the form of an element bit-string, to the found. If "n" is not a binary integer, it point of invocation. The element bit- is converted to a binary integer of default string indicates whether or not at least precision. It is an error if "x" has less one of the corresponding bits of the given than "n" dimensions, if "n" is less than or array elements is set to 1. equal to 0, or if "x" is not currently allocated. Reference: ANY (x) Result: The value returned by this function is a binary integer of default precision giving the current upper bound Argument: The argument, "x," is an array for the nth dimension of "x." of nit strings. If the elements are not bit strings, they are converted to bit strings. LBOUND Array Manipulation Function Result: The value returned by this function is a bit string whose length is equal to the length of the longest element Definition: LBOUND finds the current lower in "x" and whose bit values are determined bound for a specified dimension of a given by the following rule: array and returns it to the point of invocation. If the ith bit of any element in "x" exists and is 1, then the ith bit of the Reference: LBOUND (x,n) result is 1; otherwise, the ith bit of the result is 0. Arguments: The argument "x" is the array to be investigated; "n" is the dimension of "x" for which the lower bound is to be found. If "n" is not a binary integer, it is converted to a binary integer of default DIM Array Manipulation Function precision. It is an error if "x" has less than "n" dimensions, if "n" is less than or equal to 0, or if "x" is not currently Definition: DIM finds the current extent allocated. for a specified dimension of a given array and returns it to the point of invocation. Result: The value returned by this function is a binary integer of default precision giving the current lower bound of Reference: DIM (x,n) the nth dimension of "x." Arguments: The argument "x" is the array to be investigated; "n" is the dimension of POLY Array Manipulation Function "x," the extent of which is to be found. If "n" is not a binary integer, it is converted to a binary integer of default Definition: POLY forms a polynomial from precision. It is an error if "x" has less two given arguments and returns the result than "n" dimensions, if "n" is less than or of the evaluation of that polynomial to the equal to 0, or if "x" is not currently point of invocation. allocated. Reference: POLY (a,x) Result: The value returned by this function is a binary integer of default Arguments: Arguments "a" and "x" must be precision, giving the current extent of the one-dimension arrays (vectors). They are nth dimension of "x." defined as follows: Section G: Built-In Functions and Pseudo-Variables 301 a(m:n) Result: The value returned by this function is the sum of all of the elements x(p:q) in "x." The scale of the result is floating-point, while the base, mode, and where (m:n) and (p:q) represent the bounds precision are those of the converted of "a" and "x," respectively. elements of the argument. Result: The value returned by this function is defined as: Condition Built-In Functions The condition built-in functions allow the PL/I programmer to investigate interrupts If (q-p)<(n-m-1), then x(p+i)=x(q) for that arise from enabled ON-conditions. (p+i)>q. If m=n, then the result is a(m). None of these functions requires arguments. Each condition built-in function returns If "x" is an element variable, it is the value described only when executed in interpreted as an array of one element, an on-unit (or a block activated directly i.e., x(1), and the result is then: or indirectly by an on-unit) that is entered as a result of an interrupt caused by one of the ON-conditions for which the function can be used. Such an on-unit can be one specific to the condition, or it can be for the ERROR or FINISH condition when these conditions are raised as standard system action. If a condition built-in PROD Array Manipulation Function function is used out of context, the value returned is as described for each function. Definition: PROD finds the product of all The on-units in which each function can of the elements of a given array and be used are given in the function returns that product to the point of definition. invocation. Reference: PROD (x) DATAFIELD Condition Built-in Function Argument: The argument, "x," should be an array of coded arithmetic floating-point elements. If it is not, each element is Definition: Whenever the NAME condition is converted to coded arithmetic and raised, DATAFIELD may be used to extract floating-point before being multiplied with the contents of the data field that caused the previous product. the condition to be raised. It can be used only in an on-unit for the NAME condition Result: The value returned by this or in an ERROR or FINISH condition raised function is the product of all of the as a result of standard system action for elements in "x." The scale of the result the NAME condition. is floating-point, while the base, mode, and precision are those of the converted Reference: DATAFIELD elements of "x." Result: The value returned by this function is a varying-length character string giving the contents of the data SUM Array Manipulation Function field that caused the NAME condition to be raised. The maximum length of this string is defined by the F Compiler as 255. If Definition: SUM finds the sum of all of DATAFIELD is used out of context, a null the elements of a given array and returns string is returned. that sum to the point of invocation. Reference: SUM (x) ONCHAR Condition Built-in Function Argument: The argument, "x," should be an array of coded arithmetic floating-point elements. If it is not, each element is Definition: Whenever the CONVERSION converted to coded arithmetic and condition is raised, ONCHAR may be used to floating-point before being summed with the extract the character that caused the previous total. condition to be raised. It can be used 302 only in an on-unit for the CONVERSION ONFILE Condition Built-in Function condition or in an on-unit for an ERROR or FINISH condition raised as standard system action for the CONVERSION condition. Definition: ONFILE determines the name of (ONCHAR can also be used as a the file for which an input/output or pseudo-variable.) CONVERSION condition was raised and returns that name to the point of invocation. This function can be used in the on-unit for any Reference: ONCHAR input/output or CONVERSION condition; it also can be used in an on-unit for an ERROR or FINISH condition raised as standard Result: The value returned by this system action for an input/output or function is a character string of length 1, CONVERSION condition. containing the character that caused the CONVERSION condition to be raised. This Reference: ONFILE character can be modified in the on-unit by the use of the ONCHAR or ONSOURCE Result: The value returned by this pseudo-variables. If ONCHAR is used out of function is a varying-length character context, a blank is returned. string, of 31-character maximum length, consisting of the name of the file for which an input/output or CONVERSION condition was raised. In the case of a CONVERSION condition, if that condition is ONCODE Condition Built-in Function not associated with a file, the returned value is the null string. Definition: ONCODE can be used in any on-unit to determine the type of interrupt that caused the on-unit to become active. ONKEY Condition Built-in Function Reference: ONCODE Result: ONCODE returns a binary integer of Definition: ONKEY extracts the value of default precision. This "code" defines the the key for the record that caused an type of interrupt that caused the entry input/output condition to be raised. This into the currently active on-unit. The function can be used in the on-unit for an codes for the F Compiler are given in input/output condition or a CONVERSION section H, "ON-Conditions." If ONCODE is condition; it can also be used in an used out of context, a value of 0 is on-unit for an ERROR or FINISH condition returned. raised as standard system action for one of the above conditions. Reference: ONKEY ONCOUNT Condition Built-In Function Result: The value returned by this function is a varying-length character string giving the value of the key for the Definition: ONCOUNT can be used in any record that caused an input/output on-unit entered due to the abnormal condition to be raised., If the interrupt completion of an input/output event to is not associated with a keyed record, the determine the number of interrupts returned value is the null string. For the (including the current one) that remain to F Compiler, the returned value is a null be handled when a multiple interrupt has string in the case of the PENDING resulted from that abnormal completion. condition. (Multiple interrupts are discussed in Section H, "ON- Conditions.") ONLOC Condition Built-in Function Reference: ONCOUNT Result: ONCOUNT returns a binary value of Definition: Whenever an ON-condition is default precision. If ONCOUNT is used in raised, ONLOC may be used in the on-unit an on-unit entered as part of a multiple for that condition to determine the entry interrupt, this value specifies the point to the procedure in which that corresponding number of equivalent single condition was raised. ONLOC may be used in interrupts (including the current one) that any on-unit. remain to be handled; if ONCOUNT is used in any other case, the returned value is zero. Reference: ONLOC Section G: Built-In Functions and Pseudo-Variables 303 Result: The value returned by this bit-string variable forming part of an function is a varying-length character unaligned array or structure. string giving the name of the entry point to the procedure in which the ON-condition Result: ADDR returns a pointer value was raised. If ONLOC is used out of identifying the location at which "x" has context, a null string is returned. been allocated. If "x" is a parameter, the returned value identifies the corresponding argument (dummy or otherwise). If "x" is a based variable, the returned value is ONSOURCE Condition Built-in Function determined from the pointer variable declared with "x"; if this pointer variable has not been set, the value returned by Definition: Whenever the CONVERSION ADDR is undefined. If "x" is an condition is raised, ONSOURCE may be used unallocated controlled variable, a null to extract the contents of the field that pointer value is returned. was being processed when the condition was raised. This function can be used in the on-unit for a CONVERSION condition or in an on-unit for an ERROR or FINISH condition EMPTY Based Storage Built-in Function raised as standard system action for a CONVERSION condition. (ONSOURCE can also be used as a pseudo-variable.) Definition: EMPTY clears an area of storage defined by an area variable, by Reference: ONSOURCE effectively freeing all the allocations contained within the area. The area can Result: The value returned by this then be used for a new set of allocations. function is a varying-length character string (maximum length is 255 for the F Reference: EMPTY Compiler) giving the contents of the field being processed when CONVERSION was raised. Arguments: None This string may be modified in the on-unit by use of the ONCHAR or ONSOURCE Result: EMPTY returns an area of zero pseudo-variable. If ONSOURCE is used out size, containing no allocations, to the of context, a null string is returned. point of invocation. When this value is assigned to an area variable, all the allocations contained within the area are freed. Based Storage Built-In Functions Note: The value of the EMPTY built-in function is automatically assigned to all The based storage built-in functions area variables when they are allocated. generally return special values to program control variables concerned in the use of based storage and list processing. Only ADDR requires an argument. NULL Based Storage Built-in Function Definition: NULL returns a null pointer ADDR Based Storage Built-in Function value (that is, a pointer value that cannot identify any allocation) so as to indicate that a pointer variable does not currently Definition: ADDR finds the location at identify an allocation. which a given variable has been allocated and returns a pointer value to the point of Reference: NULL invocation. The pointer value identifies the location at which the variable has been Arguments: None allocated. Result: The value returned by this Reference: ADDR (x) function is a null pointer value. This value cannot be converted to offset type. Argument: The argument, "x," is the variable whose location is to be found. It can be any variable that represents an element, an array, a structure, an area, an NULLO Based Storage Built-in Function element of an array, a minor structure, or an element of a structure. It can be of any data type and storage class. For the F Definition: NULLO returns a null offset Compiler, the variable should not be a value (that is, an offset value that cannot 304 identify any relative location of a based Result: The value returned by this task is variable allocation) so as to indicate that a fixed binary value of precision (n,0), an offset variable does not currently where n is implementation-defined (15, for identify an allocation. the F Compiler). The value is the priority value of the named task, relative to the Reference: NULLO priority of the task evaluating the function. No interrupt can occur during Arguments: None evaluation of PRIORITY. Result: The value returned by this function is a null offset value. This value cannot be converted to pointer type. STATUS Multitasking Built-in Function Multitasking Built-In Functions Definition: STATUS determines the status value of a given event variable. (STATUS can also be used as a pseudo-variable.) The multitasking built-in functions are used during multitasking and during Reference: STATUS (event-name) asynchronous input/output operations. They allow the programmer to investigate the Argument: The argument, "event-name", can relative priority of a task or the current be an event element or an event array. It state of execution of a task or represents the event (or events) whose asynchronous input/output operation. They status value is to be determined. The all require arguments. event can be associated with completion of a task, or with completion of an input/output operation, or it can be user-defined. It can be active or COMPLETION Multitasking Built-in Function inactive. An array argument causes an array value to be returned. Definition: COMPLETION determines the Result: The value returned by this completion value of a given event variable. function is a fixed binary value of default (COMPLETION can also be used as a precision ((15,0) for the F Compiler). It pseudo-variable.) is zero if the event is normal, or nonzero if abnormal. The nonzero value is set to 1 Reference: COMPLETION (event-name) as a result of the completion of the task, or input/output operation, with which the Argument: The argument, "event-name", can event variable has been associated by the be an event element or an event array. It event option. If the nonzero value is user represents the event (or events) whose defined it can be set to any value the use completion value is to be determined. The selects. event can be associated with completion of a task, or with completion of an input/output operation, or it can be user-defined. It can be active or inactive. An array argument causes an Miscellaneous Built-In Functions array value to be returned. Result: The value returned by this The functions described in this section function is '0'B if the event is have little in common with each other and incomplete, '1'B if the event is complete. with the other categories of built-in functions. some require arguments and others do not. Those that do not require arguments will be so identified. PRIORITY Multitasking Built-in Function Definition: PRIORITY determines the ALLOCATION Built-in Function relative priority of a given task. (PRIORITY can also be used as a pseudo-variable.) Definition: ALLOCATION determines whether or not storage is allocated for a given Reference: PRIORITY (task-name) controlled variable and returns an appropriate indication to the point of Argument: The argument, "task-name," invocation. represents the task whose relative priority is to be determined. Reference: ALLOCATION (x) Section G: Built-In Functions and Pseudo-Variables 305 Argument: The argument, "x," must be an X = DATE; unsubscripted array name, a major structure name, or an element variable name, and it will cause the character string '680229' to must have the CONTROLLED attribute. be returned to the point of invocation. Result: The value returned by this function is defined as follows: if storage has been allocated for "x," the returned LINENO Built-in Function value is '1'B (provided that the allocation is known to the task executing the function); if storage has not been Definition: LINENO finds the current line allocated for "x," the returned value is number for a file having the PRINT '0'B. attribute and returns that number to the point of invocation. Reference: LINENO (file-name) COUNT Built-in Function Argument: The argument, "file name," must be the name of a file having the PRINT Definition: COUNT determines the number of attribute. data items that were transmitted during the last GET or PUT operation on a given file Result: The value returned by this and returns the result to the point of function is a binary fixed-point integer of invocation. default precision specifying the current line number of "file name." Reference: COUNT (file-name) Argument: The argument, "file name," represents the file to be investigated. TIME Built-in Function This file must have the STREAM attribute. Result: The value returned by this Definition: TIME returns the current time function is a binary fixed-point integer of to the point of invocation. default precision specifying the number of element data items that were transmitted Reference: TIME during the last GET or PUT operation on "file name." Note that if an on-unit or Arguments: None procedure is entered during a GET or PUT operation, and within that on-unit or Result: The value returned by this procedure a GET or PUT is executed for the function is a character string of length same file, the value of COUNT is reset for nine, in the form hhmmssttt, where: the new operation and is not restored when the original GET or PUT is continued. hh is the current hour of the day mm is the number of minutes DATE Built-in Function ss is the number of seconds ttt is the number of milliseconds in Definition: DATE returns the current date machine-dependent increments to the point of invocation. Example: If the current time is 4 P.M., 23 Reference: DATE minutes, 19 seconds, and 80 milliseconds, a reference to the TIME function, for some Arguments: None computers, will return the character string '162319080' to the point of invocation. Result: The value returned by this function is a character string of length six, in the form yymmdd, where: Pseudo-Variables yy is the current year mm is the current month In general, pseudo-variables are certain built-in functions that can appear wherever dd is the current day other variables can appear in order to receive values. In short, they are Example: If the current date is February built-in functions used as receiving 29, 1968, execution of the statement fields. For example, a pseudo-variable may 306 appear on the left of the equal sign in an ONCHAR Pseudo-variable assignment or DO statement; it may appear in the data list of a GET statement; it may appear as the string name in the STRING Reference: ONCHAR option of a PUT statement. Description: ONCHAR can be used in the Since all pseudo-variables have built-in on-unit for a CONVERSION condition or in function counterparts, only a short the on-unit for an ERROR or FINISH description of each pseudo-variable is condition raised as standard system action given here; the discussion of the for a CONVERSION condition; it can also be corresponding built-in function should be used in a block directly or indirectly consulted for the details. Note that activated by such an on-unit. If ONCHAR is pseudo-variables cannot be nested; for used in some other context, it is an error. example, the following statement is invalid: The expression being assigned to ONCHAR is evaluated, converted to a character UNSPEC(SUBSTR(A,1,2))='00'B; string of length 1, and assigned to the character that caused the error. The new character will displace the current value of the ONCHAR built-in function, and will be used when the conversion is COMPLETION Pseudo-variable re-attempted, upon the resumption of execution at the point of interrupt. Reference: COMPLETION (event-name) Description: The named event variable must ONSOURCE Pseudo-variable be inactive and is as described for the COMPLETION built-in function. The value received by this pseudo-variable is a Reference: ONSOURCE bit-string of length 1. This value sets the completion value of the event variable. Description: ONSOURCE can be used in the A value of '0'B specifies that the event on-unit for a CONVERSION condition or in an associated with the "event variable" is on-unit for an ERROR or FINISH condition incomplete; a value of '1'B specifies that raised as standard system action for a the event is complete. No interrupt can CONVERSION condition; it can also be used take place during assignment to the in a block directly or indirectly activated pseudo-variable. by such an on-unit. If ONSOURCE is used in some other context, it is an error. The expression being assigned to ONSOURCE is evaluated, converted to a COMPLEX Pseudo-variable character string, and assigned to the string that caused the CONVERSION condition to be raised. The string will be padded Reference: COMPLEX (a,b) with blanks, if necessary, to match the length of the string that caused the error. Description: Only complex values can be This new string displaces the current value assigned to this pseudo-variable. The real of the ONSOURCE built-in function and will part of the complex value is assigned to be used when the conversion is the variable "a"; the imaginary part is re-attempted, upon the resumption of assigned to the variable "b." If either execution at the point of interrupt. "a" and "b" is an array, both must be arrays of identical bounds. PRIORITY Pseudo-variable IMAG Pseudo-variable Reference: PRIORITY [(task-name)] Reference: IMAG (c) Description: The "task-name" is as described for the PRIORITY built-in Description: Real or complex values may be function, but need not be specified. The assigned to this pseudo-variable. The real value received by this pseudo-variable is a value or the real part of the complex value fixed-point binary value of precision is assigned to the imaginary part of the (n,0), where n is implementation-defined complex variable "c," which may be an (15, for the F Compiler). The priority element variable or an array variable. value of the named task variable is Section G: Built-In Functions and Pseudo-Variables 307 adjusted so that it becomes n relative to The value being assigned must be an the priority that the current task had element expression and is converted, if prior to the assignment. If an active task necessary, to bit-string or is associated with the named task variable, character-string type, depending on the its priority is given the same value as the characteristics of the argument "x." It is task variable. then assigned piece by piece to the elements of "x," using the normal rules of If "task-name" is not specified, the string assignment, until either all of the task variable associated with the current elements of the aggregate have been task (if there is such a variable) is assigned to, or no portion of the assigned implied, and the priority of this variable string remains. In the latter case, the is modified; hence, the priority of the normal string assignment rules apply to the current task is modified. remainder of the aggregate, i.e., varying strings are given a zero length, and No interrupt can occur during assignment non-varying strings are filled with blanks. to the PRIORITY pseudo-variable. (The length of each assigned piece is determined by the length of the corresponding element of the argument; the normal rules for string assignment apply if the last piece is too short.) REAL Pseudo-variable STRING pseudo-variable can only be used in an assignment statement and a DO Reference: REAL (c) statement. It cannot be used in options such as REPLY and KEYTO. Description: Real or complex values may be assigned to this pseudo-variable. The real value or the real part of the complex value is assigned to the real part of the complex SUBSTR Pseudo-variable variable "c," which may be an element variable or an array variable. Reference: SUBSTR (string,i[,j]) Description: The value being assigned to STATUS Pseudo-variable SUBSTR is assigned to the substring of the character- or bit-string variable "string," as defined for the built-in function Reference: STATUS (event-name) SUBSTR. If "string" is an array, i and/or j may be arrays, in which case they must Description: The named event variable can have identical bounds. The remainder of be active or inactive, and is as described "string" remains unchanged. The SUBSTR for the STATUS built-in function. The pseudo-variable cannot be applied to a value received by this pseudo-variable is a numeric picture. fixed point binary value of default precision ((15,0) for the F Compiler). No interrupt can occur during assignment to the pseudo-variable. UNSPEC Pseudo-variable Reference: UNSPEC (v) STRING Pseudo-variable Description: The letter "v" represents an Reference: STRING(x) 'element or array variable of arithmetic, string, area, pointer, or offset type. The Description: The argument "x" is an value being assigned to UNSPEC is element, array, or structure variable, evaluated, converted to a bit string (the composed either entirely of character length of which is a function of the strings and/or numeric character data, or characteristics of "v" -- see the UNSPEC entirely of bit strings. The variable may built-in function), and then assigned to be aligned or unaligned. "v," without conversion to the type of "v." If "v" is a string of varying length, its Note: The argument to STRING length after the assignment will be the pseudo-variable cannot be a cross section same as that of the bit string assigned to of an array for the F Compiler. it. 308 Section H: ON-Conditions Introduction NOCONVERSION NOFIXEDOVERFLOW The ON-conditions are those exceptional conditions that can be specified in PL/I by NOOVERFLOW means of an ON statement. If a condition is enabled, the occurrence of the condition NOUNDERFLOW will result in an interrupt. The interrupt, in turn, will result in the NOZERODIVIDE execution of the current action specification for that condition. If an ON statement for that condition is not in Such a condition prefix renders the effect, the current action specification is corresponding condition disabled throughout the standard system action for that the scope of the prefix; the condition condition. If an ON statement for that remains enabled outside this scope. (Scope condition is in effect, the current action of a condition prefix is discussed in Part specification is either SYSTEM, in which I, Chapter 13, "Exceptional Condition case the standard system action for that Handling and Program Checkout.") condition is taken, or an on-unit, in which case the programmer has supplied his own Conversely, those conditions that are action to be taken for that condition. always disabled unless they have been enabled by a condition prefix are: SIZE If a condition is not enabled (i.e., if it is disabled), and the condition occurs, SUBSCRIPTRANGE an interrupt will not take place, and errors may result. STRINGRANGE CHECK Some conditions are always enabled unless they have been explicitly disabled The appearance of one of these four in a by condition prefixes; others are always condition prefix renders the condition disabled unless they have been explicitly enabled throughout the scope of the prefix; enabled by condition prefixes; and still the condition remains disabled outside this others are always enabled and cannot be scope. Further, a condition prefix speci- disabled. fying NOSIZE, NOSUBSCRIPTRANGE, NOSTRING- RANGE, or NOCHECK will disable the corresponding condition throughout the Those conditions that are always enabled scope of that prefix. unless they have been explicitly disabled by condition prefixes are: All other conditions are always enabled and remain so for the duration of the program. These conditions are: CONVERSION AREA FIXEDOVERFLOW CONDITION OVERFLOW ENDFILE UNDERFLOW ENDPAGE ZERODIVIDE ERROR FINISH Each of the above conditions can be disabled by a condition prefix specifying KEY the condition name preceded by NO without intervening blanks. Thus, one of the NAME following names in a condition prefix will disable the respective condition: PENDING Section H: ON-Conditions 309 RECORD 341 SIZE (I/O) 350 STRINGRANGE TRANSMIT 360 AREA (raised by based variable allocation) UNDEFINEDFILE 361 AREA (raised by area assignment) 362 AREA (signaled) 500 CONDITION 510 CHECK (LABEL) Condition Codes (ON-Codes) 511 CHECK (variable) 520 SUBSCRIPTRANGE 600 CONVERSION (internal) (signaled) The ONCODE built-in function may be used by 601 CONVERSION (I/O) the programmer in any on-unit to determine 602 CONVERSION (transmit) the nature of the error or condition that 603 CONVERSION (error in F-format input) caused entry into that on-unit. The codes 604 CONVERSION (error in F-format input) corresponding to the conditions and errors (I/O) checked for by the F Compiler are given 605 CONVERSION (error in F-format input) below: (transmit) 606 CONVERSION (error in E-format input) 607 CONVERSION (error in E-format input) Code Condition/Error (I/O) 608 CONVERSION (error in E-format input) (transmit) 0 ONCODE function used out of context 609 CONVERSION (error in B-format input) 3 Source program error 610 CONVERSION (error in B-format input) 4 FINISH (normal termination, or (I/O) signaled by STOP or EXIT) 611 CONVERSION (error in B-format input) 9 ERROR (signaled) (transmit) 10 NAME 612 CONVERSION (character-string to 20 RECORD (signaled) arithmetic) 21 RECORD (record variable smaller than 613 CONVERSION (character-string to record size) arithmetic) (I/O) 22 RECORD (record variable larger than 614 CONVERSION (character-string to record size) arithmetic) (transmit) 23 RECORD (attempt to write zero length 615 CONVERSION (character-string to record) bit-string) 24 RECORD (zero length record has been 616 CONVERSION (character-string to read) bit-string) (I/O) 40 TRANSMIT (signaled) 617 CONVERSION (character-string to 41 TRANSMIT (output) bit-string) (transmit) 42 TRANSMIT (input) 618 CONVERSION (character to picture) 50 KEY (signaled) 619 CONVERSION (character to picture) 51 KEY (keyed record not found) (I/O) 52 KEY (attempt to add duplicate key) 620 CONVERSION (character to picture) 53 KEY (key sequence error) (transmit) 54 KEY (key conversion error) 621 CONVERSION (P-format input -- 55 KEY (key specification error) decimal) 56 KEY (keyed relative record/track 622 CONVERSION (P-format input -- outside data set limit) decimal) (I/O) 57 KEY (no space available to add keyed 623 CONVERSION (P-format input -- record) decimal) (transmit) 70 ENDFILE 624 CONVERSION (P-format input -- 80 UNDEFINEDFILE (signaled) character) 81 UNDEFINEDFILE (attribute conflict) 625 CONVERSION (P-format input -- 82 UNDEFINEDFILE (access method not character) (I/O) supported) 626 CONVERSION (P-format input -- 83 UNDEFINEDFILE (blocksize not character) (transmit) specified) 627 CONVERSION (P-format input -- 84 UNDEFINEDFILE (file cannot be sterling) opened, no DD card) 628 CONVERSION (P-format input -- 85 UNDEFINEDFILE (error initializing sterling) (I/O) REGIONAL data set) 629 CONVERSION (P-format input -- 90 ENDPAGE sterling) (transmit) 300 OVERFLOW 1000 Attempt to read output file 310 FIXEDOVERFLOW 1001 Attempt to write input file 320 ZERODIVIDE 1002 GET/PUT string length error 330 UNDERFLOW 1003 Unacceptable output transmission 340 SIZE (normal) error 310 1004 Print option on non-PRINT file 3004 A-format input error 1005 Message length for DISPLAY 3005 B-format input error statements is zero 3006 Picture character-string error 1006 Illegal array data item for 3798 ONSOURCE or ONCHAR pseudo-variables data-directed input used out of context 1007 REWRITE not immediately preceded by 3799 Improper return from CONVERSION READ on-unit 1008 GET STRING -- unrecognizable data 3800 Structure length >= 16**6 bytes name 3801 Virtual origin of array >= 16**6 or 1009 Unsupported file operation <=16**6 1010 File type not supported 3900 Attempt to wait on inactive and 1011 Inexplicable I/O error incomplete event 1012 Outstanding read for update exists 3901 Task variable already active 1013 No completed read exists -- 3902 Event already being waited for incorrect NCP value 3903 Wait on more than 255 incomplete 1014 Too many incomplete I/O operations events 1015 Event variable already in use 3904 Active event variable as argument to 1016 Implicit open failures -- cannot COMPLETION pseudo-variable proceed 3905 Invalid task variable as argument to 1017 Attempt to rewrite out of sequence PRIORITY pseudo-variable 1018 ERROR condition raised when end of 3906 Event variable active in assignment file encountered unexpectedly in statement list-directed or data-directed 3907 Event variable already active input, or when field width in format 3908 Attempt to wait for I/O event in list of edit-directed input would wrong task take scan beyond end of file. 8091 Invalid operation 11019 Attempt to close file not opened in 8092 Privileged operation current task 8093 EXECUTE statement executed 1500 Short SQRT error 8094 Protection violation 1501 Long SQRT error 8095 Addressing interruption 1504 Short LOG error 8096 Specification interruption 1505 Long LOG error 8097 Data interruption 1506 Short SIN error 9000 Too many active on-units and entry 1507 Long SIN error parameter procedures 1508 Short TAN error 9001 No invocation count 1509 Long TAN error 9002 Invalid free storage (main 1510 Short ARCTAN error procedure) 1511 Long ARCTAN error 9003 Invalid free VDA 1512 Short SINH error 1513 Long SINH error 1514 Short ARCTANH error 1515 Long ARCTANH error Multiple Interrupts 1550 Invalid exponent in short float integer exponentiation 1551 Invalid exponent in long float A multiple interrupt can occur only for an integer exponentiation input/output operation that has been 1552 Invalid exponent in short float associated with an event variable. It general exponentiation occurs during the execution of the WAIT 1553 Invalid exponent in long float statement naming that event variable, if general exponentiation the event has been completed abnormally 1554 Invalid exponent in complex short (i.e., if one or more conditions occurred float integer exponentiation during the operation). Since conditions 1555 Invalid exponent in complex long for an input/output event are raised at the float integer exponentiation execution of the WAIT for that event, the 1556 Invalid exponent in complex short interrupts for these conditions also occur float general exponentiation at this time. It is possible for more than 1557 Invalid exponent in complex long one interrupt to occur for an input/output float general exponentiation event. The aggregate of interrupts for an 1558 Invalid argument in short float input/output event is called a multiple complex ARCTAN or ARCTANH interrupt. 1559 Invalid argument in long float complex ARCTAN or ARCTANH When an input/output event is completed 2000 Unacceptable DELAY statement abnormally, the order in which the 2001 Unacceptable TIME statement conditions are raised, and therefore, the 3000 E-format conversion error order in which the interrupts for these 3001 F-format conversion error conditions occur, is implementation- 3002 A-format conversion error defined. If the on-unit for such a 3003 B-format conversion error condition ends abnormally, then all Section H: ON-Conditions 311 unprocessed conditions (i.e., remaining GO TO statement that transfers control interrupts of the multiple interrupt) are out of an on-unit is an abnormal ignored; if an on-unit ends normally, the on-unit termination. Note that if a next condition is processed. If an on-unit condition has been raised by the has not been established for such a SIGNAL statement, the normal return is condition or if SYSTEM is in effect, the always to the statement immediately next condition outstanding will be following SIGNAL. processed only if the standard system action is to comment and continue; if the standard system action is otherwise, all The conditions are grouped as follows: remaining interrupts in the multiple interrupt will be ignored. Note: If the UNDEFINEDFILE condition is 1. Computational conditions -- those raised by an attempt at implicit opening, conditions associated with data caused by a statement associated with an handling, expression evaluation, and event variable, the condition is raised computation. They are: immediately, and the interrupt will occur even before the WAIT statement is executed. CONVERSION FIXEDOVERFLOW OVERFLOW Section Organization SIZE UNDERFLOW ZERODIVIDE This section presents each condition in its logical grouping, and in alphabetical order within that grouping. In general, the following information is given for each 2. Input/output conditions -- those condition: conditions associated with data transmission. They are: 1. General format -- given only when it consists of more than the condition name. ENDFILE ENDPAGE KEY 2. Description -- a discussion of the NAME condition, including the circumstances PENDING under which the condition can be RECORD raised. Note that an enabled TRANSMIT condition can always be raised by a UNDEFINEDFILE SIGNAL statement; this fact is not included in the descriptions. 3. Result -- the result of the operation 3. Program-checkout conditions -- those that caused the condition to occur. conditions that facilitate the This applies when the condition is debugging of a program. They are: disabled as well as when it is enabled. In some cases, the result is CHECK not defined; that is, it cannot be SUBSCRIPTRANGE predicted. This is stated wherever STRINGRANGE applicable. 4. List processing condition -- the AREA 4. Standard system action -- the action condition, which is associated with taken by the system when an interrupt area usage. occurs and the programmer has not specified an on-unit to handle that 5. System action conditions -- those interrupt. conditions that provide facilities to extend the standard system action that 5. Status -- an indication of the is taken after the occurrence of a enabled/disabled status of the condition or at the completion of a condition at the start of the program, program. They are: and how the condition may be disabled (if possible) or enabled. ERROR FINISH 6. Normal return -- the point to which control is returned as a result of the 6. Programmer-named condition -- the normal termination of the on-unit. A CONDITION condition. 312 Computational Conditions implementations, this maximum is 15 for decimal fixed-point values and 31 for binary fixed-point values. The CONVERSION Condition Result: The result of the invalid fixed-point operation is undefined. Description: The CONVERSION condition occurs whenever an illegal conversion is Standard System Action: In the absence of attempted on character-string data. This an on-unit, the system prints a message and attempt may be made internally or during an raises the ERROR condition. input/output operation. For example, the condition occurs when a character other Status: FIXEDOVERFLOW is enabled than 0 or 1 exists in a character string throughout the program, except within the being converted to a bit string; other scope of a condition prefix that specifies examples are when a character string being NOFIXEDOVERFLOW. converted to a numeric character field contains characters not permitted by the Normal Return: Upon normal termination of PICTURE specification, or when a string the on-unit for this condition, control being converted to coded arithmetic data returns to the point immediately following does not contain the character the point of interrupt. representation of an arithmetic constant. All conversions of character-string data are carried out character-by-character in a The OVERFLOW Condition left-to-right sequence and the condition occurs for each invalid character. When an invalid character is encountered, an Description: The OVERFLOW condition occurs interrupt occurs (provided, of course, that when the magnitude of a floating-point CONVERSION has not been disabled) and the number exceeds the permitted maximum. (For current action specification for the System/360 implementations, the magnitude condition is executed. If the action of a floating-point number or intermediate specification is an on-unit, the invalid result must not be greater than character can be corrected within the unit approximately 10 75 or 2252.) by using the ONSOURCE or ONCHAR pseudo-variables. On return from the Result: The value of such an illegal on-unit, the conversion of the string is floating-point number is undefined. retried from the beginning. For the F Compiler, if the illegal character has not Standard System Action: In the absence of been corrected, a message is printed and an on-unit, the system prints a message and the ERROR condition is raised. raises the ERROR condition. Result: When CONVERSION occurs, the Status: OVERFLOW is enabled throughout the contents of the entire result field are program, except within the scope of a undefined. condition prefix specifying NOOVERFLOW. Standard System Action: In the absence of Normal Return: Upon normal termination of an on-unit, the system prints a message and the on-unit for this condition, control raises the ERROR condition. returns to the point immediately following the point of interrupt. Status: CONVERSION is enabled throughout the program, except within the scope of a condition prefix specifying NOCONVERSION. The SIZE Condition Normal Return: Upon the normal termination of the on-unit for this condition, control returns to the beginning of the string and Description: The SIZE condition occurs the conversion is retried. only when high-order (i.e., leftmost) significant binary or decimal digits are lost in an assignment to a variable or a temporary or in an input/output operation. The FIXEDOVERFLOW Condition This loss may result from a conversion involving different data types, different bases, different scales, or different Description: The FIXEDOVERFLOW condition precisions. occurs when the length of the result of a fixed-point arithmetic operation exceeds The SIZE condition differs from the the maximum length allowed by the FIXEDOVERFLOW condition in an important implementation. For System/360 sense, i.e., FIXEDOVERFLOW occurs when the Section H: ON-Conditions 313 size of a calculated fixed-point value Standard System Action: In the absence of exceeds the maximum allowed by the an on-unit, the system prints a message and implementation (see the description of the continues execution from the point at which FIXEDOVERFLOW condition), whereas SIZE is the interrupt occurred. raised when the size of the value being assigned to a data item exceeds the Status: UNDERFLOW is enabled throughout declared (or default) size of the data the program, except within the scope of a item. SIZE can be raised on assignment of condition prefix specifying NOUNDERFLOW. a value regardless of whether or not FIXEDOVERFLOW was raised in the calculation Normal Return: Upon normal termination of of that value. the on-unit for this condition, control returns to the point immediately following The declared size is not necessarily the the point of interrupt. actual precision with which the item is held in storage; however, the limit for SIZE is the declared or default size, not the actual size in storage. For example, The ZERODIVIDE Condition with the F Compiler, a fixed binary item of precision (20) will occupy a fullword in storage, but SIZE is raised if a value Description: The ZERODIVIDE condition whose size exceeds FIXED BINARY(20) is occurs when an attempt is made to divide by assigned to it. zero. This condition is raised for fixed-point and floating-point division. Result: The contents of the data item receiving the wrong-sized value are Result: The result of a division by zero undefined. is undefined. Standard System Action: In the absence of Standard System Action: In the absence of an on-unit, the system prints a message and an on-unit, the system prints a message and raises the ERROR condition. raises the ERROR condition. Status: SIZE is disabled within the scope Status: ZERODIVIDE is enabled throughout of a NOSIZE condition prefix and elsewhere the program, except within the scope of a throughout the program, except within the condition prefix specifying NOZERODIVIDE. scope of a condition prefix specifying SIZE. Normal Return: Upon normal termination of the on-unit for this condition, control Normal Return: Upon normal termination of returns to the point immediately following the on-unit for this condition, control the point of interrupt. returns to the point immediately following the point of interrupt. Input/Output Conditions The UNDERFLOW Condition The input/output conditions are always enabled and cannot appear in condition prefixes; they can be specified only in ON, Description: The UNDERFLOW condition SIGNAL, and REVERT statements. occurs when the magnitude of a floating-point number is smaller than the permitted minimum. (For System/360 implementations, the magnitude of a The ENDFILE Condition floating-point value may not be less than approximately 10- 76 or 2-260.) General Format: ENDFILE (file-name) UNDERFLOW does not occur when equal numbers are subtracted (often called Description: The ENDFILE condition can be significance error). raised during a GET or READ operation; it is caused by an attempt to read past the Note that, for the F Compiler, the file delimiter of the file named in the GET expression X**(-Y) (where Y>0) is evaluated or READ statement. It applies only to by taking the reciprocal of X**Y; hence, SEQUENTIAL files. the OVERFLOW condition may be raised instead of the UNDERFLOW condition. If the file is not closed after ENDFILE occurs, then any subsequent GET or READ Result: The invalid floating-point value statement for that file immediately raises is set to 0. the ENDFILE condition again. 314 If ENDFILE is raised by an input/output If ENDPAGE is raised during data statement using the EVENT option, the transmission, then, on return from the interrupt does not take place until the on-unit, the data is written on the current execution of a subsequent WAIT statement line, which may have been changed by the for that event in the same procedure. on-unit. If ENDPAGE results from a LINE or SKIP option, then, on return from the Standard System Action: In the absence of on-unit, the action specified by LINE or an on-unit, the system prints a message and SKIP is ignored. raises the ERROR condition. Status: The ENDFILE condition is always Standard System Action: In the absence of enabled; it cannot be disabled. an on-unit, the system starts a new page. If the condition is signaled, execution is Normal Return: Upon the normal termination unaffected and continues with the statement of the on-unit for the condition, execution following the SIGNAL statement. continues with the statement immediately following the statement that caused the Status: ENDPAGE is always enabled; it ENDFILE condition to be raised (or, if cannot be disabled. ENDFILE was raised by a READ with the EVENT option, control passes back to the WAIT Normal Return: Upon the normal completion statement from which the on-unit was of the on-unit for this condition, invoked). execution of the PUT statement continues in the manner described above. The ENDPAGE Condition The KEY Condition General Format: ENDPAGE (file-name) General Format: KEY (file-name) The "file name" must be the name of a file having the PRINT attribute. Description: The KEY condition can be raised only during operations on keyed Description: The ENDPAGE condition is records. It is raised in any of the raised when a PUT statement results in an following cases: attempt to start a new line beyond the limit specified for the current page. This 1. The keyed record cannot be found. limit can be specified by the PAGESIZE option in an OPEN statement; if PAGESIZE 2. An attempt is made to add a duplicate has not been specified, a default limit of key. 60 applies for the F Compiler. The attempt to exceed the limit may be made during data 3. The key is out of sequence. transmission (including associated format items, if the PUT statement is 4. An error occurred in the conversion of edit-directed), by the LINE option, or by the key. the SKIP option. ENDPAGE can also be raised by a LINE option or LINE format item 5. The key has not been specified that specifies a line number less than the correctly. current line number. 6. No space is available to add the keyed When ENDPAGE is raised, the current line record. number is one greater than that specified by the PAGESIZE option (or 61, if the If KEY is raised by an input/output default applies) so that it is possible to statement using the EVENT option, the continue writing on the same page. The interrupt does not occur until the on-unit may start a new page by execution execution of a subsequent WAIT statement of a PAGE option or a PAGE format item, for that event in the same procedure. which sets the current line to 1. The condition is not raised for a LOCATE ENDPAGE is raised only once per page. statement until actual transmission is If the on-unit does not start a new page, attempted (that is, immediately before the current line number may increase execution of the next WRITE or LOCATE indefinitely. If a subsequent LINE option statement for the file, or immediately or LINE format item specifies a line number before the file is closed); until the error that is less than the current line number, is corrected, the record cannot be ENDPAGE is not raised, but a new page is transmitted, nor can any further operation started with the current line set to 1. take place for the file. Section H: ON-Conditions 315 Standard System Action: In the absence of attempt is made to read a record that is an on-unit, the system prints a message and temporarily unavailable (i.e., for the F raises the ERROR condition. Compiler, when the message queue associated with the file contains no messages at the Status: KEY is always enabled; it cannot time the READ statement is executed). be disabled. Standard System Action: In the absence of Normal Return: Upon the normal completion an on-unit, the action is as described for of the on-unit for this condition, control normal return. passes to the statement immediately following the statement that caused KEY to Status: PENDING is always enabled; it be raised (or, if KEY was raised by an cannot be disabled. input/output statement with the EVENT option, control passes back to the WAIT Normal Return: Upon the normal completion statement from which the on-unit was of the on-unit for .this condition, control invoked). returns to the point of interrupt (unless the condition was signaled), where execution is suspended until an appropriate record becomes available. If the condition The NAME Condition was signaled, execution continues with the statement immediately following the SIGNAL statement that caused the interrupt. General Format: NAME (file-name) Note: The value of the ONKEY built-in Description: The NAME condition can be function when the PENDING condition is raised only during a data-directed GET raised is a null string. statement. It can be raised either when an identifier in the input stream does not have a counterpart in the data list of the GET statement or when the GET statement has The RECORD Condition no data list and an identifier that is not known in the block is encountered in the stream. General Format: RECORD (file-name) NAME is raised at the time the unmatched Description: The RECORD condition can be identifier is encountered in the stream. raised only during a READ, WRITE, or RE-WRITE operation. It is raised by any of The programmer may retrieve the data the following: field (i.e., the identifier and its value) containing the unmatched identifier by 1. The size of the record is greater than using the built-in function DATAFIELD in the size of the variable. the on-unit. 2. The size of the record is less than Standard System Action: In the absence of the size of the variable. an on-unit, the system ignores the incorrect data field, prints a message, and 3. A record of zero length has been read. continues the execution of the GET statement. 4. An attempt is made to write a record of zero length. Status: NAME is always enabled; it cannot be disabled. If the size of the record is greater than the size of the variable, the excess Normal Return: Upon the normal completion data in the record is lost on input and is of the on-unit for this condition, the unpredictable on output. If the size of execution of the GET statement continues the record is less than the size of the with the next identifier in the stream. variable, the excess data in the variable is not transmitted on output and is unaltered on input. (Thus, if a zero length record is read, the variable The PENDING Condition contains the same data that it contained before the read operation.) If an attempt is made to write a record of zero length, General Format: PENDING (file-name) the attempt is aborted, and, in effect, the statement is ignored. Description: Except when signaled, the PENDING condition can be raised only during If RECORD is raised during transmission execution of a READ statement for a of an area, the area control field will TRANSIENT INPUT file. It is raised when an contain incorrect information 316 If RECORD is raised by an input/output The UNDEFINEDFILE Condition statement using the EVENT option, the interrupt does not occur until the execution of a subsequent WAIT statement General Format: UNDEFINEDFILE (file-name) for that event in the same procedure. Description: The UNDEFINEDFILE condition is raised whenever an attempt to open a Standard System Action: In the absence of file is unsuccessful. If the attempt is an on-unit, the system prints a message and made by means of an OPEN statement that raises the ERROR condition. specifies more than one file name, attempts to open all other files in that statement will be made before the condition is Status: RECORD is always enabled; it raised. If the condition is raised for cannot be disabled. more than one file in the same OPEN statement, on-units will be executed according to the order of appearance (taken Normal Return: Upon normal completion of from left to right) of the file names in the on-unit, execution continues with the that OPEN statement. statement immediately following the one for which RECORD occurred (or if RECORD was If the condition is raised by an raised by an input/output statement with an implicit file opening in an input/output EVENT option, control returns to the WAIT statement without the EVENT option, then, statement from which the on-unit was upon normal return from the on-unit, invoked). processing continues with the remainder of the interrupted input/output statement. If the file was not opened in the on-unit, then the statement cannot be continued and the ERROR condition is raised. The TRANSMIT Condition If the condition is raised by an implicit file opening in an input/output General Format: TRANSMIT (file-name) statement having an EVENT option, then the interrupt occurs before the event variable Description: The TRANSMIT condition can be is initialized. In other words, the event raised during any input/output operation. variable retains its previous value and It is raised by a permanent transmission remains inactive. On normal return from error, and therefore signifies that any the on-unit, the evente variable is data transmitted is potentially incorrect. initialized, that is, it is made active and During input, the condition is raised after its completion value is set to '0'B assignment of the potentially incorrect (provided the file has been opened in the data item or record. During output, the on-unit). Processing then continues with condition is raised after the transmission the remainder of the interrupted statement. of the potentially incorrect data item or However, if the file has not been opened in record has been attempted. the on-unit, the event variable remains uninitialized, the statement cannot be If TRANSMIT is raised by an input/output continued, and the ERROR condition is statement using the EVENT option, the raised. interrupt does not take place until the execution of a subsequent WAIT statement For the F Compiler, some cases for which for that event in the same procedure. the UNDEFINEDFILE condition is raised are as follows: Standard System Action: In the absence of an on-unit, the system prints a message and 1. A conflict in attributes exists. raises the ERROR condition. 2. The blocksize has not been specified. Status: TRANSMIT is always enabled; it cannot be disabled. 3. There is no recognizable DD statement for the file. Normal Return: Upon the normal completion of the on-unit, processing continues as Standard System Action: In the absence of though no error had occurred, allowing an on-unit, the system prints a message and another condition (e.g., RECORD) to be raises the ERROR condition. raised by the statement or data item that raised the TRANSMIT condition. (If Status: UNDEFINEDFILE is always enabled; TRANSMIT is raised by an input/output it cannot be disabled. statement with an EVENT option, control returns to the WAIT statement from which Normal Return: Upon the normal completion the on-unit was invoked.) of the final on-unit, control is given to Section H: ON-Conditions 317 the statement immediately following the CHECK (Q,R,S) statement that caused the condition to be raised (see "Description" for action in the The CHECK condition is raised within the case of an implicit opening). scope of a CHECK prefix in any of the following cases: 1. If a name in the CHECK prefix is a statement label constant, the Program-Checkout Conditions condition is raised and the interrupt occurs prior to the execution of the statement to which the label is The CHECK Condition prefixed. If the label is prefixed to a DECLARE or FORMAT statement, the condition is not raised. General Format: CHECK (name-list) 2. If a name in the CHECK prefix is a The "name list" is one or more names variable (as specified in item 3 of separated by commas; a name may be a the general format above), the qualified name. Each name must be one of condition is raised whenever the value the following: of the variable, or of any part of the variable, is changed by any statement 1. An entry name within the scope of the prefix. 2. A statement label constant Specifically, if the identifier ID represents the variable, the condition 3. An unsubscripted name representing an is raised in the following cases: element, an array, or a structure a. ID appears on the left-hand side The names appearing in a CHECK prefix of an assignment statement. (This refer to the names known within the block applies to BY NAME assignment even to which the prefix is attached. A name if the name mentioned does not cannot be a parameter or a variable having appear in the final expansion of the DEFINED or BASED atrributes. the statement.) b. ID is set as a result of a Description: The CHECK condition is raised pseudo-variable appearing on the only within the scope of a CHECK condition left-hand side of an assignment prefix. Such a condition prefix may be statement. prefixed only to a PROCEDURE or BEGIN statement. The CHECK condition is enabled c. ID appears as the control variable separately for each name in the list of the of a DO-group or a repetitive CHECK prefix. For example, the prefix specification in a data list (or CHECK (A,B,C) is equivalent to CHECK (A): it is set as a result of a CHECK (B): CHECK (C). Hence, the action pseudo-variable appearing as the specification can be controlled separately control variable of a DO-group or for each name. The REVERT statement can be a repetitive specification in a used to change the action specification for data list). one or more names in the list. Also, a NOCHECK prefix can be used to disable the d. ID appears in the data list of an CHECK condition for a specific name (like edit-directed or list-directed GET CHECK, NOCHECK can appear only as a prefix statement. to a PROCEDURE or BEGIN statement). e. ID is altered by data-directed If the name of a structure or array of input. structures appears in the name list following CHECK, such a list is equivalent f. ID appears in the REPLY option of to one that contains, in the order in which a DISPLAY statement. they were declared, the elements of that structure or array of structures. For g. ID appears in the STRING option of example, if P is defined: a PUT statement. DECLARE 1 P, 2 Q, 2 R, 2 S; h. ID is passed as an argument to a programmer-defined procedure, no then: intermediate argument is created, and the procedure terminates with CHECK (P) a RETURN or END. is equivalent to: i. ID appears in the KEYTO or INTO 318 option of a READ statement. Note 3. If a name in the CHECK prefix is an that if the READ statement has an entry name, the condition is raised EVENT option, the CHECK condition and the interrupt occurs prior to each will not be raised. invocation of the entry point corresponding to the entry name. The condition is raised only if the entry j. ID is a pointer variable and point is invoked by the entry name appears in a SET option. given in the prefix. Note that in a, b, d, and e above, if 4. For the F Compiler the number of ID is a structure, the CHECK condition characters in a qualified name, which is raised each time an element of that is to be used in CHECK name lists, structure is given a value, but the must not exceed 256. interrupt for each condition does not occur until after the statement that 5. The maximum number of entries in a caused the condition to be raised has CHECK condition, whether in a prefix been executed completely. list or in an ON statement, is 510. The maximum number of data items being The condition is not raised under any of checked at any point in the the following circumstances: compilation varies between 2078-2n and 3968-2n, where n is the number of a. If the value of a variable defined currently checked items which have the on ID or on part of ID changes in attribute EXTERNAL. any of the ways described above. b. If the parameter that represents Result: When CHECK is raised, there is no the argument ID changes value. effect on the statement being executed. c. If ID appears in a GO TO or RETURN Standard System Action: In the absence of statement or any statement that an on-unit, if the name in the name list is involves the execution of a GO TO a statement-label constant, a or RETURN statement. statement-label variable, a task name, an event name, an area variable, a locator d. If ID is set by the INITIAL variable, or an entry name, then for the F attribute. Compiler, only the name is printed on SYSPRINT; in all other cases, the name and Note that in all of the above its new value are printed on SYSPRINT in contexts, ID can appear in subscripted the format of data-directed output. or qualified form. Note also that ID need not appear in the name list of a Note: Standard system action for the CHECK CHECK prefix; it only need represent a condition requires access to the variable; structure or element contained by, or consequently, if SIGNAL CHECK is given for containing, a name in the list. an unallocated variable, an error will result, as it would if the variable were The interrupt for a CHECK condition accessed by an on-unit. occurs after the statement that caused the condition to be raised has been Status: CHECK is disabled by default and executed. (Note that an IF statement within the scope of a NOCHECK condition is considered executed just prior to prefix. It is enabled only within the the execution of the THEN or ELSE scope of a CHECK prefix. clause.) If the statement is a DO statement, the interrupt occurs each Normal Return: Upon the normal completion time control proceeds sequentially to of the on-unit for the CHECK condition, the statement following the DO execution continues immediately following statement. If the DO specifies the point at which the interrupt occurred. repetitive execution, the interrupt occurs each time the control variable changes value. Only a data-directed GET statement or The STRINGRANGE Condition a DO statement can cause a condition to be raised more than once for the same appearance of the same name. If Definition: The STRINGRANGE condition is a statement causes a CHECK condition raised whenever the lengths of the to be raised for several names, the arguments to a SUBSTR reference fail to conditions will be raised in the comply with the rules described for the left-to-right order of appearance of SUBSTR built-in function. It is raised for the names. each such reference. Section H: ON-Conditions 319 Standard System Action: Execution Status: SUBSCRIPTRANGE is disabled by continues as described for normal return. default and within the scope of a NOSUBSCRIPTRANGE condition prefix. It is Status: STRINGRANGE is disabled by default enabled only within the scope of a and within the scope of a NOSTRINGRANGE SUBSCRIPTRANGE condition prefix. condition prefix. It is enabled only within the scope of a STRINGRANGE condition prefix. Normal Return: Upon the normal completion of the on-unit for this condition, Normal Return: On normal return from the execution continues immediately following on-unit, execution continues with a revised the point at which the condition occurred. SUBSTR reference whose value is defined as follows: Assuming that the length of the source string (after execution of the on-unit, if List Processing Condition specified) is k, the starting point is i, and the length of the substring is j; The AREA Condition 1. If i is greater than k the value is the null string. Description: The AREA condition is raised 2. If i is less than or equal to k, the in either of the following circumstances: value is that substring beginning at the mth character or bit of the source 1. When an attempt is made to allocate a string and extending n characters or based variable within an area that bits, where m and n are defined by: contains insufficient free storage for the allocation to be made. m=MAX(i,1) 2. When an attempt is made to perform an n=MAX(0,MIN(j+MIN(i,1)-1,k-m+1)) area assignment, and the target area [if j is specified] contains insufficient storage to accommodate the allocations in the n=k-m+1 source area. [if j is not specified] This means that the new arguments are Result: If the condition occurs as the forced within the limits. result of an attempted allocation, the allocation has no effect; if the condition The values of i and j are established occurs as a result of an area assignment, before entry to the on-unit; they are not the contents of the target area are reevaluated on return from the on-unit. undefined. Standard System Action: In the absence of The SUBSCRIPTRANGE Condition an on-unit, the system prints a message and raises the ERROR condition. Description: SUBSCRIPTRANGE can be raised whenever a subscript is evaluated and found Status: AREA is always enabled; it cannot to lie outside its specified bounds. If be disabled. more than one subscript is associated with an identifier, e.g., A(I,J,K), Normal Return: On normal return from the SUBSCRIPTRANGE is raised after each on-unit, the action is as follows: erroneous subscript has been checked. Thus, if both I and J in the above example 1. If the condition was raised by an were in error, SUBSCRIPTRANGE would be allocation, the allocation is raised after I was evaluated and again reattempted. If the on-unit has after J was evaluated. changed the value of a pointer qualifying the reference to the Result: When SUBSCRIPTRANGE has been inadequate area so that it points to raised, the value of the illegal subscript another area, the allocation is is undefined, and, hence, the reference is reattempted within the new area. also undefined. 2. If the condition was raised by an area Standard System Action: In the absence of assignment, or by a SIGNAL statement, an on-unit, the system prints a message and execution continues at the point of raises the ERROR condition. interrupt. 320 System Action Conditions part of that task. An abnormal return from the on-unit will avoid any subsequent task termination processes and permit the The ERROR Condition interrupted task to continue. Standard System Action: In the absence of Description: The ERROR condition is raised an on-unit, no action is taken; that is, under the following circumstances: execution of the interrupted statement is resumed. 1. As a result of the standard system action for an ON-condition for which Status: FINISH is always enabled; it that action is to "print an error cannot be disabled. message and raise the ERROR condition" Normal Return: Upon the normal completion 2. As a result of an error (for which of the on-unit, execution of the there is no ON-condition) occurring interrupted statement is resumed. during program execution 3. As a result of a SIGNAL ERROR statement Programmer-Named Condition Standard System Action: For the F Compiler, if the condition is raised in the major task, the FINISH condition is raised, The CONDITION Condition and subsequently the major task is terminated. If the condition is raised in any other task, that task is terminated. General Format: CONDITION (identifier) Status: ERROR is always enabled; it cannot The "identifier" must be specified by be disabled. the programmer. The appearance of an identifier with CONDITION in an ON, SIGNAL, Normal Return: Upon the normal completion or REVERT statement constitutes a of the on-unit, the standard system action contextual declaration for it; the is taken. identifier is given the EXTERNAL attribute. Description: CONDITION is raised by a SIGNAL statement that specifies the The FINISH Condition appropriate identifier. The identifier specified in the SIGNAL statement determines which CONDITION condition is to Description: The FINISH condition is be raised. raised during execution of a statement which would cause the termination of the Standard System Action: In the absence of major task of a PL/I program, that is, by a an on-unit for this condition, the system STOP statement in any task, or an EXIT prints a message and continues with the statement in the major task, or a RETURN or statement following SIGNAL. END statement in the initial external procedure of the major task. The condition Status: CONDITION is always enabled; it is also raised by SIGNAL EINISH in any cannot be disabled. task, and as part of the standard system action for the ERROR condition. The Normal Return: Upon the normal completion interrupt occurs in the task in which the of the on-unit, execution continues with statement is executed, and any on-unit the statement following the SIGNAL specified for the condition is executed as statement that caused the interrupt. Section H: ON-Conditions 321 Section I: Attributes A name appearing in a PL/I program may have FACTORING OF ATTRIBUTES one of many different meanings. It may, for example, be a variable referring to arithmetic data items; it may be a file Attributes common to several names can be name; it may be a variable referring to a factored in a declaration to eliminate character string, or it may be a statement repeated specification of the same label or a variable referring to a attribute for many identifiers. Factoring statement label. is achieved by enclosing the names in parentheses, and following this by the set of attributes which apply. All factored Properties, or characteristics, of the attributes must apply to all of the names. values a name represents (for example, No factored attribute can be overridden for arithmetic characteristics of data items any of the names, but any name within the represented by an arithmetic variable) and list may be given other attributes so long other properties of the name itself (such as there is no conflict with the factored as scope, storage class, etc.) together attributes. Factoring of attributes is make up the set of attributes that can be permitted only in the DECLARE statement, associated with a name. but not within an ENTRY attribute declaration. The number of left parentheses used for factoring attributes in DECLARE statements is limited to 73 in a The attributes enable the compiler to compilation. The dimension attribute may assign a unique meaning to the identifier be factored. The precision and length specified in a DECLARE statement. For attributes can be factored only in example, if the variable is an arithmetic conjunction with an associated keyword data variable, the base, scale, mode, and attribute. Factoring can be nested as precision attributes must be associated shown in the fourth example below. with the name. Associated attributes are those specified in a DECLARE statement or Names within the parenthesized list are assumed by default. separated by commas. Note: Structure level numbers can also be This section discusses the different factored, but a factored level number must attributes. The attributes are grouped by precede the parenthesized list. function and then detailed discussions follow, in alphabetic order, showing the DECLARE (A,B,C,D) BINARY FIXED (31); rules, defaults, and format for each attribute. DECLARE (E DECIMAL(6,5), F CHARACTER(10)) STATIC; DECLARE 1 A, 2(B,C,D) (3,2) BINARY FIXED (15), ...; DECLARE ((A,B) FIXED(10), C FLOAT(5)) Specification of Attributes EXTERNAL; Attributes, other than the dimension, length, and precision attributes, specified Data Attributes in DECLARE statements, are separated by blanks and may appear in any order. The dimension attribute specification must PROBLEM DATA immediately follow the array name; the length and precision attribute specifications must follow one of their Attributes for problem data are used to associated attributes. A comma must follow describe arithmetic and string variables. the last attribute specification for a Arithmetic variables have attributes that particular name (or the name itself if no specify the base, scale, mode, and attributes are specified with it), unless precision of the data items. String it is the last name in the DECLARE variables have attributes that specify statement, in which case the semicolon is whether the variable represents character used. strings or bit strings and that specify the 322 length to be maintained. The arithmetic ENTRY data attributes are: RETURNS BINARY|DECIMAL GENERIC FIXED|FLOAT BUILTIN REAL|COMPLEX (precision) PICTURE File Description Attributes The string data attributes are: The file description attributes establish BIT|CHARACTER an identifier as a file name and describe characteristics for that file, e.g., how (length) the data is to be transmitted, whether records are to be buffered. If the same VARYING file name is declared in more than one external procedure, the declarations must PICTURE not conflict, unless one is declared with the INTERNAL attribute. Other attributes can also be declared for data variables. The INITIAL attribute The file description attributes are: specifies the initial value to be given to the variable. The DEFINED attribute FILE specifies that the data item is to occupy the same storage area as that assigned to STREAM|RECORD other data. The ALIGNED and UNALIGNED attributes specify the positioning of data elements in storage. The storage class and INPUT|OUTPUT|UPDATE scope attributes also apply to data. PRINT Other attributes apply only to data SEQUENTIAL|DIRECT|TRANSIENT aggregates. For array variables, the dimension attribute specifies the number of BUFFERED|UNBUFFERED dimensions and the bounds of an array. The LIKE attribute specifies that the structure BACKWARDS variable being declared is to have the same structuring as the structure of the name ENVIRONMENT(option-list) following the attribute LIKE. KEYED PROGRAM CONTROL DATA EXCLUSIVE Note that file description attributes, Attributes for program control data specify except for the ENVIRONMENT attribute, can that the associated name is to be used by be specified as options in the option list the programmer to control the execution of of the OPEN statement. this program. The LABEL, TASK, EVENT, POINTER, OFFSET, and AREA attributes specify program control data. Scope Attributes Entry Name Attributes The scope attributes are used to specify whether or not a name may be known in The entry name attributes identify the name another external procedure. The scope being declared as an entry name and attributes are EXTERNAL and INTERNAL. describe features of that entry point. For example, the attribute BUILTIN specifies All external declarations for the same that the reference to the associated name identifier in a program are linked as within the scope of the declaration is declarations of the same name. The scope interpreted as a reference to the built-in of this name is the union of the scopes of function or pseudo-variable of the same all the external declarations for this name. The entry name attributes are: identifier. Section I: Attributes 323 In all of the external declarations for ALIGNED and UNALIGNED (Data Attributes) the same identifier, the attributes declared must be consistent, since the declarations all involve a single name. The ALIGNED and UNALIGNED attributes For example, it would be an error if the specify the positioning of data elements in identifier ID were declared as an EXTERNAL storage, to influence speed of access or file name in one block and as an EXTERNAL storage economy respectively. They may be entry name in another block in the same specified for element, array, or structure program. variables. The INTERNAL attribute specifies that ALIGNED in System/360 implementations the declared name cannot be known in any specifies that the data element is to be other block except those contained in the aligned on the storage boundary block in which the declaration is made. corresponding to its data type requirement. UNALIGNED in System/360 implementations The same identifier may be declared with specifies that the data element is to be the INTERNAL attribute in more than one stored contiguously with the data element block without regard to whether the preceding it, and that a word or doubleword attributes given in one block are item is to be mapped on the next available consistent with the attributes given in byte boundary in a similar manner to another block, since the compiler regards character strings of length 4 or 8. such declarations as referring to different names. General format: ALIGNED|UNALIGNED For a discussion of the scope of names, see Part I, Chapter 7, "Recognition of General rules: Names." 1. Although they are essentially element data attributes, ALIGNED and UNALIGNED can be applied to any array or structure. This is equivalent to applying the attribute to all contained elements that are not Storage Class Attributes explicitly declared with the ALIGNED or UNALIGNED attribute. The storage class attributes are used to 2. Application of either attribute to a specify the type of storage for a data contained array or structure overrides variable. The storage class attributes an ALIGNED or UNALIGNED attribute that are: otherwise would apply to elements of the contained aggregate by having been STATIC specified for the containing structure. AUTOMATIC 3. The LIKE attribute is expanded before CONTROLLED the ALIGNED and UNALIGNED attributes are applied to the contained elements BASED of the LIKE structure variable. The only ALIGNED and UNALIGNED attributes that are carried over from the LIKE structure variable (i.e., A in the example below) are those explicitly specified for substructures and Alphabetic List of Attributes elements of the structure variable. Example: Following are detailed descriptions of the attributes, listed in alphabetic order. DECLARE 1 A ALIGNED, Alternative attributes are discussed 2 B, /* ALIGNED FROM A */ together, with the discussion listed in the 2 C UNALIGNED, alphabetic location of the attribute whose 3 D; /* UNALIGNED FROM C */ name is the lowest in alphabetic order. A cross-reference to the combined discussion DECLARE 1 X UNALIGNED LIKE A; appears wherever an alternative appears in the alphabetic listing. DECLARE 1 Y LIKE A; 324 The second declare statement is AREA (Program Control Data Attribute) equivalent to: The AREA attribute defines storage that, on DECLARE 1 X UNALIGNED, allocation, is to be reserved for the 2 B, /* UNALIGNED FROM X */ allocation of based variables. Storage 2 C UNALIGNED, thus reserved can be allocated to and freed 3 D; /* UNALIGNED FROM C */ from based variables by naming the area variable in the IN option of the ALLOCATE and FREE statements. Storage that has been The third declare statement is freed can be subsequently reallocated to a equivalent to: based variable. 4. For overlay defining involving bit- and character-class data (see Figure 1. The area size for areas that are not I-1), both the defined item and the of static storage class is given by an overlaid part of the base item must be expression whose integral value unaligned. For all other types of specifies the number of units of defining, equivalent items must be storage to be reserved. The unit for either both ALIGNED or both UNALIGNED. System/360 implementations is the byte. 5. The ALIGNED and UNALIGNED attributes of an argument in a procedure 2. The size for areas of static storage invocation must match the attributes class must be specified as a constant; of the corresponding parameter. If for the F Compiler, it must be a these attributes of the original decimal integer constant. argument do not match those of the corresponding parameter in an ENTRY 3. Data of the area type cannot be attribute declaration, a dummy converted to any other type; an area argument is created, with the can be assigned to an area variable attributes specified in the ENTRY only. attribute declaration, and the original argument is assigned to it. 4. No operators can be applied to area variables. 6. If a based variable is used to refer to a generation of another variable, 5. Only the INITIAL CALL form of the the ALIGNED and UNALIGNED attributes INITIAL attribute is allowed with area of both variables must agree. variables. 7. Default assumptions for ALIGNED and 6. An area variable cannot be unaligned. UNALIGNED are applied on an element basis. Assumptions: 8. POINTER, OFFSET, LABEL, EVENT and AREA 1. The implementation maximum size AREA cannot be unaligned. is 32,767 bytes. If the size specification is omitted, a default Assumptions: value is assumed. For the F Compiler, this is 1000. 1. Defaults are applied at element level. The default for bit-string data, 2. An area variable can be contextually character-string data, and numeric declared by its appearance in an character data is UNALIGNED; for all OFFSET attribute or an IN option. other types of data, the default is Note, however, that all contextually ALIGNED. declared area variables are given the AUTOMATIC attribute. The F Compiler 2. For all operators and built-in implementation requires that the functions, the default for ALIGNED or variable named in the OFFSET attribute UNALIGNED is applicable to the must be based; if a nonbased area elements of the result. variable is named, the offset variable will be changed to a pointer variable. 3. Constants take the default for ALIGNED Hence, unless the variable named in or UNALIGNED. the OFFSET attribute is explicitly Section I: Attributes 325 declared, OFFSET effectively becomes STATIC, AUTOMATIC, and BASED POINTER, and a severe error occurs. 3. attributes cannot be specified for parameters. 4. Variables declared with adjustable array bounds, string lengths, or area AUTOMATIC, STATIC, CONTROLLED and BASED sizes cannot have the STATIC (Storage Class Attributes) attribute. 5 For a structure variable, a storage The storage class attributes are used to class attribute can be given only for specify the type of storage allocation to the major structure name. The be used for data variables. attribute then applies to all elements of the structure or to the entire AUTOMATIC specifies that storage is to array of structures. If the attribute be allocated upon each entry to the block CONTROLLED or BASED is given to a to which the storage declaration is structure, only the major structure internal. The storage is released upon and not the elements can be allocated exit from the block. If the block is a and freed. procedure that is invoked recursively, the previously allocated storage is "pushed 6. The following rules govern the use of down" upon entry; the latest allocation of based variables: storage is "popped up" upon termination of each generation of the recursive procedure a. The pointer variable named in the (for a discussion of push-down and pop-up BASED attribute must be a stacking, see Part I, Chapter 6, "Blocks, nonbased, unsubscripted, element Flow of Control, and Storage Allocation"). pointer variable. This applies to explicit pointer qualifiers also. STATIC specifies that storage is to be allocated when the program is loaded and is b. Whenever a pointer value is needed not to be released until program execution to complete a based variable has been completed. reference, and none is explicitly specified, the pointer variable CONTROLLED specifies that full control named in the relevant BASED will be maintained by the programmer over attribute is used. the allocation and freeing of stora ge by means of the ALLOCATE and FREE statements. c. Based variables cannot have the Multiple allocations of the same controlled INITIAL attribute. Based label variable, without intervening freeing, will arrays cannot be initialized by cause stacking of generations of the subscripted label prefixes. variable. d. When reference is made to a based BASED, like CONTROLLED, specifies that variable, the data attributes full control over storage allocation and assumed are those of the based freeing will be maintained by the variable, while the qualifying programmer, but by various methods that are pointer variable identifies the described in Chapter 14, "Based Variables location of data. and List Processing." Multiple allocations are not stacked but are available at any e. A based variable can be used to time; each can be identified by the value identify and describe existing of a pointer variable. data; to obtain storage by means of the ALLOCATE statement; or to General format: obtain storage in an output buffer by means of the LOCATE statement. STATIC|AUTOMATIC| CONTROLLED|BASED(pointer-variable) f. The relative locations of based variables allocated within an area General rules: can be identified by the values of offset variables, but these must 1. Automatic and based variables can have be assigned to pointer variables internal scope only. Static and for the purpose of explicit controlled variables may have either qualification. internal or external scope. g. The EXTERNAL attribute cannot 2. Storage class attributes cannot be appear with a based variable specified for entry names, file names, declaration, but a based variable members of structures, or DEFINED data reference can be qualified by an items. external pointer variable. 326 h. A based structure can be declared BINARY and DECIMAL (Arithmetic Data to contain only one adjustable Attributes) bound or length specification. See "The REFER Option," in Chapter 14, "Based Variables and List The BINARY and DECIMAL attributes specify Processing." the base of the data items represented by an arithmetic variable as either binary or decimal. i. Based variables cannot be transmitted using data-directed General format: input/output. BINARY|DECIMAL j. The VARYING attribute cannot be General rule: applied to based variables. The BINARY or DECIMAL attribute cannot Assumptions: be specified with the PICTURE attribute. 1. If no storage class attribute is Assumptions: specified and the scope is internal, AUTOMATIC is assumed. Undeclared identifiers (or identifiers declared only with one or more of the 2. If no storage class attribute is dimensions, UNALIGNED, ALIGNED, scope, and specified and the scope is external, storage class attributes) are assumed to be STATIC is assumed. arithmetic variables with assigned attributes depending upon the initial 3. If neither the storage class nor the letter. For identifiers beginning with any scope attribute is specified, letter I through N, the default attributes AUTOMATIC is assumed. are REAL FIXED BINARY (15,0). For identifiers beginning with any other 4. A pointer variable can be contextually alphabetic character, the default declared by its appearance in the attributes are REAL FLOAT DECIMAL (6). If EASED attribute. FIXED or FLOAT and/or REAL or COMPLEX are declared, then DECIMAL is assumed. The default precisions are those defined for System✓ 360 implementations. BACKWARDS (File Description Attribute) BIT and CHARACTER (String Attributes) The BACKWARDS attribute specifies that the records of a SEQUENTIAL INPUT file associated with a data set on magnetic tape The BIT and CHARACTER attributes are used are to be accessed in reverse order, i.e., to specify string variables. The BIT from the last record to the first record. attribute specifies a bit string. The CHARACTER attribute specifies a character General format: BACKWARDS string. The length attribute for the string must also be specified. General format: General rules: BIT 1. The BACKWARDS attribute applies to (length) [VARYING] RECORD files only; that is, it CHARACTER conflicts with the STREAM attribute. It implies RECORD and SEQUENTIAL. General rules: 2. The BACKWARDS attribute applies only 1. The length attribute specifies the to files associated with data sets on length of a fixed-length string or the magnetic tape. maximum length of a varying-length string. 2. The VARYING attribute specifies that the variable is to represent BASED (Storage Class Attribute) varying-length, strings, in which case length specifies the maximum length. The current length at any time is the See AUTOMATIC. length of the current value. For the Section I: Attributes 327 F Compiler, the length of an The UNBUFFERED attribute specifies that uninitialized varying-length string is such records need not pass through buffers. set to zero. VARYING may appear It does not, however, specify that they anywhere in the declaration of the must not. For the F Compiler, hidden string, and it may be factored. buffers will, in fact, be used if INDEXED VARYING cannot be applied to based or REGIONAL (2) or (3) is specified in the variables. ENVIRONMENT attribute or if the records are variable-length. 3. The length attribute must immediately follow the CHARACTER or BIT attribute at the same factoring level with or General format: without intervening blanks. 4. The length attribute may be specified BUFFERED|UNBUFFERED by an expression or an asterisk. If the length specification is an General rule: expression, it is converted to an integer when storage is allocated for the variable. The BUFFERED and UNBUFFERED attributes can be specified for TRANSIENT or The asterisk notation can be used for SEQUENTIAL RECORD files only. the length attribute specification to indicate that the length is specified elsewhere. For parameters or Assumption: CONTROLLED variables, the length can be taken from a previous allocation or, for CONTROLLED variables, it can Default is BUFFERED. be specified in a subsequent ALLOCATE statement. 5. If a string has the STATIC attribute, the length attribute must be a decimal BUILTIN (Entry Attribute) integer constant. 6. If a string has the BASED attribute, The BUILTIN attribute specifies that any the length attribute must be a decimal reference to the associated name within the integer constant unless the string is scope of the declaration is to be a member of a based structure and the interpreted as a reference to the built-in REFER option is used, in which case function or pseudo-variable of the same one adjustable string length may be name. allowed. (See "The REFER Option" in Chapter 14.) General format: 7. The BIT, CHARACTER, and VARYING BUILTIN attributes cannot be specified with the PICTURE attribute. General rules: 8. The PICTURE attribute can be used 1 BUILTIN is used to refer to a built-in instead of CHARACTER to declare a function or pseudo-variable in a block fixed-length character-string variable that is contained in another block in (see the PICTURE attribute). which the same identifier has been declared to have another meaning. 9. All of the string attributes must be declared explicitly unless the PICTURE 2 If the BUILTIN attribute is declared attribute is used. There are no for an entry name, the entry name can defaults for string data. have no other attributes. 3. The BUILTIN attribute cannot be BUFFERED and UNBUFFERED (File Description declared for parameters. Attributes) 328 COMPLEX and REAL (Arithmetic Data specification used to determine the portion Attributes) of a base identifier array that the currently declared variable will represent. POSITION is discussed under the rules for The COMPLEX and REAL attributes are used to overlay defining. specify the mode of an arithmetic variable. REAL specifies that the data items represented by the variable are to be real Rules for defining: numbers. COMPLEX specifies that the data items represented by the variable are to be 1. The INITIAL, storage class, and scope complex numbers, that is, each data item is attributes cannot be specified for the a pair: the first member is a real number defined item. The defined item must and the second member an imaginary number. be a level 1 variable and it cannot be a parameter. The VARYING attribute General format: must not be specified for either the defined item or the base identifier. REAL|COMPLEX It should be noted that although the base can have the EXTERNAL attribute, General rule: the defined item always has the INTERNAL attribute and cannot be If a numeric character variable is to declared with any scope attribute. If represent complex values, the COMPLEX the base is external, its name will be attribute must be specified with the known in all blocks in which it is PICTURE attribute. The COMPLEX attribute declared external, but the name of the is the only other arithmetic or string data defined item will not. However, the attribute that can be specified with the value of the defined item will be PICTURE attribute. changed if the value of the base item is changed in any block. Assumption: 2. The base identifier must always be Default is REAL. known within the block in which the defined item is declared. The base identifier cannot have the DEFINED attribute. It can represent a minor CONTROLLED (Storage Class Attribute) structure. The current F Compiler does not allow the base identifier to be controlled or based. See AUTOMATIC. There are two types of defining, correspondence defining and overlay defining. If iSUB variables are involved, DECIMAL (Arithmetic Data Attribute) or if both the defined item and base identifier are arrays with the same number of dimensions and the POSITION attribute is See BINARY. not specified, correspondence defining is in effect. In all other cases, overlay defining is in effect. DEFINED (Data Attribute) In correspondence defining, the elements of the base identifier and the elements of the defined item must have the same The DEFINED attribute specifies that the attributes. The lengths need not be the variable being declared is to represent same; however, the length of the defined part or all of the same storage as that item must not be greater than the length of assigned to other data. The DEFINED the base item. The current F Compiler does attribute can be declared for element, not allow correspondence defining for array, or structure variables. arrays of structures. General format: Correspondence Defining DEFINED base-identifier {[subscript-list]|[POSITION When correspondence defining has been (decimal-integer-constant)]} specified, a reference to an element of the defined item is interpreted as a reference The "base identifier" is an unsubscripted, to the corresponding element of the base optionally qualified variable whose storage identifier. A reference to the defined is also to be represented by the variable array is interpreted as a reference to the being declared. The "subscript list" is a aggregate of all of the base elements that Section I: Attributes 329 correspond to some element of the defined Overlay Defining array. If there is no subscript list following Overlay defining specifies that the defined the base identifier, then the item is to occupy part or all of the correspondence is direct. In such a case, storage allocated to the base. In this the arrays must have the same number of way, changes to the value of either dimensions, and a reference to an element variable may be reflected in the value of of the defined item would be interpreted as the other. Overlay defining is permitted a reference to an element of the base with between the items shown in Figure I-1. the same subscripts. If a subscript list follows the base Rules for overlay defining: identifier in the DEFINED attribute specification, each subscript can be an expression and each expression may contain 1. For bit and character class data, the references to the dummy variables indicated POSITION attribute may be specified by iSUB. for the defined item. If POSITION is specified, the DEFINED attribute must In the dummy variable iSUB, i is a also be specified. POSITION need not decimal integer constant in the range 1 to necessarily follow the appearance of n, where n is the number of dimensions of DEFINED; it may precede it in the same the defined item. Thus, 1SUB represents declaration, if so desired. The subscripts of the first dimension of the general format of the POSITION defined array, 2SUB represents the second attribute is as follows: dimension of the defined array, and so forth. The subscript list following the POSITION (decimal-integer-constant) name of the base array in the DEFINED attribute specification must contain the This specifies the position, in same number of subscript expressions as relation to the start of the base, at there are dimensions of the base array. which the defined item is to begin. If this attribute is omitted, POSITION At least one reference to iSUB must (1) is assumed; that is, the defined appear in the subscript list. An array item is to begin at the first position defined by using iSUB variables in the of the base. The maximum value of the subscript list cannot be passed as an integer constant in the POSITION argument. The base array can be passed, attribute is 32,767. and an equivalent array can be defined on the corresponding parameter. 2. For bit and character class data, the extent of the defined item must not be The base element corresponding to a larger than the extent of the base. defined element is obtained by replacing Extent is calculated by summing the each iSUB in the subscript list by the lengths of the parts of the data, integer value of the ith subscript of the including all individual elements of defined element. arrays, and, in the case of the defined item, adding n - 1 (where n is The bounds of a defined array must be the position in relation to the start within the bounds of the base array. of the base). 330 Figure I-1. Permissible Items for Overlay Defining Order of Evaluation In this example of correspondence defining, B is a vector consisting of Evaluation proceeds as follows: every even element in the diagonal of the array A. In other words, B(1) corresponds to A(2,2), B(2) 1. Expressions specified in all corresponds to A(4,4), etc. attributes of the defined item (other than the DEFINED attribute) are evaluated on entry to the declaring 2. DECLARE 1 P, 2 Q CHARACTER (10), block. 2 R CHARACTER (100), PSTRING1 CHARACTER (110) 2. Subscripts in the subscript list DEFINED P; following the base identifier are evaluated when a reference to the defined item is made. In this example of overlay defining, PSTRING1 is a character string that represents the concatenation of the Examples of Defining two character strings Q and R, which are elements of the structure P. Note 1. DECLARE A(20,20), B(10) that P has the UNALIGNED attribute by DEFINED A(2*1SUB, 2*1SUB); default. Section I: Attributes 331 3. DECLARE LIST CHARACTER (40), General format: ALIST CHARACTER (10) DEFINED LIST, BUST CHARACTER (20) (bound (,bound]...) DEFINED LIST POSITION (21), CLIST CHARACTER (10) where "bound" is: DEFINED LIST POSITION (11); ((lower-bound:] upper-bound}|* In this example of overlay defining, and "upper-bound" and "lower-bound" are ALIST refers to the first ten element expressions. characters of LIST, BUST refers to the twenty-first through fortieth General rules: characters of LIST, and CLIST refers to the eleventh through twentieth 1. The number of bounds specifications characters of LIST. indicates the number of dimensions in the array unless the variable being 4. DECLARE 1 A, declared is contained in an array of 2 B FIXED, structures, in which case it inherits 2 C FLOAT, dimensions from the containing 1 X DEFINED A, structure. 2 Y FIXED, 2 Z FLOAT; 2. The bounds specification indicates the bounds as follows: In this example of overlay defining, Y refers to B and Z refers to C. a. If only the upper bound is given, the lower bound is assumed to be Note: Although the language rules specify 1. that the attributes (except for length) of the defined item must exactly match the b. The lower bound must be less than attributes of the base item, the F Compiler or equal to the upper bound. allows a programmer to make an exception to this rule, under certain circumstances. c. If asterisk notation is used, an asterisk must be used for each If attributes declared for the defined bounds specification of the array. item differ from those of the base An asterisk specifies that the identifier, the compiler notes this with a actual bounds are to be specified message at the ERROR level. If, however, in an ALLOCATE statement, if the the error code of the EXECUTE job control variable is CONTROLLED, or in a statement of the following step is high declaration of an associated enough, linkage editing and execution of argument, if the variable is a the compiled procedure can continue. For simple parameter. Thus, the example: asterisk notation can be used only for parameters and CONTROLLED DECLARE A FIXED BINARY(31), variables. B BIT (32) DEFINED A; 3. Bounds that are expressions are Compilation of this DECLARE statement would evaluated and converted to integer cause an error message to be issued by the data -- for System/360 compiler. However, execution of the implementations, BINARY(15) -- when program could be successful, and arithmetic storage is allocated for the array. operations performed upon A would result in For dummy arguments that are arrays, the change of value of the bit-string the bounds are determined at variable B. invocation of the block containing the ENTRY attribute. For simple parameters, bounds can be only optionally signed decimal integer constants or asterisks. Dimension (Array Attribute) 4. The bounds of arrays declared STATIC must be optionally signed decimal The dimension attribute specifies the integer constants. number of dimensions of an array and the bounds of each dimension. The dimension 5. The bounds of arrays declared BASED attribute either specifies the bounds must be optionally signed decimal (either the upper bound or the upper and integer constants unless the array is lower bounds) or indicates, by use of an part of a based structure and the asterisk, that the actual bounds for the REFER option is used, in which case array are to be taken from elsewhere. one adjustable bound specification is 332 allowed. (See "The REFER Option" in data set associated with a TRANSIENT file Chapter 14.) differs from those associated with DIRECT and SEQUENTIAL files in that its contents 6. The dimension attribute must are dynamic; reading a record removes it immediately follow the array name (or from the data set. Such a data set can the parenthesized list of names, if it never be created or accessed by a DIRECT or is being factored). Intervening SEQUENTIAL file. blanks are optional. The use of TRANSIENT files is almost 7. If the asterisk notation is used to totally dependent on the implementation; declare dimensions of an array of for this reason, a list of rules for the structures, all dimension declarations use of TRANSIENT with the F Compiler is within the major structure must also given below the general rules and be asterisks. assumptions. 8. Arrays are limited, for each General Format: dimension, to a lower bound of -32,768 and to an upper bound of 32,767. DIRECT|SEQUENTIAL|TRANSIENT General rules: DIRECT, SEQUENTIAL, and TRANSIENT (File 1. DIRECT files must also have the KEYED Description Attributes) attribute (which is implied by DIRECT). SEQUENTIAL files may or may not have the KEYED attribute. The DIRECT, SEQUENTIAL, and TRANSIENT TRANSIENT files must also have the attributes specify access information for KEYED attribute (for the (F) the data set associated with a file. Compiler). The DIRECT and SEQUENTIAL attributes 2. The DIRECT and SEQUENTIAL attributes specify the manner in which the records in cannot be specified for files with the a data set associated with a RECORD file STREAM attribute. are to be accessed, SEQUENTIAL implies that the records are to be accessed according to 3. The TRANSIENT attribute cannot be their sequence in the data set. (The specified with the UPDATE attribute or records in an INDEXED data set are with the STREAM attribute. processed in their logical sequence; the records in a CONSECUTIVE or REGIONAL data Assumptions: set are processed in their physical sequence.) DIRECT specifies that the 1. Default is SEQUENTIAL for RECORD records are to be accessed by use of a key; files. each record must, therefore, have a key associated with it. Either of these two 2. If a file is implicitly opened by an attributes implies the RECORD attribute. UNLOCK statement, DIRECT is assumed. The TRANSIENT attribute is designed for 3. The TRANSIENT attribute does not imply teleprocessing applications. It indicates any file attributes other than FILE. that the contents of the data set associated with the file are re-established The following rules apply specifically each time the data set is accessed. In to the use of TRANSIENT with the F effect, this means that records can be Compiler: continually added to the data set by one program during the execution of another 1. The TRANSIENT attribute can be program that continually removes records specified only for RECORD KEYED from the data set. Thus the data set can BUFFERED files with either the INPUT be considered to be a continuous queue or OUTPUT attribute. through which the records pass in transit between a message control program and a 2. The ENVIRONMENT attribute with one of message processing program. the two teleprocessing format options (G and R) must be declared for Note that DIRECT and SEQUENTIAL specify TRANSIENT files. only the current usage of the file; they do not specify physical properties of the data 3. Input can be specified only by a READ set associated with the file. The data set statement with the KEYTO option and associated with a SEQUENTIAL file may either the INTO option or the SET actually have keys recorded with the data. option. Most data sets accessed by DIRECT files are created by SEQUENTIAL files. However, a 4. Output can be specified only by a Section I: Attributes 333 WRITE statement or a LOCATE statement, 1. The ENTRY attribute with associated either of which must have the KEYFROM parameter attribute lists must be option. declared for any entry name that is invoked within the block if the 5. The EVENT option is not permitted, attributes of any argument of the since TRANSIENT files are always invocation differ from the attributes BUFFERED. of the associated parameter. This specifies that the compiler is to 6. The "data set" associated with a create the necessary dummy arguments. TRANSIENT file is in fact a queue of messages maintained automatically in 2. The ENTRY attribute must be specified main storage by a separate message for any entry name that is declared control program using the QTAM (Queued elsewhere and not recognized as such Telecommunications Access Method) within the block if any reference is facilities of the operating system. made to that entry name (such as in an The queue is always accessed argument list) unless, within the sequentially. For more details of the block: message control program, see IBM System/360 Operating System: PL/I (F) a. The entry name appears in a CALL Programmer's Guide. statement or a function reference with an argument list, either of 7. The name or title of a TRANSIENT INPUT which constitutes a contextual file must be the name of a recognized declaration of the ENTRY queue set up by the message control attribute, or program. For TRANSIENT OUTPUT files, any name can be declared, since the b. The entry name is declared to have file is re-associated for each output the RETURNS attribute (which operation with a queue determined by implies ENTRY) or the BUILTIN the terminal name, as specified in the attribute. The ENTRY attribute KEYFROM option. cannot be specified for a name that is given the BUILTIN or 8. The element expression specified in GENERIC attributes. the KEYFROM option must have as its value a recognized terminal or process 3. The ENTRY attribute must be specified queue identification. or implied for an entry name that is a parameter. 4. Expressions used for length or bounds ENTRY Attribute in an ENTRY attribute specification for non-CONTROLLED parameters are evaluated upon entry to the block to The ENTRY attribute specifies that the which the declaration of the ENTRY identifier being declared is an entry name. attribute is internal. It also is used to describe the attributes of parameters of the entry point. 5. Factoring of attributes is not permitted within parameter attribute General format: lists of an ENTRY attribute specification. ENTRY [(parameter-attribute-list [,parameter-attribute-list]...)] 6. The ENTRY attribute must appear for each entry name in a GENERIC attribute Each "parameter attribute list" describes specification. the attributes of a single parameter; the parameter name is not listed, but if the 7. The ENTRY attribute can be declared parameter is a structure, the level number for an internal entry name only within must precede the attributes for each level. the block to which the name is If a parameter is an array, the dimension internal. attribute must be the first specified for that parameter; otherwise, attributes may 8. For the F Compiler the maximum nesting appear in any order. Parameter attribute of ENTRY attributes within an ENTRY or lists must appear in the same order as the GENERIC attribute is 3. associated parameters. If the attribute of any parameter need not be described, the Assumptions: absence of the corresponding parameter attribute list must be indicated by a The ENTRY attribute can be assumed comma. either contextually or by implication, as described in rule 2. The appearance of a General rules: name as a label prefix of either a 334 PROCEDURE statement or an ENTRY statement F(block-size[,record-size]) specifies constitutes an explicit declaration of that fixed-length records with the block identifier as an entry name. No defaults size stated in bytes. If the record are applied for parameters unless size is specified (also in number of attributes and/or level numbers are bytes), it indicates that records are specified. If only a level number and/or blocked, that is, that each block the dimension attribute is specified for a contains more than one record. In parameter, FLOAT, DECIMAL, and REAL are such cases, the block size must be a assumed. simple multiple of the record size. If the record size is not specified, record size is the same as block size. V(max-block-size[,max-record-size]) specifies variable-length records that can be contained within the stated ENVIRONMENT (File Description Attribute) maximum block size. If the maximum record size is not specified, each block contains only one record. If The ENVIRONMENT attribute is an the maximum record size is specified, implementation-defined attribute that each block will contain as many specifies various file characteristics that complete records as it can are not part of the PL/I language. accommodate. General format: -size]){VS|VBS}(max-block-size[,max-record specifies variable-length records that may exceed the maximum ENVIRONMENT (option-list) block size. If necessary, a record is segmented and continued in consecutive blocks. If VS is specified, each Each option in the "option list" is block contains only one record or separated by one or more blanks. The segment; if VBS is specified, each options themselves cannot contain blanks. block contains as many records and/or The option list is defined individually for segments as it can accommodate. The each implementation of PL/I. For the F specification of a maximum record size Compiler, it has the following format: does not affect blocking. Four bytes of control information per ([record-format] [buffer-allocation] block, plus four bytes per record or [data-set-organization] segment of record, are included [volume-disposition] automatically by the system for [printer-punch-control] variable-length records. These [data-interchange] control bytes must be included in the [data-management-optimization] count of maximum block size and [key-classification] [track-overflow] maximum record size. [asynchronous-operations-limit]}| teleprocessing-format U(max-block-size) specifies records of undefined length up to the maximum The options may appear in any order. stated. No control information is Note that "teleprocessing format" can only included, and the record size is the appear alone. same as the block size. General rules: Neither record size nor block size can exceed 32,760 bytes. 1. The ENVIRONMENT attribute can be specified only in a DECLARE statement. 3. "Buffer allocation" specifies the It cannot be specified as an option of number of buffers to be allocated for an OPEN statement. the file; the specification is as follows: 2. The "record format" describes the format of the records to be written or BUFFERS(n) retrieved. The record format specification is as follows: The number (n), which is specified by a decimal integer constant, must not exceed F(block-size[,record-size]) 255. For BUFFERED files, one or two V(max-block-size[,max-record-size]) buffers are automatically allocated, {VS|VBS} (max-block-size depending on the access method, unless a [,max-record-size]) greater number is indicated in the U(max-block-size) BUFFERS(n) option. For UNBUFFERED files Section I: Attributes 335 that require hidden buffers, one buffer is 5. The "volume-disposition" specifies the automatically allocated. If not specified action to be taken when the end of a in the ENVIRONMENT option, the buffer count magnetic tape volume is reached during can be specified in the BUFNO subparameter access to a data set or when a data of the associated DD statement. set on a magnetic tape volume is closed normally or abnormally. Volume disposition is specified by one of the 4. The "data set organization" describes following ENVIRONMENT attribute some physical characteristics of the options: data set and how records are to be written or retrieved. Data set LEAVE organization is specified by one of the following: REWIND CONSECUTIVE LEAVE specifies that no repositioning of the volume is to take place if the INDEXED end of the volume has been reached. The channel can then be freed. If a REGIONAL(1) data set is closed normally or abnormally, LEAVE specifies that the REGIONAL(2) tape is to be positioned at the end of the data set or at the beginning of REGIONAL(3) the data set if a BACKWARDS file is being used. If the data set continues CONSECUTIVE describes a data set on another volume, the tape is consisting of unkeyed records that are positioned at the end of the current to be written or retrieved in a volume or at the beginning if a physically sequential order. This BACKWARDS file is being used. The organization is assumed if none is channel remains busy during the specified. Note the difference positioning operation. between CONSECUTIVE and SEQUENTIAL. CONSECUTIVE specifies physical REWIND allows the end-of-volume or characteristics of the data set; data-set-closure tape action to be SEQUENTIAL specifies how a file is to controlled by the DISP field of the be used to process the records in the associated DD statement. If data set. A file declared SEQUENTIAL DISP=(status,DELETE) is specified in can have any of the five data set the DD statement, the tape is rewound organization options. but not unloaded. If DISP=(status,KEEP|CATLG|UNCATLG) is INDEXED describes a data set that specified, the tape is rewound and consists of keyed records, any one of unloaded. If DISP=(status,PASS) is which can be located by means of specified, the tape is wound on to the several levels of indexes. end of the data set, unless a BACKWARDS file is being used, in which REGIONAL (1) describes a data set that case the tape is repositioned at the consists of records without recorded beginning of the data set. When keys but which can be located by means DISP=(status,PASS) is specified, the of a source key that specifies a channel is kept busy when positioning; relative record position within the in the other two cases the channel is data set. freed when positioning. REGIONAL (2) describes a data set that 6. The "printer/punch control" specifies consists of records with recorded that the first character of a record keys. A source key specifies the is to be interpreted as a control relative record and the recorded key. character. The control options are: A search for the record with the specified recorded key starts at the CTLASA, which specifies that the first beginning of the track on which the character of a record is to be relative record resides. interpreted as an ASA standard control character, and REGIONAL (3) describes a data set that consists of records with recorded CTL360, which specifies that the first keys. A source key specifies the character of a record is to be relative track and the recorded key. interpreted as an IBM System/360 The search is similar to that for machine code control character. REGIONAL(2), but starts at the beginning of the specified relative 7. The "data interchange" option is track. specified as follows: 336 COBOL members of the class 'ABC'; and the three recorded keys can be considered It specifies that the file will to be unique members of the classes contain structures mapped according to 'ABCD', 'ABCE', and 'ABDF', the COBOL (F) algorithm. This type of respectively. file can be used only with READ INTO and WRITE FROM statements. The GENKEY option allows the programmer to start sequential reading 8. The 'data management optimization" or updating of an INDEXED data set increases program efficiency, in from the first non-dummy record that certain circumstances, when DIRECT has a key in a particular class; the files are used to access INDEXED data class is identified by the inclusion sets. The data management of its generic key in the KEY option optimization options are: of a READ statement. Subsequent records can be read by READ statements INDEXAREA[(index-area-size)] without the KEY option. No indication is given when the end of a key class NOWRITE is reached. INDEXAREA[(index-area-size)] improves If the data set contains no records the input/output speed of a DIRECT with keys in the specified class, or INPUT or DIRECT UPDATE file with if all the records with keys in the INDEXED data set organization, by specified class are dummy records, the having the highest level of index KEY condition is raised and the data placed in main storage. The "index set is positioned to read the first area size," when specified, must be a record. decimal integer constant whose value lies within the range zero through The GENKEY option affects the 32,767. If an index area size is not execution of a READ statement that specified, the highest level index is supplies a source key shorter than the moved unconditionally into main key length specified in the KEYLEN storage. If an index area size is subparameter of the DD statement that specified, the highest level index is defines the data set. GENKEY causes held in main storage, provided that the key to be interpreted as a generic its size does not exceed that key, and the data set is positioned to specified. If the specified size is the first non-dummy record in the data less than zero or greater than 32,767, set whose key begins with the source the compiler issues a warning message key. If GENKEY is not specified, a and ignores the parameter of the short source key is padded on the option. right with blanks to the specified key length, and the data set is positioned NOWRITE can be specified only for to the record that has this padded DIRECT UPDATE files with INDEXED data key(if such a record exists). set organization. It informs the compiler that no records are to be The use of the GENKEY option does not added to the data set and that data affect the result of supplying a management modules concerned solely source key whose length is greater with adding records are not required; than or equal to the specified key it thus allows the size of the length. The source key, truncated on compiled program to be reduced. the right if necessary, identifies a specific record (whose key can be 9. The "key classification" option GENKEY considered to be the only member of (generic key), applies only to INDEXED its class). data sets. It enables the programmer to classify keys recorded in a data 10. The "track overflow" option indicates set and to use a SEQUENTIAL KEYED that records transmitted to a INPUT or SEQUENTIAL KEYED UPDATE file direct-access storage device can be to access records according to their written on overflow tracks if key classes. necessary. It is specified as follows: A generic key is a character string that identifies a class of keys: all TRKOFL keys that begin with the string are members of that class. For example, 11. The "asynchronous operations limit" the recorded keys 'ABCD', 'ABCE', and specifies the number of incomplete 'ABDF' are all members of the classes input/output operations that are identified by the generic keys 'A' and allowed to exist for the file at one 'AB', and the first two are also time (see "The EVENT Option" in Section I: Attributes 337 Chapter 10, "Record-Oriented that require hidden buffers. NCP(1) is Transmission"). The specification is assumed unless otherwise specified. as follows: NCP(decimal-integer-constant) EVENT (Program Control Data Attribute) The decimal integer constant must have a value in the range 1 through 99; The EVENT attribute specifies that the otherwise, 1 is assumed and an error associated identifier is used as an event message is issued. name. Event names are used to investigate the current state of tasks or of 12. The "teleprocessing format" option is asynchronous input/output operations. They the equivalent, for teleprocessing can also be used as program switches. applications, of "record format." It must be specified for TRANSIENT files; General format: it cannot be specified for DIRECT, SEQUENTIAL, or STREAM files; and it EVENT cannot appear in conjunction with any other option of the ENVIRONMENT General rules: attribute. The teleprocessing format specification is as follows: 1. An identifier may be explicitly declared with the EVENT attribute in a G(maximum-message-size) DECLARE statement. It may be R(maximum-record-size) contextually declared by its appearance in an EVENT option of a The maximum message size and maximum CALL statement, in a WAIT statement, record size are specified by decimal in a DISPLAY statement, or in various integer constants. input/output statements (see Chapter 10, "Record-Oriented Transmission," G(maximum-message-size) specifies that and Chapter 15, "Multitasking.") execution of an input/output statement will result in the movement of a 2. Event names may also have the complete message to or from a message following attributes: queue. Dimension R(maximum-record-size) specifies that execution of an input-output statement Scope (the default is INTERNAL) will result in the movement of one record of a message to or from a Storage class (the default is message queue AUTOMATIC) For both G and R formats, a buffer is DEFINED (event names may only be always used, and its length will defined on other event names) depend on the value of the specified decimal integer constant. The value 3. An event variable has two separate that must be specified will depend on values: the message format as set up by the separate message control program (see a. A single bit which reflects the "Teleprocessing" in Chapter 10, completion value of the variable. "Record-Oriented Transmission"). The '1'B indicates complete, '0'B PL/I programmer must have details of indicates incomplete. the message format in order to write a message processing program. In b. A fixed-point value of default general, the messages and records are precision ((15,0) for the F treated as if they were V-format Compiler) which reflects the records. status value of the variable. A zero value indicates normal, Assumptions: nonzero indicates abnormal status. (The following assumptions do not apply The values of the event variable can when a teleprocessing format option is be separately returned by use of the specified.) CONSECUTIVE data set COMPLETION and STATUS built-in organization is assumed unless stated functions. The COMPLETION function otherwise. Tape reels are rewound unless returns a bit-string value the LEAVE option is specified. If the corresponding to the completion value BUFFERS(n) option is not specified, two of the variable; STATUS returns a buffers are allocated for BUFFERED files, fixed binary value corresponding to and one is allocated for UNBUFFERED files the status value. 338 Assignment of one event variable to area) by means of an input/output another causes both the completion and statement. status values to be assigned. Conversion between event variables and 9. On execution of a CALL statement with any other data type is not possible. the EVENT option, the event variable, if inactive, is set to zero status value and to incomplete. The sequence 4. Event variables may be elements of an of these two assignments is array. Arrays containing event uninterruptable, and is completed variables may take part in assignment, before control passes to the named provided that this would not require entry point. On termination of the conversion to or from event data. task initiated by the CALL statement, the event variable is set complete and 5. The values of the event variable can is no longer active. If the task be set by one of the following means: termination is not due to RETURN or END in the task, then theevent a. Use of the COMPLETION variable status is set to 1, unless it pseudo-variable, to set the is already nonzero. The sequence of completion value. the two assignments to the event variable values is uninterruptable. b. Use of the STATUS pseudo-variable, to set the status value. 10. On execution of an input/output statement with the EVENT option, the c. Event variable assignment. event variable, if inactive, is set to zero status value and to incomplete. d. By a statement with the EVENT The sequence of these two assignments option. is uninterruptable and is completed before any transmission is initiated e. By a WAIT statement for an event but after any action associated with variable associated with an an implicit opening is completed. An input/output event. input/output event variable will not be set complete until either the f. By the termination of a task with termination of the task that initiated which the event variable is the event or the execution, by that associated. task, of a WAIT statement naming the associated event variable. The WAIT g. By closing a file on which an operation delays execution of this input/output operation with an task until any transmission associated event option is in progress. with the event is terminated. If no input/output conditions are to be 6. On allocation of an event variable, raised for the operation, the event its status and completion values are variable is set complete and is no undefined. longer active. If any input/output conditions are to be raised, the event 7. An event variable may be associated variable is set to have a status value with an event, that is, a task or an of 1 and the relevant conditions are input/output operation, by means of raised. On normal return from the the EVENT option on a statement. The last on-unit entered as a result of variable remains associated with the these conditions, or on abnormal event until the event is completed. return from one of the on-units, the For a task the event is completed when event variable is set complete and is the task is terminated because of a no longer active. RETURN, END or EXIT; for an input/output event, the event is 11. Event variables cannot be unaligned. completed during the execution of the WAIT for the associated event. During this period the event variable is said to be active. It is an error to EXCLUSIVE (File Description Attribute) associate an active event variable with another event, or to modify the completion value of an active event The EXCLUSIVE attribute specifies that variable by event variable assignment records in a data set associated with a or by use of the COMPLETION DIRECT UPDATE file may be locked by an pseudo-variable. accessing task to prevent other tasks from interfering with an operation. The section 8. It is an error to assign to an active entitled "The EXCLUSIVE Attribute," in event variable (including an event Chapter 15, "Multitasking," contains a variable in an array, structure, or table showing the effects of various Section I: Attributes 339 operations on EXCLUSIVE files and the EXTERNAL and INTERNAL (Scope Attributes) records contained in the associated data sets. The EXTERNAL and INTERNAL attributes specify the scope of a name. INTERNAL General format: specifies that the name can be known only in the declaring block and its contained blocks. EXTERNAL specifies that the name EXCLUSIVE may be known in other blocks containing an external declaration of the same name. General rules: General format: EXTERNAL|INTERNAL 1. The EXCLUSIVE attribute can be applied to RECORD KEYED DIRECT UPDATE files General rules: only. 1. When a major structure name is declared EXTERNAL in more than one 2. A READ statement referring to an block, the attributes of the structure EXCLUSIVE file has the effect of members must be the same in each case, locking the record that is read, although the corresponding member unless the READ statement has the names need not be identical. NOLOCK option, or unless the record has already been locked by another 2. Members of structures always have the task; in the latter case, the task INTERNAL attribute and cannot be executing the READ statement will wait declared with any scope attribute. until the record is unlocked before However, a reference to a member of an proceeding. external structure, using the member name known to the block containing the reference, is effectively a reference 3. A DELETE or REWRITE statement to that member in all blocks in which referring to a locked record will the external name is known, regardless automatically unlock the record at the of whether the corresponding member end of the DELETE or REWRITE names are identical. operation; if the record has been locked by another task, the task Assumptions: executing the DELETE or REWRITE statement will wait until the record INTERNAL is assumed for entry names of is unlocked. While a DELETE or internal procedures and for variables with REWRITE operation is taking place, the any storage class. EXTERNAL is assumed for record is always locked. file names and entry names of external procedures. Programmer-defined condition 4. Automatic unlocking takes place at the names are assumed to be EXTERNAL. end of the operation, on normal return from any on-units entered because of the operation (that is, at the corresponding WAIT statement when the EVENT option has been specified). FILE (File Description Attribute) 5. A locked record can be explicitly unlocked by the task that locked it, The FILE attribute specifies that the by means of the UNLOCK statement. identifier being declared is a file name. 6. Closing an EXCLUSIVE file unlocks all General format: the records locked by the file. FILE 7. When a task is terminated, all records locked by that task are unlocked. Assumptions: Assumptions: The FILE attribute can be implied by any of the other file description attributes. 1. If a file is implicitly opened by the In addition, an identifier may be UNLOCK statement, it is given the contextually declared with the FILE EXCLUSIVE attribute. attribute through its appearance in the FILE option of any input/output statement, 2. EXCLUSIVE implies RECORD, KEYED, or in an ON statement for any input/output DIRECT, and UPDATE. condition. 340 FIXED and FLOAT (Arithmetic Data for the name being given the GENERIC Attributes) attribute. 2. Each "entry name declaration" The FIXED and FLOAT attributes specify the following the GENERIC attribute scale of the arithmetic variable being corresponds to one member of the declared. FIXED specifies that the family, and has the form: variable is to represent fixed-point data items. FLOAT specifies that the variable entry-name attribute-list is to represent floating-point data items. General format: 3. The "attribute list" of each entry name declaration specifies attributes FIXED|FLOAT of the entry name. It must include the ENTRY attribute. It may General rule: optionally have INTERNAL, EXTERNAL, and RETURNS attributes. No entry name The FIXED and FLOAT attributes cannot be declaration can have the GENERIC specified with the PICTURE attribute. attribute, nor can it have the BUILTIN attribute. Assumptions: Undeclared identifiers (or identifiers 4. Each entry name declaration must declared only with one or more of the specify attributes or level numbers dimension, PACKED, ALIGNED, scope, and for each parameter. An ENTRY storage class attributes) are assumed to be declaration within a GENERIC arithmetic variables with assigned declaration is exactly the same as any attributes depending upon the initial other ENTRY declaration. Therefore, letter. For identifiers beginning with any no other entry attribute declaration letter I through N, the default attributes for the same identifier can appear in are REAL FIXED BINARY (15,0). For the same block if the entry name identifiers beginning with any other appears in a GENERIC attribute alphabetic character, the default specification. attributes are REAL FLOAT DECIMAL (6). If BINARY or DECIMAL and/or REAL or COMPLEX are specified, FLOAT is assumed. The 5. When a generic name is referred to, default precisions are those defined for the attributes of the arguments must System/360 implementations. match exactly the list following the entry name declaration of one and only one member of the family. The reference is then interpreted as a FLOAT (Arithmetic Data Attribute) reference to that member. Thus, the selection of a particular entry name is based upon the arguments of the See FIXED. reference to the generic name. Note that no conversion is done for arguments passed to generic functions. Consequently, the precision of a GENERIC (Entry Name Attribute) constant or any other expression must match the precision of a parameter. The GENERIC attribute is used to define a name as a family of entry names, each of 6. The selection of a particular entry which is referred to by the name being name is first based on the number of declared. When the generic name is arguments in the reference to the referred to, the proper entry name is name. The following attributes are selected, based upon the arguments then considered in choice of generic specified for the generic name in the members: procedure reference. Base General format: Scale GENERIC (entry-name-declaration [,entry-name-declaration]...) Mode General rules: Precision 1. No other attributes can be specified PICTURE Section I: Attributes 341 LABEL (but not label list) INITIAL (Data Attribute) Number of dimensions (but not bounds) The INITIAL attribute has two forms. The first specifies an initial constant value CHARACTER (but not length) to be assigned to a data item when storage is allocated to it. The second form BIT (but not length) specifies that, through the CALL option, a procedure is to be invoked to perform VARYING initialization at allocation. ENTRY (but not parameter description or other attributes of General format: entry names) 1. INITIAL (item [,item]...) FILE (but no other FILE attributes) 2. INITIAL CALL entry-name ALIGNED [argument-list] UNALIGNED General rule: AREA (but not size) The INITIAL attribute cannot be given for entry names, file names, defined data, OFFSET (but not specified area structures, parameters, or based variables. variable) Rules for form 1: POINTER 1. In this discussion, the term TASK "constant" denotes one of the following: EVENT [+|-] arithmetic-constant 7. Generic entry names (as opposed to references) may be specified as character-string-constant arguments to non-generic procedures if the invoked entry name is explicitly bit-string-constant declared with the ENTRY attribute. This ENTRY attribute must specify that [+|-]real-constant{+|-}imaginary-constant the appropriate parameter is an entry name and must specify, by means of a further ENTRY attribute, the 2. Only one constant value can be attributes of all its parameters. specified for an element variable; This enables a choice to be made of more than one can be specified for an which family member is to be passed. array variable. A structure variable can be initialized only by separate 8. There is a limitation on the number of initialization of its elementary family members and arguments which may names, whether they are element or be associated with a GENERIC entry array variables. name. The value given by evaluating the following formula must not exceed 3. Constant values specified for an array 700: are assigned to successive elements of the array in row-major order (final subscript varying most rapidly). 4. If too many constant values are specified for an array, excess ones are ignored; if not enough are specified, the remainder of the array is not initialized. 5. Each item in the list can be a constant, an asterisk denoting no initialization for a particular element, or an iteration specification. 9. For the F Compiler the maximum nesting of ENTRY attributes within a GENERIC 6. The iteration specification has one of attribute is 3. the following general forms: 342 (iteration-factor) constant 12. An alternate method of initialization is available for elements of arrays of non-STATIC statement label variables: (iteration-factor)(item[,item]...) an element of a label array can appear as a statement prefix, provided that (iteration-factor) * all subscripts are optionally signed decimal integer constants. The effect The "iteration factor" specifies the of this appearance is the number of times the constant, or item initialization of that array element list, is to be repeated in the to a value that is a constructed label initialization of elements of an constant for the statement prefixed array. If a constant follows the with the subscripted reference. This iteration factor, then the specified statement must be internal to the number of elements are to be block containing the declaration of initialized with that value. If a the array. Only one form of list of items follows the iteration initialization can be used for a given factor, then the list is to be label array. If CHECK is specified repeated the specified number of for a label array and the elements of times, with each item initializing an the label array are initialized by a element of the array. If an asterisk label prefix, the CHECK condition is follows the iteration factor, then the not raised at initialization. specified number of elements are to be skipped in the initialization 13. For the F Compiler, character-string operation. or bit-string data having the STATIC attribute cannot he initialized with 7. The iteration factor can be an element complex values. expression, except for STATIC data, in which case it must be an unsigned 14. This form of the INITIAL attribute decimal integer constant. When cannot be used in the declaration of storage is allocated for the array, locator or area variables. the expression is evaluated to give an integer that specifies the number of 15. Initialization of LABEL variables on iterations. structures with the LIKE attribute requires careful handling particularly B. A negative or zero iteration factor as the implementation does not provide causes no initialization. the result specified by the language. A structure A is declared, using the 9. For initialization of a string array, LIKE attribute, to be identical to a if only one parenthesized element structure B. Structure B contains a expression precedes the string initial LABEL variable that is initialized, value, the expression is interpreted using the INITIAL attribute, to the to be a string repetition factor for value of a LABEL constant. The the string; that is, it is interpreted initial value of the corresponding as a part of the specification of the LABEL variable in A is the initial value for a single element of the value of the LABEL constant known in array. Consequently, for an the block containing the declaration expression to cause initialization of of B, not A. more than one element of a string array, both the string repetition For example: factor and the iteration factor must be explicitly stated, even if the DCL 1 B, string repetition factor is (1). For 2 L LABEL INITIAL (L1); example, consider the following: ((2) 'A') is equivalent to ('AA') (for a single element) L1:• .; /*B.L = Ll*/ ((2)(1)'A') is equivalent to ('A', 'A') (for two elements) BEGIN;• 10. Iterations may be nested. DCL A LIKE B; 11. Label constants given as initial ▪ /*A.L ISL1: GIVEN .; THE VALUE OF values for label variables must be L1 IN STRUCTURE B*/ known within the block in which the label variable declarations occur. STATIC label variables cannot have the INITIAL attribute. END; Section I: Attributes 343 Rules for form 2: In the last example, transfer is made to a particular element of the array Z by 1. The "entry name" and "argument list" giving I a value of 1,2, or 3. passed must satisfy the condition stated for prologues as discussed in Part I, Chapter 6, "Blocks and Flow of Control." 2. Form 2 cannot be used to initialize STATIC data. INPUT, OUTPUT, and UPDATE (File Description Attributes) The INPUT, OUTPUT, and UPDATE attributes indicate the function of the file. INPUT specifies that data is to be transmitted from external storage to the program. OUTPUT specifies that data is to be transmitted from the program to external storage. UPDATE specifies that the data can be transmitted in either direction; that is, the file is both an input and an output file. General format: INPUT|OUTPUT|UPDATE General rules: 1. A file with the INPUT attribute cannot have the PRINT attribute. 2. A file with the OUTPUT attribute cannot have the BACKWARDS attribute. 3. A file with the UPDATE attribute cannot have the STREAM, BACKWARDS, or PRINT attributes. A declaration of UPDATE for a SEQUENTIAL file indicates the update-in-place mode: a record can be updated only by a READ statement followed by a corresponding REWRITE statement. Assumptions: Default is INPUT. The PRINT attribute implies OUTPUT. The EXCLUSIVE attribute implies UPDATE. The following assumptions are made when a file is implicitly opened by an input/output statement: Example c results in the following: each of the first 920 elements of A is set to 0, WRITE, LOCATE, PUT OUTPUT the next 80 elements consist of 20 repetitions of the sequence 5,5,5,9. READ, GET INPUT In Example d, INITIALIZE is the name of DELETE, REWRITE, UNLOCK UPDATE a procedure that sets the initial values of elements in TABLE. X and Y are arguments passed to INITIALIZE. In Example e, B and C inherit a INTERNAL (Scope Attribute) dimension of (8) but, whereas only the first element of B is initialized, all the elements of C are initialized. See EXTERNAL. 344 IRREDUCIBLE and REDUCIBLE LABEL (Program Control Data Attribute) The attributes REDUCIBLE and IRREDUCIBLE The LABEL attribute specifies that the are optimization attributes applied to identifier being declared is a label ENTRY declarations. A call to an ENTRY variable and is to have statement labels as which is declared as REDUCIBLE will be values. To aid in optimization of the optimized. A procedure is completely object program, the attribute specification IRREDUCIBLE if it, or any block activated may also include the values that the name by it, does any of the following: can have during execution of the program. • Returns different function values for General format: identical argument values LABEL [(statement-label-constant [,statement-label-constant]...)] • Maintains any kind of history • Performs input or output operations General rules: • Returns control from the procedure by 1. If a list of statement label constants means of a GO TO statement is given, the variable can have as values only members of the list. The Assumptions: label constants in the list must be known in the block containing the Default is IRREDUCIBLE declaration. IRREDUCIBLE and REDUCIBLE attributes 2. The number of statement label both imply the ENTRY attribute. constants specified by the LABEL attribute is limited to 125 in any particular label list. 3. If the variable is a parameter, its KEYED (File Description Attribute) value can be any statement label variable or constant passed as an argument. If the ar gument is a label The KEYED attribute specifies that the variable, the value of the label options KEY, KEYTO, and KEYFROM may be used parameter can be any value permitted to access records, in statements that refer for the label variable that is passed. to the file. These options indicate that keys are involved in accessing the records. 4. An entry name cannot be a value of a label variable. General format: 5. The parenthesized list of statement KEYED label constants can be used in a LABEL attribute specification for a label General rules: array. A subscripted label specifying an element of a label array can appear 1. A KEYED file cannot have the as a statement label prefix, if the attributes STREAM or PRINT. label variable is not STATIC, but it cannot appear in an END statement 2. The KEYED attribute can be specified after the keyword END. For further only for RECORD files associated with information, see general rule 12 in data sets on direct-access devices, or the discussion of the INITIAL for TRANSIENT files. attribute. 3. The KEYED attribute must be specified 6. The INITIAL attribute cannot be for every file with which any of the specified for STATIC label variables. options KEY, KEYTO, and KEYFROM is used. It need not be specified if 7. Labels cannot be unaligned. none of the options are to be used, even though the corresponding data set may actually contain recorded keys. Assumption: Length (String Attribute) The DIRECT and EXCLUSIVE attributes imply KEYED. See BIT. Section I: Attributes 345 LIKE (Structure Attribute) the name declared with the LIKE attribute. The LIKE attribute specifies that the name 5. Attributes of the "structure variable" being declared is a structure variable with itself do not carry over to the the same structuring as that for the name created structure. For example, following the attribute keyword LIKE. storage class attributes do not carry Substructure names, elementary names, and over. If the "structure variable" attributes for substructure names and following the keyword LIKE represents elementary names are to be identical. an array of structures, its dimension attribute is not carried over. Attributes of substructure names and General format: elementary names, however, are carried over; contained dimension and length LIKE structure-variable attributes are recomputed. An exception is that this does not apply General rules: to the INITIAL attribute for any elements of a label array that has 1. The "structure variable" can be a been initialized by prefixing to a major structure name or a minor statement. structure name. It can be a qualified name, but it cannot be subscripted. 6. If a direct application of the description to the structure declared 2. The "structure variable" must be known LIKE would cause an incorrect in the block containing the LIKE continuity of level numbers (for attribute specification. The example, if a minor structure at level structure names in all LIKE attributes 3 were declared LIKE a major structure are associated with declared at level 1) the level numbers are structures before any LIKE attributes modified by a constant before are expanded. For example: application. 7. The LIKE attribute is expanded before the ALIGNED and UNALIGNED attributes are applied to the contained elements of a structure. OFFSET and POINTER (Program Control Data Attributes) The OFFSET and POINTER attributes describe locator variables. A pointer variable can These declarations result in the be used in a based variable reference to following: identify a particular allocation of the based variable. Offset variables identify 1 A LIKE D is expanded to give: a location relative to the start of an area; pointer variables identify any 1 A, 2 C, 3 G, 3 H location, including those within areas. 1 B LIKE A.0 is expanded to give: General format: 1 B, 3 E, 3 F POINTER|OFFSET (area-variable) 3. Neither the "structure variable" nor General rules: any of its substructures can be declared with the LIKE attribute, nor 1. A pointer variable can be explicitly may the "structure variable" have been declared in a DECLARE statement, or it completed by the LIKE attribute. can be contextually declared by its appearance as a pointer qualifier, by 4. Neither additional substructures nor its appearance in a BASED attribute, elementary names can be added to the or by its appearance in a SET option. created structure; any level number that immediately follows the 2. An offset variable must be explicitly "structure variable" in the LIKE declared. attribute specification in a DECLARE statement must be algebraically equal 3. The value of a pointer variable can be to or less than the level number of set in any of the following ways: 346 a. With the SET option of a READ OUTPUT (File Description Attribute) statement; See INPUT. t. By a LOCATE statement; c. By an ALLOCATE statement; PICTURE (Data Attribute) d. By assignment of the value of The PICTURE attribute is used to define the another locator variable, or a internal and external formats of locator value returned by a character-string and numeric character data user-defined function; and to specify the editing of data. Numeric character data is data having an arithmetic value but stored internally in e. By assignment of an ADDR or NULL character form. Numeric character data built-in function value. must be converted to coded arithmetic before arithmetic operations can be 4. The value of an offset variable can be performed. set only by assignment of the value of another locator variable or the value The picture characters are described in of the NULLO built-in function. Section D, "Picture Specification Characters." 5. Locator variables cannot be operands of any operators other than the General format: comparison operators = and ¬ =. PICTURE 6. Locator data cannot be converted to any other data type, but pointer can 'character-picture-specification' be converted to offset, and vice versa. 'numeric-picture-specification' 7. A locator value can be assigned only A "picture specification," either character to a locator variable. When an offset or numeric, is composed of a string of value is assigned to an offset picture characters enclosed in single variable, the area variables named in quotation marks. An individual picture the OFFSET attributes are ignored. character may be preceded by a repetition factor, which is a decimal integer 8. Locator data cannot be transmitted constant, n, enclosed in parentheses, to using STREAM input/output. indicate repetition of the character n times. If n is zero, the character is 9. Only the INITIAL CALL form of the ignored. Picture characters are considered INITIAL attribute is allowed in to be grouped into fields, some of which locator declarations. contain subfields. 10. Offset variables cannot be used to General rules: qualify a based reference. 1. The "character picture specification" 11. For the F Compiler, the area variable is used to describe a character-string named in an OFFSET attribute must be data item. Three characters may be of based storage class. used: A, indicating that the associated position in the data item 12. Pointer variables and offset variables may contain any alphabetic character cannot be unaligned. or a blank; X, indicating that the associated postion may contain any Assumption: character; and 9, indicating that the associated position may contain any The variable named in the OFFSET decimal digit or a blank. A character attribute is contextually declared to have picture specification must include at the AREA attribute, but its storage class least one A or X. Each character will be automatic; hence, it will not picture specification is a single conform to general rule 11, above. For the field with no contained subfields. F Compiler, therefore, an offset declaration without an accompanying Example: explicit area declaration will result in an error. (See also "AREA (Program Control DECLARE ORDER# PICTURE Data Attribute)," in this section.) 'AA(3)9X99X(4)9'; Section I: Attributes 347 This declaration specifies that values suppression characters, editing of ORDER# are to be character strings characters, and sign characters may be of length 13. The string consists of included in a numeric picture two letters, three digits, any specification to indicate editing. character, two digits, any character, Editing characters are not a part of and four digits. For example, the the arithmetic value of a numeric character string 'G 42-63-0024' would character data item, but they are a fit this description. part of its character-string value. Repetition factors are allowed in Editing and suppression characters are numeric specifications. not allowed in character picture specifications. Each picture specification character must represent 3. A numeric character data item can have an actual character in the data item. only a decimal base. Its scale and precision are specified by the picture 2. The "numeric picture specification" is characters. The PICTURE attribute used to describe a character item that cannot be specified in combination represents either an arithmetic value with base, scale, or precision or a character-string value, depending attributes. If the mode of the upon its use. A numeric picture numeric character data is COMPLEX, specification can consist of one or however, the COMPLEX attribute must be more fields, some of which can be explicitly stated. divided into subfields. A single field is used to describe a 4. The following paragraphs indicate the fixed-point number or the mantissa of combinations of picture characters for a floating-point number. Either may different arithmetic data formats. be divided into two subfields, one describing the integer portion, the other describing the fractional a. Real decimal fixed-point items are portion. For floating-point numbers, described in the following general a second field is required to describe form: the exponent; it cannot be divided into subfields. A second field may PICTURE '19]...[V][9]... optionally be used with fixed-point [F([+|-] integer)]' numbers to indicate a scaling factor. Four basic picture characters can be used in a numeric picture The optional field of the picture specification: specification, beginning with the letter F together with a 9 indicating any decimal digit parenthesized, optionally signed decimal integer constant, is a ✓ indicating the assumed location of scaling factor that indicates the a decimal point. It does not location of an assumed decimal specify an actual character in the point if that location is outside character-string value of the data the actual data item. The scaling item. The V also indicates the end factor has an effect similar to of a subfield of a picture the exponent of a floating-point specification. number; it indicates that the assumed decimal point is "integer" K indicating, for floating-point data places to the right (or left, if items, that the exponent should be negative) of the position assumed to begin at the position otherwise indicated. associated with the picture character following the K. It does Sign, editing, and zero not specify an actual character in suppression picture characters can the character-string value of the be included in a fixed-point data item, either an E or a sign. specification. The V cannot The K delimits the two fields of appear more than once in a the specification. specification, although it may be used in combination with the E indicating, for floating-point data decimal point (.) or comma (,) items, that the associated position editing characters, which cause will contain the letter E to insertion of a period or comma. indicate the beginning of the If no V is included, the decimal exponent. The E also delimits the point is assumed to be to the two fields. right of the rightmost digit. Only one sign indication can be In addition to these characters, zero included in the first field (the 348 actual sign of the integer in a 5. The precision of a numeric character scaling factor is allowed variable is dependent upon the number additionally). The specification of digit positions, actual and must include at least one digit conditional. Digit positions can be position. specified by the following characters: 9 which is an actual digit character Example: Z DECLARE A PICTURE '999V99'; * which are conditional digit This specification describes characters specifying zero numeric character items of five suppression digits, two of which are assumed Y to be fractional digits. T b. Real decimal floating-point items I which are digit characters are described by the following specifying an overpunch general form: R PICTURE '[9]...[V][9]...{E|K}9[9]' + which are conditional digit Both the mantissa field and the drifting characters exponent field must each contain at least one digit position. The exponent field can contain no more than two digits, since System/360 implementations allow only two Each but the first conditional digit digits in the exponent field of a drifting character in a drifting decimal floating-point number. If string specifies a digit position. A arithmetic data items are to be conditional digit drifting character assigned to the described used alone does not specify a digit variable, the exponent field must position. contain both of the allowed digit specification characters, or the second digit of the exponent field will be lost and the SIZE Precision of a fixed-point variable is condition will be raised. (p,q), where p is the number of digit positions in the picture specification Sign, editing, and zero and g is the number of digit positions suppression picture characters can following V. Precision of a be included in a floating-point floating-point variable is (p), where specification. One sign p is the number of digit positions indication is allowed for each preceding the E or K. Indicated field. Only one V is allowed, and static editing characters or insertion it can appear in the first field characters do not participate in the only. As with fixed-point specification of precision, but they specifications, the V may appear must be counted in the number of in combination with the decimal characters if the data item is written point editing character (as .V or as output or assigned internally to a V.). character string. c. Complex numeric character data is described using the general form: 6. A variable representing sterling data items can be specified by using a PICTURE 'real-picture' COMPLEX numeric picture specification that consists of three fields, one each for The "real picture" is a pounds, shillings, and pence. The specification for either a decimal pence field may be divided into two fixed-point or a decimal subfields. Data so described is floating-point data item. The stored in character format as three single picture specification contiguous numbers corresponding to describes both parts of a complex each of the three fields. If any number. arithmetic operations are specified for the variable, its value is Section I: Attributes 349 converted to coded fixed-point decimal decimal integer constant and "scale factor" representing the value in pence. is an optionally signed decimal integer Sterling picture specifications have constant. The precision attribute the following form: specification is often represented, for brevity, as (p,q), where p represents the PICTURE "number of digits" and g represents the "scale factor." 'G [editing-character-1]... M pounds-field General rules: M [separator-1]... shillings-field 1. The precision attribute must immediately follow, with or without M [separator-2]... intervening blanks, the scale (FIXED pence-field or FLOAT), base (DECIMAL or BINARY), or mode (REAL or COMPLEX) attribute at [editing-character-2]-' the same factoring level. Picture specification characters, 2. The number of digits specifies the editing characters, and separators can number of digits to be maintained for be used in any of these fields and are data items assigned to the variable. discussed in Section D, "Picture The scale factor specifies the number Specification Characters." of fractional digits. No point is actually present; its location is The precision (p,q) of a sterling assumed. numeric character data item is defined as follows: 3. The scale factor can be specified for fixed-point variables only; the number q = number of fractional digits in of digits is specified for both the pence field fixed-point and floating-point variables. p = 3+q+(number of digit positions, actual and conditional, in the 4. When the scale is FIXED and no scale pounds field) factor is specified, it is assumed to be zero; that is, the variable is to represent integers. POINTER (Program Control Data Attribute) 5. The scale factor of a variable, or of an intermediate result of type FIXED, must be in the range -128 and +127. See OFFSET. 6. The scale factor can be negative, and it can be larger than the number of digits. A negative scale factor (-q) POSITION (Data Attribute) always specifies integers, with the point assumed to be located g places to the right of the rightmost actual See DEFINED. digit. A positive scale factor (q) that is larger than the number of digits always specifies a fraction, with the point assumed to be located g Precision (Arithmetic Data Attribute) places to the left of the rightmost actual digit. In either case, intervening zeros are assumed, but The precision attribute is used to specify they are not stored; only the the minimum number of significant digits specified number of digits are to be maintained for the values of the data actually stored. items, and to specify the scale factor (the assumed position of the binary or decimal 7. The precision attribute cannot be point). The precision attribute applies specified in combination with the to both binary and decimal data. PICTURE attribute. General format: 8. The maximum number of digits allowed for System/360 implementations is 15 (number-of-digits [,scale-factor]) for decimal fixed-point data, 31 for binary fixed-point data, 16 for The "number of digits" is an unsigned decimal floating-point data, and 53 350 for binary floating-point data. RECORD and STREAM (File Description Attributes) Assumptions: The RECORD and STREAM attributes specify the kind of data transmission to be used for the file. STREAM indicates that the data of the file is considered to be a The defaults for System/360 continuous stream of data items, in implementations are as follows: character form, to be assigned from the stream to variables, or from expressions into the stream. RECORD indicates that the (5,0) for DECIMAL FIXED file consists of a collection of physically (15,0) for BINARY FIXED separate records, each of which consists of (6) for DECIMAL FLOAT one or more data items in any form. Each (21) for BINARY FLOAT record is transmitted as an entity to or from a variable. General format: RECORD|STREAM PRINT (File Description Attribute) General rules: 1. A file with the STREAM attribute can The PRINT attribute specifies that the data be specified only in the OPEN, CLOSE, of the file is ultimately to be printed. GET, and PUT statements. The PAGE and LINE options of the PUT statement and the PAGES= option of the 2. A file with the RECORD attribute can OPEN statement can be used only with files be specified only in the OPEN, CLOSE, having the PRINT attribute. These options READ, WRITE, REWRITE, LOCATE, UNLOCK, are described in Section J, "Statements." and DELETE statements. General format: 3. A file with the STREAM attribute cannot have any of the following PRINT attributes: UPDATE, DIRECT, SEQUENTIAL, BACKWARDS, BUFFERED, General rules: UNBUFFERED, EXCLUSIVE, and KEYED, any of which implies RECORD. 1. The PRINT attribute implies the OUTPUT and STREAM attributes. 4. A file with the RECORD attribute cannot have the PRINT attribute. 2. The PRINT attribute conflicts with the RECORD attribute. (However, through Assumptions: the use of the DD statement, RECORD files can be associated with the Default is STREAM. If a file is printer.) implicitly opened by a READ, WRITE, REWRITE, UNLOCK, or DELETE statement, 3. The PRINT attribute causes the initial RECORD is assumed. data byte within each record to be reserved for ASA printer control characters. These control characters REDUCIBLE are set by the PAGE, SKIP, or LINE format items or options. See IRREDUCIBLE Assumption: If no FILE or STRING specification appears in a PUT statement, the standard RETURNS (Entry Name Attribute) output file SYSPRINT is assumed. The RETURNS attribute may be specified in a DECLARE statement for an entry name that is used in a function reference within the REAL (Arithmetic Data Attribute) scope of the declaration. It is used to describe the attributes of the function value returned when that entry name is See COMPLEX. invoked as a function. Section I: Attributes 351 General format: SEQUENTIAL (File Description Attribute) RETURNS (attribute...) See DIRECT. It is used in the following manner: STATIC (Storage Class Attribute) DECLARE entry-name [ENTRY-attribute-specification] RETURNS (attribute...); See AUTOMATIC. General rules: • STREAM (File Description Attribute) 1. The "ENTRY attribute specification" consists of the keyword ENTRY with or See RECORD. without associated parameter attribute lists. If parameter attribute lists are not required, the keyword ENTRY is optional, since the RETURNS attribute TASK (Program Control Data Attribute) implies the ENTRY attribute. The TASK attribute describes a variable 2. The attributes in the parenthesized that may be used as a task name, to test or list following the keyword RETURNS are control the relative priority of a task. separated by blanks. They must agree with the attributes specified in the RETURNS option of the PROCEDURE or General format: ENTRY statement to which the entry name is prefixed. If the attributes TASK of the actual value returned do not agree with those declared with the RETURNS attribute, no conversion will General rules: be performed. 1. An identifier can be explicitly declared with the TASK attribute in a 3. Only arithmetic, string, locator, DECLARE statement, or it can be AREA, and PICTURE attributes can be contextually declared by its specified. appearance in a TASK option of a CALL statement. 4. Length attribute specifications are evaluated on entry to the block 2. Task variables can also have the containing the RETURNS attribute following attributes: specification. a. Dimension 5. Unless default attributes for the entry name apply, any invocation of a b. Scope (the default is INTERNAL) function must appear within the scope of a RETURNS attribute declaration for c. Storage class (the default is the entry name. For an internal AUTOMATIC) function, the RETURNS attribute can be specified only in a DECLARE statement d. DEFINED (task variables may only that is internal to the same block as be defined on other task names) the function procedure. 3. A task variable can be used in the Assumptions: following contexts only: If the RETURNS attribute is not a. In the TASK option of a CALL specified within the scope of a function statement reference, the defaults assumed for the returned value are FIXED BINARY (15,0) if b. As an argument of the PRIORITY the entry name begins with any of the pseudo-variable or built-in letters I through N; otherwise, the function defaults are FLOAT DECIMAL (6). Default precisions are those defined for System/360 c. As an argument in a CALL statement implementations. or function reference 352 d. As a parameter in a PROCEDURE or 6. Structures, arrays, or areas ENTRY statement or in the containing task variables cannot take parameter attribute list of an part in assignment or input/output ENTRY attribute operations. 7. Task data cannot be converted to any e. In an ALLOCATE or FREE Statement other data type. 4. A task variable may be associated with 8. A task variable cannot be passed as an the priority of a task by including argument if this would require the task name in the TASK option of a creation of a dummy argument. CALL statement. A task variable is said to be active if its associated task is active. A task variable must TRANSIENT (File Description Attribute) be in an allocated state when it is associated with a task and must not be See DIRECT freed while it is active. An active task variable cannot be associated with another task. UNALIGNED (Data Attribute) 5. A task variable contains a single See ALIGNED. value, a priority value. This value is a fixed-point binary value of precision (n,0), where n is UNBUFFERED (File Description Attribute) implementation-defined (15, for the F Compiler). This value can be tested See BUFFERED. and adjusted by means of the PRIORITY built-in function and pseudo-variable. The built-in function returns the UPDATE (File Description Attribute) priority of the task argument relative to the priority of the task executing See INPUT. the function. Similarly, the pseudo-variable permits assignment, to the named task variable, of a priority VARYING (String Attribute) relative to the priority of the task executing the assignment. See BIT. Section I: Attributes 353 This section presents the PL/I statements keyword ALLOCATE must be a level 1 in alphabetical order. (The preprocessor identifier. statements are alphabetically arranged at the end of this section.) Most statements 3. Each identifier must represent data of are accompanied by the following the controlled storage class or be an information: element of a controlled major structure. 1. Function -- a short description of the meaning and use of the statement 4. "Dimension" indicates a dimension attribute. "Attribute" indicates a 2. General format -- the syntax of the BIT, CHARACTER, or INITIAL attribute. statement 5. A dimension attribute, if present, 3. Syntax rules -- rules of syntax that must specify the same number of are not reflected in the general dimensions as that declared for the format associated identifier. 4. General rules -- rules governing the 6. The attribute BIT may appear only with use of the statement and its meaning a BIT identifier; CHARACTER may appear in a PL/I program only with a CHARACTER identifier. 7. A structure element name, other than the major structure name, may appear The ALLOCATE Statement only if the relative structuring of the entire structure appears as in the DECLARE statement for that structure. Function: Syntax rules 8 and 9 apply only to The ALLOCATE statement causes storage to Option 2: be allocated for specified controlled or based data. 8. The based variable appearing in the ALLOCATE statement may be an element General format: variable, an array, or a major structure. When it is a major Option 1: structure, only the major structure name is specified. ALLOCATE [level] identifier [dimension] [attribute]... 9. The SET clause, if present, may appear [,[level] identifier [dimension] preceding or following the IN clause. [attribute]...]...; General rules: Option 2: Rules 1 through 6 apply only to Option 1: ALLOCATE based-variable-identifier [SET (pointer-variable)] 1. When Option 1 is used, an ALLOCATE [IN (area-variable)] statement for an identifier for which [, based-variable-identifier storage was allocated and not freed [SET (pointer-variable)] causes storage for the identifier to [IN (area-variable)]]...; be "pushed down" or stacked. This pushing down creates a new generation Syntax rules: of data for the identifier. When storage for this identifier is freed, 1. Based variables and controlled using the FREE statement, storage is variables may both be specified as "popped up" or removed from the stack. identifiers in the same ALLOCATE statement. 2. Bounds for arrays and lengths of strings are fixed at the execution of Syntax rules 2 through 7 apply only to an ALLOCATE statement. Option 1: a. If a bound or length is explicitly 2. "Level" indicates a level number. The specified in an ALLOCATE first identifier appearing after the statement, that bound or length 354 overrides any bound or length interdependent; they cannot depend on given in the DECLARE statement. each other at the same time. Rules 7 through 12 apply only to b. If a bound or length is specified Option 2: by an asterisk in an ALLOCATE statement, that bound or length is 7. When Option 2 is used, storage is not taken from the current generation. "pushed down" or stacked. In this If no generation of the variable case, reference may be made to any exists, the bound or length is generation of a based variable through undefined. a pointer variable. c. Either the ALLOCATE statement or 8. The SET clause indicates the pointer the DECLARE statement must specify variable that is to receive the value any necessary dimension size, or identifying the allocation. The SET length attributes for an clause need not name the pointer identifier. Any expression taken variable declared with the based from the DECLARE statement is variable. If the SET clause is evaluated at the point of omitted, the pointer that was declared allocation using the condition with the based variable is set. enabling of the ALLOCATE statement, although the names are 9. If the IN clause appears in the interpreted in the environment of ALLOCATE statement, storage will be the DECLARE statement. allocated in the named area, for the based variable. If sufficient storage d. If, in either an ALLOCATE or a does not exist within this area, the DECLARE statement, bounds, AREA condition will be raised. lengths, or area sizes are specified by expressions that 10. The amount of storage allocated for a contain references to the variable based variable depends on its being allocated, the expressions attributes, and on its dimensions and are evaluated using the value of length specifications if these are the most recent generation of the applicable at the time of allocation. variable. These attributes are determined from the declaration of the based variable, 3. Upon allocation of an identifier, and additional attributes may not be initial values are assigned to it if specified in the ALLOCATE statement. the identifier has an INITIAL A based structure may contain one attribute in either the ALLOCATE adjustable array bound or string statement or DECLARE statement. length, whose value is taken, on Expressions or a CALL option in the allocation, from the current value of INITIAL attribute are executed at the a variable outside the structure (see point of allocation, using the "The REFER Option", in Chapter 14, condition enabling of the ALLOCATE "Based Variables and List statement, although the names are Processing.") Note that the asterisk interpreted in the environment of the notation for bounds and length is not declaration. If an INITIAL attribute permitted for based variables. appears in both DECLARE and ALLOCATE statements, the INITIAL attribute in 11. If the area variable is an array, the the ALLOCATE statement is used. If subscripts must be specified with the initialization involves reference to area variable. the variable being allocated, the reference will be to the new 12. A based variable transferred as an generation of the variable. argument to a procedure cannot appear in an ALLOCATE statement in the called 4. To determine whether or not storage procedure. has been allocated for an identifier the built-in function ALLOCATION may Examples: be used. 1. The following examples illustrate the 5. A parameter that is declared use of the ALLOCATE statement for a CONTROLLED may be specified in an controlled identifier: ALLOCATE statement. DECLARE A(N1,N2) CONTROLLED ; 6. Any evaluations performed at the time the ALLOCATE statement is executed N1, N2 = 10; (e.g., evaluation of expressions in an ALLOCATE A; The bounds are 10 and INITIAL attribute) must not be 10 Section J: Statements 355 ALLOCATE A The bounds are K1 and Allocates storage for the (K1,K2); K2 which override N1 structure GROUP, and sets the and N2. pointer variable R to identify the N1 = N1 + 1; particular allocation. The ALLOCATE A; The bounds are 11 and current value of N is used to 10. determine the bound of VALUES, and ALLOCATE A The bounds are 11 and this value is assigned to DIM. (*,*); 10. ALLOCATE A The bounds are J1 and C. ALLOCATE RATES SET (T) IN (TABLE); (J1, J2); J2. Allocates storage within the area S-> TABLE for the variable RATES. 2. The following example illustrates the The pointer variable T is set to use of the ALLOCATE statement when the identify the location within TABLE DECLARE statement contains asterisks at which RATES is allocated. for the length of a controlled bit string B: DECLARE B BIT (*) VARYING CONTROLLED ; The Assignment Statement ALLOCATE B Invalid; violates rule BIT (*); 2b. Function: ALLOCATE B; Invalid; violates rule 2b. The assignment statement is used to ALLOCATE B The maximum length is evaluate an expression and to assign its BIT (N); N. value to one or more target variables; the ALLOCATE B CHAR- Invalid; violates syn- target variables may be element, array, or ACTER (4); tax rule 5. structure variables. The target variables ALLOCATE B The maximum length is may be indicated by pseudo-variables. BIT (8); 8. General formats: 3. The following example illustrates the use of the built-in function The assignment statement has 3 general ALLOCATION and of the INITIAL format options. They are given in Figure attribute for a controlled variable in J-1. an ALLOCATE statement: Syntax rules: DECLARE A(N,N) CONTROLLED INITIAL ((N*N)0); 1. In Option 2, each target variable must be an array. If the right-hand side contains arrays of structures, then all target variables must be arrays of IF ALLOCATION (A) THEN ALLOCATE A structures. The BY NAME option may be INITIAL (1,(N-1) ((N)0,1)); given only when the right-hand side contains at least one structure. 2. In Option 3, each target variable must ALLOCATE A; be a structure. 4. The following example illustrates General rules: three uses of Option 2 of the ALLOCATE statement for based identifiers. 1. Aggregate assignments (Options 2 and 3) are expanded into a series of DECLARE VALUE BASED (P), element assignments according to rules RATES BASED (Q), 5 through 8. 1 GROUP BASED (R), 2 DIM FIXED BINARY, 2. An element assignment is performed as 2 VALUES (N REFER (DIM)), follows: TABLE AREA BASED (S), N FIXED BINARY, a. Subscripts of the target T POINTER; variables, and the second and third arguments of SUBSTR a. ALLOCATE VALUE SET (P); pseudo-variable references, are Allocates storage for the based evaluated from left to right. variable VALUE and sets the pointer variable P to identify the b. The expression on the right-hand particular allocation. side is then evaluated. b. ALLOCATE GROUP SET (R); c. For each target variable (in left 356 Figure J-1. General Formats of the Assignment Statement to right order), the expression is declared for the variable, the converted to the characteristics value is truncated on the right. of the target variable according The target string obtains a to rules for data conversion current length equal to its (except that whenever a conversion maximum length. If the value of of arithmetic base is involved, the expression is not longer than the value is converted directly to the maximum length, the value is the precision of the target assigned; the target string variable). The converted value is obtains a current length equal to then assigned to the target the length of the value. variable. 5. The following rules apply to other 3. For the F Compiler, multiple element assignments: assignments are limited by the following rule: a. If the target is an area variable, the expression must be an area Count 11 for each target of a multiple variable or function. The AREA assignment, add 3 for each condition will be raised by this pseudo-variable and then add 11 for assignment if the size of the each argument of a pseudo-variable. target area is insufficient for The total must not exceed 4,085. the current extent of the area being assigned. 4. The following rules apply to string element assignment: b. If the target is a pointer variable, the expression can only a. The assignment is performed from be a pointer (or offset) variable left to right, starting with the or a pointer (or offset) function leftmost position. reference. If the expression is of offset type, its value is b. If the target variable is a converted to pointer. fixed-length string, the expression value is truncated on c. If the target is an offset the right if it is too long or variable, the expression can only padded on the right (with blanks be an offset (or pointer) variable for character string, zeros for or an offset (or pointer) function bit strings) if the value is too reference. If the expression is short. (Note that a string of pointer type, its value is pseudo-variable is considered to converted to offset. be a fixed-length string). The resulting value is assigned to the d. If the target is a label variable, target. the expression can only be a label variable or label constant. c. If the target is a VARYING string Environmental information (i.e., and the value of the expression is information that identifies the longer than the maximum length invocation of the block) is always Section 3: Statements 357 assigned to the label variable. of dimensions of the master variable that are to participate in the assignment. In the generated e. If the target is an event assignment statement, all array variable, the expression can only operands are fully subscripted, using be an event variable. The (from left to right) the dummy assignment is uninterruptable, and variables j1 to jn. If an array it involves both the completion operand appears with no subscripts, it and status values. An event will only have the subscripts j1 to variable does not become active jn; if cross-section notation is used, when it has an active event the asterisks are replaced by j1 to variable assigned to it. It is an jn. If the original assignment error to assign to an active event statement (which may have been variable. generated by Rule 7 or Rule 8) has a condition prefix, the generated f. If the target is a STATUS assignment statement is given this pseudo-variable, a value can be condition prefix. If the original assigned whether or not the event assignment statement (which may have variable is active. It is an been generated by Rule 8) has a BY error to assign to a COMPLETION NAME option, the generated assignment pseudo-variable if the named event statement is given a BY NAME option. variable is active. If the generated assignment statement is a structure assignment, it is 6. The first target variable in an expanded as given below. aggregate assignment is known as the master variable. If the master 8. In Option 3, where the BY NAME option variable is an array, then an array is not specified, the following rules expansion (Rule 6) is performed; apply: otherwise, a structure expansion (Rules 7 and 8) is performed. The a. None of the operands can he CHECK condition for assignment to a arrays, although they may be target variable is not raised during structures that contain arrays. the assignment; it is raised (when suitably enabled) after the assignment b. All of the structure operands must is complete. Such CHECK conditions have the same number, k, of are raised in the written order of the immediately contained items. enabled identifiers. In the case of BY NAME assignment, the CHECK c. The assignment statement (which condition for the target variable is may have been generated by Rule 6) raised regardless of whether any value is replaced by k generated is assigned to an item. The label assignment statements. The ith prefix of the original statement is generated assignment statement is applied to a null statement preceding derived from the original the other generated statements. assignment statement by replacing each. structure operand by its ith 7. In Option 2, all array operands must contained item; such generated have the same number of dimensions and assignment statements may require identical bounds. The array further expansion according to assignment is expanded into a loop of Rule 6 or Rule 7. All generated the form: assignment statements are given the condition prefix of the LABEL: DO j1 = LBOUND(master-variable,1) TO original statement. HBOUND(master-variable,1); 9. In Option 3, where the BY NAME option DO j2 = LBOUND(master-variable,2) TO is given, the structure assignment, HBOUND(master-variable,2); which may have been generated by Rule 6, is expanded according to steps (a) through (d) below. None of the operands can be arrays. DO jn = LBOUND(master-variable,n) TO a. The first item immediately HBOUND(master-variable, n); contained in the master variable is considered. generated assignment statement b. If each structure operand and END LABEL; target variable has an immediately contained item with the same In this expansion, n is the number identifier, an assignment 358 statement is generated as follows: ONE.PART2 = TWO.PART2 - 2 * the statement is derived by THREE.PART2, BY NAME; replacing each structure operand and target variable with its Applying Rule 8 again, these immediately contained item that statements are replaced by: has this identifier. If any structure contains no such ONE.PART1.RED = TWO.PART1.RED identifier, no statement is - 2 * THREE.PART1.RED; generated. If the generated assignment is a structure or ONE.PART1.WHITE = TWO.PART1.WHITE array-of-structures assignment, BY - 2 * THREE.PART1.WHITE; NAME is appended. The first generated assignment is given the ONE.PART2.YELLOW = TWO.PART2.YELLOW label prefix of the original - 2 * THREE.PART2.YELLOW; assignment statement; all generated assignment statements ONE.PART2.ORANGE = TWO.PART2.ORANGE are given the condition prefix of - 2 * THREE.PART2.ORANGE; the original assignment statement. The final assignment is expanded c. Step b is repeated for each of the according to Rule 6. items immediately contained in the master variable. The assignments 2. The following example illustrates are generated in the order of the array assignment (Option 2): items contained in the master variable. Given the array A 2 4 3 6 d. Steps a through c may generate 1 7 further array and structure 4 8 assignments. These are expanded according to Rules 6 through 8. and the array B 1 5 7 8 Examples: 3 4 6 3 1. Suppose that the following three structures have been declared. Consider the assignment statement: 1 ONE 1 TWO A = (A+B)**2-A(1,1); 2 PART1 2 PART1 3 RED 3 RED After execution, A has the value 3 WHITE 3 GREEN 7 74 3 BLUE 3 WHITE 93 189 2 PART2 2 PART2 9 114 3 GREEN 3 BLUE 93 114 3 YELLOW 3 YELLOW 3 ORANGE(3) 3 ORANGE(3) Note that the new value for A(1,1) 2 PART3 which is 7, is used in evaluating the 3 BLACK expression for all other elements. 3 WHITE 3. The following example illustrates 1 THREE string assignment: 3 PART1 5 BLACK Given: 5 WHITE 5 RED A is a fixed-length string whose 3 PART2 value is 'XZ/BQ'. 5 YELLOW B is a varying-length string of 5 WHITE maximum length 8 whose value is 5 ORANGE(3) 'MAFY'. 5 PURPLE C is a fixed-length string of length 3. Consider the following assignment: D is a varying-length string of maximum length 5. ONE = TWO - 2 * THREE, BY NAME; Then in the statement: By Rule 8 this generates: C=A, the value of C is 'XZ/'. ONE.PART1 = TWO.PART1 - 2 * C='X', the value of C is 'Xbb'. THREE.PART1, BY NAME; D=B, the value of D is 'MAFY'. Section J: Statements 359 D=SUBSTR(A,2,3)||SUBSTR(A,2,3), that if computational or system action the value of D is 'Z/BZ/'. interrupts occur during execution of SUBSTR(A,2,4)=B, the value of A is the block, the result is not 'XMAFY'. necessarily the same as it would be SUBSTR(B,2,2)='R', the value of B under the strict rules. is 'MRbY'. SUBSTR(B,2)='R', the value of B is 3. The ORDER option specifies that the 'MRbb'. normal language rules are not to be relaxed; i.e., any optimization must be such that the execution of a block always produces a result that is in The BEGIN Statement accordance with the strict definition of PL/I. This means that the values of variables set by execution of all statements prior to computational or Function: system action interrupts are guaranteed in an on-unit entered as a The BEGIN statement heads and identifies result of the interrupt, or anywhere a begin block. in the program afterwards. Note that the strict definition now allows the General format: compiler to optimize common expressions, where safely possible, by BEGIN [ORDER|REORDER]; evaluating them once only and saving the result, rather than re-evaluating Syntax rules: for each reference. (A common expression is an expression that 1. A label of a BEGIN statement may be occurs more than once in a program but subscripted, but such a label cannot is obviously intended to result in the appear after an END statement. same value each time that it is evaluated, i.e., if a later expression 2. ORDER and REORDER are options used to is identical to an earlier expression, control the optimization performed by with no intervening modification to the compiler. The selected option any operand, the expressions are said applies to all nested blocks unless to be common.) overridden; if neither option is specified, the option that applies to 4. The REORDER option specifies that the containing block will apply to the execution of the block must produce a begin block. (If the containing block result that is in accordance with the is an external procedure, the strict definition of PL/I unless a procedure will have the ORDER option computational or system action unless REORDER has been explicitly interrupt occurs during execution of specified with the PROCEDURE the block; the result is then allowed statement.) to deviate as follows: General rules: a. After a computational or system action interrupt has occurred 1. A BEGIN statement is used in during execution of the block, the conjunction with an END statement to values of variables modified, delimit a begin block. A complete allocated, or freed in the block discussion of begin blocks can be are guaranteed only after normal found in Part I, Chapter 6, "Blocks, return from an on-unit or when Flow of Control, and Storage accessed by the ONCHAR and Allocation." ONSOURCE condition built-in functions. 2. The ORDER and REORDER options specify, for optimization purposes, the degree b. The values of variables modified, of language stringency to be observed allocated, or freed in an on-unit during compilation of the block. The for a computational or system strict rules require that the source action condition (or in a block program should be compiled so as to be activated by such an on-unit) are executed in the order specified by the not guaranteed on return from the sequence of the statements in the on-unit into the block, except for source program (see "Control values modified by the ONCHAR and Statements" in Chapter 5, "Statement ONSOURCE pseudo-variables. Classification"), even if the code could be reordered so as to produce A program is in error if a the same result more efficiently. The computational or system action relaxation allowed by REORDER is such interrupt occurs during the execution 360 of the block and this interrupt is the task to be controlled at some followed by a reference to a variable other point by the use of the PRIORITY whose value is not guaranteed in such pseudo-variable and built-in function. circumstances. (See also Chapter 17: "Optimization and Efficient Performance.") 3. When the EVENT option is used, the event name is associated with the completion of the task created by the CALL statement. Another task can then The CALL Statement wait for completion of this created task by specifying the event name in a WAIT statement. Function: Upon execution of the CALL The CALL statement invokes a procedure statement, the event variable is made and causes control to be transferred to a active, and the completion value is specified entry point of the procedure. set to '0'B and the status value to 0. Upon termination of the created task, The CALL statement is also used for the completion value is set to '1'B linking a PL/I program to library modules and, unless the task has been that interface to the operating system terminated by a RETURN or END facilities including checkpoint restart, statement, the status is set to 1 if sort/merge and storage dumping. For still zero. details see the publication: IBM System/360 Operating System PL/I (F) Programmer's Guide. 4. If the PRIORITY option is used, the General format: expression in the PRIORITY option is evaluated to an integer m, of an CALL entry-name implementation-defined precision (15,0). The priority of the named [(argument [,argument] . . .)} task is then made m relative to the task in which the CALL is executed. [TASK [(scalar-task-name)]] [EVENT (scalar-event-name)] [PRIORITY (expression)]; If a CALL statement with the EVENT or TASK option does not have the Syntax rules: PRIORITY option, the priority of the invoked task is made equal to that of 1. The entry name, which can be a generic the task variable in the TASK option, name, represents the entry point of if there is one, or else made equal to the procedure invoked. the priority of the invoking task. 2. An argument cannot be a condition name. 5. Expressions in these options, as well 3. The TASK, EVENT, and PRIORITY options as any argument expressions, are can appear in any order. evaluated in the task in which the call is executed. This includes General rules: execution of any on-units entered as the result of the evaluations. 1. The TASK, EVENT, and PRIORITY options, when used alone or in any combination, specify that the invoked and invoking 6. The environment of the invoked procedures are to be executed procedure is established after asynchronously. Note that if either evaluation of the expressions named in the EVENT option or the PRIORITY Rule 5, and before the procedure is option, or both, are used without the invoked. TASK option, the created task will have no name. (See Part I, Chapter 15, "Multitasking.") 7. See Part I, Chapter 12, "Subroutines and Functions" for detailed 2. When the TASK option is used, the task descriptions of the interaction of name, if given, is associated with the arguments with the parameters that task created by the CALL. Reference represent these arguments in the to this name enables the priority of invoked procedure. Section J: Statements 361 Examples: Examples: 1. CALL CRITICAL_PATH (A,B*C,D); 1. CLOSE FILE (MASTER); The file, MASTER, is closed, and the facilities allocated to it are CRITICAL_PATH: PROCEDURE(ALPHA,BETA, released. GAMMA); 2. CLOSE FILE (TABLEA), FILE (TABLED); The two files, TABLEA and TABLEB are END; closed in the same way as MASTER, in the preceding example. 2. CALL PAYROLL (NAME, DATE, HRRATE); The DECLARE Statement 3. CALL PRINT (A,B) TASK (T2) EVENT (ET2) PRIORITY (-2); Function: The DECLARE statement is the principal method for explicitly declaring attributes The CLOSE Statement of names. General format: Function: DECLARE [level] identifier [attribute]... The CLOSE statement dissociates the [,[level] identifier [attribute]...]...; named file from the data set with which it was associated by opening in the current Syntax rules: task. 1. Any number of identifiers ray be General format: declared in one DECLARE statement. CLOSE FILE (file-name) [,FILE 2. "Level" is a nonzero unsigned decimal (file-name)]...; integer constant. If a level number is not specified, level 1 is assumed General rules: tor all element and array variables. Level 1 must be specified for all 1. The FILE(filename) option specifies major structure names. A blank space which file is to be closed. It must must separate a level number from the appear once. Several files can be identifier following it. closed by one CLOSE statement. 3. In general, attributes must 2. A closed file can be reopened. immediately follow the identifier to which they apply as shown in the 3. Closing an unopened file, or an general format. However, attributes already closed file, has no effect. can be factored (see "Factoring of Attributes" in Section I, 4. The CLOSE statement cannot be used to "Attributes"). close a file in a task different from the one that opened the file. General rules: 5. If a file is not closed by a CLOSE 1. A particular level 1 identifier can be statement, it is automatically closed specified in only one DECLARE at the completion of the task in which statement within a particular block. it was opened. All attributes given explicitly for that identifier must be declared 6. All input/output events that have not together in that DECLARE statement. been completed before the file is (Note, however, that identifiers closed are set complete, with a status having the FILE attribute may be given value of 1. attributes in an OPEN statement as well. See "The OPEN Statement" in 7. A CLOSE statement unlocks all records this section and in Part I, Chapter 8, previously locked by the file in the "Input and Output," for further task in which the CLOSE appears. information.) 362 2. Attributes of external names, in expression is converted to a character separate blocks and compilations, must string and determines which record is be consistent. to be deleted. 3. Labels may be prefixed to DECLARE 4. If the file is a SEQUENTIAL UPDATE statements (however, such labels are file, the record to be deleted is the treated as comments and, hence, have last record that was read; the data no meaning). Condition prefixes set organization must be INDEXED. cannot be attached to a DECLARE statement. 5. The EVENT option allows processing to continue while a record is being deleted. This option cannot be specified for a SEQUENTIAL BUFFERED The DELAY Statement file. When control reaches a DELETE statement containing this option, the Function: "event variable" is made active (that is, it cannot be associated with The DELAY statement causes the execution another event) and is given the of a task to be suspended for a specified completion value '0'B, provided that period of time. the UNDEFINEDFILE condition is not raised by an implicit file opening General format: (see "Note" below). The event variable remains active and retains DELAY (element-expression); its '0'B completion value until control reaches a WAIT statement General rule: specifying that event variable. At this time, either of the following can Execution of the DELAY statement causes occur: the element expression to be evaluated and converted to an integer n; execution is a. If the DELETE statement has been then suspended for n milliseconds. executed successfully and neither of the conditions TRANSMIT or KEY Example: has been raised as a result of the DELETE, the event variable is set DELAY (10); complete, given the completion value '1'B, and the event variable This statement causes execution of the is made inactive, that is, can be task to be suspended for ten milliseconds. associated with another event. b. If the DELETE statement has resulted in the raising of The DELETE Statement TRANSMIT or KEY, the interrupt for each of these conditions does not occur until the WAIT is encountered. At such time, the Function: corresponding on-units (if any) are entered in the order in which The DELETE statement deletes a record the conditions were raised. After from an UPDATE file. a return from the final on-unit, or if one of the on-units is General format: terminated by a GO TO statement, the event variable is given the DELETE FILE [KEY(expression)](file-name) completion value '1'B and is made inactive. [EVENT(event-variable)]; Note: If the DELETE statement causes an General rules: implicit file opening that results in the raising of UNDEFINEDFILE, the on-unit 1. The options may appear in any order. associated with this condition is entered immediately and the event variable remains 2. The FILE(filename) option specifies unchanged; that is, the event variable the UPDATE file; it must be specified. remains inactive and retains the same value it had when the DELETE was encountered. If 3. The KEY option must be specified if the on-unit does not correct the condition, the file is a DIRECT UPDATE file; it then, upon normal return from the on-unit, cannot be specified otherwise. The the ERROR condition is raised; if the Section J: Statements 363 condition is corrected in the on-unit, that program is suspended until the is, if the file is opened successfully, operator's message is received. In then, upon normal return from the on-unit, option 1, execution continues the event variable is set to '0'B, it is uninterrupted. made active, and execution of the DELETE statement continues. 4. If the EVENT (event-variable) option is given, execution will not wait for 6. The DELETE statement unlocks a record the reply to be completed before only if that record had been locked in continuing with subsequent statements. the same task in which the DELETE The completion part of the event appears. variable will be given the value '0'B until the reply is completed, when it 7. The DELETE statement can cause will be given the value '1'B. The implicit opening of a file. reply is considered complete only after the execution of a WAIT Example: statement naming the event. DELETE FILE(ALPHA) KEY (DKEY); 5. The EVENT and REPLY options can be given in either order. This statement causes the record identified by DKEY to be deleted from the 6. The effect of the DISPLAY statement data set associated with the file ALPHA. when multiple consoles are in use will If the record was previously locked in the depend on the default route code and same task, it is unlocked. descriptor code. For details of these codes, see IBM System/360 Operating System: PL/I (F) Programmer's Guide. The DISPLAY Statement Example: DISPLAY ('END OF JOB'); Function: This statement causes the message "END OF JOB" to be displayed. The DISPLAY statement causes a message to be displayed to the machine operator. A response may be requested. The DO Statement General format: Option 1. Function: DISPLAY (element-expression); The DO statement heads a DO-group and Option 2. can also be used to specify repetitive execution of the statements within the DISPLAY (element-expression) group. REPLY (character-variable) [EVENT (event-variable)]; General formats: General rules: The three format types for the DO 1. Execution of the DISPLAY statement statement are shown in Figure J-2. causes the element expression to be evaluated and, where necessary, Syntax rules: converted to a varying character string of implementation-defined 1. In all three types, the DO statement maximum length (72 characters for the is used in conjunction with the END F Compiler). This character string is statement to delimit a DO-group. Only the message to be displayed. Type 1 does not provide for the repetitive execution of the statements 2. In Option 2, the character variable within the group. receives a string that is a message to be supplied by the operator. For the 2. In Type 3, the variable or F Compiler, the message cannot exceed pseudo-variable must represent a 126 characters. single element; "variable" may be subscripted and/or qualified. Real 3. In Option 2, if the EVENT option is arithmetic variables are generally not specified, execution of the used, but label, string, and complex 364 Figure J-2. General Format of the DO Statement variables are allowed, provided that for repetitive execution as defined by the expansions given in the general the following: rules below result in valid PL/I programs. Note, however, that if "variable" is a label variable, each "specification" must have the LABEL: DO WHILE (expression); following form: statement-1 (element-label-variable label-constant statement-n END; [WHILE (expression)] NEXT: statement /*STATEMENT FOLLOWING THE DO GROUP*/ 3. Each expression in a specification rust be an element expression. The above is exactly equivalent to the following expansion: 4. If "BY expression3" is omitted from a "specification," and if "TO LABEL: IF (expression) THEN; ELSE expression2" is included, GO TO NEXT; "expression3" is assumed to be 1. statement-1 5. If "TO expression2" is omitted from a "specification," repetitive execution continues until it is terminated by statement-n the WHILE clause or by some statement GO TO LABEL; within the group. NEXT: statement /*STATEMENT FOLLOWING THE DO GROUP*/ 6. If both "TO expression2" and "BY expression3" are omitted from a 3. In Type 3, the DO statement delimits specification, it implies a single the start of a DO-group and provides execution of the group, with the for controlled repetitive execution as control variable having the value of defined by the following: "expression1". If "WHILE expression4" is included, this single execution will not take place unless LABEL: DO variable (ai,...,an)= "expression4" is true. expression1 TO expression2 General rules: BY expression3 WHILE (expression4); 1. In Type 1, the DO statement only statement-1 delimits the start of a DO-group; it does not provide for repetitive execution. statement-m 2. In Type 2, the DO statement delimits LABEL1: END; the start of a DO-group and provides NEXT: statement Section J: Statements 365 This is exactly equivalent to the following expansion: Note that statements 1 through m are not actually duplicated in the program. b. If the WHILE clause is omitted, the IF statement immediately preceding statement-1 in the expansion is omitted. In the above expansion, a1,...,an are expressions that may appear as c. If "TO expression2" is omitted, subscripts of the control variable; the statement "e2=expression2" and temp1....tempn are compiler-created the IF statement identified by work areas, with the attributes BINARY LABEL2 are omitted. FIXED(15), to which the expression values are assigned; v is equivalent d. If both "TO expression2" and "BY to "variable" with the associated expression3" are omitted, all "temp" subscripts; "el," "e2," and statements involving e2 and e3, as "e3" are compiler-created work areas well as the statement GO TO having the attributes of " LABEL2, are omitted. expression1," "expression2," and "expres- sion3," respectively. In the simplest 4. The WHILE clause in Types 2 and 3 cases, there are no subscripts (i.e., specifies that before each repetition n=0) and the first statement in the of statement execution, the associated expansion is therefore el=expressionl. element expression is evaluated, and, if necessary, converted to a bit string. If any bit in the resulting string is 1, the statements of the Additional rules for the above DO-group are executed. If all bits expansion follow: are 0, then, for Type 2, execution of the DO-group is terminated, while for Type 3, only the execution associated with the "specification" containing the WHILE clause is terminated; a. The above expansion only shows the repetitive execution for the next result of one "specification." If "specification," if one exists, then the DO statement contains more begins. than one "specification," the statement labeled NEXT is the 5. In a "specification," "expression1" first statement in the expansion represents the initial value of the for the next "specification." The control variable (i.e., "variable" or second expansion is analogous to "pseudo-variable"); "expression3" the first expansion in every represents the increment to be added respect. Thus, if a second to the control variable after each "specification" appeared in the DO execution of the statements in the statement, the second expansion group; expression2 represents the would look like this: terminating value of the control 366 variable. Execution of the statements The ENTRY Statement in a DO-group terminates for a "specification" as soon as the value of the control variable is outside the Function: range defined by "expression1" and "expression2." When execution for the The ENTRY statement specifies a last "specification" is terminated, secondary entry point of a procedure. control, in general, passes to the statement following the DO-group. General format: 6. Control may transfer into a DO-group entry-name: [entry-name:]... from outside the DO-group only if the ENTRY [(parameter [,parameter]...)] DO-group is delimited by the DO [RETURNS(attribute...)]: statement in Type 1; that is, only if repetitive execution is not specified. Syntax rules: Consequently, repetitive DO-groups cannot contain ENTRY statements. 1. The only attributes that may be specified in the RETURNS option of an ENTRY statement are the arithmetic, 7. The effect of allocating or freeing string, POINTER, OFFSET, AREA, and the control variable within the PICTURE attributes. The attributes DO-group is undefined. specified determine the characteristics of the value returned by the procedure when it is invoked as a function at this entry point. 2. A condition prefix cannot be specified for an ENTRY statement. The END Statement General rules: Function: 1. The relationship established between the parameters of a secondary entry The END statement terminates blocks and point and the arguments passed to that groups. entry point is exactly the same as that established for primary entry point parameters and arguments. See General format: Part I, Chapter 12, "Subroutines and Functions," for a complete discussion END [label]; of this subject. Syntax rules: 2. As stated in syntax rule 1, the If "label" is specified, it cannot be an attributes specified in the RETURNS element of a label array; that is, it option of an ENTRY statement determine cannot be subscripted. the characteristics of the value returned by the procedure when it is General rules: invoked as a function at this entry point. The value being returned by 1. If a label follows END, the statement the procedure (i.e., the value of the terminates the unterminated group or expression in a RETURN statement) is block headed by the nearest preceding converted, if necessary, to correspond DO, BEGIN, or PROCEDURE statement to the specified attributes. If the having that label. It also terminates RETURNS option is omitted, default any unterminated groups or blocks attributes are applied, according to physically within that group or block. the first letter of the entry name used to invoke the entry point. 2. If a label does not follow END, the statement terminates that group or 3. If an ENTRY statement has more than block headed by the nearest preceding one label, each label is interpreted DO, BEGIN, or PROCEDURE statement for as though it were a single entry name which there is no corresponding END for a separate ENTRY statement having statement. the same parameter list and explicit attribute specification. For example, 3. If control reaches an END statement consider the statement: for a procedure, it is treated as a RETURN statement. A: I: ENTRY; Section J: Statements 367 This statement is effectively the same label: [label:]... FORMAT (format-list); as: A: ENTRY; Syntax rules: I: ENTRY; 1. The "format list" must be specified Since the attributes of the returned according to the rules governing value are not explicitly stated, the format list specifications with characteristics of the value returned edit-directed transmission as by the procedure will depend on described in Part I, Chapter 9, whether the entry point has been "Stream-Oriented Transmission." invoked as A or I. 4. The ENTRY statement must be internal 2. At least one "label" must be specified to the procedure for which it defines for a FORMAT statement. One of the a secondary entry point. It may not labels (or a label variable having the be internal to any block contained in value of one of the labels) is the this procedure; nor may it be within a statement label designator appearing DC-group that specifies repetitive in a remote format item. None of the execution. labels can be specified in a GO TO statement. General rules: The EXIT Statement 1. A GET or PUT statement may include a remote format item, R, in the format list of an edit-directed data Function: specification. That portion of the format list represented by R must be The EXIT statement causes immediate supplied by a FORMAT statement termination of the task that contains the identified by the statement label statement and all tasks attached by this specified with R. task. If the EXIT statement is executed in a major task, it is equivalent to a STOP 2. The remote format item and the FORMAT statement. statement must be internal to the same block. General format: 3. If a condition prefix is associated EXIT; with a FORMAT statement, it must be identical to the condition prefix General rule: associated with the GET or PUT statement referring to that FORMAT If executed in a major task, EXIT causes statement. the FINISH condition to be raised in that task. On normal return from the FINISH 4. When a FORMAT statement is encountered on-unit, the task executing the statement, in normal sequential flow, control and all of its descendant tasks are passes around it, and the CHECK terminated. The completion values f the condition will not be raised for a event variables associated with these tasks statement label attached to it. are set to '1'B, and their status values to 1 (unless they are already non-zero). The FREE Statement The FORMAT Statement Function: Function: The FREE statement causes the storage The FORMAT statement specifies a format allocated for specified based or controlled list that can be used by edit-directed variables to be freed. For controlled transmission statements to control the variables, the next most recent allocation format of the data being transmitted. in the task is made available, and subsequent references in the task to the General format: identifier refer to that allocation. 368 General formats: storage to be freed has been allocated using the IN option, and it must have Option 1 been allocated in the area specified in the FREE statement. The IN option FREE controlled-variable cannot appear in the FREE statement in [,controlled-variable]...; any other circumstances. Note that area assignment causes allocation of Option 2 based storage in the target area; such allocations can be freed by the IN FREE [pointer-qualifier ->] option naming the target area. based-variable[IN(area-variable)] [,[pointer-qualifier- >] Examples: based-variable [IN(area-variable)]]...; 1. FREE X,Y,Z; Syntax rules: 2. The following excerpt from a procedure illustrates the FREE statement in 1. In Option 1, the "controlled variable" conjunction with an ALLOCATE is an element, array, or major statement: structure of the controlled storage class. 2. In Option 2, the "based variable" must be an unsubscripted, level-one based variable. 3. The forms of Option 1 and Option 2 can be combined in the same FREE statement. General rules: 1. Controlled storage allocated in a task cannot be freed by a descendant task. 2. If a specified nonbased identifier has no allocated storage at the time the FREE statement is executed, it is an error. 3. In the example below, it is assumed Rules 3 through 6 apply only to Option 2. the declarations specified in Example 4 of the ALLOCATE statement apply. 3. If the based variable is not qualified by pointer qualification, the pointer FREE VALUE; declared with the based variable will be used to identify the generation of Frees that portion of storage which is data occupying the portion of storage occupied by the allocation of VALUE to be freed. identified by pointer P. 4. The amount of storage freed depends FREE V->GROUP; upon the attributes of the based variable, including bounds and/or Frees that portion of storage which is lengths at the time the storage is occupied by the allocation of GROUP freed, if applicable. The user is identified by pointer V. The value responsible for determining that this V->DIM is used to determine the bound amount coincides with the amount of VALUES. allocated. If the variable has not been allocated, the results are unpredictable. The GET Statement 5. A based variable can be used to free storage only if that storage has been allocated for a based variable having identical data attributes, including Function: values of bounds, lengths, and area size expressions. The GET statement is a STREAM transmission statement that can be used in 6. The IN option must be specified if the either of the following ways: Section 3: Statements 369 1. It can cause the assignment of data opened in the task for stream output from an external source (that is, from transmission. a data set) to one or more internal receiving fields (that is, to one or 9. The COPY option, which may only be more variables). used with the FILE(filename) option, specifies that the source data, as 2. It can cause the assignment of data read, is to be written, without from an internal source (that is, from alteration, on the standard a character-string variable) to one or installation print file. more internal receiving fields (that is, to one or more variables). 10. The SKIP option causes a new current line to be defined for the data set. General format: The expression, if present, is converted to an integer w, which must GET option-list; be greater than zero. If not, the F Compiler substitutes a value of 1. Following is the format of "option The data set is positioned at the list": start of the wth line relative to the current line. If the expression is FILE(filename) | STRING(character- omitted, SKIP(1) is assumed. The SKIP string-name) ] option is always executed before any [data-specification] [COPY] data is transmitted. [SKIP[(expression)]] Examples: General rules: 1. GET LIST (A,B,C); 1. If neither the FILE(filename) option nor the STRING(character-string-name) Specifies the list-directed option appears, the file option transmission of the values to be FILE(SYSIN) is assumed. assigned to A, B and C from the file SYSIN. 2. One data specification must appear unless the SKIP option is specified. 2. GET FILE (BETA) EDIT (X,Y,Z) (A(5), F(5,2), A(10)); 3. The options may appear in any order. Specifies the edit-directed 4. The filename refers to a file which transmission of the values assigned to has been associated, by opening, with X, Y and Z from file BETA. the data set which is to provide the values. It must be a STREAM INPUT file. 5. The "character-string name" refers to The GO TO Statement the character string that is to provide the data to be assigned to the data list. This name may be a reference to a built-in function. Function: Each GET operation using this option always begins at the beginning of the The GO TO statement causes control to be specified string. If the number of transferred to the statement identified by characters in this string is less than the specified label. the total number of characters specified by the data specification, General format: the ERROR condition is raised. GO TO label-constant; 6. When the STRING option is used under data-directed transmission, the ERROR GOTO element-label-variable; condition is raised if an identifier within the string does not have a General rules: match within the data specification. 1. If an "element label variable" is 7. The data specification is as described specified, the value of the label in Part I, Chapter 9, "Stream-Oriented variable determines the statement to Transmission." which control is transferred. Since the label variable may have different 8. If the FILE (filename) option refers values at each execution of the GO TO to a file that is not open in the statement, control may not always pass current task, the file is implicitly to the same statement. 370 2. A GO TO statement cannot pass control General rules: to an inactive block. 1. The element expression is evaluated 3. A GO TO statement cannot transfer and, if necessary, converted to a bit control from outside a DO-group to a string. When the ELSE clause (that statement inside the DO-group if the is, ELSE and its following "unit") is DO-group specifies repetitive specified, the following occurs: execution, unless the GO TO terminates a procedure or on-unit invoked from If any bit in the string is 1, within the DO-group. "unit-1" is executed, and control then passes to the statement 4. If a GO TO statement transfers control following the IF statement. If all from within a block to a point not bits in the string have the value contained within that block, the block 0, "unit-1" is skipped and "unit-2" is terminated, Also, if the transfer is executed, after which control point is contained in a block that did passes to the next statement. not directly activate the block being terminated, all intervening blocks in When the ELSE clause is not specified, the activation sequence are also the following occurs: terminated (see Part I, Chapter 6, "Blocks, Flow of Control, and Storage If any bit in the string is 1, Allocation," for examples and "unit-1" is executed, and control details). When one or more blocks are then passes to the statement terminated by a GO TO statement, following the IF statement. If all conditions are reinstated and bits are 0, "unit-1" is not automatic variables are freed just as executed and control passes to the if the blocks had terminated in the next statement. usual fashion. Each "unit" may contain statements 5. When a GO TO statement transfers that specify a transfer of control control out of a procedure that has (e.g., GO TO); hence, the normal been invoked as a function, the sequence of the IF statement may be evaluation of the expression that overridden. contained the corresponding function reference is discontinued. 2. IF statements may be nested; that is, either "unit", or both, may itself be an IF statement. Since each ELSE The IF Statement clause is always associated with the innermost unmatched IF in the same block or DO-group, an ELSE with a null statement may be required to specify a Function: desired sequence of control. The IF statement tests the value of a specified expression and controls the flow The LOCATE Statement of execution according to the result of that test. General fqrmat: Function: IF element-expression The LOCATE statement, which applies to THEN unit-1 BUFFERED OUTPUT files, causes allocation of [ELSE unit-2] a based variable in a buffer; it may also cause transmission of a previously Syntax rules: allocated based variable. 1. Each unit is either a single statement General format: (except DO, END, PROCEDURE, BEGIN, DECLARE, FORMAT, or ENTRY), a DO- LOCATE variable FILE(filename) group, or a begin block. [SET(pointer-variable)] [KEYFROM(expression)]; 2. The IF statement itself is not terminated by a semicolon; however, Syntax rules: each "unit" specified must be terminated by a semicolon. 1. The options may appear in any order. 3. Each "unit" may be labeled and may 2. The "variable" must be an have condition prefixes. unsubscripted level 1 based variable. Section J: Statements 371 General rules: statement is enabled for the CHECK condition, CHECK is raised whenever control 1. The FILE(filename) option specifies reaches the null statement. the file involved. This option must appear. General format: 2. Execution of a LOCATE statement causes [label:]...; the specified based variable to be allocated in the buffer. Oomponents of the based variable that have been specified in REFER options are The ON Statement initialized. A pointer value is assigned to the pointer variable named in the SET option or, if the SET Function: option is omitted, to the pointer variable specified in the declaration The ON statement specifies what action of the based variable. The pointer is to be taken (programmer-defined or value identifies the record in the standard system action) when an interrupt buffer. After execution of the LOCATE results from the occurrence of the statement, values may be assigned to specified exceptional condition. the based variable for subsequent transmission to the data set General format: associated with the file, which will cccur immediately before the next ON condition[SNAP]{SYSTEM;|on-unit} LOCATE, WRITE, or CLOSE operation on the file, at which time the record is Syntax rules: freed. 1. The condition may be any of those 3. If the KEYFROM(expression) option described in Section H, "ON- appears, the value of the expression Conditions". is converted to a character string and is used as the key of the record when 2. The "on-unit" represents a it is subsequently written. For the F programmer-defined action to be taken Compiler, this option must appear if when an interrupt results from the the specified file is TRANSIENT. occurrence of the specified "condition". It can be either a 4. If the FILE(filename) option refers to single unlabeled simple statement or an unopened file, the file is opened an unlabeled begin block. If it is an automatically; the effect is as if the unlabeled simple statement, it can be LOOATE statement were preceded by an any simple statement except BEGIN, DO, OPEN statement referring to the file. END, RETURN, FORMAT, PROCEDURE, or DECLARE. If the on-unit is an Example: unlabeled begin block, any statement can be used freely within that block, LOCATE ALPHA SET (REC_POINT) FILE with one exception: A RETURN statement (BETA); can appear only within a procedure nested within the begin block. The based variable ALPHA is allocated in a buffer and REC_POINT is set to 3. Since the "on-unit" itself requires a identify ALPHA in the buffer. Values semicolon, no semicolon is shown for may subsequently be assigned to ALPHA the "on-unit" in the general format. and the record will be written in the However, the word SYSTEM must be data set associated with file BETA followed by a semicolon. when a subsequent LOCATE or WRITE statement is executed for file BETA or General rules: if BETA is closed, either explicitly or implicitly. 1. The ON statement determines how an interrupt occurring for the specified condition is to be handled. Whether the interrupt is handled in a standard The Null Statement system fashion or by a programmer-supplied method is determined by the action specification Function: in the ON statement, as follows: The null statement causes no action and a. If the action specification is does not modify sequential statement SYSTEM, the standard system action execution. If the label of a null is taken. The standard system 372 action is not the same for every (and, hence, effectively, the condition, although for most procedure or block in which the conditions the system simply on-unit is executed) but, rather, to prints a message and raises the the environment of the invocation of ERROR condition. The standard the procedure or block in which the ON system action for each condition statement for that on-unit was is given in Section H, executed. (Remember that an ON "ON-Conditions." (Note that the statement is executed as it is standard system action is always encountered in statement flow; taken if an interrupt occurs and whereas, the action specification for no ON statement for the condition that ON statement is executed only is in effect.) when the associated interrupt occurs.) b. If the action specification is an 4. A condition raised during execution "on-unit," the programmer has results in an interrupt if and only if supplied his own the condition is enabled at the point interrupt-handling action, namely, where it is raised. the action defined by the statement(s) in the on-unit a. The conditions AREA, OVERFLOW, itself. The on-unit is not FIXEDOVERFLOW, UNDERFLOW, executed when the ON statement is ZERODIVIDE, CONVERSION, all of the executed; it is executed only when input/output conditions, and the an interrupt results from the conditions CONDITION, FINISH, and occurrence of the specified ERROR are enabled by default. condition (or if the interrupt results from the condition being b. The conditions SIZE, STRINGRANGE, signaled by a SIGNAL statement). SUBSCRIPTRANGE, and CHECK are disabled by default. 2. The action specification (i.e., "on-unit" or SYSTEM) established by c. The enabling and disabling of executing an ON statement in a given OVERFLOW, FIXED OVERFLOW, block remains in effect throughout UNDERFLOW, ZERODIVIDE, CONVERSION, that block and throughout all blocks SIZE, STRINGRANGE, SUBSCRIPTRANGE, in any activation sequence initiated and CHECK can be controlled by by that block, unless it is overridden condition prefixes. by the execution of another ON statement or a REVERT statement, as 5. If on-unit is a single statement, it follows: cannot refer to a remote format specification. a. If a later ON statement specifies the same condition as a prior ON 6. If SNAP is specified, then when the statement and this later ON given condition occurs and the statement is executed in a block interrupt results, a calling trace is that lies within the activation listed; that is, a trace of all of the sequence initiated by the block procedures active at the time the containing the prior ON statement, interrupt resulted is printed on the action specification f the SYSPRINT. prior ON statement is temporarily suspended, or stacked. It can be restored either by the execution of a REVERT statement, or by the termination of the block The OPEN Statement containing the later ON statement. b. If the later ON statement and the prior ON statement are internal to Function: the same invocation of the same block, the effect of the prior ON The OPEN statement opens a file by statement is completely nullified. associating a file name with a data set. It can also complete the specification of 3. An on-unit is always treated by the attributes for the file, if a complete set compiler as a procedure internal to of attributes has not been declared for the the block in which it appears. file being opened. (Conceptually, it is enclosed in PROCEDURE and END statements.) Any General format: names used in an on-unit do not belong to the invocation of the procedure or OPEN FILE(file-name)[options-group] block in which the interrupt occurred [,FILE(file-name)[options-group]]...; Section J: Statements 373 where "options group" is as follows; a line during subsequent operations on the file. New lines may be started by [DIRECT|SEQUENTIAL|TRANSIENT] use of the printing and control format [BUFFERED|UNBUFFERED] items or by options in a GET or PUT [STREAM|RECORD] statement. If an attempt is made to [INPUT|OUTPUT|UPDATE] position a file past the end of a line [KEYED] [EXCLUSIVE] before explicit action to start a new [BACKWARDS] line is taken, a new line is [TITLE (element-expression)] automatically started, and the file is [PRINT] positioned to the start of this new [LINESIZE(element-expression)] line. If no line size is given for a [PAGESIZE(element-expression)] PRINT file, an implementation-defined default is supplied. For the F Syntax rules: Compiler, this is 120 characters. 1. The INPUT, OUTPUT, UPDATE, STREAM, The LINESIZE option cannot be RECORD, DIRECT, SEQUENTIAL, TRANSIENT, specified for an INPUT file. The line BUFFERED, UNBUFFERED, KEYED, size taken into consideration whenever EXCLUSIVE, BACKWARDS, and PRINT a SKIP option appears in a GET options specify attributes that statement is the line size that was augment the attributes specified in used to create the data set, if any; the file declaration; for rules otherwise, the line size is taken to governing which of these attributes be the current length of the logical can be applied together, see Part I, record (minus control bytes, for Chapter 8, "Input and Output," and the variable-length records). The maximum corresponding attributes in Section I, linesize for V format records is "Attributes." 32,751 and for U,F format records is 32,759. 2. The options in an "options group" and the FILE option for a file may appear 4. The PAGESIZE option can be specified in any order. only for a file having the STREAM and PRINT attributes. The element 3. The "file name" is the name of the expression is evaluated and converted file that is to be associated with a to an integer, which represents the data set. Several files can be opened maximum number of lines to a page. by one OPEN statement. During subsequent transmission to the PRINT file, a new page may be started General rules: by use of the PAGE format item or by the PAGE option in the PUT statement. 1. The opening of an already open file If a page becomes filled and more data does not affect the file if the second remains to be printed before action to opening takes place in the same task start a new page is taken, the ENDPAGE or an attached task. In such cases, condition is raised. For the F any expressions in the "options_group" Compiler, the maximum size of a page are evaluated, but they are not used. is 32,767 lines; the minimum is 1 line. If PAGESIZE is not specified, 2. If the TITLE option is specified, the the default is 60 lines per page. "element expression" is converted to a character string, if necessary, the first eight characters of which identify the data set (the ddname) to The PROCEDURE Statement be associated with the file. If this option does not appear, the first eight characters of the file name (padded or truncated) are taken to be Function: the ddname. Note that this is not the same truncation as that for external The PROCEDURE statement has the names. If the file name is a following functions: parameter, the identifier of the original argument passed to the • It heads a procedure. parameter, rather than the identifier of the parameter itself, is used as • It defines the primary entry point to the identification. the procedure. 3. The LINESIZE option can be specified • It specifies the parameters, if any, only for a STREAM OUTPUT file. The for the primary entry point. expression is evaluated, converted to an integer, and used as the length of • It may specify certain special 374 characteristics that a procedure can procedure must have the OPTIONS (MAIN) have. designation; if more than one is so designated, the operating system will • It may specify the attributes of the invoke the one that appears first, value that is returned by the procedure physically. (If multitasking is to be if it is invoked as a function at its used, the external procedure must also primary entry point. have the keyword TASK in the OPTIONS attribute.) OPTIONS applies to all of General format: the entry points (both primary and secondary) that the procedure for entry-name: [entry-name:]... which it has been declared might have. PROCEDURE[(parameter[,parameter]...)] [OPTIONS (option-list)] 3. RECURSIVE must be specified if the [RECURSIVE] [RETURNS (attribute...)] procedure might be invoked [ORDER|REORDER]; recursively; that is, if it might be re-activated while it is still active. Syntax rules: If specified, it applies to all of the entry points (primary and secondary) 1. The RETURNS option specifies the that the procedure might have. It attributes of the value returned by applies only to the procedure for the procedure when it is invoked as a which it is declared. function at its primary entry point. Only arithmetic, string, pointer, 4. The RETURNS option specifies the offset, AREA, and PICTURE attributes attributes of the value returned by are allowed. the procedure when it is invoked as a function at its primary entry point. 2. OPTIONS and RECURSIVE are special The value specified in the RETURN procedure specifications that the user statement of the invoked procedure is can specify. They and the other converted to conform with these PL/I-defined options may appear in any attributes before it is returned to order and are separated by blanks. the invoking procedure. 3. The "option list" of OPTIONS specifies If the RETURNS option is omitted, one or more additional implementation- default attributes are supplied. In defined options. For the F Compiler, such a case, the name f the entry the "option list" may contain the MAIN point (the entry name by which the and TASK options, separated by commas. procedure has been invoked) is used to MAIN specifies that the procedure is determine the default base, precision, the initial procedure, to be invoked and scale. (Since the entry point can by the operating system as the first have several entry names, the default step in the execution of the PL/I base, precision, and scale can differ program; TASK specifies that the according to the entry name.) multitasking facilities are to be used. 5. If a PROCEDURE statement has more than one entry name, the first name can be 4. ORDER and REORDER are options used to considered as the only label of the control the optimization performed by statement; each subsequent entry name the compiler. The selected option can be considered as a separate ENTRY applies to all nested blocks unless statement having the same parameter overridden. (These options are also list and RETURNS option as the allowed on BEGIN statements.) If PROCEDURE statement. For example, the neither option is given for an statement: external procedure, ORDER is assumed. A: I: PROCEDURE RETURNS(BINARY FIXED); General rules: is effectively the same as: 1. When the procedure is invoked, a relationship is established between A: PROCEDURE RETURNS(BINARY FIXED); the arguments passed to the procedure and the parameters that represent I: ENTRY RETURNS(BINARY FIXED); those arguments in the invoked procedure. This topic is discussed in 6. The ORDER and REORDER options specify, Part I, Chapter 12, "Subroutines and for optimization purposes, the degree Functions." of language stringency to be observed during compilation of the block. The 2. For the F Compiler, OPTIONS may be strict rules require that the source specified only for an external program should be compiled so as to be procedure, and at least one external executed in the order specified by the Section J: Statements 375 sequence of the statements in the on-unit into the block, except for source program, (see "Control values modified by the ONCHAR and Statements" in Chapter 5, "Statement ONSOURCE pseudo-variables. Classification"), even if the code could be reordered so as to produce A program is in error if a the same result more efficiently. The computational or system action relaxation allowed by REORDER is such interrupt occurs during the execution that if computational or system action of the block and this interrupt is interrupts occur during execution of followed by a reference to a variable the block, the result is not whose value is not guaranteed in such necessarily the same as it would be circumstances. under the strict rules. (See also Chapter 17: "Optimization and 7. The ORDER option specifies that the Efficient Performance.") normal language rules are not to be relaxed; i.e., any optimization must be such that the execution of a block always produces a result that is in The PUT Statement accordance with the strict definition of PL/I. This means that the values of variables set by execution of all Function: statements prior to computational or system action interrupts are The PUT statement is a STREAM guaranteed in an on-unit entered as a transmission statement that can be used in result of the interrupt, or anywhere either of the following ways: in the program afterwards. Note that the strict definition now allows the 1. It can cause the values in one or more compiler to optimize common internal storage locations to be expressions, where safely possible, by transmitted to a data set on an evaluating them once only and saving external medium. the result, rather than re-evaluating for each reference. (A common 2. It can cause the values in one or more expression is an expression that internal storage locations to be cccurs more than once in a program but assigned to an internal receiving is obviously intended to result in the field (represented by a same value each time that it is character-string variable). evaluated, i.e., if a later expression is identical to an earlier expression, General format: with no intervening modification to any operand, the expressions are said PUTT FILE (file-name) to be common.) [STRING (character-string-variable) [data-specification] 8. The REORDER option specifies that PAGE [LINE(element-expression)] execution of the block must produce a SKIP [(element-expression)] result that is in accordance with the [LINE(element-expression) strict definition of PL/I unless a computational or system action Syntax rules: interrupt occurs during execution of the block; the result is then allowed 1. If neither the FILE nor STRING option to deviate as follows: appears, the specification FILE (SYSPRINT) is assumed. If such a PUT a. After a computational or system statement lies within the scope of a action interrupt has occurred declaration of the identifier during execution of the block, the SYSPRINT, SYSPRINT must have been values of variables modified, declared as FILE STREAM OUTPUT. If allocated, or freed in the block the PUT statement does not lie within are guaranteed only after normal the scope of a declaration of return from an on-unit or when SYSPRINT, SYSPRINT is the standard accessed by the ONCHAR and system output file. ONSOURCE condition built-in functions. 2. The FILE option specifies transmission to a data set on an external medium. b. The values of variables modified, The file name in this option is the allocated, or freed in an on-unit name of the file that has been for a computational or system associated (by implicit or explicit action condition (or in a block opening) with the data set that is to activated by such an on-unit) are receive the values. This file must not guaranteed on return from the have the OUTPUT and STREAM attributes. 376 3. The STRING option specifies the start of the wth line relative to transmission from internal storage the current line. If the expression locations (represented by variables or is omitted, SKIP(1) is assumed. expressions in the "data specification") to a character string For PRINT files w may be less than or (represented by the "character-string equal to zero; in this case, the variable"). The "character-string effect is that of a carriage return variable" can be a string with the same current line. If less pseudo-variable. than w lines remain on the current page when a SKIP(w) is issued, ENDPAGE is raised. 4. The "data specification" option is as described in Part I, Chapter 9, 6. The LINE option causes a new current "Stream-Oriented Transmission." line to be defined for the data set. The expression is converted to an 5. The PAGE, SKIP, and LINE options integer w. The LINE option specifies cannot appear with the STRING option. that blank lines are to be inserted so that the next line will be the wth 6. The options may appear in any order; line of the current page. If at least at least one must appear. w lines have already been written on the current page or if w exceeds the General rules: limits set by the PAGESIZE option of the OPEN statement, the ENDPAGE 1. If the FILE option is specified, and condition is raised. If w is less the "file name" refers to an unopened than or equal to zero, it is assumed file, the file is opened implicitly as to be 1. an OUTPUT file. 7. If the FILE(filename) option refers to 2. If the STRING option is specified, the a file that is not open in the current PUT operation begins assigning values task, the file is opened implicitly in to the beginning of the string (that this task for stream output. is, at the left-most character position), after appropriate Examples: conversions have been performed. Blanks and delimiters are inserted as 1. PUT DATA (A,B,C); usual. If the string is not long enough to accommodate the data, the Specifies the data-directed ERROR condition is raised. transmission of the values A, B and C to the file SYSPRINT. 3. The PAGE and LINE options can be specified for PRINT files only. All 2. PUT FILE (LIST) EDIT (X,Y,Z) (A(10)) of the options take effect before PAGE; transmission of any values defined by the data specification, if given. Of Specifies that a new page is to be the three, only PAGE and LINE may defined for the print file LIST. The appear in the same PUT statement, in values f X, Y and Z are placed which case, the PAGE option is applied starting in the first printing first. position of the new page. Each of the values will use the A(10) format item. 4. The PAGE option causes a new current page to be defined within the data set. If a data specification is present, the transmission f values occurs after the definition of the new The READ Statement page. The page remains current until the execution of a PUT statement with the PAGE option, until a PAGE format Function: item is encountered, or until an END-PAGE interrupt results in the The READ statement causes a record to be definition of a new page. A new transmitted from a RECORD INPUT or RECORD current page implies line one. UPDATE file to a variable or buffer. 5. The SKIP option causes a new current General format: line to be defined for the data set. The expression, if present, is READ option-list; converted to an integer w, which for non-PRINT files must be greater than The format of "option list" is shown in zero. The data set is positioned at Figure J-3. Section J: Statements 377 Figure J-3. Format of Option List for READ Statement General rules: is TRANSIENT.) It specifies that the key of the record being read is to be 1. The options may appear in any order. assigned to the "character-string variable" according to the rules for 2. The FILE(filename) option specifies character-string assignment. If the file from which the record is to proper assignment cannot be made, the be read. This option must appear. If KEY condition is raised. For the F the file specified is not open in the Compiler, the value assigned is as current task, it is opened. follows: 3. The INTO(variable) option specifies an unsubscripted level 1 variable into a. For REGIONAL (1), the eight which the record is to be read. It character region number, padded or cannot be a parameter, nor can it have truncated on the left to the the DEFINED attribute. For TRANSIENT declared length of the files, either the INTO option or the character-string variable SET option must appear. b. For REGIONAL (2) and REGIONAL (3), 4. If the variable in the FROM or INTO the recorded key without the option is a structure, it cannot region number, padded or truncated contain VARYING strings. However it on the right to the declared is possible to have a VARYING string length of the character-string element variable in these options. variable This is an implementation restriction. c. For INDEXED, the recorded key, 5. The KEY and KEYTO options can be padded or truncated on the right specified for KEYED files only. to the declared length of the character-string variable 6. The KEY option must appear if the file has the DIRECT attribute. The The KEY condition will not be raised "expression" is converted to a for such padding or truncation. character string that represents a key. It is this key that determines Note: The KEYTO option cannot specify which record will be read. a variable declared with a numeric picture specification. The KEY option may also appear for files having the SEQUENTIAL and KEYED 8. The EVENT option allows processing to attributes. In such cases, the file continue while a record is being read is positioned to the record having the or ignored. This option cannct be specified key. Thereafter, records specified for a BUFFERED file. may be read sequentially from that point on by using READ statements When control reaches a READ statement withcut the KEY option. For containing this option, the "event System/360 implementations, the data variable" is made active (that is, it set must have the INDEXED cannot be associated with another organization. For the F Compiler, the event) and is given the completion KEY option cannot appear if the FILE value '0'B, provided that the is TRANSIENT. UNDEFINEDFILE condition is not raised by an implicit file opening (see 7. The KEYTO option can be given only if "Note" below). The event variable the file has the SEQUENTIAL KEYED or remains active and retains its '0'B TRANSIENT KEYED attributes. (For the completion value until control reaches F Compiler, it must appear if the file a WAIT statement specifying that event 378 variable. At this time, either of the statement for the file specified following can occur: in the locking READ statement; a. If the READ statement has been c. The locking task is completed. executed successfully and none of the conditions ENDFILE, TRANSMIT, Note that a record is considered KEY or RECORD has been raised as a locked only for tasks other than the result of the READ, the event task that actually locks it; in other variable is set complete (given words, a locked record can always be the completion value '1'B) and is read by the task that locked it and made inactive, that is, it can be still remain locked as far as other associated with another event. tasks are concerned (unless, of course, the record has been explicitly b. If the READ statement has resulted unlocked by one of the above methods). in the raising of ENDFILE, TRANSMIT, KEY, or RECORD, the 10. The SET option specifies that the interrupt for each of these record is to be read into a buffer and conditions does not occur until that a pointer value is to be assigned the WAIT is encountered. At such to the named pointer variable. The time, the corresponding on-units pointer value identifies the record in (if any) are entered in the order the buffer. For TRANSIENT files, in which the conditions were either the SET option or the INTO raised. After a return from the option must appear. final on-unit, or if one of the on-units is terminated by a GO TO 11. The IGNORE option may be specified for statement, the event variable is SEQUENTIAL INPUT and SEQUENTIAL UPDATE given the completion value '1'B files. The expression in the IGNORE and is made inactive. option is evaluated and converted to an integer. If the value, n, is Note: If the READ statement causes an greater than zero, n records are implicit file opening that results in ignored; a subsequent READ statement the raising of UNDEFINEDFILE, the for the file will access the (n+1)th on-unit associated with this condition record. A READ statement without an is entered immediately and the event INTO, SET, or IGNORE option is variable remains unchanged; that is, equivalent to a READ with an the event variable remains inactive IGNORE(1). and retains the same value it had when the READ was encountered. If the 12. An INDEXED data set that is accessed on-unit does not correct the , by a KEYED SEQUENTIAL INPUT file or a condition, then, upon normal return KEYED SEQUENTIAL UPDATE file may be from the on-unit, the ERROR condition positioned by issuing a READ statement is raised; if the condition is with the KEY option. The specified corrected in the on-unit, that is, if key will be used to identify the the file is opened successfully, then, record required. Thereafter, records upon normal return from the on-unit, may be read sequentially from that the event variable is set to '0 ' B, it point by use of READ statements is made active, and execution of the without the KEY option. READ statement continues. For BUFFERED SEQUENTIAL files, two 9. Any READ statement referring to an positioning statements can be used, EXCLUSIVE file will cause the record with the following formats: to be locked unless the NOLOCK option is specified. A locked record cannot READ FILE (filename) be read, deleted, or rewritten by any INTO (variable) other task until it is unlocked. Any KEY (expression); attempt to read, delete, rewrite, or unlock a record locked by another task READ FILE (filename) results in a wait. Subsequent SET (pointer-variable) unlocking occurs as a result of one of KEY (expression); the following actions: For UNBUFFERED SEQUENTIAL files, a. The locking task executes an only the first form shown immediately UNLOCK, REWRITE, or DELETE above can be used, and it may be statement that specifies the same specified with the EVENT option. file name and key as the locking READ statement; 13. If, at the time of execution of a READ statement for a TRANSIENT file, no b. The locking task executes a CLOSE data is available for transmission Section J: Statements 379 (i.e., the message queue associated completion value of the associated with the file is empty), the PENDING event variable (if any) is set to condition is raised. Standard system '1'B, and the status value is left action for this condition is to wait unchanged. until data is available before resuming execution of the READ 2. The RETURN statement in Option 2 is statement. used to terminate a procedure invoked as a function procedure only. Control Examples: is returned to the point of invocation, and the value returned to 1. READ FILE (ALPHA) SET (RECIDENT); the function reference is the value of the expression specified converted to The next record from the data set conform to the attributes declared for associated with ALPHA is made the invoked entry point. These available and the pointer variable attributes may be explicitly specified REC_IDENT is set to identify the at the entry point; they are otherwise record in the buffer. implied by the initial letter of the entry name through which the procedure 2. READ FILE (BETA) KEY (VALUE) INTO is invoked. (WORK); 3. If control reaches an END statement The record identified by the key VALUE corresponding to the end of a is transmitted from the data set procedure, this END statement is associated with BETA into the variable treated as a RETURN statement (of the WORK. Option 1 form) for the procedure. Example: The RETURN Statement A: PROCEDURE (X,Y) RETURNS (FIXED); DECLARE (X,Y) FLOAT; Function: The RETURN statement terminates RETURN (X**2+Y**2); execution of the procedure that contains END; the RETURN statement. If the procedure has B: PROCEDURE; not been invoked as a task, the RETURN DECLARE A ENTRY RETURNS (FIXED); statement returns control to the invoking procedure. The RETURN statement may also return a value. R = A(P,Q); General format: Option 1. END; RETURN; In the assignment statement (R=A(P,Q);), Option 2. procedure B invokes procedure A as a function. Procedure B specifies that the RETURN (expression); element expression in the RETURN statement is to be evaluated; since X and Y are General rules: floating-point variables and the RETURNS option of the PROCEDURE statement specifies 1. Only the RETURN statement in Option 1 that the value returned is to be can be used to terminate procedures fixed-point, the value of the expression is not invoked as function procedures; converted to fixed-point, and this value is control is returned to the point returned to B. logically following the invocation. Option 1 represents the only form of the RETURN statement that can be The REVERT Statement used to terminate a procedure initiated as a task. If the RETURN statement terminates the major task, the FINISH condition is raised prior Function: to the execution of any termination processes. If the RETURN statement The REVERT statement is used to cancel terminates any other task, the the effect of one or more previously 380 executed ON statements. It can affect only the record that will replace the ON statements that are internal to the existing record in the data set. block in which the REVERT statement occurs and which have been executed in the same General rules: invocation of that block. Execution of the REVERT statement in a given block cancels 1. If the file whose name appears in the the action specification of any ON FILE specification has not been statement for the named condition that has opened, it is opened implicitly with been executed in that block; it then the attributes RECORD and UPDATE. re-establishes the action specification that was in force at the time of activation 2. The KEY option must appear if the file of the block. has the DIRECT attribute; it cannot appear otherwise. The General format: element-expression is converted to a character string. This character REVERT condition; string is the source key that determines which record is to be Syntax rule: rewritten. For SEQUENTIAL files associated with INDEXED data sets in The "condition" is any of those System/360 implementations, the key described in Section H, "ON-Conditions." must be the same as the one it replaces. General rule: 3. The FROM option must be specified for The execution of a REVERT statement has UPDATE files having either the DIRECT the effect described above only if (1) an attribute or both the SEQUENTIAL and ON statement, specifying the same condition UNBUFFERED attributes. A REWRITE and internal to the same block, was statement in which the FROM option has executed after the block was activated and not been specified has the following (2) the execution of no other similar effect: if the last record was read by REVERT statement has intervened. If either a READ statement with the INTO option, of these two conditions is not met, the REWRITE without FROM has no effect on REVERT statement is treated as a null the record in the data set; if the statement. last record was read by a READ statement with the SET option, the record will be updated by whatever assignments were made in the buffer The REWRITE Statement identified by the pointer variable in the SET option. 4. If the variable in the FROM or INTO Function: option is a structure, it cannot contain VARYING strings. However it The REWRITE statement can be used only is possible to have a VARYING string for update files. It replaces an existing element variable in these options. record in a data set. This is an implementation restriction. General format: 5. The EVENT option allows processing to continue while a record is being REWRITE FILE (file-name) rewritten. This option cannot be [FROM(variable)] specified for a SEQUENTIAL BUFFERED [KEY (element-expression)] file. [EVENT (event-variable)] When control reaches a REWRITE Syntax rules: statement containing this option, the event variable is made active (that 1. The options may appear in any order. is, it cannot be associated with another event) and is given the 2. The "FILE (file-name)" option completion value '0'B, provided that specifies the name of the file, which the UNDEFINEDFILE condition is not must have the UPDATE attribute. raised by an implicit file opening (see "Note" below). The event 3. The "variable" in the FROM option must variable remains active and retains be an unsubscripted level 1 variable its '0 ' B completion value until (that is, a variable not contained in control reaches a WAIT statement an array or structure). It cannot specifying that event variable. At have the DEFINED attribute and it this time, either of the following can cannot be a parameter. It represents occur: Section J: Statements 381 a. If the REWRITE statement has been Syntax rule: executed successfully and none of the conditions TRANSMIT, KEY, or The "condition" is any one of those RECORD has been raised as a result described in Section H, "ON-Conditions." of the REWRITE, the event variable is set complete (given the General rules: completion value '1 ' 13), and the event variable is made inactive 1. When a SIGNAL statement is executed, (that is, it can be associated it is as if the specified condition with another event). has actually occurred. Sequential execution is interrupted and control b. If the REWRITE statement has is transferred to the current on-unit resulted in the raising of for the specified condition. After TRANSMIT, KEY, or RECORD, the the on-unit has been executed, control interrupt for each of these normally returns to the statement conditions does not occur until immediately following the SIGNAL the WAIT is encountered. At such statement. time, the corresponding on-units (if any) are entered in the order 2. The on-condition CONDITION can cause in which the conditions were an interrupt only as a result of its raised. After a return from the specification in a SIGNAL statement. final on-unit, or if one of the on-units is terminated by a GO TO 3. If the specified condition is statement, the event variable is disabled, no interrupt occurs, and the given the completion value '1'B SIGNAL statement becomes equivalent to and is made inactive. a null statement. Note: If the REWRITE statement causes 4. If there is no current on-unit for the an implicit file opening that results specified condition, then the standard in the raising of UNDEFINEDFILE, the system action for the condition is on-unit associated with this condition performed. is entered immediately and the event variable remains unchanged, that is, the event variable remains inactive and retains the same value it had when the REWRITE was encountered. If the The STOP Statement on-unit does not correct the condition, then, upon normal return from the on-unit, the ERROR condition is raised; if the condition is Function: corrected in the on-unit, that is, if the file is opened successfully, then, The STOP statement causes immediate upon normal return from the on-unit, termination of the major task and all the event variable is set to '0'B, it sub-tasks is made active, and execution of the REWRITE statement continues. General format: 6. If the record rewritten is one that STOP; was locked in the same task, it becomes unlocked. General rule: Prior to any termination activity the FINISH condition is raised in the task in which the STOP is executed. On normal The SIGNAL Statement return from the FINISH on-unit, all tasks in the program are terminated. Function: The UNLOCK Statement The SIGNAL statement simulates the occurence of an interrupt. It may be used to test the current action specification for the associated condition. Function: General format: The UNLOCK statement makes the specified locked record available to other tasks for SIGNAL condition; operations on the record. 382 General format: converted to an integer. This integer specifies the number of events in the UNLOCK option-list; list that must satisfy the above condition before control for the block Following is the format of "option passes to the statement following the list": WAIT. Of course, if an on-unit entered due to the WAIT is terminated FILE(filename) KEY(expression) abnormally, control might not pass to the statement following the WAIT. General rules: If the value of the expression is 1. The options may appear in either zero or negative, the WAIT statement order. is treated as a null statement. If the value of the expression is greater 2. The FILE(filename) option specifies than the number, n, of event names in the file involved, which must have the the list, the value is taken to be n. attributes UPDATE, DIRECT, and If the statement refers to an array EXCLUSIVE. event name, then each f the array elements contributes to the count. 3. In the KEY(expression) option, the "expression" is converted to a 4. If the event variable named in the character string and determines which list has been associated with a task record is unlocked. in its attaching CALL statement, then the condition in Rule 1 will be 4. A record can be unlocked only by the satisfied on termination of that task. task which locked it. 5. If the event variable named in the list is associated with an input/output operation initiated in The WAIT statement the same task as the WAIT, the condition in Rule 1 will be satisfied when the input/output operation is Function: completed. The execution f the WAIT is a necessary part of the completion The execution of a WAIT statement within of an input/output operation. If an activation f a block retains control prior to, or during, the WAIT all for that activation of that block within transmission associated with the the WAIT statement until certain specified input/output operation is terminated, events have completed. then the WAIT performs the following action: If the transmission has General format: finished without requiring any input/output conditions to be raised, WAIT (event-name [,event-name]...) the event variable is set complete [(element-expression)]; (i.e., COMPLETION(event name) = '1'B). If the transmission has been General rules: terminated but has required conditions to be raised, the event variable is 1. Control for a given block activation set abnormal (i.e., STATUS(event remains within this statement until, name) = 1) and all the required ON at possibly separate times during the conditions are raised. On return from execution of the statement, the the last on-unit, the event variable condition. is set complete. COMPLETION(event-name) = '1'B has been satisfied, for some or all of 6. The order in which ON conditions for the event names in the list. different input/output events are raised is not dependent on the order 2. If the optional expression does not of appearance of the event names in appear, all the event names in the the list. If an ON condition for one list must satisfy the above condition event is raised, then all other before control returns to the next conditions for that event are raised statement in this task following the before the WAIT is terminated or WAIT. before any other input/output conditions are raised unless an 3. If the optional expression appears, abnormal return is made from one of the expression is evaluated when the the on-units thus entered. The WAIT statement is executed and raising of ON conditions for one event Section J: Statements 383 implies nothing about the completion The WRITE Statement or termination of transmission of other events in the list. Function: The WRITE statement is a RECORD transmission statement that transfers a 7. If an abnormal return is made from any record from a variable in internal storage on-unit entered from a WAIT, the to an OUTPUT or UPDATE file. associated event variable is set complete, the execution of the WAIT is terminated, and control passes to the General format: point specified by the abnormal return. WRITE FILE (file-name) FROM (variable) [KEYFROM(element-expression) [EVENT(event-variable)]; 8. If the user wishes to specify more than one event name in a WAIT Syntax rules: statement, the multiple-wait option must have been specified at SYSGEN 1. The FILE and FROM specifications and time. the KEYFROM and EVENT options may appear in any order. 9. If a WAIT statement is executed and the events required to satisfy the 2. The "file name" specifies the file in WAIT contain a mixture of input/output which the record is to be written. and non-input/output events all This file must be a RECORD file that non-input/output events will be set has either the OUTPUT attribute or the complete before any of the DIRECT and UPDATE attributes. input/output events. 3. The "variable" in the FROM specification must be an unsubscripted level 1 variable (i.e., a variable not 10. If some of the event names in the WAIT contained in an array or structure). list are associated with input/output It cannot have the DEFINED attribute operations and have not been set and it cannot be a parameter. It complete before the WAIT is terminated contains the record to be written. (either because enough events have been completed or due to an abnormal General rules: return), then these incomplete events will not be set complete until the 1. If the file is not open, it is opened execution of another WAIT referring to implicitly with the attributes RECORD these events in this same task. and OUTPUT (unless UPDATE has been declared). Example: 2. If the KEYFROM option is specified, PI: PROCEDURE; the "element expression" is converted to a character string. This character string is the source key that specifies the relative location in the CALL P2 EVENT(EP2); data set where the record is written. For REGIONAL (2), REGIONAL (3), and INDEXED data sets, KEYFROM also specifies a recorded key whose length WAIT(EP2); is determined by the KEYLEN subparameter. For the F Compiler, this option must appear if the file is TRANSIENT. END; 3. The EVENT option allows processing to The CALL statement, when executed, continue while a record is being attaches a task whose completion written. This option cannot be status is associated with the event specified for a TRANSIENT or name EP2. When the WAIT statement is SEQUENTIAL BUFFERED file. encountered, the execution of the task is suspended until the value of The EVENT option should not be used on EVENT(EP2) is '1'B, i.e., until the a WRITE statement if V or U format attached task is completed. records are being added to a 384 REGIONAL(3) data set which is being the event variable is set to '0'B, it accessed in a direct update mode. is made active, and execution of the WRITE statement continues. When control reaches a WRITE statement containing this option, the "event variable" is made active (that is, it cannot be associated with another Preprocessor Statements event) and is given the completion value '0'B, provided that the UNDEFINEDFILE condition is not raised All of the statements that can be executed by an implicit file opening (see at the preprocessor stage are presented "Note" below). The event variable alphabetically in this section. remains active and retains its '0'B completion value until control reaches a WAIT statement specifying that event variable. At this time, either of the The %ACTIVATE Statement following can occur: a. If the WRITE statement has been executed successfully and none of Function: the conditions TRANSMIT, KEY, or RECORD has been raised as a result The appearance of an identifier in a of the WRITE, the event variable %ACTIVATE statement makes it active and is set complete (given the eligible for replacement; that is, any completion value '1'B), and the subsequent encounter of that identifier in event variable is made inactive, a nonpreprocessor statement, while the that is, it can be associated with identifier is active, will initiate another event. replacement activity. b. If the WRITE statement has General format: resulted in the raising of TRANSMIT, KEY, or RECORD, the %[label:]... ACTIVATE identifier interrupt for each of these [,identifier]...; conditions does not occur until the WAIT is encountered. At such Syntax rules: time, the corresponding on-units (if any) are entered in the order 1. Each identifier must be either a in which the conditions were preprocessor variable or a raised. After a return from the preprocessor procedure name. final on-unit, or if one of the on-units is terminated by a GO TO 2. A %ACTIVATE statement cannot appear statement, the event variable is within a preprocessor procedure. given the completion value ('1'B) and is made inactive. General rules: 4. If the variable in the FROM or INTO 1. An identifier cannot be activated option is a structure, it cannot initially by a %ACTIVATE statement; contain VARYING strings. However it the appearance of that identifier in a is possible to have a VARYING string %DECLARE statement serves that element variable in these options. purpose. An identifier can be This is an implementation restriction. activated by a %ACTIVATE statement only after it has been deactivated by Note: If the WRITE statement causes an a %DEACTIVATE statement. implicit file opening that results in the raising of UNDEFINEDFILE, the 2. When an identifier is active (and has on-unit associated with this condition been given a value -- if it is a is entered immediately and the event preprocessor variable) any encounter variable remains unchanged; that is, of that identifier within a the event variable remains inactive nonpreprocessor statement will and retains the same value it had when initiate replacement activity in all the WRITE was encountered. If the cases except when the identifier on-unit does not correct the appears within a comment or within condition, then, upon normal return single quotes. from the on-unit, the ERROR condition is raised; if the condition is Example: corrected in the on-unit, that is, if the file is opened successfully, then If the source program contains the upon normal return from the on-unit, following sequence of statements: Section J: Statements 385 % DECLARE I FIXED, T CHARACTER; of course, the identifier has been reactivated in the interim). % DEACTIVATE I; General format: % I = 15; %[label:]... DEACTIVATE identifier % T = 'A(I)'; [,identifier]...; S = I*T*3; Syntax rules: % I = I+5; % ACTIVATE I; 1. Each "identifier" must be either a preprocessor variable, the SUBSTR % DEACTIVATE T; built-in function, or a preprocessor procedure name. R = I*T*2; then the preprocessed text generated by the 2. A %DEACTIVATE statement cannot appear above would be as follows (replacement within a preprocessor procedure. blanks are not shown): General rule: S = I*A(I)*3; The deactivation of an identifier does R = 20*T*2; not strip it of its value, nor does it prevent it from receiving new values in subsequent preprocessor statements. Deactivation simply prevents any replacement for a particular identifier from taking place. The % Assignment Statement Function: The %DECLARE Statement The % assignment statement is used to evaluate preprocessor expressions and to assign the result to a preprocessor Function: variable. The %DECLARE statement establishes an General format: identifier as a preprocessor variable or a preprocessor procedure name and also serves %[label:]... preprocessor-variable = to activate that identifier. An identifier preprocessor-expression; must appear in a %DECLARE statement before it can be used as a variable or a procedure General rule: name in any other preprocessor statement. When the value assigned to a General format: preprocessor variable is a character string, this character string should not The general format is shown in Figure contain a preprocessor statement, nor J-4. should it contain unmatched comment or string delimiters. Syntax rules: 1. CHARACTER or FIXED must be specified The %DEACTIVATE Statement if the "identifier" is a preprocessor variable; an entry declaration must be specified if the "identifier" is a Function: preprocessor procedure name. The appearance of an identifier in a 2. Only the attributes shown in the above %DEACTIVATE statement makes it inactive and format can be specified in a %DECLARE ineligible for replacement; that is, any statement. subsequent encounter of that identifier in a nonpreprocessor statement will not 3. Factoring of attributes is restricted initiate any replacement activity (unless, to no more than three. Figure J-4. General Format of the %DECLARE Statement 4. Any label attached to a %DECLARE additional parameter must be kept by a statement is ignored by the scan. comma. Thus, ENTRY („FIXED) specifies three parameters, the third General rules: of which has the attribute FIXED; the preprocessor makes no assumptions about the attributes of the first two. 1. No length can be specified with the CHARACTER attribute. If CHARACTER is The RETURNS attribute specifies the specified, it is assumed that the attribute of the value to be returned associated identifier represents a by the preprocessor procedure to the varying-length character string that point of invocation. If, in fact, the has no maximum length. attribute of the value does not agree with the attribute specified by 2. A preprocessor declaration is not RETURNS, no conversion is performed known until it has been encountered by and errors may result. the scan. If a reference to a preprocessor variable or procedure is See "Preprocessor Procedures" in Part encountered in a preprocessor I, Chapter 16, "Compile-Time statement before the declaration for Facilities," for a discussion of the that variable or procedure has been above attributes, as well as a scanned, then the reference is in discussion of the association of error. arguments and parameters at the time of invocation. 3. The scope of all preprocessor variables, procedure names, and labels 5. After a %DECLARE statement has been is the entire source program scanned executed, it is replaced by a null by the preprocessor, not including any statement so that any subsequent preprocessor procedures that redeclare scanning through the statement has no such identifiers. The scope of a effect. declaration in a preprocessor procedure is limited to that procedure. 4. An entry declaration must be specified The %DO Statement for each preprocessor procedure in the source program. The ENTRY attribute specifies the number (and attributes, Function: if desired) of the parameters of the procedure; the RETURNS attribute The %DO statement is used in conjunction specifies the attribute of the value with a %END statement to delimit a returned by that procedure. preprocessor DO-group. It cannot be used in any other way. The ENTRY attribute in the entry declaration must account for every General format: parameter specified in the %PROCEDURE statement of the preprocessor procedure. If the procedure has no parameters, ENTRY must be specified without the parenthesized list following; if the procedure has one Syntax rule: parameter, ENTRY followed by empty closed parentheses -- ENTRY () -- will The "i" represents a preprocessor suffice; if the procedure has more variable, and "ml," "m2," and "m3" are than one parameter, the place of each preprocessor expressions. Section J: Statements 387 General rule: 2. A preprocessor GO TO statement appearing within a preprocessor procedure cannot transfer control to a The expansion of a preprocessor DO-group point outside of that procedure. In is the same as the expansion for a other words, the label following GO TO corresponding nonpreprocessor DO-group and must be contained within the "i," "ml," "m2," and "m3" have the same procedure. meaning that the corresponding expressions in a nonpreprocessor DO-group have. 3. See "The %INCLUDE Statement" for a restriction regarding the use of %GO See "Preprocessor DO-Groups" in Part I, TO with included text. Chapter 16, "Compile-Time Facilities," for a discussion and an example of its use. The %IF Statement The %END Statement Function: The %IF statement can control the flow Function: of the scan according to the value of a preprocessor expression. The %END statement is used in conjunction with %DO or %PROCEDURE statements to delimit preprocessor General format: DO-groups or preprocessor procedures. %[label:]...IF preprocessor-expression General format: %THEN preprocessor-clause-1 % [label:]... END [label]; [%ELSE preprocessor-clause-2] Syntax rule: The label following END must be a label Syntax rule: of a %PROCEDURE or %DO statement. Multiple closure is permitted. A preprocessor clause is any single preprocessor statement other than %DECLARE, %PROCEDURE, %END, or %DO (percent symbol included) op a preprocessor DO-group The %GO TO Statement (percent symbols included). Otherwise, the syntax is the same as that for non-preprocessor IF statements. Function: General rules: The %GO TO statement causes the 1. The preprocessor expression is preprocessor to continue its scan at the evaluated and converted to a bit specified label. string (if the conversion cannot be made, it is an error). If any bit in General format: the string has the value 1, clause-1 is executed and clause-2, if present, % [label:]... {GO TO|GOTO} label; is ignored; if all bits are 0, clause-1 is ignored and clause-2, if General rules: present, is executed. In either case, the scan resumes immediately following the IF statement, unless, of course, a 1. The label following the keyword GO TO %GO TO in one of the clauses causes determines the point to which the scan the scan to resume elsewhere. will be transferred. It must be a label of a preprocessor statement, 2. %IF statements can be nested according although it cannot be the label of a to the rules for nesting preprocessor procedure. nonpreprocessor IF statements. 388 The %INCLUDE Statement execution: control can be transferred from an inner group to an cuter, containing group, but not from an Function: outer group into an inner, contained group. The %INCLUDE statement is used to include (incorporate) strings of external text into the source program being scanned. 4. Preprocessor statements in included This included text can contribute to the text must be complete. It is not preprocessed text being formed. permissible, for example, to have half of a %IF statement in included text General format: and half in the other part of the source program. The %INCLUDE statement is defined as follows for the F Compiler: Example: If the source program contained the following sequence of statements: %DECLARE (FILENAME1, FILENAME2) CHARACTER; % FILENAME1 = 'MASTER'; Syntax rules: % FILENAME2 = 'NEWFILE'; 1. Each "ddname" and "member name" pair identifies the external text to be % INCLUDE DCLS; incorporated into the source program. This external text rust be a member of and if the SYSLIB member name DCLS a partitioned data set. contained: 2. A "ddname" specifies the ddname DECLARE (FILENAME1, FILENAME2) cccurring in the name field of the FILE RECORD INPUT appropriate DD statement. Its DIRECT KEYED; associated "member name" specifies the name of the data set member to be then the following would be inserted into incorporated. If "ddname" is omitted, the preprocessed text: SYSLIB is assumed, and the SYSLIB DD statement is required. DECLARE (MASTER, NEWFILE) FILE RECORD INPUT 3. A %INCLUDE statement cannot be used in DIRECT KEYED; a preprocessor procedure. Note that this is a way in which a General rules: central library of file declarations can be used, with each user supplying his own 1. Included text can contain names for the files being declared. nonpreprocessor and/or preprocessor statements. 2. The included text is scanned, in sequence, in the same manner as the The % Null Statement source program; that is, preprocessor statements are executed and replacements are made where required. Function: 3. %INCLUDE statements can be nested. In other words, included text also can The % null statement can be used to contain %INCLUDE statements. A %GO TO provide transfer targets for %GO TO statement in included text can statements. It is also useful for transfer control to a point in the balancing ELSE clauses in nested %IF source program or in any included text statements. at an outer level of nesting, but the reverse is not permitted. An General format: analogous situation exists for nested DO-groups that specify iterative % [label:]...; Section J: Statements 389 The %PROCEDURE Statement 3. As implied by general rule 1, preprocessor procedures cannot be nested. Function: 4. A preprocessor procedure can be The %PROCEDURE statement is used in invoked by a function reference in a conjunction with a %END statement to preprocessor statement, or, if the delimit a preprocessor procedure. Such a function procedure name is active, by preprocessor procedure is an internal the encounter of that name in a function procedure that can be executed nonpreprocessor statement. only at the preprocessor stage. General format: 5. For the F Compiler there may be no more than 254 compile-time procedures % label: [label:]... PROCEDURE per compilation. Further, each [(identifier [, procedure is limited to a maximum of 'RETURNS(FIXED|CHARACTER)'; 15 parameters. Syntax rules: 1. Each "identifier" is a parameter of the function procedure. 2. One of the attributes CHARACTER or The Preprocessor RETURN Statement FIXED must be specified to indicate the type of value returned by the function procedure. There can be no Function: default. The preprocessor RETURN statement can be General rules: used only in a preprocessor procedure and, therefore, can have no leading %. It 1. The only statements and groups that returns a value as well as control back to can be used within a preprocessor the point from which the preprocessor procedure are: procedure was invoked. a. the preprocessor assignment statement General format: b. the preprocessor DECLARE statement [label:]... RETURN (preprocessor-expression); c. the preprocessor DO-group d. the preprocessor GO TO statement General rule: e. the preprocessor IF statement f. the preprocessor null statement The value of the preprocessor expression is converted to the attribute specified in g. the preprocessor RETURN statement the %PROCEDURE statement before it is passed back to the point of invocation. If All of these statements and the the point of invocation is in a DO-group must adhere to the syntax and nonpreprocessor statement, replacement general rules given for them in this activity can be performed on the returned section, with one exception; all value after that value has replaced the percent symbols must be omitted. procedure reference. 2. A GO TO statement appearing in a Note that the rules for preprocessor preprocessor procedure cannot transfer expressions do not permit the value control to a point outside of that returned by a preprocessor procedure to procedure. contain preprocessor statements. 390 Section K: Data Mapping This section describes structure mapping RULES and alignment of records in buffers as performed by the F Compiler. The information is included in this manual The mapping for a complete structure because, under certain circumstances, it reduces to successively combining pairs of should be borne in mind while the program items (elements, or minor structures whose is being written. However, the information individual mappings have already been is not essential to programmers using determined). Once a pair has been stream-oriented transmission or unaligned combined, it becomes a unit to be paired data; it is intended for those using with another unit, and so on until the record-oriented transmission (particularly complete structure has been mapped. The locate mode) with aligned structures. rules for the process are therefore categorized as: Rules for determining the order of pairing Rules for mapping one pair Structure Mapping These rules are described below, and are followed by an example showing an application of the rules in detail. For any structure (major or minor), the length, alignment requirement, and position Note: To follow these rules, it is relative to a doubleword boundary will necessary to appreciate the difference depend on the lengths, alignment between logical level and level number. requirements, and relative positions of its The item with the greatest level number is members. The process of determining these not necessarily the item with the deepest requirements for each level in turn and logical level. If the structure finally for the complete structure, is declaration is written with consistent known as structure mapping. level numbers or suitable indention (as in the detailed example given after the rules), the logical levels are immediately apparent. In any case, the logical level During the structure mapping process, of each item in the structure can be the F compiler minimizes the amount of determined by applying the following rule unused storage (padding) between members of to each item in turn, starting at the the structure. It completes the entire beginning of the structure declaration: process before the structure is allocated, according (in effect) to the rules The logical level of a given item is discussed in the following paragraphs. It always one unit deeper than that of the is necessary for the programmer to nearest preceding item that has a understand these rules for such purposes as lesser level number than the given determining the record length required for item. a structure when record-oriented input/output is used, and for determining For example: the amount of padding or rearrangement required to ensure correct alignment of a DCL 1 A, 4 B, 5 C, 5 D, 3 E, 8 F, 7 G; structure for locate-mode input/output (see "Record Alignment," below). 1 2 3 3 2 3 3 The lower line shows the logical level for each item in the declaration. Structure mapping is not a physical process. Although during this discussion such terms as "shifted" and "offset" are used, these terms are used purely for ease of discussion, and do not imply actual Rules for Order of Pairing movement in storage; when the structure is allocated, the relative locations are already known as a result of the mapping The steps in determining the order of process. pairing are as follows: Section K: Data Mapping 391 1. Find the minor structure with the that the offset from a doubleword boundary deepest logical level (which we will can be given; in addition, the bytes in the call logical level n). model may be numbered continuously from zero onwards, starting at any byte, so that 2. If the number of minor structures at lengths and offsets from the start of a logical level n exceeds one, take the structure can be given.) first one of them as it appears in the declaration. 1. Begin the first item of the pair on a 3. Using the rules for mapping one pair doubleword boundary; or, if the item (see below), pair the first two is a minor structure that has already elements appearing in this minor been mapped, offset it from the structure, thus forming a unit. doubleword boundary by the amount indicated. 4. Pair this unit with the next element (if any) appearing in the declaration 2. Begin the other item of the pair at ' for the minor structure, thus forming the first valid position following the a larger unit. end of the first item. This position will depend on the alignment 5. Repeat rule 4 until all the elements requirement of the second item. in the minor structure have been Alignment and length requirements for combined into one unit. This elements are given in Figures K-1 and completes the mapping for this minor K-2. (If the item is a minor structure; its alignment requirement structure, its alignment requirement and length, including any padding, are will have been determined already.) now determined and will not change (unless the programmer changes the 3. Shift the first item towards the structure declaration). Its offset second item as far as the alignment from a doubleword boundary will also requirement of the first item will have been determined; note that this allow. The amount of shift determines offset will be significant during the offset of this pair from a mapping of any containing structure, doubleword boundary. and it may change as a result of such mapping. After this process has been completed, any padding between the two items will have 6. Repeat rules 3 through 5 for the next been minimized and will remain unchanged minor structure (if any) appearing at throughout the rest of the operation. The logical level n in the declaration. pair can now be considered to be a unit of fixed length and alignment requirement; its 7. Repeat rule 6 until all minor length is the sum of the two lengths plus structures at logical level n have padding, and its alignment requirement is been mapped. Each of these minor the higher of the two alignment structures can now be thought of as an requirements (if they differ). element for structure mapping purposes. 8. Repeat the process for minor structures at the next higher logical Effect of UNALIGNED Attribute level; that is, make n equal to (n - 1) and repeat rules 2 through 7. The example of structure mapping given 9. Repeat rule 8 until n = 1; then repeat below shows the rules applied to a rules 3 through 5 for the major structure declared ALIGNED, because mapping structure. of aligned structures is more comp lex owing to the number of different alignment requirements. Briefly, with the F compiler, the general effect of the UNALIGNED attribute is to reduce fullword Rules for Mapping One Pair and doubleword alignment requirements down to byte, and to reduce the alignment requirement for bit strings from byte down (As stated earlier, terms apparently to bit. The same structure mapping rules implying physical storage are used here apply, but the reduced alignment only for ease of discussion; the storage requirements are used. This means that thus implied may be thought of as an unused storage between items can only be imaginary model consisting of a number of bit padding within a byte, and never a contiguous doublewords. Each doubleword complete byte; bit padding may occur when has eight bytes numbered zero through 7, so the structure contains bit strings. 392 Note: The term CEIL used in some storage calculations has the same meaning as the CEIL built-in function of PL/I, i.e., the smallest integer that exceeds the value of the expression in parentheses; thus, CEIL(30/8)=4. Figure K-1. Summary of Alignment Requirements for ALIGNED Data POINTER, OFFSET, LABEL, TASK, EVENT, and out. For example, in a program with the AREA data cannot be unaligned. If a declaration structure has the UNALIGNED attribute and it contains an element that cannot be unaligned, then UNALIGNED is ignored for DECLARE 1 A UNALIGNED, that element; the element is aligned by the 2 B, compiler and error message IEM3181I is put 2 C AREA(100); Section K: Data Mapping 393 Note: POINTER, OFFSET, LABEL, TASK, EVENT, and AREA data cannot be UNALIGNED. Figure K-2. Summary of Alignment Requirements for UNALIGNED Data C is given the attribute ALIGNED, as the inherited attribute UNALIGNED conflicts with AREA. EXAMPLE OF STRUCTURE MAPPING This example shows the application of the structure mapping rules for a structure declared as follows: The minor structure at the deepest logical level is G, so that this is mapped first. Then E is mapped, followed by N, S, C, and M, in that order. Finally, the major structure A is mapped. For each structure, a table is given showing the steps in the process, accompanied by a 394 diagram giving a visual interpretation of the process. At the end of the example, the structure map for A is set out in the form of a table showing the offset of each member from the start of A. Figure F-3. Mapping of Minor Structure G Section Ks Data Mapping 395 Figure K-4. Mapping of Minor Structure E 396 Figure K-5. Mapping of Minor Structure N Section K: Data Mapping 397 Figure K-6. Mapping of Minor Structure S 398 Figure K-7. Mapping of Minor Structure C Section K: Data Mapping 399 Figure K-8. Mapping of Minor Structure M 400 Figure K-9. Mapping of Major Structure A Section K: Data Mapping 401 Figure K-10. Offsets in Final Mapping of Structure A Record Alignment The user must pay attention to record alignment within the buffer when using locate mode input/output. The first data byte of the first record in a block is generally aligned in a buffer on a doubleword boundary (see Figure K-14); the Figure K-11. Format of Structure S next record begins at the next available byte in the buffer. The user must ensure that the alignment of this byte matches the If the block was created using a alignment requirements of the based sequence of WRITE FROM(S) statements, the variable with which the record is to be format of the block would be as in Figure associated. K-12, and it can be seen that the alignment in the buffer differs from the alignment of S. Most of the alignment problems described here cccur in ALIGNED based or non-based variables. If these variables were There is no problem if the file is then UNALIGNED, the preservation of the record read using move mode READ statements, e.g., alignment in the buffer would be READ INTO(S), because information is moved considerably easier. from the buffer to correctly aligned storage. If a VB-format record is to be If, however, a structure is defined as: constructed with logical records defined by the structure: 1 SBASED BASED(P) LIKE S; and READ SET(P) statements are used, 1 S, reference to SBASED.B will, for the first 2 A CHAR(1), record in the block, be to data aligned at 2 B FIXED BINARY(31,0); a doubleword plus one byte, and will probably result in a specification this structure is mapped as in Figure K-11. interrupt. 402 Figure K-12. Block Created from Structure S Figure K-13. Block Created by Structure S with Correct Alignment The same problem would have arisen had For unblocked INDEXED, the LOCATE the file originally been created by using statement will use a hidden buffer if the the statement: data set key length is not a multiple of 8. The pointer variable will point at this LOCATE SBASED SET(P); hidden buffer. Again, for the first record in the A special problem arises when using block, P would be set to address a locate mode input/output in conjunction doubleword and references to SBASED.B would with based variable containing adjustable be invalid. extents, i.e., containing a REFER option. Consider the following structure: In both cases the problem is avoided if 1 S BASED(P), the structure is padded in such a way that 2 N, B is always correctly aligned: 2 C CHAR (L REFER (N)); 1 5, If it is desired to create blocked V-format 2 PAD CHAR(3), records of this type, using locate mode 2 A CHAR(1), input/output, record alignment must be such 2 B FIXED BINARY; that N is word aligned. If L is not a multiple of 4 then, if the alignment of the The block format would now be as in Figure current record is correct, that of the K-13; B is always on a word boundary. following record will be incorrect. Padding may be required at the beginning Correct alignment can be obtained by the and end of a structure to preserve following sequence: alignment. LENGTH = L; The alignment of different types of /* SAVE DESIRED LENGTH L */ record within a buffer is shown in Figure L = 4* CEIL(L/4); K-14. For all organizations and record /* ROUND UP TO MULTIPLE OF 4 */ types except blocked records in INDEXED LOCATE S FILE (F); data sets with RKP=0, the first data byte N = LENGTH; in a block is always on a doubleword /* SET REFER VARIABLE */ boundary. The position of any successive records in the buffer depends on the record This technique can be adapted to other uses format. of the REFER option. Section K: Data Mapping 403 Figure F-14. Alignment of Data in a Buffer in Locate Mode Input/Output, for Different Formats and Data Set Organizations 404 Section L: Definitions of Terms This section provides definitions for most alphabetic character: any of the of the terms used in this publication. characters A through Z and the alphabetic extenders #, $, and @. access: the act that encompasses the reference to and retrieval of data. alphameric character: an alphabetic character or a digit. action specification: in an ON statement, the on-unit or the single keyword SYSTEM, alternative attributes: attributes that either of which specifies the action to be may be chosen from groups of two or more taken whenever an interrupt results from alternatives. If none is specified, a raising of the named condition. default is assumed. activation: institution of execution of a area: a block of storage defined by an block. A procedure block is activated when area variable and reserved, on allocation, it is invoked at any of its entry points; a for the allocation of based variables. begin block is activated when it is encountered in normal sequential flow. arithmetic conversion: the transformation of a value from one arithmetic active: representation to another arithmetic representation. 1. the state in which a block is said to be after activation and before argument: an expression, file name, termination. statement label constant or variable, mathematical built-in function name, or 2. the state in which a preprocessor entry name passed to an invoked procedure variable or preprocessor procedure is as part of the procedure reference. said to be when its value can replace the corresponding identifier in source arithmetic data: data that has the program text. characteristics of base, scale, mode, and precision. It includes coded arithmetic 3. the state in which an event variable data and numeric character data. is said to be as a result of its appearance in the EVENT option of an arithmetic operators: any of the prefix executed RECORD input/output operators, + and -, or the infix operators statement. An event variable remains +, *, /, and **. active, and, hence, cannot be associated with any other input/output array: a named, ordered collection of data operation, until a WAIT statement elements, all of which have identical naming that event variable has been attributes. An array has dimensions, and executed. elements that are identified by subscripts. An array can also be an ordered collection additive attributes: file attributes for of identical structures. which there are no defaults and which, if required, must always be stated explicitly. array of structures: an ordered collection of structures formed by giving the address: a specific storage location at dimension attribute to the name of a which a data item can be stored. structure. adjustable (bounds and lengths): bounds or assignment: giving a value to a variable. lengths that may be different for different allocations of the associated variable. asynchronous: describes either the overlap Adjustable bounds and lengths are specified of an input/output operation with the as variables, expressions, or asterisks, execution of statements, or the concurrent which are evaluated separately at each execution of procedures, using multiple allocation. They cannot be used for STATIC flows of control. data. attachment of a task: the invocation of a allocated variable: a variable with which procedure that is to be executed storage has been associated. asynchronously with the invoking procedure. allocation: the association of storage attribute: a descriptive property with a variable. associated with a name or expression to Section L: Definitions of Terms 405 describe a characteristic of data items, of comment: a string of characters, used for a file, or of an entry point the name may documentation, which is preceded by /* and represent. terminated by */ and which is treated as a blank. automatic storage: storage that is allocated at the activation of a block and common expression: an expression that released at the termination of that block. occurs more than once in a program but is obviously intended to result in the same value each time it is evaluated, i.e., an base: the number system in terms of which expression that is identical to another an arithmetic value is represented. In expression, with no intervening PL/I, the base is binary or decimal. modification to any operand. The compiler is permitted to optimize such expressions based storage: storage whose allocation by evaluating them once only and saving the and release is controlled by the result, rather than re-evaluating for each programmer, with immediate access to all reference. unfreed allocations. comparison operators: the operators ¬ < < begin block: a collection of statements <= ¬= >= > ¬> headed by a BEGIN statement and ended by an END statement that delimits the scope of compile time: in general, the time during names and, in general, is activated by which a source program is translated into normal sequential statement flow. It an object module. In PL/I, it is the time controls the allocation and freeing of during which a source program can be automatic storage declared in that block. altered (preprocessed), if desired, and then translated into an object program. binary: the number system based on the value 2. compiler: a translator that converts a source program into an object module. It bit: a binary digit, either 0 or 1. consists of two stages, a preprocessor and a processor. bit string: a string composed of zero or more bits. complex data: arithmetic data consisting of a real part and an imaginary part. bit-string operators: the operators ,(not), &(and), and |(or). compound statement: a statement that contains other statements. IF and ON are block: a begin block or a procedure block. the only compound statements. bounds: the upper and lower limits of an concatenation: the operation that connects array dimension. two strings in the order indicated, thus forming one string whose length is equal to buffer: an intermediate area, used in the sum of the lengths of the two strings. input/output operations, into which a It is specified by the operator |. record is read during input and from which a record is written during output. condition name: a language keyword that represents an exceptional condition that built-in function: one of the PL/I-defined might arise during execution of a program. functions. condition prefix: a parenthesized list of call: the invocation of a subroutine by one or more condition names prefixed to a means of the CALL statement or the CALL statement by a colon. It determines option of the INITIAL attribute. whether or not the program is to be interrupted if one of the specified character string: A string composed of conditions occurs within the scope of the zero or more characters from the complete prefix. Condition names within the list set of characters whose bit configuration are separated by commas. is recognized by the computer system in use. For System/360 implementations, any constant: an arithmetic or string data of the 256 EBCDIC characters can be used. item that does not have a name; a statement label. coded arithmetic data: arithmetic data whose characteristics are given by the contained in: all of the text of a block base, scale, mode, and precision except any entry names of that block. (A attributes. The types for System/360 are label of a BEGIN statement is not contained packed decimal, binary full words, and in the begin block defined by that hexadecimal floating-point. statement.) 406 contextual declaration: the association of separate identifiers and constants, or attributes with an identifier according to statements from one another. the context in which the identifier appears. dimensionality: the number of bounds specifications associated with an array. controlled storage: storage whose allocation and release is controlled by the programmer, with immediate access to the disabled: the state in which the latest allocation only. occurrence of a particular condition will not result in a program interrupt. conversion: the transformation of a value from one representation to another. DO-group: a sequence of statements headed by a DO statement and closed by its cross section of an array: every element corresponding END statement. represented by the extent of at least one dimension of an array. An asterisk in the dummy argument: a compiler-assigned place of a subscript in an array reference variable for an argument that has no indicates the entire extent of that programmer-assigned name or whose dimension. attributes do not agree with those declared with the ENTRY attribute for the data: representation of information or of corresponding parameter. value. edit-directed transmission: that type of data-directed transmission: the type of STREAM transmission for which both a data STREAM input and output in which list and a format list are specified. self-identifying data of the type, variable-name = value, is transmitted. element: a single data item as opposed to a collection of data items, such as a data item: a single unit of data; it is structure or an array. (Sometimes called a synonymous with "element." "scalar item.") data list: a list of expressions used in a element variable: a variable that can STREAM input/output specification that represent only a single value at any one represent storage areas to which data items point in time. are to be assigned during input or from which data items are to be obtained on enabled: that state in which the output. (On input, the list may contain occurrence of a particular condition will only variables.) result in a program interrupt. data set: a collection of data external to entry name: a label of a PROCEDURE or the program. ENTRY statement. data specification: the portion of a entry point: a point in a procedure at stream-oriented data transmission statement which it may be invoked by reference to the that specifies the mode of transmission entry name. (See primary entry point and (DATA, LIST, or EDIT) and includes the data secondary entry point.) list and, for edit-directed transmission, the format list. epilogue: those processes which occur at the termination of a block. deactivated: the state in which a preprocessor variable is said to be when event: an identifiable point in the its value cannot replace the corresponding execution of a program. identifier in source program text. event name: the identifier used to refer decimal: the number system based on the to an event variable. value 10. event variable: a variable associated with declaration: the association of attributes an event; its value shows whether an event with an identifier explicitly, is complete and the status of the contextually, or implicitly. completion. default: the alternative assumed when an exceptional condition: an occurrence, identifier has not been declared to have which can cause a program interrupt, of an one of two or more alternative attributes. unexpected situation, such as an overflow error, or an occurrence of an expected delimiter: any valid special character or situation, such as an end of file, that combination of special characters used to occurs at an unpredictable time. Section L: Definitions of Terms 407 explicit declaration: the assignment of function reference: the appearance of an attributes to an identifier by means of the entry name in an expression, usually in DECLARE statement, the appearance of the conjunction with an argument list. identifier as a label, or the appearance of the identifier in a parameter list. generation (of a block): a particular activation of a block. exponent (of floating-point constant): a decimal integer constant specifying the generation (of data): a particular power to which the base of the allocation of controlled or automatic floating-point number is to be raised. storage. generic key: a character string that expression: the representation of a value; identifies a class of keys: all keys that examples are variables and constants begin with the string are members of that appearing alone or in combination with class. For example, the recorded keys operators, and function references. The 'ABCD', 'ABCE', and 'ABDF' are all members term "expression" refers to an element of the classes identified by the generic expression, an array expression, or a keys 'A' and 'AB', and the first two are structure expression. also members of the class 'ABC'; and the three recorded keys can be considered to be external declaration: an explicit or unique members of the classes 'ABCD', contextual declaration of the EXTERNAL 'ABCE', and 'ABDF', respectively. attribute for an identifier. Such an identifier is known in all other blocks for generic name: the name of a family of which such a declaration exists. entry names. A reference to the name is replaced by the entry name whose entry external name: an identifier which has the attribute matches the attributes of the EXTERNAL attribute. argument list. external procedure: a procedure that is group: a DO-group. not contained in any other procedure. identifier: a string of alphameric and field (in the data stream): that portion break characters, not contained in a of the data stream whose width, in number comment or constant, preceded and followed of characters, is defined by a single data by a delimiter and whose initial character or spacing format item. is alphabetic. field (of a picture specification): a imaginary number: a number whose factors character-string picture specification or include the square root of -1. that portion (or all) of a numeric character picture specification that implicit declaration: association of describes a fixed-point number. If more attributes with an identifier used as a than one field appears in a single variable without having been explicitly or specification, they are divided by the F contextually declared; default attributes scaling-factor character for fixed-point apply, depending upon the initial letter of data, the E or E exponent character for the identifier. floating-point data, or the M field-separator for sterling data. inactive block: a procedure or begin block that has not been activated or that has file: a symbolic representation, within a been terminated. program, of a data set. inactive event variable: an event variable file name: a symbolic name used within a that is not currently associated with an program to refer to a data set. event. format item: a specification used in infix operator: an operator that defines edit-directed transmission to describe the an operation between two operands. representation of a data item in the stream or to control the format of a printed page. initial procedure: an external procedure whose PROCEDURE statement has the OPTIONS format list: a list of format items (MAIN) attribute. Every PL/I program must required for an edit-directed data have an initial procedure. It is invoked specification. automatically as the first step in the execution of a program. function: a procedure that is invoked by the appearance of one of its entry names in input/output: the transfer of data between a function reference. an external medium and internal storage. 408 interleaving of subscripts: a subscript identifier prefixed to a statement by a notation used with subscripted qualified colon. names that allows one or more of the required subscripts to immediately follow any of the component names. leading zeros: zeros that have no significance in the value of an arithmetic number; all zeros to the left of the first internal block: a block that is contained significant digit (1 through 9) of a within another block. number. internal name: an identifier that has the level number: an unsigned decimal integer INTERNAL attribute. constant specifying the hierachy of a name in a structure. It appears to the left of internal procedure: a procedure that is the name and is separated from it by a contained in another block. blank. internal to: all of the text contained in level-one variable: a major structure a block except that text contained in name; any unsubscripted data variable not another block. Thus the text of an contained within a structure. internal block (except for its entry names) is not internal to the containing block. list-directed transmission: the type of Note: An entry name of a block is not STREAM transmission in which data in the contained in that block. stream appears as constants separated by blanks or commas. interrupt: the suspension of normal program activities as the result of the list processing: the use of based occurrence of an enabled condition. variables and locator variables to build chains or lists of data. invoke: to activate a procedure at one of its entry points; to enter an on-unit. locator variable: a variable whose value identifies an allocation of a based invoked procedure: a procedure that has variable in storage. Pointer variables and been activated at one of its entry points. offset variables are the two types of locator variables. invoking block: a block containing a statement that activates another block. major structure: a structure whose name is declared with level number 1. iteration factor: an expression that specifies: major task: the task that has control at the outset of execution of a program. 1. the number of consecutive elements of an array that are to be initialized minor structure: a structure whose name is with a given constant. declared with a level number greater than 1. 2. the number of times a given format item or list of format items is to be mode: real or complex designation for an used in succession in a format list. arithmetic value. key: see source key and recorded key. multiple declaration: two or more declarations of the same identifier key class: a set of keys that begin with a internal to the same block without common character string; this character different qualifications, or two or more string is the generic key for the class. EXTERNAL declarations of the same identifier as different names within a keyword: an identifier that is part of the single program. language and which, when used in the proper context, has a specific meaning to the multiprogramming: the use of a computing compiler. system to execute a number of instructions concurrently. known: a term that is used to indicate the scope of an identifier. For example, an multitasking: the PL/I facility that identifier is always known in the block in allows the programmer to make use of the which it has been declared. multiprogramming capability of a system. label constant: synonymous with statement name: an identifier that has been label. declared. label prefix: an unparenthesized nesting: Section L: Definitions of Terms 409 1. the cccurrence of a block within invoking block at which the procedure another block. reference to the invoked procedure appears. 2. the occurrence of a group within pointer variable: a locator variable whose another group. value identifies an absolute location in storage. 3. the occurrence of an IF statement in a THEN clause or an ELSE clause. precision: the value range of an arithmetic variable expressed as the total 4. the occurrence of a function reference number of digits allowed and, for as an argument of another function fixed-point variables, the assumed location reference. of the decimal (or binary) point. prefix: a label or a parenthesized list of null locator value: a special locator condition names connected by a colon to the value that cannot identify any location in beginning of a statement. storage; it gives a positive indication that a locator variable does not currently prefix operator: an operator that identify any allocation of a based precedes, and is associated with, a single variable. operand. The prefix operators are 1 + - null string: a string data item of zero preprocessed text: the output from the length. first stage of compile-time activity. This output is a sequence of characters that is numeric character data: arithmetic data altered source program text and which described by a picture that is stored in serves as input to the processor stage in character form. It has both an arithmetic which the actual compilation is performed. value and a character-string value. The picture must not contain either an A or an preprocessor: the first of the two X picture specification character. compiler stages. At this stage the source program is examined for preprocessor offset variable: a locator variable whose statements which are then executed, value identifies a location in storage, resulting in the alteration of the source relative to the start of an area. program text. on-unit: the action to be executed upon preprocessor statements: special the occurrence of the ON-condition named in statements appearing in the source program the containing ON statement. that specify how the source program text is to be altered; they are identified by a operator: a symbol specifying an operation leading percent sign and are executed as to be performed. See arithmetic operators, they are encountered by the preprocessor bit-string operators, comparison operators, (they appear without the percent sign in and concatenation. preprocessor procedures). option: a specification in a statement primary entry point: the entry point named that may be used by the programmer to in the PROCEDURE statement. influence the execution of the statement. priority: the value that determines packed decimal: the System/360 internal whether a task will take precedence over representation of a fixed-point decimal another task. data item. problem data: string or arithmetic data parameter: a name in an invoked procedure that is processed by a PL/I program. that is used to represent an argument passed to that procedure. procedure: a block of statements, headed by a PROCEDURE statement and ended by an parameter-attribute list: a description in END statement, that defines a program an ENTRY attribute specification that lists region and delimits the scope of names and attributes of parameters of the named entry that is activated by a reference to its point. This enables dummy arguments to be name. It controls allocation and freeing created correctly. of automatic storage declared in that block. picture: a character-by-character specification describing the composition procedure reference: a function or and attributes of numeric character and subroutine reference. character-string data. It allows editing. processor: the second of the two compiler point of invocation: the point in the stages. The stage at which the 410 preprocessed text is compiled into an scope (of a condition prefix): the range object module. of a program throughout which a condition prefix applies. program: a set of one or more external scope (of a name): the range of a program procedures, one of which must have the throughout which a name has a particular OPTIONS(MAIN) attribute in its PROCEDURE interpretation. statement. secondary entry point: an entry point program control data: data used in a PL/I defined by a label of an ENTRY statement program to affect the execution of the within a procedure. program. Program control data consists of the following types: label, event, task, source key: a character string referred to pointer, offset, and area. in a RECORD transmission statement that identifies a particular record within a prologue: those processes that occur at direct-access data set. The source key may the activation of a block. or may not also contain, as its first part, a substring to be compared with, or written pseudo-variable: one of the built-in as, a recorded key to positively identify function names that can be used as a the record. Note: The source key can be receiving field. identical to the recorded key. pushed-down stack: a stack of allocations source program: the program that serves as to which new allocations are added and input to the compiler. The source program removed from the top on a last-in, may contain preprocessor statements. first-cut basis. standard file: a file assumed by the qualified name: a sequence of names of compiler in the absence of a FILE or STRING structure members connected by periods, to option in a GET or PUT statement (the uniquely identify a component of a standard files are: SYSIN for input, structure. Any of the names may be SYSPRINT for output). subscripted. statement: a basic element of a PL/I receiving field: any field to which a program that is used to delimit a portion value may be assigned. of the program, to describe data used in the program, or to specify action to be record: the unit of transmission in a taken. RECORD input or output operation; in the internal form of a level-one variable. statement label: an identifying name prefixed to any statement other than a recorded key: a character string recorded PROCEDURE or ENTRY statement. in a direct-access volume to identify the data record that immediately follows. statement label variable: a variable declared with the LABEL attribute and thus recursion: the reactivation of a procedure able to assume as its value a statement while it is already active. label. repetition factor: a parenthesized static storage: storage that is allocated unsigned decimal integer constant preceding before execution of the program begins and a string configuration as a shorthand that remains allocated for the duration of representation of a string constant. The the program. repetition factor specifies the number of occurrences that make up the actual stream: data being transferred from or to constant. In picture specifications, the an external medium represented as a repetition factor specifies repetition of a continuous string of data items in single picture character. character form. repetitive specification: an element of a string: a connected sequence of characters data list that specifies controlled or bits that is treated as a single data iteration to transmit a list of data items, item. generally used in conjunction with arrays. structure: a hierarchical set of names returned value: the value returned by a that refers to an aggregate of data items function procedure to the point of that may or may not have different invocation. attributes. scale: fixed- or floating-point subfield: the integer description portion representation of an arithmetic value. or the fraction description portion of a Section L: Definitions of Terms 411 picture specification field that describes task variable: a variable whose value a noninteger fixed-point data item. The gives the relative priority of a task. subfields are divided by the picture character V. termination of block: cessation of subroutine: a procedure that is invoked by execution of a block, and the return of a CALL statement or a CALL option. A control to the activating block by means of subroutine cannot return a value to the a RETURN or END statement, or the transfer invoking block, but it can alter the value of control to the activating block or some of variables that are known within the other active block by means of a GO TO invoking block. statement. A return of control to the operating system via a RETURN or END subscript: an element expression statement in the initial procedure or a specifying a location within a dimension of STOP or EXIT statement in any block results an array. A subscript can also be an in the termination of the program. See asterisk, in which case it specifies the epilogue. entire extent of the dimension. subtask: a task that is attached by termination of task: conclusion of the another task; any task attached by this flow of control for a task. subtask is a subtask of both tasks. synchronous: describes serial execution of variable: a name that represents data. a program, using a single flow of control. Its attributes remain constant, but it can represent different values at different task: the execution of one or more times. Variables fall into three procedures. categories: element, array, and structure variables. Variables may be subscripted task name: the identifier used to refer to and/or qualified. a task variable. 412 Index Index 413 414 Index 415 416 Index 417 418 Index 419 420 Index 421 422 Index 423 424 Index 425 426 Index 427 428 Index 429 430 Index 431 432 Index 433 GC28-8201-2 International Business Machines Corporation Data Processing Division 112 East Post Road, White Plains, N.Y. 10601 [USA Only) IBM World Trade Corporation 821 United Nations Plaza, New York, New York 10 017 [International] READER'S COMMENT FORM IBM System/360 GC28-8201-2 PL/I Reference Manual • How did you use this publication? As a reference source ❑ As a classroom text ❑ As a self-study text ❑ • Based on your own experience, rate this publication . . . As a reference source: Very Good Fair Poor Very Good Poor As a text: Very Good Fair Poor Very Good Poor • What is your occupation? • We would appreciate your other comments; please give specific page and line references where appropriate. If you wish a reply, be sure to include your name and address. Thank you for your cooperation. No postage stamp necessary if mailed in the U.S.A. GC28-8201-2 YOUR COMMENTS PLEASE . . . . This SRL manual is part of a library that serves as a reference source for systems analysts, programmers and operators of IBM systems. Your answers to the questions on the back of this form, together with your comments, will help us produce better publications for your use. Each reply will be carefully reviewed by the persons responsible for writing and publishing this material. All comments and suggestions become the property of IBM. Please note : Requests for copies of publications and for assistance in utilizing your IBM system should be directed to your IBM representative or to the IBM sales office serving your locality. InternationalIBM Business Machines Corporation Data Processing Division 112 East Post Road, White Plains, N.Y.10601 [USA Only) IBM World Trade Corporation 821 United Nations Plaza, New York, New York 10 017 [International]