Enterprise PL/I for z/OS Language Reference

Enterprise PL/I for z/OS
PL/I for AIX
Rational Developer for System z PL/I for Windows
Language Reference
Version 4 Release 3
SC14-7285-02
Enterprise PL/I for z/OS
PL/I for AIX
Rational Developer for System z PL/I for Windows
Language Reference
Version 4 Release 3
SC14-7285-02
Note
Before using this information and the product it supports, be sure to read the general information under “Notices” on page
787.
Third Edition (September 2012)
This edition applies to Enterprise PL/I for z/OS, Version 4 Release 3 (5655-W67), IBM PL/I for AIX, Version 3
Release 1 (5724-H45), and Rational Developer for System z PL/I for Windows, Version 8.5, and to any subsequent
releases of any of these products until otherwise indicated in new editions or technical newsletters. Make sure you
are using the correct edition for the level of the product.
Order publications through your IBM representative or the IBM branch office serving your locality. Publications are
not stocked at the address below.
A form for readers' comments is provided at the back of this publication. If the form has been removed, address
your comments to:
IBM Corporation, Department H150/090
555 Bailey Ave.
San Jose, CA, 95141-1099
United States of America
When you send information to IBM, you grant IBM a nonexclusive right to use or distribute the information in any
way it believes appropriate without incurring any obligation to you.
© Copyright IBM Corporation 1999, 2012.
US Government Users Restricted Rights – Use, duplication or disclosure restricted by GSA ADP Schedule Contract
with IBM Corp.
Contents
Tables . . . . . . . . . . . . . . . xiii
Figures . . . . . . . . . . . . . . xv
About this book . . . . . . . . . . xvii
Notation conventions used in this book . . . . xvii
Semantics . . . . . . . . . . . . . . . xx
Industry standards used . . . . . . . . . . xx
Summary of changes . . . . . . . . . . . xx
Enhancements in this release . . . . . . . xx
Enhancements from V4R2 . . . . . . . . xxi
Enhancements from V4R1 . . . . . . . . xxi
Enhancements from V3R9 . . . . . . . . xxii
Enhancements from V3R8 . . . . . . . . xxii
Enhancements from V3R7 . . . . . . . . xxiii
Enhancements from V3R6 . . . . . . . . xxiv
Enhancements from V3R5 . . . . . . . . xxiv
Enhancements from V3R4 . . . . . . . . xxiv
Enhancements from V3R3 . . . . . . . . xxv
Enhancements from V3R2 . . . . . . . . xxv
Enhancements from V3R1 . . . . . . . . xxv
How to send your comments . . . . . . . xxvii
Accessibility . . . . . . . . . . . . . xxvii
Interface information . . . . . . . . . xxvii
Keyboard navigation . . . . . . . . . xxviii
Accessibility of this information . . . . . xxviii
IBM and accessibility . . . . . . . . . xxviii
Chapter 1. Program elements . . . . . 1
Single-byte character set . . .
Decimal digits . . . . . .
Binary digits . . . . . .
Hexadecimal digits . . . .
Special characters . . . . .
Composite symbols . . . .
Case sensitivity . . . . .
Statement elements for SBCS . .
Identifiers . . . . . . .
Delimiters and operators . .
Statements . . . . . . . .
Simple statements . . . .
Compound statements. . .
Groups . . . . . . . . .
Double-byte character set . . .
DBCS identifiers . . . . .
Statement elements for DBCS
DBCS continuation rules . .
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
. 1
. 3
. 3
. 3
. 3
. 4
. 5
. 5
. 5
. 6
. 8
. 10
. 10
. 10
. 11
. 11
. 12
. 13
Chapter 2. Data elements . . . . . . . 15
Data items. . . . . .
Variables . . . . .
Constants . . . . .
Using quotation marks
Punctuating constants .
.
.
.
.
.
© Copyright IBM Corp. 1999, 2012
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
15
16
16
16
16
Data types and attributes . . . . . .
Data attributes . . . . . . . .
Nondata attributes . . . . . . .
Computational data types and attributes
Coded arithmetic data and attributes .
String data and attributes. . . . .
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
17
18
18
22
22
29
Chapter 3. Expressions and references 49
Order of evaluation. . . .
Targets . . . . . . . .
Variables . . . . . .
Pseudovariables . . . .
Intermediate results . .
Operational expressions . .
Handle operations . . .
Pointer operations . . .
Arithmetic operations . .
Bit operations. . . . .
Comparison operations .
Concatenation operations .
Combinations of operations
Array expressions . . . .
Prefix operators and arrays
Infix operators and arrays
Structure expressions . . .
Restricted expressions . . .
Examples . . . . . .
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
52
52
52
52
53
53
54
54
55
63
63
65
67
69
69
69
70
70
71
Chapter 4. Data conversion . . . . . . 73
Built-in functions for computational data conversion
Converting string lengths. . . . . . . . . .
Converting arithmetic precision. . . . . . . .
Converting mode . . . . . . . . . . . .
Converting other data attributes . . . . . . .
Source-to-target rules . . . . . . . . . . .
Examples . . . . . . . . . . . . . . .
DECIMAL FIXED to BINARY FIXED with
fractions . . . . . . . . . . . . . .
Arithmetic to bit string . . . . . . . . .
Arithmetic to character . . . . . . . . .
A conversion error . . . . . . . . . . .
74
75
76
76
76
77
85
85
85
86
86
Chapter 5. Program organization . . . 87
Programs . . . . . . .
Program structure . . .
Program activation . . .
Program termination . .
Blocks . . . . . . . .
Block activation . . . .
Block termination . . .
Packages . . . . . . .
Procedures . . . . . .
PROCEDURE and ENTRY
ENTRY statement . . .
Parameter attribute . . .
. . . .
. . . .
. . . .
. . . .
. . . .
. . . .
. . . .
. . . .
. . . .
statements
. . . .
. . . .
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
87
87
88
89
89
89
90
90
93
94
95
96
iii
Procedure activation . . . . . . . .
Procedure termination . . . . . . .
Recursive procedures . . . . . . . .
Dynamic loading of an external procedure
Subroutines . . . . . . . . . . . .
Example 1 . . . . . . . . . . .
Example 2 . . . . . . . . . . .
Built-in subroutines . . . . . . . . .
Functions. . . . . . . . . . . . .
Examples . . . . . . . . . . . .
Built-in functions . . . . . . . . .
Passing arguments to procedures . . . . .
Using BYVALUE and BYADDR . . . .
Using INONLY, INOUT and OUTONLY .
Dummy arguments . . . . . . . .
Passing arguments to the MAIN procedure
Begin-blocks . . . . . . . . . . . .
BEGIN statement . . . . . . . . .
Begin-block activation . . . . . . .
Begin-block termination . . . . . . .
Entry data . . . . . . . . . . . .
Entry constants . . . . . . . . . .
Entry variables . . . . . . . . . .
ENTRY attribute . . . . . . . . .
OPTIONAL attribute . . . . . . . .
LIST attribute . . . . . . . . . .
LIMITED attribute. . . . . . . . .
Generic entries . . . . . . . . . .
GENERIC attribute . . . . . . . .
Entry invocation or entry value . . . . .
CALL statement . . . . . . . . . .
RETURN statement . . . . . . . . .
Return from a subroutine . . . . . .
Return from a function . . . . . . .
OPTIONS option and attribute . . . . .
RETURNS option and attribute . . . . .
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
. 99
100
101
102
105
105
106
106
107
107
108
109
109
110
110
111
112
112
112
112
113
113
114
115
118
119
123
124
124
127
127
128
128
128
129
138
Chapter 6. Type definitions . . . . . 139
User-defined types (aliases). . . . . . . . .
DEFINE ALIAS statement . . . . . . . .
Defining ordinals . . . . . . . . . . . .
DEFINE ORDINAL statement . . . . . . .
Defining typed structures and unions . . . . .
HANDLE attribute . . . . . . . . . .
Declaring typed variables . . . . . . . . .
TYPE attribute . . . . . . . . . . . .
ORDINAL attribute . . . . . . . . . .
Typed structure qualification . . . . . . . .
Using the '.' operator . . . . . . . . . .
Combinations of arrays and typed structures or
unions. . . . . . . . . . . . . . .
Using handles . . . . . . . . . . . .
Using ordinals . . . . . . . . . . . . .
Example . . . . . . . . . . . . . .
Type functions . . . . . . . . . . . . .
139
139
140
140
142
143
144
144
145
145
146
146
147
147
148
150
Chapter 7. Data declarations . . . . . 151
Explicit declaration . .
DECLARE statement .
Factoring attributes .
iv
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
Enterprise PL/I for z/OS Language Reference
.
.
.
. 151
. 152
. 153
Implicit declaration . . . . . . . . . .
Scope of declarations . . . . . . . . . .
INTERNAL and EXTERNAL attributes . . .
RESERVED attribute . . . . . . . . . .
SUPPRESS attribute . . . . . . . . . .
Data alignment . . . . . . . . . . . .
ALIGNED and UNALIGNED attributes . .
Defaults for attributes . . . . . . . . .
Language-specified defaults . . . . . .
DEFAULT statement . . . . . . . . .
Restoring language-specified defaults . . .
Arrays. . . . . . . . . . . . . . .
DIMENSION attribute . . . . . . . .
DIMACROSS attribute . . . . . . . .
Examples of arrays . . . . . . . . .
Subscripts . . . . . . . . . . . .
Cross sections of arrays . . . . . . . .
Structures and unions . . . . . . . . .
Structures . . . . . . . . . . . .
Unions . . . . . . . . . . . . .
Structure and union qualification . . . . .
LIKE attribute . . . . . . . . . . .
NOINIT attribute . . . . . . . . . .
XMLATTR and XMLOMIT attributes . . .
Aggregate combinations and mapping . . . .
Combinations of arrays, structures, and unions
Cross sections of arrays of structures or unions
Structure and union operations . . . . .
Structure and union mapping . . . . . .
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
154
155
157
162
163
163
164
168
168
169
172
173
173
174
175
175
177
177
177
178
179
180
182
183
184
184
185
. 185
. 185
Chapter 8. Statements and directives
195
ALLOCATE statement . . . . . . . . . .
ASSERT statement. . . . . . . . . . . .
Assignment and compound assignment statements
Assignment statement . . . . . . . . .
Compound assignment statement . . . . .
Target variables . . . . . . . . . . .
How assignments are performed . . . . . .
Multiple assignments . . . . . . . . . .
Examples . . . . . . . . . . . . . .
ATTACH statement . . . . . . . . . . .
BEGIN statement . . . . . . . . . . . .
CALL statement . . . . . . . . . . . .
CLOSE statement . . . . . . . . . . . .
DECLARE statement . . . . . . . . . . .
DEFINE ALIAS statement . . . . . . . . .
DEFINE ORDINAL statement . . . . . . . .
DEFINE STRUCTURE statement . . . . . . .
DEFAULT statement . . . . . . . . . . .
DELAY statement . . . . . . . . . . . .
DELETE statement . . . . . . . . . . .
DETACH statement . . . . . . . . . . .
DISPLAY statement . . . . . . . . . . .
DO statement . . . . . . . . . . . . .
Type 1. . . . . . . . . . . . . . .
Types 2 and 3 . . . . . . . . . . . .
Type 4. . . . . . . . . . . . . . .
Examples of basic repetitions . . . . . . .
Example of DO with WHILE, UNTIL . . . .
Example of DO with UPTHRU and
DOWNTHRU . . . . . . . . . . . .
196
196
198
198
199
200
201
203
203
205
205
205
205
205
205
205
205
205
205
206
206
206
207
207
207
214
215
216
217
Example of REPEAT .
END statement . . . .
ENTRY statement . . .
EXIT statement . . . .
FETCH statement . . .
FLUSH statement . . .
FORMAT statement . .
FREE statement . . .
GET statement . . . .
GO TO statement . . .
IF statement . . . . .
Examples . . . . .
Short-circuit evaluation
%INCLUDE directive. .
ITERATE statement . .
LEAVE statement . . .
Example . . . . .
%LINE directive . . .
LOCATE statement . .
%NOPRINT directive. .
%NOTE directive . . .
null statement . . . .
ON statement . . . .
OPEN statement . . .
OTHERWISE statement .
PACKAGE statement . .
%PAGE directive . . .
%POP directive. . . .
%PRINT directive . . .
PROCEDURE statement .
%PROCESS directive . .
*PROCESS directive . .
%PUSH directive . . .
PUT statement . . . .
READ statement . . .
RELEASE statement . .
RESIGNAL statement. .
RETURN statement . .
REVERT statement . .
REWRITE statement . .
SELECT statement. . .
Examples . . . . .
SIGNAL statement . .
%SKIP directive . . .
STOP statement . . .
WAIT statement . . .
WHEN statement . . .
WRITE statement . . .
%XINCLUDE statement .
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
218
219
219
219
220
220
220
220
220
220
221
222
222
224
224
224
225
225
226
226
226
227
227
227
227
227
227
227
228
228
228
228
229
229
229
230
230
230
230
230
230
231
232
232
232
232
233
233
233
Chapter 9. Storage control . . . . . . 235
Storage classes, allocation, and deallocation . .
Static storage and attribute . . . . . . . .
Automatic storage and attribute . . . . . .
Controlled storage and attribute . . . . . .
ALLOCATE statement for controlled variables
FREE statement for controlled variables . .
Multiple generations of controlled variables .
Asterisk notation . . . . . . . . . .
Adjustable extents . . . . . . . . . .
Built-in functions for controlled variables . .
.
.
.
.
.
.
.
.
.
235
237
237
238
239
241
242
242
242
243
Based storage and attribute. . . . . . . .
Extent specifications in BASED declarations .
BASED VARYING string . . . . . . .
Storage allocation for BASED variable . . .
Locator variables . . . . . . . . . .
DEFINED and UNION attributes . . . . .
INITIAL attribute . . . . . . . . . .
Locator data . . . . . . . . . . . .
POINTER variable and attribute . . . . .
Built-in functions for based variables . . .
ALLOCATE statement for based variables . .
FREE statement for based variables . . . .
REFER option (self-defining data) . . . .
Area data and attribute . . . . . . . . .
Offset data and attribute . . . . . . .
Built-in functions for area variables . . . .
Area assignment . . . . . . . . . .
Input/output of areas . . . . . . . .
List processing . . . . . . . . . . . .
ASSIGNABLE and NONASSIGNABLE attributes
NORMAL and ABNORMAL attributes . . . .
BIGENDIAN and LITTLEENDIAN attributes. .
HEXADEC and IEEE attributes . . . . . .
CONNECTED and NONCONNECTED attributes
DEFINED and POSITION attributes . . . . .
Unconnected Storage . . . . . . . . .
Simple Defining . . . . . . . . . .
iSUB Defining . . . . . . . . . . .
String Overlay Defining . . . . . . . .
POSITION attribute . . . . . . . . .
INITIAL attribute . . . . . . . . . . .
Initializing array variables . . . . . . .
Initializing unions . . . . . . . . . .
Initializing static variables . . . . . . .
Initializing automatic variables . . . . .
Initializing based and controlled variables . .
Examples . . . . . . . . . . . . .
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
243
243
244
245
245
245
246
246
248
249
249
250
251
253
254
255
255
256
256
258
259
259
260
261
262
264
264
265
266
267
268
271
272
272
273
273
273
Chapter 10. Input and output. . . . . 275
Data sets . . . . . . . . . . . . .
Consecutive . . . . . . . . . . .
Indexed . . . . . . . . . . . .
Relative . . . . . . . . . . . .
Regional . . . . . . . . . . . .
Files . . . . . . . . . . . . . .
FILE attribute . . . . . . . . . .
RECORD and STREAM attributes . . .
INPUT, OUTPUT, and UPDATE attributes.
SEQUENTIAL and DIRECT attributes . .
BUFFERED and UNBUFFERED attributes .
ENVIRONMENT attribute . . . . . .
KEYED attribute . . . . . . . . .
PRINT attribute . . . . . . . . .
Opening and closing files . . . . . . .
OPEN statement . . . . . . . . .
Implicit opening . . . . . . . . .
CLOSE statement . . . . . . . . .
FLUSH statement . . . . . . . . .
SYSPRINT and SYSIN . . . . . . . .
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
276
276
276
277
277
277
277
280
281
281
282
282
282
282
283
283
285
287
288
288
Contents
v
Chapter 11. Record-oriented data
transmission. . . . . . . . . . . . 289
Data transmitted . . . . . . . .
Unaligned bit strings . . . . . .
Varying length strings . . . . .
Area variables . . . . . . . .
Data transmission statements . . . .
READ statement . . . . . . .
WRITE statement . . . . . . .
REWRITE statement . . . . . .
LOCATE statement . . . . . .
DELETE statement . . . . . .
Options of data transmission statements
FILE option . . . . . . . . .
FROM option . . . . . . . .
IGNORE option . . . . . . .
INTO option . . . . . . . .
KEY option . . . . . . . . .
KEYFROM option . . . . . . .
KEYTO option . . . . . . . .
SET option . . . . . . . . .
Processing modes . . . . . . . .
Move mode . . . . . . . . .
Locate mode . . . . . . . .
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
289
289
290
290
290
290
291
291
292
292
293
293
293
293
294
294
295
295
296
296
296
296
Chapter 12. Stream-oriented data
transmission. . . . . . . . . . . . 299
Data transmission statements . . . .
GET statement . . . . . . . .
PUT statement . . . . . . . .
Options of data transmission statements
COPY option . . . . . . . .
Data specification options . . . .
FILE option . . . . . . . . .
LINE option . . . . . . . . .
PAGE option . . . . . . . .
SKIP option . . . . . . . . .
STRING option . . . . . . . .
Transmission of data-list items. . . .
Data-directed data specification . . .
Restrictions on data-directed data . .
Syntax of data-directed data . . .
GET data-directed . . . . . . .
PUT data-directed . . . . . . .
Edit-directed data specification . . .
GET edit-directed . . . . . . .
PUT edit-directed . . . . . . .
FORMAT statement . . . . . .
List-directed data specification . . .
Syntax of list-directed data . . . .
GET list-directed . . . . . . .
PUT list-directed . . . . . . .
PRINT attribute . . . . . . . .
DBCS data in stream I/O . . . . .
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
300
300
300
301
301
302
303
304
304
304
305
306
307
307
308
308
310
311
313
313
315
315
315
316
317
318
319
Chapter 13. Edit-directed format items 321
A-format item .
B-format item .
C-format item .
COLUMN format
vi
. .
. .
. .
item
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
Enterprise PL/I for z/OS Language Reference
.
.
.
.
.
.
.
.
321
322
322
323
E-format item . .
F-format item . .
G-format item . .
L-format item . .
LINE format item .
P-format item . .
PAGE format item .
R-format item . .
Example . . .
SKIP format item .
V-format item . .
X-format item . .
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
324
326
328
328
329
329
330
330
330
331
331
332
Chapter 14. Picture specification
characters. . . . . . . . . . . . . 333
Picture repetition factor . . . . . . . .
Picture characters for character data . . . .
Picture characters for numeric character data .
Digits and decimal points . . . . . .
Zero suppression . . . . . . . . .
Insertion characters . . . . . . . .
Defining currency symbols . . . . . .
Signs and currency symbols . . . . .
Credit, debit, overpunched, and zero
replacement characters . . . . . . .
Exponent characters . . . . . . . .
Scaling factor . . . . . . . . . .
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
334
334
335
336
338
339
340
342
.
.
.
. 344
. 346
. 346
Chapter 15. Condition handling. . . . 349
Condition prefixes . . . . . . . . .
Scope of the condition prefix . . . .
Raising conditions with OPTIMIZATION
On-units . . . . . . . . . . . .
ON statement . . . . . . . . .
Null ON-unit . . . . . . . . .
Scope of the ON-unit . . . . . . .
Dynamically descendent ON-units . .
ON-units for file variables . . . . .
REVERT statement . . . . . . . .
SIGNAL statement . . . . . . . .
RESIGNAL statement. . . . . . . .
Multiple conditions . . . . . . . .
CONDITION attribute . . . . . . .
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
349
351
351
351
352
353
353
353
354
355
355
356
356
356
Chapter 16. Conditions . . . . . . . 357
ANYCONDITION condition
AREA condition . . . .
ATTENTION condition . .
CONDITION condition . .
CONVERSION condition .
ENDFILE condition . . .
ENDPAGE condition . . .
ERROR condition . . . .
FINISH condition . . . .
FIXEDOVERFLOW condition
INVALIDOP condition . .
KEY condition . . . . .
NAME condition . . . .
OVERFLOW condition . .
RECORD condition . . .
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
357
358
359
360
361
362
363
364
365
365
366
367
367
368
369
SIZE condition . . . . . .
STORAGE condition . . . .
STRINGRANGE condition . .
STRINGSIZE condition . . .
SUBSCRIPTRANGE condition .
TRANSMIT condition . . .
UNDEFINEDFILE condition .
UNDERFLOW condition . .
ZERODIVIDE condition . . .
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
370
370
371
372
373
373
374
375
376
Chapter 17. Multithreading facility . . 377
Creating a thread . . . . .
ATTACH statement . . . .
Examples . . . . . . .
Terminating a thread . . . .
Waiting for a thread to complete
Detaching a thread . . . .
Condition handling . . . .
Task data and attribute . . .
THREADID built-in function
Sharing data between threads .
Sharing files between threads .
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
378
378
379
379
379
380
380
380
381
381
381
Chapter 18. Built-in functions,
pseudovariables, and subroutines . . 383
Declaring and invoking built-in functions,
pseudovariables, and built-in subroutines . . . .
BUILTIN attribute . . . . . . . . . . .
Invoking built-in functions and pseudovariables
Invoking built-in subroutines . . . . . . .
Specifying arguments for built-in functions,
pseudovariables, and built-in subroutines . . . .
Aggregate arguments. . . . . . . . . .
Null and optional arguments . . . . . . .
Accuracy of mathematical functions . . . . . .
Categories of built-in functions . . . . . . .
Arithmetic built-in functions . . . . . . .
Array-handling built-in functions. . . . . .
Buffer-management built-in functions . . . .
Condition-handling built-in functions . . . .
Date/time built-in functions . . . . . . .
Floating-point inquiry built-in functions . . .
Floating-point manipulation built-in functions
Input/output built-in functions . . . . . .
Integer manipulation built-in functions . . . .
Mathematical built-in functions . . . . . .
Miscellaneous built-in functions . . . . . .
Ordinal-handling built-in functions . . . . .
Precision-handling built-in functions . . . .
Pseudovariables . . . . . . . . . . .
Storage control built-in functions . . . . . .
String-handling built-in functions. . . . . .
Subroutines . . . . . . . . . . . . .
ABS . . . . . . . . . . . . . . . .
ACOS . . . . . . . . . . . . . . . .
ADD . . . . . . . . . . . . . . . .
ADDR. . . . . . . . . . . . . . . .
ADDRDATA . . . . . . . . . . . . .
ALL . . . . . . . . . . . . . . . .
ALLCOMPARE. . . . . . . . . . . . .
386
386
387
387
388
388
388
388
389
389
390
390
391
392
394
395
395
396
396
397
398
398
399
399
401
402
404
405
406
407
408
409
410
ALLOCATE . . . . . .
ALLOCATION . . . . .
ALLOCSIZE . . . . . .
ANY . . . . . . . .
ASIN . . . . . . . .
ATAN . . . . . . . .
ATAND . . . . . . .
ATANH . . . . . . .
AUTOMATIC . . . . .
AVAILABLEAREA . . .
Example . . . . . .
BINARY . . . . . . .
BINARYVALUE . . . .
BIT . . . . . . . . .
BITLOCATION . . . . .
BOOL . . . . . . . .
BYTE . . . . . . . .
CDS . . . . . . . .
CEIL . . . . . . . .
CENTERLEFT . . . . .
Example . . . . . .
CENTRELEFT . . . . .
CENTERRIGHT . . . .
Example . . . . . .
CENTRERIGHT . . . .
CHARACTER . . . . .
Example . . . . . .
CHARGRAPHIC . . . .
Example 1 . . . . .
Example 2 . . . . .
CHARVAL . . . . . .
CHECKSTG . . . . . .
COLLATE . . . . . .
COMPARE . . . . . .
Example . . . . . .
COMPLEX . . . . . .
CONJG . . . . . . .
COPY . . . . . . . .
COS . . . . . . . .
COSD . . . . . . . .
COSH . . . . . . . .
COUNT . . . . . . .
CS . . . . . . . . .
CURRENTSIZE. . . . .
CURRENTSTORAGE . . .
DATAFIELD. . . . . .
DATE . . . . . . . .
DATETIME . . . . . .
DAYS . . . . . . . .
Example . . . . . .
DAYSTODATE . . . . .
DAYSTOSECS . . . . .
DECIMAL . . . . . .
DIMENSION . . . . .
DIVIDE . . . . . . .
EDIT . . . . . . . .
Example . . . . . .
EMPTY . . . . . . .
ENDFILE. . . . . . .
ENTRYADDR . . . . .
ENTRYADDR pseudovariable
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
Contents
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
411
412
413
414
415
416
417
418
419
420
420
421
422
423
424
425
426
427
428
429
429
430
431
431
432
433
433
434
434
434
435
436
437
438
438
439
440
441
442
443
444
445
446
448
449
450
451
452
453
453
454
455
456
457
458
459
459
460
461
462
463
vii
EPSILON . . . . .
ERF . . . . . .
ERFC . . . . . .
EXP . . . . . .
EXPONENT . . . .
FILEDDINT . . . .
FILEDDTEST . . .
FILEDDWORD . . .
FILEID . . . . .
FILEOPEN . . . .
FILEREAD . . . .
FILESEEK . . . .
FILETELL . . . .
FILEWRITE . . . .
FIXED . . . . . .
FIXEDBIN . . . .
FIXEDDEC . . . .
FLOAT . . . . .
FLOATBIN . . . .
FLOATDEC . . . .
FLOOR . . . . .
GAMMA . . . . .
GETENV . . . . .
GRAPHIC . . . .
Example 1 . . .
Example 2 . . .
HANDLE . . . .
HBOUND . . . .
HBOUNDACROSS .
HEX . . . . . .
Example 1 . . .
Example 2 . . .
HEXIMAGE . . . .
HIGH . . . . . .
HUGE . . . . . .
IAND . . . . . .
IEOR . . . . . .
IMAG . . . . . .
IMAG pseudovariable
INDEX . . . . .
Example . . . .
INDICATORS . . .
INOT . . . . . .
Examples . . . .
IOR . . . . . .
ISFINITE . . . . .
ISIGNED . . . . .
Examples . . . .
ISINF . . . . . .
ISLL . . . . . .
Examples . . . .
ISMAIN . . . . .
ISNAN . . . . .
ISNORMAL . . . .
ISRL . . . . . .
Examples . . . .
ISZERO . . . . .
IUNSIGNED . . .
Examples . . . .
LBOUND. . . . .
LBOUNDACROSS. .
viii
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
Enterprise PL/I for z/OS Language Reference
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
464
465
466
467
468
469
470
471
472
473
474
475
476
477
478
479
480
481
482
483
484
485
486
487
487
487
489
490
491
492
492
492
494
495
496
497
498
499
500
501
501
502
503
503
504
505
506
506
507
508
508
509
510
511
512
512
513
514
514
515
516
LEFT . . . . . . . . . . . . . . .
Example . . . . . . . . . . . . .
LENGTH . . . . . . . . . . . . . .
LINENO . . . . . . . . . . . . . .
LOCATION . . . . . . . . . . . . .
Example . . . . . . . . . . . . .
LOG . . . . . . . . . . . . . . .
LOGGAMMA . . . . . . . . . . . .
LOG2 . . . . . . . . . . . . . . .
LOG10 . . . . . . . . . . . . . .
LOW . . . . . . . . . . . . . . .
LOWERCASE . . . . . . . . . . . .
LOWER2 . . . . . . . . . . . . . .
Examples . . . . . . . . . . . . .
MAX . . . . . . . . . . . . . . .
MAXEXP . . . . . . . . . . . . . .
Example (Intel Values) . . . . . . . .
Example (AIX Values) . . . . . . . .
Example (z/OS Hexdecimal Values) . . . .
Example (z/OS IEEE Binary Floating Point
Values) . . . . . . . . . . . . .
Example (z/OS IEEE Decimal Floating Point
Values) . . . . . . . . . . . . .
MAXLENGTH . . . . . . . . . . . .
Example . . . . . . . . . . . . .
MEMCONVERT . . . . . . . . . . .
MEMCU12 . . . . . . . . . . . . .
MEMCU14 . . . . . . . . . . . . .
MEMCU21 . . . . . . . . . . . . .
MEMCU24 . . . . . . . . . . . . .
MEMCU41 . . . . . . . . . . . . .
MEMCU42 . . . . . . . . . . . . .
MEMINDEX. . . . . . . . . . . . .
Example . . . . . . . . . . . . .
MEMSEARCH . . . . . . . . . . . .
Example . . . . . . . . . . . . .
MEMSEARCHR . . . . . . . . . . .
Example . . . . . . . . . . . . .
MEMVERIFY . . . . . . . . . . . .
Example . . . . . . . . . . . . .
MEMVERIFYR . . . . . . . . . . . .
Example . . . . . . . . . . . . .
MIN . . . . . . . . . . . . . . .
MINEXP . . . . . . . . . . . . . .
Example (Intel Values) . . . . . . . .
Example (AIX Values) . . . . . . . .
Example (z/OS Hexadecimal Values) . . .
Example (z/OS IEEE Binary Floating Point
Values) . . . . . . . . . . . . .
Example (z/OS IEEE Decimal Floating Point
Values) . . . . . . . . . . . . .
MOD . . . . . . . . . . . . . . .
Example . . . . . . . . . . . . .
MPSTR . . . . . . . . . . . . . .
MULTIPLY . . . . . . . . . . . . .
NULL . . . . . . . . . . . . . . .
OFFSET . . . . . . . . . . . . . .
OFFSETADD . . . . . . . . . . . .
OFFSETDIFF . . . . . . . . . . . .
OFFSETSUBTRACT . . . . . . . . . .
OFFSETVALUE. . . . . . . . . . . .
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
517
517
518
519
520
520
521
522
523
524
525
526
527
527
528
529
529
529
529
. 529
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
529
530
530
531
532
533
534
535
536
537
538
538
539
539
540
540
541
541
542
542
543
544
544
544
544
. 544
.
.
.
.
.
.
.
.
.
.
.
544
545
545
546
547
548
549
550
551
552
553
OMITTED . . . . . . . . . . . . .
ONAREA . . . . . . . . . . . . .
ONCHAR . . . . . . . . . . . . .
ONCHAR pseudovariable . . . . . . . .
ONCODE . . . . . . . . . . . . .
ONCONDCOND . . . . . . . . . . .
ONCONDID . . . . . . . . . . . .
ONCOUNT . . . . . . . . . . . . .
ONFILE . . . . . . . . . . . . . .
ONGSOURCE . . . . . . . . . . . .
ONGSOURCE pseudovariable . . . . . . .
ONKEY . . . . . . . . . . . . . .
ONLINE . . . . . . . . . . . . . .
ONLOC . . . . . . . . . . . . . .
ONOFFSET . . . . . . . . . . . . .
ONSOURCE. . . . . . . . . . . . .
ONSOURCE pseudovariable . . . . . . .
ONSUBCODE . . . . . . . . . . . .
ONWCHAR . . . . . . . . . . . . .
ONWCHAR pseudovariable . . . . . . .
ONWSOURCE . . . . . . . . . . . .
ONWSOURCE pseudovariable . . . . . .
ORDINALNAME . . . . . . . . . . .
ORDINALPRED . . . . . . . . . . .
ORDINALSUCC . . . . . . . . . . .
PACKAGENAME . . . . . . . . . . .
PAGENO . . . . . . . . . . . . . .
PICSPEC . . . . . . . . . . . . . .
PLACES . . . . . . . . . . . . . .
Example (Intel Values) . . . . . . . .
Example (AIX Values) . . . . . . . .
Example (z/OS Hexadecimal Values) . . .
Example (z/OS IEEE Binary Floating Point
Values) . . . . . . . . . . . . .
Example (z/OS IEEE Decimal Floating Point
Values) . . . . . . . . . . . . .
PLIASCII . . . . . . . . . . . . . .
PLICANC . . . . . . . . . . . . .
PLICKPT . . . . . . . . . . . . . .
PLIDELETE . . . . . . . . . . . . .
PLIDUMP . . . . . . . . . . . . .
PLIEBCDIC . . . . . . . . . . . . .
PLIFILL . . . . . . . . . . . . . .
Example . . . . . . . . . . . . .
PLIFREE . . . . . . . . . . . . . .
PLIMOVE . . . . . . . . . . . . .
Example . . . . . . . . . . . . .
PLIOVER. . . . . . . . . . . . . .
PLIREST . . . . . . . . . . . . . .
PLIRETC . . . . . . . . . . . . . .
PLIRETV . . . . . . . . . . . . . .
PLISAXA . . . . . . . . . . . . . .
PLISAXB . . . . . . . . . . . . . .
PLISAXC . . . . . . . . . . . . . .
PLISAXD . . . . . . . . . . . . . .
PLISRTA . . . . . . . . . . . . . .
PLISRTB . . . . . . . . . . . . . .
PLISRTC . . . . . . . . . . . . . .
PLISRTD . . . . . . . . . . . . . .
PLITRAN11 . . . . . . . . . . . . .
PLITRAN12 . . . . . . . . . . . . .
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
554
555
556
557
558
559
560
561
562
563
564
565
566
567
568
569
570
571
572
573
574
575
576
577
578
579
580
581
582
582
582
582
. 582
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
582
583
584
585
586
587
588
589
589
590
591
591
592
593
594
595
596
597
598
599
600
601
602
603
604
605
PLITRAN21 . . . . . . . . . . . .
PLITRAN22 . . . . . . . . . . . .
POINTER . . . . . . . . . . . .
POINTERADD . . . . . . . . . . .
POINTERDIFF . . . . . . . . . . .
POINTERSUBTRACT. . . . . . . . .
POINTERVALUE . . . . . . . . . .
POLY . . . . . . . . . . . . . .
POPCNT . . . . . . . . . . . . .
PRECISION . . . . . . . . . . . .
PRED . . . . . . . . . . . . . .
PRESENT . . . . . . . . . . . .
PROCEDURENAME . . . . . . . . .
PROD . . . . . . . . . . . . . .
PUTENV . . . . . . . . . . . . .
RADIX . . . . . . . . . . . . .
RAISE2 . . . . . . . . . . . . .
Example . . . . . . . . . . . .
RANDOM . . . . . . . . . . . .
RANK. . . . . . . . . . . . . .
REAL . . . . . . . . . . . . . .
REAL pseudovariable . . . . . . . .
REG12. . . . . . . . . . . . . .
REM . . . . . . . . . . . . . .
REPATTERN . . . . . . . . . . .
REPEAT . . . . . . . . . . . . .
REPLACEBY2 . . . . . . . . . . .
REVERSE. . . . . . . . . . . . .
Example . . . . . . . . . . . .
RIGHT . . . . . . . . . . . . .
Example . . . . . . . . . . . .
ROUND . . . . . . . . . . . . .
ROUND of FIXED. . . . . . . . .
ROUND of IEEE decimal floating point .
ROUND of IEEE binary floating point . .
ROUND of IBM hexadecimal floating point
ROUNDDEC . . . . . . . . . . .
SAMEKEY . . . . . . . . . . . .
SCALE . . . . . . . . . . . . .
SEARCH . . . . . . . . . . . . .
Example 1 . . . . . . . . . . .
Example 2 . . . . . . . . . . .
SEARCHR . . . . . . . . . . . .
Example . . . . . . . . . . . .
SECS . . . . . . . . . . . . . .
Example . . . . . . . . . . . .
SECSTODATE . . . . . . . . . . .
SECSTODAYS . . . . . . . . . . .
SIGN . . . . . . . . . . . . . .
SIGNED . . . . . . . . . . . . .
SIN. . . . . . . . . . . . . . .
SIND . . . . . . . . . . . . . .
SINH . . . . . . . . . . . . . .
SIZE . . . . . . . . . . . . . .
Example . . . . . . . . . . . .
SOURCEFILE . . . . . . . . . . .
SOURCELINE . . . . . . . . . . .
SQRT . . . . . . . . . . . . . .
SQRTF . . . . . . . . . . . . .
STACKADDR . . . . . . . . . . .
STORAGE . . . . . . . . . . . .
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
Contents
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
606
607
608
609
610
611
612
613
614
615
616
617
618
619
620
621
622
622
623
624
625
626
627
628
629
630
631
632
632
633
633
634
634
634
635
635
636
637
638
639
639
639
641
641
642
642
643
644
645
646
647
648
649
650
650
652
653
654
655
656
657
ix
STRING . . . . . . . .
STRING pseudovariable . . .
SUBSTR . . . . . . . .
SUBSTR pseudovariable . . .
SUBTRACT . . . . . . .
SUCC . . . . . . . . .
SUM . . . . . . . . .
SYSNULL . . . . . . .
SYSTEM . . . . . . . .
TALLY . . . . . . . .
Example . . . . . . .
TAN . . . . . . . . .
TAND . . . . . . . . .
TANH . . . . . . . . .
THREADID . . . . . . .
TIME . . . . . . . . .
TINY . . . . . . . . .
TRANSLATE . . . . . .
Example . . . . . . .
TRIM . . . . . . . . .
Example . . . . . . .
TRUNC . . . . . . . .
TYPE . . . . . . . . .
TYPE pseudovariable. . . .
ULENGTH . . . . . . .
ULENGTH8 . . . . . . .
ULENGTH16 . . . . . .
UNALLOCATED . . . . .
UNSIGNED . . . . . . .
UNSPEC . . . . . . . .
UNSPEC pseudovariable . .
Example . . . . . . .
UPOS . . . . . . . . .
UPPERCASE . . . . . .
USUBSTR . . . . . . .
USUPPLEMENTARY . . . .
UTF8 . . . . . . . . .
UTF8TOCHAR . . . . . .
UTF8TOWCHAR . . . . .
UVALID . . . . . . . .
UWIDTH. . . . . . . .
VALID . . . . . . . .
VALIDDATE . . . . . .
Example . . . . . . .
VARGLIST . . . . . . .
VARGSIZE . . . . . . .
VERIFY . . . . . . . .
Example . . . . . . .
VERIFYR . . . . . . . .
Example . . . . . . .
WCHARVAL . . . . . .
WEEKDAY . . . . . . .
WHIGH . . . . . . . .
WIDECHAR. . . . . . .
WLOW . . . . . . . .
XMLCHAR . . . . . . .
Example of using XMLCHAR
Y4DATE . . . . . . . .
Y4JULIAN . . . . . . .
Y4YEAR . . . . . . . .
x
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
Enterprise PL/I for z/OS Language Reference
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
658
660
661
662
663
664
665
666
667
668
668
669
670
671
672
673
674
675
675
676
676
677
678
679
680
681
682
683
684
685
687
687
688
689
690
691
692
693
694
695
697
698
699
699
700
701
702
702
703
703
704
705
706
707
708
709
709
711
712
713
Chapter 19. Type Functions . . . . . 715
Invoking type functions . . . . . .
Specifying arguments for type functions
Brief descriptions of type functions . .
BIND . . . . . . . . . . . .
CAST . . . . . . . . . . . .
FIRST . . . . . . . . . . . .
Example . . . . . . . . . .
LAST . . . . . . . . . . . .
Example . . . . . . . . . .
NEW . . . . . . . . . . . .
RESPEC . . . . . . . . . . .
SIZE . . . . . . . . . . . .
VALUE . . . . . . . . . . .
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
726
727
727
729
730
730
731
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
731
732
733
734
736
737
738
739
740
741
742
743
744
745
746
747
748
749
750
751
752
753
754
755
756
757
758
759
760
761
762
763
764
765
765
765
766
Chapter 20. Preprocessor Facilities
Preprocessor Options . . . . . . . . .
Preprocessor Scan . . . . . . . . . .
Preprocessor Statements . . . . . . .
Preprocessor Variables and Data Elements . .
Preprocessor References and Expressions . .
Scope of Preprocessor Names . . . . . .
Preprocessor Procedures . . . . . . . .
Arguments and Parameters for Preprocessor
Procedures . . . . . . . . . . .
%PROCEDURE Statement . . . . . .
Preprocessor RETURN Statement . . . .
Preprocessor ANSWER Statement . . .
Preprocessor Built-In Functions . . . . .
COLLATE . . . . . . . . . . .
COMMENT . . . . . . . . . . .
COMPILEDATE . . . . . . . . .
COMPILETIME . . . . . . . . .
COPY . . . . . . . . . . . . .
COUNTER . . . . . . . . . . .
DIMENSION . . . . . . . . . .
HBOUND . . . . . . . . . . .
INDEX . . . . . . . . . . . .
LBOUND. . . . . . . . . . . .
LENGTH . . . . . . . . . . . .
LOWERCASE . . . . . . . . . .
MACCOL . . . . . . . . . . .
MACLMAR . . . . . . . . . . .
MACNAME . . . . . . . . . . .
MACRMAR . . . . . . . . . . .
MAX . . . . . . . . . . . . .
MIN . . . . . . . . . . . . .
PARMSET . . . . . . . . . . .
QUOTE . . . . . . . . . . . .
REPEAT . . . . . . . . . . . .
SUBSTR . . . . . . . . . . . .
SYSPARM . . . . . . . . . . .
SYSTEM . . . . . . . . . . . .
SYSVERSION . . . . . . . . . .
TRANSLATE . . . . . . . . . .
TRIM . . . . . . . . . . . . .
UPPERCASE . . . . . . . . . .
VERIFY . . . . . . . . . . . .
Preprocessor Statements . . . . . . . .
%ACTIVATE Statement . . . . . . .
%assignment Statement . . . . . . .
715
715
715
717
718
719
719
720
720
721
722
723
724
725
%DEACTIVATE Statement
%DECLARE Statement .
%DO Statement . . .
%END Statement . . .
%GO TO Statement . .
%IF Statement . . . .
%INCLUDE Statement .
%INSCAN Statement . .
%ITERATE Statement .
%LEAVE Statement . .
%NOTE Statement . .
%null Statement . . .
%REPLACE Statement .
%SELECT Statement . .
%XINCLUDE Statement .
%XINSCAN Statement .
Preprocessor Examples . .
Example 1 . . . . .
Example 2 . . . . .
Example 3 . . . . .
Example 4 . . . . .
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
766
767
769
770
770
771
771
772
773
773
773
774
774
775
775
775
776
776
776
777
777
Example 5
Example 6
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
. 778
. 778
Appendix. Limits . . . . . . . . . . 781
Notices . . . . . . . . . . . . . . 787
Trademarks .
.
.
.
.
.
.
.
.
.
.
.
.
. 788
Bibliography . . . . . . . . . . . . 789
PL/I publications . . . .
Enterprise PL/I for z/OS
PL/I for MVS & VM . .
PL/I for AIX . . . .
Related publications . . .
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
789
789
789
789
789
Glossary . . . . . . . . . . . . . 791
Index . . . . . . . . . . . . . . . 809
Contents
xi
xii
Enterprise PL/I for z/OS Language Reference
Tables
1.
2.
3.
4.
5.
6.
7.
8.
9.
10.
11.
12.
13.
14.
15.
16.
17.
18.
19.
20.
21.
22.
23.
24.
25.
26.
27.
28.
29.
30.
31.
Alphabetic equivalents . . . . . . . . . 2
Decimal digit equivalents . . . . . . . . 3
Special character equivalents . . . . . . . 3
Composite symbol description . . . . . . 4
Delimiters . . . . . . . . . . . . . 6
Operators . . . . . . . . . . . . . 6
Classification of attributes by constant types
19
Classification of attributes by variable types
21
Abbreviations for coded arithmetic data
attributes . . . . . . . . . . . . . 23
FIXED BINARY SIGNED data storage
requirements . . . . . . . . . . . . 25
FIXED BINARY UNSIGNED data storage
requirements . . . . . . . . . . . . 25
Abbreviations for string data attributes
30
Results of arithmetic operations for one or
more FLOAT operands . . . . . . . . . 58
Results of arithmetic operations between two
unscaled FIXED operands under RULES(ANS) . 59
Results of arithmetic operations between two
scaled FIXED operands under RULES(ANS) . 60
Results of arithmetic operations between two
FIXED operands under RULES(IBM) . . . . 61
Comparison of FIXED division and constant
expressions . . . . . . . . . . . . 62
Special cases for exponentiation . . . . . . 62
Bit operations . . . . . . . . . . . . 63
Bit operation examples . . . . . . . . . 63
Priority of operations and guide to conversions 68
CEIL (n*3.32) and CEIL (n/3.32) values
76
Ordinal-handling built-in functions . . . . 147
Type functions . . . . . . . . . . . 150
Alignment on integral boundaries of
halfwords, words, and doublewords . . . . 164
Alignment requirements . . . . . . . . 164
Default arithmetic precisions . . . . . . 169
Compound assignment operators . . . . . 199
Alternative file attributes. . . . . . . . 278
Attributes by data transmission type
278
Attributes of PL/I file declarations . . . . 279
© Copyright IBM Corp. 1999, 2012
32.
33.
34.
35.
36.
37.
38.
39.
40.
41.
42.
43.
44.
45.
46.
47.
48.
49.
50.
51.
52.
53.
54.
55.
56.
57.
58.
59.
60.
61.
62.
63.
64.
65.
66.
67.
Attributes implied by implicit open . . . .
Merged and implied attributes . . . . . .
Options and format items for PRINT files
Character picture specification examples
Examples of digit and decimal point
characters . . . . . . . . . . . . .
Examples of zero suppression characters
Examples of insertion characters . . . . .
Examples of signs and currency characters
Interpretation of the T, I, and R picture
characters . . . . . . . . . . . . .
Examples of credit, debit, overpunched, and
zero replacement characters . . . . . . .
Examples of exponent characters . . . . .
Examples of scaling factor characters
Classes and status of conditions . . . . .
Built-in functions and pseudovariables that
accept structure or union arguments . . . .
Arithmetic built-in functions . . . . . .
Array-handling built-in functions . . . . .
Buffer-management built-in functions
Condition-handling built-in functions
Date/time built-in functions . . . . . .
Date/time patterns. . . . . . . . . .
Floating-point inquiry built-in functions
Floating-point manipulation built-in functions
Input/output built-in functions . . . . .
Integer manipulation built-in functions
Mathematical built-in functions . . . . .
Miscellaneous built-in functions . . . . .
Ordinal-handling built-in functions . . . .
Precision-handling built-in functions . . . .
Built-in pseudovariables . . . . . . . .
Storage control built-in functions . . . . .
String-handling built-in functions . . . . .
Built-in subroutines . . . . . . . . .
Length of bit string returned by UNSPEC
Type functions . . . . . . . . . . .
Language element limits . . . . . . . .
Macro facility limits . . . . . . . . .
285
286
318
335
337
338
340
343
344
346
346
347
350
388
389
390
390
391
392
394
394
395
395
396
396
397
398
398
399
400
401
402
685
715
781
784
xiii
xiv
Enterprise PL/I for z/OS Language Reference
Figures
1.
2.
3.
4.
5.
6.
7.
8.
9.
10.
Named constants. . . . . . . . . . . 44
A PL/I application structure . . . . . . . 88
Package statement . . . . . . . . . . 93
Array argument with parameters . . . . . 98
Valid and invalid call statements . . . . . 119
Sample program illustrating LIST attribute
121
Scopes of data declarations . . . . . . . 156
Scopes of entry and label declarations
157
Example of scopes of various declarations
160
Mapping of example structure . . . . . . 189
© Copyright IBM Corp. 1999, 2012
11.
12.
13.
14.
15.
16.
17.
18.
19.
Mapping of minor structure G . . .
Mapping of minor structure E . . .
Mapping of minor structure N . . .
Mapping of minor structure S . . .
Mapping of minor structure C . . .
Mapping of minor structure M. . .
Mapping of major structure A . . .
Offsets in final mapping of structure A
Example of one-directional chain . .
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
190
190
191
191
192
192
193
194
. 257
xv
xvi
Enterprise PL/I for z/OS Language Reference
About this book
Notation conventions used in this book . . . . xvii
Semantics . . . . . . . . . . . . . . . xx
Industry standards used . . . . . . . . . . xx
Summary of changes . . . . . . . . . . . xx
Enhancements in this release . . . . . . . xx
Enhancements from V4R2 . . . . . . . . xxi
Enhancements from V4R1 . . . . . . . . xxi
Enhancements from V3R9 . . . . . . . . xxii
Enhancements from V3R8 . . . . . . . . xxii
Enhancements from V3R7 . . . . . . . . xxiii
Enhancements from V3R6 . . . . . . . . xxiv
Enhancements from V3R5 . . . . . . . . xxiv
Enhancements from V3R4 . . . . . . . . xxiv
Enhancements from V3R3 . . . . . . . . xxv
Enhancements from V3R2 . . . . . . . . xxv
Enhancements from V3R1 . . . . . . . . xxv
How to send your comments . . . . . . . xxvii
Accessibility . . . . . . . . . . . . . xxvii
Interface information . . . . . . . . . xxvii
Keyboard navigation . . . . . . . . . xxviii
Accessibility of this information . . . . . xxviii
IBM and accessibility . . . . . . . . . xxviii
This book is a reference for the programmer using the IBM PL/I compiler in these
IBM products:
v Enterprise PL/I for z/OS, V4R3
v PL/I for AIX, V3R1
v Rational Developer for System z PL/I for Windows, Version 8.5
It is not a tutorial, but is designed for the reader who already has a knowledge of
the PL/I language and who requires reference information needed to write a
program for an IBM PL/I compiler. It contains guidance information and
general-use programming interfaces.
Because this book is a reference manual, it is not intended to be read from front to
back, and terms can be used before they are defined. Terms are highlighted where
they are defined in the book, and definitions are found in the glossary.
Text set apart by the workstation opening and closing icons designates features
which are supported only on PL/I workstation products (AIX and Windows).
Notation conventions used in this book
The following sections describe how information is presented in this book.
Examples and user-supplied information are presented in mixed-case characters.
The following rules apply to the syntax diagrams used in this book:
Arrow symbols
Read the syntax diagrams from left to right, from top to bottom, following
the path of the line.
───
Indicates the beginning of a statement.
───
Indicates that the statement syntax is continued on the next line.
───
Indicates that a statement is continued from the previous line.
───
Indicates the end of a statement.
Diagrams of syntactical units other than complete statements start with the
─── symbol and end with the ─── symbol.
Conventions
© Copyright IBM Corp. 1999, 2012
xvii
About this book
v Keywords, their allowable synonyms, and reserved parameters, appear
in uppercase for the MVS platform, and lowercase for UNIX® platform.
These items must be entered exactly as shown.
v Variables appear in lowercase italics (for example, column-name). They
represent user-defined parameters or suboptions.
v When entering commands, separate parameters and keywords by at
least one blank if there is no intervening punctuation.
v Enter punctuation marks (slashes, commas, periods, parentheses,
quotation marks, equal signs) and numbers exactly as given.
v Footnotes are shown by a number in parentheses, for example, (1).
v A symbol indicates one blank position.
Required items
Required items appear on the horizontal line (the main path).
REQUIRED_ITEM
Optional Items
Optional items appear below the main path.
REQUIRED_ITEM
optional_item
If an optional item appears above the main path, that item has no effect on
the execution of the statement and is used only for readability.
optional_item
REQUIRED_ITEM
Multiple required or optional items
If you can choose from two or more items, they appear vertically in a
stack. If you must choose one of the items, one item of the stack appears on
the main path.
REQUIRED_ITEM
required_choice1
required_choice2
If choosing one of the items is optional, the entire stack appears below the
main path.
REQUIRED_ITEM
optional_choice1
optional_choice2
Repeatable items
An arrow returning to the left above the main line indicates that an item
can be repeated.
REQUIRED_ITEM repeatable_item
xviii
Enterprise PL/I for z/OS Language Reference
About this book
If the repeat arrow contains a comma, you must separate repeated items
with a comma.
,
REQUIRED_ITEM repeatable_item
A repeat arrow above a stack indicates that you can specify more than one
of the choices in the stack.
Default keywords
IBM-supplied default keywords appear above the main path, and the
remaining choices are shown below the main path. In the parameter list
following the syntax diagram, the default choices are underlined.
default_choice
REQUIRED_ITEM
optional_choice
optional_choice
Fragments
Sometimes a diagram must be split into fragments. The fragments are
represented by a letter or fragment name, set off like this: | A |. The
fragment follows the end of the main diagram. The following example
shows the use of a fragment.
STATEMENT item 1 item 2
A
A:
item 3
item 4
KEYWORD
item 5
item 6
Substitution-block
Sometimes a set of several parameters is represented by a
substitution-block such as <A>. For example, in the imaginary /VERB
command you could enter /VERB LINE 1, /VERB EITHER LINE 1, or /VERB
OR LINE 1.
/VERB
LINE
line#
<A>
where <A> is:
EITHER
OR
Parameter endings
Parameters with number values end with the symbol '#', parameters that
are names end with 'name', and parameters that can be generic end with
'*'.
About this book
xix
About this book
/MSVERIFY
MSNAME msname
SYSID sysid#
The MSNAME keyword in the example supports a name value and the
SYSID keyword supports a number value.
Semantics
To describe the PL/I language, the following conventions are used:
v The descriptions are informal. For example, we usually write “x must be a
variable” instead of the more precise “x must be the name of a variable”.
Similarly, we can sometimes write “x is transmitted” instead of “the value of x is
transmitted”. When the syntax indicates “reference”, we can later write “the
variable” instead of “the referenced variable”.
v When we say that two different source constructs are equivalent, we mean that
they produce the same result, and not necessarily that the implementation is the
same.
v Unless specifically stated in the text following the syntax specification, the
unqualified term “expression” or “reference” refers to a scalar expression. For an
expression other than a scalar expression, the type of expression is noted. For
example, the term “array expression” indicates that neither a scalar expression
nor a structure expression is valid.
v When a result or behavior is undefined, it is something you “must not” do. Use
of an undefined feature is likely to produce different results on different
implementations or releases of a PL/I product. The application program is
considered to be in error.
v Default is used to describe an alternative value, attribute, or option that is
assumed by the system when no explicit choice is specified.
v Implicit is used to describe the action taken in the absence of an explicit
specification by the program.
v The lowercase letter b, when not in a word, indicates a blank character.
Industry standards used
The PL/I compiler is designed according to the specifications of the following
industry standards as understood and interpreted by IBM as of December 1987:
v American National Standard Code for Information Interchange (ASCII),
X3.4 - 1977
v American National Standard Representation of Pocket Select Characters in
Information Interchange, level 1, X3.77 - 1980 (proposed to ISO, March 1, 1979)
v The draft proposed American National Standard Representation of Vertical
Carriage Positioning Characters in Information Interchange, level 1, dpANS
X3.78 (also proposed to ISO, March 1, 1979)
v Selected features of the American National Standard PL/I General Purpose
Subset (ANSI X3.74-1987).
Summary of changes
Enhancements in this release
This release provides the following functional enhancements described in this and
the other IBM PL/I books.
xx
Enterprise PL/I for z/OS Language Reference
About this book
v The new ASSERT statement improves the verification of the correctness of a
program. It asserts whether a condition is true or false or a statement should not
be executed.
v The support of the following handle operations is enhanced to allow:
– Comparing handles with the same associated structure type.
– Adding to and subtracting from handles with sensitivity to the associated
structure type.
– Computing the difference of two handles with sensitivity to the associated
structure type.
v The maximum length of WIDECHAR strings is increased to 32767.
v Some use of LIKE with LIKE is now supported.
v You can use the SUPPRESS attribute on PROCEDURE statements.
v The support of OPTIONAL parameters allows users to pass an omitted
OPTIONAL parameter as an argument to an entry if the corresponding
parameter in the declaration for that entry is also OPTIONAL.
v INOUT and OUTONLY now imply BYADDR.
v The new ALLCOMPARE built-in function supports the comparison of two
structures.
v The USUPPLEMENTARY built-in function now replaces USURROGATE.
v The new built-in functions UTF8, UTF8TOCHAR, and UTF8TOWCHAR can
convert between CHAR and UTF-8 with sensitivity to the CODEPAGE option.
They also simplify conversions between UTF-8 and UTF-16. The UTF8 function
also allows the user to create UTF-8 literals and to initialize static variables with
UTF-8 data.
Enhancements from V4R2
This release provides the following functional enhancements described in this and
the other IBM PL/I books.
v XML generation, by using the XMLCHAR built-in function, now supports XML
attributes and the omission of null values.
v The compiler now explicitly supports some use of adjustable BASED without
REFER.
v The compiler now supports comparisons of POINTER to null strings ('' and ''b).
v The compiler has raised the maximum number of distinct include files allowed
in a single compilation from 2047 to 4095.
v The new BY DIMACROSS form of assignments makes it easier to write code to
handle the results of SQL multi-row fetch.
v The compiler and the preprocessors (rather than just the SQL preprocessor when
parsing EXEC SQL code) now all support <> as a not-equals symbol.
v The new INDICATORS built-in function makes it easy to declare an array to be
used as an SQL indicator variable with a structure.
v The new POPCNT built-in function returns a FIXED BIN value holding in each
byte the number of bits equal to 1 in the corresponding byte of x.
Enhancements from V4R1
This release provides the following functional enhancements described in this and
the other IBM PL/I books.
v The new PLISAXD built-in subroutine provides the ability to parse XML
documents with validation against a schema.
About this book
xxi
About this book
v The new ONAREA built-in function allows you to have easy access to another
piece of information formerly available only in the runtime error message or
memory dump, namely the name of the AREA reference for which an AREA
condition is raised.
v The new VALUE type function supports the initialization of or assignment to a
variable that has the corresponding structure type.
v The INITIAL attribute is allowed on the elementary names of the DEFINE
STRUCTURE statement.
Enhancements from V3R9
This release provides the following functional enhancements described in this and
the other IBM PL/I books.
v The new MEMCU12, MEMCU21, MEMCU14, MEMCU24, MEMCU41, and
MEMCU42 built-in functions provide the ability to convert between UTF-8,
UTF-16, and UTF-32, and on z/OS, they do this with inline code that exploits
the corresponding hardware instruction.
v The new PLITRAN11, PLITRAN12, PLITRAN21, and PLITRAN22 built-in
functions provide the ability to translate one-byte and/or two-byte buffers, and
on z/OS, they do this with inline code that exploits the corresponding hardware
instruction.
v The new USURROGATE built-in function provides the ability to test if a CHAR
or WCHAR string contains any UTF surrogate pairs.
v The new ROUNDDEC built-in function provides the ability to specify that a
DFP number should be rounded at the nth decimal digit (rather than at the nth
digit as provided by the ROUND built-in function).
v The new INONLY, INOUT, and OUTONLY attributes will make it easier to make
code more self-documenting and to allow the compiler to produce more accurate
diagnostics (for example, the compiler can now not flag dummy arguments if
they are declared as INONLY and not flag uninitialized arguments if they are
declared as OUTONLY).
v The new %DO SKIP; statement makes it easy to exclude blocks of code from the
compilation and to "comment out" comments.
v Six additional datetime patterns support zero suppression on input and output.
Enhancements from V3R8
This release provides the following functional enhancements described in this and
the other IBM PL/I books.
v The new PLISAXC built-in function will allow the user to exploit the z/OS XML
System Services parser as if it were a SAX parser. Thanks to the underlying
support in this parser, PLISAXC will provide support for name spaces as well as
documents that are larger than 2G.
v The new ULENGTH, ULENGTH8, ULENGTH16, UPOS, USUBSTR, UVALID
and UWIDTH built-in functions will allow the user to query and process strings
containing UTF-8 and UTF-16 data.
v The new FIXEDBIN, FIXEDDEC, FLOATBIN and FLOATDEC built-in functions
will allow the user to specify all the result attributes (other than the mode) in a
numeric conversion and thus allow the user to write not only more easily
understood code but code that will also perform better (particularly for some
DFP conversions).
xxii
Enterprise PL/I for z/OS Language Reference
About this book
v The new ONLINE built-in function will allow the user to have easy access to
another piece of information formerly available only in the runtime error
message or dump, namely the line number in the user code at which a condition
was raised.
v The new REG12 built-in function will return the address of the CAA and will
make it easier for users to write code that uses some Language Environment
services.
v The REPATTERN built-in function will support 3 additional DB2 date-time
formats.
v The new DIMACROSS attribute will make it easier to exploit DB2 multi-row
fetch.
v The new SUPPRESS attribute will make it easier to selectively suppress the
compiler warning messages for uninitialized and unreferenced variables.
v Trailing OPTIONAL arguments may now be omitted also on calls to internal
procedures.
v The new HEX suboption of the USAGE compiler option will allow the user to
specify how much data is displayed when applying the HEX built-in function to
VARYING and VARYINGZ strings.
Enhancements from V3R7
This release provides the following functional enhancements described in this and
the other IBM PL/I books.
v IEEE Decimal Floating-Point (DFP) is supported.
This includes support for the following new built-in functions:
– ISFINITE
– ISINF
– ISNAN
– ISNORMAL
– ISZERO
Also, as part of the DFP support, the following old built-in functions have been
updated:
– EPSILON
–
–
–
–
–
–
–
EXPONENT
HUGE
MAXEXP
MINEXP
PLACES
PRED
RADIX
– ROUND
– SCALE
– SUCC
– TINY
v The new MEMCONVERT built-in function will allow the user to convert
arbitrary lengths of data between arbitrary code pages.
About this book
xxiii
About this book
v The new ONOFFSET built-in function will allow the user to have easy access to
another piece of information formerly available only in the runtime error
message or dump, namely the offset in the user procedure at which a condition
was raised.
v The new STACKADDR built-in function will return the address of the current
dynamic save area (register 13 on z/OS) and will make it easier for users to
write their own diagnostic code.
v The new QUOTE option will allow the user to specify alternate code points for
the quote (") symbol since this symbol is not code-page invariant.
v The new XML compiler option can be used to specify that the tags in the output
of the XMLCHAR built-in function be either in all upper case or in the case in
which they were declared.
Enhancements from V3R6
This release provides the following new language features (additional
platform-specific enhancements are described in the appropriate Programming
Guide):
v The PICSPEC built-in function is now supported so that CHARACTER data may
be quickly cast to PICTURE.
v The THREADID built-in function may now be used under z/OS. It has also
been changed so that it returns a pointer to the thread identifier and so that it
always requires a parameter.
Enhancements from V3R5
This release provides the following new language features (additional
platform-specific enhancements are described in the appropriate Programming
Guide):
v The LOCATION built-in function may now specify the first element using
REFER in a structure without the structure having been allocated
v The DB2 date patterns 'YYYY-MM-DD', 'MM/DD/YYYY' and 'DD.MM.YYYY'
may now be used in the datetime-handling built-in functions
Enhancements from V3R4
This release provides the following new language features (additional
platform-specific enhancements are described in the appropriate Programming
Guide):
v The semantics for the DEFAULT statement now match those of the old host
compiler.
v Support for RETURN statements inside BEGIN blocks within PROCEDURES
containing ENTRY statements
v The REPLACEBY2 built-in function
v The NOINIT attribute
v The following built-in functions in the MACRO preprocessor
–
–
–
–
xxiv
LOWERCASE
MACNAME
TRIM
UPPERCASE
Enterprise PL/I for z/OS Language Reference
About this book
Enhancements from V3R3
This release also provides all of the functional enhancements offered in Enterprise
PL/I V3R3, including the following language features:
v The following built-in functions
– MEMINDEX
– MEMSEARCH
– MEMSEARCHR
– MEMVERIFY
– MEMVERIFYR
– XMLCHAR
v The V format item in GET EDIT.
Enhancements from V3R2
This release also provides all of the functional enhancements offered in Enterprise
PL/I V3R2, including the following the following language features:
v Support for the NOMAP, NOMAPIN and NOMAP attributes for PROCs and
ENTRYs with OPTIONS(COBOL).
v Support, in the same manner as provided by the old host compiler, for PROCs
with ENTRY statements that have differing RETURNS attributes.
v OPTIONS(RETCODE) is assumed for PROCs and ENTRYs with
OPTIONS(COBOL).
v The SIZE condition is no longer promoted to ERROR if unhandled.
v The new USAGE compiler option gives you full control over the IBM or ANS
behavior of the ROUND and UNSPEC built-in function without the other effects
of the RULES(IBM|ANS) option.
v POINTERs are now allowed in PUT LIST and PUT EDIT statements: the 8-byte
hex value will be output.
v If specified on a STATIC variable, the ABNORMAL attribute will cause that
variable to be retained even if unused.
Enhancements from V3R1
This release also provides all of the functional enhancements offered in Enterprise
PL/I V3R1, including the following:
v Support for Multithreading on z/OS
v Support for IEEE floating-point on z/OS
v Support for the ANSWER statement in the macro prepreprocessor
v SAX-style XML parsing via the PLISAXA and PLISAXB built-in subroutines
v Additional built-in functions:
– CS
– CDS
– ISMAIN
– LOWERCASE
– UPPERCASE
This release also provides all of the functional enhancements offered in VisualAge
PL/I V2R2, including the following:
v Initial UTF-16 support via the WIDECHAR attribute
There is currently no support yet for
– WIDECHAR characters in source files
About this book
xxv
About this book
–
–
–
–
v
v
v
v
v
W string constants
use of WIDECHAR expressions in stream I/O
implicit conversion to/from WIDECHAR in record I/O
implicit endianness flags in record I/O
If you create a WIDECHAR file, you should write the endianness flag
('fe_ff'wx) as the first two bytes of the file.
DESCRIPTORS and VALUE options supported in DEFAULT statements
PUT DATA enhancements
– POINTER, OFFSET and other non-computational variables supported
– Type-3 DO specifications allowed
– Subscripts allowed
DEFINE statement enhancements
– Unspecified structure definitions
– CAST and RESPEC type functions
Additional built-in functions:
– CHARVAL
– ISIGNED
– IUNSIGNED
– ONWCHAR
– ONWSOURCE
– WCHAR
– WCHARVAL
– WHIGH
– WIDECHAR
– WLOW
Preprocessor enhancements
– Support for arrays in preprocessor procedures
–
–
–
–
WHILE, UNTIL and LOOP keywords supported in %DO statements
%ITERATE statement supported
%LEAVE statement supported
%REPLACE statement supported
– %SELECT statement supported
– Additional built-in functions:
- COLLATE
- COMMENT
- COMPILEDATE
- COMPILETIME
- COPY
- COUNTER
- DIMENSION
- HBOUND
- INDEX
- LBOUND
- LENGTH
- MACCOL
- MACLMAR
- MACRMAR
- MAX
- MIN
- PARMSET
- QUOTE
- REPEAT
xxvi
Enterprise PL/I for z/OS Language Reference
About this book
-
SUBSTR
SYSPARM
SYSTEM
SYSVERSION
TRANSLATE
VERIFY
How to send your comments
Your feedback is important in helping us to provide accurate, high-quality
information. If you have comments about this document or any other PL/I
documentation, contact us in one of these ways:
v Use the Online Readers' Comment Form at
www.ibm.com/software/awdtools/rcf/
or send an e-mail to
comments@us.ibm.com
Be sure to include the name of the document, the publication number of the
document, the version of PL/I, and, if applicable, the specific location (for
example, page number) of the text that you are commenting on.
v Fill out the Readers' Comment Form at the back of this document, and return it
by mail or give it to an IBM representative. If the form has been removed,
address your comments to:
International Business Machines Corporation
Reader Comments
H150/090
555 Bailey Avenue
San Jose, CA 95141-1003
USA
v Fax your comments to this U.S. number: (800)426-7773.
When you send information to IBM, you grant IBM a nonexclusive right to use or
distribute the information in any way it believes appropriate without incurring any
obligation to you.
Accessibility
Accessibility features help users who have a disability, such as restricted mobility
or limited vision, to use information technology products successfully. The
accessibility features in z/OS provide accessibility for Enterprise PL/I.
The major accessibility features in z/OS are:
v Interfaces that are commonly used by screen readers and screen-magnifier
software
v Keyboard-only navigation
v Ability to customize display attributes such as color, contrast, and font size
Interface information
Assistive technology products work with the user interfaces that are found in
z/OS. For specific guidance information, see the documentation for the assistive
technology product that you use to access z/OS interfaces.
About this book
xxvii
Accessibility
Keyboard navigation
Users can access z/OS user interfaces by using TSO/E or ISPF. For information
about accessing TSO/E or ISPF interfaces, see the following publications:
v z/OS TSO/E Primer
v z/OS TSO/E Primer
v z/OS TSO/E Primer
These guides describe how to use TSO/E and ISPF, including the use of keyboard
shortcuts or function keys (PF keys). Each guide includes the default settings for
the PF keys and explains how to modify their functions.
Accessibility of this information
The English-language XHTML format of this information that will be provided in
the IBM System z® Enterprise Development Tools & Compilers Information Center
at publib.boulder.ibm.com/infocenter/pdthelp/index.jsp is accessible to visually
impaired individuals who use a screen reader.
To enable your screen reader to accurately read syntax diagrams, source code
examples, and text that contains the period or comma PICTURE symbols, you must
set the screen reader to speak all punctuation.
IBM and accessibility
See the IBM Human Ability and Accessibility Center at www.ibm.com/able for
more information about the commitment that IBM® has to accessibility.
xxviii
Enterprise PL/I for z/OS Language Reference
Chapter 1. Program elements
Single-byte character set . . .
Decimal digits . . . . . .
Binary digits . . . . . .
Hexadecimal digits . . . .
Special characters . . . . .
Composite symbols . . . .
Case sensitivity . . . . .
Statement elements for SBCS . .
Identifiers . . . . . . .
PL/I keywords . . . .
Programmer-defined names
Delimiters and operators . .
Blanks . . . . . . .
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
1
3
3
3
3
4
5
5
5
5
5
6
7
Comments . . . . . . . . . . .
Statements . . . . . . . . . . . . .
Simple statements . . . . . . . . .
Compound statements. . . . . . . .
Groups . . . . . . . . . . . . . .
Double-byte character set . . . . . . . .
DBCS identifiers . . . . . . . . . .
Single-byte identifiers in DBCS form . .
DBCS identifiers containing double-byte
characters . . . . . . . . . . .
Uses for double-byte character identifiers
Statement elements for DBCS . . . . .
DBCS continuation rules . . . . . . .
.
.
.
.
.
.
.
.
. 7
. 8
. 10
. 10
. 10
. 11
. 11
. 11
.
.
.
.
.
.
.
.
11
12
12
13
This chapter describes the basic elements that are used to write a PL/I program.
The elements include character sets, programmer-defined identifiers, keywords,
delimiters, and statements.
PL/I supports a single-byte character set (SBCS) and a double-byte character set
(DBCS).
The implementation limits for PL/I's language elements are listed in “Limits,” on
page 781.
Single-byte character set
A character set is an ordered set of unique representations called characters; for
example, the set of symbols in Morse code, or the letters of the Cyrillic alphabet
are character sets. PL/I supports all PC character sets. Character set 0640 is called
the invariant character set because a character from this set has the same code point
in all code pages. A code point is a one-byte code representing one of 256 potential
characters; a code page is an assignment of graphic characters and control function
meanings to all of the code points.
PL/I supports all code pages that conform to character set 0640; however, PL/I
assumes code page 0850 for all code points, except for those characters which are
specified by the programmer using the CURRENCY, NAMES, OR, or NOT
compiler options. For more information on these options, refer to the Programming
Guide.
Code page 0850 contains the English alphabet, ten decimal digits, special
characters, and other national language and control characters. Constants and
comments can contain any SBCS character value. PL/I elements (for example,
statements, keywords and delimiters) are limited to the characters described in the
following sections.
Alphabetic and extralingual characters
The default alphabet for PL/I is the English alphabet plus the extralingual
characters.
© Copyright IBM Corp. 1999, 2012
1
Alphabetic and extralingual characters
Alphabetic characters
There are 26 base alphabetic characters that comprise the English alphabet. They
are shown in Table 1 with the equivalent ASCII and EBCDIC values in hexadecimal
notation.
Table 1. Alphabetic equivalents
Character
EBCDIC
Uppercase Hex
Value
EBCDIC
Lowercase Hex
Value
ASCII
Uppercase Hex
Value
ASCII
Lowercase Hex
Value
A
C1
81
41
61
B
C2
82
42
62
C
C3
83
43
63
D
C4
84
44
64
E
C5
85
45
65
F
C6
86
46
66
G
C7
87
47
67
H
C8
88
48
68
I
C9
89
49
69
J
D1
91
4A
6A
K
D2
92
4B
6B
L
D3
93
4C
6C
M
D4
94
4D
6D
N
D5
95
4E
6E
O
D6
96
4F
6F
P
D7
97
50
70
Q
D8
98
51
71
R
D9
99
52
72
S
E2
A2
53
73
T
E3
A3
54
74
U
E4
A4
55
75
V
E5
A5
56
76
W
E6
A6
57
77
X
E7
A7
58
78
Y
E8
A8
59
79
Z
E9
A9
5A
7A
Extralingual characters
The default extralingual characters are the number sign (#), the at sign (@), and the
currency sign ($). The hexadecimal values for these characters vary across code
pages. You can use the NAMES compiler option to define your own extralingual
characters. For more information on defining extralingual characters, refer to the
Programming Guide.
Alphanumeric characters
An alphanumeric character is either an alphabetic or extralingual character, or a
digit.
2
Enterprise PL/I for z/OS Language Reference
Decimal digits
Decimal digits
PL/I recognizes the ten decimal digits, 0 through 9. They are also known simply as
digits and are used to write decimal constants and other representations and
values. The following table shows the digits and their hexadecimal values.
Table 2. Decimal digit equivalents
Character
EBCDIC Hex Value
ASCII Hex Value
0
F0
30
1
F1
31
2
F2
32
3
F3
33
4
F4
34
5
F5
35
6
F6
36
7
F7
37
8
F8
38
9
F9
39
Binary digits
PL/I recognizes the two binary digits, 0 and 1. They are also known as bits and
are used to write binary and bit constants.
Hexadecimal digits
PL/I recognizes the 16 hexadecimal digits, 0 through 9 and A through F. A through
F represent the decimal values 10 through 15, respectively. They are also known as
hex digits or just hex and are used to write constants in hexadecimal notation.
Special characters
Table 3 shows the special characters, their PL/I meanings, and their ASCII and
EBCDIC values in hexadecimal notation.
Table 3. Special character equivalents
Character
Meaning
Default EBCDIC Default ASCII
Hex Value
Hex Value
b
Blank
40
20
=
Equal sign or assignment symbol
7E
3D
+
Plus sign
4E
2B
-
Minus sign
60
2D
*
Asterisk or multiply symbol
5C
2A
/
Slash or divide symbol
61
2F
(
Left parenthesis
4D
28
)
Right parenthesis
5D
29
,
Comma
6B
2C
.
Point or period
4B
2E
'
Single quotation mark
7D
27
"
Double quotation mark
7F
22
Note 1
Chapter 1. Program elements
3
Special characters
Table 3. Special character equivalents (continued)
Character
Meaning
Default EBCDIC Default ASCII
Hex Value
Hex Value
%
Percent
6C
25
;
Semicolon
5E
3B
:
Colon
7A
3A
Not symbol, exclusive-or symbol
5F
5E
50
26
4F
7C
¬
Note 1
&
And symbol
Note 1
|
Or symbol
>
Greater than symbol
6E
3E
<
Less than symbol
4C
3C
_
Break character (underscore)
6D
5F
Note 1:
The or (|), the not (¬) and the quote (") symbols have variant code points. You can use the
compiler options OR, NOT and QUOTE to define alternate symbols to represent these
operators. For more information about these options, refer to the Programming Guide.
Composite symbols
You can combine special characters to create composite symbols. The following
table describes these symbols and their meanings. Composite symbols cannot
contain blanks.
Table 4. Composite symbol description
4
Composite Symbol
Meaning
{
Concatenation
**
Exponentiation
¬<
Not less than
¬>
Not greater than
¬= or <>1
Not equal to; Evaluate, exclusive-or and assign
<=
Less than or equal to
>=
Greater than or equal to
/*
Start of a comment
*/
End of a comment
–>
Locator (pointers and offsets)
=>
Locator (handles)
+=
Evaluate expression, add and assign
-=
Evaluate expression, subtract and assign
*=
Evaluate expression, multiply and assign
/=
Evaluate expression, divide and assign
|=
Evaluate expression, or and assign
&=
Evaluate expression, and, and assign
{=
Evaluate expression, concatenate and assign
**=
Evaluate expression, exponentiate and assign
Enterprise PL/I for z/OS Language Reference
Composite symbols
Table 4. Composite symbol description (continued)
Composite Symbol
Meaning
(:
Start of type function parameter list
:)
End of type function parameter list
1. You can use <> as an alternative to ¬=.
Case sensitivity
You can use a combination of lowercase and uppercase characters in a PL/I
program.
When used in keywords or identifiers, the lowercase characters are treated as the
corresponding uppercase characters. This is true even if you entered a lowercase
character as a DBCS character.
When used in a comment or in a character, mixed, or a graphic string constant,
lowercase characters remain lowercase.
Statement elements for SBCS
This section describes the elements that make up a PL/I program when using
SBCS.
A PL/I statement consists of identifiers, delimiters, operators, and constants.
Constants are described in Chapter 2, “Data elements,” on page 15.
Identifiers
An identifier is a series of characters that are not contained in a comment or a
constant. Except for P, PIC, and PICTURE, identifiers must be preceded and
followed by a delimiter. (P, PIC, and PICTURE identifiers can be followed by a
character string.) The first character of an identifier must be an alphabetic or
extralingual character. If the identifier names an INTERNAL symbol, it may also
use the break (_) character as its first character. Other characters, if any, can be
alphabetic, extralingual, digit, or the break (_) character. External user names must
not start with IBM, PLI, CEE, _IBM, _PLI, and _CEE.
Identifiers can be PL/I keywords or programmer-defined names. Because PL/I can
determine from the context if an identifier is a keyword, you can use any identifier
as a programmer-defined name. There are no reserved words in PL/I.
PL/I keywords
A keyword is an identifier that has a specific meaning in PL/I. Keywords can
specify such things as the action to be taken or the attributes of data. For example,
READ, DECIMAL, and ENDFILE are keywords. Some keywords can be
abbreviated. The keywords and their abbreviations are shown in uppercase letters.
Programmer-defined names
In a PL/I program, names are given to variables and program-control data. There
are also built-in names, condition names, and generic names. Any identifier can be
used as a name. A name can have only one meaning in a program block; the same
name cannot be used for both a file and a floating-point variable in the same block.
To improve readability, the break character (_) can be used in a name, such as
Gross_Pay.
Chapter 1. Program elements
5
Identifiers
Examples of names are:
A
Rate_of_pay
Record
Loop_3
Additional requirements for programmer-defined external names are given in
“INTERNAL and EXTERNAL attributes” on page 157.
An asterisk (*) can be used as an identifier name in situations where a name is
required but you do not otherwise refer to that identifier. For more information,
see the example in ENTRY attribute.
Delimiters and operators
Delimiters and operators are used to separate identifiers and constants. Table 5
shows delimiters and Table 6 shows operators.
Table 5. Delimiters
Name
Delimiter
Use
Comma
,
Separates elements of a list; precedes the BY NAME option
Period
.
Connects elements of a qualified name; decimal or binary
point
Semicolon
;
Terminates a statement
Equal sign
=
Indicates assignment or, in a conditional expression, equality
Colon
:
Connects prefixes to statements; connects lower-bound to
upper-bound in a dimension attribute; used in RANGE
specification of DEFAULT statement
Blank
b
Separates elements
Parentheses
( )
Enclose lists, expressions, iteration factors, and repetition
factors; enclose information associated with various
keywords
Locator
–>
=>
Denotes locator qualification (pointers and offsets)
Denotes locator qualification (handles)
Percent
%
Indicates %statements and %directives
Note: Omitting certain symbols can cause errors that are difficult to trace. Common errors
are unbalanced quotes, unmatched parentheses, unmatched comment delimiters, and
missing semicolons.
Table 6. Operators
Character(s)
Description
+
*
/
**
Addition or prefix plus
Subtraction or prefix minus
Multiplication
Division
Exponentiation
Operator type
Arithmetic
6
Enterprise PL/I for z/OS Language Reference
Delimiters and operators
Table 6. Operators (continued)
Character(s)
Description
Comparison
=
¬= or <>
<
¬<
>
¬>
<=
>=
Equal to
Not equal to
Less than
Not less than
Greater than
Not greater than
Less than or equal to
Greater than or equal to
Logical
¬
&
|
Not, Exclusive-or
And
Or
String
{
Concatenation
Operator type
The characters used for delimiters can be used in other contexts. For example, the
period is a delimiter when used in name qualification (for example,
Weather.Temperature), but is a decimal point in an arithmetic constant (for
example, 3.14).
Blanks
You can surround each operator or delimiter with blanks (b).
One or more blanks must separate identifiers and constants that are not separated
by some other delimiter. The only exception to this rule is that the identifiers P,
PIC and PICTURE can be followed by a character string without any intervening
blanks. Any number of blanks can appear wherever one blank is allowed.
Blanks cannot occur within identifiers, composite symbols, or constants (except in
character, mixed, widechar and graphic string constants).
Some examples are:
is
is
is
is
ab+bc
Table(10)
First,Second
AtoB
equivalent to
equivalent to
equivalent to
not equivalent to
Ab + Bc
TABLEb(b10bbb)
first,bsecond
AbtobB
Other cases that require or allow blanks are noted where those language features
are discussed.
Comments
Comments are allowed wherever blanks are allowed as delimiters. A comment is
treated as a blank and used as a delimiter. Comments are ignored and do not affect
the logic of a program. Use the following syntax when for comments.
/*
*/
text
/* Specifies the beginning of a comment.
Chapter 1. Program elements
7
Delimiters and operators
text
Specifies any sequences of characters except the */ composite symbol, which
would terminate the comment.
*/ Specifies the end of the comment.
A comment can be entered on one or more lines, for example:
A = /* This comment is on one line */ 21;
/* This comment spans
two lines
*/
In the following example, what appears to be a comment is actually a character
string constant because it is enclosed in quotes.
A = ’/* This is a constant, not a comment */’ ;
Comments may not be nested. However, the %DO SKIP: statement may be used as
a way of "commenting out" code that contains comments.
Statements
You use identifiers, delimiters, operators, and constants to construct PL/I
statements.
Although your source program consists of a series of records or lines, PL/I views
the program as a continuous stream of characters. There are few restrictions in the
format of PL/I statements, and programs can be written without considering
special coding rules or checking to see that each statement begins in a specific
column. A statement can begin in the next position after the previous statement, or
it can be separated by any number of blanks.
Some statements begin with a % symbol. These statements are either %directives
that direct preprocessor and compiler operations (controlling listings, including
program source text from a library, and so on) or are PL/I macro facility
%statements. A %directive must be on a line by itself.
To improve program readability and maintainability and to avoid unexpected
results caused by loss of trailing blanks in source lines:
v Do not split a language element across lines. If a string constant must be written
on multiple lines, use the concatenation operator ({).
v Do not write more than one statement on a line.
v Do not split %directives across lines.
The PL/I statements, macro facility %statements, and the %directives are
alphabetically listed in Chapter 8, “Statements and directives,” on page 195.
Syntax for a PL/I statement:
condition-prefix
8
Enterprise PL/I for z/OS Language Reference
label-prefix
statement
Statements
Syntax for a %directive:
%
statement
Syntax for a %statement:
% label-prefix
statement
Syntax for a macro statement:
label-prefix
statement
Every statement must be contained within some enclosing group or block. Macro
statements must be contained within some enclosing macro group or procedure.
condition-prefix
A condition prefix specifies the enabling or disabling of a PL/I condition (see
Chapter 15, “Condition handling,” on page 349).
label-prefix
A label prefix is one or more statement labels. It identifies a statement so that it
can be referred to at some other point in the program. Statement labels are
either label constants (discussed in “Label data and LABEL attribute” on page
44), entry constants (discussed in “Entry data” on page 113), or format
constants (discussed in “Format data and FORMAT attribute” on page 46).
Any statement, except DECLARE, DEFAULT, WHEN, OTHERWISE, and ON
statements, can have a label prefix. Use the following syntax for a label prefix.
identifier :
The syntax for individual statements throughout this book generally does not
show the condition prefix or the label prefix.
Chapter 1. Program elements
9
Statements
statement
A simple or a compound statement.
Simple statements
The types of simple statements are keyword, assignment, and null.
A keyword statement is a statement that begins with a keyword. This keyword
indicates the function of the statement. In the following example, READ and
DECLARE are keywords.
read file(In) into(Input);
%declare Text char;
/* keyword statement */
/* keyword %statement */
The assignment statement contains one or more identifiers on the left side of the
assignment symbol (=) and an expression on the right. It does not begin with a
keyword:
A = B + C;
%Size = 15;
/*
assignment statement
/* % assignment statement
*/
*/
The null statement consists of only a semicolon and is a nonoperational statement.
;
Label:;
% ;
/* null statement
*/
/* labeled null statement */
/* % null statement
*/
Compound statements
Compound statements are all keyword statements. Each begins with a keyword
which indicates the purpose of the statement. A compound statement contains one
or more simple or compound statements. There are four compound statements: IF,
ON, WHEN, and OTHERWISE. A compound statement is terminated by the
semicolon that also terminates the final statement of the compound statement.
The following are examples of compound statements:
on conversion
onchar() = ’0’;
if Text = ’stmt’ then
do;
select(Type);
when(’if’) call If_stmt;
when(’do’) call Do_stmt;
when(’’) /* do nothing */ ;
otherwise
call Other_stmt;
end;
call Print;
end;
end;
%if Type = ’AREA’ %then
%Size = Size + 16;
%else;
Groups
Statements can be contained within larger program units called groups. A group is
either a do-group or a select-group. A do-group is a sequence of statements
delimited by a DO statement and a corresponding END statement. A select-group
is a sequence of WHEN statements and an optional OTHERWISE statement
10
Enterprise PL/I for z/OS Language Reference
Groups
delimited by a SELECT statement and a corresponding END statement. The
delimiting statements are considered to be part of the group.
When a group is used in a compound statement, control either flows into the
group or bypasses it, effectively treating the group as if it were a single statement.
The flow of control within a group is discussed for do-groups under “DO
statement” on page 207 and for select-groups under “SELECT statement” on page
230.
Every group must be contained within some enclosing group or block. Groups can
contain none, one, or more statements, groups, or blocks.
Double-byte character set
Each character in the double-byte character set (DBCS) is stored in 2 bytes. When
the GRAPHIC compiler option is in effect, some source language elements can be
written using DBCS and SBCS characters. In particular, you can use DBCS
characters in the source program in following places:
v inside comments
v as part of statement labels and identifiers
v in G or M literals
However INCLUDE file names and the TITLE option of FETCH statements must
be in SBCS.
On the z/OS platform, each string of DBCS characters must be immediately
enclosed in shift codes, but shift codes are neither required nor accepted on the
other platforms supported by the compiler. In the examples that follow, these shift
codes will be included, but they must be omitted on all platforms other than z/OS.
DBCS identifiers
DBCS identifiers can be composed of single-byte characters in DBCS form,
double-byte characters, or a combination of both.
Single-byte identifiers in DBCS form
DBCS identifiers containing only single-byte characters must conform to the
normal PL/I naming conventions, including the first-character rule. A DBCS
identifier containing single-byte characters expressed as DBCS equivalents is a
synonym of the same identifier in SBCS.
Notes:
1. This book uses the symbol “.” (bold period) to represent the first byte
of a double-byte character that can also be represented as SBCS.
2. This book uses “kk” to represent a double-byte character.
3. This book uses < to represent a shift-out character ('0E'X).
4. This book uses > to represent a shift-in character ('0F'X).
Example:
<.I.B.M> = 3;
/* is the same as IBM=3; */
DBCS identifiers containing double-byte characters
The number of bytes used in a DBCS name cannot exceed the value specified as
the maximum length of a name specified in the compiler LIMITS option.
Chapter 1. Program elements
11
DBCS identifiers
SBCS characters expressed in DBCS form within a DBCS identifier are considered
to be SBCS, for example:
A<kk>B
A<kk.B>
<.Akk>B
/* are all A<kk>B
(SBCS-DBCS-SBCS) */
Uses for double-byte character identifiers
A DBCS identifier can be used wherever an SBCS identifier is allowed. When
DBCS identifiers are used for EXTERNAL names and %INCLUDE file names, you
must ensure that the identifiers are acceptable to the operating system, or are made
acceptable by one of the following:
v The EXTERNAL attribute with an environment-name is used.
v The TITLE option of the OPEN statement is used.
Statement elements for DBCS
This section provides supplemental information about writing PL/I language
elements using DBCS. Definitions of the language elements in this section and
general usage rules appear in corresponding sections in “Statement elements for
SBCS” on page 5.
The following is a list of the language elements that may be coded using DBCS, an
explanation of the rules, and examples of usage.
Identifiers
Use SBCS, DBCS or both.
dcl Eof
dcl <.E.o.f>
dcl
dcl
dcl
dcl
<kkkk>X
<kkkk.X>
<kkkk>x
<kkkk.x>
/* in SBCS, is the same as
/* this in DBCS.
*/
*/
/* these are all the same, where */
/* kk is a valid
*/
/* DBCS character
*/
/*
*/
Comments
Use SBCS, DBCS or both.
/* comment */
/* <.T.y.p.ekk> */
/* all SBCS
/* DBCS text */
*/
Comment delimiters must be specified in SBCS.
Mixed Character String Constants
Use SBCS, DBCS or both and are enclosed in SBCS or DBCS quotes.
If the string is enclosed in SBCS quotes, then it is not necessary to end the
string with an M suffix.
Any DBCS data inside the quotes is not converted to SBCS; it and any shift
codes are stored as is in the internal representation of the string.
’<.a.b.c>’M
’<.I.B.M.’.S>’M
’<.I.B.M>’’<.S>’M
’IBM<kk>’M
Graphic Constants
Use DBCS only and are enclosed in SBCS or DBCS quotes.
’<.a.b.c>’G
’<.I.B.M.’.S>’G
/* 6 byte graphic constant */
/* 10 byte graphic constant .I.B.M.’.S
*/
G literals can start and end with DBCS quotes, and in that case, the G itself
can also be specified in DBCS. So, the following are all equivalent
12
Enterprise PL/I for z/OS Language Reference
DBCS statement elements
’<.a.b.c>’G
<.’.a.b.c.’>G
<.’.a.b.c.’.G>
DBCS continuation rules
If a string literal or an identifier has a DBCS character that is separated from the
right margin by a single SBCS blank, then the blank is ignored and the statement
element is continued at the left margin of the next record.
Chapter 1. Program elements
13
14
Enterprise PL/I for z/OS Language Reference
Chapter 2. Data elements
Data items. . . . . . . . . . .
Variables . . . . . . . . . .
Constants . . . . . . . . . .
Using quotation marks . . . . .
Punctuating constants . . . . . .
Data types and attributes . . . . . .
Data attributes . . . . . . . .
Nondata attributes . . . . . . .
Computational data types and attributes
Coded arithmetic data and attributes .
BINARY and DECIMAL attributes .
FIXED and FLOAT attributes . .
PRECISION attribute . . . . .
REAL and COMPLEX attributes .
SIGNED and UNSIGNED attributes
Binary fixed-point data . . . .
Binary fixed-point constant . . .
XN (hex) binary fixed-point constant
XU (hex) binary fixed-point constant
Decimal fixed-point data . . . .
Decimal fixed-point constant . .
Binary floating-point data . . .
Binary floating-point constant . .
Decimal floating-point data . . .
Decimal floating-point constant. .
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
15
16
16
16
16
17
18
18
22
22
23
23
23
24
24
25
25
26
26
26
27
27
27
28
28
String data and attributes. . . . . . . .
BIT, CHARACTER, GRAPHIC and
WIDECHAR attributes . . . . . . .
VARYING, VARYINGZ, and NONVARYING
attributes . . . . . . . . . . . .
PICTURE attribute . . . . . . . . .
Character data . . . . . . . . . .
Character constant . . . . . . . . .
A (ASCII) character constant. . . . . .
E (EBCDIC) character constant . . . . .
X (hex) character constant . . . . . .
Bit data. . . . . . . . . . . . .
Bit constant . . . . . . . . . . .
B4 (hex) bit constant . . . . . . . .
B3 (octal) bit constant . . . . . . . .
Graphic data . . . . . . . . . . .
Graphic constant . . . . . . . . .
GX (hex) graphic constant . . . . . .
Mixed character data . . . . . . . .
M (Mixed) character constant . . . . .
Widechar data . . . . . . . . . .
WX (hex) widechar constant . . . . . .
Numeric character data . . . . . . .
Date attribute. . . . . . . . . . .
Named constants . . . . . . . . .
. 29
. 29
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
30
31
32
32
33
33
33
34
34
34
35
35
35
36
36
36
37
37
38
39
42
This chapter introduces the kinds of data you can use in PL/I programs and the
attributes you use to describe them. The discussion covers:
A review of data items
A review of variables and constants
The types of data that are available and the attributes that define them
For information on how to declare data, refer to Chapter 7, “Data declarations,” on
page 151.
Data items
A data item is either the value of a variable or a constant. (These terms are not
exactly the same as in general mathematical usage. They are discussed further in
the next section.) Data items can be single items, called scalars, or they can be a
collection of items called data aggregates.
Data aggregates are groups of data items that can be referred to either collectively
or individually. The kinds of data aggregates are arrays, structures, and unions. You
can use any type of computational or program-control data to form a data
aggregate.
Arrays are discussed in “Arrays” on page 173, structures in “Structures” on page
177, unions in “Unions” on page 178, and arrays of structures and unions starting
in “Combinations of arrays, structures, and unions” on page 184.
© Copyright IBM Corp. 1999, 2012
15
Variables
Variables
A variable has a value or values that might change during execution of a program.
A variable is introduced by a declaration, which declares the name and certain
attributes of the variable. However, a variable having the NONASSIGNABLE
attribute is assumed not to change during execution. (Refer to “ASSIGNABLE and
NONASSIGNABLE attributes” on page 258 for more information.) A variable
reference is one of the following:
v A declared variable name
v A reference derived from a declared name through one or more of the following:
– Pointer qualification
– Structure qualification
– Subscripting
(See Chapter 3, “Expressions and references,” on page 49.)
Constants
A constant has a value that cannot change. Constants for computational data are
referred to by stating the value of the constant or naming the constant in a
DECLARE statement. For more information on declaring named constants, see
“Named constants” on page 42.
Constants for program-control data are referred to by name.
Using quotation marks
String constants, hexadecimal constants, and the picture-specification are enclosed
in either single or double quotation marks.
The following rules apply to quotation marks within a string:
v If the included quotation marks are the same type as those used to enclose the
string, you must enter two quotation marks (that is, '' or "") for each occurrence
to be included.
v If the included quotation marks are the type not used to enclose the string, enter
only one quotation mark for each instance to be included. The single occurrence
is treated as data.
Examples:
’Shakespeare’’s "Hamlet"’ is identical to
"Shakespeare’s ""Hamlet"""
PICTURE "99V9" is identical to
PICTURE ’99V9’
Note: The syntax diagrams in this book show single quotation marks. Double
quotation marks can be substituted unless otherwise noted.
Punctuating constants
To improve readability, arithmetic, bit, and hexadecimal constants can use the
break character ( _ ).
’1100_1010’B
1100_1010B
’C_A’B4
’C_A’XN
16_777_216
16
Enterprise PL/I for z/OS Language Reference
is
is
is
is
is
the
the
the
the
the
same
same
same
same
same
as
as
as
as
as
’11001010’B
11001010B
’ca’b4
’ca’XN
16777216
Punctuating constants
Data types and attributes
Data used in a PL/I program can be classified as either computational data or
program-control data:
Computational data
Represents values that are used in computations to produce a desired result.
Arithmetic and string data constitute computational data.
Arithmetic data is either coded arithmetic data or numeric picture data.
Coded arithmetic data items are rational numbers. They have the data
attributes of base (BINARY or DECIMAL), scale (FLOAT or FIXED), precision
(significant digits and decimal-point placement), and mode (REAL or
COMPLEX).
Numeric picture data is numeric data that is held in character form and is
discussed under “Numeric character data” on page 38.
A string is a sequence of contiguous characters, bits, widechars or graphics that
are treated as a single data item.
Program-control data
Represents values that are used to control execution of your program. It
consists of the following data types—area, entry, label, file, format, pointer, and
offset.
For example:
Area = (Radius**2) * 3.1416;
Area and Radius are coded arithmetic variables of computational data. The
numbers 2 and 3.1416 are coded arithmetic constants of computational data.
If the number 3.1416 is used in more than one place in the program, or if it
requires specific data or precision attributes, you should declare it as a named
constant. Thus, the above statement can be coded as:
dcl Pi FIXED DECIMAL (5,4) VALUE(3.1416);
area = (radius**2) * Pi;
Constants for program-control data have a value that is determined by the
compiler. In the following example, the name loop represents a label constant of
program-control data. The value of loop is the address of the statement A=2*B;.
loop:
A=2*B;
C=B+6;
To work with a data item, PL/I needs to know the type of data and how to
process it. Attributes provide this information. The kinds of attributes are data
attributes and nondata attributes.
Chapter 2. Data elements
17
Data attributes
Data attributes
Describe computational data, program-control data, and program characteristics.
AREA
BINARY
BIT
CHARACTER
COMPLEX
DECIMAL
DIMENSION
ENTRY
FILE
FIXED
FLOAT
FORMAT
GRAPHIC
HANDLE
LABEL
NONVARYING
OFFSET
ORDINAL
PICTURE
POINTER
PRECISION
REAL
RETURNS
SIGNED
STRUCTURE
TASK
TYPE
UNSIGNED
UNION
VARYING
VARYINGZ
WIDECHAR
Nondata attributes
Describe nondata elements (for example, built-in functions) or provide additional
description for elements that have other data attributes.
ABNORMAL
ALIGNED
ASSIGNABLE
AUTOMATIC
BASED
BIGENDIAN
BUFFERED
BUILTIN
BYADDR
BYVALUE
CONDITION
CONNECTED
CONTROLLED
DEFINED
DIMACROSS
DIRECT
ENVIRONMENT
EXCLUSIVE
EXTERNAL
GENERIC
HEXADEC
IEEE
INITIAL
INONLY
INOUT
INPUT
INTERMAL
KEYED
LIKE
LIST
LITTLEENDIAN
NONASSIGNABLE
NONCONNECTED
NORMAL
OPTIONAL
OPTIONS
OUTONLY
OUTPUT
PARAMETER
POSITION
PRINT
RECORD
SEQUENTIAL
STATIC
STREAM
UNALIGNED
UNBUFFERED
UPDATE
VALUE
VARIABLE
XMLATTR
XMLOMIT
For example, the keyword CHARACTER is a data attribute for the string type of
computational data. The keyword FILE is a data attribute for the file type of
program-control data. The INTERNAL scope attribute specifies that the data item
is known only within its declaring block.
The details on using keywords and expressions to specify the attributes are in
Chapter 7, “Data declarations,” on page 151. Briefly, you specify attributes:
v Explicitly, using a DECLARE statement
v Contextually, letting PL/I determine them
v By using programmer-defined or language-specified defaults
Table 7 on page 19 and Table 8 on page 21 help you correlate PL/I's variety of
attributes with its variety of computational and program-control data types. The
tables show that the constants and the named constants can only have the
indicated data and scope attributes (Table 7 on page 19). Variables can specify
additional attributes (Table 8 on page 21).
In the example,
Area = (Radius**2)*3.1416;
the constant 3.1416 is given the following attributes:
v DECIMAL. It is given, because the constant is not explicitly a binary constant.
v FIXED. It is given, because the constant is a fixed-point number.
v PRECISION(5,4) (5 significant digits with 4 to the right of the decimal point)
v REAL. It is given, because the constant does not have an imaginary part.
18
Enterprise PL/I for z/OS Language Reference
Nondata attributes
v INTERNAL and ALIGNED
(See the “Coded arithmetic” row, and “Data Attributes” and “Scope Attributes”
columns of Table 7.)
The constant 1.0 (a decimal fixed-point constant) is different from the constants 1
(another decimal fixed-point constant), '1'B (a bit constant), '1' (a character
constant), 1B (binary fixed-point constant), or 1E0 (a decimal floating-point
constant).
In the following example, the variable Pi has the programmer-defined data
attributes of FIXED and DECIMAL with a PRECISION of five digits, four to the
right of the decimal point:
declare Pi fixed decimal(5,4) initial(3.1416);
Because this DECLARE statement contains no other attributes for Pi, PL/I applies
the defaults for the remaining attributes:
v REAL from the Data Attributes column
v ALIGNED from the Alignment Attributes column
v INTERNAL from the Scope Attributes column
v AUTOMATIC from the Storage Attributes column
v SIGNED from the Data Attributes column
(See the coded arithmetic row of Table 8 on page 21.)
Table 7. Classification of attributes by constant types
Data Attributes
Scope Attributes
Notes 1 and 2
Notes 1 and 2
Coded
arithmetic
REAL | imaginary
FLOAT | FIXED
BINARY | DECIMAL
PRECISION
SIGNED
internal
Named coded
arithmetic
REAL | COMPLEX
FLOAT | FIXED
BINARY | DECIMAL
PRECISION
VALUE
SIGNED | UNSIGNED
internal
String
BIT | CHARACTER |
GRAPHIC | WIDECHAR
(length)
internal
Named string
BIT | CHARACTER |
GRAPHIC | WIDECHAR
[(length)]
NONVARYING
VALUE
internal
Named locator
POINTER | OFFSET | HANDLE
VALUE
internal
Named picture
PICTURE
REAL | COMPLEX
VALUE
internal
Constant Type
Chapter 2. Data elements
19
Nondata attributes
Table 7. Classification of attributes by constant types (continued)
Constant Type
FileNote
3
EntryNote
Format
Label
5
Note 5
Note 5
Data Attributes
Scope Attributes
Notes 1 and 2
Notes 1 and 2
FILE ENVIRONMENT
STREAM | RECORD
INPUT | OUTPUT | UPDATE
SEQUENTIAL | DIRECT
BUFFERED | UNBUFFEREDNote
KEYED
PRINT
INTERNAL | EXTERNAL
4
ENTRY [RETURNS]
INTERNAL | EXTERNAL
FORMAT
internal
LABEL
internal
Notes:
1. Attributes in this table that appear in uppercase can be explicitly declared. Attributes that are in lowercase are
implicitly given to the data type.
2. Defaults for data attributes are underlined. Because the data attributes for literal constants are contextual, defaults
are not applicable. Named constants and file constants have selectable attributes, so defaults are shown.
3. File Attributes are described in Chapter 10, “Input and output,” on page 275.
4. BUFFERED is the default for SEQUENTIAL files. UNBUFFERED is the default for DIRECT files.
5. Format and label constants, and INTERNAL entry constants cannot be declared in a DECLARE statement.
20
Enterprise PL/I for z/OS Language Reference
Nondata attributes
Table 8. Classification of attributes by variable types
Variable
Type
Data Attributes
Alignment
Attributes
Scope
Attributes
Storage
Attributes
Area
AREA(size)
ALIGNED
Coded
arithmetic
REAL | COMPLEX
FLOAT | FIXED
BINARY | DECIMAL
PRECISION
[SIGNED |
UNSIGNED]
ALIGNED |
UNALIGNED
INTERNAL |
EXTERNAL
AUTOMATIC |
STATIC |
BASED |
CONTROLLED
Note 1
Entry
ENTRY [RETURNS]
[LIMITED]
File
FILE
Format
FORMAT
Label
LABEL
Locator
POINTER | HANDLE |
{OFFSET
[(area-variable)]}
Ordinal
ORDINAL
Picture
PICTURE
REAL | COMPLEX
String
BIT | CHARACTER |
GRAPHIC | WIDECHAR
[(length)]
[ VARYING |
VARYINGZ |
NONVARYING]
Task
TASK
(INTERNAL is
mandatory for
AUTOMATIC
BASED
DEFINED
PARAMETER)
(AUTOMATIC
is the
default for
INTERNAL;
STATIC is
the default
for
EXTERNAL)
Defined
variable:
DEFINED
[POSITION]
ALIGNED |
UNALIGNED
Parameter:
PARAMETER
[CONNECTED |
NONCONNECTED]
[CONTROLLED]
[INITIAL
[CALL]]
ALIGNED |
UNALIGNED
[VARIABLE]
[NORMAL |
ABNORMAL]
ASSIGNABLE |
NONASSIGNABLE
Arrays: DIMENSION can be added to the declaration of any variable. Refer to “Arrays” on page 173 for more
information.
Structures and unions:
v For a major structure or union: scope, storage (except INITIAL), alignment, STRUCTURE or UNION, and the LIKE
attributes can be specified.
v For a member that is a structure or a union: alignment, STRUCTURE or UNION, and the LIKE attributes can be
specified.
v Members always have the INTERNAL scope attribute.
Refer to “Structures” on page 177 and “Unions” on page 178 for more information.
Notes:
1. Undeclared names, or names declared without a data type, default to coded arithmetic variables. Default
attributes are described in “Defaults for attributes” on page 168. Defaults shown are IBM defaults. ANS defaults
are FIXED and BINARY rather than FLOAT and DECIMAL.
2. POSITION can be used only with string overlay defining.
Chapter 2. Data elements
21
Computational data
Computational data types and attributes
This section describes the data types classified as computational data and the
attributes associated with them.
Coded arithmetic data and attributes
Refer to “Data types and attributes” on page 17 for general information about
coded arithmetic data.
Syntax for coded arithmetic data is shown in the following diagram:
float sequence
REAL
fixed sequence
COMPLEX
precision specification
precision specification
float sequence:
FLOAT
precision specification
DECIMAL
precision specification
BINARY
precision specification
fixed sequence:
FIXED
precision specification
DECIMAL
precision specification
SIGNED
BINARY
precision specification
UNSIGNED
precision specification:
PRECISION
float precision
fixed precision
float precision:
(number-of-digits)
fixed precision:
(number-of-digits
)
,scaling-factor
22
Enterprise PL/I for z/OS Language Reference
Coded arithmetic data and attributes
Table 9. Abbreviations for coded arithmetic data attributes
Attribute
Abbreviation
BINARY
COMPLEX
DECIMAL
PRECISION
BIN
CPLX
DEC
PREC
BINARY and DECIMAL attributes
The base of a coded arithmetic data item is either decimal or binary. DECIMAL is
the default.
FIXED and FLOAT attributes
The scale of a coded arithmetic data item is either fixed-point or floating-point.
A fixed-point data item is a rational number in which the position of the decimal
or binary point is specified, either by its appearance in a constant or by a scaling
factor declared for a variable.
Floating-point data items are rational numbers in the form of a fractional part and
an exponent part.
PRECISION attribute
The precision of a coded arithmetic data item includes the number of digits and the
scaling factor. (The scaling factor is used only for fixed-point items).
number of digits
An integer that specifies how many digits the value can have. For fixed-point
items, the integer is the number of significant digits. For floating-point items,
the integer is the number of significant digits to be maintained excluding the
decimal point (independent of its position).
scaling factor
An optionally-signed integer that specifies the assumed position of the decimal
or binary point, relative to the rightmost digit of the number. If no scaling
factor is specified, the default is 0.
The precision attribute specification is often represented as (p,q), where p
represents the number of digits and q represents the scaling factor.
A negative scaling factor (-q) specifies an integer, with the point assumed to be
located q places to the right of the rightmost actual digit. A positive scaling factor
(q) that is larger than the number of digits specifies a fraction, with the point
assumed to be located q places to the left of the rightmost actual digit. In either
case, intervening zeros are assumed, but they are not stored; only the specified
number of digits is actually stored.
If PRECISION is omitted, the precision attribute must follow, with no intervening
attribute specifications, the scale (FIXED or FLOAT), base (DECIMAL or BINARY),
or mode (REAL or COMPLEX) attributes at the same factoring level.
If included, PRECISION can appear anywhere in the declaration.
Integer value means a fixed-point value with a scaling factor of zero.
Chapter 2. Data elements
23
REAL and COMPLEX
REAL and COMPLEX attributes
The mode of an arithmetic data item (coded arithmetic or numeric character) is
either real or complex.
A real data item is a number that expresses a real value.
A complex data item consists of two parts—a real part and an imaginary part. For
a variable representing complex data items, the base, scale, and precision of the
two parts are identical.
Arithmetic variables default to REAL.
An imaginary constant is written as a real constant of any type immediately
followed by the letter I. Examples are:
27I
3.968E10I
11011.01BI
Each of these has a real part of zero. A complex value with a nonzero real part is
represented by an expression with the following syntax:
real_constant
+
-
+
-
imaginary_constant
For example, 38+27I.
Given two complex numbers, y and z:
y = complex(A,B);
z = complex(C,D);
x=y/z is calculated by:
real(x) = (A*C + B*D)/(C**2 + D**2);
imag(x) = (B*C - A*D)/(C**2 + D**2);
x=y*z is calculated as follows:
real(x) = A*C - B*D;
imag(x) = B*C + A*D;
Computational conditions can be raised during these calculations.
SIGNED and UNSIGNED attributes
The SIGNED and UNSIGNED attributes can be used only with FIXED BINARY
variables and ORDINAL variables. SIGNED indicates that the variable can assume
negative values. UNSIGNED indicates that the variable can assume only
nonnegative values.
UNSIGNED has the following effects on the semantics of fixed-point operations:
v The result of IAND, IEOR, INOT and IOR is UNSIGNED if all the operands are
UNSIGNED.
v The result of ISLL and ISRL is UNSIGNED if the first operand is UNSIGNED.
v The result of REAL or IMAG is UNSIGNED if its operand is UNSIGNED.
24
Enterprise PL/I for z/OS Language Reference
SIGNED and UNSIGNED attributes
If you are using the RULES(ANS) compiler option, UNSIGNED has the following
effect on the semantics of fixed- point operations:
v The result of an add, multiply, or divide operation is UNSIGNED if both
operands are UNSIGNED.
v The result of MAX or MIN is UNSIGNED if all operands are UNSIGNED
v The result of REM or MOD is UNSIGNED if all operands are UNSIGNED
The SIGNED and UNSIGNED attributes affect storage requirements, as shown in
Table 10 and Table 11.
Table 10. FIXED BINARY SIGNED data storage requirements
This precision:
Occupies this amount of storage (bytes):
precision <= 7
7 < precision <= 15
15 < precision <= 31
31 < precision <= 63
1
2
4
8
Table 11. FIXED BINARY UNSIGNED data storage requirements
This precision:
Occupies this amount of storage (bytes):
precision <= 8
8 < precision <= 16
16 < precision <= 32
32 < precision <= 64
1
2
4
8
Binary fixed-point data
The data attributes for declaring binary fixed-point variables are BINARY and
FIXED. For example:
declare Factor binary fixed (20,2);
Factor is declared as a variable that can represent binary fixed-point data of 20
data bits, two of which are to the right of the binary point.
Refer to “SIGNED and UNSIGNED attributes” on page 24 for information on how
much storage signed and unsigned fixed-binary data occupy.
The declared number of data bits is in the low-order positions, but the extra
high-order bits participate in any operation performed upon the data item. Any
arithmetic overflow into such extra high-order bit positions can be detected only if
the SIZE condition is enabled.
Binary fixed-point constant
A binary fixed-point constant consists of one or more bits with an optional binary
point, followed immediately by the letter B. Binary fixed-point constants have a
precision (p,q), where p is the total number of data bits in the constant, and q is the
number of bits to the right of the binary point, for example:
Constant
1011_0B
1111_1B
101B
1011.111B
Precision
(5,0)
(5,0)
(3,0)
(7,3)
Chapter 2. Data elements
25
XN (hex) binary constant
XN (hex) binary fixed-point constant
The XN constant describes a SIGNED REAL FIXED BINARY constant in
hexadecimal notation. If the constant has 8 or fewer digits, it has a precision of 31;
otherwise, it has a precision of 63.
' hex-digit
'XN
Consider the following examples:
’100’XN
’8000’XN
’FFFF’XN
"ffff_ffff"XN
/* same as ’00000100’XN with value 256
/* same as ’00008000’XN with value 32,768
/* same as ’0000FFFF’XN with value 65,535
/* is the value -1
*/
*/
*/
*/
The hexadecimal value for the XN constant is the value specified padded on the
left with hex zeros if necessary.
XU (hex) binary fixed-point constant
The XU constant describes an UNSIGNED REAL FIXED BINARY constant in
hexadecimal notation. If the constant has 8 or fewer digits, it has a precision of 32;
otherwise, it has a precision of 64.
' hex-digit
'XU
Consider the following examples:
’100’XU
’8000’XU
’FFFF’XU
"ffff_ffff"XU
/* same as ’00000100’XU with value 256
/* same as ’00008000’XU with value 32,768
/* same as ’0000FFFF’XU with value 65,535
/* is the value 2**32-1
*/
*/
*/
*/
The hexadecimal value for the XU constant is the value specified padded on the
left with hex zeros if necessary.
Decimal fixed-point data
The data attributes for declaring decimal fixed-point variables are DECIMAL and
FIXED. For example:
declare A fixed decimal (5,4);
specifies that A represents decimal fixed-point data of 5 digits, 4 of which are to the
right of the decimal point.
These two examples:
declare B fixed (7,0) decimal;
declare B fixed decimal(7);
both specify that B represents integers of 7 digits.
26
Enterprise PL/I for z/OS Language Reference
Decimal fixed-point data
This example
declare C fixed (7,-2) decimal;
specifies that C has a scaling factor of -2. This means that C holds 7 digits that
range from -9999999*100 to 9999999*100, in increments of 100.
This example
declare D decimal fixed real(3,2);
specifies that D represents fixed-point data of 3 digits, 2 of which are fractional.
Decimal fixed-point data is stored two digits per byte, with a sign indication in the
rightmost 4 bits of the rightmost byte. Consequently, a decimal fixed-point data
item is always stored as an odd number of digits, even though the declaration of
the variable can specify the number of digits, p, as an even number.
When the declaration specifies an even number of digits, the extra digit place is in
the high-order position, and it participates in any operation performed upon the
data item, such as in a comparison operation. If the extra high-order digit place is
non-zero, the use of the data in arithmetic operation or assignment may produce
an exception. Any arithmetic overflow or assignment into an extra high-order digit
place can be detected only if the SIZE condition is enabled.
Decimal fixed-point constant
A decimal fixed-point constant consists of one or more decimal digits with an
optional decimal point. Decimal fixed-point constants have a precision (p,q), where
p is the total number of digits in the constant and q is the number of digits
specified to the right of the decimal point. Examples are:
Constant
3.1416
455.3
732
1_200_300
003
5280
.0012
Precision
(5,4)
(4,1)
(3,0)
(7,0)
(3,0)
(4,0)
(4,4)
Binary floating-point data
The data attributes for declaring binary floating-point variables are BINARY and
FLOAT. For example:
declare S binary float (16);
S represents binary floating-point data with a precision of 16 binary digits.
The exponent cannot exceed five decimal digits. If the declared precision is less
than or equal to (21), short floating-point form is used. If the declared precision is
greater than (21) and less than or equal to (53), long floating-point form is used. If
the declared precision is greater than (53), extended floating-point form is used.
Binary floating-point constant
A binary floating-point constant is a mantissa followed by an exponent and the
letter B. The mantissa is a binary fixed-point constant. The exponent is the letter E,
S, D, or Q followed by an optionally-signed decimal integer (meaning 2 to the
power of this integer). Constants using E have a precision (p) where p is the
Chapter 2. Data elements
27
Binary floating-point constant
number of binary digits of the mantissa. Constants using S, D, and Q always have
maximum single, double, and extended precisions, respectively. Examples are:
Constant
101101E5B
101.101E2B
11101E-28B
11.01E+42B
1S0b
1D0b
1Q0b
1Q0b
1Q0b
Precision
(6)
(6)
(5)
(4)
(21)
(53)
(64) (Windows)
(106) (AIX)
(109) (z/OS)
Decimal floating-point data
The data attributes for declaring decimal floating-point variables are DECIMAL
and FLOAT. Consider this example:
declare Light_years decimal float(5);
The value for Light_years represents decimal floating-point data of 5 decimal
digits.
For IEEE decimal floating-point data,
v If the declared precision is less than or equal to 7, short floating-point form is
used.
v If the declared precision is greater than 7 and less than or equal to 16, long
floating-point form is used.
v If the declared precision is greater than 16, extended floating-point form is used.
For all other decimal floating-point data,
v If the declared precision is less than or equal to 6, short floating-point form is
used.
v If the declared precision is greater than 6 and less than or equal to 16, long
floating-point form is used.
v If the declared precision is greater than 16, extended floating-point form is used.
Decimal floating-point constant
A decimal floating-point constant is a mantissa followed by an exponent. The
mantissa is a decimal fixed-point constant. The exponent is the letter E, S, D, or Q
followed by an optionally-signed decimal integer of four or less digits (meaning 10
to the power of this integer). Constants using E have a precision (p) where p is the
number of digits of the mantissa. Constants using S, D, and Q always represent
single, double, and extended precision respectively. Examples are:
Constant
15E-23
15E23
4E-3
1.96E+07
438E0
3_141_593E-6
.003_141_593E3
1s0
1d0
28
Enterprise PL/I for z/OS Language Reference
Precision
(2)
(2)
(1)
(3)
(3)
(7)
(9)
(6)
(16)
Decimal floating-point constant
Constant
1q0
1q0
1q0
Precision
(18) (Windows)
(32) (AIX)
(33) (z/OS)
The last five examples represent the same value (although with different
precisions).
For IEEE Decimal Floating Point (DFP), decimal floating-point literals, when
converted to "right-units-view", i.e. when the exponent has been adjusted, if
needed, so that no non-zero digits follow the decimal point (for example, as would
be done when viewing 3.1415E0 as 31415E-4), must have an exponent within the
range of the normal numbers for the precision given by the literal. These bounds
are given by the value of MINEXP-1 and MAXEXP-PLACES. In particular, the
following must hold:
v For short float, -95 <= exponent <= 90
v For long float, -383 <= exponent <= 369
v For extended float, -6143 <= exponent <= 6111
So, for IEEE Decimal Floating Point (DFP), the largest positive short decimal
floating-point literal is 9999999E90 (or .9999999E97), and the smallest postive
non-zero short decimal floating-point literal is 1E-95.
Rather than trying to specify the largest positive floating point value as a literal,
you should use the HUGE built-in function for this purpose. Similarly, to specify
the smallest non-zero positive value, you should use the TINY built-in function.
String data and attributes
Refer to “Data types and attributes” on page 17 for general information about
strings.
BIT, CHARACTER, GRAPHIC and WIDECHAR attributes
The BIT attribute specifies a bit variable.
The CHARACTER attribute specifies a character variable. Character strings can
also be declared using the PICTURE attribute.
The WIDECHAR attribute specifies a widechar variable which will hold UTF-16
data.
The GRAPHIC attribute specifies a graphic variable.
The syntax for the BIT, CHARACTER, GRAPHIC and WIDECHAR attributes is:
NONVARYING
BIT
CHARACTER
GRAPHIC
WIDECHAR
(length
)
REFER(variable)
VARYING
(*)
VARYINGZ
Chapter 2. Data elements
29
BIT, CHARACTER, GRAPHIC and WIDECHAR
Table 12. Abbreviations for string data attributes
Attribute
Abbreviation
CHARACTER
GRAPHIC
WIDECHAR
NONVARYING
VARYING
VARYINGZ
CHAR
G
WCHAR
NONVAR
VAR
VARZ
length
Specifies the length of a NONVARYING string or the maximum length of a
VARYING or VARYINGZ string. The length is in bits, characters, widechars or
graphics (DBCS characters), as appropriate.
You can specify the length as an expression or as an asterisk. If the length is
not specified, the default is 1. For named constants, length is determined from
the length of the value expression.
For a parameter, an expression is valid only if it is CONTROLLED. An asterisk
specification for a parameter indicates that the length is taken from the
argument that is passed.
If the length specification is an expression, it is evaluated and converted to a
FIXED BINARY(31,0) value, which must be nonnegative, when storage is
allocated for the variable.
For STATIC data, length must be a restricted expression.
For information about specifying the length of the BASED data, see “Extent
specifications in BASED declarations” on page 243.
REFER
See “REFER option (self-defining data)” on page 251 for the description of the
REFER option.
The statement below declares User as a variable that can represent character data
with a length of 15:
declare User character (15);
The following example shows the declaration of a bit variable:
declare Symptoms bit (64);
VARYING, VARYINGZ, and NONVARYING attributes
The VARYING and VARYINGZ attributes specify that a variable can have a length
varying from 0 to the declared maximum length. NONVARYING specifies that a
variable always has a length equal to the declared length.
The storage allocated for VARYING strings is 2 bytes longer than the declared
length. The leftmost 2 bytes hold the string's current length.
The storage allocated for a VARYINGZ character string is 1 byte longer than the
declared length. The current length of the string is equal to the number of bytes
before the first ’00’x in the storage allocated to it.
The storage allocated for a VARYINGZ GRAPHIC string is 2 bytes longer than the
declared length. The current length of the string is equal to half the number of
bytes before the first ’0000’gx in the storage allocated to it.
30
Enterprise PL/I for z/OS Language Reference
VARYING, VARYINGZ, NONVARYING attributes
The storage allocated for a VARYINGZ WIDECHAR string is 2 bytes longer than
the declared length. The current length of the string is equal to half the number of
bytes before the first ’0000’wx in the storage allocated to it.
The VARYINGZ attribute is not allowed with BIT strings.
In the following DECLARE statements, both User and Zuser represent
varying-length character data with a maximum length of 15. However, unlike User,
Zuser is null-terminated. The storage allocated is 17 bytes for User and 16 bytes for
Zuser.
declare User character (15) varying;
declare Zuser character (15) varyingz;
The length for User and Zuser at any time is the length of the data item assigned
to it at that time. You can determine the declared and the current length by using
the MAXLENGTH and LENGTH built-in functions, respectively.
The null terminator held in a VARYINGZ string is not used in comparisons or
assignments, other than to determine the length of the string. Consequently,
although the strings in the following declarations have the same internal hex
representation, they do not compare as being equal:
declare A char(4) nonvarying init( (’abc’ { ’00’x) );
declare B char(3) varyingz
init( ’abc’ );
To the contrary, Z and C in this example do compare as equal:
dcl Z char(3) nonvarying init(’abc’);
dcl C char(3) varyingz init(’abc’);
The VARYING and VARYINGZ strings can be passed and received as parameters
with * length. They can be passed without a descriptor if they have the
NONASSIGNABLE attribute.
PICTURE attribute
The PICTURE attribute specifies the properties of a character data item by
associating a picture character with each position of the data item. A picture
character specifies a category of characters that can occupy that position.
PICTURE ' picture-specification '
Abbreviation PIC
picture-specification
Describes either a character data item or a numeric character data item. Refer
to “Picture characters for character data” on page 334 or “Picture characters for
numeric character data” on page 335 for the valid characters.
A numeric picture specification specifies arithmetic attributes of numeric character
data in much the same way that they are specified by the appearance of a constant.
Numeric character data has an arithmetic value but is stored in character form.
Numeric character data is converted to coded arithmetic before arithmetic
operations are performed.
Chapter 2. Data elements
31
PICTURE
The base of a numeric character data item is decimal. Its scale is either fixed-point
or floating-point (the K or E picture character denotes a floating-point scale). The
precision of a numeric character data item is the number of significant digits
(excluding the exponent in the case of floating-point). Significant digits are
specified by the picture characters for digit positions and conditional digit
positions. The scaling factor of a numeric character data item is derived from the V
or the F picture character or the combination of V and F.
Only decimal data can be represented by picture characters. Complex data can be
declared by specifying the COMPLEX attribute along with a single picture
specification that describes either a fixed-point or a floating-point data item.
For more information on numeric character data, see “Numeric character data” on
page 38.
Character data
Data with the CHARACTER attribute can contain any of the 256 characters
supported by the character set. Data with the PICTURE attribute must have
characters that match the picture-specification characters. Each character occupies 1
byte of storage.
Character constant
A character constant is a contiguous sequence of characters enclosed in single or
double quotation marks.
Quotation marks included in the constant follow the rules listed in “Using
quotation marks” on page 16. The length of a character constant is the number of
characters between the enclosing quotation marks counting any doubled quotation
marks as a single character.
A null character constant is written as two quotation marks with no intervening
blank. The syntax for a character constant is:
'
'
character
Examples of character constants are:
Constant
’Shakespeare’’s "Hamlet"’
"Shakespeare’s ""Hamlet"""
"Page 5"
’/* This is a comment */’
’’
(2)’Walla ’
Length
22
22
6
27
0
12
In the last example, the number in parentheses is a string repetition factor, which
indicates repetition of the characters that follow. This example is equivalent to the
constant "Walla Walla ". The string repetition factor must be a constant and
enclosed in parentheses.
32
Enterprise PL/I for z/OS Language Reference
A character constant
A (ASCII) character constant
An A (ASCII) character constant is a character constant that ends with an A. The
data in an A character constant is converted to ASCII.
'
'A
character
character
All characters in an A character constant must be code page invariant and
occupy only one byte if converted to UTF-8.
Example
'123'A represents the hex value '313233'X .
This representation is independent of the setting of the DEFAULT(ASCII |
EBCDIC) option.
E (EBCDIC) character constant
An E (EBCDIC) character constant is a character constant that ends with an E. The
data in an E character constant is converted to EBCDIC.
'
'E
character
character
All characters in an E character constant must be code page invariant and
occupy only one byte if converted to UTF-8.
Example
'123'E represents the hex value 'F1F2F3'X
This representation is independent of the setting of the DEFAULT(ASCII |
EBCDIC) option.
X (hex) character constant
The X character constant is a contiguous sequence of an even number of hex digits
enclosed in single or double quotation marks and followed immediately by the
letter X. Each pair of hex digits represents one character.
The length of an X constant is half the number of hex digits specified.
A null X constant is written as two quotation marks followed by the X suffix.
Chapter 2. Data elements
33
X (hex)
' 'X
hex-digit hex-digit
Examples of X constants are:
Constant
"0d0A"x
’’X
Length
2
0
Note: The use of X constants can limit the portability of a program.
Bit data
Data with the BIT attribute allows manipulation of storage in terms of bits. Each
byte of storage is composed of 8 bits.
Bit constant
A bit constant is a contiguous sequence of binary digits enclosed in single or
double quotation marks and followed immediately by the letter B.
' 'B
binary-digit
A null bit constant is written as two quotation marks, followed by B.
Examples of bit constants are:
Constant
’1’B
"1100_1010_11"B
(64)’0’B
’’B
’0’B
Length
1
10
64
0
1
The number in parentheses in the third example is a string repetition factor which
specifies that the following series of bits is repeated the specified number of times.
The example shown would result in a string of 64 zero bits.
(See “Source-to-target rules” on page 77 for a discussion on the conversion of
bit-to-character data and character-to-bit data.)
B4 (hex) bit constant
The B4 bit constant is a contiguous sequence of hex digits enclosed in single or
double quotation marks and followed immediately by B4. Each hex digit represents
four bits. BX is a synonym for B4.
34
Enterprise PL/I for z/OS Language Reference
B4 (hex)
' '
hex-digit
B4
BX
Some examples of B4 constants are:
’CA’B4
is the same as
"1100_1010"B
’80’B4
’1’B4
(2)’F’B4
(2)’F’B4
’’B4
is
is
is
is
is
’1000_0000’B
’0001’B
’1111_1111’B
’FF’BX
""B
the
the
the
the
the
same
same
same
same
same
as
as
as
as
as
B3 (octal) bit constant
The B3 bit constant is a contiguous sequence of octal digits enclosed in single or
double quotation marks and followed immediately by B3. Each octal digit
represents three bits.
Some examples of B3 constants are:
’22’B3
is the same as
"010_010"B
’40’B3
’1’B3
(2)’7’B3
’’B3
is
is
is
is
’100_000’B
’001’B
’111_111’B
""B
the
the
the
the
same
same
same
same
as
as
as
as
Graphic data
GRAPHIC data can contain any DBCS character. Each DBCS character occupies 2
bytes of storage.
Graphic constant
A graphic constant is a contiguous sequence of DBCS characters enclosed in single
or double quotation marks. Graphic constants take up 2 bytes of storage for each
DBCS character in the constant.
G literals can start and end with DBCS quotes; in this case, the G itself can also be
specified in DBCS.
'< >'G
kk
The GRAPHIC compiler option must be in effect for graphic constants to be
accepted. If the GRAPHIC ENVIRONMENT option is not specified for STREAM
I/O files that include graphic constants, the CONVERSION condition is raised.
Chapter 2. Data elements
35
GX (hex) graphic
GX (hex) graphic constant
The GX graphic constant is a contiguous sequence of hex digits, in multiples of 4,
enclosed in single or double quotation marks and followed immediately by GX.
Each group of 4 hex digits represents one DBCS character.
' 'GX
hex-digit hex-digit hex-digit hex-digit
Examples:
represents one DBCS character
is the same as ’’g
’81a1’GX
""gX
Note: The use of GX can limit the portability of a program.
Mixed character data
Mixed character data can contain SBCS and DBCS characters. Mixed data is
represented by the CHARACTER data type, and follows the processing rules for
CHARACTER data.
The CHARGRAPHIC option of the OPTIONS attribute and the MPSTR built-in
function can be used to assist in mixed data handling. For more information on
CHARGRAPHIC see “OPTIONS option and attribute” on page 129; for
information on MPSTR, see “MPSTR” on page 546.
M (Mixed) character constant
An M constant is a contiguous sequence of DBCS and/or SBCS characters enclosed
in quotation marks (single or double), followed immediately by the letter M.
Quotations marks included in the constant follow the rules listed in “Using
quotation marks” on page 16. The length of an M constant is the number of SBCS
characters between the enclosing quotation marks counting any doubled quotation
marks as a single character, plus twice the number of DBCS characters in the
string.
A null M constant is written as two quotation marks followed by M.
' 'M
character
<kk>
Examples of mixed character constants are:
Constant
'IBM<kk>'M
36
Enterprise PL/I for z/OS Language Reference
Length
7 bytes on z/OS, 5 bytes on other platforms
M (Mixed)
Constant
'<.I.B.M>'M
''M
Length
8 bytes on z/OS, 6 bytes on other platforms
0
The GRAPHIC compiler option must be in effect for mixed constants to be
accepted. If the GRAPHIC ENVIRONMENT option is not specified for STREAM
I/O files having mixed constants, the CONVERSION condition is raised.
On z/OS, these additional rules apply to mixed constants:
v Shift-out/shift-in pairs must match; you may not nest pairs.
v The DBCS portion must not contain '0E'x or '0F'x in either byte
v The character portion must not contain the values '0E'x or '0F'x, unless
specifically intended as shift codes.
Note: Because shift-codes are used only on z/OS, the use of mixed data and M
constants can limit program portability.
Widechar data
WIDECHAR data can contain any UTF-16 character. Each widechar occupies 2
bytes of storage.
There is currently no support yet for
v
v
v
v
v
WIDECHAR characters in source files
W string constants
use of WIDECHAR expressions in stream I/O
implicit conversion to/from WIDECHAR in record I/O
implicit endianness flags in record I/O
If you create a WIDECHAR file, you should write the endianness flag ('fe_ff'wx)
as the first two bytes of the file.
WX (hex) widechar constant
The WX widechar constant is a contiguous sequence of hex digits, in multiples of
4, enclosed in single or double quotation marks and followed immediately by WX.
Each group of 4 hex digits represents one UTF-16 character.
' 'WX
hex-digit hex-digit hex-digit hex-digit
Examples:
’0031’wx
""wX
represents one UTF-16 character
is the same as ’’w
Note: WX constants should be specified in bigendian format (even if the program
will run in littleendian format). So, for example, the widechar value for the
character '1' should always be specified as '0031'wx (and not as '3100'wx).
Chapter 2. Data elements
37
WX (hex) widechar
Note: The use of WX can limit the portability of a program.
Numeric character data
A numeric character data item is the value of a variable that has been declared
with the PICTURE attribute with a numeric picture specification. The data item is
the character representation of a decimal fixed-point or floating-point value.
Numeric picture specification describes a character string that can be assigned only
data that can be converted to an arithmetic value.
For example:
declare Price picture ’999V99’;
specifies that any value assigned to Price is maintained as a character string of
five decimal digits, with an assumed decimal point preceding the rightmost two
digits. Data assigned to Price is aligned on the assumed point in the same way
that point alignment is maintained for fixed-point decimal data.
Numeric character data has arithmetic attributes, but it is not stored in coded
arithmetic form. Numeric character data is stored as a character string. Before it
can be used in arithmetic computations, it must be converted either to decimal
fixed-point or to decimal floating-point format. Such conversions are done
automatically, but they require extra processing time.
Although numeric character data is in character form, like character strings, and
although it is aligned on the decimal point like coded arithmetic data, it is
processed differently from the way either coded arithmetic items or character
strings are processed. Editing characters can be specified for insertion into a
numeric character data item, and such characters are actually stored within the
data item. Consequently, when the item is printed or treated as a character string,
the editing characters are included in the assignment operation. However, if a
numeric character item is assigned to another numeric character or arithmetic
variable, the editing characters are not included in the assignment operation—only
the actual digits, signs, and the location of the assumed decimal point are assigned.
For example:
declare Price picture ’$99V.99’,
Cost character (6),
Amount fixed decimal (6,2);
Price = 12.28;
Cost = ’$12.28’;
In the picture specification for PRICE, the currency symbol ($) and the decimal
point (.) are editing characters. They are stored as characters in the data item.
However, they are not a part of its arithmetic value. After both assignment
statements are executed, the actual internal character representation of Price and
Cost can be considered identical. If they were printed, they would print exactly the
same; but they do not always function in the same way. For example:
Amount
Cost
Amount
Price
=
=
=
=
Price;
Price;
Cost;
Cost;
After the first two assignment statements are executed, the value of Amount is
0012.28 and the value of Cost is '$12.28'. In the assignment of Price to Amount, the
currency symbol and the decimal point are editing characters, and they are not
part of the assignment. The numeric value of Price is converted to internal coded
arithmetic form. In the assignment of Price to Cost, however, the assignment is to
38
Enterprise PL/I for z/OS Language Reference
Numeric character data
a character string, and the editing characters of a numeric picture specification
always participate in such an assignment. No conversion is necessary because
Price is stored in character form.
The third and fourth assignment statements would raise the CONVERSION
condition. The value of Cost cannot be assigned to Amount because the currency
symbol in the string makes it invalid as an arithmetic constant. The value of Cost
cannot be assigned to Price for the same reason. Only values that are of arithmetic
type, or that can be converted to arithmetic type, can be assigned to a variable
declared with a numeric picture specification.
Although the decimal point can be an editing character or an actual character in a
character string, it does not raise the CONVERSION condition in converting to
arithmetic form, since its appearance is valid in an arithmetic constant. The same is
true for a valid plus or minus sign, because converting to arithmetic form provides
for a sign preceding an arithmetic constant.
Other editing characters, including zero suppression characters, drifting characters,
and insertion characters, can be used in numeric picture specifications. For a
complete discussion of picture characters, see Chapter 14, “Picture specification
characters,” on page 333.
Date attribute
Implicit date comparisons and conversions are made by the compiler if the two
operands have the DATE attribute. The DATE attribute specifies that a variable (or
argument or returned value) holds a date with a specified pattern.
DATE
('pattern')
pattern
One of the supported date patterns. If you do not specify a pattern, YYMMDD
is the default.
The DATE attribute is valid only with variables having one of the following sets of
attributes:
v CHAR(n) NONVARYING
v PIC'(n)9' REAL
v FIXED DEC(n,0) REAL
The length or precision of n must match the length of the pattern.
When you specify the RESPECT compile-time option (see the Programming Guide
for details), the following occur:
v The compiler knows to honor the DATE attribute
v The DATE built-in function returns a value that has the attribute
DATE('YYMMDD').
This allows DATE() to be assigned to a variable with the attribute
DATE('YYMMDD') without an error message being generated. If DATE() is
assigned to a variable not having the DATE attribute, however, an error message is
generated.
Chapter 2. Data elements
39
Date attribute
Implicit DATE comparisons:
The DATE attribute causes implicit commoning when two variables declared with
the DATE attribute are compared. Comparisons where only one variable has the
DATE attribute are flagged, and the other comparand is generally treated as if it
had the same DATE attribute, although some exceptions apply which are discussed
later.
Implicit commoning means that the compiler generates code to convert the dates to
a common, comparable representation. This process converts 2-digit years using
the window you specify in the WINDOW compile-time option.
In the following code fragment, if the DATE attribute is honored, then the
comparison in the second display statement is 'windowed'. This means that if the
window started at 1900, the comparison would return false. However, if the
window started at 1950, the comparison would return true.
dcl
dcl
dcl
dcl
a
b
c
d
pic’(6)9’
pic’(6)9’
pic’(6)9’
pic’(6)9’
date;
def(a);
date;
def(c);
b = ’670101’;
d = ’010101’;
display( b || ’ < ’ || d || ’ ?’ );
display( a < c );
Date comparisons can occur in the following places:
v IF and SELECT statements
v WHILE or UNTIL clauses
v Implicit comparisons caused by a TO clause
Comparing dates with like patterns:
The compiler does not generate any special code to compare dates with identical
patterns under the following conditions:
v The comparison operator of =, ¬= or <> is used.
v The pattern is equal to YYYY, YYYYMM, YYYYDDD, or YYYYMMDD.
Comparing dates with differing patterns:
For comparisons involving dates with unlike patterns, the compiler generates code
to convert the dates to a common comparable representation. Once the conversion
has taken place, the compiler compares the two values.
Comparisons involving the DATE attribute and a literal:
If you are making comparisons in which one comparand has the DATE attribute
and the other is a literal, the compiler issues a W-level message. Further compiler
action depends on the value of the literal as follows:
v If the literal appears to be a valid date, it is treated as if it had the same date
pattern and window as the comparand with the DATE attribute.
v If the literal does not appear to be a valid date, the DATE attribute is ignored on
the other comparand.
40
Enterprise PL/I for z/OS Language Reference
Date attribute
dcl start_date char(6) date;
if start_date >= ’’ then /* no windowing */
...
if start_date >= ’851003’ then /* windowed */
...
Comparisons involving the DATE attribute and a non-literal:
In comparisons where one comparand has the DATE attribute and the other is not
a date and not a literal, the compiler issues an E-level message. The non-date value
is treated as if it had the same date pattern as the other comparand and as if it had
the same window.
dcl start_date char(6) date;
dcl non_date char (6);
if start_date >= non_date then /* windowed */
...
Implicit DATE assignments:
The DATE attribute can also cause implicit conversions to occur in assignments of
two variables declared with date patterns.
v If the source and target have the same DATE and data attributes, then the
assignment proceeds as if neither had the DATE attribute.
v If the source and target have differing DATE attributes, then the compiler
generates code to convert the source date before making the assignment.
v In assignments where the source has the DATE attribute but the target does not,
the compiler issues an E-level message and ignores the DATE attribute.
v In assignments where the target has the DATE attribute but the source does not
(and the source IS NOT a literal), the compiler issues an E-level message and
ignores the DATE attribute.
v In assignments where the target has the DATE attribute but the source does not
(and the source IS a literal), the compiler issues a W-level message and ignores
the DATE attribute.
dcl start_date char(6) date;
start_date = ’’;
...
v If the source holds a four-digit year and the target holds a two-digit year, the
source can hold a year that is not in the target window. In this case, the ERROR
condition is raised.
dcl x char(6) date;
dcl y char(8) date(’YYYYMMDD’);
y = ’20600101’;
x = y; /* raises error if window is <= 1960 */
v The DATE attribute is ignored in:
– The debugger
– Assignments performed in record I/O statements
– Assignments and conversions performed in stream I/O statements (such as
GET DATA).
Even if you do not choose a windowing solution, you might have some code that
needs to manipulate both two- and four-digit years. You can use multiple date
patterns to help you in these situations:
Chapter 2. Data elements
41
Date attribute
dcl old_date char(6) date(’YYMMDD’);
dcl new_date char(8) date(’YYYYMMDD’);
new_date = old_date;
Date diagnostics:
In PL/I, effective assignments occur when
v An expression is passed as an argument to an entry that has described that
argument
v An expression is used in a RETURN statement.
The following uses of date variables are flagged:
v Assignments (explicit or effective) which include either
– A date to a non-date
– A non-date to a date
v Any arithmetic operation applied to a date
v Use of a date in a BY clause (since this implies an arithmetic operation)
v Use of a date in any mathematical built-in function
v Use of a date in any arithmetic built-in function except BINARY, DECIMAL,
FIXED, FLOAT, or PRECISION.
v Use of a date in the built-in functions SUM, PROD, or POLY.
In all of the cases listed previously, code is produced but no windowing occurs. In
effect, the DATE attribute is ignored.
Named constants
Named constants can be declared for scalars or structures.
As a scalar identifier, a named constant is declared with the VALUE attribute along
with other data attributes. All references to the name are logically treated as a
reference to the appropriate constant but with the complete set of attributes,
whether explicitly declared or defaulted.
A structure can define a namespace of named constants, when the VALUE attribute
is specified on the leaf elements, and the references to the members of all structure
elements are unambiguous. You can specify the elements of a structure with the
VALUE attribute, provided that the structure meets all of the following conditions:
v All leaf elements of the structure have the VALUE attribute.
v The structure contains no arrays or unions.
v The structure has no storage attributes such as AUTOMATIC.
Note: The effect of the use of a named constant might not be exactly the same as
the use of an unnamed constant. The attributes for a named constant are
taken from the declaration which includes explicit and default attributes.
The attributes for an unnamed constant are deduced from the shape, form,
and size of the constant. For string data, if the length is not specified, or is
specified with an asterisk, the length is determined from the length of the
restricted expression.
Named constants can be more precise to use in an application program, and they
can offer more predictable results. For example, if the named constant Unit is
defined as FIXED BINARY VALUE(1), it has the attributes FIXED BINARY(15)
VALUE(1). If you simply use the digit 1, its attributes are FIXED DECIMAL(1,0).
See Figure 1 on page 44 for other differences that can occur.
42
Enterprise PL/I for z/OS Language Reference
Named constants
In addition, named constants allow you to parameterize your application, which
makes it easier to debug and maintain.
Named constants can be declared for arithmetic data, string data, and for pointers
and offsets. For arithmetic and string data and their attributes, see “String data and
attributes” on page 29 and “Coded arithmetic data and attributes” on page 22,
respectively. A named constant must be declared before it is used.
VALUE attribute:
VALUE(restricted-expression)
restricted expression
The expression must evaluate to a scalar value. For information on restricted
expressions see “Restricted expressions” on page 70.
Examples of named constants:
Figure 1 on page 44 shows named constants and the differences in attributes and
precisions that can occur between named and unnamed constants.
Named constants can be used wherever a constant is required. They can also be
used in restricted expressions that appear later in the program allowing evaluation
of a dependent constant.
Chapter 2. Data elements
43
Program-control data
Dcl A4 value(148) fixed bin,
C4 value(261) fixed bin,
Whole value(800) fixed bin;
Dcl Notes (4) static,
init(a4, (Whole/4),
/* 148, 200 */
c4, (Whole*2)); /* 261, 1600 */
/* note that "Head" gets length equal to length of VALUE
*/
Dcl Head char VALUE(’Feel the Power of PL/I’); /* char(22) */
Dcl Headsize fixed bin value(length(Head));
/* 22
*/
Dcl 1 Head1 static,
2 * char(Headsize) initial(Head),
/* char(22) */
2 * char(20) init(’’),
2 * char(5) init(’Page ’),
2 Page_number pic ’zz9’,
2 * char(0);
Dcl TwoHeads char(2*Headsize);
/* char(44) */
Dcl Page0 picture ’zz9’ value(0);
Dcl MyNullPtr ptr value(ptrvalue(’ffff_ffff’xn));
/* Differences in attributes/results of
named and unnamed constants
*/
Dcl Pi float bin value (3.1416);
3.1416
/* is FLOAT BINARY(21) but ... */
/* is FIXED DECIMAL(5,4)
*/
Dcl Unit fixed bin value(1);
1
1.0
1B
0000_0000_0000_001B
/*
/*
/*
/*
/*
is
is
is
is
is
FIXED
FIXED
FIXED
FIXED
FIXED
BINARY(15) but ... */
DECIMAL(1,0)
*/
DECIMAL(2,1)
*/
BINARY(1)
*/
BINARY(15)
*/
Dcl Title char(20) value(’SCIDS’); /* is CHAR(20)
Dcl Title2 char
value(’SCIDS’);/* is CHAR(5)
’SCIDS’
/* is CHAR(5)
but ... */
*/
*/
Figure 1. Named constants
Program-control data types and attributes:
This section describes program control data and associated attributes. Use
program-control data to indicate values that control the execution of your program.
Label data and LABEL attribute:
A label is a label constant or the value of a label variable.
LABEL
,
(
44
label-constant
Enterprise PL/I for z/OS Language Reference
)
Label data and attribute
If a list of label constants is given, the variable must always have as its value a
member of that list, and the label constants in the list must be known in the block
containing the label declaration. The parenthesized list of label constants can be
used in a LABEL attribute specification for a label array.
A label constant is a name written as the label prefix of a statement (other than
PROCEDURE, ENTRY, PACKAGE, or FORMAT) so that during execution,
program-control can be transferred to that statement through a reference to it.
(“Statements” on page 8 discusses the syntax of the label prefix.) In the following
line of code, for example, Abcde is a label constant.
Abcde: Miles = Speed*Hours;
The labelled statement can be executed either by normal sequential execution of
instructions or by using the GO TO statement to transfer control to it from some
other point in the program.
A label variable can have another label variable or a label constant assigned to it.
When such an assignment is made, the environment of the source label is assigned
to the target. If you declare a static array of labels to have initial values, the array
is treated as nonassignable.
A label variable used in a GO TO statement must have as its value a label constant
that is used in a block that is active at the time the GO TO is executed. Consider
the following example:
declare Lbl_x label;
Lbl_a:
statement;
.
.
.
Lbl_b:
statement;
.
.
.
Lbl_x = Lbl_a;
.
.
.
go to Lbl_x;
Lbl_a and Lbl_b are label constants, and Lbl_x is a label variable. By assigning
Lbl_a to Lbl_x, the statement GO TO Lbl_x transfers control to the Lbl_a statement.
Elsewhere, the program can contain a statement assigning Lbl_b to Lbl_x. Then,
any reference to Lbl_x would be the same as a reference to Lbl_b. This value of
Lbl_x is retained until another value is assigned to it.
If a label variable has an invalid value, detection of such an error is not
guaranteed. In the following example, transfer is made to a particular element of
the array Z based on the value of I.
go to Z(I);
.
.
.
Z(1): if X = Y then return;
.
.
.
Z(2): A = A + B + C * D;
Chapter 2. Data elements
45
Label data and attribute
.
.
.
Z(3):
A = A + 10;
If Z(2) is omitted, GO TO Z(I) when I=2 raises the ERROR condition. GO TO Z(I)
when I < LBOUND(Z) or I > HBOUND(Z) causes unpredictable results if the
SUBSCRIPTRANGE condition is disabled.
Format data and FORMAT attribute:
A format data item is a format constant or a format variable. A format constant is a
name written as the label prefix of a FORMAT statement.
The FORMAT attribute specifies that the name being declared is a format variable.
FORMAT
A name declared with the FORMAT attribute can have another format variable or
a format constant assigned to it. When such an assignment is made, the
environment of the source label is assigned to the target.
To maintain compatibility between other PL/I compilers, format variables may be
declared as label variables.
Consider the following example:
Prntexe: format
( column(20),A(15), column(40),A(15), column(60),A(15) );
Prntstf: format
( column(20),A(10), column(35),A(10), column(50),A(10) );
Prntexe and Prntstf are the format constants.
A second example indicates that 4 and 5 have the same effect as 2, and 6
and 7 have the same effect as 3.
1
2
3
4
5
6
7
dcl Print format;
put edit (X,Y,Z) (R(Prntexe) );
put edit (X,Y,Z) (R(Prntstf) );
Print = Prntexe;
put edit (X,Y,Z) (R(Print) );
Print = Prntstf;
put edit (X,Y,Z) (R(Print) );
VARIABLE attribute:
The VARIABLE attribute establishes the name as a variable and should be
specified only along with one of the attributes: ENTRY, FILE or LABEL. It will be
ignored in all other declares.
VARIABLE
46
Enterprise PL/I for z/OS Language Reference
VARIABLE
The VARIABLE attribute is implied if the name is a member of a structure or
union, or if any of the following attributes are specified:
Storage class attribute
DIMENSION
PARAMETER
Alignment attribute
INITIAL
In the following declaration, Account1 and Account2 are file variables and File1
and File2 are file constants.
declare Account1 file variable,
Account2 file automatic,
File1 file,
File2 file;
File1 and File2 can subsequently be assigned to Account1 or to Account2.
Chapter 2. Data elements
47
48
Enterprise PL/I for z/OS Language Reference
Chapter 3. Expressions and references
Order of evaluation. . . . . . . . . .
Targets . . . . . . . . . . . . . .
Variables . . . . . . . . . . . .
Pseudovariables . . . . . . . . . .
Intermediate results . . . . . . . .
Operational expressions . . . . . . . .
Handle operations . . . . . . . . .
Pointer operations . . . . . . . . .
Arithmetic operations . . . . . . . .
Data conversion in arithmetic operations
Results of arithmetic operations . . .
Using exponentiation . . . . . . .
Bit operations. . . . . . . . . . .
BOOL built-in function . . . . . .
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
52
52
52
52
53
53
54
54
55
55
56
62
63
63
Comparison operations . . .
Concatenation operations . . .
Results under RULES(IBM) .
Results under RULES(ANS) .
Combinations of operations . .
Priority of operators . . .
Array expressions . . . . . .
Prefix operators and arrays . .
Infix operators and arrays . .
Array-and-element operations
Array-and-array operations .
Structure expressions . . . . .
Restricted expressions . . . . .
Examples . . . . . . . .
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
63
65
66
66
67
67
69
69
69
69
70
70
70
71
This chapter discusses the various types of expressions and references.
An expression is a representation of a value. An expression can be one of the
following:
v A single constant, variable, or function reference
v Any combination of constants, variables, or function references, including
operators and parentheses used in the combination.
An expression that contains operators is an operational expression. The constants and
variables of an operational expression are called operands. See “Operational
expressions” on page 53 for more information.
The following diagram shows the syntax for expressions and references.
unary-expression
(1)
infix-operator
unary-expression
unary-expression:
elementary-expression
(1)
prefix-operator
elementary-expression:
(expression)
reference
constant
© Copyright IBM Corp. 1999, 2012
49
Expressions and references
reference:
(2)
locator-qualifier
basic-reference
(3)
(
subscript-list
)
(4)
(
argument-list
)
locator-qualifier:
(2)
reference
->
=>
.
basic-reference:
(5)
qualified-reference
(6)
identifier
subscript-list:
,
(3)
expression
*
argument-list:
,
(4)
expression
*
qualified-reference:
(5)
basic-reference
.
(
subscript-list
)
Notes:
50
1
Operators are shown in Table 6 on page 6.
2
Locator-qualifier is described under “Locator qualification” on page 247 and
“Typed structure qualification” on page 145.
3
Subscripts are described under “Arrays” on page 173.
4
Arguments are described in “Passing arguments to procedures” on page 109.
Enterprise PL/I for z/OS Language Reference
Expressions and references
5
Qualified-reference is described under “Structure and union qualification” on
page 179.
6
Identifiers are described under “Identifiers” on page 5.
Any expression can be classified as an element expression (also called a scalar
expression), an array expression, or a structure expression. Element variables and
array variables can appear in the same expression.
An element expression
represents a single value. This definition includes an elementary name
within a structure or a union or a subscripted name that specifies a single
element of an array.
An array expression
represents an array of values. This definition includes a member of a
structure or union that has the dimension attribute.
A structure expression
represents a structured set of values.
Given the following example:
dcl A(10,10) bin fixed(31),
B(10,10) bin fixed(31),
1 Rate,
2 Primary dec fixed(4,2),
2 Secondary dec fixed(4,2),
1 Cost(2),
2 Primary dec fixed(4,2),
2 Secondary dec fixed(4,2),
C bin fixed(15),
D bin fixed(15);
dcl Pi bin float value(3.1416);
These are element expressions:
Pi
27
C
C * D
A(3,2) + B(4,8)
Rate.Primary - Cost.Primary(1)
A(4,4) * C
Rate.Secondary / 4
A(4,6) * Cost.Secondary(2)
sum(A)
addr(Rate)
These are array expressions:
A
A + B
A * C - D
B / 10B
The syntax of many PL/I statements allows expressions, provided the result of the
expression conforms with the syntax rules. Unless specifically stated in the text
following the syntax specification, the unqualified term expression or reference refers
to a scalar expression. For expressions other than a scalar expression, the type of
expression is noted. For example, the term array expression indicates that a scalar
expression is not valid.
An example of a structure expression is:
Chapter 3. Expressions and references
51
Expressions and references
Rate = Rate*2
Order of evaluation
PL/I statements often contain more than one expression or reference. Except as
described for specific instances (for example, the assignment statement), evaluation
can be in any order, or (conceptually) at the same time.
For example:
dcl (X,Y,Z) entry returns(float), (F,G,H) float;
F = X( Y(G,H), Z(G,H) );
The functions Y and Z can change the value of the arguments passed to them.
Hence, the value returned by X might be different depending on which function is
invoked first. You should not presume that the first parameter is evaluated first. In
some situations, it is more optimal to evaluate the last first.
Assuming that the INC function increments the value of the argument passed to it
and returns the updated value, the example that follows could put out B(1,2) or
B(2,1) depending on which subscript is evaluated first. You should not presume
which subscript is evaluated first.
dcl B(2,2);
I = 0;
put list ( B( INC(I), INC(I) ) );
Targets
The results of an expression evaluation or of a conversion are assigned to a target.
Targets can be variables, pseudovariables, or intermediate results.
Variables
In the case of an assignment, such as the statement:
A = B;
the target is the variable on the left of the assignment symbol (in this case A).
Assignment to variables can also occur in stream I/O, DO, DISPLAY, and record
I/O statements.
Pseudovariables
A pseudovariable represents a target field, for example:
declare A character(10),
B character(30);
substr(A,6,5) = substr(B,20,5);
In this assignment statement, the SUBSTR built-in function extracts a substring of
length 5 from the string B, beginning with the twentieth character. The SUBSTR
pseudovariable indicates the location, within string A, that is the target. Thus, the
last 5 characters of A are replaced by characters 20 through 24 of B. The first 5
characters of A remain unchanged.
Pseudovariables are discussed in Chapter 18, “Built-in functions, pseudovariables,
and subroutines,” on page 383.
52
Enterprise PL/I for z/OS Language Reference
Intermediate results
Intermediate results
When an expression is evaluated, the target attributes usually are partly derived
from the source, partly from the operation being performed, and partly from the
attributes of a second operand. Some defaults may be used, and some
implementation restrictions (for example, maximum precision) and conventions
exist. An intermediate result can undergo conversion if a further operation is
performed. After an expression is evaluated, the result can be further converted for
assignment to a variable or pseudovariable. These conversions follow the same
rules as the conversion of programmer-defined data, for example:
declare A character(8),
B fixed decimal(3,2),
C fixed binary(10);
A = B + C;
During the evaluation of the expression B + C and during the assignment of that
result, there are four different results:
1. The intermediate result to which the converted binary equivalent of B is
assigned
2. The intermediate result to which the binary result of the addition is assigned
3. The intermediate result to which the converted decimal fixed-point equivalent
of the binary result is assigned
4. A, the final destination of the result, to which the converted character
equivalent of the decimal fixed-point representation of the value is assigned
The attributes of the first result are determined from the attributes of the source B,
from the operator, and from the attributes of the other operand. If one operand of
an arithmetic infix operator is binary, the other is converted to binary before
evaluation.
The attributes of the second result are determined from the attributes of the source
(C and the converted representation of B).
The attributes of the third result are determined in part from the source (the
second result) and in part from the attributes of the eventual target A. The only
attribute determined from the eventual target is DECIMAL (a binary arithmetic
representation must be converted to decimal representation before it can be
converted to a character value).
The attributes of A are known from the DECLARE statement.
Operational expressions
An operational expression consists of one or more single operations. A single
operation is either a prefix operation (an operator preceding a single operand) or an
infix operation (an operator between two operands). The two operands of any infix
operation normally should be the same data type when the operation is performed.
The operands of an operation in a PL/I expression are converted, if necessary, to
the same data type before the operation is performed. Detailed rules for conversion
can be found in Chapter 4, “Data conversion,” on page 73.
There are few restrictions on the use of different data types in an expression.
However, these mixtures imply conversions. If conversions take place at run time,
Chapter 3. Expressions and references
53
Operational expressions
the program takes longer to run. Also, conversion can result in loss of precision.
When using expressions that mix data types, you should understand the relevant
conversion rules.
These classes of operations are described in the following topics: handle, pointer,
arithmetic, bit, comparison, and concatenation.
Handle operations
The following handle operations can be used:
v Compare two handles having the same associated structure type.
v Add an expression to or subtract an expression from a handle with sensitivity to
the associated structure type.
For example, if x is a handle for structure type t and n is an integer value, x+n
and x−n are handles for t.
– x+n increments the associated pointer value of x by n times the size of the
structure t.
– x−n decrements the associated pointer value of x by n times the size of
structure t.
You can also use the += and −= compound assignments to increment and
decrement handles.
v Compute the difference of two handles with sensitivity to the associated
structure type.
For example, if x and y are handles for structure type t, the result of x-y is the
number of instances of t between x and y. The value x-y equals the result of
(PTRVALUE(x)-PTRVALUE(y)) / SIZE(:t:).
Computing the difference of two handles to different structure types is not
permitted.
Pointer operations
The following pointer operations can be used:
v Add an expression to or subtract an expression from a pointer expression. The
expression type must be computational. If necessary, the nonpointer operand is
converted to FIXED BINARY(31,0), for example:
Ptr1 = Ptr1 - 16;
Ptr2 = Ptr1 + (I*J);
You can also use the built-in function, POINTERADD, to perform these
operations. You must use POINTERADD if the result is used as a locator
reference, for example:
(Ptr1 + 16) -> Based_ptr
is invalid
pointeradd(Ptr1,16) -> Based_ptr
is valid
v Subtract two pointers to obtain the logical difference. The result is a FIXED
BINARY(31,0) value.
Bin31 = Ptr2 - Ptr1;
v Compare pointer expressions using infix operators.
if Ptr2 > Ptr1 then
Bin31 = Ptr2 - Ptr1;
v Compare pointer expressions to null strings (' ' or ' 'b). The NULLSTRPTR
suboption of the DEFAULT compiler option determines how the compiler
handles assignments of null strings to pointers and comparisons of null strings
54
Enterprise PL/I for z/OS Language Reference
Operational expressions
to pointers. In both cases, the option determines if the null string is treated as if
it were a reference to the NULL built-in function or to the SYSNULL built-in
function.
For example, if the NULLSTRPTR(SYSNULL) suboption is in effect, the
assignment in the following code assigns SYSNULL() to header, and the
comparison produces a true value if header equals to SYSNULL().
dcl header pointer;
header = ’’;
...
if header = ’’ then...
v Use pointer expressions in arithmetic contexts using the BINARYVALUE built-in
function.
Bin31 = Bin31 + binaryvalue(Ptr1);
v Use computational expressions in pointer contexts using the POINTERVALUE
built-in function.
dcl 1 Cvtprt pointer based(pointervalue(16));
dcl 1 Cvt based(Cvtptr),
2 Cvt ...;
If necessary, the expressions are converted to FIXED BINARY(31,0).
A PL/I block can use pointer arithmetic to access any element within a structure or
an array variable. However, the block must be passed the containing structure or
array variable, or have the referenced aggregate within its name scope.
Arithmetic operations
An arithmetic operation is specified by combining operands with one of these
operators:
+
-
*
/
**
The plus sign and the minus sign can appear as prefix operators or as infix
operators. All other arithmetic operators can appear only as infix operators.
(Arithmetic operations can also be specified by the ADD, SUBTRACT, DIVIDE, and
MULTIPLY built-in functions.)
Prefix operators can precede and be associated with any of the operands of an infix
operation. For example, in the expression A*-B, the minus sign indicates that the
value of A is multiplied by -1 times the value of B.
More than one prefix operator can precede and be associated with a single
variable. More than one positive prefix operator has no cumulative effect, but two
negative prefix operators have the same effect as a single positive prefix operator.
Data conversion in arithmetic operations
The two operands of an arithmetic operation can differ in type, base, mode,
precision, and scale. When they differ, conversion takes place as described below.
(For coded arithmetic operands, you can also determine conversions using Table 13
on page 58. Each operand is converted to the type, base, and mode of the result. It
is not necessarily converted to the result's precision and scale.)
Note: Scaled FIXED BINARY operands are converted to scaled FIXED DECIMAL
before any operations on them are performed.
Chapter 3. Expressions and references
55
Data conversion in arithmetic operations
Type:
Character operands are converted to FIXED DECIMAL(N,0). Bit operands are
converted to FIXED BINARY(M,0). (Refer to “Limits,” on page 781 for the
maximums.) Numeric character operands are converted to DECIMAL with scale
and precision determined by the picture-specification.
Graphic and widechar variables and strings are allowed in all computational
contexts. If conversion is necessary, the rules followed are the same as for
character.
The result of an arithmetic operation is always in coded arithmetic form. Type
conversion is the only conversion that can take place in an arithmetic prefix
operation.
Base:
If the bases of the two operands differ, the decimal operand is converted to its
binary equivalent.
Mode:
If the modes of the two operands differ, the real operand is converted to complex
mode by acquiring an imaginary part of zero with the same base, scale, and
precision as the real part. The exception to this is in the case of exponentiation
when the second operand (the exponent of the operation) is fixed-point real with a
scaling factor of zero. In such a case, conversion is not necessary.
Precision:
If only precisions and/or scaling factors vary, type conversion is not necessary.
Scale:
If the scales of the two operands differ, the fixed-point operand is converted to
floating-point scale. The exception to this is in the case of exponentiation when the
first operand is of floating-point scale and the second operand (the exponent of the
operation) is fixed-point with a scaling factor of zero, that is, an integer or a
variable that has been declared with precision (p,0). In such a case, conversion is
not necessary, but the result is floating-point.
If both operands of an exponentiation operation are fixed-point, conversions can
occur in one of the following ways:
v Both operands are converted to floating-point if the exponent has a precision
other than (p,0).
v The first operand is converted to floating-point unless the exponent is an
unsigned integer.
v The first operand is converted to floating-point if precisions indicate that the
result of the fixed-point exponentiation would exceed the maximum number of
digits allowed.
Results of arithmetic operations
After any necessary conversion of the operands in an expression has been carried
out, the arithmetic operation is performed and a result is obtained. This result can
be the value of the expression, or it can be an intermediate result upon which
further operations are to be performed, or a condition can be raised.
56
Enterprise PL/I for z/OS Language Reference
Results of arithmetic operations
Table 13 on page 58 and Table 14 on page 59 show the attributes and precisions
that result from various arithmetic operations.
Table 18 on page 62 shows the attributes of the result for the special cases of
exponentiation noted in the right-hand columns of Table 13 on page 58 and
Table 14 on page 59.
On the z/OS platform, the choice of which set of instructions is used for a float
calculation is determined by two compiler options:
v under FLOAT(DFP)
– All computations that would yield a FLOAT DEC result are done using the
IEEE decimal floating-point instructions.
– All computations that would yield a FLOAT BIN result are done using the
floating-point instructions for the format specified by the HEXADEC and
IEEE suboptions of the DEFAULT compiler option.
v under FLOAT(NODFP)
– All computations that would yield a FLOAT result are done using the
floating-point instructions for the format specified by the HEXADEC and
IEEE suboptions of the DEFAULT compiler option.
So, under the FLOAT(NODFP) and DEFAULT(HEXADEC) options, all
computations are done using the hexadecimal floating-point instructions, and
variables declared IEEE will be converted to HEXADEC. But, under the
FLOAT(NODFP) and DEFAULT(IEEE) options, all computations are done using the
IEEE binary floating-point instructions, and variables declared HEXADEC will be
converted to IEEE as necessary.
On all other platforms, float calculations are done using the IEEE binary
floating-point instructions native to that platform.
Under the compiler option RULES(ANS), if one operand is scaled FIXED
DECIMAL and the other is FIXED BINARY, the FIXED BINARY value is converted
to FIXED DECIMAL. Table 15 on page 59 shows the attributes and precisions that
result for this case under compiler option RULES(ANS). For more information on
the RULES compiler option, see the Programming Guide.
Chapter 3. Expressions and references
57
Results of arithmetic operations
Table 13. Results of arithmetic operations for one or more FLOAT operands
1st Operand
(p1,q1)
2nd Operand
(p2,q2)
FLOAT
DECIMAL
(p1)
FLOAT
DECIMAL
(p2)
FLOAT
DECIMAL
(p1)
FLOAT
DECIMAL
(p2,q2)
FIXED
DECIMAL
(p1,q1)
FLOAT
DECIMAL
(p2)
FLOAT
BINARY
(p1)
FLOAT
BINARY
(p2)
FLOAT
BINARY
(p1)
FIXED
BINARY
(p2,q2)
FIXED
BINARY
(p1,q1)
FLOAT
BINARY
(p2,q2)
FIXED
DECIMAL
(p1,q1)
FLOAT
BINARY
(p2)
FLOAT
DECIMAL
(p1)
FLOAT
BINARY
(p1,q2)
FLOAT
DECIMAL
(p1)
FLOAT
BINARY
(p2)
FIXED
BINARY
(p1,q1)
FLOAT
DECIMAL
(p2)
FLOAT
BINARY
(p1)
FIXED
DECIMAL
(p2,q2)
FLOAT
BINARY
(p1)
FLOAT
DECIMAL
(p2)
Attributes of
the Result
for Addition,
Subtraction,
Multiplication,
or Division
Addition
or
Subtraction
Precision
Multiplication
Precision
FLOAT
DECIMAL (p)
(unless special case
C applies)
p = MAX(p1,p2)
FLOAT
DECIMAL
(p)
p = MAX(p1,p2)
FLOAT
BINARY
(p)
FLOAT
BINARY (p)
(unless special case
C applies)
p = MAX(p1,p2)
FLOAT
BINARY
(p)
p = MAX(
CEIL(p1*3.32),p2)
FLOAT
BINARY (p)
(unless special case
A or C applies)
p = MAX(
CEIL(p1*3.32),p2)
p = MAX(p1,CEIL(p2*3.32))
FLOAT
BINARY (p)
(unless special case
B or C applies)
p = MAX(
p1,CEIL(p2*3.32))
FLOAT
BINARY
(p)
Notes:
1. Special cases of exponentiation are described in Table 18 on page 62.
2. For a table of CEIL(N*3.32) values, see Table 22 on page 76.
58
Division
Precision
Attributes
of the
Result for
Exponentiation
Enterprise PL/I for z/OS Language Reference
Results of arithmetic operations
Table 14. Results of arithmetic operations between two unscaled FIXED operands under RULES(ANS)
1st Operand
(p1,q1)
Attributes of
the Result for
Addition,
Subtraction,
2nd Operand Multiplication,
or Division
(p2,q2)
FIXED
DECIMAL
(p1,0)
FIXED
DECIMAL
(p2,0)
FIXED
DECIMAL
(p,q)
p = 1
p = 1
+MAX(p1,p2) +p1+p2
q = 0
q = 0
p = N
q = N-p1
FLOAT DECIMAL (p)
(unless special case
A applies)
p = MAX(p1,p2)
FIXED
BINARY
(p1,0)
FIXED
BINARY
(p2,0)
FIXED
BINARY
(p,0)
p = 1
+MAX(p1-q1,
p2-q2) +q
q = 0
p = 1+p1
+p2
q = 0
p = M
q = 0
FLOAT BINARY (p)
(unless special case
B applies)
p = MAX(p1,p2)
FIXED
DECIMAL
(p1,0)
FIXED
BINARY
(p2,0)
FIXED
BINARY
(p,0)
p = 1
+MAX(r,p2)
q = 0
p = 1
+r+p2
q = 0
p = M
q = 0
FLOAT BINARY (p)
(unless special case
A applies)
p = MAX(CEIL
(p1*3.32 ),p2)
FIXED
BINARY
(p1,0)
FIXED
DECIMAL
(p2,0)
FIXED
BINARY
(p,0)
p = 1
+MAX(p1,t)
q = 0
p = 1
+p1+t
q = 0
p = M
q = 0
FLOAT BINARY (p)
(unless special case
B applies)
p = MAX(CEIL
(p1*3.32 ),p2)
Addition
or
Subtraction
Precision
M is the maximum precision for FIXED BINARY.
N is the maximum precision for FIXED DECIMAL.
r = 1 + CEIL(p1*3.32)
s = CEIL(ABS(q1*3.32)) * SIGN(q1)
Multiplication
Precision
Division
Precision
Attributes
of the
Result for
Exponentiation
t = 1 + CEIL(p2*3.32)
u = CEIL(ABS(q2*3.32)) * SIGN(q2)
v = CEIL(p2/3.32)
w = CEIL(p1/3.32)
Notes:
The scaling factor must be in the range -128 through +127.
1. Special cases of exponentiation are described in Table 18 on page 62.
2. For a table of CEIL(N*3.32) values, see Table 22 on page 76.
3. Under RULES(ANS) a divide with unscaled FIXED operands can produce a scaled result only if both operands
are FIXED DECIMAL.
Table 15. Results of arithmetic operations between two scaled FIXED operands under RULES(ANS)
1st Operand
(p1,q1)
Attributes of
the Result for
Addition,
Subtraction,
2nd Operand Multiplication,
or Division
(p2,q2)
FIXED
DECIMAL
(p1,q1)
FIXED
DECIMAL
(p2,q2)
FIXED
DECIMAL
(p,q)
Addition
or
Subtraction
Precision
p = 1 +
MAX(p1-q1,
p2-q2) +q
q =
MAX(q1,q2)
Multiplication
Precision
p = 1
+p1+p2
q =
q1+q2
Division
Precision
p = N
q =
N-p1+q1-q2
Attributes
of the
Result for
Exponentiation
FLOAT DECIMAL (p)
(unless special case
A applies)
p = MAX(p1,p2)
Chapter 3. Expressions and references
59
Results of arithmetic operations
Table 15. Results of arithmetic operations between two scaled FIXED operands under RULES(ANS) (continued)
1st Operand
(p1,q1)
Attributes of
the Result for
Addition,
Subtraction,
2nd Operand Multiplication,
or Division
(p2,q2)
FIXED
DECIMAL
(p1,q1)
FIXED
BINARY
(p2,0)
FIXED
DECIMAL
(p,q)
p = 1
+MAX(p1q1,v) +q
q = q1
p = 1
+p2+v
q = q1
FIXED
BINARY
(p1,0)
FIXED
DECIMAL
(p2,q2)
FIXED
DECIMAL
(p,q)
p = 1
+MAX(p2q2,w) +q
q = q2
p = 1
+p2+w
q = q1
Addition
or
Subtraction
Precision
M is the maximum precision for FIXED BINARY.
N is the maximum precision for FIXED DECIMAL.
r = 1 + CEIL(p1*3.32)
s = CEIL(ABS(q1*3.32)) * SIGN(q1)
Multiplication
Precision
Division
Precision
Attributes
of the
Result for
Exponentiation
p = N
q = N-q1
FLOAT BINARY (p)
(unless special case
A applies)
p = MAX(CEIL
(p1*3.32 ),p2)
p = N
q = N-q2
FLOAT BINARY (p)
(unless special case
B applies)
p = MAX(CEIL
(p1*3.32 ),p2)
t = 1 + CEIL(p2*3.32)
u = CEIL(ABS(q2*3.32)) * SIGN(q2)
v = CEIL(p2/3.32)
w = CEIL(p1/3.32)
Notes:
The scaling factor must be in the range -128 through +127.
1. Special cases of exponentiation are described in Table 18 on page 62.
2. For a table of CEIL(N*3.32) values, see Table 22 on page 76.
3. Under RULES(ANS), scaled FIXED BINARY is not allowed.
Table 16. Results of arithmetic operations between two FIXED operands under RULES(IBM)
1st Operand
(p1,q1)
Attributes of
the Result for
Addition,
Subtraction,
2nd Operand Multiplication,
or Division
(p2,q2)
FIXED
DECIMAL
(p1,q1)
FIXED
DECIMAL
(p2,q2)
FIXED
DECIMAL
(p,q)
p = 1
+MAX(p1-q1,
p2-q2) +q
q =
MAX(q1,q2)
FIXED
BINARY
(p1,q1)
FIXED
BINARY
(p2,q2)
FIXED
BINARY
(p,q)
FIXED
DECIMAL
(p1,q1)
FIXED
BINARY
(p2,q2)
FIXED
BINARY
(p,q)
60
Enterprise PL/I for z/OS Language Reference
Addition
or
Subtraction
Precision
Multiplication
Precision
Division
Precision
Attributes
of the
Result for
Exponentiation
p = N
q =
N-p1+q1-q2
FLOAT DECIMAL (p)
(unless special case
A applies)
p = MAX(p1,p2)
p = 1
+MAX(p1-q1, p = 1
+p1+p2
p2-q2) +q
q = q1+q2
q =
MAX(q1,q2)
p = M
q = M-p1
+q1-q2
FLOAT BINARY (p)
(unless special case
B applies)
p = MAX(p1,p2)
p = 1
+MAX(r-s,
p2-q2)+q
q =
MAX(s,q2)
p = M
q = M-r
+s-q2
FLOAT BINARY (p)
(unless special case
A applies)
p =MAX(
CEIL((p1*3.32 ),p2)
p = 1
+p1+p2
q =
q1+q2
p = 1+r
+p2
q = s+q2
Results of arithmetic operations
Table 16. Results of arithmetic operations between two FIXED operands under RULES(IBM) (continued)
1st Operand
(p1,q1)
Attributes of
the Result for
Addition,
Subtraction,
2nd Operand Multiplication,
or Division
(p2,q2)
FIXED
BINARY
(p1,q1)
FIXED
DECIMAL
(p2,q2)
FIXED
BINARY
(p,q)
Addition
or
Subtraction
Precision
Multiplication
Precision
p = 1
p = 1
+MAX(p1+p1+t
q1,t-u) +q
q = q1+u
q =
MAX(s,q1,u)
M is the maximum precision for FIXED BINARY.
N is the maximum precision for FIXED DECIMAL.
r = 1 + CEIL(p1*3.32)
s = CEIL(ABS(q1*3.32)) * SIGN(q1)
Division
Precision
p = M
q = M-p1
+q1-u
Attributes
of the
Result for
Exponentiation
FLOAT BINARY (p)
(unless special case
B applies)
p = MAX(p1,
CEIL(p2*3.32))
t = 1 + CEIL(p2*3.32)
u = CEIL(ABS(q2*3.32)) * SIGN(q2)
v = CEIL(p2/3.32)
w = CEIL(p1/3.32)
Notes:
The scaling factor must be in the range -128 through +127.
1. Special cases of exponentiation are described in Table 18 on page 62.
2. For a table of CEIL(N*3.32) values, see Table 22 on page 76.
3. The bounds of the precision p for FIXED BINARY are determined by the FIXEDBIN suboption and for FIXED
DECIMAL by the FIXEDDEC suboption of the LIMITS compiler option. The LIMITS option has no effect on the
bounds of the scaling factor q.
Consider the expression:
A * B + C
The operation A * B is performed first, to give an intermediate result. Then the
value of the expression is obtained by performing the operation (intermediate
result) + C.
PL/I gives the intermediate result attributes the same way it gives attributes to any
variable. The attributes of the result are derived from the attributes of the two
operands (or the single operand in the case of a prefix operation) and the operator
involved. The way the attributes of the result are derived is further explained
under “Targets” on page 52.
The ADD, SUBTRACT, MULTIPLY, and DIVIDE built-in functions allow you to
override the implementation precision rules for addition, subtraction,
multiplication, and division operations.
FIXED division:
FIXED division can result in overflows or truncation. For example, the result of
evaluating the expression:
25+1/3
is undefined and the FIXEDOVERFLOW condition is raised because FIXED
division results in a value of maximum implementation defined precision.
For the following expression, however:
25+01/3
Chapter 3. Expressions and references
61
Results of arithmetic operations
The result is 25.3333333333333 (when the maximum precision is 15) because
constants have the precision with which they are written. The results of the two
evaluations are reached as shown in Table 17:
Table 17. Comparison of FIXED division and constant expressions
Item
Precision
Result
1
3
1/3
25
25+1/3
(1,0)
(1,0)
(15,14)
(2,0)
(15,14)
1
3
0.33333333333333
25
undefined
(truncation on left;
FIXEDOVERFLOW is raised
when the maximum
precision is 15)
01
3
01/3
25
25+01/3
(2,0)
(1,0)
(15,13)
(2,0)
(15,13)
01
3
00.3333333333333
25
25.3333333333333
The PRECISION built-in function can also be used. For example:
25+prec(1/3,15,13)
Note: Named constants are recommended for situations that require exact
precisions.
Using exponentiation
The following table describes how exponentiation is handled in PL/I.
Table 18. Special cases for exponentiation
Case
First Operand
Second Operand
Attributes of Result
A
FIXED DECIMAL
(p1,q1)
Integer with
value n
FIXED DECIMAL (p,q)
(provided p <= N)
where p = (p1 + 1)*n-1
and q = q1*n
B
FIXED BINARY
(p1,q1)
Integer with
value n
FIXED BINARY (p,q)
(provided p <= M)
where p = (p1 + 1)*n-1
and q = q1*n
C
FLOAT (p1)
FIXED (p2,0)
FLOAT (p1) with
base of first operand
Special casesof x**y in real/complex modes:
Real mode:
Complex mode:
If x=0 and y>0,
result is 0. If x=0, and real part of y>0 and imaginary part of y=0, result is 0.
If x=0 and y<=0,
ERROR condition is raised. If x=0 and real part of y<=0 or imaginary part of y
¬=0, ERROR condition is raised.
If x<0 and y not FIXED (p,0),
ERROR condition is raised. If x¬=0 and real and imaginary parts of y=0, result is
1.
62
Enterprise PL/I for z/OS Language Reference
Bit operations
Bit operations
A bit operation is specified by combining operands with one of the following
logical operators:
¬
&
|
The not/exclusive-or symbol (¬), can be used as a prefix or infix operator. The and
(&) symbol and the or (|) symbol, can be used as infix operators only. (The
operators have the same function as in Boolean algebra.)
Operands of a bit operation are converted, if necessary, to bit strings before the
operation is performed. If the operands of an infix operation do not have the same
length, the shorter is padded on the right with '0'B.
The result of a bit operation is a bit string equal in length to the length of the
operands.
Bit operations are performed on a bit-by-bit basis. Table 19 illustrates the result for
each bit position for each of the operators. Table 20 shows some examples of bit
operations.
Table 19. Bit operations
A
B
¬A
¬B
A&B
A|B
A¬B
1
1
0
0
1
1
0
1
0
0
1
0
1
1
0
1
1
0
0
1
1
0
0
1
1
0
0
0
Table 20. Bit operation examples
For these operands and values
This operation
Yields this result
A
B
C
D
¬ A
'101000'B
¬ C
'001'B
C & B
'110000'B
A | B
'111111'B
A ¬ B
''101000''B
A ¬ C
'100111'B
C | B
'111111'B
A | (¬C)
'011111'B
¬((¬C)|(¬B))
'110111'B
SUBSTR(A,1,1)|(D=5)
'1'B
=
=
=
=
'010111'B
'111111'B
'110'B
5
BOOL built-in function
In addition to the not, exclusive-or, and, and or operations using the operators ¬, &,
and |, Boolean operations can be performed using the BOOL built-in function
discussed in “BOOL” on page 425.
Comparison operations
A comparison operation is specified by combining operands with one of the
following infix operators:
Chapter 3. Expressions and references
63
Comparison operations
v
v
v
v
v
<
¬<
<=
=
¬= or <>
v >=
v >
v ¬>
The result of a comparison operation is always a bit string of length 1. The value is
'1'B if the relationship is true, or '0'B if the relationship is false.
Comparisons are defined as follows:
Algebraic
is the comparison of signed arithmetic values in coded arithmetic form. If
operands differ in base, scale, precision, or mode, they are converted in a
manner analogous to arithmetic operation conversions. Numeric character
data is converted to coded arithmetic before comparison. Only the
operators =, ¬=, and <> are valid for comparison of operands that are
complex numbers.
Character
is a left-to-right, character-by-character comparison of characters according
to the binary value of the bytes.
Bit
is a left-to-right, bit-by-bit comparison of binary digits.
Graphic
is a left-to-right, symbol-by-symbol comparison of DBCS characters. The
comparison is based on the binary values of the DBCS characters.
Widechar
is a left-to-right, widechar-by-widechar comparison of characters according
to the binary value of the byte-pairs.
Ordinal data
is a comparison of ordinals of the same type using relational operators.
Pointer and offset data
is a comparison of pointer and offset values containing any relational
operators. However, the only conversion that can take place is offset to
pointer.
Program-control data
is a comparison of the internal coded forms of the operands. Only the
comparison operators =, ¬=, and <> are allowed; area variables cannot be
compared. No type conversion can take place; all type differences between
operands for program-control data comparisons are in error.
Comparisons are equal for the following operands:
Entry
In a comparison operation, it is not an error to specify an entry
variable whose value is an entry point of an inactive block. Entry
names on the same PROCEDURE or ENTRY statement do not
compare equal.
Format
Format labels on the same FORMAT statement compare equal.
64
Enterprise PL/I for z/OS Language Reference
Comparison operations
File
If the operands represent file values, all of whose parts are equal.
Label
Labels on the same statement compare equal. In a comparison
operation, it is not an error to specify a label variable whose value
is a label constant used in a block that is no longer active.
The label on a compound statement does not compare equal with
that on any label contained in the body of the compound
statement.
If the operands of a computational data comparison have data types that are
appropriate to different types of comparison, the operand of the lower precedence
is converted to conform to the comparison type of the other. The precedence of
comparison types is (1) algebraic (highest), (2) widechar, (3) graphic, (4) character,
(5) bit. For example, if a bit string is compared with a fixed decimal value, the bit
string is converted to fixed binary for algebraic comparison with the decimal value.
The decimal value is also converted to fixed binary.
In the comparison of strings of unequal lengths, the shorter string is padded on the
right. This padding consists of:
v Blanks in a character comparison
v '0'B in a bit comparison
v A graphic (DBCS) blank in a graphic comparison.
v A widechar blank ('0020'wx) in a widechar comparison.
The following example shows a comparison operation in an IF statement:
if A = B
then action-if-true;
else action-if-false;
The evaluation of the expression A = B yields either ’1’B, for true, or ’0’B, for
false.
In the following assignment statement:
X = A <= B;
the value ’1’B is assigned to X if A is less than B; otherwise, the value ’0’B is
assigned.
In the following assignment statement:
X = A = B;
the first equal symbol is the assignment symbol; the second equal symbol is the
comparison operator. The value ’1’B is assigned to X if A is equal to B; otherwise,
the value ’0’B is assigned.
An example of comparisons in an arithmetic expression is:
(X<0)*A + (0<=X & X<=100)*B + (100<X)*C
The value of the expression is A, B, or C and is determined by the value of X.
Concatenation operations
A concatenation operation is specified by combining operands with the
concatenation infix operator:
{
Chapter 3. Expressions and references
65
Concatenation operations
Concatenation signifies that the operands are to be joined in such a way that the
last character, bit, graphic or widechar of the operand to the left immediately
precedes the first character, bit, graphic or widechar of the operand to the right,
with nothing intervening.
The concatenation operator can cause conversion to a string type because
concatenation can be performed only upon strings—either character, bit, graphic or
widechar. The results differ according to the setting of the RULES compiler option:
Results under RULES(IBM)
When you specify RULES(IBM), the concatenation operator behaves as follows:
v If either operand is widechar, the result is widechar.
v Else, if either operand is graphic, the result is graphic.
v Else, if either operand is bit or binary, the result is bit.
v Otherwise the result is character.
For example:
dcl B bin(4) initial(4),
C bit(1) initial(’1’b);
put skip list (B { C);
/*
Produces ’01001’
not ’bbb41’
*/
Results under RULES(ANS)
When you specify RULES(ANS), the concatenation operator behaves as follows:
v If either operand is widechar, the result is widechar.
v Else, if either operand is graphic, the result is graphic.
v Else, if both operands are bit, the result is bit.
v Otherwise the result is character.
Consider this example:
dcl B bin(4) initial(4),
C bit(1) initial(’1’b);
put skip list (B { C);
/*
Produces ’bbb41’, not ’01001’
*/
The result of a concatenation operation is a string whose length is equal to the sum
of the lengths of the two operands, and whose type (that is, character, bit, graphic
or widechar) is the same as that of the two operands.
If an operand requires conversion for concatenation, the result depends upon the
length of the string to which the operand is converted.
For these operands and values
This operation
Yields this result
A
B
C
D
A { B
'010111_101'B
A { A { B
'010111_010111_101'B
C { D
'xy,Zaa/BB'
D { C
'aa/BBxy,Z'
B { D
'101aa/BB'
=
=
=
=
'010111'B
'101'B
'xy,Z'
'aa/BB'
In the last example, the bit string '101'B is converted to the character string '101'
before the concatenation is performed. The result is a character string.
66
Enterprise PL/I for z/OS Language Reference
Combinations of operations
Combinations of operations
Different types of operations can be combined within the same operational
expression. Any combination can be used.
For example:
declare Result bit(3),
A fixed decimal(1),
B fixed binary (3),
C character(2), D bit(4);
Result = A + B < C & D;
Each operation within the expression is evaluated according to the rules for that
kind of operation, with necessary data conversions taking place before the
operation is performed, as follows:
v
v
v
v
The
The
The
The
and
decimal value of A is converted to binary base.
binary addition is performed, adding A and B.
binary result is compared with the converted binary value of C.
bit result of the comparison is extended to the length of the bit variable D,
the & operation is performed.
v The result of the & operation, a bit string of length 4, is assigned to Result
without conversion, but with truncation on the right.
The expression in this example is evaluated operation-by-operation, from left to
right. The order of evaluation, however, depends upon the priority of the operators
appearing in the expression.
Priority of operators
The priority of the operators in the evaluation of expressions is shown in Table 21.
Table 21. Priority of operations and guide to conversions
Priority
1
Operator
Type of Operation
Remarks
**
Arithmetic
Result is in coded arithmetic form
prefix +, -
Arithmetic
No conversion is required if operand is in coded
arithmetic form
Operand is converted to FIXED DECIMAL if it is
a CHARACTER string or numeric character
(PICTURE) representation of a fixed-point decimal
number
Operand is converted to FLOAT DECIMAL if it is
a numeric character (PICTURE) representation of
a floating-point decimal number
Operand is converted to FIXED BINARY if it is a
BIT string
prefix ¬
Bit string
All non-BIT data converted to BIT
2
*, /
Arithmetic
Result is in coded arithmetic form
3
infix +, -
Arithmetic
Result is in coded arithmetic form
4
{
Concatenation
Refer to “Results under RULES(ANS)” on page 66
and “Results under RULES(IBM)” on page 66
5
<, ¬<, <=, =, ¬= or <>,
>=, >, ¬>
Comparison
Result is always either '1'B or '0'B
6
&
Bit string
All non-BIT data converted to BIT
Chapter 3. Expressions and references
67
Priority of operators
Table 21. Priority of operations and guide to conversions (continued)
Priority
7
Operator
Type of Operation
Remarks
│
Bit string
All non-BIT data converted to BIT
infix ¬
Bit string
All non-BIT data converted to BIT
Note:
1. The operators are listed in order of priority, group 1 having the highest priority and group 7 the lowest. All
operators in the same priority group have the same priority. For example, the exponentiation operator ** has the
same priority as the prefix + and prefix - operators and the not operator ¬.
2. For priority group 1, if two or more operators appear in an expression, the order of priority is right to left within
the expression; that is, the rightmost exponentiation or prefix operator has the highest priority, the next rightmost
the next highest, and so on. For all other priority groups, if two or more operators in the same priority group
appear in an expression, their order or priority is their order left to right within the expression.
The order of evaluation of the expression
A + B < C & D
is the same as if the elements of the expression were parenthesized as
(((A + B) < C) & D)
The order of evaluation (and, consequently, the result) of an expression can be
changed through the use of parentheses. Expressions enclosed in parentheses are
evaluated first, to a single value, before they are considered in relation to
surrounding operators.
The above expression, for example, might be changed as follows:
(A + B) < (C & D)
The value of A converts to fixed-point binary, and the addition is performed,
yielding a fixed-point binary result (result_1). The value of C converts to a bit
string (if valid for such conversion) and the and operation is performed. At this
point, the expression is reduced to:
Result_1 < Result_2
Result_2 is converted to binary, and the algebraic comparison is performed,
yielding a bit string of length 1 for the entire expression.
The priority of operators is defined only within operands (or sub-operands).
Consider the following example:
A + (B < C) & (D { E ** F)
In this case, PL/I specifies only that the exponentiation occurs before the
concatenation. It does not specify the order of the evaluation of (D{E ** F) in
relation to the evaluation of the other operand (A + (B < C)).
Any operational expression (except a prefix expression) must eventually be
reduced to a single infix operation. The operands and operator of that operation
determine the attributes of the result of the entire expression. In the following
example, the & operator is the operator of the final infix operation.
A + B < C & D
The result of the evaluation is a bit string of length 4.
68
Enterprise PL/I for z/OS Language Reference
Priority of operators
In the next example, because of the use of parentheses, the operator of the final
infix operation is the comparison operator:
(A + B) < (C & D)
The evaluation yields a bit string of length 1.
Array expressions
Array expressions are allowed as:
v the source in an assignment or in multiple assignments
v the argument to the ALL, ANY, POLY, PROD or SUM built-in functions
v an argument to a user procedure and function, as long as the associated
parameter is not a string of unknown length
v an item in the data-lists of PUT LIST and PUT EDIT statements
Evaluation of an array expression yields an array result. All operations performed
on arrays are performed element-by-element, in row-major order. Therefore, all
arrays referred to in an array expression must have the same number of
dimensions, and each dimension must be of identical bounds.
Array expressions can include operators (both prefix and infix), element variables,
and constants. The rules for combining operations and for data conversion of
operands are the same as for element operations.
Prefix operators and arrays
The operation of a prefix operator on an array produces an array of identical
bounds. Each element of this array is the result of the operation performed on each
element of the original array. For example:
If A is the array
then -A is the array
5
1
6
3 -9
2
7
3 -4
-5 -3
9
-1 -2 -7
-6 -3
4
Infix operators and arrays
Infix operations that include an array variable as one operand can have an element
or another array as the other operand.
Array-and-element operations
The result of an expression with an element, an array, and an infix operator is an
array with bounds identical to the original array. Each element of the resulting
array is the result of the operation between each corresponding element of the
original array and the single element. For example:
If A is the array
5 10
12 11
8
3
then A*3 is the array
15 30
36 33
24
9
and 9 > A is the array of
bit strings of length 1
1
0
0
0
1
1
The element of an array-element operation can be an element of the same array.
Consider the following assignment statement:
Chapter 3. Expressions and references
69
Infix operators and arrays
A = A * A(1,2);
Again, using the above values for A, the newly assigned value of A would be:
50
1200
100
1100
800
300
That is, the value of A(1,2) is fetched again.
Array-and-array operations
If the two operands of an infix operator are arrays, the arrays must have the same
number of dimensions, and corresponding dimensions must have identical lower
bounds and identical upper bounds. The result is an array with bounds identical to
those of the original arrays; the operation is performed upon the corresponding
elements of the two original arrays. For example:
If A is the array
2
6
4
4
1
8
3
7
2
and if B is the array
1
8
6
5
3
3
7
4
1
then A+B is the array
3
9 10
14
4 11
10 11
3
and A*B is the array
2 20 21
48
3 28
24 24
2
and A>B is the array of
bit strings of length 1
1
0
0
0
0
1
0
1
1
Structure expressions
Structure expressions, unlike structure references, are allowed only in assignments
and as arguments to procedures or functions, as long as the associated parameter
has constant extents, namely, constant string lengths, area sizes, and array bounds.
All structure variables appearing in a structure expression must have identical
structuring, which means:
v The structures must have the same minor structuring and the same number of
contained elements and arrays.
v The positioning of the elements and arrays within the structure (and within the
minor structures, if any) must be the same.
v Arrays in corresponding positions must have identical bounds.
Restricted expressions
Where PL/I requires a (possibly signed) constant, a restricted expression can be
used. A restricted expression is an expression whose value is calculated at compile
time and used as a constant. For example, you can use expressions to define
constants required for:
v Extents in static, parameter, and based declarations
v Extents in entry descriptions
v Values and iteration factors to be used in static initialization
A restricted expression is identical to a normal expression but requires that each
operand be:
70
Enterprise PL/I for z/OS Language Reference
Restricted expressions
v A constant or a named constant. A named constant must be declared before it is
used.
v A built-in function applied to a restricted expression(s), where the built-in
function is from the following categories:
– String-handling
– Arithmetic (except RANDOM)
– Mathematical
– Floating-point inquiry
– Floating-point manipulation
– Integer manipulation
– Precision-handling
– Array-handling functions DIMENSION, LBOUND, and HBOUND
– Storage-control functions BINARYVALUE, LENGTH, NULL, OFFSETVALUE,
POINTERVALUE, SIZE, STORAGE, and SYSNULL
v Type functions BIND, CAST, FIRST, LAST, RESPEC, SIZE, and VALUE
Examples
dcl Max_names fixed bin value (1000),
Name_size fixed bin value (30),
Addr_size fixed bin value (20),
Addr_lines fixed bin value (4);
dcl 1 Name_addr(Max_names),
2 Name char(Name_size),
2 * union,
3 Address char(Addr_lines*Addr_size), /* address
*/
3 addr(Addr_lines) char(Addr_size),
2 * char(0);
dcl One_Name_addr char(size(Name_addr(1)));
/* 1 name/addr*/
dcl Two_Name_addr char(length(One_Name_addr)
*2);
/* 2 name/addrs */
dcl Name_or_addr char(max(Name_size,Addr_size)) based;
dcl Ar(10) pointer;
dcl Ex
entry( dim(lbound(Ar):hbound(Ar)) pointer);
dcl Identical_to_Ar( lbound(Ar):hbound(Ar) ) pointer;
If you change the value of any of the named constants in the example, all of the
dependent declarations are automatically reevaluated.
Chapter 3. Expressions and references
71
72
Enterprise PL/I for z/OS Language Reference
Chapter 4. Data conversion
Built-in functions for computational
Converting string lengths. . . .
Converting arithmetic precision. .
Converting mode . . . . . .
Converting other data attributes .
Source-to-target rules . . . . .
data conversion
. . . . . .
. . . . . .
. . . . . .
. . . . . .
. . . . . .
74
75
76
76
76
77
Examples . . . . . . . .
DECIMAL FIXED to BINARY
fractions . . . . . . .
Arithmetic to bit string . .
Arithmetic to character . .
A conversion error . . . .
. . . .
FIXED with
. . . .
. . . .
. . . .
. . . .
.
.
. 85
.
.
.
.
.
.
.
.
.
.
.
.
85
85
86
86
This chapter discusses data conversions for computational data. PL/I converts data
when a data item with a set of attributes is assigned to another data item with a
different set of attributes. In this chapter, source refers to the data item to be
converted, and target refers to the attributes to which the source is converted.
Topics discussed for these data conversions include:
Built-in functions
String lengths
Arithmetic precision
Mode
Source-to-target rules
Examples of data conversion are included at the end of the chapter.
Data conversion for locator data is discussed in “Locator conversion” on page 246.
Conversion of the value of a computational data item can change its internal
representation, precision or mode (for arithmetic values), or length (for string
values). The tables that follow summarize the circumstances that can cause
conversion to other attributes.
Case
Target Attributes
Assignment
Attributes of variable on left of assignment
symbol
Determined by rules for evaluation of
expressions
Attributes of receiving field
As determined by format list if stream is
edit-directed, otherwise character-string
Attributes of corresponding parameter
Depends on the function or pseudovariable
Operand in an expression
Stream input (GET statement)
Stream output (PUT statement)
Argument to PROCEDURE or ENTRY
Argument to built-in function or
pseudovariable
INITIAL attribute
RETURN statement expression
DO statement, BY, TO, or REPEAT option
Other attributes of variable being initialized
Attributes specified in PROCEDURE
statement
Attributes of control variable
The following can cause conversion to character values:
Statement
Option
DISPLAY
Record I/O
OPEN
KEYFROMKEY
TITLE
© Copyright IBM Corp. 1999, 2012
73
Data conversion
The following can cause conversion to a BINARY value:
Statement
Option/Attribute/Reference
DECLARE, ALLOCATE, DEFAULT
length, size, dimension, bound, repetition
factor
milliseconds
iteration factor w, d, s, p
DELAY
FORMAT (and format items in GET and
PUT)
OPEN
I/O
Most statements
LINESIZE, PAGESIZE
SKIP, LINE, IGNORE
subscript
All attributes for source and target data items (except string length) must be
specified at compile time. Conversion can raise one of the following conditions:
CONVERSION, OVERFLOW, SIZE, or STRINGSIZE. (Refer to Chapter 16,
“Conditions,” on page 357.)
Constants can be converted at compile time as well as at run time. In all cases, the
conversions are as described here.
In the discussions of conversions that follow:
v M is the maximum precision for FIXED BINARY. This is the value M2 from the
compiler option LIMITS(FIXEDBIN(M1,M2)).
v N is the maximum precision for FIXED DECIMAL. This is the value N2 from the
compiler option LIMITS(FIXEDDEC(N1,N2)).
More than one conversion might be required for a particular operation. The
implementation does not necessarily go through more than one. To understand the
conversion rules, it is convenient to consider them separately, for example:
dcl A fixed dec(3,2) init(1.23);
dcl B fixed bin(15,5);
B = A;
In this example, the decimal representation of 1.23 is first converted to a binary
(11,7) value, as 1.0011101B. Then precision conversion is performed, resulting in a
binary (15,5) value of 1.00111B.
Additional examples of conversion are provided at the end of this chapter.
Built-in functions for computational data conversion
Conversions can take place during expression evaluation, I/O GET and PUT
operations, and assignment operations, and between arguments and parameters.
Conversions can also be initiated with the following built-in functions:
BINARY
BIT
CHAR
COMPLEX
DECIMAL
FIXED
FLOAT
GRAPHIC
IMAG
PRECISION
REAL
SIGNED
UNSIGNED
WIDECHAR
Each is discussed in Chapter 18, “Built-in functions, pseudovariables, and
subroutines,” on page 383.
74
Enterprise PL/I for z/OS Language Reference
Built-in functions for computational data conversion
Each function returns a value with the attribute specified by the function name,
performing any required conversions.
With the exception of the conversions performed by the COMPLEX, GRAPHIC,
and IMAG built-in functions, assignment to a PL/I variable having the required
attributes can achieve the conversions performed by these built-in functions.
However, you might find it easier and clearer to use a built-in function than to
create a variable solely to carry out a conversion.
Converting string lengths
The source string is assigned to the target string from left to right. If the source
string is longer than the target, excess characters, bits, graphics or widechars on
the right are ignored, and the STRINGSIZE condition is raised. For fixed-length
targets, if the target is longer than the source, the target is padded on the right. If
STRINGSIZE is disabled, and the length of the source and/or the target is
determined at run time, and the target is too short to contain the source,
unpredictable results can occur.
Note: If you use SUBSTR with variables as the parameters, and the variables
specify a string not contained in the target, unpredictable results can occur if
the STRINGRANGE condition is not enabled.
Character strings are padded with blanks, bit strings with '0'B, graphic strings with
DBCS blanks, and widechar strings with widechar blanks.
declare Subject char(10);
Subject = ’Transformations’;
'Transformations' has 15 characters, therefore, when PL/I assigns the string to
Subject, it truncates five characters from the right end of the string. This is
equivalent to executing the following:
Subject = ’Transforma’;
The first two of the following statements assign equivalent values to Subject and
the last two assign equivalent values to Code:
Subject = ’Physics’;
Subject = ’Physics
’;
declare Code bit(10);
Code = ’110011’B;
Code = ’1100110000’B;
The following statements do not assign equivalent values to Subject:
Subject = ’110011’B;
Subject = ’1100110000’B;
When the first statement is executed, the bit constant on the right is first converted
to a character string and is then extended on the right with blank characters rather
than zero characters. This statement is equivalent to:
Subject = ’110011bbbb’;
The second of the two statements requires only a conversion from bit to character
type and is equivalent to:
Subject = ’1100110000’;
A string value is not extended with blank characters or zero bits when it is
assigned to a string variable that has the VARYING attribute. Instead, the length of
Chapter 4. Data conversion
75
Converting string lengths
the target string variable is set to the length of the assigned string. However,
truncation will occur if the length of the assigned string exceeds the maximum
length declared for the varying-length string variable.
Converting arithmetic precision
When an arithmetic value has the same data attributes (except for precision) as the
target, precision conversion is required.
For fixed-point data items, decimal or binary point alignment is maintained during
precision conversion. Therefore, padding or truncation can occur on the left or
right. If nonzero bits or digits on the left are lost, the SIZE condition is raised.
For floating-point data items, truncation on the right, or padding on the right with
zeros, can occur.
Converting mode
If a complex value is converted to a real value, the imaginary part is ignored. If a
real value is converted to a complex value, the imaginary part is zero.
Converting other data attributes
Source-to-target rules are given, following this section, for converting data items
with the following data attributes:
v Coded arithmetic:
FIXED BINARY
FIXED DECIMAL
FLOAT BINARY
FLOAT DECIMAL
v Arithmetic character PICTURE
v CHARACTER
v BIT
v GRAPHIC
v WIDECHAR
Changes in value can occur in converting between decimal representations and
binary representation. In converting between binary and decimal, the factor 3.32 is
used as follows:
v n decimal digits convert to CEIL (n*3.32) binary digits.
v n binary digits convert to CEIL (n/3.32) decimal digits.
A table of CEIL values is provided in Table 22 to calculate these conversions.
Table 22. CEIL (n*3.32) and CEIL (n/3.32) values
76
n
CEIL
(n*3.32)
n
CEIL
(n/3.32)
1
2
3
4
5
6
7
8
4
7
10
14
17
20
24
27
1-3
4-6
7-9
10-13
14-16
17-19
20-23
24-26
1
2
3
4
5
6
7
8
Enterprise PL/I for z/OS Language Reference
Converting other data attributes
Table 22. CEIL (n*3.32) and CEIL (n/3.32) values (continued)
n
CEIL
(n*3.32)
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
30
34
37
40
44
47
50
531
57
60
64
67
70
74
77
80
83
87
90
93
97
100
103
107
110
n
CEIL
(n/3.32)
27-29
9
30-33
10
34-36
11
37-39
12
40-43
13
44-46
14
47-49
15
50-53
16
54-56
17
57-59
18
60-63
19
64-66
20
67-69
21
70-73
22
74-76
23
77-79
24
80-83
25
84-86
26
87-89
27
90-92
28
93-96
29
97-99
30
100-102
31
103-106
32
107-109
33
110-112
34
113-116
35
Note 1: While ceil(16*3.32) = 54, the value 53 is used. If it were not, a float decimal(16),
when converted to binary, would have to be converted from long floating-point to extended
floating-point (because float binary(54) is represented as extended floating-point).
For fixed-point integer values, conversion does not change the value. For
fixed-point fractional values, the factor 3.32 provides only enough digits or bits so
that the converted value differs from the original value by less than 1 digit or bit
in the rightmost place.
For example, the decimal constant .1, with attributes FIXED DECIMAL (1,1),
converts to the binary value .0001B, converting 1/10 to 1/16. The decimal constant
.10, with attributes FIXED DECIMAL (2,2), converts to the binary value .0001100B,
converting 10/100 to 12/128.
Source-to-target rules
Target: Coded Arithmetic
Source:
FIXED BINARY, FIXED DECIMAL,
Chapter 4. Data conversion
77
Source-to-target rules
FLOAT BINARY, and FLOAT DECIMAL
These are all coded arithmetic data. Rules for conversion between them are
given under each data type taken as a target.
Arithmetic character PICTURE
Data first converts to decimal with scale and precision determined by the
corresponding PICTURE specification. The decimal value then converts to the
base, scale, mode, and precision of the target. See the specific target types of
coded arithmetic data using FIXED DECIMAL or FLOAT DECIMAL as the
source.
CHARACTER
The source string must represent a valid arithmetic constant or complex
expression; otherwise, the CONVERSION condition is raised. The constant can
be preceded by a sign and can be surrounded by blanks. The constant cannot
contain blanks between the sign and the constant, or between the end of the
real part and the sign preceding the imaginary part of a complex expression.
The constant has base, scale, mode, and precision attributes. It converts to the
attributes of the target when they are independent of the source attributes, as
in the case of assignment. See the specific target types of coded arithmetic data
using the attributes of the constant as the source.
If an intermediate result is necessary, as in evaluation of an operational
expression, the attributes of the intermediate result are the same as if a decimal
fixed-point value of precision (N,0) had appeared in place of the string. (This
allows the compiler to generate code to handle all cases, regardless of the
attributes of the contained constant.) Consequently, any fractional portion of
the constant might be lost. See the specific target types of coded arithmetic
data using FIXED DECIMAL as the source.
It is possible that during the initial conversion of the character data item to an
intermediate fixed decimal number, the value might exceed the default size of
the intermediate result. If this occurs, the SIZE condition is raised if it is
enabled.
If a character string representing a complex number is assigned to a real target,
the complex part of the string is not checked for valid arithmetic characters
and CONVERSION cannot be raised, since only the real part of the string is
assigned to the target.
If the source is a null string or a string of one or more blanks, the target will
be assigned the value zero. The CONVERSION condition will not be raised.
BIT
If the conversion occurs during evaluation of an operational expression, the
source bit string is converted to an unsigned value that is FIXED
BINARY(M,0). See the specific target types of coded arithmetic data using
FIXED BINARY as the source.
If the source string is longer than the allowable precision, bits on the left are
ignored. If nonzero bits are lost, the SIZE condition is raised.
A null string gives the value zero.
GRAPHIC
Graphic variables and strings are converted to CHARACTER, and then follow
the rules for character source described
WIDECHAR
Widechar variables and strings are converted to CHARACTER, and then
follow the rules for character source described in CHARACTER.
78
Enterprise PL/I for z/OS Language Reference
Source-to-target rules
Target: FIXED BINARY (p2,q2)
Source:
FIXED DECIMAL (p1,q1)
The precision of the result is p2 = min(M,1+CEIL(p1*3.32)) and
q2=CEIL(ABS(q1*3.32))*SIGN(q1).
FLOAT BINARY (p1)
The precision conversion is as described under “Converting arithmetic
precision” on page 76 with p1 as declared or indicated and q1 as indicated by
the binary point position and modified by the value of the exponent.
FLOAT DECIMAL (p1)
The precision conversion is the same as for FIXED DECIMAL to FIXED
BINARY with p1 as declared or indicated and q1 as indicated by the decimal
point position and modified by the value of the exponent.
Arithmetic character PICTURE
See Target: Coded Arithmetic.
CHARACTER
See Target: Coded Arithmetic.
BIT
See Target: Coded Arithmetic.
GRAPHIC
See Target: Coded Arithmetic.
WIDECHAR
See Target: Coded Arithmetic.
Target: FIXED DECIMAL (p2,q2)
Source:
FIXED BINARY (p1,q1)
The precision of the result is p2=1+CEIL(p1/3.32) and q2=CEIL(ABS(q1/
3.32))*SIGN(q1).
FLOAT BINARY (p1)
The precision conversion is the same as for FIXED BINARY to FIXED
DECIMAL with p1 as declared or indicated and q1 as indicated by the binary
point position and modified by the value of the exponent.
FLOAT DECIMAL (p1)
The precision conversion is as described under “Converting arithmetic
precision” on page 76 with p1 as declared or indicated and q1 as indicated by
the decimal point position and modified by the value of the exponent.
Arithmetic character PICTURE
See Target: Coded Arithmetic.
CHARACTER
See Target: Coded Arithmetic.
Chapter 4. Data conversion
79
Source-to-target rules
BIT
See Target: Coded Arithmetic.
GRAPHIC
See Target: Coded Arithmetic.
WIDECHAR
See Target: Coded Arithmetic.
Target: FLOAT BINARY (p2)
Source:
FIXED BINARY (p1,q1)
The precision of the result is p2=p1. The exponent indicates any fractional part
of the value.
FIXED DECIMAL (p1,q1)
The precision of the result is p2=CEIL(p1*3.32). The exponent indicates any
fractional part of the value.
FLOAT DECIMAL (p1)
The precision of the result is p2=CEIL(p1*3.32).
Arithmetic character PICTURE
See Target: Coded Arithmetic.
CHARACTER
See Target: Coded Arithmetic.
BIT
See Target: Coded Arithmetic.
GRAPHIC
See Target: Coded Arithmetic.
WIDECHAR
See Target: Coded Arithmetic.
Target: FLOAT DECIMAL (p2)
Source:
FIXED BINARY (p1,q1)
The precision of the result is p2=CEIL(p1/3.32). The exponent indicates any
fractional part of the value.
FIXED DECIMAL (p1,q1)
The precision of the result is p2=p1. The exponent indicates any fractional part
of the value.
FLOAT BINARY (p1)
The precision of the result is p2=CEIL(p1/3.32).
Arithmetic character PICTURE
See Target: Coded Arithmetic.
CHARACTER
See Target: Coded Arithmetic.
80
Enterprise PL/I for z/OS Language Reference
Source-to-target rules
BIT
See Target: Coded Arithmetic.
GRAPHIC
See Target: Coded Arithmetic.
WIDECHAR
See Target: Coded Arithmetic.
Target: Arithmetic character PICTURE
The arithmetic character PICTURE data item is the character representation of a
decimal fixed-point or floating-point value. The following descriptions for source
to arithmetic character PICTURE target show those target attributes that allow
assignment without loss of leftmost or rightmost digits.
Source:
FIXED BINARY (p1,q1)
The target must imply:
fixed decimal (1+x+q-y,q) or
float decimal (x)
where x>=CEIL(p1/3.32), y=CEIL(q1/3.32), and q>=y.
FIXED DECIMAL (p1,q1)
The target must imply:
fixed decimal (x+q-q1,q) or
float decimal (x)
where x>=p1 and q>=q1.
FLOAT BINARY (p1)
The target must imply:
fixed decimal (p,q) or
float decimal (p)
where p>=CEIL(p1/3.32) and the values of p and q take account of the range
of values that can be held by the exponent of the source.
FLOAT DECIMAL (p1)
The target must imply:
fixed decimal (p,q) or
float decimal (p)
where p>= p1 and the values of p and q take account of the range of values
that can be held by the exponent of the source.
Arithmetic character PICTURE
The implied attributes of the source will be either FIXED DECIMAL or FLOAT
DECIMAL. See the respective entries for this target.
CHARACTER
See Target: Coded Arithmetic.
BIT(n)
The target must imply:
Chapter 4. Data conversion
81
Source-to-target rules
fixed decimal (1+x+q,q) or
float decimal (x)
where x>=ceil(n/3.32) and q>=0.
GRAPHIC
See Target: Coded Arithmetic.
WIDECHAR
See Target: Coded Arithmetic.
Target: CHARACTER
Source:
FIXED BINARY, FIXED DECIMAL,
FLOAT BINARY, and FLOAT DECIMAL
The coded arithmetic value is converted to a decimal constant (preceded by a
minus sign if it is negative) as described below. The constant is inserted into an
intermediate character string whose length is derived from the attributes of the
source. The intermediate string is assigned to the target according to the rules
for string assignment.
The rules for coded-arithmetic-to-character-string conversion are also used for
list-directed and data-directed output, and for evaluating keys (even for
REGIONAL files).
FIXED BINARY (p1,q1)
The binary precision (p1,q1) is first converted to the equivalent decimal
precision (p,q), where p=1+CEIL(p1/3.32) and q=CEIL(ABS(q1/
3.32))*SIGN(q1). Thereafter, the rules are the same as for FIXED DECIMAL to
CHARACTER.
FIXED DECIMAL (p1,q1)
If p1>=q1>=0 then:
v The constant is right adjusted in a field of width p1+3. (The 3 is necessary to
allow for the possibility of a minus sign, a decimal or binary point, and a
leading zero before the point.)
v Leading zeros are replaced by blanks, except for a single zero that
immediately precedes the decimal point of a fractional number. A single zero
also remains when the value of the source is zero.
v A minus sign precedes the first digit of a negative number. A positive value
is unsigned.
v If q1=0, no decimal point appears; if q1>0, a decimal point appears and the
constant has q fractional digits.
If p1<q1 or q1<0, a scaling factor appends to the right of the constant; the
constant is an optionally-signed integer. The scaling factor appears even if the
value of the item is zero and has the following syntax:
F{+|-}nn
where {+|-}nn has the value of -q1.
The length of the intermediate string is p1+k+3, where k is the number of
digits necessary to hold the value of q1 (not including the sign or the letter F).
82
Enterprise PL/I for z/OS Language Reference
Source-to-target rules
If the arithmetic value is complex, the intermediate string consists of the
imaginary part concatenated to the real part. The left-hand, or real, part is
generated as a real source. The right-hand, or imaginary, part is always signed,
and it has the letter I appended. The generated string is a complex expression
with no blanks between its elements. The length of the intermediate string is:
2*p1+7
for p1>=q1>=0
2*(p1+k)+7 for p1<q1 or q1<0
The following examples show the intermediate strings that are generated from
several real and complex fixed-point decimal values:
Precision
(5,0)
(4,1)
(4,-3)
(2,1)
Value
2947
-121.7
-3279000
1.2+0.3I
String
’bbbb2947’
’b-121.7’
’-3279F+3’
’bbb1.2+0.3I’
FLOAT BINARY (p1)
The floating-point binary precision (p1) first converts to the equivalent
floating-point decimal precision (p), where p=CEIL(p1/3.32). Thereafter, the
rules are the same as for FLOAT DECIMAL to CHARACTER.
FLOAT DECIMAL (p1)
A decimal floating-point source converts as if it were transmitted by an
E-format item of the form E(w,d,s) where:
w, the length of the intermediate string, is p1+8.
d, the number of fractional digits, is p1-1.
s, the number of significant digits, is p1.
If the arithmetic value is complex, the intermediate string consists of the
imaginary part concatenated to the real part. The left-hand, or real, part is
generated as a real source. The right-hand, or imaginary, part is always signed,
and it has the letter I appended. The generated string is a complex expression
with no blanks between its elements. The length of the intermediate string is
2*p+17.
The following examples show the intermediate strings that are generated from
several real and complex floating-point decimal values:
Precision
Value
String
(5)
(5)
(3)
(5)
1735*10**5
-.001663
1
17.3+1.5I
’b1.7350E+0008’
’-1.6630E-0003’
’b1.00E+0000’
’b1.7300E+0001+1.5000E+0000I’
Arithmetic character PICTURE
A real arithmetic character field is interpreted as a character string and
assigned to the target string according to the rules for converting string
lengths. If the arithmetic character field is complex, the real and imaginary
parts are concatenated before assignment to the target string. Insertion
characters are included in the target string.
BIT
Bit 0 becomes the character 0 and bit 1 becomes the character 1. A null bit
string becomes a null character string. The generated character string is
assigned to the target string according to the rules for converting string
lengths.
Chapter 4. Data conversion
83
Source-to-target rules
GRAPHIC
DBCS to SBCS conversion is possible only if there is a corresponding SBCS
character. Otherwise, the CONVERSION condition is raised.
WIDECHAR
Conversion from widechar to character is performed only if all the widechars
have a value less than '0080'wx. Otherwise, the CONVERSION condition is
raised.
Target: BIT
Source:
FIXED BINARY, FIXED DECIMAL,
FLOAT BINARY, and FLOAT DECIMAL
If necessary, the arithmetic value converts to binary and both the sign and any
fractional part are ignored. (If the arithmetic value is complex, the imaginary
part is also ignored.) The resulting binary value is treated as a bit string. It is
assigned to the target according to the rules for string assignments.
FIXED BINARY (p1,q1)
The length of the intermediate bit string is given by:
min(M,(p1-q1))
If (p1-q1) is negative or zero, the result is a null bit string.
The following examples show the intermediate strings that are generated from
several fixed-point binary values:
Precision
Value
String
(1)
(3)
(4,2)
1
-3
1.25
’1’B
’011’B
’01’B
FIXED DECIMAL (p1,q1)
The length of the intermediate bit string is given by:
min(M,CEIL((p1-q1)*3.32))
If (p1-q1) is negative or zero, the result is a null bit string.
The following examples show the intermediate strings that are generated from
several fixed-point decimal values:
Precision
Value
(1)
(2,1)
1
1.1
String
’0001’B
’0001’B
FLOAT BINARY (p1)
The length of the intermediate bit string is given by:
min(M,p1)
FLOAT DECIMAL (p1)
The length of the intermediate bit string is given by:
min(M,ceil(p1*3.32))
Arithmetic character PICTURE
Data is first interpreted as decimal with scale and precision determined by the
84
Enterprise PL/I for z/OS Language Reference
Source-to-target rules
corresponding PICTURE specification. The item then converts according to the
rules given for FIXED DECIMAL or FLOAT DECIMAL to BIT.
CHARACTER
Character 0 becomes bit 0 and character 1 becomes bit 1. Any character other
than 0 or 1 raises the CONVERSION condition. A null string becomes a null
bit string. The generated bit string, which has the same length as the source
character string, is assigned to the target according to the rules for string
assignment.
GRAPHIC
Graphic 0 becomes bit 0 and graphic 1 becomes bit 1. Any graphic other than 0
or 1 raises the CONVERSION condition. A null string becomes a null bit
string. The generated bit string, which has the same length as the source
graphic string, is then assigned to the target according to the rules for string
assignment.
WIDECHAR
Widechar 0 ('0030'wx) becomes bit 0 and widechar 1 ( '0031'wx) becomes bit 1.
Any widechar other than 0 or 1 raises the CONVERSION condition. A null
string becomes a null bit string. The generated bit string, which has the same
length as the source widechar string, is then assigned to the target according to
the rules for string assignment.
Target: GRAPHIC
Nongraphic source is first converted to character according to the rules in Target:
Character. The resultant character string is then converted to a DBCS string.
Target: WIDECHAR
Source other than widechar is first converted to character according to the rules in
Target: Character. The resultant character string is then converted to a widechar
string.
Examples
DECIMAL FIXED to BINARY FIXED with fractions
dcl I fixed bin(31,5) init(1);
I = I+.1;
The value of I is now 1.0625. This is because .1 is converted to FIXED BINARY
(5,4), so that the nearest binary approximation is 0.0001B (no rounding occurs). The
decimal equivalent of this is .0625. The result achieved by specifying .1000 in place
of .1 would be different.
Arithmetic to bit string
dcl A bit(1),
D bit(5);
A=1;
/* A has value ’0’B
*/
Chapter 4. Data conversion
85
Examples
D=1;
D=’1’B;
if A=1 then
else
/* D
/* D
go to
go to
has value ’00010’B */
has value ’10000’B */
Y;
X;
The branch is to X, because the assignment to A resulted in the following sequence
of actions:
1. The decimal constant, 1, has the attributes FIXED DECIMAL (1,0) and is
assigned to temporary storage with the attributes FIXED BINARY(4,0) and the
value 0001B.
2. This value now converts to a bit string of length (4), so that it becomes '0001'B.
3. The bit string is assigned to A. Since A has a declared length of 1, and the
value to be assigned has acquired a length of 4, truncation occurs at the right,
and A has a final value of '0'B.
For the comparison operation in the IF statement, '0'B and 1 convert to FIXED
BINARY and compare arithmetically. They are unequal, giving a result of false for
the relationship A=1.
In the first assignment to D, a sequence of actions similar to that described for A
takes place, except that the value is extended at the right with a zero, because D
has a declared length that is 1 greater than that of the assigned value.
Arithmetic to character
In the following example, the three blanks are necessary to allow for the possibility
of a minus sign, a decimal or binary point, and provision for a single leading zero
before the point:
dcl A char(4),
B char(7);
A=’0’; /*A has value ’0bbb’*/
A=0;
/*A has value ’bbb0’*/
B=1234567; /*B has value ’bbb1234’*/
A conversion error
dcl Ctlno char(8) init(’0’);
do I=1 to 100;
Ctlno=Ctlno+1;
.
.
.
end;
For this example, FIXED DECIMAL precision 15 was used for the implementation
maximum. The example raises the CONVERSION condition because of the
following sequence of actions:
1. The initial value of CTLNO, that is, '0bbbbbbb' converts to FIXED
DECIMAL(15,0).
2. The decimal constant, 1, with attributes FIXED DECIMAL(1,0), is added; in
accordance with the rules for addition, the precision of the result is (16,0).
3. This value now converts to a character string of length 18 in preparation for the
assignment back to CTLNO.
4. Because CTLNO has a length of 8, the assignment causes truncation at the
right; thus, CTLNO has a final value that consists entirely of blanks. This value
cannot be successfully converted to arithmetic type for the second iteration of
the loop.
86
Enterprise PL/I for z/OS Language Reference
Chapter 5. Program organization
Programs . . . . . . . . . . . . . . . 87
Program structure . . . . . . . . . . . 87
Program activation . . . . . . . . . . . 88
Program termination . . . . . . . . . . 89
Blocks . . . . . . . . . . . . . . . . 89
Block activation . . . . . . . . . . . . 89
Block termination . . . . . . . . . . . 90
Packages . . . . . . . . . . . . . . . 90
Procedures . . . . . . . . . . . . . . 93
PROCEDURE and ENTRY statements . . . . 94
ENTRY statement . . . . . . . . . . . 95
Parameter attribute . . . . . . . . . . . 96
Simple Parameter Bounds, Lengths, and Sizes 97
Controlled Parameter Bounds, Lengths, and
Sizes. . . . . . . . . . . . . . . 97
Procedure activation . . . . . . . . . . 99
Procedure termination . . . . . . . . . 100
Recursive procedures . . . . . . . . . . 101
Effect of recursion on automatic variables
102
Dynamic loading of an external procedure . . 102
Rules and features. . . . . . . . . . 103
FETCH statement . . . . . . . . . . 103
RELEASE statement . . . . . . . . . 104
Subroutines . . . . . . . . . . . . . . 105
Example 1 . . . . . . . . . . . . . 105
Example 2 . . . . . . . . . . . . . 106
Built-in subroutines . . . . . . . . . . . 106
Functions. . . . . . . . . . . . . . . 107
Examples . . . . . . . . . . . . . . 107
Example 1 . . . . . . . . . . . . 107
Example 2 . . . . . . . . . .
Built-in functions . . . . . . . . .
Passing arguments to procedures . . . . .
Using BYVALUE and BYADDR . . . .
Using INONLY, INOUT and OUTONLY .
Dummy arguments . . . . . . . .
Deriving dummy argument attributes .
Rules for dummy arguments . . . .
Passing arguments to the MAIN procedure
Begin-blocks . . . . . . . . . . . .
BEGIN statement . . . . . . . . .
Begin-block activation . . . . . . .
Begin-block termination . . . . . . .
Entry data . . . . . . . . . . . .
Entry constants . . . . . . . . . .
Entry variables . . . . . . . . . .
ENTRY attribute . . . . . . . . .
OPTIONAL attribute . . . . . . . .
LIST attribute . . . . . . . . . .
LIMITED attribute. . . . . . . . .
Example . . . . . . . . . . .
Generic entries . . . . . . . . . .
GENERIC attribute . . . . . . . .
Entry invocation or entry value . . . . .
CALL statement . . . . . . . . . .
RETURN statement . . . . . . . . .
Return from a subroutine . . . . . .
Return from a function . . . . . . .
OPTIONS option and attribute . . . . .
RETURNS option and attribute . . . . .
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
108
108
109
109
110
110
111
111
111
112
112
112
112
113
113
114
115
118
119
123
124
124
124
127
127
128
128
128
129
138
This chapter discusses how statements can be organized into different kinds of
blocks to form a PL/I program, how control flows among blocks, and how
different blocks can make use of the same data.
Proper division of a program into blocks simplifies the writing and testing of the
program, particularly when many programmers are writing it. Proper division can
also result in more efficient use of storage, since automatic storage is allocated on
entry to the block in which it is declared and released when the block is
terminated.
Programs
Program structure
PL/I is a block-structured language, consisting of packages, procedures,
begin-blocks, statements, expressions, and built-in functions.
A PL/I application consists of one or more separately loadable entities, known as a
load module. Each load module can consist of one or more separately compiled
entities, known as a compilation unit (CU). Unless otherwise stated, a program refers
to a PL/I application or a compilation unit.
© Copyright IBM Corp. 1999, 2012
87
Program structure
A compilation unit is a PL/I PACKAGE or an external PROCEDURE. Each
package can contain zero or more procedures, some or all of which can be
exported. A PL/I external or internal procedure contains zero or more blocks. A
PL/I block is either a PROCEDURE or a BEGIN block, which contains zero or
more statements and/or zero or more blocks.
A PL/I block allows you to produce highly-modular applications, because blocks
can contain declarations that define variable names and storage class. Thus, you
can restrict the scope of a variable to a single block or a group of blocks, or can
make it known throughout the compilation unit or a load module.
By giving you freedom to determine the degree to which a block is self-contained,
PL/I makes it possible to produce blocks that many compilation units and
applications can share, leading to code reuse.
Figure 2 shows an application structure.
Figure 2. A PL/I application structure
Packages are discussed in “Packages” on page 90.
Procedures are discussed in “Procedures” on page 93.
Begin-blocks are discussed in “Begin-blocks” on page 112.
Program activation
A PL/I program becomes active when a calling program invokes the main
procedure. This calling program usually is the operating system, although it could
be another program. The main procedure is the external procedure for which the
statement has the OPTIONS(MAIN) specification. In the following example, Contrl
is the main procedure and it invokes other external procedures in the program.
The main procedure remains active for the duration of the program.
88
Enterprise PL/I for z/OS Language Reference
Program activitation
Contrl: procedure options(main);
call A;
call B;
call C;
end Contrl;
Program termination
A program is terminated when the main procedure is terminated. Whether
termination is normal or abnormal, control returns to the calling program. In the
previous example, when control transfers from the C procedure back to the Contrl
procedure, Contrl terminates. See “Procedure termination” on page 100 for more
information.
Blocks
A block is a delimited sequence of statements that does the following:
v Establishes the scope of names declared within it
v Limits the allocation of automatic variables
v Determines the scope of DEFAULT statements (as described in “Defaults for
attributes” on page 168).
The kinds of blocks are:
v Package
v Procedure
v Begin
These blocks can contain declarations that are treated as local definitions of names.
This is done to establish the scope of the names and to limit the allocation of
automatic variables. These declarations are not known outside their own block,
and the names cannot be referred to in the containing block. See “Scope of
declarations” on page 155 for more information.
Storage is allocated to automatic variables upon entry to the block where the
storage is declared, and is freed upon exit from the block. See “Scope of
declarations” on page 155, for more information.
Block activation
Each block plays the same role in the allocation and freeing of storage and in
delimiting the scope of names. How activation occurs is discussed in “Procedures”
on page 93 and “Begin-blocks” on page 112. Packages are neither activated nor
terminated.
During block activation, the following are performed:
v Expressions that appear in declare statements are evaluated for extents and
initial values (including iteration factors).
v Storage is allocated for automatic variables. Their initial values are set if
specified.
v Storage is allocated for dummy arguments and compiler-created temporaries
that might be created in this block.
Initial values and extents for automatic variables must not depend on the values or
extents of other automatic variables declared in the same block. For example, the
following initialization can produce incorrect results for J and K:
dcl I init(10),J init(K),K init(I);
Chapter 5. Program organization
89
Block activation
Similarly, the following code causes b to have an undefined value (and most likely,
not the value 10) after this structure is initialized:
dcl
1 a,
2 b fixed bin init(c),
2 c fixed bin init(10);
Declarations of data items must not be mutually interdependent. For example, the
following declarations are invalid:
dcl A(B(1)), B(A(1));
dcl D(E(1)), E(F(1)), F(D(1));
Errors can occur during block activation, and the ERROR condition (or other
conditions) can be raised. If so, the environment of the block might be incomplete.
In particular, some automatic variables might not have been allocated. Statements
referencing automatic variables executed after the ERROR condition has been
raised may reference unallocated storage. The results of referring to unallocated
storage are undefined.
Block termination
There are a number of ways a block can be terminated. How termination occurs is
discussed in “Procedures” on page 93 and “Begin-blocks” on page 112. Packages
are neither activated nor terminated.
During block termination:
v The ON-unit environment is reestablished as it existed before the block was
activated.
v Storage for all automatic variables allocated in the block is released.
Packages
A package is a block that can contain only declarations, default statements, and
procedure blocks. The package forms a name scope that is shared by all
declarations and procedures contained in the package, unless the names are
declared again. Some or all of the level-1 procedures can be exported and made
known outside of the package as external procedures. A package can be used for
implementing multiple entry point applications.
A package that contains a MAIN procedure must not also contain any
FETCHABLE procedures. A package that contains a MAIN procedure may also not
be linked into a DLL. It should form part of a base executable that may, if desired,
invoke routines in a DLL. Such a package may, of course, also define external
routines that may be called from other routines statically linked with it, and the
package may also define EXTERNAL STATIC data that may be referenced from
other routines statically linked with it.
If a package (not containing a MAIN routine) is linked into a DLL, then the only
EXTERNAL STATIC variables that will be exported from that package out of the
DLL will be those variables that have the RESERVED attribute.
If the source contains a PACKAGE statement, then there must be at most only one
set of *PROCESS statements and those must be the first statements in the source. If
the source contains no PACKAGE statement, then the compiler effectively inserts
90
Enterprise PL/I for z/OS Language Reference
Packages
one after the first set of *PROCESS statements and the source may contain multiple
external procedures separated by groups of *PROCESS statements.
condition-prefix : package-name :
PACKAGE
,
EXPORTS (
procedure
)
*
;
,
RESERVES (
variable name
*
declare-statement
default-statement
procedure-statement
OPTIONS(options)
)
END
;
package-name
procedure:
procedure-name
EXTERNAL(environment-name)
condition-prefix
Condition prefixes specified on a PACKAGE statement apply to all procedures
contained in the package unless overridden on the PROCEDURE statement.
For more information on condition prefixes, refer to “Condition prefixes” on
page 349.
package-name
The name of the package. All PACKAGE names must be unique within a
linked module.
EXPORTS
Specifies that all (EXPORTS(*)) or the named procedures are to be exported
and thus made externally known outside of the package. If no EXPORTS
option is specified, EXPORTS(*) is assumed.
procedure name
Is the name of a level-1 procedure within the package.
EXTERNAL (environment name)
Is a scope attribute discussed in “Scope of declarations” on page 155.
Chapter 5. Program organization
91
Packages
RESERVES
Specifies that this package reserves the storage for all (RESERVES(*)), or only
for the named variables that have the RESERVED attribute, see “RESERVED
attribute” on page 162.
variable name
Is the name of a level-1 external static variable.
OPTIONS option
For OPTIONS options applicable to a package statement, refer to “OPTIONS
option and attribute” on page 129.
declare statement
All variables declared within a package but outside any contained level-1
procedure must have the storage class of static, based, or controlled. Automatic
variables are not allowed. Default storage class is STATIC. Refer to Chapter 7,
“Data declarations,” on page 151.
default statement
Refer to “Defaults for attributes” on page 168.
procedure statement
Refer to “PROCEDURE and ENTRY statements” on page 94.
An example of the package statement appears in Figure 3 on page 93.
92
Enterprise PL/I for z/OS Language Reference
Procedures
*Process S A(F) LIMITS(EXTNAME(31)) NUMBER;
Package_Demo: Package exports (Factorial);
/***********************************************/
/*
Common Data
*/
/***********************************************/
dcl N fixed bin(15);
dcl Message char(*) value(’The factorial of ’);
/***********************************************/
/*
Main Program
*/
/***********************************************/
Factorial: proc options (main);
dcl Result fixed bin(31);
put skip list(’Please enter a number whose factorial ’ ||
’must be computed ’);
get list(N);
Result = Compute_factorial(n);
put list(Message || trim(N) || ’ is ’ || trim(Result));
end Factorial;
/***********************************************/
/*
Subroutine
*/
/***********************************************/
Compute_factorial: proc (Input) recursive returns (fixed bin(31));
dcl Input fixed bin(15);
if Input <= 1 then
return(1);
else
return( Input*Compute_factorial(Input-1) );
end Compute_factorial;
end Package_Demo;
Figure 3. Package statement
Procedures
A procedure is a sequence of statements delimited by a PROCEDURE statement
and a corresponding END statement. A procedure can be a main procedure, a
subroutine, or a function. An application must have exactly one external procedure
that has OPTIONS(MAIN). In the following example, the name of the procedure is
Name and represents the entry point of the procedure.
Name:
procedure;
end Name;
The ENTRY statement can define a secondary entry point to a procedure. For
example,
Name: procedure;
B: entry;
end Name;
B defines a secondary entry point to the Name procedure. The ENTRY statement is
described in “ENTRY attribute” on page 115.
A procedure must have a name. A procedure block nested within another
procedure or begin-block is called an internal procedure. A procedure block not
Chapter 5. Program organization
93
Procedures
nested within another procedure or begin-block is called an external procedure.
Level-1 exported procedures from a package also become external procedures.
External procedures can be invoked by other procedures in other compilation
units. Procedures can invoke other procedures.
A procedure can be recursive, which means that it can be reactivated from within
itself or from within another active procedure while it is already active. You can
pass arguments when invoking a procedure.
For more information on these subjects, see the following sections:
v “Scope of declarations” on page 155
v “Subroutines” on page 105
v “Functions” on page 107
v “Passing arguments to procedures” on page 109.
PROCEDURE and ENTRY statements
A procedure (subroutine or function) can have one or more entry points. The
primary entry point to a procedure is established by the leftmost label of the
procedure statement. Secondary entry points to a procedure are established by
additional labels on the PROCEDURE statement and by the ENTRY statement.
Each entry point has an entry name. See “INTERNAL and EXTERNAL attributes”
on page 157 for a discussion of the rules for the creation of an external name.
A PROCEDURE statement identifies the procedure as a main procedure, a
subroutine, or a function. Parameters expected by the procedure and other
characteristics are also specified on the PROCEDURE statement.
entry-label:
PROCEDURE
,
( )
parameter
returns-option
OPTIONS(options)
; scope-attribute
END
statement
group
internal-procedure
begin-block
;
entry-label
Abbreviations: PROC for PROCEDURE
94
Enterprise PL/I for z/OS Language Reference
RECURSIVE
PROCEDURE and ENTRY
entry-label
The entry point to the procedure. External entries are explicitly declared in the
invoking procedure. If multiple entry labels are specified, the leftmost name is
the primary entry point and is the name returned by the PROCNAME and
ONLOC built-in functions. For more information on entry data, refer to “Entry
data” on page 113.
parameter
Refer to “Parameter attribute” on page 96 and “Passing arguments to
procedures” on page 109.
returns-option
Applies only to function procedures. Refer to “Functions” on page 107 and
“RETURNS option and attribute” on page 138.
OPTIONS option
Refer to “OPTIONS option and attribute” on page 129.
RECURSIVE
Refer to “Recursive procedures” on page 101.
scope-attribute
Refer to “Scope of declarations” on page 155.
ENTRY statement
The ENTRY statement specifies a secondary entry point of a procedure. The
ENTRY statement must be internal to the procedure for which it defines a
secondary entry point. It cannot be within a do-group that specifies repetitive
execution, or internal to a ON-unit.
entry-label:
ENTRY
,
( parameter
)
;
OPTIONS(options)
RETURNS( attribute
)
entry-label
The secondary entry point to the procedure.
parameter
Refer to “Parameter attribute” on page 96 and “Passing arguments to
procedures” on page 109.
RETURNS option
Refer to “RETURNS option and attribute” on page 138.
OPTIONS option
Refer to “OPTIONS option and attribute” on page 129.
Chapter 5. Program organization
95
ENTRY
All parameters on an ENTRY statement must be BYADDR, and for a procedure
containing ENTRY statements, all non-pointer parameters to that procedure must
be BYADDR.
If a procedure containing ENTRY statements has the RETURNS option (or if any of
its contained ENTRY statements have the RETURNS option), then
v the BYADDR attribute must be specified (or implied by the compile-time option
DEFAULT(RETURNS(BYADDR)) in all of the RETURNS options for that
procedure and its ENTRY statements.
v All routines that call one of these entry points must also either declare the entry
with RETURNS(BYADDR) or be compiled with the
DEFAULT(RETURNS(BYADDR)) compiler option.
When a procedure contains ENTRY statements and some, but not all of its entry
points have the RETURNS attribute, the ERROR condition is detected under the
following circumstances:
v If the code executes a RETURN statement with an expression when the
procedure was entered at an entry point which did not have the RETURNS
attribute.
v If the code executes a RETURN statement without an expression when the
procedure was entered at an entry point that has the RETURNS attribute.
Parameter attribute
A parameter is contextually declared with the parameter attribute by its
specification in a PROCEDURE or ENTRY statement. The parameter should be
explicitly declared with appropriate attributes. The PARAMETER attribute can also
be specified in the declaration. If attributes are not supplied in a DECLARE
statement, default attributes are applied. The parameter name must not be
subscripted or qualified.
PARAMETER
Table 8 on page 21, and the following discussion, describe the attributes that can be
declared for a parameter.
A parameter always has the INTERNAL attribute.
If the parameter is a structure or union, it must specify the level-1 name.
A parameter cannot have any storage class attributes except CONTROLLED. A
controlled parameter must have a controlled argument, and can also have the
INITIAL attribute.
Parameters used in record-oriented input/output, or as the base variable for
DEFINED items, must be in connected storage. The CONNECTED attribute must
be specified both in the declaration in the procedure and in the descriptor list of
the procedure entry declaration.
96
Enterprise PL/I for z/OS Language Reference
Simple parameter bounds, lengths, and sizes
Simple Parameter Bounds, Lengths, and Sizes
Bounds, lengths, and sizes of simple parameters must be specified either by
asterisks or by restricted expressions. When the actual length, bounds, or size can
be different for different invocations, each can be specified in a DECLARE
statement by an asterisk. When an asterisk is used, the length, bounds, or size are
taken from the current generation of the associated argument.
An asterisk is not allowed as the length specification of a string that is an element
of an aggregate, if the associated argument creates a dummy. The string length
must be specified as an integer.
Controlled Parameter Bounds, Lengths, and Sizes
The bounds, length, or size of a controlled parameter can be specified in a
DECLARE statement either by asterisks or by element expressions.
Asterisk Notation:
When asterisks are used, length, bounds, or size of the controlled parameter are
taken from the current generation of the associated argument. Any subsequent
allocation of the controlled parameter uses these same bounds, length, or size,
unless they are overridden by a different length, bounds, or size specification in
the ALLOCATE statement. If no current generation of the argument exists, the
asterisks determine only the dimensionality of the parameter, and an ALLOCATE
statement in the invoked procedure must specify bounds, length, or size for the
controlled parameter before other references to the parameter can be made.
Expression Notation:
Each time the parameter is allocated, the expressions are evaluated to give current
bounds, lengths, or sizes for the new allocation. However, such expressions in a
DECLARE statement can be overridden by a bounds, length, or size specification
in the ALLOCATE statement itself.
Example of array argument with parameters:
In Figure 4 on page 98, when Sub1 is invoked, A and B, which have been allocated,
are passed.
Chapter 5. Program organization
97
Controlled parameter bounds, lengths, and sizes
%process or(’|’) num margins(1,72);
Package:package exports(*);
Main: procedure options(main);
declare (A(NA), B(NB), C(NC), D(ND) ) controlled;
declare (NA init(20), NB init(30), NC init(100),
ND init(100) ) fixed bin(31);
declare Sub1 entry((*) controlled, (*) controlled);
declare Sub2 entry ((*) ctl, (*) ctl, fixed bin);
allocate A,B; /* A(20), B(30) */
display (’Gen1: DIM(A)=’ { dim(A) { ’, ’ { "DIM(B)=" { dim(B));
call Sub1(A,B);
display (’Gen2: Allocn(A)=’ { allocn(a)
’Allocn(B)=’ { allocn(B) );
display (’Gen2: DIM(A)=’ { dim(A) { ’,
free A,B;
display (’Gen1: Allocn(A)=’ { allocn(A)
’Allocn(B)=’ { allocn(B) );
display (’Gen1: DIM(A)=’ { dim(A) { ’,
free A,B;
display (’Gen0: Allocn(A)=’ { allocn(A)
’Allocn(B)=’ { allocn(B) );
call Sub2 (C,D,10);
display (’Gen1:
’Allocn(D)=’ {
display (’Gen1:
free C,D;
display (’Gen0:
’Allocn(D)=’ {
end Main;
{ ’, ’ {
’ { "DIM(B)=" { dim(B));
{ ’, ’ {
’ { "DIM(B)=" { dim(B));
{ ’, ’ {
Allocn(C)=’ { allocn(C) { ’, ’ {
allocn(D) );
DIM(C)=’ { dim(C) { ’, ’ { "DIM(D)=" { dim(D));
Allocn(C)=’ { allocn(c) { ’, ’ {
allocn(D) );
Sub1: procedure (U,V);
dcl (U(UB), V(*)) controlled,
UB fixed bin(31);
display (’Gen1: Allocn(U)=’ { allocn(U)
’Allocn(V)=’ { allocn(V) );
display (’Gen1: DIM(U)=’ { dim(U) { ’,
UB=200;
allocate U,V; /* U(200), V(30) */
display (’Gen2: Allocn(U)=’ { allocn(U)
’Allocn(V)=’ { allocn(V) );
display (’Gen2: DIM(U)=’ { dim(U) { ’,
end Sub1;
{ ’, ’ {
’ { "DIM(V)=" { dim(V));
{ ’, ’ {
’ { "DIM(V)=" { dim(V));
Sub2: procedure (X,Y,N);
dcl (X(N),Y(N)) controlled,
N fixed bin;
display (’Gen0: Allocn(X)=’ { allocn(X) { ’, ’ {
’Allocn(Y)=’ { allocn(Y) );
allocate X,Y; /* X(10), Y(10) */
display (’Gen1: Allocn(X)=’ { allocn(X) { ’, ’ {
’Allocn(Y)=’ { allocn(Y) );
display (’Gen1: DIM(X)=’ { dim(X) { ’, ’ { "DIM(Y)=" { dim(Y));
end Sub2;
end Package;
Figure 4. Array argument with parameters
The ALLOCATE statement in Sub1 allocates a second generation of A and B. B has
the same bounds for both generations while A has different bounds for the second
generation.
On returning to Main, the first FREE statement frees the second generation of A and
B (allocated in Sub1). The second FREE statement frees the first generation of A and
B (allocated in Main).
98
Enterprise PL/I for z/OS Language Reference
Controlled parameter bounds, lengths, and sizes
In Sub2, X and Y are declared with bounds that depend on the value of N. When X
and Y are allocated, their values determine the bounds of the allocated arrays.
On returning to Main from Sub2, the FREE statement frees the only generation of C
and D (allocated in Sub2).
Procedure activation
Sequential program flow passes around a procedure, from the statement before the
PROCEDURE statement to the statement after the END statement for that
procedure. The only way that a procedure can be activated is by a procedure
reference. (“Program activation” on page 88 tells how to activate the main
procedure.) The execution of the invoking procedure is suspended until the
invoked procedure returns control to it.
A procedure reference is the appearance of an entry expression in one of the
following contexts:
v Using a CALL statement to invoke a subroutine, as described in “CALL
statement” on page 127
v Invoking a function, as described in “Functions” on page 107
The information in this section is relevant to each of these contexts. However, the
examples in this chapter use CALL statements.
When a procedure reference occurs, the procedure containing the specified entry
point is said to be invoked. The point at which the procedure reference appears is
called the point of invocation and the block in which the reference is made is called
the invoking block. An invoking block remains active even though control is
transferred from it to the procedure it invokes.
When a procedure is invoked at its primary entry point, arguments and
parameters are associated and execution begins with the first statement in the
invoked procedure. When a procedure is invoked at a secondary entry point with
the ENTRY statement, execution begins with the first statement following the
ENTRY statement. The environment established on entry to a block at the primary
entry point is identical to the environment established when the same block is
invoked at a secondary entry point.
Communication between two procedures is by means of arguments passed from an
invoking procedure to the invoked procedure, by a value returned from an
invoked procedure, and by names known within both procedures. Therefore, a
procedure can operate upon different data when it is invoked from different
points. For example,
Readin: procedure;
statement-1
statement-2
Errt: entry;
statement-3
statement-4
end Readin;
can be activated by any of these entry references:
call Readin;
call Errt;
The statement call Readin invokes Readin at its primary entry point and execution
begins with statement-1; the statement call Errt invokes the Readin procedure at
Chapter 5. Program organization
99
Procedure activation
the secondary entry point Errt and execution begins with statement-3. The entry
constant (Readin) can also be assigned to an entry variable that is used in a
procedure reference. For example:
declare Readin entry,
Ent1 entry variable;
Ent1 = Readin;
call Ent1;
call Readin;
The two CALL statements have the same effect.
Procedure termination
A procedure is terminated when, by some means other than a procedure reference,
control passes back to the invoking program, block, or to some other active block.
Procedures terminate normally when:
v Control reaches a RETURN statement within the procedure. The execution of a
RETURN statement returns control to the point of invocation in the invoking
procedure. If the point of invocation is a CALL statement, execution in the
invoking procedure resumes with the statement following the CALL. If the point
of invocation is a function reference, execution of the statement containing the
reference is resumed.
v Control reaches the END statement of the procedure. Effectively, this is
equivalent to the execution of a RETURN statement.
Procedures terminate abnormally when:
v Control reaches a GO TO statement that transfers control out of the procedure.
The GO TO statement can specify a label in a containing block, or it can specify
a parameter that has been associated with a label argument passed to the
procedure. A STOP statement is executed in the current thread of a
single-threaded program or in any thread of a multithreaded program.
v An EXIT statement is executed.
v The ERROR condition is raised and there is no established ON-unit for ERROR
or FINISH. Also, if one or both of the conditions has an established ON-unit,
ON-unit exit is by normal return rather than by a GO TO statement.
v The procedure calls or invokes another procedure that terminates abnormally.
Transferring control out of a procedure using a GO TO statement can sometimes
result in the termination of several procedures and/or begin-blocks. Specifically, if
the transfer point specified by the GO TO statement is contained in a block that
did not directly activate the block being terminated, all intervening blocks in the
activation sequence are terminated. In the following example:
A: procedure options(main);
statement-1
statement-2
B: begin;
statement-b1
statement-b2
call C;
statement-b3
end B;
statement-3
statement-4
C: procedure;
statement-c1
statement-c2
statement-c3
100
Enterprise PL/I for z/OS Language Reference
Procedure termination
D: begin;
statement-d1
statement-d2
go to Lab;
statement-d3
end D;
statement-c4
end C;
statement-5
Lab: statement-6
statement-7
end A;
A activates B, which activates C, which activates D. In D, the statement go to Lab
transfers control to statement-6 in A. Since this statement is not contained in D, C,
or B, all three blocks are terminated; A remains active. Thus, the transfer of control
out of D results in the termination of intervening blocks B and C as well as the
termination of block D.
Recursive procedures
An active procedure that is invoked from within itself or from within another
active procedure is a recursive procedure. Such an invocation is called recursion.
A procedure that is invoked recursively must have the RECURSIVE attribute
specified in the PROCEDURE statement.
RECURSIVE
The environment (that is, values of automatic variables and the like) of every
invocation of a recursive procedure is preserved in a manner analogous to the
stacking of allocations of a controlled variable (see “Controlled storage and
attribute” on page 238). Think of an environment as being pushed down at a
recursive invocation, and popped up at the termination of that invocation. A label
constant in the current block is always a reference to the current invocation of the
block that contains the label.
If a label constant is assigned to a label variable in a particular invocation, and the
label variable is not declared within the recursive procedure, a GO TO statement
naming that variable in another invocation restores the environment that existed
when the assignment was performed, terminating the current and any intervening
procedures and begin-blocks.
The environment of a procedure that was invoked from within a recursive
procedure by means of an entry variable is the one that was current when the
entry constant was assigned to the variable. Consider the following example:
I=1;
call A;
/* First invocation of A
*/
A: proc recursive;
declare Ev entry variable static;
if I=1 then
do;
I=2;
Ev=B;
call A;
/* 2nd invocation of A
*/
Chapter 5. Program organization
101
Recursive procedures
end;
else call Ev;
/* Invokes B with environment */
/* of first invocation of A
*/
B: proc;
go to Out;
end B;
Out: end A;
The GO TO statement in the procedure B transfers control to the END A statement in
the first invocation of A, and terminates B and both invocations of A.
Effect of recursion on automatic variables
The values of variables allocated in one activation of a recursive procedure must be
protected from change by other activations. This is arranged by stacking the
variables. A stack operates on a last-in, first-out basis. The most recent generation
of an automatic variable is the only one that can be referenced. Static variables are
not affected by recursion. Thus, they are useful for communication across recursive
invocations. This also applies to automatic variables that are declared in a
procedure that contains a recursive procedure and to controlled and based
variables. In the following example:
A: proc;
dcl X;
.
.
.
B: proc recursive;
dcl Z,Y static;
call B;
.
.
.
end B;
end A;
A single generation of the variable X exists throughout invocations of procedure B.
The variable Z has a different generation for each invocation of procedure B. The
variable Y can be referred to only in procedure B and is not reallocated at each
invocation. (The concept of stacking variables is also of importance in the
discussion of controlled variables in “Controlled storage and attribute” on page
238.)
Dynamic loading of an external procedure
A module can be dynamically fetched (loaded) or released (deleted) by a PL/I
program using FETCH and RELEASE statements.
A procedure invoked by a procedure reference usually is resident in main storage
throughout the execution of the program. However, a procedure can be loaded into
main storage for only as long as it is required. The invoked procedure can be
dynamically loaded into, and dynamically deleted from, main storage during
execution of the calling procedure.
Dynamic loading and deletion of procedures is particularly useful when a called
procedure is not necessarily invoked every time the calling procedure is executed,
and when conservation of main storage is more important than a short execution
time.
The appearance of an entry constant in a FETCH statement indicates that the
referenced procedure needs to be loaded into main storage before it can be
102
Enterprise PL/I for z/OS Language Reference
Dynamic loading of an external procedure
executed, unless a copy already exists in main storage. Provided the name is
referenced in a FETCH statement, a procedure can also be loaded from the disk by:
v Execution of a CALL statement or the CALL option of an INITIAL attribute
v Execution of a function reference.
It is not necessary that control pass through a FETCH or RELEASE statement,
either before or after execution of the CALL or function reference.
Whichever statement loaded the procedure, execution of the CALL statement or
option or the function reference invokes the procedure in the normal way.
It is not an error if the procedure has already been loaded into main storage. The
fetched procedure can remain in main storage until execution of the whole
program is completed. Alternatively, the storage it occupies can be freed for other
purposes at any time by means of the RELEASE statement.
Rules and features
FETCH and RELEASE have the following rules and features:
v Only external procedures can be fetched.
v EXTERNAL files and CONDITION conditions are shared across the entire
application (main and fetched modules). Other external variables are shared only
within a single module.
v Storage for STATIC variables in the fetched procedure is allocated when the load
module containing the procedure is loaded into memory. Each time a load
module is loaded into memory, the STATIC variables are given the initial values
indicated by their declarations.
v The FETCH and RELEASE statements must specify entry constants. An entry
constant for a fetched procedure can be assigned to an entry variable provided
the procedure has been fetched.
FETCH statement
The FETCH statement checks main storage for the named procedures. Procedures
not already in main storage are loaded from the disk.
,
FETCH entry-constant
SET ( ptr-ref )
TITLE ( char-expr )
;
entry-constant
Specifies the name by which the procedure to be fetched is known to the
operating system. Details of the linking considerations for fetchable procedures
are given in the Programming Guide.
The entry-constant must be the same as the one used in the corresponding
CALL statement, CALL option, or function reference.
SET
Specifies a pointer reference (ptr-ref) that will be set to the address of the entry
point of the loaded module. This option can be used to load tables
Chapter 5. Program organization
103
FETCH
(non-executable load modules). It can also be used for entries that are fetched
and whose addresses need to be passed to non-PL/I procedures.
If the load module is later released by the RELEASE statement, and the load
module is accessed (through the pointer), unpredictable results can occur.
TITLE
For TITLE, char-expr is any character expression or an expression that can be
converted to a character expression. If TITLE is specified, the load module
name specified is searched for and loaded. If it is not specified, the load
module name used is the environment name specified in the EXTERNAL
attribute for the variable (if present) or the entry constant name itself.
For example:
dcl
dcl
dcl
T =
A entry;
B entry ext(’C’);
T char(20) varying;
’Y’;
fetch
fetch
fetch
fetch
fetch
A title(’X’);
A;
B title(’Y’);
B;
B title(T);
/*
/*
/*
/*
/*
X
A
Y
C
Y
is
is
is
is
is
loaded
loaded
loaded
loaded
loaded
*/
*/
*/
*/
*/
For more detailed information on title strings, refer to the Programming Guide.
RELEASE statement
The RELEASE statement frees the main storage occupied by procedures identified
by its specified entry constants.
,
RELEASE
entry-constant
*
;
entry constant
Must be the same as the one used in the corresponding CALL statement,
CALL option, function reference, and FETCH statements. RELEASE * releases
all previously fetched PL/I modules. It must not be executed from within a
fetched module.
If the module has never been fetched in the same external procedure before or
has already been released, the entry constant is the null pointer. No release is
performed, no message is issued and execution continues with the statement
that follows the RELEASE statement.
Consider the following example, in which ProgA and ProgB are entry names of
procedures resident on disk:
Prog:
104
procedure;
1
2
3
fetch ProgA;
call ProgA;
release ProgA;
4
call ProgB;
Enterprise PL/I for z/OS Language Reference
RELEASE
go to Fin;
fetch ProgB;
Fin: end Prog;
1
ProgA is loaded into main storage by the first FETCH statement.
2
ProgA executes when the first CALL statement is reached.
3
Storage for ProgA is released when the RELEASE statement is executed.
4
ProgB is loaded and executed when the second CALL statement is reached,
even though the FETCH statement referring to this procedure is never
executed.
The same results would be achieved if the statement FETCH ProgA were omitted.
The appearance of ProgA in a RELEASE statement causes the statement CALL
ProgA to load the procedure, as well as invoke it.
The fetched procedure is compiled and linked separately from the calling
procedure. You must ensure that the entry constant specified in FETCH, RELEASE,
and CALL statements; CALL options; and in function references is the name
known on the disk. This is discussed in the Programming Guide.
Note: Before a module is released, the module must release all system resources it
has acquired. This includes but is not limited to the following actions:
v Release any modules it has fetched.
v Close any files it has opened.
v Free any controlled storage it has allocated.
Subroutines
A subroutine is an internal or external procedure that is invoked by a CALL
statement. For the syntax of a subroutine, see “Procedures” on page 93.
The arguments of the CALL statement are associated with the parameters of the
invoked procedure. The subroutine is activated, and execution begins. The
arguments (zero or more) can be input only, output only, or both.
A subroutine is normally terminated by the RETURN or the END statement.
Control is then returned to the invoking block. A subroutine can be abnormally
terminated as described in “Procedure termination” on page 100.
A subroutine procedure must:
v Not have the RETURNS option on the procedure statement
v Not be declared as an entry with the RETURNS attribute if it is an external
procedure
v Be invoked using the CALL statement, not a function reference
v Not return a result value using the RETURN statement
The following examples illustrate the invocation of subroutines that are external to
and internal to the invoking block.
Example 1
Prmain:
4
procedure;
declare Name character (20),
Item bit(5),
Outsub entry;
Chapter 5. Program organization
105
Subroutines
1
2
3
call Outsub (Name, Item);
end Prmain;
Outsub:
procedure (A,B);
declare A character (20),
B bit(5);
put list (A,B);
end Outsub;
1
The CALL statement in Prmain invokes the procedure Outsub in 2 with
the arguments Name and Item.
2
Outsub associates Name and Item passed from Prmain with its parameters, A
and B. When Outsub is executed, each reference to A is treated as a
reference to Name. Each reference to B is treated as a reference to Item.
3
The put list (A,B) statement transmits the values of Name and Item to the
default output file, SYSPRINT.
4
In the declaration of Outsub as an entry constant, no parameter descriptor
has to be given with the ENTRY attribute, because the attributes of the
arguments and parameters match. Also see “ENTRY attribute” on page 115.
Example 2
A:
1
3
2
procedure;
declare Rate float (10),
Time float(5),
Distance float(15),
Master file;
call Readcm (Rate, Time, Distance, Master);
Readcm:
procedure (W,X,Y,Z);
declare W float (10),
X float(5),
Y float(15), Z file;
get File (Z) list (W,X,Y);
Y = W * X;
if Y > 0 then
return;
else
put list(’ERROR READCM’);
end Readcm;
end A;
1
The arguments Rate, Time, Distance, and Master are passed to the
procedure Readcm in 3 and associated with the parameters W, X, Y, and Z.
2
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.
3
Note that Readcm is not explicitly declared in A. It is implicitly declared
with the ENTRY attribute by its specification on the PROCEDURE
statement.
Built-in subroutines
You can use built-in subroutines, which provide ready-made programming tasks.
Their built-in names can be explicitly declared with the BUILTIN attribute. (For
more information on the BUILTIN attribute or for the description of any built-in
function, see Chapter 18, “Built-in functions, pseudovariables, and subroutines,” on
page 383.)
106
Enterprise PL/I for z/OS Language Reference
Functions
Functions
A function is a procedure that has zero or more arguments and is invoked by a
function reference in an expression. The function reference transfers control to a
function procedure; the function procedure returns control and a value, which
replaces the function reference in the evaluation of the expression. Aggregates
cannot be returned; ENTRY variables cannot be returned unless they have the
LIMITED attribute. The evaluation of the expression then continues.
A function procedure must:
v Have the RETURNS option on the procedure statement.
v Be declared as an entry with the RETURNS attribute, if it is an external
procedure.
v Be invoked using a function reference. The CALL statement can be used to
invoke it only if the returned value has the OPTIONAL attribute. In this case,
the returned value is discarded upon return. Using END instead of RETURN can
cause unpredictable results.
v Have matching attributes in the RETURNS option and in the RETURNS
attribute.
v Use the RETURN statement to return control and the result value.
Whenever a function is invoked, the arguments in the invoking expression are
associated with the parameters of the entry point. Control is then passed to that
entry point. The function is activated and execution begins.
The RETURN statement terminates a function and returns the value specified in its
expression to the invoking expression. See “RETURN statement” on page 128 for
more information.
A function can be abnormally terminated as described in “Procedure termination”
on page 100. If this method is used, evaluation of the expression that invoked the
function is not completed, and control goes to the designated statement.
In some instances, a function can be defined so that it does not require an
argument list. In such cases, the appearance of an external function name within
an expression is recognized as a function reference only if the function name has
been explicitly declared as an entry name. See “Entry invocation or entry value”
on page 127 for additional information.
Examples
The following examples illustrate the invocation of functions that are internal to
and external to the invoking block.
Example 1
In the following example, the assignment statement contains a reference to the
Sprod function:
1
2
Mainp: procedure;
get list (A, B, C, Y);
X = Y**3+Sprod(A,B,C);
Sprod: procedure (U,V,W)
returns (bin float(21));
dcl (U,V,W) bin float(53);
if U > V + W then
Chapter 5. Program organization
107
Functions
3
3
return (0);
else
return (U*V*W);
end Sprod;
1
When Sprod is invoked, the arguments A, B, and C are associated with the
parameters U, V, and W in 2, respectively.
2
Sprod is a function because RETURNS appears in the procedure statement.
It is internal, and therefore needs no explicit entry declaration. If Sprod
were external, Mainp would contain an entry declaration with RETURNS
specified.
3
Sprod returns either zero or the value represented by U*V*W, along with
control to the expression in Mainp. The returned value is taken as the value
of the function reference, and evaluation of the expression continues.
Example 2
Mainp:
1
1
2
3
procedure;
dcl Tprod entry (bin float(53),
bin float(53),
bin float(53),
label) external
returns (bin float(21));
get list (A,B,C,Y);
X = Y**3+Tprod(A,B,C,Lab1);
Lab1: call Errt;
end Mainp;
Tprod:
procedure (U,V,W,Z)
returns (bin float(21));
dcl (U,V,W) bin float(53);
declare Z label;
if U > V + W then
go to Z;
else
return (U*V*W);
end Tprod;
1
When Tprod is invoked, Lab1 is associated with parameter Z.
2
If U is greater than V + W, control returns to Mainp at the statement labeled
Lab1. Evaluation of the assignment in 1 is discontinued.
3
If U is not greater than V + W, U*V*W is calculated and returned to Mainp in
the normal fashion. Evaluation of the assignment in 1 continues.
Notice that Tprod is an external procedure. It has an explicit entry declaration in
Mainp, which contains RETURNS.
Built-in functions
Besides allowing programmer-written function procedures, PL/I provides a set of
built-in functions. Built-in functions include commonly used arithmetic functions, as
well as functions for manipulating strings and arrays, using storage, and others.
You invoke built-in functions the same way that you invoke programmer-defined
functions. However, many built-in functions can return an array of values, whereas
a programmer-defined function can return only an element value. The built-in
names for built-in functions can be explicitly declared with the BUILTIN attribute.
(For more information on the BUILTIN attribute or for the description of any
built-in function, see Chapter 18, “Built-in functions, pseudovariables, and
subroutines,” on page 383.)
108
Enterprise PL/I for z/OS Language Reference
Passing arguments to procedures
Passing arguments to procedures
When a function or a subroutine is invoked, parameters are associated, from left to
right, with the passed arguments.
In general:
v Computational data arguments can be passed to parameters of any
computational data type.
v Program-control data arguments must be passed to parameters of the same type,
with these exceptions.
– Pointer and offset can be passed to each other.
– LIMITED ENTRY can be passed to ENTRY, but ENTRY cannot be passed to
LIMITED ENTRY.
– An array of label constants cannot be used as an argument.
Arguments that require aggregate temporaries derived from structures are not
allowed, unless the structure argument is declared with constant extents.
Expressions in the argument list are evaluated in the invoking block before the
subroutine or function is invoked. A parameter has no storage associated with it. It
is merely a means of allowing the invoked procedure to access storage allocated in
the invoking procedure.
Using BYVALUE and BYADDR
Unless an argument is passed BYVALUE, a reference to an argument, not its value,
is generally passed to a subroutine or function. This is known as passing
arguments by reference, or BYADDR. A reference to a parameter in a procedure is
a reference to the corresponding argument. Any change to the value of a parameter
is actually a change to the value of the corresponding argument. However, this is
not always possible or desirable. Constants, for example, should not be altered by
an invoked procedure. For arguments that should not change, a dummy argument
containing the value of the original argument is passed. Any reference to the
parameter then is a reference to the dummy argument and not to the original
argument.
When you specify BYADDR, the compiler puts the address of the corresponding
argument in the parameter list. When you specify BYVALUE, puts the value of the
argument in the parameter list.
When you specify BYVALUE, a dummy argument is not created; however, as is
also true for dummy arguments, any change to the corresponding parameter in the
called routine will not be visible in the calling routine.
BYVALUE can be specified only for scalar arguments and parameters that have
lengths and sizes known at compile time.
A BYVALUE argument should be one that could reasonably be passed in a register.
Hence its type should be one of
v REAL FIXED BIN
v REAL FLOAT
v POINTER
v OFFSET
v HANDLE
Chapter 5. Program organization
109
BYVALUE and BYADDR
v
v
v
v
v
LIMITED ENTRY
FILE
ORDINAL
CHAR(1)
WCHAR(1)
v ALIGNED BIT(n) with n less than or equal to 8
Using INONLY, INOUT and OUTONLY
Unless an argument is declared with the attribute INONLY or OUTONLY, the
argument is INOUT and is presumed to have a value before it is passed and to be
changed (possibly) by the called code.
When you declare an argument as INONLY, then the argument is presumed to
have a value before it is passed but not to be changed by the called code. Hence a
dummy argument would never need to be created for such an argument.
When you declare an argument as OUTONLY, then the argument is presumed not
to have a value before it is passed but to be set by the called code.
The BYVALUE attribute implies the INONLY attribute. Hence the attributes
OUTONLY and BYVALUE conflict and may not both be specified for the same
argument. However, the ASSIGNABLE attribute is allowed with the BYVALUE
attribute.
The attributes INONLY and OPTIONAL also conflict and may not both be
specified for the same argument.
The explicit use of these attributes makes your code more self-documenting.
Furthermore, it allows the compiler to produce better code and to be more accurate
in reporting possibly uninitialized variables.
Dummy arguments
A dummy argument is created when the argument is any of the following:
v A constant (unless the parameter has the INONLY attribute).
v An expression with operators, parentheses, or function references.
v A variable whose data attributes, alignment attributes, or connected attribute are
different from the attributes declared for the parameter.
This does not apply to noncontrolled parameters when only bounds, lengths, or
size differ and these are declared with asterisks, nor when an expression other
than a constant is used to define the extents of a controlled parameter. In the
latter case, argument and parameter extents are assumed to match.
In the case of an argument and parameter with the PICTURE attribute, a
dummy argument is created unless the picture specifications match exactly, after
any repetition factors are applied. The only exception is that an argument or
parameter with a + sign in a scaling factor matches a parameter or argument
without the + sign.
v A string or area with an adjustable length or size that is associated with a
noncontrolled parameter whose length or size is a constant. Note that under the
RULES(LAXCTL) compiler option, the extents of a CONTROLLED string or
AREA are always changeable, but. under the RULES(NOLAXCTL) compiler
option, the extents of a CONTROLLED string or AREA are changeable unless
declared as constants.
110
Enterprise PL/I for z/OS Language Reference
Dummy arguments
Deriving dummy argument attributes
PL/I derives the attributes of dummy arguments from:
v The attributes declared for the associated parameter in an internal procedure.
v The attributes specified in the parameter descriptor for the associated parameter
in the declaration of the external entry. If there was not a descriptor for this
parameter, the attributes of the constant or expression are used.
v The extents (when specified by an asterisk in a declaration) of the argument for
the bounds of an array, the length of a string, or the size of an area.
Rules for dummy arguments
The following rules apply to dummy arguments:
v If a parameter is an element (that is, a variable that is neither a structure nor an
array), the argument must be an element expression.
v When a VARYING or VARYINGZ string element is passed to a NONVARYING
parameter, whose length is undefined (that is, specified by an asterisk), a
dummy argument with the current length of the original is created.
v Entry variables passed as arguments are assumed to be aligned; therefore, no
dummy argument is created when only the alignments of argument and
parameter differ. See “Generic entries” on page 124, for a description of generic
name arguments for entry parameters.
v If the parameter is of the program-control data type (except locator), the
argument must be a reference of the same data type.
v If a parameter is a locator (pointer or offset), the argument must be a locator. If
the types differ, a dummy argument is created. The parameter descriptor of an
offset parameter must not specify an associated area.
v A noncontrolled parameter can be associated with an argument of any storage
class. However, if more than one generation of the argument exists, the
parameter is associated only with that generation existing at the time of
invocation.
v If the parameter is controlled, you must explicitly state this in the parameter
descriptor for the ENTRY declaration. In addition, a controlled parameter must
always have a corresponding controlled argument that:
– is not subscripted
– is not an element of a structure
– does not cause a dummy to be created
If more than one generation of the argument exists at the time of invocation, the
parameter corresponds to the entire stack of generations in existence.
Consequently, at the time of invocation, a controlled parameter represents the
current generation of the corresponding argument. A controlled parameter can
be allocated and freed in the invoked procedure, allowing the manipulation of
the allocation stack of the associated argument.
If the extents of the controlled parameter are specified as asterisks or
nonrestricted expressions, the original declaration must have extents declared as
nonrestricted expressions.
Passing arguments to the MAIN procedure
The PROCEDURE statement for the main procedure can have a parameter list.
Such parameters require no special considerations in PL/I. However, you must be
aware of any requirements of the invoking program (for example, when not to use
such a parameter as the target of an assignment).
Chapter 5. Program organization
111
Passing arguments to the MAIN procedure
When the invoking program is the operating system and when compiled with the
SYSTEM(MVS) compiler option:
v A single argument is passed to the MAIN procedure, and that parameter must
be declared as CHARACTER VARYING.
v The current length of this parameter is set equal to the argument length at
run-time. So, in the following example:
Tom: proc (Param) options (main);
dcl Param char(100) varying;
storage is allocated only for the current length of the argument.
v The contents of this parameter depend on a second option that may be specified
along with OPTIONS(MAIN):
– If you specify OPTIONS(MAIN NOEXECOPS), then the string passed by the
operating system to PL/I is passed as is to your program. NOEXECOPS is
recommended.
– If you specify only OPTIONS(MAIN), then the string passed by the operating
system to PL/I is stripped of all characters up to and including the first '/'.
This means that if the string contains no '/', then your program receives a
null string.
Begin-blocks
A begin-block is a sequence of statements delimited by a BEGIN statement and a
corresponding END statement. For example:
B: begin;
statement-1
statement-2
.
.
.
statement-n
end B;
BEGIN statement
The BEGIN statement and a corresponding END statement delimit a begin-block.
BEGIN
;
OPTIONS ( options )
OPTIONS option
For begin-block options, refer to “OPTIONS option and attribute” on page 129.
Begin-block activation
Begin-blocks are activated through sequential flow or as a unit in an IF, ON,
WHEN, or OTHERWISE statement.
You can transfer control to a labeled BEGIN statement using the GO TO statement.
Begin-block termination
A begin-block is terminated when control passes to another active block by some
means other than a procedure reference. These means are:
112
Enterprise PL/I for z/OS Language Reference
Begin-block termination
v The END statement for the begin-block is executed. Control continues with the
statement physically following the END, except when the block is an ON-unit.
v A GO TO statement within the begin-block (or within any block internal to it) is
executed, transferring control to the point outside the block.
v A STOP or an EXIT statement is executed.
v Control reaches a RETURN statement that transfers control out of the
begin-block and out of its containing procedure.
A GO TO statement can also terminate other blocks if the transfer point is
contained in a block that did not directly activate the block being terminated. In
this case, all intervening blocks in the activation sequence are terminated. For an
example of this, see the example in “Procedure termination” on page 100.
Entry data
The entry data can be an entry constant or the value of an entry variable.
An entry constant is a name prefixed to a PROCEDURE or ENTRY statement, or a
name declared with the ENTRY attribute and not the VARIABLE attribute. It can
be assigned to an entry variable. In the following example, P, E1, and E2 are entry
constants. Ev is an entry variable.
P:
procedure;
declare Ev entry variable,
(E1,E2) entry;
Ev =
call
Ev =
call
E1;
Ev;
E2;
Ev;
The first CALL statement invokes the entry point E1. The second CALL invokes the
entry point E2.
The following example declares F(5), a subscripted entry variable.
The five entries A, B, C, D, and E are each invoked with the parameters X, Y, and Z.
declare (A,B,C,D,E) entry,
declare F(5) entry variable initial (A,B,C,D,E);
do I = 1 to 5;
call F(I) (X,Y,Z);
end;
When an entry constant that is an entry point of an internal procedure is assigned
to an entry variable, the assigned value remains valid only as long as the block
that the entry constant was internal to remains active (and, for recursive
procedures, remains current).
Entry constants
The appearance of a label prefix to a PROCEDURE or ENTRY statement explicitly
declares an entry constant. A parameter-descriptor list is obtained from the
parameter declarations, if any, and by defaults.
External entry constants must be explicitly declared. This declaration:
v Defines an entry point to an external procedure.
Chapter 5. Program organization
113
Entry constants
v Optionally specifies a parameter-descriptor list (the number of parameters and
their attributes), if any, for the entry point.
v Specifies the attributes of the value that is returned by the procedure if the entry
is a function.
ENTRY
(parameter-descriptor-list)
RETURNS
attribute
OPTIONS(characteristic-list)
EXTERNAL
(environment-name)
The attributes can appear in any order.
ENTRY attribute
For complete ENTRY attribute syntax, refer to “ENTRY attribute” on page 115.
OPTIONS attribute
For complete OPTIONS attribute syntax, refer to “OPTIONS option and
attribute” on page 129.
RETURNS attribute
For complete RETURNS attribute syntax, refer to “RETURNS option and
attribute” on page 138.
EXTERNAL attribute
If you don't specify an environment-name, the name is the same as the
declaration. For a complete description of the EXTERNAL attribute refer to
“INTERNAL and EXTERNAL attributes” on page 157.
Entry variables
An entry variable can contain both internal and external entry values. It can be
part of an aggregate. For structuring and array dimension attributes, refer to
“Arrays” on page 173 and “Structures” on page 177.
ENTRY
(parameter-descriptor-list)
OPTIONS(characteristic-list)
VARIABLE
LIMITED
RETURNS
attribute
EXTERNAL
(environment-name)
The options can appear in any order.
ENTRY attribute
Refer to “ENTRY attribute” on page 115.
114
Enterprise PL/I for z/OS Language Reference
Entry variables
OPTIONS attribute
Refer to “OPTIONS option and attribute” on page 129.
VARIABLE attribute
The VARIABLE attribute establishes the name as an entry variable. This
variable can contain entry constants and variables. Refer to “VARIABLE
attribute” on page 46 for syntax information.
LIMITED attribute
Refer to “LIMITED attribute” on page 123.
RETURNS attribute
Refer to “RETURNS option and attribute” on page 138.
EXTERNAL attribute
Refer to “Scope of declarations” on page 155.
ENTRY attribute
The ENTRY attribute specifies that the name being declared is either an external
entry constant, or an entry variable. It also describes the attributes of the
parameters of the entry point.
Chapter 5. Program organization
115
ENTRY
ENTRY
,
( parameter-descr
structure-union-descr
)
parameter-descr:
attribute
*
ALIGNED
UNALIGNED
OPTIONAL
ASSIGNABLE
NONASSIGNABLE
INOUT
INONLY
OUTONLY
CONNECTED
NONCONNECTED
BYADDR
BYVALUE
structure-union-descr:
1 ,
attribute
OPTIONAL
level
attribute
ENTRY
The ENTRY attribute, without a parameter descriptor list, is implied by the
RETURNS attribute.
parameter-descr (parameter-descriptor)
A parameter descriptor list can be given to describe the attributes of the
parameters of the associated external entry constant or entry variable. It is
used for argument and parameter attribute matching and the creation of
dummy arguments.
If no parameter descriptor list is given, the default is for the argument
attributes to match the parameter attributes. Thus, the parameter descriptor list
must be supplied if argument attributes do not match the parameter attributes.
Each parameter descriptor corresponds to one parameter of the entry point
invoked and, if given, specifies the attributes of that parameter.
The parameter descriptors must appear in the same order as the parameters
they describe. If a descriptor is absent, the default is for the argument to match
the parameter.
116
Enterprise PL/I for z/OS Language Reference
ENTRY
If a descriptor for a parameter is not required, the absence of the descriptor
must be indicated by an asterisk. For example:
Indicates four arguments.
entry(character(10),*,*,fixed dec)
Indicates one argument.
entry(*)
entry( )
entry
Specifies that the entry name must never
have any arguments.
Specifies that it can have any number of
arguments.
Indicates two arguments.
entry(float binary,*)
attribute
The allowed attributes are any of the data attributes listed under “Data
attributes” on page 18. The attributes can appear in any order in a parameter
descriptor. For an array parameter-descriptor, the dimension attribute must be
the first one specified.
*
An asterisk specifies that, for that parameter, any data type is allowed. The
only attributes which are valid following the asterisk are:
v ALIGNED or UNALIGNED
v ASSIGNABLE or NONASSIGNABLE
v BYADDR or BYVALUE
v CONNECTED or NONCONNECTED
v INONLY, INOUT, or OUTONLY
v OPTIONAL
No conversions are done.
OPTIONAL
This attribute is discussed in “OPTIONAL attribute” on page 118.
structure-union-descr (structure-union-descriptor)
For a structure-union descriptor, the descriptor level-numbers need not be the
same as those of the parameter, but the structuring must be identical. The
attributes for a particular level can appear in any order.
Defaults are not applied if an asterisk is specified. For example, in the following
declaration defaults are applied only for the second parameter.
dcl X entry(* optional, aligned); /* defaults applied for 2nd parm */
Extents (lengths, sizes, and bounds) in parameter descriptors must be specified as
constants or as asterisks. Controlled parameters must have asterisks.
RETURNS attribute implies the ENTRY attribute. For example:
Example parameter descriptors
Declarations for example descriptors
Chapter 5. Program organization
117
ENTRY
Example parameter descriptors
Test:
procedure (A,B,C,D,E,F);
declare A
B
C
1
fixed decimal (5),
float binary (21),
pointer,
D,
2 P,
2 Q,
3 R fixed decimal,
1 E,
2 X,
2 Y,
3 Z,
F(4) character (10);
end Test;
Declarations for example descriptors
declare Test entry
(decimal fixed (5),
binary float (21),
*,
1,
2,
2,
3 decimal fixed,
*,
(4) char(10));
In the previous example, the parameter C, and the structure parameter E do not
have descriptors.
OPTIONAL attribute
OPTIONAL can be specified as part of the parameter-descriptor list or as an
attribute in the parameter declaration.
OPTIONAL
OPTIONAL arguments can be omitted in calls and function references by
specifying an asterisk for the argument. An omitted item can be anywhere in the
argument list, including at the end. However, the omitted item is counted as an
argument. With its inclusion in an entry, the number of arguments must not exceed
the maximum number allowed for the entry.
Using OPTIONAL and BYVALUE for the same item is invalid, unless the item is a
LIMITED ENTRY.
The receiving procedure can use the OMITTED or PRESENT built-in function to
determine if an OPTIONAL parameter/argument was omitted in the invocation of
the entry. (For more information on the OMITTED built-in function, see
“OMITTED” on page 554.)
You can pass an omitted OPTIONAL parameter as an argument to an entry if the
corresponding parameter in the declaration for that entry is also OPTIONAL.
If the final parameters in an ENTRY declaration are declared as OPTIONAL, then
the ENTRY may be invoked with those parameters completely omitted: it is not
even necessary to specify the appropriate number of asterisks. So, for example, if
an ENTRY is declared as having 5 parameters, of which the last 2 have the
OPTIONAL attribute, then it may be invoked with 3, 4 or 5 arguments.
You may omit such trailing OPTIONAL parameters both when the ENTRY invoked
is explicitly declared and when the ENTRY invoked is a nested subprocedure. Note
118
Enterprise PL/I for z/OS Language Reference
OPTIONAL
also that unless the ENTRY has the OPTIONS(ASSEMBLER) attribute, the
generated code will supply null pointers for the omitted parameters.
Figure 5 shows both valid and invalid CALL statements for the procedure Vrtn.
Vrtn determines if OPTIONAL parameters were omitted, and takes the appropriate
Caller: proc;
dcl Vrtn entry (
fixed bin,
ptr optional,
float,
* optional);
/*
The following calls are valid:
call
call
call
call
call
/*
Vrtn(10,
Vrtn(10,
Vrtn(10,
Vrtn(10,
Vrtn(10,
*/
*, 15.5, ’abcd’);
*, 15.5, *);
addr(x), 15.5, *);
*, 15.5);
addr(x), 15.5);
The following calls are invalid:
*/
call Vrtn(*, addr(x));
call Vrtn(10,addr(x));
call Vrtn(10);
call Vrtn;
end Caller;
Vrtn: proc (Fb, P, Fl, C1);
dcl Fb fixed bin,
P ptr optional,
Fl float,
C1 char(8) optional;
if ¬omitted(C1) then display (C1);
if ¬omitted(P) then P=P+10;
end;
Figure 5. Valid and invalid call statements
action.
LIST attribute
LIST can be specified on the last parameter in a parameter-descriptor list or as an
attribute on the last parameter to a procedure.
LIST
When the LIST attribute is specified in an entry declaration, it indicates that zero
or more additional arguments may be passed to that entry. For example, the
following declare specifies that vararg must be invoked with one character
varyingz parameter and may be invoked with any number of other parameters.
dcl vararg
external
entry( list byaddr char(*) varz nonasgn )
options( nodescriptor byvalue );
Chapter 5. Program organization
119
LIST
When the LIST attribute is specified in the declaration of the last parameter in a
procedure, it indicates that zero or more additional arguments may have been
passed to that procedure.
When the LIST attribute is specified, no descriptors are allowed, and
OPTIONS(NODESCRIPTOR) must be specified on its PROCEDURE statement and
on its corresponding ENTRY declaration.
The address of the first of these additional parameters may be obtained via the
VARGLIST built-in function. This address may be used to obtain the addresses of
any additional parameters as follows:
v if the additional parameters to this procedure were passed BYVALUE,
successively incrementing this initial address by the value returned by the
VARGSIZE built-in function will return the addresses of any additional
parameters
v if the additional parameters to this procedure were passed byaddr, successively
incrementing this initial address by the size of a pointer will return the
addresses of any additional parameters
The following sample program, which implements a simple version of printf,
illustrates how to use the LIST attribute. The routine varg1 illustrates how to walk
a variable argument list with BYVALUE parameters, while varg2 illustrates how to
walk such a list with byaddr parameters.
120
Enterprise PL/I for z/OS Language Reference
LIST
*process rules(ans) dft(ans) gn;
vararg: proc options(main);
dcl i1
dcl i2
dcl d1
fixed bin(31) init(1729);
fixed bin(31) init(6);
float bin(53) init(17.29);
dcl varg1
ext entry( char(*) varz byaddr list )
options(byvalue nodescriptor );
ext entry( char(*) varz byaddr list )
options(byaddr nodescriptor );
dcl varg2
call
call
call
call
varg1(
varg1(
varg1(
varg1(
’test byvalue’ );
’test1 parm1=%i’, i1 );
’test2 parm1=%i parm2=%i’, i1, i2 );
’test3 parm1=%d’, d1 );
call
call
call
call
end;
varg2(
varg2(
varg2(
varg2(
’test byaddr’ );
’test1 parm1=%i’, i1 );
’test2 parm1=%i parm2=%i’, i1, i2 );
’test3 parm1=%d’, d1 );
*process ;
varg1:
proc( text )
options( nodescriptor byvalue );
dcl text
list byaddr nonasgn varz char(*);
dcl
dcl
dcl
dcl
dcl
dcl
dcl
dcl
dcl
dcl
fixed bin;
fixed bin;
fixed bin;
pointer;
pointer;
fixed bin(31) based;
float bin(53) based;
float bin(64) based;
char(32767) based;
char(1) based;
jx
iz
ltext
ptext
p
i
d
q
chars
ch
Figure 6. Sample program illustrating LIST attribute
Chapter 5. Program organization
121
LIST
ptext = addr(text);
ltext = length(text);
iz = index( substr(ptext->chars,1,ltext), ’%’ );
p = varglist();
do while( iz > 0 );
if iz = 1 then;
else
put edit( substr(ptext->chars,1,iz-1) )(a);
ptext += iz;
ltext -= iz;
select( ptext->ch );
when( ’i’ )
do;
put edit( trim(p->i) )(a);
p += vargsize( p->i );
end;
when( ’d’ )
do;
put edit( trim(p->d) )(a);
p += vargsize( p->d );
end;
end;
ptext += 1;
ltext -= 1;
if ltext <= 0 then leave;
iz = index( substr(ptext->chars,1,ltext), ’%’ );
end;
if ltext = 0 then;
else
put edit( substr(ptext->chars,1,ltext) )(a);
put skip;
end;
Sample program illustrating LIST attribute
122
Enterprise PL/I for z/OS Language Reference
LIST
*process ;
varg2:
proc( text )
options( nodescriptor byaddr );
dcl text
list byaddr nonasgn varz char(*);
dcl
dcl
dcl
dcl
dcl
dcl
dcl
dcl
dcl
dcl
dcl
fixed bin;
fixed bin;
fixed bin;
pointer;
pointer;
pointer based;
fixed bin(31) based;
float bin(53) based;
float bin(64) based;
char(32767) based;
char(1) based;
jx
iz
ltext
ptext
p
p2
i
d
q
chars
ch
ptext = addr(text);
ltext = length(text);
iz = index( substr(ptext->chars,1,ltext), ’%’ );
p = varglist();
do while( iz > 0 );
if iz = 1 then;
else
put edit( substr(ptext->chars,1,iz-1) )(a);
ptext += iz;
ltext -= iz;
select( ptext->ch );
when( ’i’ )
do;
put edit( trim(p->p2->i) )(a);
p += size( p );
end;
when( ’d’ )
do;
put edit( trim(p->p2->d) )(a);
p += size( p );
end;
end;
ptext += 1;
ltext -= 1;
if ltext <= 0 then leave;
iz = index( substr(ptext->chars,1,ltext), ’%’ );
end;
if ltext = 0 then;
else
put edit( substr(ptext->chars,1,ltext) )(a);
put skip;
end;
Sample program illustrating LIST attribute
LIMITED attribute
The LIMITED attribute indicates that the entry variable has only non-nested entry
constants as values. A entry variable that is not LIMITED can have any entry
constants as values.
Chapter 5. Program organization
123
LIMITED
LIMITED
Example
Example: proc options(reorder reentrant);
dcl (Read, Write) entry;
dcl FuncRtn(2) entry limited
static init (Read, Write);
dcl (Prt1) entry;
dcl PrtRtn(2) entry variable limited
static init (Prt1,
/* legal
*/
Prt2);
/* illegal */
Prt2:
proc;
.
.
.
end Prt2;
end Example;
A LIMITED static entry variable can be initialized with the value of a non-nested
entry constant, thus allowing generation of more efficient code. It also uses less
storage than a non-LIMITED entry variable.
Generic entries
A generic entry declaration specifies a generic name for a set of entry references
and their descriptors. During compilation, invocation of the generic name is
replaced by one of the entries in the set.
GENERIC attribute
The generic name must be explicitly declared with the GENERIC attribute.
124
Enterprise PL/I for z/OS Language Reference
GENERIC attribute
generic-name GENERIC (
references
, entry-ref
OTHERWISE
) ;
references
,
,
entry-ref WHEN ( )
generic-descriptor
*
generic-descriptor:
data-attributes
ALIGNED
UNALIGNED
ASSIGNABLE
(1)
NONASSIGNABLE
INOUT
INONLY
OUTONLY
CONNECTED
(1)
HEXADEC
IEEE
BIGENDIAN
LITTLEENDIAN
OPTIONAL
NONCONNECTED
Notes:
1
If specified, this keyword is ignored.
Abbreviation: OTHER for OTHERWISE
For the general declaration syntax, see “DECLARE statement” on page 152.
entry-ref
Must not be subscripted or defined. The same entry reference can appear more
than once within a single GENERIC declaration with different lists of
descriptors.
generic-descriptor
Corresponds to a single argument. It specifies an attribute that the
corresponding argument must have so that the associated entry reference can
be selected for replacement.
Structures or unions cannot be specified.
Where a descriptor is not required, its absence must be indicated by an
asterisk.
The descriptor that represents the absence of all arguments in the invoking
statement is expressed by omitting the generic descriptor in the WHEN clause
of the entry. It has the form:
generic (... entry1 when( ) ...)
data-attributes
Listed in “Data types and attributes” on page 17.
Chapter 5. Program organization
125
GENERIC attribute
ALIGNED and UNALIGNED
Discussed in “ALIGNED and UNALIGNED attributes” on page 164.
ASSIGNABLE and NONASSIGNABLE
Discussed in “ASSIGNABLE and NONASSIGNABLE attributes” on page 258.
CONNECTED and NONCONNECTED
Discussed in “CONNECTED and NONCONNECTED attributes” on page 261.
HEXADEC and IEEE
Discussed in “HEXADEC and IEEE attributes” on page 260.
BIGENDIAN and LITTLEENDIAN
Discussed in “BIGENDIAN and LITTLEENDIAN attributes” on page 259.
OPTIONAL
Discussed in “OPTIONAL attribute” on page 118.
When an invocation of a generic name is encountered, the number of arguments
specified in the invocation and their attributes are compared with descriptor list of
each entry in the set. The first entry reference for which the descriptor list matches
the arguments both in number and attributes replaces the generic name.
In the following example, an entry reference that has exactly two descriptors with
the attributes DECIMAL or FLOAT, and BINARY or FIXED is searched for.
declare Calc generic (
Fxdcal when (fixed,fixed),
Flocal when (float,float),
Mixed when (float,fixed),
Error otherwise);
Dcl
X decimal float (6),
Y binary fixed (15,0);
Z = X+Calc(X,Y);
If an entry with the exact number of descriptors with the exact attributes is not
found, the entry with the OTHERWISE clause is selected if present. In the previous
example, Mixed is selected as the replacement.
In a similar manner, an entry can be selected based on the dimensionality of the
arguments.
dcl
D generic (D1
D2
A(2),
B(3,5);
call D(A);
/*
call D(B);
/*
when ((*))),
when((*,*))),
D1 selected because A has one dimension */
D2 selected because B has two dimensions */
If all of the descriptors are omitted or consist of an asterisk, the first entry
reference with the correct number of descriptors is selected.
An entry expression used as an argument in a reference to a generic value matches
only a descriptor of type ENTRY. If there is no such description, the program is in
error.
126
Enterprise PL/I for z/OS Language Reference
Entry invocation or entry value
Entry invocation or entry value
There are times when it might not be apparent whether an entry value itself will
be used or the value returned by the entry invocation will be used. The following
table and example help you understand which happens when.
If the entry reference . . .
Is a built-in function
Has an argument list, even if null
Is referenced in a CALL statement
Has no argument list and is not referenced in
a CALL statement
It is . . .
Invoked
Invoked
Invoked
Not Invoked
In the following example, A is invoked, B(C) passes C as an entry value, and
D( C() ) invokes C.
dcl ( A, B, C returns (fixed bin), D) entry;
call A;
call B(C);
call D( C() );
/* A is invoked
/* C is passed as an entry value
/* C is invoked
*/
*/
*/
In the following example, the first assignment is invalid because it represents an
attempt to assign an entry constant to an integer. The second assignment is valid.
dcl A fixed bin,
B entry returns ( fixed bin );
A = B;
A = B();
CALL statement
The CALL statement invokes a subroutine.
CALL
entry-reference
generic-name
built-in-name
(
) ;
,
argument
*
entry-reference
Specifies that the name of the subroutine to be invoked is declared with the
ENTRY attribute (discussed in “Entry data” on page 113).
generic-name
Specifies that the name of the subroutine to be invoked is declared with the
GENERIC attribute (discussed in “Generic entries” on page 124).
built-in name
Specifies the name of the subroutine to be invoked is declared with the
BUILTIN attribute (see “BUILTIN attribute” on page 386).
argument
Is an element, an element expression, or an aggregate to be passed to the
invoked subroutine. See “Passing arguments to procedures” on page 109.
Chapter 5. Program organization
127
CALL
References and expressions in the CALL statement are evaluated in the block in
which the call is executed. This includes execution of any ON-units entered as the
result of the evaluations.
RETURN statement
The RETURN statement terminates execution of the subroutine or function
procedure that contains the RETURN statement and returns control to the invoking
procedure. Control is returned to the point immediately following the invocation
reference.
The RETURN statement with an expression should not be used within a procedure
with OPTIONS(MAIN).
A RETURN statement without an expression is invalid in a procedure with the
RETURNS option. Conversely, a RETURN statement with an expression is invalid
in a procedure without the RETURNS option.
A procedure with the RETURNS option must contains at least one RETURN
statement (with an expression, of course).
Return from a subroutine
To return from a subroutine, the RETURN statement syntax is:
RETURN ;
If the RETURN statement terminates the main procedure, the FINISH condition is
raised prior to program termination.
Return from a function
To return from a function, the RETURN statement syntax is:
RETURN (expression) ;
The value returned to the function reference is the value of the expression
specified, converted to conform to the attributes specified in the RETURNS option
of the ENTRY or PROCEDURE statement at which the function was entered. For
example:
F: procedure returns(fixed bin(15));
.
.
.
G: entry returns(fixed dec(7,2));
.
.
.
dcl D fixed bin(31);
.
.
.
return (D);
128
Enterprise PL/I for z/OS Language Reference
Return from a function
If this function was entered at F, then D is converted to the attributes specified in
the RETURNS option for the procedure F (FIXED BIN(15)). But, if this function was
entered at G, then D is converted to the attributes specified in the RETURNS option
for the entry G (FIXED DEC(7,2)).
You cannot specify an expression for the RETURN statement in a begin-block.
OPTIONS option and attribute
The OPTIONS option can be specified on PACKAGE, PROCEDURE, ENTRY, and
BEGIN statements. The OPTIONS attribute can be specified on ENTRY
declarations. It is used to specify processing characteristics that apply to the block
and the invocation of a procedure. The options shown in the following syntax
diagrams are listed alphabetically and discussed starting in 132.
BEGIN statement
ORDER
OPTIONS ( )
REORDER
NOCHARGRAPHIC
CHARGRAPHIC
NOINLINE
INLINE
Chapter 5. Program organization
129
OPTIONS option and attribute
ENTRY declaration
OPTIONS ( )
ASSEMBLER
RETCODE
COBOL
FORTRAN
FETCHABLE
BYADDR
BYVALUE
DESCRIPTOR
NODESCRIPTOR
LINKAGE ( linkage )
IRREDUCIBLE
REDUCIBLE
NOMAP
parameter-list
NOMAPIN
parameter-list
NOMAPOUT
parameter-list
130
Enterprise PL/I for z/OS Language Reference
OPTIONS option and attribute
ENTRY statement
OPTIONS ( REENTRANT
)
ASSEMBLER
RETCODE
COBOL
FORTRAN
BYADDR
BYVALUE
DESCRIPTOR
NODESCRIPTOR
DLLINTERNAL
LINKAGE(linkage)
NOMAP
parameter-list
NOMAPIN
parameter-list
NOMAPOUT
parameter-list
IRREDUCIBLE
REDUCIBLE
PACKAGE statement
NOCHARGRAPHIC
OPTIONS ( )
CHARGRAPHIC
ORDER
REORDER
REENTRANT
Chapter 5. Program organization
131
OPTIONS option and attribute
PROCEDURE statement
OPTIONS (
)
ASSEMBLER
COBOL
FORTRAN
FETCHABLE
MAIN
NOEXECOPS
BYADDR
BYVALUE
NOCHARGRAPHIC
CHARGRAPHIC
DESCRIPTOR
NODESCRIPTOR
DLLINTERNAL
FROMALIEN
LINKAGE ( linkage
)
NOMAP
parameter-list
NOMAPIN
parameter-list
NOMAPOUT
parameter-list
NOINLINE
INLINE
ORDER
REORDER
IRREDUCIBLE
REDUCIBLE
REENTRANT
RETCODE
WINMAIN
The options are separated by blanks or commas. They can appear in any order.
ASSEMBLER
Abbreviation: ASM
The ASSEMBLER option has the same effect as NODESCRIPTOR.
If a procedure has the ASSEMBLER option, then upon exit from that
procedure, the PLIRETV() value will be used as the return value for the
procedure.
A PROCEDURE or ENTRY statement that specifies OPTIONS(ASSEMBLER)
will have LINKAGE(SYSTEM) unless a different linkage is explicitly specified.
For more information, refer to the Programming Guide.
132
Enterprise PL/I for z/OS Language Reference
OPTIONS option and attribute
BYADDR or BYVALUE
These specify how arguments and parameters are passed and received.
BYADDR is the default.
BYVALUE can be specified only for scalar arguments and parameters that have
known lengths and sizes.
The BYVALUE and BYADDR attributes can also be specified in the description
list of an entry declaration and in the attribute list of a parameter declaration.
Specifying BYVALUE or BYADDR in an entry or a parameter declaration
overrides the option specified in an OPTIONS statement.
The following examples show BYVALUE and BYADDR in both entry
declarations and in the OPTIONS statement. The examples assume that the
compiler option DEFAULT(BYADDR) is in effect.
Example 1
MAINPR: proc options(main);
dcl D entry (fixed bin byaddr,
ptr,
char(4) byvalue)
options(byvalue);
dcl E2 entry;
dcl Length fixed bin,
P
pointer,
Name
char(4);
/*
byvalue not needed
*/
/* default(byaddr) in effect */
call D(Length, P, Name);
/* Length is passed byaddr */
/* P is passed by value */
/* Name is passed by value */
call E2(P);
/* P is passed by address */
D: proc(I, Q, C)
options(byvalue);
dcl I fixed bin byaddr,
Q ptr,
C char(4) byvalue;
E2: proc(Q);
dcl Q ptr;
Example 2
dcl F entry (fixed bin byaddr,
ptr,
char(4) byvalue)
options(byaddr);
dcl E3 entry;
dcl E4 entry (fixed bin byvalue);
/*
byaddr not needed
*/
call F(Length, P, Name);
/* Length is passed byaddr */
/* P is passed byaddr
*/
/* Name is passed by value */
call E3(Name);
call E4(Length);
/* Name is passed byaddr
*/
/* Length is passed by value */
Chapter 5. Program organization
133
OPTIONS option and attribute
F: proc(I,P,C) options(byaddr);
dcl I fixed bin byaddr;
dcl P ptr byaddr;
dcl C char(4) byvalue;
/* byaddr not needed
/* byaddr not needed
/* byvalue needed
*/
*/
*/
E3: proc(L);
dcl L char(4);
E4: proc(N);
dcl N fixed bin byvalue;
CHARGRAPHIC or NOCHARGRAPHIC
Abbreviations: CHARG, NOCHARG
The default for an external procedure is NOCHARG. Internal procedures and
begin-blocks inherit their defaults from the containing procedure.
When CHARG is in effect, the following semantic changes occur:
v All character string assignments are considered to be mixed character
assignments.
v STRINGSIZE condition causes MPSTR built-in function to be used.
STRINGSIZE must be enabled for character assignment that can cause
truncation and intelligent DBCS truncation is required. (For information on
the MPSTR BUILTIN see “MPSTR” on page 546.) For example:
Name: procedure options(chargraphic);
dcl A char(5);
dcl B char(8);
/* the following statement...
*/
(stringsize): A=B;
/*...is logically transformed into...
*/
A=mpstr(B,’vs’,length(A));
When NOCHARG is in effect, no semantic changes occur.
COBOL
This option has the same effects as NODESCRIPTOR (see below), but
additionally OPTIONS(COBOL)
v implies LINKAGE(SYSTEM) unless a different linkage is specified on the
entry declaration or procedure statement.
v permits the use of the NOMAP, NOMAPIN and NOMAPOUT options
v implies, if specified on a procedure statement, that upon exit from that
procedure, the PLIRETV() value will be used as the return value for the
procedure.
COBOL and MAIN must not be specified together.
DESCRIPTOR or NODESCRIPTOR
These indicate whether the procedure specified in the entry declaration or
procedure statement will be passed a descriptor list when it is invoked.
If DESCRIPTOR appears, the compiler passes descriptors, if necessary.
If NODESCRIPTOR appears, the compiler does not pass descriptors.
134
Enterprise PL/I for z/OS Language Reference
OPTIONS option and attribute
If neither appears, DESCRIPTOR is assumed only when one of the invoked
procedure's parameters is a string, array, area, structure, or union.
It is an error for NODESCRIPTOR to appear on a procedure statement or entry
declaration in which any of the parameters or elements:
v Use the asterisk ( * ) to indicate the extents, length, or size
v If any parameter is NONCONNECTED
However, NODESCRIPTOR is allowed if the parameters with unspecified
extents are INONLY VARYING or VARYINGZ strings.
DLLINTERNAL
This option indicates that the procedure or entry is intended to be internal to a
DLL and, consequently, that its name should not be included in any definition
side file generated by the compiler.
The DLLINTERNAL attribute is valid only on EXTERNAL procedures or
ENTRYs.
FETCHABLE
This option indicates the procedure is dynamically fetched if necessary before
invoking it.
The FETCHABLE attribute is not valid on INTERNAL procedures.
FETCHABLE procedures should not be linked into a load module that contains
a MAIN procedure.
FORTRAN
This option causes no descriptors to be passed except for character variables.
FORTRAN and MAIN must not be specified together.
FROMALIEN
This option indicates that this procedure can be called from a non-PL/I
routine. FROMALIEN can be specified on any procedure; however, this would
incur unnecessary overhead.
INLINE or NOINLINE
INLINE and NOINLINE are optimization options that can be specified for
begin-blocks and non-nested level-one procedures in a package.
INLINE indicates that whenever the begin-block or procedure is invoked in the
package that defines it, the code for the begin-block or procedure should be
executed inline at the point of its invocation. Even if INLINE is specified, the
compiler can choose not to inline the begin-block or procedure.
NOINLINE indicates that the begin-block or procedure is never to be executed
inline.
OPTIONS(INLINE) makes it easier to write well-structured, readable code. For
instance, a program could be written as a series of calls to a set of procedures,
and OPTIONS(INLINE) could be used to eliminate the overhead of actually
calling these procedures one by one.
If a procedure or begin-block is executed inline, the values returned by built-in
functions like ONLOC return the name of the procedure into which it is
inlined. Similarly, traceback information does not include the called procedure.
Some procedures and begin-blocks are never inlined. These include, but are not
limited to:
v Procedures and begin-blocks in packages in which condition enablement
varies
Chapter 5. Program organization
135
OPTIONS option and attribute
v Procedures and begin-blocks containing ON or REVERT statements
v Procedures and begin-blocks containing data-directed input/output
statements
v Procedures and begin-blocks containing assignments or comparisons of
ENTRY, FORMAT, or LABEL constants
If a non-nested procedure with the INLINE option is not external and not
referenced, no code will be generated for it. If neither INLINE nor NOINLINE
is specified for a procedure, the option is set by the DEFAULT compiler option.
For more information about using INLINE and NOINLINE, refer to the
Programming Guide.
LINKAGE
This option specifies the calling convention used and may be specified on
PROCEDURE statements and ENTRY declarations.
CDECL (INTEL only)
This option specifies the CDECL linkage convention used by 32-bit C
compilers.
OPTLINK
This option is the default, and is the fastest linkage convention. It is not
standard linkage for most compilers.
STDCALL (Windows Only)
This option specifies the STDCALL linkage which is the standard linkage
convention used by all Windows APIs.
SYSTEM
This option is the calling convention which should be used for calls to the
operating system. Although this option is slower than OPTLINK, it is
standard for all MVS and AIX applications.
For more information about calling conventions, refer to the Programming
Guide.
MAIN
This option indicates that this external procedure is the initial procedure of a
PL/I program. MAIN is valid, and required, only on one external procedure
per program. The operating system control program invokes it as the first step
in the execution of that program.
A PL/I program that contains more than one procedure with OPTIONS(MAIN)
can produce unpredictable results.
Neither COBOL nor FORTRAN is valid when MAIN is specified.
NOEXECOPS
The NOEXECOPS option is valid only with the MAIN option. It specifies that
the run-time options will not be specified on the command or statement that
invokes the program. Only parameters for the main procedure will be
specified.
NOMAP, NOMAPIN, NOMAPOUT
These options prevent the automatic manipulation of data aggregates at the
interface between either COBOL or FORTRAN and PL/I.
Each option argument-list may specify the parameters to which the option
applies. Parameters may appear in any order and are separated by commas or
blanks. If there is no argument-list for an option, the default list is all the
parameters of the entry name.
136
Enterprise PL/I for z/OS Language Reference
OPTIONS option and attribute
NOMAP, NOMAPIN and NOMAPOUT may all appear in the same OPTIONS
specification. This specification should not include the same parameter in more
than one specified or default argument list.
These options are accepted but ignored unless the COBOL option applies.
ORDER or REORDER
ORDER and REORDER are optimization options that are specified for a
procedure or begin-block.
ORDER indicates that only the most recently assigned values of variables
modified in the block are available for ON-units that are entered because of
computational conditions raised during statement execution and expressions in
the block.
The REORDER option allows the compiler to generate optimized code to
produce the result specified by the source program when error-free execution
takes place.
For more information on using the ORDER and REORDER options, refer to the
Programming Guide.
If neither option is specified for the external procedure, the default is set by the
DEFAULT compiler option. Internal blocks inherit ORDER or REORDER from
the containing block.
REDUCIBLE or IRREDUCIBLE
Abbreviations: RED, IRRED
REDUCIBLE indicates that a procedure or entry need not be invoked multiple
times if the argument(s) stays unchanged, and that the invocation of the
procedure has no side effects.
For example, a user-written function that computes a result based on
unchanging data should be declared REDUCIBLE. A function that computes a
result based on changing data, such as a random number or time of day,
should be declared IRREDUCIBLE.
REENTRANT
This option is ignored. On the Intel and AIX platforms, all PL/I programs are
reentrant. On the z/OS platform, all programs compiled with the RENT
compiler option are reentrant, and other programs are reentrant if they do not
alter any static variables (which may require use of the NOWRITABLE
compiler option).
RETCODE
This option specifies that if the ENTRY point also has the ASM or COBOL
option, then the ENTRY will return a value that will be saved, after the ENTRY
is invoked, as the PL/I return code. Essentially, after such an ENTRY is
invoked, its return value will be passed to the PLIRETC subroutine.
WINMAIN (Windows only)
This option automatically implies LINKAGE(STDCALL) and EXT('WinMain').
The associated routine should contain four parameters:
1. An instance handle
2. A previous handle
3. A pointer to the command line
4. An integer to be passed to ShowWindow.
Chapter 5. Program organization
137
OPTIONS option and attribute
These are the same four parameters expected by the C WinMain and the calls
made from this routine are the same as those expected from a C routine.
RETURNS option and attribute
If a procedure is a function procedure, you must specify the RETURNS option on
the procedure statement. Further, in the invoking procedure or package, you must
declare such a procedure as an entry with the RETURNS attribute. The RETURNS
option and the RETURNS attribute are used to specify the attributes of the value
that is being returned. The attributes in the RETURNS option must match the
attributes in the RETURNS attribute.
Procedures that are subroutines (and are therefore invoked using the CALL
statement) must not have the RETURNS option on the procedure statement and
their entry declaration must not have the RETURNS attribute.
RETURNS ( attribute
)
If more than one attribute is specified, they must be separated by blanks (except
attributes such as precision that are enclosed in parentheses).
The attributes are specified in the same way as they are in a declare statement.
Defaults are applied in the normal way.
The attributes that can be specified are any of the data attributes and alignment
attributes for scalar variables (as shown in Table 8 on page 21). ENTRY variables
must have the LIMITED attribute. In addition, you can specify the TYPE attribute
to name user-defined types, ordinals, and typed structures and unions.
String lengths and area sizes must be specified by constants. The returned value
has the specified length or size.
BYADDR and BYVALUE can also be specified in the list of attributes for
RETURNS. The BYADDR attribute must be in effect if a procedure contains any
ENTRY statements and the procedure or any of its secondary entry points returns:
v no value, or
v an aggregate value
On z/OS, BYADDR is the default for RETURNS. If a C function is called,
BYVALUE must be specified in the list of attributes for RETURNS. For a discussion
of these attributes, see “Using BYVALUE and BYADDR” on page 109.
138
Enterprise PL/I for z/OS Language Reference
Chapter 6. Type definitions
User-defined types (aliases). . . .
DEFINE ALIAS statement . . .
Example . . . . . . . .
Defining ordinals . . . . . . .
DEFINE ORDINAL statement . .
Example . . . . . . . .
Defining typed structures and unions
HANDLE attribute . . . . .
Declaring typed variables . . . .
TYPE attribute . . . . . . .
Examples . . . . . . . .
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
139
139
140
140
140
141
142
143
144
144
144
ORDINAL attribute . . . . .
Typed structure qualification . . .
Using the '.' operator . . . . .
Combinations of arrays and typed
unions. . . . . . . . . .
Using handles . . . . . . .
Using ordinals . . . . . . . .
Example . . . . . . . . .
Example . . . . . . . .
Example . . . . . . . .
Type functions . . . . . . . .
. . . . .
. . . . .
. . . . .
structures or
. . . . .
. . . . .
. . . . .
. . . . .
. . . . .
. . . . .
. . . . .
145
145
146
146
147
147
148
148
149
150
In a programming language, a type is a description of a set of values and a set of
allowed operations on those values. PL/I has many built-in data types. Each type
can specify a number of elementary attributes. Chapter 2, “Data elements,” on page
15 describes these built-in data types.
PL/I allows you to define your own types using the built-in data types. This
chapter discusses user-defined types (aliases, ordinals, structures, and unions),
declarations of variables with these types, handles, and type functions.
All types that are created by DEFINE statements follow the same scoping rules
that apply to names in DECLARE statements. For example, an ORDINAL defined
in a procedure is known in all child procedures of that procedure, but not in any
of its sister or parent procedures. Therefore, if a procedure returns a type, that type
must be defined in a parent procedure or at the package level.
User-defined types (aliases)
An alias is a type name that can be used wherever an explicit data type is allowed.
Using the DEFINE ALIAS statement, you can define an alias for a collection of
data attributes. In this way, you can assign meaningful names to data types and
improve the understandability of a program. By defining an alias, you can also
provide a shorter notation for a set of data attributes, which can decrease
typographical errors.
DEFINE ALIAS statement
The DEFINE ALIAS statement specifies a name that can be used as a synonym for
the set of data type attributes you give to the alias.
,
DEFINE ALIAS alias-name attribute
;
alias-name
Specifies the name that can be used wherever the explicit data type defined by
the specified attributes is allowed
© Copyright IBM Corp. 1999, 2012
139
DEFINE ALIAS
attributes
The attributes that can be specified are any of the attributes for variables that
can be returned by a function (for example, those attributes valid in the
RETURNS option and attribute). These valid attributes are listed in Table 8 on
page 21. Therefore, you cannot specify an alias for an array or a structured
attribute list. However, you can specify an alias for a type that is defined in a
DEFINE ORDINAL, or DEFINE STRUCTURE statement (see “DEFINE
ORDINAL statement” and “Defining typed structures and unions” on page
142), or in another DEFINE ALIAS statement. Also, as in the RETURNS option
and attribute, any string lengths or area sizes must be restricted expressions.
Missing data attributes are supplied using PL/I defaults.
Example
define alias Name char(31) varying;
define alias Salary fixed dec(7);
/* real by default
*/
define alias Zip
char(5)
/* nonvarying by default */
Whenever Name is used in a DECLARE statement, it has the attributes char(31)
varying.
Defining ordinals
An ordinal is a named set of ordered values. Using the DEFINE ORDINAL
statement, you can define an ordinal and assign meaningful names to be used to
refer to that set. For example, you can define an ordinal called “color”. The “color”
ordinal could include the members “red”, “yellow”, “blue”, etc. The members of
the “color” set can then be referred to by these names instead of by their
associated fixed binary value, making code much more self-documenting.
Furthermore, a variable declared with the ordinal type can be assigned and
compared only with an ordinal of the same type, or with a member of that ordinal
type. This automatic checking provides for better program reliability.
DEFINE ORDINAL statement
The DEFINE ORDINAL statement specifies a named type representing a set of
named ordered values.
DEFINE ORDINAL ordinal-type-name (
ordinal-value-list
;
PRECISION (integer)
)
SIGNED
UNSIGNED
ordinal-value-list:
,
member
VALUE(integer)
ordinal-type-name
Ordinal-type-name specifies the name of the set of ordinal values. This name
140
Enterprise PL/I for z/OS Language Reference
DEFINE ORDINAL
can be used only in DECLARE statements with the ORDINAL attribute. Use of
this name elsewhere results in it being treated as any other nonordinal name.
member
Specifies the name of a member within the set.
VALUE
The VALUE attribute specifies the value of a particular member within the set.
If the VALUE attribute is omitted for the first member, a value of zero is used.
If the VALUE attribute is omitted for any other member, the next greater
integer value is used.
The value in the given (or assumed) VALUE attribute must be an integer, can
be signed, and must be strictly increasing. The value in the given (or assumed)
VALUE attributed may also be specified as an XN constant.
PRECISION
Abbreviation: PREC
The PRECISION attribute specifies the precision of a particular ordinal value.
If omitted, the precision is determined by the range of ordinal values.
The maximum precision is the same as that for data items declared FIXED
BINARY.
SIGNED or UNSIGNED
These attributes indicate whether ordinal values can assume negative values. If
omitted, they are determined by the range of ordinal values. For example, if
any value is negative, the SIGNED attribute is applied.
For more information on SIGNED and UNSIGNED, refer to “SIGNED and
UNSIGNED attributes” on page 24.
In the following example, Red has the value 0, Orange has the value 1, etc. But Low
has the value 2 and Medium has the value 3.
Example
define ordinal Color ( Red,
Orange,
Yellow,
Green,
Blue,
Indigo,
Violet );
/* is 0, since VALUE is omitted */
define ordinal Intensity ( Low
value(2),
Medium,
High
value(5));
Chapter 6. Type definitions
141
Structure types
Defining typed structures and unions
The DEFINE STRUCTURE statement specifies a named structure or union type.
DEFINE STRUCTURE 1 structure-type-name
,
UNION
,
level minor-structure-name
;
attribute
Abbreviation: STRUCT
structure-type-name
Specifies the name given to this structure type (see “Structures” on page 177
for more information on major structures). This name cannot have dimensions,
although substructures can.
UNION
Is discussed in “UNION attribute” on page 179.
minor-structure-name
Specifies the name given to a deeper level. (see “Structures” on page 177 for
more information on minor structures).
attributes
Specifies attributes for the minor-structure name. Only the following attributes
are allowed:
v The data attributes
v The INITIAL nondata attribute. For more information about the INITIAL
attribute, see “INITIAL attribute” on page 268.
v The VALUE nondata attribute. For more information about the VALUE
attribute, see “Named constants” on page 42.
Any string lengths, area sizes, or array dimensions specified in a DEFINE STRUCT
statement must be restricted expressions.
INITIAL expressions in DEFINE STRUCT statements must be restricted expressions
that do not depend on any address value. Therefore, ENTRY, FILE, and LABEL
constants must not be used in these INITIAL expressions.
Missing data attributes are supplied using PL/I defaults.
Restrictions:
v Defined structures must occupy a number of bytes that is a
multiple of the structure’s alignment.
v In a defined structure, the number of bytes before the element with
the most stringent alignment must be a multiple of that element's
alignment.
142
Enterprise PL/I for z/OS Language Reference
Structure types
For example, if a structure contains an aligned fixed bin(31) field as its most
stringently aligned item,
v the structure must occupy a multiple of 4 bytes.
v there must be a multiple of 4 bytes before the first aligned fixed bin(31) field.
The DEFINE STRUCTURE statement defines a “strong” type. In other words,
variables declared with that type can only be assigned to variables (or parameters)
having the same type. Typed structures can not be used in data-directed
input/output statements.
A DEFINE STRUCTURE statement that merely names the structure to be defined
without specifying any of its members defines an "unspecified structure".
v An unspecified structure cannot be dereferenced, but it may be used to declare a
HANDLE which, of course, cannot be dereferenced either.
v An unspecified structure may also be the subject of a later DEFINE STRUCTURE
statement which does specifies its members.
Unspecified structure definitions are useful when a structure definition contains is
a handle to a second structure which also contains is a handle to the first structure.
For instance, in the following example, the parent structure contains a handle to
the child structure, but the child structure also contains a handle to the parent
structure.
define structure 1 child;
define structure
1 parent,
2 first_child
2 parent_data
handle child,
fixed bin(31);
define structure
1 child,
2 parent
2 next_child
2 child_data
handle parent,
handle child,
fixed bin(31);
HANDLE attribute
You can use the HANDLE attribute to declare a variable as a pointer to a structure
type. Such a variable is called a handle.
HANDLE
structure-type-name
(structure-type-name)
structure-type-name
Specifies the typed structure this handle points to.
Like defined structures, handles are strongly typed: they can only be assigned to or
compared with handles for the same structure type. No arithmetic operations are
permitted on handles.
You cannot use the ADDR built-in function to assign the address of a typed
structure to a handle because the ADDR built-in function returns a pointer, and
pointers cannot be assigned to handles. However, the HANDLE built-in function
takes a typed structure as its argument and returns a handle to that type. In the
Chapter 6. Type definitions
143
HANDLE attribute
following example, using the tm structure type defined on page “Example 2,” a
handle is declared which locates the tm type and the address of Daterec is assigned
to that handle.
dcl P_Daterec handle tm;
dcl Daterec type tm;
P_Daterec = handle(Daterec);
You can convert a handle to a pointer using the POINTERVALUE built-in function.
Declaring typed variables
By using the TYPE attribute, a variable can be declared with the type specified in a
DEFINE ALIAS, DEFINE STRUCTURE or DEFINE ORDINAL statement.
TYPE attribute
TYPE
defined-type-name
(defined-type-name)
defined-type-name
Specifies the name of a previously defined alias, defined structure, or ordinal
type.
Examples
Example 1:
define alias Name
/*
dcl Employee_Name
/*
define alias Rate
/*
char(31) varying;
Name has attributes char(31) varying */
type Name;
Employee_Name type char(31) varying */
fixed dec(3,2);
Rate has attributes fixed dec real */
define structure
1 Payroll,
2 Name,
3 Last type Name,
3 First type Name,
2 Hours,
3 Regular fixed dec(5,2),
3 Overtime fixed dec(5,2),
2 Rate,
3 Regular type Rate,
3 Overtime type Rate;
dcl Non_Exempt type Payroll;
dcl Exempt
type Payroll;
/* Has Payroll structure type */
/* Has Payroll structure type */
The TYPE attribute can be used in a DEFINE ALIAS statement to specify an alias
for a type defined in a previous DEFINE ALIAS statement. For example:
define alias Word fixed bin(31);
define alias Short type word;
Example 2:
144
Enterprise PL/I for z/OS Language Reference
Declaring typed variables
The following example defines several named types, a structure type (tm), and
declares the C function that gets a handle to this typed structure:
define alias int
define alias time_t
define structure
1 tm
,2 tm_sec
type
,2 tm_min
type
,2 tm_hour type
,2 tm_mday type
,2 tm_mon
type
,2 tm_year type
,2 tm_wday type
,2 tm_yday type
,2 tm_isdst type
;
fixed bin(31);
fixed bin(31);
int
int
int
int
int
int
int
int
int
/*
/*
/*
/*
/*
/*
/*
/*
/*
seconds after the minute (0-61)
minutes after the hour (0-59)
hours since midnight (0-23)
day of the month (1-31)
months since January (0-11)
years since 1900
days since Sunday (0-6)
days since January 1 (0-365)
Daylight Saving Time flag
*/
*/
*/
*/
*/
*/
*/
*/
*/
dcl localtime
ext(’localtime’)
entry( nonasgn byaddr type time_t )
returns( byvalue handle tm );
dcl time
ext(’time’)
entry( byvalue pointer )
returns( byvalue type time_t );
ORDINAL attribute
By using the TYPE or ORDINAL attribute, variables can be declared with an
ordinal type. See “TYPE attribute” on page 144 for the syntax for the TYPE
attribute.
ORDINAL ordinal-type-name
ordinal-type-name
Specifies the name of a previously defined set of ordinal values.
For example:
dcl Wall_color ordinal Color;
The ORDINAL attribute conflicts with other data attributes such as FIXED or
SIGNED, but it is allowed with attributes such as BASED or DIMENSION.
Typed structure qualification
You reference a member of a typed structure using the . operator or a handle with
the => operator. Unlike names in a typical untyped structure, the names in a typed
structure form their own “name space” and cannot be referenced by themselves.
For example, given the following declares and definitions
dcl 1 A,
2 B fixed bin,
2 C fixed bin;
define structure
1 X,
2 Y fixed bin,
2 Z fixed bin;
dcl S type X;
Chapter 6. Type definitions
145
Typed structure qualification
B is a valid reference, but Y is not.
Type names are also in a separate name space from declared names. Therefore, you
can use the name of a type as a variable name also.
define alias Hps pointer;
declare Hps type Hps;
Using the '.' operator
The syntax for referring to a typed structure member using the "." operator is:
typed-structure-name .
typed-structure-member
typed-structure-reference
Name of the declared typed structure
typed-structure-member
Name of the referenced major or minor structure member of the structure type
For example, given the structure type tm and function localtime defined as in
“Example 2” on page 144, the following code obtains the system date and displays
the time:
dcl Daterec type tm;
dcl ltime
dcl ptime
type time_t;
handle tm;
ltime = time( null() );
ptime = localtime( ltime );
Daterec = ptime => tm;
display ( edit(Daterec.Hours,’99’) { ’:’ {
edit(Daterec.Minutes,’99’) { ’:’ {
edit(Daterec.Seconds,’99’));
Combinations of arrays and typed structures or unions
As described in “Combinations of arrays, structures, and unions” on page 184,
given this untyped structure:
dcl 1 a(3),
2 b(4) fixed bin,
2 c(5) fixed bin;
a(1).b(2), a.b(1,2), and a(1,2).b have the same meaning.
However, given the following typed structure:
define structure
1 t,
2 b(4) fixed bin,
2 c(5) fixed bin;
dcl x(3) type t;
only x(1).b(2) is valid. In addition, the assignment statement x.b = 0 is invalid,
but x(1).b = 0; is valid.
146
Enterprise PL/I for z/OS Language Reference
Typed structure qualification
Given the structure type t defined previously and the following function f:
dcl f entry returns( type t );
display( f().b(2) ) is valid.
Using handles
Handles access members of a typed structure with the => operator. In the
following example, given the tm type defined on page “Example 2” on page 144,
the time is displayed using a handle to that type:
dcl P_Daterec handle tm;
P_Daterec = handle(Daterec);
display ( edit(P_Daterec=>tm_hours,’99’) { ’:’ {
edit(P_Daterec=>tm_min,’99’) { ’:’ {
edit(P_Daterec=>tm_sec,’99’) );
Handles can locate any member in a typed structure, including the level-1 name
(the type name itself). A reference by a handle to its type name constitutes a
reference to the typed structure which is pointed to by that handle. This allows
reference to this aggregate data by its handle. For example, given that H1 and H2
point to two allocated structures, you can swap two structures by:
define structure 1 T, 2 U, 2 V, 2 W;
dcl (H1, H2) handle T;
dcl Temp
type T;
Temp = H1=>T;
H1=>T = H2=>T;
H2=>T = Temp;
Using ordinals
When using ordinals, keep in mind the following:
v Ordinals are strongly-typed; that is, an ordinal can only be compared with or
assigned to another ordinal of the same type. The ordinal must have been
explicitly declared in a DECLARE statement.
v The ordinal-type-name in a DEFINE ORDINAL statement cannot used in
comparisons or assignments.
v Ordinals can be passed/received as arguments/parameters like any other data
type.
v Ordinals are invalid as arguments for all built-in functions requiring arguments
with computational types. However, in support of ordinals, built-in functions
have been defined and BINARYVALUE has been extended. These built-in
functions are listed in Table 23, and their descriptions can be found in
Chapter 18, “Built-in functions, pseudovariables, and subroutines,” on page 383.
Each of the built-in functions listed takes exactly one argument, which must be a
reference having type ORDINAL.
Table 23. Ordinal-handling built-in functions
Function
Description
BINARYVALUE
Converts an ordinal to a binary value
ORDINALPRED
Returns the next lower value for an ordinal
ORDINALSUCC
Returns the next higher value for an ordinal
ORDINALNAME Returns a character string giving an ordinal’s name
Chapter 6. Type definitions
147
Using Ordinals
For example, in the following sample code, the first DO loop below would list, in
ascending order, the members of the Color set; the second DO loop would list them
in descending order. The example uses the ordinal definition from “Example” on
page 141.
Example
dcl Next_color ordinal Color;
do Next_color = first (:Color:)
repeat ordinalsucc( Next_color )
until (Next_color = last (:Color:));
display( ordinalname( Next_color ) );
end;
do Next_color = last (:Color:)
repeat ordinalpred( Next_color)
until (Next_color = first(:Color:);
display( ordinalname( Next_color));
end;
The sample output for the first loop would be:
RED
ORANGE
YELLOW
GREEN
BLUE
INDIGO
VIOLET
An ordinal cannot be used as an index into an array and cannot define an extent
for a variable, including the lower or upper bound of an array. However, an
ordinal can be converted to binary using the BINARYVALUE built-in function. The
value which is returned by this function can then be used to index into an array or
define an extent.
For example, the following package defines an array usage_count to hold the
number of times each color is used, a procedure Record_usage to update this array,
and a procedure Show_usage to display the values in this array.
Example
Usage: package exports(*);
define ordinal Color ( Red,
Orange,
Yellow,
Green,
Blue,
Indigo,
Violet );
dcl Usage_count(
binvalue( first(:Color:))
: binvalue( last(:Color:)) )
static fixed bin(31) init( (*) 0 );
/* first(:Color:) = Red
*/
/* last(:Color:) = Violet */
Record_usage: proc (Wall_color );
dcl Wall_color type Color parm byvalue;
Usage_count( binvalue(Wall_color) )
148
Enterprise PL/I for z/OS Language Reference
Using Ordinals
= 1 + Usage_count( binvalue(Wall_color) );
end Record_usage;
Show_usage: proc;
dcl Next_color type Color;
do Next_color = Red upthru Violet;
put skip list( ordinalname( Next_color) );
put list( Usage_count( binvalue(Next_color) ));
end;
end Show_usage;
end Usage;
Ordinals can be used to create functions that are easy to maintain and enhance, but
which are as efficient as table look-ups.
In the following example, the function Is_mellow returns a bit indicating whether a
color is or is not “mellow”. If more colors are defined, the “mellow” ones can be
added to the list of colors in the select-group. In a select-group, unlike a hand-built
table, the colors do not have to be in the same order as in the DEFINE statement,
or in any particular order at all.
However, since all of the statements inside the select-group consist of RETURN
statements that return constant values, the compiler will convert the entire
select-group into a simple table look-up.
Example
Is_mellow: proc( Test_color ) returns( bit(1) aligned );
dcl Test_color type Color parm byvalue;
select (Test_color);
when( Yellow, Indigo)
return( ’1’b );
otherwise
return( ’0’b );
end;
end;
This feature can also be used to define your own version of the ORDINALNAME
built-in function. Your own version can return the name you want to be displayed
for each ordinal value. For example, the following function Color_name returns the
color name associated with each name with the first letter capitalized:
Color_name: proc( Test_color ) returns( char(8) varying );
dcl Test_color type Color parm byvalue;
select (Test_color);
when ( Blue ) return(
when ( Green ) return(
when ( Orange ) return(
when ( Red
) return(
when ( Yellow ) return(
otherwise return (");
end;
’Blue’);
’Green’);
’Orange’);
’Red’);
’Yellow’);
end;
Chapter 6. Type definitions
149
Type functions
Type functions
Since type names are in a separate name space from declared names, they cannot
be used where variable references are required, in particular as arguments to
built-in functions. However, type names can be used as arguments to type functions.
(In ANSI terminology, these type functions are known as enquiry functions.) These
type functions are listed in Table 24.
Table 24. Type functions
Function
Description
BIND
Converts a pointer to a handle for a type
CAST
Converts an expression to a specified type using C conversion rules
FIRST
Returns the first value in an ordinal set
LAST
Returns the last value in an ordinal set
NEW
Acquires storage for a structure type and returns a handle to the
acquired storage
RESPEC
Changes the attributes of an expression to a specified type without
changing the bit pattern of the expression
SIZE
Returns the amount of storage needed to represent a type
VALUE
Initializes or assigns to a variable that has the corresponding structure
type
Descriptions for these type functions can be found in Chapter 19, “Type
Functions,” on page 715.
150
Enterprise PL/I for z/OS Language Reference
Chapter 7. Data declarations
Explicit declaration . . . . . . . .
DECLARE statement . . . . . . .
Factoring attributes . . . . . . .
Implicit declaration . . . . . . . .
Scope of declarations . . . . . . . .
INTERNAL and EXTERNAL attributes .
RESERVED attribute . . . . . . . .
SUPPRESS attribute . . . . . . . .
Data alignment . . . . . . . . . .
ALIGNED and UNALIGNED attributes
Defaults for attributes . . . . . . .
Language-specified defaults . . . .
DEFAULT statement . . . . . . .
Restoring language-specified defaults .
Arrays. . . . . . . . . . . . .
DIMENSION attribute . . . . . .
DIMACROSS attribute . . . . . .
Examples of arrays . . . . . . .
Subscripts . . . . . . . . . .
Cross sections of arrays . . . . . .
Structures and unions . . . . . . .
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
151
152
153
154
155
157
162
163
163
164
168
168
169
172
173
173
174
175
175
177
177
Structures . . . . . . . . . . . . .
Unions . . . . . . . . . . . . . .
UNION attribute . . . . . . . . . .
Structure and union qualification . . . . . .
LIKE attribute . . . . . . . . . . . .
Examples . . . . . . . . . . . . .
NOINIT attribute . . . . . . . . . . .
XMLATTR and XMLOMIT attributes . . . .
XMLATTR attribute . . . . . . . . .
XMLOMIT attribute . . . . . . . . .
Example of using XMLATTR and XMLOMIT
Aggregate combinations and mapping . . . . .
Combinations of arrays, structures, and unions
Cross sections of arrays of structures or unions
Structure and union operations . . . . . .
Structure and union mapping . . . . . . .
Rules for order of pairing . . . . . . .
Rules for mapping one pair . . . . . .
Effect of UNALIGNED attribute . . . . .
Example of structure mapping. . . . . .
177
178
179
179
180
181
182
183
183
183
183
184
184
185
185
185
186
187
187
188
When a PL/I program is executed, it can manipulate many different data items of
particular data types. Each data item, except an unnamed arithmetic or string
constant, is referred to in the program by a name. Each data name is given
attributes and a meaning by a declaration (explicit or implicit).
Most attributes of data items are known at the time the program is compiled. For
nonstatic items, attribute values (the bounds of the dimensions of arrays, the
lengths of strings, area sizes, initial values) and some file attributes can be
determined during execution of the program. Refer to “Block activation” on page
89 for more information.
Data items, types, and attributes are introduced in Chapter 2, “Data elements,” on
page 15.
This chapter discusses explicit and implicit declarations, scalar, array, structure,
and union declarations, scope of names, data alignment, and default attributes.
Explicit declaration
A name is explicitly declared if it appears:
v In a DECLARE statement. The DECLARE statement explicitly declares attributes
of names.
v As an entry constant. Labels of PROCEDURE and ENTRY statements constitute
declarations of the entry constants within the containing procedure.
v As a label constant. A label constant explicitly declares a label.
v As a format constant. A label on a FORMAT statement constitutes an explicit
declaration of the label.
Note:
© Copyright IBM Corp. 1999, 2012
151
Explicit declaration
1. Naming an internal entry constant, a label constant, or a format constant
in a DECLARE statement is invalid.
2. The bounds, if any, for a label or format constant are determined by the
smallest and largest values that are specified in any use of it as a label in
the source code.
The scope of an explicit declaration of a name is the block containing the
declaration. This includes all contained blocks, except those blocks (and any blocks
contained within them) to which another explicit declaration of the same name is
internal. In the following diagram, the lines indicate the scope of the declaration of
the names.
B and B’ indicate the two distinct uses of the name B; C and C’ indicate the two
uses of the name C.
For more information about scope, refer to “Scope of declarations” on page 155.
DECLARE statement
The DECLARE statement specifies some or all of the attributes of a name. If the
attributes are not explicitly declared and cannot be determined by context, default
attributes are applied.
DECLARE statements can be an important part of the documentation of a
program. Consequently, you can make liberal use of declarations, even when
default attributes suffice or when an implicit declaration is possible. Because there
are no restrictions on the number of DECLARE statements, you can use different
DECLARE statements for different groups of names. Any number of names can be
declared in one DECLARE statement.
,
DECLARE level
name
*
;
attributes
attributes:
data-attributes
alignment-attributes
scope-attributes
storage-attributes
complementary-attributes
Abbreviation: DCL
For more information about declaring arrays, structures, and unions, refer to
“Arrays” on page 173, “Structures” on page 177, or “Unions” on page 178.
*
152
Cannot be used as the name of an INTERNAL or an EXTERNAL scalar or as
Enterprise PL/I for z/OS Language Reference
DECLARE
the name of a level-1 EXTERNAL structure or union unless the EXTERNAL
attribute specifies an environment name (see “INTERNAL and EXTERNAL
attributes” on page 157).
attributes
The attributes can appear in any order.
All attributes given explicitly for the name must be declared together in a
DECLARE statement, except that:
Names having the FILE attribute can also be given attributes in an OPEN
statement (or have attributes implied by an implicit opening). For more
information on the OPEN statement, see “OPEN statement” on page 283.
The parameter attribute is contextually applied by the appearance of the
name in a parameter list. A DECLARE statement internal to the block can
specify additional attributes.
Attributes of external names, in separate blocks and compilations, must be
consistent.
For more information about attributes and the members of the given groups,
refer to “Data types and attributes” on page 17.
level
A nonzero integer. If a level-number is not specified, level 1 is the default for
element and array variables. Level 1 must be specified for major structure and
union names.
name
Each level-1 name must be unique within a block. For more information on
level-1 names, refer to “Structures” on page 177.
Condition prefixes and labels cannot be specified on a DECLARE statement.
Factoring attributes
Attributes common to several names can be factored to eliminate repeated
specification of the same attributes. Factoring is achieved by enclosing the names
in parentheses followed by the set of attributes which apply to all of the names.
Factoring can be nested. The dimension attribute can be factored. Factoring can
also be used on elementary names within structures and unions. A factored
level-number must precede the parenthesized list.
Names within the parenthesized list are separated by commas. No factored
attribute can be overridden for any of the names, but any name within the list can
be given other attributes as long as there is no conflict with the factored attributes.
The following examples show factoring. The last declaration in the set of examples
shows nested factoring.
declare (A,B,C,D) binary fixed (31);
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)) external;
Chapter 7. Data declarations
153
Implicit declaration
Implicit declaration
If a name appears in a program and is not explicitly declared, it is implicitly
declared. The scope of an implicit declaration is determined as if the name were
declared in a DECLARE statement immediately following the PROCEDURE
statement of the external procedure in which the name is used.
With the exception of files, entries, and built-in functions, implicit declaration has
the same effect as if the name were declared in the outermost procedure. For files
and built-in functions, implicit declaration has the same effect as if the names were
declared in the logical package outside any procedures.
Note: Using implicit declarations for anything other than built-in functions and the
files SYSIN and SYSPRINT is in violation of the 1987 ANSI standard and
should be avoided.
Some attributes for a name declared implicitly can be determined from the context
in which the name appears. These cases, called contextual declarations, are:
v A name of a built-in function.
v A name that appears in a CALL statement or the CALL option of INITIAL, or
that is followed by an argument list, is given the ENTRY and EXTERNAL
attributes.
v A name that appears in the parameter list of a PROCEDURE or ENTRY
statement is given the PARAMETER attribute.
v A name that appears in a FILE or COPY option, or a name that appears in an
ON, SIGNAL, or REVERT statement for a condition that requires a file name, is
given the FILE attribute.
v A name that appears in an ON CONDITION, SIGNAL CONDITION, or
REVERT CONDITION statement is given the CONDITION attribute.
v A name that appears in the BASED attribute, in a SET option, or on the
left-hand side of a locator qualification symbol is given the POINTER attribute.
v A name that appears in an IN option, or in the OFFSET attribute, is given the
AREA attribute.
Examples of contextual declaration are:
read file (PREQ) into (Q);
allocate X in (S);
In these statements, PREQ is given the FILE attribute, and S is given the AREA
attribute.
Implicit declarations that are not contextual declarations acquire all attributes by
default, as described in “Defaults for attributes” on page 168. Because a contextual
declaration cannot exist within the scope of an explicit declaration, it is impossible
for the context of a name to add to the attributes established for that name in an
explicit declaration.
154
Enterprise PL/I for z/OS Language Reference
Scope of declarations
Scope of declarations
The part of the program to which a name applies is called the scope of the
declaration of that name. In most cases, the scope of the declaration of a name is
determined entirely by the position where the name is declared within the
program. Implicit declarations are treated as if the name were declared in a
DECLARE statement immediately following the PROCEDURE statement of the
external procedure.
It is not necessary for a name to have the same meaning throughout a program. A
name explicitly declared within a block has a meaning only within that block.
Outside the block, the name is unknown unless the same name has also been
declared in the outer block. Each declaration of the name establishes a scope and
in this case, the name in the outer block refers to a different data item. This enables
you to specify local definitions and, hence, to write procedures or begin-blocks
without knowing all the names used in other parts of the program.
In the following example, the output for A is actually C.A, which is 2. The output
for B is 1, as declared in procedure X.
X: proc options(main);
dcl (A,B) char(1) init(’1’);
call Y;
return;
Y: proc;
dcl 1 C,
3 A char(1) init(’2’);
put data(A,B);
return;
end Y;
end X;
Thus, for nested procedures, PL/I uses the variable declared within the current
block before using any variables that are declared in containing blocks.
In order to understand the scope of the declaration of a name, you must
understand the terms contained in and internal to.
All of the text of a block, from the PACKAGE, PROCEDURE, or BEGIN statement
through the corresponding END statement (including condition prefixes of BEGIN,
PACKAGE, and PROCEDURE statements), is said to be contained in that block.
However, the labels of the BEGIN or PROCEDURE statement heading the block, as
well as the labels of any ENTRY statements that apply to the block, are not
contained in that block. Nested blocks are contained in the block in which they
appear.
Text that is contained in a block, but not contained in any other block nested
within it, is said to be internal to that block. Entry names of a procedure (and
labels of a BEGIN statement) are not contained in that block. Consequently, they
are internal to the containing block. Entry names of an external procedure are
treated as if they were external to the external procedure.
Figure 7 on page 156 illustrates the scopes of data declarations.
Chapter 7. Data declarations
155
Scope of declarations
Figure 7. Scopes of data declarations
The brackets to the left indicate the block structure; the brackets to the right show
the scope of each declaration of a name. The scopes of the two declarations of Q
and R are shown as Q and Q’ and R and R’.
Note that X and Y are visible to all of the procedures contained in the package.
1
P is declared in the block A and known throughout A because it is not
redeclared.
2
Q is declared in block A, and redeclared in block B. The scope of the first
declaration of Q is all of A except B; the scope of the second declaration of Q
is block B only.
3
R is declared in block C, but a reference to R is also made in block B. The
reference to R in block B results in an implicit declaration of R in A, the
external procedure. Therefore, two separate names (R and R’ in Figure 7)
with different scopes exist. The scope of the explicitly declared R is block C;
the scope of the implicitly declared R in block B is all of A except block C.
4
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.
5
S is explicitly declared in procedure D and is known only within D.
Figure 8 on page 157 illustrates the scopes of entry constant and statement label
declarations.
156
Enterprise PL/I for z/OS Language Reference
Scope of declarations
Figure 8. Scopes of entry and label declarations
Figure 8 shows two external procedures, A and E.
1
The scope of the declaration of the name A is only all of the block A, and
not E.
2
E is explicitly declared in A as an external entry constant. The explicit
declaration of E applies throughout block A. It is not linked to the explicit
declaration of E that applies throughout block E. The scope of the
declaration of the name E is all of block A and all of block E.
3
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 block C, the second applies to block C only. Therefore, when the GO
TO statement in block B executes, control transfers to L1 in block A, and
block B terminates.
4
D and B are explicitly declared in block A and can be referred to anywhere
within A; but because they are INTERNAL, they cannot be referred to in
block E.
5
C is explicitly declared in B and can be referred to from within B, but not
from outside B.
6
L2 is declared in B and can be referred to in block B, including C, which is
contained in B, but not from outside B.
INTERNAL and EXTERNAL attributes
The INTERNAL and EXTERNAL attributes define the scope of a name.
INTERNAL
EXTERNAL
(
environment-name
)
Chapter 7. Data declarations
157
INTERNAL and EXTERNAL
Abbreviations: INT for INTERNAL, EXT for EXTERNAL
environment-name
Specifies the name by which the procedure or variable is known outside of the
compilation unit.
When so specified, the name being declared effectively becomes internal and is
not known outside of the compilation unit. The environment name is known
instead.
The environment name must be a character string constant, and is used as is
without any translation to uppercase.
For example:
dcl X entry external (’koala’);
Environment names should not start with a break character (_). Names starting
with this character are reserved for the library.
On platforms where the linker decorates environment names, if an environment
name is specified with the external attribute, it will still be decorated if it
differs only in case from the variable name. In the following declaration:
dcl abc ext(’kLm’), xyz ext(’xYz’ );
The name for xyz is decorated. For more information on the decoration of
environment names, refer to the PL/I for Windows Programming Guide., under
the section "Understanding linkage considerations" in the "Calling conventions"
chapter.
INTERNAL is the default for entry names of internal procedures and for all other
variables except for entry constants, file constants and programmer defined
conditions. INTERNAL specifies that the name can be known only in the declaring
block. Any other explicit declaration of that name refers to a new object with a
different scope that does not overlap.
Note: INTERNAL may be specified on level-1 procedures in a package. If the
package is declared with EXPORTS(*), an INTERNAL procedure is not
visible outside the package.
EXTERNAL is the default for file constants, entry constants (other than internal
procedures) and programmer-defined conditions. A name with the EXTERNAL
attribute can be declared more than once, either in different external procedures or
within blocks contained in external procedures. All declarations of the same name
with the EXTERNAL attribute refer to the same data. The scope of each declaration
of the name (with the EXTERNAL attribute) includes the scopes of all the
declarations of that name (with EXTERNAL) within the application.
When a major structure or union name is declared EXTERNAL in more than one
block, the attributes of the members must be the same in each case, although the
corresponding member names need not be identical.
In the following example:
ProcA: procedure;
declare 1 A external,
2 B,
2 C;
.
.
.
end ProcA;
158
Enterprise PL/I for z/OS Language Reference
INTERNAL and EXTERNAL
%process;
ProcB: procedure;
declare 1 A external,
2 B,
2 D;
.
.
.
end ProcB;
If A.B is changed in ProcA, it is also changed for ProcB, and vice versa; if A.C is
changed in ProcA, A.D is changed for ProcB, and vice versa.
Members of structures and unions always have the INTERNAL attribute.
Because external declarations for the same name all refer to the same data, they
must all result in the same set of attributes. When EXTERNAL names are declared
in different external procedures, the user has the responsibility to ensure that the
attributes are matching. Figure 9 on page 160 illustrates a variety of declarations
and their scopes.
Chapter 7. Data declarations
159
INTERNAL and EXTERNAL
1
2
7
7
9
8
4,5
9,5
12,2
6
8
9
8
9
2,3
9
11
11,7
12
10
7
Scope_Example: package exports(*);
A: procedure;
declare S character (20);
dcl Set entry(fixed decimal(1)),
Out entry(label);
call Set (3);
E: get list (S,M,N);
B: begin;
declare X(M,N), Y(M);
get list (X,Y);
call C(X,Y);
C:
procedure (P,Q);
declare
P(*,*),
Q(*),
S binary fixed external;
S = 0;
do I = 1 to M;
if sum (P(I,*)) = Q(I) then
go to B;
S = S+1;
if S = 3 then
call Out (E);
Call D(I);
B: end;
end C;
D:
procedure (N);
put list (’Error in row ’,
N, ’Table Name ’, S);
end D;
end B;
go to E;
end A;
Out: procedure (R);
Declare
R Label,
(K static internal,
L static external) init (0),
S binary fixed external,
Z fixed decimal(1);
K = K+1; S=0;
if K<L then
stop;
else go to R;
end;
Set: procedure (Z);
declare Z fixed dec(1);
L=Z;
declare L external init(0);
return;
end;
end Scope_Example;
Figure 9. Example of scopes of various declarations
160
1
A is an external procedure name. Its scope is all of block A, plus any other
blocks where A is declared as external.
2
S is explicitly declared in block A and block C. The character variable
declaration applies to all of block A except block C. The fixed binary
declaration applies only within block C. Notice that although D is called
from within block C, the reference to S in the PUT statement in D is to the
character variable S, and not to the S declared in block C.
Enterprise PL/I for z/OS Language Reference
INTERNAL and EXTERNAL
3
N appears as a parameter in block D, but is also used outside the block. Its
appearance as a parameter establishes an explicit declaration of N within D.
The references outside D cause an implicit declaration of N in block A. These
two declarations of the name N refer to different objects, although in this
case, the objects have the same data attributes, which are, by default,
FIXED BINARY(15,0) and INTERNAL. Under DEFAULT(ANS), the
precision is (31,0).
4
X and Y are known throughout B and can be referred to in block C or D
within B, but not in that part of A outside B.
5
P and Q are parameters, and therefore if there were no other declaration of
these names within the block, their appearance in the parameter list would
be sufficient to constitute a contextual declaration. However, a separate,
explicit declaration statement is required in order to specify that P and Q
are arrays. Although the arguments X and Y are declared as arrays and are
known in block C, it is still necessary to declare P and Q in a DECLARE
statement to establish that they, too, are arrays. (The asterisk notation
indicates that the bounds of the parameters are the same as the bounds of
the arguments.)
6
I and M are not explicitly declared in the external procedure A. Therefore,
they are implicitly declared and are known throughout A, even though I
appears only within block C.
7
The Out and Set external procedures in the example have an external
declaration of L that is common to both. They also must be declared
explicitly with the ENTRY attribute in procedure A. Because ENTRY
implies EXTERNAL, the two entry constants Set and Out are known
throughout the two external procedures.
8
The label B appears twice in the program—first in A, as the label of a
begin-block, which is an explicit declaration, and then redeclared as a label
within block C by its appearance as a prefix to an END statement. The go
to B statement within block C, therefore, refers to the label of the END
statement within block C. Outside block C, any reference to B is to the label
of the begin-block.
9
Blocks C and D can be called from any point within B but not from that part
of A outside B, nor from another external procedure. Similarly, because
label E is known throughout the external procedure A, a transfer to E can
be made from any point within A. The label B within block C, however, can
be referred to only from within C. Transfers out of a block by a GO TO
statement can be made; but such transfers into a nested block generally
cannot. An exception is shown in the external procedure Out, where the
label E from block C is passed as an argument to the label parameter R.
Note that, with no files specified in the GET and PUT statements, SYSIN
and SYSPRINT are implicitly declared.
10
The statement else go to R; transfers control to the label E, even though E
is declared within A, and not known within Out.
11
The variables K (INTERNAL) and L (EXTERNAL) are declared as STATIC
within the Out procedure block; their values are preserved between calls to
Out.
12
In order to identify the S in the procedure Out as the same S in the
procedure C, both are declared with the attribute EXTERNAL.
Chapter 7. Data declarations
161
RESERVED
RESERVED attribute
The RESERVED attribute implies STATIC EXTERNAL. Moreover, if a variable has
the RESERVED attribute, then the application must comply with the following
conditions:
v All declarations of the variable must specify RESERVED.
v The variable name must appear in the RESERVES option of exactly one package.
If a variable has the RESERVED attribute, any INITIAL values are ignored except
in the package reserving it.
RESERVED
(IMPORTED)
If a compilation unit has a variable with the RESERVED attribute and is not the
reserving package for that variable, then that compilation unit either must be part
of the load module containing the reserving package or must import the variable
from another load module containing the reserving package. In the latter case,
v the declaration for the variable must specify the RESERVED(IMPORTED)
attribute
v the variable must be exported from a DLL
v the sidefile associated with the DLL must be included when linking the
importing module
owns_x:
package
exports(*)
reserves(x);
dcl x char(256) reserved init( ... );
dcl y char(256) reserved init( ... );
dcl z char(256) reserved(imported) init( ... );
end;
owns_y:
package
exports(*)
reserves(y);
dcl x char(256) reserved init( ... );
dcl y char(256) reserved init( ... );
dcl z char(256) reserved(imported) init( ... );
end;
owns_z:
package
exports(*)
reserves(z);
dcl z char(256) reserved(imported) init( ... );
end;
162
Enterprise PL/I for z/OS Language Reference
RESERVED
In the preceding example, the package owns_x reserves and initializes the storage
for the variable x. It must be linked into the same load module as the package
owns_y. This load module must import the variable z from the load module into
which package owns_z is linked.
SUPPRESS attribute
You can use the SUPPRESS attribute to instruct the compiler not to issue various
messages.
When you use the SUPPRESS attribute on a variable, the compiler does not issue a
message when the variable is uninitialized, unreferenced, or both. The following
syntax diagram applies to the SUPPRESS attribute on a variable:
,
SUPPRESS (
UNINIT
UNREF
)
The following syntax diagram applies to the SUPPRESS attribute on procedure
statements:
,
SUPPRESS (
UNREF
LAXNESTED
)
UNINIT
Specifying SUPPRESS(UNINIT) as an attribute in the declaration of a variable
causes the compiler not to flag any use of the variable where it might be
uninitialized.
UNREF
Specifying SUPPRESS(UNREF) as an attribute in the declaration of a variable
causes the compiler not to flag the variable as unused when the compilation
unit contains no references to that variable.
Specifying SUPPRESS(UNREF) on the PROCEDURE statement causes the
compiler not to flag the procedure as unused when the compilation unit
contains no references to that procedure.
LAXNESTED
Specifying SUPPRESS(LAXNESTED) on a procedure causes the compiler not to
flag the procedure if executable statements follow it.
If the SUPPRESS attribute is specified on a structure or union, it also applies to all
the elements of that structure (or union).
Data alignment
The computer holds information in multiples of units of 8 bits. Each 8-bit unit of
information is called a byte.
The computer accesses bytes singly or as halfwords, words, or doublewords. A
halfword is 2 consecutive bytes. A fullword is 4 consecutive bytes. A doubleword is 8
consecutive bytes. Byte locations in storage are consecutively numbered starting
Chapter 7. Data declarations
163
Data alignment
with 0; each number is the address of the corresponding byte. Halfwords, words,
and doublewords are addressed by the address of their leftmost byte.
Your programs can execute faster if halfwords, words, and doublewords are
located in main storage on an integral boundary for that unit of information. That
is, the unit of information's address is a multiple of the number of bytes in the
unit, as can be seen in Table 25.
Table 25. Alignment on integral boundaries of halfwords, words, and doublewords
ADDRESSES IN A SECTION OF STORAGE
5000
5001
5002
5003
5004
5005
5006
5007
byte
byte
byte
byte
byte
byte
byte
byte
halfword
halfword
fullword
halfword
halfword
fullword
doubleword
PL/I allows data alignment on integral boundaries. However, unused bytes
between successive data elements can increase storage use. For example, when the
data items are members of aggregates used to create a data set, the unused bytes
increase the amount of auxiliary storage required. The ALIGNED and
UNALIGNED attributes allow you to choose whether or not to align data on the
appropriate integral boundary.
ALIGNED and UNALIGNED attributes
ALIGNED specifies that the data element is aligned on the storage boundary
corresponding to its data-type requirement. UNALIGNED specifies that each data
element is mapped on the next byte boundary, except for fixed-length bit strings,
which are mapped on the next bit.
ALIGNED
UNALIGNED
Defaults are applied at element level. UNALIGNED is the default for bit data,
character data, graphic data, widechar data and numeric character data. ALIGNED
is the default for all other types of data.
Requirements for the ALIGNED attribute are shown in Table 26.
Table 26. Alignment requirements
Variable Type
Stored Internally as:
Storage Requirements
(Bytes)
Alignment Requirements
ALIGNED Data
UNALIGNEDData
Note:
Alignment and storage requirements for program control data can vary across supported systems.
Complex data requires twice as much storage as its real counterpart, but the alignment requirements are the same.
164
Enterprise PL/I for z/OS Language Reference
ALIGNED and UNALIGNED attributes
Table 26. Alignment requirements (continued)
Variable Type
Stored Internally as:
ALIGNED:One byte
for each group of 8
bits (or part thereof)
BIT (n)
Storage Requirements
(Bytes)
ALIGNED: CEIL(n/8)
UNALIGNED: As
UNALIGNED: n bits
many bits as are
required, regardless of
byte boundaries
CHARACTER (n)
One byte per
character
CHARACTER
(n)VARYINGZ
One byte per
character plus one
byte for the
nullterminator
GRAPHIC (n)
Two bytes per graphic
2n
GRAPHIC (n)
VARYINGZ
Two bytes per graphic
plus two bytes for the
nullterminator
2n+2
WIDECHAR (n)
Two bytes per
widechar.
WIDECHAR
(n)VARYINGZ
Two bytes per
widechar plus two
bytes for the
nullterminator
PICTURE
One byte for each
PICTURE character
(except V, K, and the
F scaling factor
specification)
DECIMAL FIXED
(p,q)
Packed decimal
format (1/2 byte per
digit, plus 1/2 byte
for sign)
Alignment Requirements
ALIGNED Data
Byte(Data can begin
on any byte, 0
through 7)
UNALIGNEDData
Bit(Data can begin
on any bit in any
byte, 0 through 7)
n
n+1
2n
2n+2
Byte(Data can begin
Number of PICTURE
on any byte, 0
characters other than V,
through 7)
K, and F specification
Byte(Data can begin
on any byte, 0
through 7)
CEIL((p+1)/2
BINARY FIXED(p,q)
SIGNED
1 <= p <= 7
UNSIGNED
1 <= p <= 8
ORDINAL
One byte
1
SIGNED
1 <= p <= 7
UNSIGNED
1 <= p <= 8
Chapter 7. Data declarations
165
ALIGNED and UNALIGNED attributes
Table 26. Alignment requirements (continued)
Variable Type
Stored Internally as:
Storage Requirements
(Bytes)
BIT(n) VARYING
Two-byte prefix plus
1 byte for each group
of 8 bits (or part
thereof) of the
declared maximum
length
CHARACTER(n)
VARYING
Two-byte prefix plus
1 byte per character
of the declared
maximum length
n+2
GRAPHIC(n)
VARYING
Two-byte prefix plus
2 bytes per graphic of
the declared
maximum length
2n+2
WIDECHAR(n)
VARYING
Two-byte prefix plus
2 bytes per widechar
of the declared
maximum length
2n+2
Alignment Requirements
ALIGNED Data
UNALIGNEDData
ALIGNED:2+CEIL(n/8)
UNALIGNED: 2
bytes+n bits
Halfword (Data can Byte(Data can begin
begin on byte 0, 2, 4, on any byte, 0
or 6)
through 7)
BINARY FIXED(p,q)
SIGNED
8 <= p <= 15
UNSIGNED
9 <= p <= 16
ORDINAL
Halfword
2
SIGNED
8 <= p <= 15
UNSIGNED
9 <= p <= 16
BINARY FIXED(p,q)
SIGNED
16 <= p <= 31
UNSIGNED
17 <= p <= 32
ORDINAL
Fullword
SIGNED
16 <= p <= 31
UNSIGNED
17 <= p <= 32
4
BINARY
FLOAT(p)1<=p<=21
DECIMAL FLOAT(p)
1<=p<=6 if not DFP
Short floating-point
DECIMAL FLOAT(p)
1<=p<=7 if DFP
166
Enterprise PL/I for z/OS Language Reference
Byte(Data can begin
Fullword (Data can
on any byte, 0
begin on byte 0 or 4)
through 7)
ALIGNED and UNALIGNED attributes
Table 26. Alignment requirements (continued)
Variable Type
Stored Internally as:
Storage Requirements
(Bytes)
POINTER
–
HANDLE
–
OFFSET
–
FILE
–
ENTRY LIMITED
–
ENTRY
–
LABEL or FORMAT
–
TASK
–
16
AREA
–
16+size
Alignment Requirements
ALIGNED Data
UNALIGNEDData
4
Byte(Data can begin
Fullword(Data can
on any byte, 0
begin on byte 0 or 4)
through 7)
8
AREA data cannot
be unaligned
BINARY FIXED(p,q)
SIGNED
32 <= p <= 63
UNSIGNED
33 <= p <= 64
–
8
BINARY FLOAT(p)
22 <= p <= 53
DECIMAL FLOAT(p)
7<=p<=16 if not DFP
Doubleword (Data
can begin on byte 0)
Long floating-point
byte(Data can begin
on any byte, 0
through 7)
DECIMAL FLOAT(p)
8<=p<=16 if DFP
BINARY FLOAT(p)
54 <= p
DECIMAL FLOAT(p)
17<=p
Extended
floating-point
16
ALIGNED or UNALIGNED can be specified for element, array, structure, or union
variables. The application of either attribute to a structure or union is equivalent to
applying the attribute to all contained elements that are not explicitly declared
ALIGNED or UNALIGNED.
The following example illustrates the effect of ALIGNED and UNALIGNED
declarations for a structure and its elements:
declare 1 S,
2 X
2 A
3
3
bit(2),
aligned,
B,
C unaligned,
4 D,
4 E aligned,
4 F,
3 G,
2 H;
/*
/*
/*
/*
/*
/*
/*
/*
/*
unaligned by default */
aligned explicitly
*/
aligned from A
*/
unaligned explicitly */
unaligned from C
*/
aligned explicitly
*/
unaligned from C
*/
aligned from A
*/
aligned by default
*/
For more information about structures and unions, refer to “Structures” on page
177 and “Unions” on page 178.
Chapter 7. Data declarations
167
Defaults for attributes
Defaults for attributes
Every name in a PL/I program requires a complete set of attributes. Arguments
passed to a procedure must have attributes matching the procedure's parameters.
Values returned by functions must have the attributes expected. However, the
attributes that you specify need rarely include the complete set of attributes.
The set of attributes for:
v Explicitly declared names
v Implicitly (including contextually) declared names
v Attributes to be included in parameter descriptors
v Values returned from function procedures
can be completed by using the language-specified defaults, or by defaults that you
can define (using the DEFAULT statement) either to modify the language-specified
defaults or to develop a completely new set of defaults.
Attributes applied by default cannot override attributes applied to a name by
explicit or contextual declaration.
Language-specified defaults
When a variable has not been declared with any data attributes, it is given
arithmetic attributes by default. If mode, scale, and base are not specified by a
DECLARE or DEFAULT statement, the DEFAULT compiler option determines its
attributes as follows:
v If DEFAULT(IBM) is in effect, variables with names beginning with the letters I
through N are given the attributes REAL FIXED BINARY(15,0); all other
variables are given the attributes REAL FLOAT DECIMAL(6).
v If DEFAULT(ANS) is in effect, all variables are given the attributes REAL FIXED
BINARY(31,0).
If a scaling factor is specified in the precision attribute, the attribute FIXED is
applied before any other attributes. Therefore, a declaration with the attributes
BINARY(p,q) is always equivalent to a declaration with the attributes FIXED
BINARY(p,q).
If a precision is not specified in an arithmetic declaration, the DEFAULT compiler
option determines the precision as indicated in Table 27 on page 169. The
language-specified defaults for scope, storage and alignment attributes are shown
in Table 8 on page 21 and Table 7 on page 19.
If no description list is given in an ENTRY declaration, the attributes for the
argument must match those specified for the corresponding parameter in the
invoked procedure. For example, given the following declaration:
dcl X entry;
call X( 1 );
The argument has the attributes REAL FIXED DECIMAL(1,0). This would be an
error if the procedure x declared its parameter with other attributes, as shown in
the following example:
X: proc( Y );
dcl Y fixed bin(15);
This potential problem can be easily avoided if the entry declaration specifies the
attributes for all of its parameters.
168
Enterprise PL/I for z/OS Language Reference
Language-specified defaults
Table 27. Default arithmetic precisions
Attributes
DEFAULT(IBM)
DEFAULT(ANS)
DECIMAL FIXED
(5,0)
(10,0)
BINARY FIXED
(15,0)
(31,0)
DECIMAL FLOAT
(6)
(6)
BINARY FLOAT
(21)
(21)
DEFAULT statement
The DEFAULT statement specifies data-attribute defaults (when attribute sets are
not complete). Any attributes not applied by the DEFAULT statement for any
partially-complete explicit or contextual declarations, and for implicit declarations,
are supplied by language-specified defaults.
The DEFAULT statement overrides all other attribute specifications, except that a
name declared with the ENTRY or FILE attribute, but none of the attributes that
would imply the VARIABLE attribute, will be given the implicit CONSTANT
attribute by PL/I before any DEFAULT statements are applied. Consequently, in
the following example, PL/I gives Xtrn the CONSTANT attribute and not the
STATIC attribute.
Sample: proc;
default range(*) static;
dcl Xtrn entry;
end;
Structure and union elements are given default attributes according to the name of
the element, not the qualified element name. The DEFAULT statement cannot be
used to create a structure or a union.
,
DEFAULT RANGE (
identifiers
)
attribute-specification
;
identifiers:
,
identifier
:identifier
*
Abbreviation: DFT
RANGE( identifier )
Specifies that the defaults apply to names that begin with the same letters as in
the identifier specified. For example:
RANGE (ABC)
applies to these names:
Chapter 7. Data declarations
169
DEFAULT
ABC
ABCD
ABCDE
but not to:
ABD
ACB
AB
A
Hence a one-letter identifier in the range-specification applies to all names that
start with that letter. The RANGE identifier may be specified in DBCS.
RANGE( identifier : identifier )
Specifies that the defaults apply to names with initial letters that either match
the two identifiers specified or fall between the two in alphabetic sequence.
The letters may be in DBCS, but in determining if a RANGE specification
applies to a name, all comparisons are based solely on the hex values of the
letters involved. The letters given in the specification must be in increasing
alphabetic order. For example:
RANGE(A:G,I:M,T:Z)
RANGE(*)
Specifies all names in the scope of the DEFAULT statement. For example:
DFT RANGE (*) PIC ’99999’;
This statement specifies default attributes REAL PICTURE '99999' for all
names.
An example of a factored-specification with the range options is:
DEFAULT (RANGE(A)FIXED, RANGE(B)
FLOAT)BINARY;
This statement specifies default attributes FIXED BINARY for names with the
initial letter A, and FLOAT BINARY for those with the initial letter B.
DESCRIPTORS
Specifies that the attributes are included in any parameter descriptors in a
parameter descriptor list of an explicit entry declaration, provided that:
v The inclusion of any such attributes is not prohibited by the presence of
alternative attributes of the same class.
v At least one attribute is already present. (The DESCRIPTORS default
attributes are not applied to null descriptors).
For example:
DEFAULT DESCRIPTORS BINARY;
DCL X ENTRY (FIXED, FLOAT);
The attribute BINARY is added to each parameter descriptor in the list,
producing the equivalent list:
(FIXED BINARY, FLOAT BINARY)
attribute-list
Specifies a list of attributes from which selected attributes are applied to names
in the specified range. Attributes in the list can appear in any order and must
be separated by blanks.
Only those attributes that are necessary to complete the declaration of a data
item are taken from the list of attributes.
170
Enterprise PL/I for z/OS Language Reference
DEFAULT
If FILE is used, it implies the attributes VARIABLE and INTERNAL.
The dimension attribute is allowed, but only as the first item in an attribute
specification. The bounds can be specified as an arithmetic constant or an
expression and can include the REFER option. For example:
DFT RANGE(J) (5);
DFT RANGE(J) (5,5) FIXED;
Although the DEFAULT statement can specify the dimension attribute for
names that have not been declared explicitly, a subscripted name is
contextually declared with the attribute BUILTIN. Therefore, the dimension
attribute can be applied by default only to explicitly declared names.
The INITIAL attribute can be specified.
Attributes that conflict, when applied to a data item, do not necessarily conflict
when they appear in an attribute specification. For example:
DEFAULT RANGE(S) BINARY VARYING;
This means that any name that begins with the letter S and is declared
explicitly with the BIT, CHARACTER, or GRAPHIC attribute receives the
VARYING attribute; all others (that are not declared explicitly or contextually
as other than arithmetic data) receive the BINARY attribute.
VALUE
Can appear anywhere within an attribute-specification except before a
dimension attribute.
VALUE establishes any default rules for an area size, string length, and
numeric precision.
In a DEFAULT statement, the VALUE option is the only place where an area
size, string length or numeric precision may be specified.
These size, length and precision specifications in a VALUE clause are applied
after the system default attributes, but before the system defaults for size,
length and precision. So, for example, given DCL I; and DEFAULT RANGE(*)
VALUE( FIXED BIN(31) );, the variable I will receive the system default
attributes of FIXED BIN, but the precision 31 from the VALUE option (rather
than the system default of 15).
The size of AREA data, or length of BIT, CHARACTER, or GRAPHIC data, can
be an expression or an integer and can include the REFER option, or can be
specified as an asterisk.
For example:
DEFAULT RANGE(A:C)
VALUE (FIXED DEC(10),
FLOAT DEC(14),
AREA(2000));
DECLARE B FIXED DECIMAL,
C FLOAT DECIMAL,
A AREA;
These statements are equivalent to:
DECLARE B FIXED DECIMAL(10),
C FLOAT DECIMAL(14),
A AREA(2000);
The base and scale attributes in value-specification must be present to identify
a precision specification with a particular attribute. The base and scale
attributes can be factored (see “Factoring attributes” on page 153).
Chapter 7. Data declarations
171
DEFAULT
The only attributes that the VALUE option can influence are area size, string
length, and precision. Other attributes in the option, such as CHARACTER and
FIXED BINARY in the above examples, merely indicate which attributes the
value is to be associated with. Consider the following example:
DEFAULT RANGE(I) VALUE(FIXED DECIMAL(8,3));
I = 1;
If it is not declared explicitly, I is given the language-specified default
attributes FIXED BINARY(15,0). It is not influenced by the default statement,
because this statement specifies only that the default precision for FIXED
DECIMAL names is to be (8,3).
For example:
DFT RANGE(*) VALUE(FIXED BINARY(31));
specifies precision for identifiers already known to be FIXED BINARY, while
DFT RANGE(*) FIXED BINARY VALUE(FIXED BINARY(31));
specifies both the FIXED BINARY attribute as a default and the precision.
There can be more than one DEFAULT statement within a block. The scope of a
DEFAULT statement is the block in which it occurs, and all blocks within that
block which neither include another DEFAULT statement with the same range, nor
are contained in a block having a DEFAULT statement with the same range.
A DEFAULT statement in an internal block affects only explicitly declared names.
This is because the scope of an implicit declaration is determined as if the names
were declared in a DECLARE statement immediately following the PROCEDURE
statement of the external procedure in which the name appears.
It is possible for a containing block to have a DEFAULT statement with a range
that is partly covered by the range of a DEFAULT statement in a contained block.
In such a case, the range of the DEFAULT statement in the containing block is
reduced by the range of the DEFAULT statement in the contained block. For
example:
P:
L1:
Q:
L2:
PROCEDURE;
DEFAULT RANGE (XY) FIXED;
BEGIN;
DEFAULT RANGE (XYZ) FLOAT;
END P;
The scope of DEFAULT statement L1 is procedure P and the contained block Q.
The range of DEFAULT statement L1 is all names in procedure P beginning with
the characters XY, together with all names in begin-block Q beginning with the
characters XY, except for those beginning with the characters XYZ.
Labels can be prefixed to DEFAULT statements. A branch to such a label is treated
as a branch to a null statement. Condition prefixes cannot be attached to a
DEFAULT statement.
Restoring language-specified defaults
The following statement:
dft range(*) system;
172
Enterprise PL/I for z/OS Language Reference
Restoring defaults
overrides, for all names, any programmer-defined default rules established in a
containing block. It can be used to restore language-specified defaults for contained
blocks.
Arrays
An array is an n-dimensional collection of elements that have identical attributes.
Only the array itself is given a name. An individual item of an array is referred to
by giving its position within the array. You indicate that a name is an array variable
by providing the dimension attribute.
Unless specified using REFER, every dimension of every array must have at least
one element. When the bounds of an array are specified using REFER, then the
array may be defined to have zero elements as long as
v the array is never accessed or assigned
v the array has only one dimension (excluding any inherited dimensions)
v all of the elements in the containing structure must be either UNALIGNED or
NONVARYING BIT.
So, for example, given the following code, it would be valid to allocate the array a
when n1 was zero as long as ab3, abc1, and abc2 were neither accessed nor
assigned.
dcl n1
fixed bin(31);
dcl p
pointer;
dcl
1 a based(p),
2 ab1
fixed bin(31),
2 ab2
fixed bin(31),
2 ab3( n1 refer(ab2) ),
3 abc1
char(40) var,
3 abc2
char(40) var,
2 ab4
char(40) var;
DIMENSION attribute
The dimension attribute specifies the number of dimensions of an array and upper
and lower bounds of each.
Bounds that are nonrestricted expressions are evaluated and converted to FIXED
BINARY (with a precision corresponding to the CMPAT compiler option) when
storage is allocated for the array.
The extent of a dimension is the number of integers between, and including, the
lower and upper bounds for a dimension.
Chapter 7. Data declarations
173
DIMENSION attribute
,
( bound
:
*
)
DIMENSION
bound:
upper-bound
lower-bound
*:
lower-bound:
1
expression
REFER(variable)
upper-bound:
expression
REFER(variable)
Abbreviation: DIM
If the DIMENSION keyword is omitted, the dimension must immediately follow
the name (or the parenthesized list of names) in the declaration.
The number of bounds specifications indicates the number of dimensions in the
array, unless the declared variable is in an array of structures or unions. In this
case it inherits dimensions from the containing structure or union.
The bounds specification indicates the bounds as follows:
v If only the upper bound is given, the lower bound defaults to 1.
v The lower bound must be less than or equal to the upper bound.
v An asterisk (*) specifies that the lower and/or the upper bound is taken from
the argument associated with the parameter.
DIMACROSS attribute
The DIMACROSS attribute specifies a DIMENSION attribute on a structure, but
one which will be removed from the structure and propogated to its members.
The DIMACROSS attribute has the same syntax as the DIMENSION attribute
except that the DIMACROSS keyword is, of course, not optional.
The DIMACROSS attribute is valid only on structures, and it is invalid if any of
the immediate children already have the dimension attribute.
Unlike a variable declared with the DIMENSION attribute, a variable declared
with the DIMACROSS attribute is not an array. The children of the variable are
174
Enterprise PL/I for z/OS Language Reference
DIMACROSS attribute
arrays. However, the variable might be used as an array in a BY DIMACROSS
assignment or as an argument to the LBOUNDACROSS or HBOUNDACROSS
built-in functions.
As an example, the declare
Dcl
1 a(10) dimacross,
2 b,
2 c,
3 d,
3 e;
is equivalent to
Dcl
1 a,
2 b(10),
2 c(10),
3 d,
3 e;
Examples of arrays
Consider the following declaration:
declare List fixed decimal(3) dimension(8);
List is declared as a one-dimensional array of eight elements, each one a
fixed-point decimal element of three digits. The one dimension of List has bounds
of 1 and 8, and its extent is 8.
In the example:
declare Table (4,2) fixed dec (3);
Table is declared as a two-dimensional array of eight fixed-point decimal elements.
The two dimensions of Table have bounds of 1 and 4 and 1 and 2, and the extents
are 4 and 2.
Other examples are:
declare List_A dimension(4:11);
declare List_B (-4:3);
In the first example, the bounds are 4 and 11; in the second they are -4 and 3. The
extents are the same for each, 8 integers from the lower bound through the upper
bound.
In the manipulation of array data (discussed in “Array expressions” on page 69)
involving more than one array, the bounds—not merely the extents—must be
identical. Although List, List_A, and List_B all have the same extent, the bounds
are not identical.
Subscripts
The bounds of an array determine the way elements of the array can be referred
to. For example, when the following data items:
20 5 10 30 630 150 310 70
are assigned to the array List, as declared above, the different elements are
referred to as follows:
Chapter 7. Data declarations
175
Subscripts
Reference
LIST (1)
LIST (2)
LIST (3)
LIST (4)
LIST (5)
LIST (6)
LIST (7)
LIST (8)
Element
20
5
10
30
630
150
310
70
Each of the parenthesized numbers following LIST is a subscript. A parenthesized
subscript following an array name reference identifies a particular data item within
the array. A reference to a subscripted name, such as LIST(4), refers to a single
element and is an element variable. The entire array can be referred to by the
unsubscripted name of the array—for example, LIST.
The same data can be assigned to List_A and List_B declared previously. In this
case it is referenced as follows:
Reference
LIST_A (4)
LIST_A (5)
LIST_A (6)
LIST_A (7)
LIST_A (8)
LIST_A (9)
LIST_A (10)
LIST_A (11)
Element
20
5
10
30
630
150
310
70
Reference
LIST_B (-4)
LIST_B (-3)
LIST_B (-2)
LIST_B (-1)
LIST_B (0)
LIST_B (1)
LIST_B (2)
LIST_B (3)
Assume that the same data is assigned to TABLE, which is declared as a
two-dimensional array. TABLE can be illustrated as a matrix of four rows and two
columns:
TABLE(m,n)
(1,n)
(2,n)
(3,n)
(4,n)
(m,1)
20
10
630
310
(m,2)
5
30
150
70
An element of TABLE is referred to by a subscripted name with two parenthesized
subscripts, separated by a comma. For example, TABLE (2,1) would specify the
first item in the second row, the data item 10.
The use of a matrix to illustrate TABLE is purely conceptual. It has no relationship
to the way the items are actually organized in storage. Data items are assigned to
an array in row major order. This means that the subscript that represents columns
varies most rapidly. For example, assignment to TABLE would be to TABLE(1,1),
TABLE(1,2), TABLE(2,1), TABLE(2,2), and so forth.
A subscripted reference to an array must contain as many subscripts as there are
dimensions in the array.
Any expression that yields a valid arithmetic value can be used for a subscript. If
necessary, the value is converted to FIXED BINARY (with a precision
176
Enterprise PL/I for z/OS Language Reference
Subscripts
corresponding to the CMPAT compiler option). Thus, TABLE(I,J*K) can be used to
refer to the different elements of TABLE by varying the values of I, J, and K.
Cross sections of arrays
Cross sections of arrays can be referred to by using an asterisk for a subscript. The
asterisk specifies that the entire extent is used. For example, TABLE(*,1) refers to
all of the elements in the first column of TABLE. It specifies the cross section
consisting of TABLE(1,1), TABLE(2,1), TABLE(3,1), and TABLE(4,1). The subscripted
name TABLE(2,*) refers to all of the data items in the second row of TABLE.
TABLE(*,*) refers to the entire array, as does TABLE.
A subscripted name containing asterisk subscripts represents not a single data
element, but an array with as many dimensions as there are asterisks.
Consequently, such a name is not an element expression, but an array expression.
A reference to a cross section of an array can refer to two or more elements that
are not adjacent in storage. The storage represented by such a cross section is
known as nonconnected storage. (See “CONNECTED and NONCONNECTED
attributes” on page 261.) The rule is as follows: if a nonasterisk bound appears to
the right of the leftmost asterisk bound, the array cross section is in nonconnected
storage. Thus A(4,*,*) is in connected storage; A(*,2,*) is not.
Structures and unions
Structures
A structure is a collection of member elements that can be structures, unions,
elementary variables and arrays.
The structure variable is a name that can be used to refer to the entire aggregate of
data. Unlike an array, however, each member of a structure also has a name, and
the attributes of each member can differ. An asterisk can be used as the name of a
structure or a member when it will not be referred to. For example, reserved or
filler items can be named with an asterisk.
A structure has different levels. The name at level-1 is called a major structure.
Names at deeper levels can be minor structures or unions. Names at the deepest
level are called elementary names, which can represent an elementary variable or an
array variable. Unions are described in “Unions” on page 178.
A structure is described in a DECLARE statement through the use of
level-numbers preceding the associated names. Level-numbers must be integers.
A major structure name is declared with the level-number 1. Minor structures,
unions, and elementary names are declared with level-numbers greater than 1. A
delimiter must separate the level-number and its associated name. For example,
the items of a payroll record could be declared as follows:
declare 1 Payroll,
/* major structure name */
2 Name,
/* minor structure name */
3 Last char(20),
/* elementary name
*/
3 First char(15),
2 Hours,
3 Regular fixed dec(5,2),
3 Overtime fixed dec(5,2),
2 Rate,
3 Regular fixed dec(3,2),
3 Overtime fixed dec(3,2);
Chapter 7. Data declarations
177
Structures
In the example, Payroll is the major structure and all other names are members of
this structure. Name, Hours, and Rate are minor structures, and all other members
are elementary variables. You can refer to the entire structure by the name Payroll,
or to portions of the structure by the minor structure names. You can refer to a
member by referring to the member name.
Indentation is only for readability. The statement could be written in a continuous
string as:
Declare 1 Payroll, 2 Name, 3 Last char(20), . . .
The level-numbers you choose for successively deeper levels need not be
consecutive. A minor structure at level n contains all the names with level-numbers
greater than n that lie between that minor structure name and the next name with
a level-number less than or equal to n.
For example, the following declaration results in exactly the same structure as the
declaration in the previous example.
Declare 1 Payroll,
4 Name,
5 Last char(20),
5 First char(15),
3 Hours,
6 Regular fixed dec(5,2),
5 Overtime fixed dec(5,2),
2 Rate,
9 Regular fixed dec(3,2),
9 Overtime fixed dec(3,2);
The description of a major structure is usually terminated by a semicolon
terminating the DECLARE statement. It can also be terminated by comma,
followed by the declaration of another item.
Unions
A union is a collection of member elements that overlay each other, occupying the
same storage. The members can be structures, unions, elementary variables, and
arrays. They need not have identical attributes.
The entire union is given a name that can be used to refer to the entire aggregate
of data. Like a structure, each element of a union also has a name. An asterisk can
be used as the name of a union or a member, when it will not be referred to. For
example, reserved or filler items can be named asterisk.
Like a structure, a union can be at any level including level 1. All elements of a
union at the next deeper level are members of the union and occupy the same
storage. The storage occupied by the union is equal to the storage required by the
largest member. Normally, only one member is used at any time and the
programmer determines which member is used.
A union, like a structure, is declared through the use of level-numbers preceding
the associated names.
Unions can be used to declare variant records that would typically contain a
common part, a selector part, and variant parts. For example, records in a client
file can be declared as follows:
Declare 1 Client,
2 Number pic ’999999’,
2 Type bit(1),
178
Enterprise PL/I for z/OS Language Reference
Unions
2 * bit(7),
2 Name union,
3 Individual,
5 Last_Name char(20),
5 First_Name union,
7 First
char(15),
7 Initial char(1),
3 Company char(35),
2 * char(0);
In this example, Client is a major structure. The structure Individual, and the
element Company are members of the union Name. One of these members is active
depending on Type. The structure Individual contains the union First_name and
the element Last_name. First_name union has First and Initial as its members,
both of which are active. The example also shows the use of asterisk as a name.
The description of a union is terminated by the semicolon that terminates a
DECLARE statement or by a comma, followed by the declaration of another item.
UNION attribute
The UNION attribute allows you to specify that a variable is a union and that its
members are those that follow it and are at the next logically higher level. CELL is
accepted as a synonym for UNION.
UNION
Structure and union qualification
A member of a structure or a union can be referred to by its name alone if it is
unique. If another member has the same name, whether at the same or different
level, ambiguity occurs. Where ambiguity occurs, a qualified reference is required
to uniquely identify the correct member.
A qualified reference is a member name that is qualified with one or more names of
parent members connected by periods. (See the qualified reference syntax in
Chapter 3, “Expressions and references,” on page 49.) Blanks can appear
surrounding the period.
The qualification must follow the order of levels. That is, the name at the highest
level must appear first, with the name at the deepest level appearing last.
While the level-1 structure or union name must be unique within the block scope,
member names need not be unique as long as they do not appear at same logical
level within their most immediate parent. A qualified name must be used only so
far as necessary to make a reference of the same structure unique within the block
in which it appears. In the following example, the value of x.y (19) is displayed,
not the value (17).
dcl Y fixed init(17);
begin;
dcl
1 X,
2 Y fixed init(19);
display( Y );
end;
Chapter 7. Data declarations
179
Structure and union qualification
A reference is always taken to apply to the declared name in the innermost block
containing the reference.
The following examples illustrate both ambiguous and unambiguous references. In
the following example, A.C refers to C in the inner block; D.E refers to E in the
outer block.
declare 1 A, 2 C, 2 D, 3 E;
begin;
declare 1 A, 2 B, 3 C, 3 E;
A.C = D.E;
In the following example, D has been declared twice. A reference to A.D refers to
the second D, because A.D is a complete qualification of only the second D. The first
D is referred to as A.C.D.
declare 1 A,
2 B,
2 C,
3 D,
2 D;
In the following example, a reference to A.C is ambiguous because neither C can be
completely qualified by this reference.
declare 1 A,
2 B,
3 C,
2 D,
3 C;
In the following example, a reference to A refers to the first A, A.A to the second A,
and A.A.A to the third A.
declare 1 A,
2 A,
3 A;
In the following example, a reference to X refers to the first DECLARE statement. A
reference to Y.Z is ambiguous. Y.Y.Z refers to the second Z, and Y.X.Z refers to the
first Z.
declare X;
declare 1 Y,
2 X,
3 Z,
3 A,
2 Y,
3 Z,
3 A;
For more information about name qualification, refer to “Scope of declarations” on
page 155.
LIKE attribute
The LIKE attribute specifies that the name being declared has an organization that
is logically the same as the referenced structure or union (object of the LIKE
attribute). The object variable's member names and their attributes, including the
dimension attribute, are effectively copied and become members of the name being
declared. If necessary, the level-numbers of the copied members are automatically
adjusted. The object variable name and its attributes, including the dimension
attribute, are ignored.
180
Enterprise PL/I for z/OS Language Reference
Structure and union qualification
LIKE object-variable
object-variable
Can be a major structure, a minor structure, or a union. It must be known in
the block containing the LIKE attribute specification. It can be qualified but
must not be subscripted. The object or its members may also have the LIKE
attribute if they were declared previously.
The objects in all LIKE attributes are associated with declared names before
any LIKE attributes are expanded.
New members cannot be added to the created structure or union. Any
level-number that immediately follows the object variable in the LIKE attribute
must be equal to or less than the level-number of the name with the LIKE
attribute.
The following declarations yield the same structure for X.
dcl
1 A(10) aligned static,
2 B
bit(4),
2 C
bit(4),
1 X like A;
dcl
1 X,
2 B bit(4),
2 C bit(4);
Notice that the dimension (DIM(10)), ALIGNED, and STATIC attributes are not
copied as part of the LIKE expansion.
The LIKE attribute is expanded before the defaults are applied and before the
ALIGNED and UNALIGNED attributes are applied to the contained elements of
the LIKE object variable. However, the LIKE attribute is expanded only after all
LIKE attributes have been resolved.
Examples
declare 1 A,
2 C,
3 E(3) union,
5 E1,
5 E2,
3 F;
declare 1 B(10) union,
2 C, 3 G, 3 H,
2 D;
begin;
declare 1 C like B;
declare 1 D(2),
5 BB like A.C;
end;
Declarations C and D have the results shown in the following example:
dcl
1 C,
2 C, 3 G, 3 H,
2 D;
/* DIM and UNION not copied. */
Chapter 7. Data declarations
181
Structure and union qualification
dcl 1 D(2),
5 BB,
6 E(3) union, /* DIM(3) and UNION copied.
7 E1,
/* Note adjusted level-numbers.
7 E2,
6 F;
*/
*/
The following declarations are valid, but only because B is declared before C and E
is declared before F:
dcl 1 a, 2 a1 fixed bin;
dcl 1 b, 2 b1 like a;
dcl 1 c, 2 c1 like b;
dcl 1 d, 2 d1 fixed bin;
dcl 1 e like d;
The following example is valid, but only because the LIKE references are expanded
after they are all resolved, otherwise the reference aa3_array would be ambiguous:
dcl 1 aa(30)
,5 aa1
,5 aa2
,5 aa3_array(30)
,7 aa3_1
,7 aa3_2
,7 aa3_3
,7 aa3_4
;
dcl bb
dcl cc
char( 5)
fixed bin(31)
fixed
fixed
fixed
fixed
dec(15,2)
dec(15,2)
dec(11,4)
dec(7,3)
like aa;
like aa3_array;
The following example is invalid because C.E has the LIKE attribute and because B
is declared after A. If the order of the declarations for A and B is reversed, the code
is valid.
declare 1 A like C,
1 B,
2 C,
3 D,
3 E like X,
2 F,
1 X,
2 Y,
2 Z;
The following example is invalid because G.C cannot be resolved. G.C is not
resolved because the expansion of the LIKE for G occurs after the attempt to
resolve the LIKE attribute for A:
declare 1 B,
2 C,
3 D,
3 E,
2 F,
1 G like B;
1 A like G.C,
NOINIT attribute
The NOINIT attribute specifies that any INITIAL attributes are to be ignored.
182
Enterprise PL/I for z/OS Language Reference
Structure and union qualification
While the NOINIT attribute may be most useful on level-1 structures, it may be
specified on any substructure as well.
The NOINIT attribute is particularly useful with the LIKE attribute since when a
new variable is declared LIKE an old variable but with the NOINIT attribute, then
the new variable will inherit all the substructuring from the old variable, but none
of its INITIAL values.
XMLATTR and XMLOMIT attributes
The XMLATTR and XMLOMIT attributes specify the use of XML attributes and the
omission of null values in the XML that is generated by using the XMLCHAR
built-in function.
Note: The compiler ignores XMLATTR and XMLOMIT unless a structure that
contains fields using them is passed to XMLCHAR.
XMLATTR attribute
The XMLATTR attribute indicates that the field is presented as an attribute of its
containing structure in the XML output that is generated by XMLCHAR.
XMLATTR is invalid with any of the following elements:
v
v
v
v
Arrays
Structures or unions
Unnamed structure elements
A structure element that is used previously with the same parent but without
the XMLATTR attribute
XMLOMIT attribute
The XMLOMIT attribute indicates that the field must be omitted from the XML
output that is generated by XMLCHAR if the field is either of the following data
items:
v A string that compares equal to the null string (' ')
v A number that compares equal to 0
XMLOMIT is invalid with any of the following elements:
v Structures or unions
v Unnamed structure elements
v Elements that use non-native float (hex or dfp on Windows)
Example of using XMLATTR and XMLOMIT
The following code shows a declaration of a structure with the XMLATTR and
XMLOMIT attributes and also the output you get by using XMLCHAR with that
structure:
dcl
1 order
2 orderNr
2 customer,
3 id
3 name
3 firstname
3 partno
3 special
char(20) init(’1729’),
xmlattr fixed bin(31) init(2917),
xmlattr char(32) init(’jakob’),
xmlattr char(24) init(’michael’),
fixed bin(31) init(1367),
xmlomit char(35) init(’’);
Chapter 7. Data declarations
183
Structure and union qualification
<order>
<orderNr>1729</orderNr>
<customer id=2917 name=’jakob’ firstname=’michael’>
<partno>1367</partno>
</customer>
</order>
Aggregate combinations and mapping
Combinations of arrays, structures, and unions
Specifying the dimension attribute on a structure or union results in an array of
structures or an array of unions, respectively. The elements of such an array are
structures or unions having identical names, levels, and members. For example, if a
structure were used to hold meteorological data for each month of the year for the
twentieth and the twenty-first centuries, it might be declared as follows:
Declare 1 Year(1901:2100),
3 Month(12),
5 Temperature,
7 High decimal fixed(4,1),
7 Low decimal fixed(4,1),
5 Wind_velocity,
7 High decimal fixed(3),
7 Low decimal fixed(3),
5 Precipitation,
7 Total decimal fixed(3,1),
7 Average decimal fixed(3,1),
3 * char(0);
You could refer to the weather data for July 1991 by specifying Year(1991,7).
Portions of this data could be referred to by Temperature(1991,7) and
Wind_Velocity(1991,7). Precipitation.Total(1991,7) or Total(1991,7) would
both refer to the total precipitation during July 1991.
Temperature.High(1991,3), which would refer to the high temperature in March
1991, is a subscripted qualified reference.
The need for subscripted qualified references becomes apparent when an array of
structures or unions contains members that are arrays. In the following example,
both A and B are structures:
declare 1 A (2,2),
(2 B (2),
3 C,
3 D,
2 E) fixed bin;
To refer to a data item, it might be necessary to use as many as three names and
three subscripts. For example:
A(1,1).B
refers to B, an array of structures.
A(1,1)
refers to a structure.
A(1,1).B(1)
refers to a structure.
A(1,1).B(2).C
refers to an element.
As long as the order of subscripts remains unchanged, subscripts in such
references can be moved to names at a lower or higher level. In the previous
example, A.B.C(1,1,2) and A(1,1,2).B.C have the same meaning as A(1,1).B(2).C
184
Enterprise PL/I for z/OS Language Reference
Combinations of arrays, structures, and unions
for the above array of structures. Unless all of the subscripts are moved to the
lowest level, the reference is said to have interleaved subscripts, so A.B(1,1,2).C has
interleaved subscripts.
Any item declared within an array of structures or unions inherits dimensions
declared in the parent. In the previous declaration for the array of structures A, the
array B is a three-dimensional structure, because it inherits the two dimensions
declared for A. If B is unique and requires no qualification, any reference to a
particular B would require three subscripts, two to identify the specific A and one
to identify the specific B within that A.
Cross sections of arrays of structures or unions
A reference to a cross section of an array of structures or unions is not allowed.
That is, the asterisk notation cannot be used in a reference unless all of the
subscripts are asterisks.
Structure and union operations
Structures can be referenced in most contexts that any elementary variable can be
referenced. For example, you can have structure references in assignments, I/O
statements, and so on. References to unions or structures that contain unions,
however, are limited to the following:
v Parameters and arguments
v Storage control and those built-in functions and subroutines that allow
structures.
Structure and union mapping
Individual members of a union are mapped the same way as members of the
structure. That is, each of the members, if not a union, is mapped as if it were a
member of a structure. This means that the first storage locations for each of the
members of a union do not overlay each other if each of the members requires
different alignment and therefore different padding before the beginning of the
member.
Consider the following union:
dcl
1 A union,
2 B,
3 C char(1),
3 D fixed bin(31),
2 E,
3 F char(2),
3 G fixed bin(31),
2 H char(8);
Three bytes of padding are added between A and B. Two bytes are added between
A and E. No padding bytes are between A and H. It means that C starts with the
fourth byte of H and that F starts with the third byte of H.
You must not use the ADDR, BITLOCATION, or LOCATION built-in functions
against any UNION like the one in the previous example. You should use these
functions only when the first storage locations of the members of a union are the
same.
Chapter 7. Data declarations
185
Structure and union mapping
To ensure that the first storage location of each of the members of a union is the
same, make sure that the first member of each has the same alignment requirement
and it is the same as the highest alignment of any of its members (or members of
its member).
The remainder of the discussion applies to members of a structure or union, which
can be minor structures or elementary variables.
For any major or minor structure, the length, alignment requirement, and position
relative to an 8-byte boundary depend on the lengths, alignment requirements, and
relative positions of its members. The process of determining these requirements
for each level and for the complete structure is known as structure mapping.
You can use structure mapping for determining the record length required for a
structure when record-oriented input/output is used, and determining the amount
of padding or rearrangement required for correct alignment of a structure for
locate-mode input/output.
The structure mapping process minimizes the amount of unused storage (padding)
between members of the structure. It completes the entire process before the
structure is allocated, according (in effect) to the rules discussed in the following
paragraphs.
Structure mapping is not a physical process. Terms such as shifted and offset are
used purely for ease of discussion, and do not imply actual movement in storage.
When the structure is allocated, the relative locations are already known as a result
of the mapping process.
The mapping for a complete structure reduces to successively combining pairs of
items (elements, or minor structures whose individual mappings have already been
determined). Once a pair has been combined, it becomes a unit to be paired with
another unit, and so on until the complete structure is mapped. The rules for the
process are categorized as follows:
v Rules for determining the order of pairing
v Rules for mapping one pair.
These rules are described below, and an example shows an application of the rules
in detail. It is necessary to understand the difference between the logical level and
the level-number of structure elements. The logical levels are immediately apparent
if the structure declaration is written with consistent level-numbers or suitable
indentation (as in the detailed example given after the rules). In any case, you can
determine the logical level of each item in the structure by applying the following
rule to each item in turn, starting at the beginning of the structure declaration:
Note: The logical level of a given item is always one unit deeper than that of its
immediate containing structure.
In the following example, the lower line shows the logical level for each item in
the declaration.
dcl 1 A, 4 B, 5 C, 5 D, 3 E, 8 F, 7 G;
1
2
3
3
2
3
3
Rules for order of pairing
The steps in determining the order of pairing are as follows:
186
Enterprise PL/I for z/OS Language Reference
Rules for order of pairing
1. Find the minor structure at the deepest logical level (which we will call logical
level n).
2. If more than one minor structure has the logical level n, take the first one that
appears in the declaration.
3. Pair the first two elements appearing in this minor structure, thus forming a
unit. Use the rules for mapping one pair. (See “Rules for mapping one pair.”)
4. Pair this unit with the next element (if any) declared in the minor structure,
thus forming a larger unit.
5. Repeat step 4 until all the elements in the minor structure have been combined
into one unit. This completes the mapping for this minor structure. its
alignment requirement and length, including any padding, are now determined
and will not change (unless you change the structure declaration). Its offset
from a doubleword boundary is also now determined. This offset is significant
during mapping of any containing structure, and it can change as a result of
such mapping.
6. Repeat steps 3 through 5 for the next minor structure (if any) appearing at
logical level n in the declaration.
7. Repeat step 6 until all minor structures at logical level n have been mapped.
Each of these minor structures can now be thought of as an element for
structure mapping purposes.
8. Repeat the pairing process for minor structures at the next higher logical level;
that is, make n equal to (n-1) and repeat steps 2 through 7.
9. Repeat step 8 until n = 1; then repeat steps 3 through 5 for the major structure.
Rules for mapping one pair
For purposes of this explanation, think of storage as contiguous doublewords, each
having 8 bytes, numbered 0 through 7, which indicate the offset from a
doubleword boundary. Think of the bytes as numbered continuously from 0
onward, starting at any byte, so that lengths and offsets from the start of the
structure can be calculated.
1. Begin the first element of the pair on a doubleword boundary; or, if the
element is a minor structure that has already been mapped, offset it from the
doubleword boundary by the amount indicated.
2. Begin the second element of the pair at the first valid position following the
end of the first element. This position depends on the alignment requirement of
the second element. (If the second element is a minor structure, its alignment
requirement will have already been determined.)
3. Shift the first element towards the second element as far as the alignment
requirement of the first allows. The amount of shift determines the offset of this
pair from a doubleword boundary.
After this process has been completed, any padding between the two elements has
been minimized and does not change throughout the rest of the operation. The
pair is now a unit of fixed length and alignment requirement; its length is the sum
of the two lengths plus padding, and its alignment requirement is the higher of the
two alignment requirements (if they differ).
Effect of UNALIGNED attribute
The example of structure mapping given below shows the rules applied to a
structure declared ALIGNED. Mapping of aligned structures is more complex
because of the number of alignment requirements. The effect of the UNALIGNED
attribute is to reduce to one byte the alignment requirements for halfwords,
fullwords, and doublewords, and to reduce to one bit the alignment requirement
Chapter 7. Data declarations
187
Effect of UNALIGNED attribute
for bit strings. The same structure mapping rules apply, but the reduced alignment
requirements are used. The only unused storage will be bit padding within a byte
when the structure contains bit strings.
AREA data cannot be unaligned.
If a structure has the UNALIGNED attribute and it contains an element that cannot
be unaligned, UNALIGNED is ignored for that element. The element is aligned
and an error message is produced. For example, in a program with the following
declaration, C is given the attribute ALIGNED because the inherited attribute
UNALIGNED conflicts with AREA.
declare 1 A unaligned,
2 B,
2 C area(100);
Example of structure mapping
The following example shows the application of the structure mapping rules for a
structure with the specified declaration.
declare 1 A aligned,
2 B fixed bin(31),
2 C,
3 D float decimal(14),
3 E,
4 F entry,
4 G,
5 H character(2),
5 I float decimal(13),
4 J fixed binary(31,0),
3 K character(2),
3 L fixed binary(20,0),
2 M,
3 N,
4 P fixed binary(15),
4 Q character(5),
4 R float decimal(2),
3 S,
4 T float decimal(15),
4 U bit(3),
4 V char(1),
3 W fixed bin(31),
2 X picture ’$9V99’;
The minor structure at the deepest logical level is G, so this is mapped first. Then E
is mapped, followed by N, S, C, and M, in that order.
For each minor structure, a table in Figure 10 on page 189 shows the steps in the
process, and a diagram in Figure 11 on page 190 shows a visual interpretation of
the process. Finally, the major structure A is mapped as shown in Figure 17 on page
193. At the end of the example, the structure map for A is set out in the form of a
table (Figure 18 on page 194) showing the offset of each member from the start of
A.
188
Enterprise PL/I for z/OS Language Reference
Structure mapping example
Figure 10. Mapping of example structure
Chapter 7. Data declarations
189
Structure mapping example
Figure 11. Mapping of minor structure G
Figure 12. Mapping of minor structure E
190
Enterprise PL/I for z/OS Language Reference
Structure mapping example
Figure 13. Mapping of minor structure N
Figure 14. Mapping of minor structure S
Chapter 7. Data declarations
191
Structure mapping example
Figure 15. Mapping of minor structure C
Figure 16. Mapping of minor structure M
192
Enterprise PL/I for z/OS Language Reference
Structure mapping example
Figure 17. Mapping of major structure A
Chapter 7. Data declarations
193
Figure 18. Offsets in final mapping of structure A
194
Enterprise PL/I for z/OS Language Reference
Chapter 8. Statements and directives
ALLOCATE statement . . . . . . . . . .
ASSERT statement. . . . . . . . . . . .
Assignment and compound assignment statements
Assignment statement . . . . . . . . .
Assignment statement by using BY
DIMACROSS . . . . . . . . . . .
Compound assignment statement . . . . .
Target variables . . . . . . . . . . .
Array targets . . . . . . . . . . .
Union targets . . . . . . . . . . .
Structure targets . . . . . . . . . .
How assignments are performed . . . . . .
Element assignments . . . . . . . . .
Aggregate assignments . . . . . . . .
Multiple assignments . . . . . . . . . .
Examples . . . . . . . . . . . . . .
Example of moving internal data . . . . .
Example of assigning expression values . .
Example of assigning a structure using BY
NAME . . . . . . . . . . . . .
Example of assigning a structure using BY
DIMACROSS . . . . . . . . . . .
ATTACH statement . . . . . . . . . . .
BEGIN statement . . . . . . . . . . . .
CALL statement . . . . . . . . . . . .
CLOSE statement . . . . . . . . . . . .
DECLARE statement . . . . . . . . . . .
DEFINE ALIAS statement . . . . . . . . .
DEFINE ORDINAL statement . . . . . . . .
DEFINE STRUCTURE statement . . . . . . .
DEFAULT statement . . . . . . . . . . .
DELAY statement . . . . . . . . . . . .
DELETE statement . . . . . . . . . . .
DETACH statement . . . . . . . . . . .
DISPLAY statement . . . . . . . . . . .
DO statement . . . . . . . . . . . . .
Type 1. . . . . . . . . . . . . . .
Types 2 and 3 . . . . . . . . . . . .
Using type 2 WHILE and UNTIL. . . . .
Using type 3 with one specification . . . .
Using type 3 with two or more specifications
Using type 3 with TO, BY, REPEAT . . . .
Using type 3 with UPTHRU . . . . . .
Using type 3 with DOWNTHRU . . . . .
Type 4. . . . . . . . . . . . . . .
Examples of basic repetitions . . . . . . .
Repetition using the reference as a subscript
Repetition with TO and BY . . . . . . .
Example of DO with WHILE, UNTIL . . . .
Example of DO with UPTHRU and
DOWNTHRU . . . . . . . . . . . .
196
196
198
198
198
199
200
200
200
200
201
201
201
203
203
203
203
203
204
205
205
205
205
205
205
205
205
205
205
206
206
206
207
207
207
210
210
211
211
213
214
214
215
215
215
216
Example of REPEAT .
END statement . . . .
ENTRY statement . . .
EXIT statement . . . .
FETCH statement . . .
FLUSH statement . . .
FORMAT statement . .
FREE statement . . .
GET statement . . . .
GO TO statement . . .
IF statement . . . . .
Examples . . . . .
Short-circuit evaluation
%INCLUDE directive. .
ITERATE statement . .
LEAVE statement . . .
Example . . . . .
%LINE directive . . .
LOCATE statement . .
%NOPRINT directive. .
%NOTE directive . . .
null statement . . . .
ON statement . . . .
OPEN statement . . .
OTHERWISE statement .
PACKAGE statement . .
%PAGE directive . . .
%POP directive. . . .
%PRINT directive . . .
PROCEDURE statement .
%PROCESS directive . .
*PROCESS directive . .
%PUSH directive . . .
PUT statement . . . .
READ statement . . .
RELEASE statement . .
RESIGNAL statement. .
RETURN statement . .
REVERT statement . .
REWRITE statement . .
SELECT statement. . .
Examples . . . . .
SIGNAL statement . .
%SKIP directive . . .
STOP statement . . .
WAIT statement . . .
WHEN statement . . .
WRITE statement . . .
%XINCLUDE statement .
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
218
219
219
219
220
220
220
220
220
220
221
222
222
224
224
224
225
225
226
226
226
227
227
227
227
227
227
227
228
228
228
228
229
229
229
230
230
230
230
230
230
231
232
232
232
232
233
233
233
217
This chapter lists all of the PL/I statements and %directives. %Statements and
macro statements are described in chapters Chapter 20, “Preprocessor Facilities,”
on page 725.
© Copyright IBM Corp. 1999, 2012
195
Statements and directives
ALLOCATE statement
The ALLOCATE statement is described in Chapter 9, “Storage control,” on page
235
ASSERT statement
The ASSERT statement asserts whether a condition is true or false or whether a
statement should not be executed.
ASSERT
TRUE ( test-expression )
FALSE ( test-expression )
UNREACHABLE
TEXT
( display-expression
)
TRUE(test-expression)
Asserts that test-expression is true when one or more bits in test-expression have
the value ’1’B.
FALSE(test-expression)
Asserts that test-expression is false when all the bits in test-expression have the
value ’0’B.
TEXT(display-expression)
Passes the display-expression to the assertion routine if the assert fails.
UNREACHABLE
Asserts that the statement cannot be reached, because it is bypassed by a
proceeding statement, such as a GOTO, RETURN, or SIGNAL statement.
display-expression
A scalar CHARACTER expression.
test-expression
A computational scalar expression that is to be, if necessary, converted to BIT.
If the assertion fails, the compiled code calls routine IBMPASU for ASSERT
UNREACHABLE and IBMPAST for all the other ASSERT statements. The compiled
code calls these routines with the following BYVALUE parameters:
v A POINTER holding the address of a buffer that contains the PACKAGENAME
value as a varying character string
v A POINTER holding the address of a buffer that contains the PROCNAME value
as a varying character string
v A FIXED BIN(31) holding the SOURCELINE value
v A POINTER holding the ADDRDATA of the TEXT value. If the TEXT clause is
omitted, the value passed is SYSNULL.
v A FIXED BIN(31) holding the LENGTH of the TEXT value. If the TEXT clause is
omitted, the value passed is 0.
196
Enterprise PL/I for z/OS Language Reference
Statements and directives
Example
The following example shows the usage of the ASSERT statement. You must code
the routines that are used in this example.
asserts: package;
main: proc options(main);
dcl n fixed bin;
n = 1;
assert true( n> 0 );
assert true( n= 2 ) text(’n not equal to 2’);
assert unreachable;
end;
ibmpasu:
proc( packagename_ptr, procname_ptr, assert_sourceline,
text_addr, text_length )
ext( ’_IBMPASU’)
options( byvalue );
dcl
dcl
dcl
dcl
dcl
packagename_ptr
procname_ptr
assert_sourceline
text_addr
text_length
pointer;
pointer;
fixed bin(31);
pointer;
fixed bin(31);
dcl assert_packagename char(100) var based(packagename_ptr);
dcl assert_procname char(100) var based(procname_ptr);
dcl assert_text char(text_length) based(text_addr);
put skip edit( ’unreachable code hit on line ’,
trim(assert_sourceline),
’ in ’,
assert_packagename,
’:’, assert_procname )
( a );
if text_length = 0 then;
else
put skip list( assert_text );
end;
ibmpast:
proc( packagename_ptr, procname_ptr, assert_sourceline,
text_addr, text_length )
ext( ’_IBMPAST’)
options( byvalue );
dcl
dcl
dcl
dcl
dcl
packagename_ptr
procname_ptr
assert_sourceline
text_addr
text_length
pointer;
pointer;
fixed bin(31);
pointer;
fixed bin(31);
dcl assert_packagename char(100) var based(packagename_ptr);
dcl assert_procname char(100) var based(procname_ptr);
dcl assert_text char(text_length) based(text_addr);
put skip edit( ’conditional assertion failed on line ’,
trim(assert_sourceline),
’ in ’,
assert_packagename,
’:’, assert_procname )
Chapter 8. Statements and directives
197
Statements and directives
( a );
if text_length = 0 then;
else
put skip list( assert_text );
end;
Assignment and compound assignment statements
The assignment statement evaluates an expression and assigns its value to one or
more target variables.
These statements are used for internal data movement, as well as for specifying
computations. (The GET and PUT statements with the STRING option can also be
used for internal data movement. Additionally, the PUT statement can specify
computations to be done. See Chapter 12, “Stream-oriented data transmission,” on
page 299.)
Because the attributes of the target variable or pseudovariable can differ from the
attributes of the source (a variable, a constant, or the result of an expression), the
assignment statement might require conversions (see Chapter 4, “Data conversion,”
on page 73).
Assignment statement
Use the following syntax for the assignment statement.
,
reference
=
expression
;
,BY NAME
reference
Specifies the target to be given the assignment
expression
Specifies an expression that is evaluated and possibly converted
BY NAME
For structure assignments, the BY NAME option specifies the assignment
follows the steps outlined under “Structure assignments” on page 202.
Assignment statement by using BY DIMACROSS
Use the following syntax for the assignment statement by using BY DIMACROSS.
reference
=
exp1 ,BY DIMACROSS (exp2) ;
reference
Specifies the target to be given the assignment
exp1
Specifies an expression that is evaluated and possibly converted
198
Enterprise PL/I for z/OS Language Reference
Assignment
BY DIMACROSS
For structure assignments, the BY DIMACROSS option specifies that the
assignment follows the steps outlined under“Structure assignments” on page
202.
exp2
Specifies an expression that is used as the index appended to the associated
DIMACROSS structure elements.
Compound assignment statement
Use the following syntax for the compound assignment statement.
,
reference
compound assignment operator
expression ;
reference
Specifies the target to be given the assignment
compound assignment operator
Specifies the operator that is applied to the reference and the evaluated
expression before the assignment is made. Table 28 lists the compound
assignment operators allowed in compound assignments.
expression
Specifies an expression that is evaluated and possibly converted.
Area assignment is described in “Area data and attribute” on page 253.
Table 28. Compound assignment operators
Compound
assignment operator
Meaning
+=
Evaluate expression, add and assign
-=
Evaluate expression, subtract and assign
*=
Evaluate expression, multiply and assign
/=
Evaluate expression, divide and assign
|=
Evaluate expression, or and assign
&=
Evaluate expression, and and assign
{=
Evaluate expression, concatenate and assign
**=
Evaluate expression, exponentiate and assign
¬= or <>
Evaluate expression, exclusive-or and assign
The operator is applied to the target and source first, and then what results is
assigned to the target.
For example:
X += 1
X *= Y+Z
is the same as
is the same as
X = X+(1)
X = X*(Y+Z)
Chapter 8. Statements and directives
199
Assignment
but
X *= Y+Z
is not equivalent to
X = X*Y+Z
In a compound assignment, any subscripts or locator expressions specified in the
target variable are evaluated only once.
If f is a function and X is an array, then:
X(f()) += 1
is not equivalent to
X(f()) = X(f())+1
The function f is called only once.
The remaining text discusses the following topics: :
v The requirements for target variables
v How element and aggregate assignments are performed
v How BY NAME assignments are performed
v How multiple assignment are performed.
Examples of assignments begin in “Example of moving internal data” on page 203.
Target variables
The target variables can be element, array, or structure variables; or
pseudovariables.
Array targets
For array assignments, each target variable must be an array of scalars or
structures. The source must be a scalar or an expression with the same number of
dimensions and the same bounds for all dimensions as for the target.
Union targets
Union assignments are not allowed.
Structure targets
In BY NAME structure assignments, each target variable must be a structure. The
right-hand side must be a structure reference.
In structure assignments not using BY NAME or BY DIMACROSS, each target
variable must be a structure. The right-hand side must be a scalar or a structure
expression with the same structuring as the target structure:
v The structures must have the same minor structuring and the same number of
contained elements and arrays.
v The positioning of the elements and arrays within the structure (and within the
minor structures, if any) must be the same.
v Arrays in corresponding positions must have identical bounds.
In BY DIMACROSS structure assignments, the target variable must be a structure.
The DIMACROSS index expression is applied to all structures that are declared
with the DIMACROSS attribute and used in the assignment either as the target or
as part of the source. The following restrictions apply to these assignments:
v Only one target reference is valid.
v The structuring and bounds of all structures in the source must match those in
the target.
200
Enterprise PL/I for z/OS Language Reference
Target variables
In structure assignments not using the BY NAME and BY DIMACROSS options,
the source might be the null bit string ( ''b ) even if the target structure contains
non-computational data. In this case, the assignment is performed as if all of the
following conditions are true:
1. All of the target was filled with '00'x.
2. All the numeric target fields were set to 0.
3. All the nonvarying character, widechar and graphic fields were filled with
blanks.
How assignments are performed
Element assignments
Element assignments are performed as follows:
1. First to be evaluated are subscripts, POSITION attribute expressions, locator
qualifications of the target variables, and the second and third arguments of
SUBSTR pseudovariable references.
2. The expression on the right-hand side is then evaluated.
3. For each target variable (in left to right order), the expression is converted to
the characteristics of the target variable according to the rules for data
conversion. The converted value is then assigned to the target variable.
Aggregate assignments
Aggregate assignments (array and structure assignments) are expanded into a
series of element assignments as follows:
1. The label prefix of the original statement is applied to a null statement
preceding the other generated statements.
2. Array and structure assignments, when there are more than one, are done
iteratively.
3. Any assignment statement can be generated by a previous array or structure
assignment. The first target variable in an aggregate assignment is known as
the master variable. (It can also be the first argument of a pseudovariable). If
the master variable is an array, an array expansion is performed; otherwise, a
structure expansion is performed.
4. If an aggregate assignment meets a certain set of conditions, it can be done as a
whole instead of being expanded into a series of element assignments. Two
conditions are if the arrays are not interleaved, or if the structures are
contiguous and have the same format.
Array assignments:
In array assignments, all array operands must have the same number of
dimensions and identical bounds. The array assignment is expanded into a loop as
follows:
do J1 = lbound(Master-variable,1) to
hbound(Master-variable,1);
do J2 = lbound(Master-variable,2) to
hbound(Master-variable,2);
.
.
.
do Jn = lbound(Master-variable,N) to
hbound(Master-variable,N);
Chapter 8. Statements and directives
201
How assignments are performed
generated assignment statement
end;
In this expansion, n is the number of dimensions of the master variable that are to
participate in the assignment. In the generated assignment statement, all array
operands are fully subscripted, using (from left to right) the dummy variables j1 to
jn. If an array operand appears with no subscripts, it has only the subscripts j1 to
jn. If cross-section notation is used, the asterisks are replaced by j1 to jn. If the
original assignment statement has a condition prefix, the generated assignment
statement is given this condition prefix.
If the generated assignment statement is a structure assignment, it is expanded as
described next.
Structure assignments:
In structure assignments where the BY NAME option is not specified:
v None of the operands can be arrays, although they can be structures that contain
arrays.
v All of the structure operands must have the same number, k, of immediately
contained items.
v The assignment statement is replaced by k generated assignment statements.
– The ith generated assignment statement is derived from the original
assignment statement by replacing each structure operand by its ith
contained item; such generated assignment statements can require further
expansion.
– All generated assignment statements are given the condition prefix of the
original statement.
Structure assignments using the BY NAME option:
In structure assignments where the BY NAME option is given, the structure
assignment is expanded according to the steps below, which can generate further
array and structure assignments. None of the operands can be arrays.
1. The first item immediately contained in the master variable is considered.
2. If each structure operand and target variable has an immediately contained
item with the same name, an assignment statement is generated as follows:
a. The statement is derived by replacing each structure operand and target
variable with its immediately contained item that has this name. If any
structure contains no such name, no statement is generated.
b. If the generated assignment is a structure or array-of-structures assignment,
BY NAME is appended.
c. All generated assignment statements are given the condition prefix of the
original assignment statement.
d. A target structure must not contain unions.
3. Step 2 is repeated for each of the items immediately contained in the master
variable. The assignments are generated in the order of the items contained in
the master variable.
Structure assignments using the BY DIMACROSS option:
202
Enterprise PL/I for z/OS Language Reference
How assignments are performed
In structure assignments where the BY DIMACROSS option is given, the structure
assignment is expanded using the DIMACROSS expression as the index into the
associated array elements. None of the operands can be arrays.
Multiple assignments
Assignments can be made to multiple variables in a single assignment statement,
for example:
A,X = B + C;
The value of B + C is assigned to both A and X. In general, it has the same effect as
the following statements:
Temporary = B + C;
A = Temporary;
X = Temporary;
The source in the assignment statement must be a scalar or an array of scalars, and
if the source is an array, all the targets must also be arrays. If the source is a
constant, it is assigned to each of the targets from left to right. If the source is not a
constant, it is assigned to a temporary variable, which is then assigned to each of
the targets from left to right.
The target can be any reference allowed in a simple assignment.
BY DIMACROSS is not allowed in multiple assignments.
Although not recommended, the compound assignment operator may be used in
multiple assignments. However, the results may not always be what might be
naively expected; for example, the following statements will generally not produce
the same results:
c, c += c;
c, c = c + c;
Examples
Example of moving internal data
The following example of the assignment statement can be used for internal data
movement. The value of the expression on the right of the assignment symbol is
assigned to the variable on the left.
NTOT=TOT;
Example of assigning expression values
The following example includes an expression whose value is to be assigned to the
variable on the left of the assignment symbol:
Av=(Av*Num+Tav*Tnum)/(Num+Tnum);
Example of assigning a structure using BY NAME
The following example illustrates structure assignment using the BY NAME option:
declare
declare
1 One,
1 Two,
2 Part1,
2 Part1,
3 Red,
3 Blue,
3 Orange,
3 Green,
2 Part2,
3 Red,
3 Yellow,
2 Part2,
3 Blue,
3 Brown,
3 Green;
3 Yellow;
declare
1 Three,
2 Part1,
3 Red,
3 Blue,
3 Brown,
2 Part2,
3 Yellow,
3 Green;
Chapter 8. Statements and directives
203
Multiple assignments
1
2
1
One = Two, by name;
One.Part1 = Three.Part1, by name;
The first assignment statement is the same as the following:
One.Part1.Red
= Two.Part1.Red;
One.Part2.Yellow = Two.Part2.Yellow;
2
The second assignment statement is the same as the following:
One.Part1.Red = Three.Part1.Red;
Example of assigning a structure using BY DIMACROSS
The following example illustrates structure assignment using the BY DIMACROSS
option.
Example 1
This code sums up all the row elements:
dcl
1 x,
2
2
2
2
a
b
c
d
fixed
fixed
fixed
fixed
bin(31),
bin(31),
bin(31),
bin(31);
dcl 1 xa(17) dimacross like x;
dcl jx fixed bin;
x = 0;
do jx = lboundacross( xa ) to hboundacross( xa );
x = x + xa, by dimacross( jx );
end;
The assignment inside the loop is equivalent to the following statements:
x.a
x.b
x.c
x.d
=
=
=
=
x.a
x.b
x.c
x.d
+
+
+
+
xa.a(jx);
xa.b(jx);
xa.c(jx);
xa.d(jx);
Example 2
This code exchanges the entries in the first and seventeenth columns of xa:
dcl
1 x,
2
2
2
2
a
b
c
d
fixed
fixed
fixed
fixed
bin(31),
bin(31),
bin(31),
bin(31);
dcl 1 xa(17) dimacross like x;
dcl y like x;
x = xa,
y = xa,
xa = y,
xa = x,
204
by
by
by
by
Enterprise PL/I for z/OS Language Reference
dimacross(
dimacross(
dimacross(
dimacross(
1
17
1
17
);
);
);
);
Multiple assignments
ATTACH statement
The ATTACH statement is described in Chapter 17, “Multithreading facility,” on
page 377.
BEGIN statement
The BEGIN statement is described in Chapter 5, “Program organization,” on page
87.
CALL statement
The CALL statement is described in “CALL statement” on page 127.
CLOSE statement
The CLOSE statement is described in Chapter 10, “Input and output,” on page 275.
DECLARE statement
The DECLARE statement is described in “DECLARE statement” on page 152.
DEFINE ALIAS statement
The DEFINE ALIAS statement is described in Chapter 6, “Type definitions,” on
page 139.
DEFINE ORDINAL statement
The DEFINE ORDINAL statement is described in Chapter 6, “Type definitions,” on
page 139.
DEFINE STRUCTURE statement
The DEFINE STRUCTURE statement is described in Chapter 6, “Type definitions,”
on page 139.
DEFAULT statement
The DEFAULT statement is described in “DEFAULT statement” on page 169.
DELAY statement
The DELAY statement suspends the execution of the next statement in the
application program for the specified period of time.
DELAY (expression) ;
expression
Specifies an expression that is evaluated and converted to FIXED
BINARY(31,0). Execution is suspended for the number of milliseconds
specified.
Chapter 8. Statements and directives
205
DELAY
The maximum wait time is 23 hours and 59 minutes.
For example:
v delay (20); suspends execution for 20 milliseconds.
v delay (10**3); suspends execution for one second.
v delay (10*10**3); suspends execution for ten seconds.
When a program is running under CICS, the DELAY statement is implemented by
using the EXEC CICS DELAY command. Currently the time interval for the EXEC
CICS DELAY command has a minimum of one second. The milliseconds number
specified in the PL/I DELAY statement is rounded down to the nearest second
except when the value is less than 1 second, in which case it is set to 1.
For example:
v delay(30); suspends execution for 1 second under CICS.
v delay(2100); suspends execution for 2 seconds under CICS.
DELETE statement
The DELETE statement is described in Chapter 11, “Record-oriented data
transmission,” on page 289.
DETACH statement
The DETACH statement is described in Chapter 17, “Multithreading facility,” on
page 377.
DISPLAY statement
The DISPLAY statement displays a message on the user's screen and optionally
requests the user to enter a response to the message.
DISPLAY (expression)
;
REPLY (char-ref)
expression
Is converted, where necessary, to a character string. This character string is
displayed. It can contain mixed character data. If the expression has the
GRAPHIC attribute, it is not converted.
REPLY (char-ref)
Specifies a character reference that receives the user entered response. The
response can contain CHARACTER, GRAPHIC, or mixed data.
The REPLY option suspends program execution until the user enters a response.
If GRAPHIC data is entered in the REPLY, it is received as character data that
contains mixed data. Such character data can be converted to GRAPHIC data using
the GRAPHIC BUILTIN.
Example:
206
Enterprise PL/I for z/OS Language Reference
DISPLAY
display (’Communication link established.’);
displays the message
Communication link established.
DO statement
The DO statement and its corresponding END statement, delimit a group of
statements collectively called a do-group.
Note: Condition prefixes are invalid on DO statements.
Type 1
The type 1 do-group specifies that the statements in the group are executed. It
does not provide for the repetitive execution of the statements within the group.
Type 1
DO ;
expn
An abbreviation for expression n.
Types 2 and 3
Types 2 and 3 provide for the repetitive execution of the statements within the
do-group.
Type 2
DO
WHILE (
UNTIL (
exp4
exp5
)
;
UNTIL (
exp5
)
WHILE (
exp4
)
)
Chapter 8. Statements and directives
207
DO
Type 3
,
DO reference = specification
exp1
TO
exp2
WHILE (
exp4 )
UNTIL (
exp5 )
BY exp3
BY
exp3
TO exp2
UPTHRU exp2
DOWNTHRU exp2
REPEAT exp6
UNTIL (
exp5 )
WHILE (
exp4 )
expn
An abbreviation for expression n.
WHILE (exp4)
Specifies that, before each repetition of do-group, exp4 is evaluated and, if
necessary, converted to a bit string. If any bit in the resulting string is 1, the
do-group is executed. If all bits are 0, or the string is null, execution of the
Type 2 do-group is terminated. For Type 3, only the execution associated with
the specification containing the WHILE option is terminated. Execution for the
next specification, if one exists, then begins.
UNTIL (exp5)
Specifies that, after each repetition of do-group, exp5 is evaluated, and, if
necessary, converted to a bit string. If all the bits in the resulting string are 0,
or the string is null, the next iteration of the do-group is executed. If any bit is
1, execution of the Type 2 do-group is terminated. For Type 3, only the
execution associated with the specification containing the UNTIL option is
terminated. Execution for the next specification, if one exists, then begins.
reference
The only pseudovariables that can be used as references are SUBSTR, REAL,
IMAG and UNSPEC. All data types are allowed.
The generation, g, of a reference is established once at the beginning of the
do-group, immediately before the initial value expression (exp1) is evaluated. If
the reference generation is changed to h in the do-group, the do-group
continues to execute with the reference derived from the generation g.
However, any reference to the reference inside the do-group is a reference to
generation h. It is an error to free generation g in the do-group.
If a reference is made to a reference after the last iteration is completed, the
value of the variable is the value that was out of range of the limit set in the
specification. The preceding is true if the following conditions apply to the
limit set in the application:
v The BY value is positive and the reference is greater than the TO value.
v The BY value is negative and the reference is less than the TO value.
If reference is a program-control data variable, but is not a locator, the BY and
TO options cannot be used in specification.
If reference is a program-control variable, but is not a locator or an ordinal, the
UPTHRU and DOWNTHRU options cannot be used in specification.
208
Enterprise PL/I for z/OS Language Reference
DO
exp1
Specifies the initial value of the reference.
If TO, BY, and REPEAT are all omitted from a specification, there is a single
execution of the do-group, with the reference having the value of exp1. If
WHILE(exp4) is included, the single execution does not take place unless exp4
is true.
TO exp2
exp2 is evaluated at entry to the specification and saved. This saved value
specifies the terminating value of the reference. Execution of the statements in
a do-group terminates for a specification as soon as the value of the reference,
when tested at the beginning of the do-group, is out of range. Execution of the
next specification, if one exists, then begins.
If TO exp2 is omitted from a specification, and if BY exp3 is specified, repetitive
execution continues until it is terminated by the WHILE or UNTIL option, or
until another statement transfers control out of the do-group.
BY exp3
exp3 is evaluated at entry to the specification and saved. This saved value
specifies the increment to be added to the reference after each execution of the
do-group.
If BY exp3 is omitted from a specification, and if TO exp2 is specified, exp3
defaults to 1.
If BY 0 is specified, the execution of the do-group continues indefinitely unless
it is halted by a WHILE or UNTIL option, or control is transferred to a point
outside the do-group.
UPTHRU exp2
exp2 is evaluated at entry to the specification and saved. This saved value
specifies the terminating value of the reference. Execution of the statements in
a do-group terminates for a specification as soon as the value of the reference,
when tested at the end of the do-group, is out of range. Execution of the next
specification, if one exists, then begins.
If UPTHRU is specified, the reference is compared to exp2 after the statements
in the loop are executed, but before the reference is updated with the next
value it can assume. The loop is executed at least once.
UPTHRU is used primarily when processing ordinals using loops; however, it
can also be used for a reference which is an arithmetic or locator control
variable. If the reference is not an ordinal, the increment to be added to the
reference after each execution of the do-group is assumed to be +1.
DOWNTHRU exp2
exp2 is evaluated at entry to the specification and saved. This saved value
specifies the terminating value of the reference. Execution of the statements in
a do-group terminates for a specification as soon as the value of the reference,
when tested at the end of the do-group, is out of range. Execution of the next
specification, if one exists, then begins.
If DOWNTHRU is specified, the reference is compared to exp2 after the
statements in the loop are executed, but before the reference is updated with
the next value it could assume. The loop is executed at least once.
DOWNTHRU is used primarily when processing ordinals using loops;
however, it can also be used for a reference which is an arithmetic or locator
control variable. If the reference is not an ordinal, the increment to be added to
the reference after each execution of the do-group is assumed to be -1.
Chapter 8. Statements and directives
209
DO
REPEAT exp6
exp6 is evaluated and assigned to the reference after each execution of the
do-group. Repetitive execution continues until it is terminated by the WHILE
or UNTIL option, or another statement transfers control out of the do-group.
In Type 3 do-groups, you should not rely on the order in which exp1, exp2 and
exp3 are evaluated. Consequently, it is best if none of these expressions invoke
functions that set values used in the other expressions.
Control can transfer into a do-group from outside the do-group only if the
do-group is delimited by the DO statement in Type 1. Consequently, Type 2 and 3
do-groups cannot contain ENTRY statements. Control can also return to a
do-group from a procedure or ON-unit invoked from within that do-group.
The following sections give more information about using Type 2 and Type 3 DO
groups. Examples of DO groups begin in “Examples of basic repetitions” on page
215.
Using type 2 WHILE and UNTIL
If a Type 2 DO specification includes both the WHILE and UNTIL option, the DO
statement provides for repetitive execution as defined by the following:
Label:
Next:
do while (Exp4)
until (Exp5)
statement-1
.
.
.
statement-n
end;
statement /* Statement following the do-group */
The above is equivalent to the following expansion:
Label:
if (Exp4) then;
else
go to Next;
statement-1
.
.
.
statement-n
Label2: if (Exp5) then;
else
go to Label;
Next:
statement /* Statement following the do-group */
If the WHILE option is omitted, the IF statement at label Label is replaced by a
null statement. Note that if the WHILE option is omitted, statements 1 through n
are executed at least once.
If the UNTIL option is omitted, the IF statement at label Label2 in the expansion is
replaced by the statement GO TO Label.
Using type 3 with one specification
The following sequence of events summarizes the effect of executing a do-group
with one specification:
1. If reference is specified and BY, TO, UPTHRU, or DOWNTHRU options are
also specified, exp1, exp2, and exp3 will be evaluated prior to the assignment
of exp1 to the reference. Then the initial value is assigned to reference, for
example:
210
Enterprise PL/I for z/OS Language Reference
DO
do Reference = Exp1 to Exp2 by Exp3;
For a variable that is not a pseudovariable, the action of the do-group
definition in the preceding example is equivalent to the following expansion:
E1=Exp1;
E2=Exp2;
E3=Exp3;
V=E1;
The variable V is a compiler-created based variable with the same attributes as
the reference. E1, E2, and E3 are compiler-created variables.
2. If the TO option is present, test the value of the control variable against the
previously-evaluated expression (E2) in the TO option.
3. If the WHILE option is specified, evaluate the expression in the WHILE option.
If it is false, leave the do-group.
4. Execute the statements in the do-group.
5. If the UNTIL option is specified, evaluate the expression in the UNTIL option.
If it is true, leave the do-group.
6. If the UPTHRU option is specified, test the value of the control variable against
the previously evaluated expression in the UPTHRU expression.
7. If the DOWNTHRU option is specified, test the value of the control variable
against the previously evaluated expression in the DOWNTHRU expression.
8. If there is a reference:
a. If the TO or BY option is specified, add the previously-evaluated exp3 (E3)
to the reference.
b. If the REPEAT option is specified, evaluate the exp6 and assign it to the
reference.
c. If the TO, BY, and REPEAT options are all absent, leave the do-group.
d. If the UPTHRU option is specified and the reference is an ordinal, assign
the reference the successor of its current value. Otherwise, add 1 to the
reference.
e. If the DOWNTHRU option is specified and the reference is an ordinal,
assign it the predecessor of its current value. Otherwise, subtract 1 from the
reference.
f. If the TO, BY, UPTHRU, DOWNTHRU, and REPEAT options are all absent,
leave the do-group.
9. Go to 2.
Using type 3 with two or more specifications
If the DO statement contains more than one specification, the second expansion is
analogous to the first expansion in every respect. However, the statements in the
do-group are not actually duplicated in the program. A succeeding specification is
executed only after the preceding specification has been terminated.
When execution of the last specification terminates, control passes to the statement
following the do-group.
Using type 3 with TO, BY, REPEAT
The TO and BY options let you vary the reference in fixed positive or negative
increments. In contrast, the REPEAT option, which is an alternative to the TO and
BY options, lets you vary the control variable nonlinearly. The REPEAT option can
also be used for nonarithmetic control variables (such as pointer).
Chapter 8. Statements and directives
211
DO
If the Type 3 DO specification includes the TO and BY options, the action of the
do-group is defined by the following:
Label:
do Variable=
Exp1
to Exp2
by Exp3
while (Exp4)
until(Exp5);
statement-1
.
.
.
statement-m
Label1: end;
Next:
statement
The action of the previous do-group definition is equivalent to the following
expansion. In this expansion, V is a compiler-created variable with the same
attributes as Variable; and E1, E2, and E3 are compiler-created variables:
Label:
E1=Exp1;
E2=Exp2;
E3=Exp3;
V=E1;
Label2: if (E3>=0)&(V>E2)|(E3<0)&(V<E2) then
go to Next;
if (Exp4) then;
else
go to Next;
statement-1
.
.
.
statement-m
Label1: if (Exp5) then
go to Next;
Label3: V=V+E3;
go to Label2;
Next:
statement
If the specification includes the REPEAT option, the action of the do-group is
defined by the following:
Label:
do Variable=
Exp1
repeat Exp6
while (Exp4)
until(Exp5);
statement-1
.
.
.
statement-m
Label1: end;
Next:
statement
The action of the previous do-group definition is equivalent to the following
expansion:
Label:
E1=Exp1;
V=E1;
Label2: ;
if (Exp4) then;
else
go to Next;
statement-1
212
Enterprise PL/I for z/OS Language Reference
DO
.
.
.
statement-m
Label1: if (Exp5) then
go to Next;
Label3: V=Exp6;
go to Label2;
Next:
statement
Additional rules for the sample expansions are as follows:
1. The previous expansion shows only the result of one specification. If the DO
statement contains more than one specification, the statement labeled NEXT is
the first statement in the expansion for the next specification. The second
expansion is analogous to the first expansion in every respect. Statements 1
through m, however, are not actually duplicated in the program.
2. If the WHILE clause is omitted, the IF statement immediately preceding
statement-1 in each of the expansions is also omitted.
3. If the UNTIL clause is omitted, the IF statement immediately following
statement-m in each of the expansions is also omitted.
Using type 3 with UPTHRU
If the Type 3 DO specification includes the UPTHRU option, the action of the
do-group is defined by the following:
Label:
do Variable = Exp1 upthru Exp2 while (Exp4) until (Exp5);
statement1
.
.
.
statementn
Label1: end;
Next: statement
The action of the previous do-group is equivalent to the following expansion. In
this expansion, V is a compiler-generated variable with the same attributes as
Variable; and E1 and E2 are compiler-generated variables:
Label:
E1 = Exp1;
E2 = Exp2;
V = E1;
Label2: if (Exp4) then;
else
go to next;
statement1
.
.
.
statementn
Label1: if (Exp5) then
go to Next;
if V ≥ E2 then
go to Next;
V = V + 1;
go to Label2;
Next: statement
If the reference is an ordinal, the statement V = V + 1 is replaced by V =
ordinalsucc(V).
Chapter 8. Statements and directives
213
DO
Using type 3 with DOWNTHRU
If the Type 3 DO specification includes the DOWNTHRU option, the action of the
do-group is defined by the following:
Label:
do Variable = Exp1 downthru Exp2 while (Exp4) until (Exp5);
statement1
.
.
.
statementn
Label1: end;
Next: statement
The action of the previous do-group is equivalent to the following expansion. In
this expansion, V is a compiler-generated variable with the same attributes as
Variable; and E1 and E2 are compiler-generated variables:
Label:
E1 = Exp1;
E2 = Exp2;
V = E1;
Label2: if (Exp4) then;
else
go to Next;
statement1
.
.
.
statementn
Label1: if (Exp5) then
go to Next;
if V ≤ E2 then
go to Next;
V = V - 1;
go to Label2;
Next: statement
If the reference is an ordinal, the statement V = V - 1 is replaced by V =
ordinalpred(V).
Type 4
LOOP
Specifies infinite iteration. FOREVER is a synonym of LOOP.
For example:
dcl Payroll file;
dcl 1 Payrec,
2 Type char,
2 Subtype char,
2 * char(100);
Readfile:
do loop;
read file(Payroll) into(Payrec);
If Payrec.type = ’E’
then leave; /* like goto After_ReadFile */
If Payrec.type = ’1’ then
do;
/* process first part of record */
214
Enterprise PL/I for z/OS Language Reference
DO
If Payrec.subtype = ’S’
then iterate Readfile; /* like goto End_ReadFile */
/* process remainder of record */
end;
End_ReadFile:
end;
After_ReadFile:;
The only way to exit this loop is by a LEAVE or GO TO, or by terminating a
procedure or the program.
Examples of basic repetitions
In the following example, the do-group is executed ten times, while the value of
the reference I progresses from 1 through 10.
do I = 1 to 10;
.
.
.
end;
The effect of this DO and END statement is equivalent to the following:
I = 1;
A: if I > 10 then go to B;
.
.
.
I = I +1;
go to A;
B: next statement
The following DO statement executes the do-group three times—once for each
assignment of ’Tom’, ’Dick’, and ’Harry’ to Name.
do Name = ’Tom’, ’Dick’, ’Harry’;
The following statement specifies that the do-group executes thirteen times—ten
times with the value of I equal to 1 through 10, and three times with the value of
I equal to 13 through 15:
do I = 1 to 10, 13 to 15;
Repetition using the reference as a subscript
The reference of a DO statement can be used as a subscript in statements within
the do-group, so that each execution deals with successive elements of a table or
array.
In the following example, the first ten elements of A are set to 1 through 10 in
sequence:
do I = 1 to 10;
A(I) = I;
end;
Repetition with TO and BY
The following example specifies that the do-group is executed five times, with the
value of I equal to 2, 4, 6, 8, and 10:
do I = 2 to 10 by 2;
If negative increments of the reference are required, the BY option must be used.
For example, the following is executed with I equal to 10, 8, 6, 4, 2, 0, and -2:
Chapter 8. Statements and directives
215
DO
do I = 10 to -2 by -2;
In the following example, the do-group is executed with I equal to 1, 3, 5:
I=2;
do I=1 to I+3 by I;
.
.
.
end;
The preceding example is equivalent to:
do I=1 to 5 by 2;
.
.
.
end;
Example of DO with WHILE, UNTIL
The WHILE and UNTIL options make successive executions of the do-group
dependent upon a specified condition, for example:
do while (A=B);
.
.
.
end;
is equivalent to the following:
S:
if A=B then;
else goto R;
.
.
.
goto S;
R: next statement
The example:
do until (A=B);
.
.
.
end;
is equivalent to the following:
S:
.
.
.
if (A=B) then goto R;
goto S;
R: next statement
In the absence of other options, a do-group headed by a DO UNTIL statement is
executed at least once, but a do-group headed by a DO WHILE statement might
not be executed at all. That is, the statements DO WHILE (A=B) and DO UNTIL (A¬=B)
are not equivalent.
In the following example, if A¬=B when the DO statement is first encountered, the
do-group is not executed at all.
do while(A=B) until(X=10);
216
Enterprise PL/I for z/OS Language Reference
DO
However, if A=B, the do-group is executed. If X=10 after an execution of the
do-group, no further executions are performed. Otherwise, a further execution is
performed provided that A is still equal to B.
In the following example, the do-group is executed at least once, with I equal to 1:
do I=1 to 10 until(Y=1);
If Y=1 after an execution of the do-group, no further executions are performed.
Otherwise, the default increment (BY 1) is added to I, and the new value of I is
compared with 10. If I is greater than 10, no further executions are performed.
Otherwise, a new execution commences.
The following statement specifies that the do-group executes ten times while C(I)
is less than zero, and then (provided that A is equal to B) once more:
do I = 1 to 10 while (C(I)<0),
11 while (A = B);
Example of DO with UPTHRU and DOWNTHRU
In the following example, the do-group executes 5 times and at the end of the loop
i has the value 5:
do i = 1 upthru 5;
.
.
.
end;
When the UPTHRU option is used, the reference is compared to the terminating
value before being updated; this can be very useful when there is no value after
the terminating value. For instance, the FIXEDOVERFLOW condition would not be
raised by the following loop:
do i = 2147483641 upthru 2147483647;
.
.
.
end;
Similarly, the following loop avoids the problem of decrementing an unsigned
value equal to zero:
dcl U unsigned fixed bin;
do U = 17 downthru 0;
.
.
.
end;
UPTHRU and DOWNTHRU are particularly useful with ordinals. Consider the
following example:
define ordinal Color ( Red value (1),
Orange,
Yellow,
Green,
Blue,
Indigo,
Violet);
dcl C ordinal Color;
do C = Red upthru Violet;
.
Chapter 8. Statements and directives
217
DO
.
.
end;
do C = Violet downthru Red;
.
.
.
end;
In the first loop, c assumes each successive color in ascending order from red to
violet. In the second loop, c assumes each successive color in descending order
from violet to red.
Example of REPEAT
In the following example, the do-group is executed with I equal to 1, 2, 4, 8, 16,
and so on:
do I = 1 repeat 2*I;
.
.
.
end;
The preceding example is equivalent to:
I=1;
A:
.
.
.
I=2*I;
goto A;
In the following example, the first execution of the do-group is performed with
I=1.
do I=1 repeat 2*I until(I=256);
After this and each subsequent execution of the do-group, the UNTIL expression is
tested. If I=256, no further executions are performed. Otherwise, the REPEAT
expression is evaluated and assigned to I, and a new execution commences.
The following example shows a DO statement used to locate a specific item in a
chained list:
do P=Phead repeat P -> Fwd
while(P¬=null())
until(P->Id=Id_to_be_found);
end;
The value Phead is assigned to P for the first execution of the do-group. Before each
subsequent execution, the value P -> Fwd is assigned to P. The value of P is tested
before the first and each subsequent execution of the do-group. If it is null, no
further executions are performed.
The following statement specifies that the do-group is to be executed nine times,
with the value of I equal to 1 through 9; then successively with the value of I
equal to 10, 20, 40, and so on. Execution ceases when the do-group has been
executed with a value of I greater than 10000.
218
Enterprise PL/I for z/OS Language Reference
DO
do I = 1 to 9, 10 repeat 2*I
until (I>10000);
.
.
.
end;
END statement
The END statement ends one or more blocks or groups. Every block or group must
have an END statement.
END
;
statement-label
statement-label
Cannot be subscripted. If a statement-label follows END, the END statement
closes the unclosed group or block headed by the nearest preceding DO,
SELECT, PACKAGE, BEGIN, or PROCEDURE statement having that
statement-label. Every block with a DO, SELECT, PACKAGE, BEGIN or
PROCEDURE statement must have a corresponding END statement.
If a statement-label does not follow END, the END statement closes the one
group or block headed by the nearest preceding DO, SELECT, PACKAGE,
BEGIN, or PROCEDURE statement for which there is no other corresponding
END statement.
Execution of a block terminates when control reaches the END statement for the
block. However, it is not the only means of terminating a block's execution, even
though each block must have an END statement. (See “Procedures” on page 93
and “Begin-blocks” on page 112 for more details.)
If control reaches an END statement for a procedure, it is treated as a RETURN
statement.
Normal termination of a program occurs when control reaches the END statement
of the main procedure.
ENTRY statement
The ENTRY statement is described in “ENTRY attribute” on page 115.
EXIT statement
The EXIT statement stops the current thread.
EXIT ;
Chapter 8. Statements and directives
219
ENTRY
FETCH statement
The FETCH statement is described in “FETCH statement” on page 103.
FLUSH statement
The FLUSH statement is described in Chapter 10, “Input and output,” on page 275.
FORMAT statement
The FORMAT statement is described in Chapter 12, “Stream-oriented data
transmission,” on page 299.
FREE statement
The FREE statement is described in Chapter 9, “Storage control,” on page 235.
GET statement
The GET statement is described in Chapter 12, “Stream-oriented data
transmission,” on page 299.
GO TO statement
The GO TO statement transfers control to the statement identified by the specified
label reference. The GO TO statement is an unconditional branch.
GO TO label ;
Abbreviation: GOTO
label
Specifies a label constant, a label variable, or a function reference that returns a
label value. Since a label variable can have different values at each execution of
the GO TO statement, control might not always transfer to the same statement.
If a GO TO statement transfers control from within a block to a point not
contained within that block, the block is terminated. If the transfer point is
contained in a block that did not directly activate the block being terminated, all
intervening blocks in the activation sequence are also terminated (see “Procedure
termination” on page 100).
When a GO TO statement specifies a label constant contained in a block that has
more than one activation, control is transferred to the activation current when the
GO TO is executed (see “Recursive procedures” on page 101).
A GO TO statement cannot transfer control:
v To an inactive block. Detection of such an error is not guaranteed.
v From outside a do-group to a statement inside a Type 2 or Type 3 do-group,
unless the GO TO terminates a procedure or ON-unit invoked from within the
do-group.
220
Enterprise PL/I for z/OS Language Reference
GO TO
v To a FORMAT statement.
If the destination of the GO TO is specified by a label variable, it can then be used
as a switch by assigning label constants to the label variable. If the label variable is
subscripted, the switch can be controlled by varying the subscript. By using label
variables or function references, quite complex switching can be effected. It is
usually true, however, that simple control statements are the most efficient. GOTO
operations from one block to another block hinder many optimizations in the
target block, unless the target label is the last statement in its block.
IF statement
The IF statement evaluates an expression and controls the flow of execution
according to the result of that evaluation. The IF statement thus provides a
conditional branch.
Note: Condition prefixes are invalid on ELSE statements.
IF expression THEN unit1
ELSE
unit2
expression
The expression must have the attributes BIT(1) NONVARYING unless
RULES(LAXIF) is used.
When expressions involve the use of the & and/or | operators, they are
evaluated as described in “Combinations of operations” on page 67.
unit
Either a valid single statement, a group, or a begin-block. All single statements
are considered valid and executable except DECLARE, DEFAULT, END,
ENTRY FORMAT, PROCEDURE, or a %statement. If a nonexecutable statement
is used, the result can be unpredictable. Each unit can contain statements that
specify a transfer of control (for example, GO TO). Hence, the normal sequence
of the IF statement can be overridden.
Each unit can be labeled and can have condition prefixes.
IF is a compound statement. The semicolon terminating the last unit also
terminates the IF statement.
If any bit in the string expression has the value '1'B, unit1 is executed and unit2, if
present, is ignored. If all bits are '0'B, or the string is null, unit1 is ignored and
unit2, if present, is executed.
IF statements can be nested. That is, either unit can itself be an IF statement, or
both can be. Since each ELSE is always associated with the innermost unmatched
IF in the same block or do-group, an ELSE with a null statement might be required
to specify a desired sequence of control. For example, if B and C are constants, the
following example:
if A = B then
.
.
.
else
Chapter 8. Statements and directives
221
IF
if A = C then
.
.
.
else
.
.
.
is equivalent to and would be better coded as:
select( A );
when ( B )
.
.
.
when ( C )
.
.
.
end;
Examples
In the following example, if the comparison is true (if A is equal to B), the value of
D is assigned to C, and the ELSE unit is not executed.
if A = B then
C = D;
else
C = E;
If the comparison is false (A is not equal to B), the THEN unit is not executed, and
the value of E is assigned to C.
Either the THEN unit or the ELSE unit can contain a statement that transfers
control, either conditionally or unconditionally. If the THEN unit ends with a GO
TO statement there is no need to specify an ELSE unit, for example:
if all(Array1 = Array2) then
go to LABEL_1;
next-statement
If the expression is true, the GO TO statement of the THEN unit transfers control
to LABEL_1. If the expression is not true, the THEN unit is not executed and control
passes to the next statement.
Short-circuit evaluation
The test of the IF expression is short-circuited under the following circumstances:
v If the IF expression consists of a logical OR of 2 expressions and the first of
these expressions is true, the second expression will not be evaluated and the
code will execute the THEN clause.
v If the IF expression consists of a logical AND of 2 expressions and the first of
these expressions is false, the second expression will not be evaluated and the
code will execute the ELSE clause.
However, the code short-circuits only the following expressions:
v A comparison expression
v A BIT(1) literal
v A NONVARYING BIT(1) variable
v An ENTRY reference that returns NONVARYING BIT(1)
222
Enterprise PL/I for z/OS Language Reference
IF
v A SUBSTR built-in function reference with 3 arguments the last of which is a
REAL FIXED literal equal to 1
v An ALL or ANY built-in function reference with an an argument that is either a
comparison operator applied to 2 arrays or simply a variable that is an array of
NONVARYING BIT(1)
v A reference to one of the following other built-in functions:
–
–
–
–
–
–
CHECKSTG
ENDFILE
FILEOPEN
ISFINITE
ISINF
ISMAIN
– ISNAN
– ISNORMAL
–
–
–
–
–
ISZERO
OMITTED
PRESENT
UNALLOCATED
VALID
– VALIDDATE
Naturally, an expression formed (possibly recursively) from the above and the
NOT prefix operator and the AND or OR infix operators will also be
short-circuited.
So, for example, given the following declares
dcl
dcl
dcl
dcl
dcl
dcl
A
B
C
D
P
BX
bit(1);
bit(1);
bit(2);
bit(2);
pointer;
based fixed bin(31);
Then the following IF statements would all be short-circuited:
if
if
if
if
A
P
C
A
|
=
=
|
B then
sysnull() | P->BX = 0 then
’’b & D = ’’b then
(substr(C,1,1) & substr(D,2,1)) then
But the following IF statements would not be short-circuited:
if C | D then
if C & D then
Chapter 8. Statements and directives
223
%INCLUDE
%INCLUDE directive
The %INCLUDE directive is used to incorporate external text into the source
program.
,
%INCLUDE member
ddname (member)
;
The included member can specify an absolute file name. Enclose the absolute file
name in single or double quotes. For example, the following is valid:
INTEL
%include "\ibmpli\include\sqlcodes.inc"
AIX and z/OS UNIX
%include "/ibmpli/include/sqlcodes.inc"
ITERATE statement
The ITERATE statement transfers control to the END statement that delimits its
containing iterative do-group. The current iteration completes and the next
iteration, if needed, is started. The ITERATE statement can be specified inside a
non-iterative do-group as long as that do-group is contained by an iterative
do-group.
ITERATE
;
label-constant
label-constant
Must be the label of a containing do-group. If omitted, control transfers to the
END statement of the most recent iterative do-group containing the ITERATE
statement.
For an example, see “Type 4” on page 214.
LEAVE statement
When contained in or specifying a simple do-group, the LEAVE statement
terminates the group. When contained in or specifying an iterative do-group, the
LEAVE statement terminates all iterations of the group, including the current
iteration. The flow of control goes to the same point it would normally go to if the
do-group had terminated by reaching its END statement. This point is not
necessarily the statement following the END statement of the do-group (see
“Example” on page 225).
224
Enterprise PL/I for z/OS Language Reference
LEAVE
LEAVE
;
label-constant
label-constant
Must be a label of a containing do-group. The do-group that is left is the
do-group that has the specified label. If label-constant is omitted, the do-group
that is left is the group that contains the LEAVE statement.
The LEAVE statement and the referenced or implied DO statement must not be in
different blocks.
In addition to the following examples, see the example in “Type 4” on page 214.
Example
In the following example, the statement leave A; transfers control to C.
If Time_to_process_X then
A:
do I = lbound(X,1) to hbound(X,1);
do J = lbound(X,2) to hbound(X,2);
If X(I,J)=0 then
leave A;
/* control goes to C, not B */
else
do;
.
.
.
end;
end;
end;
Else
B:
do;
.
.
.
end;
C:
statement after group A;
%LINE directive
The %LINE directive specifies that the next line should be treated in messages and
in information generated for debugging as if it came from the specified line and
file.
%LINE ( line-number , file-specification ) ;
Chapter 8. Statements and directives
225
%LINE
The characters '%LINE' must be in columns 1 through 5 of the input line for the
directive to be recognized (and conversely, any line starting with these five
characters is treated as a %LINE directive). The line-number must be an integral
value of seven digits or less and the file-specification must not be enclosed in
quotes. Any characters specified after the semicolon are ignored.
The %LINE directive is invalid unless the LINEDIR compiler option is in effect.
LOCATE statement
The LOCATE statement is described in Chapter 11, “Record-oriented data
transmission,” on page 289.
%NOPRINT directive
The %NOPRINT directive causes printing of the source listings to be suspended
until a %PRINT directive is encountered or until a %POP directive is encountered
that restores the previous %PRINT directive.
%NOPRINT ;
For an example of the %NOPRINT directive, refer to “%PUSH directive” on page
229.
%NOTE directive
The %NOTE directive generates a diagnostic message of specified text and severity.
%NOTE (
message
)
;
,code
message
A character expression whose value is the required diagnostic message.
code
A fixed expression whose value indicates the severity of the message, as
follows:
Code
0
4
8
12
16
Severity
I
W
E
S
U
If code is omitted, the default is 0.
If code has a value other than those listed above, a diagnostic message is
produced; the resulting system action is undefined.
226
Enterprise PL/I for z/OS Language Reference
%NOPRINT
Generated messages are filed together with other messages. Whether or not a
particular message is subsequently printed depends upon its severity level and the
setting of the compiler FLAG option (as described in the Programming Guide).
Generated messages of severity U cause immediate termination of preprocessing
and compilation. Generated messages of severity S, E, or W might cause
termination of compilation, depending upon the setting of various compiler
options.
null statement
The null statement causes no operation to be performed and does not modify
sequential statement execution. It is often used to denote null action for THEN and
ELSE clauses and for WHEN and OTHERWISE statements.
;
ON statement
The ON statement is described in Chapter 15, “Condition handling,” on page 349.
OPEN statement
The OPEN statement is described in Chapter 10, “Input and output,” on page 275.
OTHERWISE statement
The OTHERWISE statement is described in “SELECT statement” on page 230.
PACKAGE statement
The PACKAGE statement is described in Chapter 5, “Program organization,” on
page 87.
%PAGE directive
The %PAGE directive allows you to start a new page in the compiler source
listings.
%PAGE ;
%POP directive
The %POP directive allows you to restore the status of the %PRINT and
%NOPRINT directives saved by the most recent %PUSH directive.
Chapter 8. Statements and directives
227
%PAGE
The most common use of the %PUSH and %POP directives is in included files and
macros.
%POP ;
For an example, see “%PUSH directive” on page 229.
%PRINT directive
The %PRINT directive causes printing of the source listings to be resumed.
%PRINT ;
%PRINT is in effect, provided that the relevant compiler options are specified. For
an example of the %PRINT directive, refer to “%PUSH directive” on page 229.
PROCEDURE statement
The PROCEDURE statement is described in Chapter 5, “Program organization,” on
page 87.
%PROCESS directive
The %PROCESS directive is used to override compiler options.
%PROCESS ;
compiler-option
The % or * must be the first data byte of a source record. Any number of
%PROCESS and *PROCESS directives can be specified, but they must all appear
before the first language element appears. Refer to the Programming Guide for
more information.
*PROCESS directive
The *PROCESS directive is a synonym for the %PROCESS directive. For
information on the %PROCESS directive, refer to “%PROCESS directive.”
228
Enterprise PL/I for z/OS Language Reference
%PROCESS
%PUSH directive
The %PUSH directive allows you to save the current status of the %PRINT and
%NOPRINT directives in a “push down” stack on a last-in, first-out basis. You can
restore this saved status later, also on a last-in, first-out basis, by using the %POP
directive.
A common use of %PUSH and %POP directives is in included files and macros.
%PUSH ;
In the following example, statements 1, 2, 3, S3, S4, and 4 are printed in the
listings. All others are not printed.
Source Program
statement 1;
statement 2;
%include First; /* statement 3 */
First
%push;
/* F1 */
%noprint;
/* F2 */
dcl A entry (ptr, fixed bin); /* F3 */
statement F4;
%include Second; /* stmt F5 */
Second
%push;
/* S1 */
%print;
/* S2 */
dcl B entry (ptr,fixed bin)
options(byvalue);
/* S3 */
statement S4;
%pop;
statement F6;
%pop;
statement 4;
The original setting is restored following the %POP directive in Second.
PUT statement
The PUT statement is described in Chapter 12, “Stream-oriented data
transmission,” on page 299.
READ statement
The READ statement is described in Chapter 11, “Record-oriented data
transmission,” on page 289.
Chapter 8. Statements and directives
229
PUT
RELEASE statement
The RELEASE statement is described in “FETCH statement” on page 103.
RESIGNAL statement
The RESIGNAL statement is described in Chapter 15, “Condition handling,” on
page 349.
RETURN statement
The RETURN statement is described in “RETURN statement” on page 128.
REVERT statement
The REVERT statement is described in Chapter 15, “Condition handling,” on page
349
REWRITE statement
The REWRITE statement is described in Chapter 11, “Record-oriented data
transmission,” on page 289.
SELECT statement
A select-group provides a multiple path conditional branch. A select-group
contains a SELECT statement, optionally one or more WHEN statements,
optionally an OTHERWISE statement, and an END statement.
Note: Condition prefixes are invalid on OTHERWISE statements.
; SELECT
(exp1)
,
WHEN( exp2
)unit;
OTHERWISE unit
;
Abbreviation: OTHER for OTHERWISE
SELECT (exp1)
The SELECT statement and its corresponding END statement, delimit a group
of statements collectively called a select-group. The expression in the SELECT
statement is evaluated and its value is saved.
WHEN (exp2, exp2, ...) unit
Specifies one or more expressions that are evaluated and compared with the
saved value from the SELECT statement.
230
Enterprise PL/I for z/OS Language Reference
SELECT
If an expression is found that is equal to the saved value, the evaluation of
expressions in WHEN statements is terminated, and the unit of the associated
WHEN statement is executed. If no such expression is found, the unit of the
OTHERWISE statement is executed.
The WHEN statement must not have a label.
OTHERWISE unit
Specifies the unit to be executed when every test of the preceding WHEN
statements fails.
If the OTHERWISE statement is omitted and execution of the select-group does
not result in the selection of a unit, the ERROR condition is raised.
The OTHERWISE statement must not have a label or condition prefix.
unit
Each unit is either a valid single statement, a group, or a begin-block.
DECLARE, DEFAULT, END, ENTRY FORMAT, PROCEDURE, and %statement
statements are not valid. Each unit can contain statements that specify a
transfer of control (for example, GO TO). Hence, the normal sequence of the
SELECT statement can be overridden.
If exp1 is omitted, each exp2 is evaluated and converted, if necessary, to a bit string.
If any bit in the resulting string is '1'B, the unit of the associated WHEN statement
is executed. If all bits are 0 or the string is null, the unit of the OTHERWISE
statement is executed.
After execution of a unit of a WHEN or OTHERWISE statement, control passes to
the statement following the select-group, unless the normal flow of control is
altered within the unit.
If exp1 is specified, each exp2 must be such that the following comparison
expression has a scalar bit value:
(exp1) = (exp2)
Both exp1 and exp2 must be scalar expressions. Hence, while arrays, structures, and
unions may be used in either exp1 or exp2, the evaluated expression must be a
scalar value.
Examples
In the following example, E, E1, and so on, are expressions. When control reaches
the SELECT statement, the expression E is evaluated and its value is saved. The
expressions in the WHEN statements are then evaluated in turn (in the order in
which they appear), and each value is compared with the value of E.
If a value is found that is equal to the value of E, the action following the
corresponding THEN statement is performed; no further WHEN statement
expressions are evaluated.
If none of the expressions in the WHEN statements are equal to the expression in
the SELECT statement, the action specified after the OTHERWISE statement is
executed.
Chapter 8. Statements and directives
231
SELECT
select (E);
when (E1,E2,E3) action-1;
when (E4,E5) action-2;
otherwise action-n;
end;
Nl: next statement;
An example of exp1 being omitted is:
select;
when (A>B) call Bigger;
when (A=B) call Same;
otherwise call Smaller;
end;
If a select-group contains no WHEN statements, the action in the OTHERWISE
statement is executed unconditionally. If the OTHERWISE statement is omitted,
and execution of the select-group does not result in the selection of a WHEN
statement, the ERROR condition is raised.
SIGNAL statement
The SIGNAL statement is described in Chapter 15, “Condition handling,” on page
349.
%SKIP directive
The %SKIP directive causes the specified number of lines to be left blank in the
compiler source listings.
%SKIP
;
(n)
n
Specifies the number of lines to be skipped. It must be an integer in the range
1 through 999. If n is omitted, the default is 1. If n is greater than the number
of lines remaining on the page, the equivalent of a %PAGE directive is
executed in place of the %SKIP directive.
STOP statement
The STOP statement stops the current application.
STOP ;
WAIT statement
The WAIT statement is described in Chapter 17, “Multithreading facility,” on page
377.
232
Enterprise PL/I for z/OS Language Reference
WHEN
WHEN statement
The WHEN statement is described in “SELECT statement” on page 230.
WRITE statement
The WRITE statement is described in Chapter 11, “Record-oriented data
transmission,” on page 289.
%XINCLUDE statement
The %XINCLUDE directive is used to incorporate external text into the source
program if it has not previously been included.
,
%XINCLUDE member
ddname( member )
;
Chapter 8. Statements and directives
233
WHEN
234
Enterprise PL/I for z/OS Language Reference
Chapter 9. Storage control
Storage classes, allocation, and deallocation . .
Static storage and attribute . . . . . . . .
Automatic storage and attribute . . . . . .
Controlled storage and attribute . . . . . .
ALLOCATE statement for controlled variables
FREE statement for controlled variables . .
Implicit freeing . . . . . . . . . .
Multiple generations of controlled variables .
Asterisk notation . . . . . . . . . .
Adjustable extents . . . . . . . . . .
Built-in functions for controlled variables . .
Based storage and attribute. . . . . . . .
Extent specifications in BASED declarations .
BASED VARYING string . . . . . . .
Storage allocation for BASED variable . . .
Locator variables . . . . . . . . . .
DEFINED and UNION attributes . . . . .
INITIAL attribute . . . . . . . . . .
Locator data . . . . . . . . . . . .
Locator conversion . . . . . . . .
Locator reference . . . . . . . . .
Locator qualification . . . . . . . .
Levels of locator qualification . . . . .
POINTER variable and attribute . . . . .
Built-in functions for based variables . . .
ALLOCATE statement for based variables . .
FREE statement for based variables . . . .
Implicit freeing . . . . . . . . . .
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
235
237
237
238
239
241
242
242
242
242
243
243
243
244
245
245
245
246
246
246
247
247
248
248
249
249
250
251
REFER option (self-defining data) . . . .
Area data and attribute . . . . . . . . .
Offset data and attribute . . . . . . .
Setting offset variables . . . . . . .
Examples of offset variables . . . . .
Built-in functions for area variables . . . .
Area assignment . . . . . . . . . .
Input/output of areas . . . . . . . .
List processing . . . . . . . . . . . .
ASSIGNABLE and NONASSIGNABLE attributes
NORMAL and ABNORMAL attributes . . . .
BIGENDIAN and LITTLEENDIAN attributes. .
HEXADEC and IEEE attributes . . . . . .
CONNECTED and NONCONNECTED attributes
DEFINED and POSITION attributes . . . . .
Unconnected Storage . . . . . . . . .
Simple Defining . . . . . . . . . .
iSUB Defining . . . . . . . . . . .
String Overlay Defining . . . . . . . .
POSITION attribute . . . . . . . . .
INITIAL attribute . . . . . . . . . . .
Initializing array variables . . . . . . .
Initializing unions . . . . . . . . . .
Initializing static variables . . . . . . .
Initializing automatic variables . . . . .
Initializing based and controlled variables . .
Examples . . . . . . . . . . . . .
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
251
253
254
254
255
255
255
256
256
258
259
259
260
261
262
264
264
265
266
267
268
271
272
272
273
273
273
All variables require storage. The attributes specified for a variable describe the
amount of storage required and how it is interpreted. In the following example a
reference to X is a reference to a piece of storage that contains a value to be
interpreted as fixed-point binary.
dcl X fixed binary(31,0) automatic;
Since X is automatic, the storage for it is allocated when its declaring block is
activated, and the storage remains allocated until the block is deactivated.
Storage classes, allocation, and deallocation
Storage allocation is the process of associating an area of storage with a variable so
that the data item(s) represented by the variable can be recorded internally. When
storage is associated with a variable, the variable is allocated.
Allocation for a given variable can take place statically, (before the execution of the
program) or dynamically (during execution). A variable that is allocated statically
remains allocated for the duration of the application program. A variable that is
allocated dynamically relinquishes its storage either upon the termination of the
block containing that variable, or at an explicit request from the application.
The storage class assigned to a variable determines the degree of storage control
applied to it and the manner in which the variable's storage is allocated and freed.
© Copyright IBM Corp. 1999, 2012
235
Storage classes, allocation, and deallocation
There are four storage classes: automatic, static, controlled, and based. You assign
the storage class using its corresponding attribute in an explicit, implicit, or
contextual declaration:
v AUTOMATIC specifies that storage is allocated upon each entry to the block
that contains the storage declaration. The storage is released when the block is
exited. If the block is a procedure that is invoked recursively, the previously
allocated storage is pushed down upon entry; the latest allocation of storage is
popped up in a recursive procedure when each generation terminates. (For a
discussion of push-down and pop-up stacking, see “Recursive procedures” on
page 101.)
v STATIC specifies that storage is allocated when the program is loaded. The
storage is not freed until program execution is completed. The storage for a
fetched procedure is not freed until the procedure is released.
v CONTROLLED specifies that you use the ALLOCATE and FREE statements to
control the allocation and freeing of storage. Multiple allocations of the same
controlled variable in the same program, without intervening freeing, stacks
generations of the variable. You can access earlier generations only by freeing
the later ones.
v BASED, like CONTROLLED, specifies that you control storage allocation and
freeing. One difference is that multiple allocations are not stacked but are
available at any time. Each allocation can be identified by the value of a pointer
variable. Another difference is that based variables can be associated with an
area of storage and identified by the value of an offset variable.
Based variables outside of areas can be allocated and freed using the
ALLOCATE built-in function and PLIFREE built-in subroutine respectively. They
can also be allocated using the AUTOMATIC built-in function; such allocated
variables are freed automatically when the block in which they are allocated
terminates.
Storage class attributes can be declared explicitly for element, array, and major
structure and union variables. For array and major structure and union variables,
the storage class declared for the variable applies to all of the elements in the array
or structure or union.
Storage class attributes cannot be specified for:
v CONDITION conditions
v Defined data items
v Entry constants
v File constants
v Format constants
v Identifiers defined in the DEFINE statement
v Label constants
v Members of structures and unions
v Named constants
Allocation of storage for variables is managed by PL/I. You do not specify where
in storage the allocation is to be made. You can, however, specify that a variable be
allocated in an existing AREA. For more information, refer to “Area data and
attribute” on page 253.
236
Enterprise PL/I for z/OS Language Reference
Static storage and attribute
Static storage and attribute
Variables declared with the STATIC attribute are allocated prior to running a
program. They remain allocated until the program terminates. The program has no
control over the allocation of static variables during execution.
STATIC
STATIC is the default for external variables, but internal variables can also be
static. It is also the default for variables declared in a package, outside of any
procedure. Static variables follow the normal scope rules for the validity of
references to them. In the following example, the variable X is allocated for the life
of the program, but it can be referenced only within procedure B or any block
contained in B. The variable Y gets the STATIC attribute and is also allocated for
the life of the program.
Package: Package exports (*);
dcl Y char(10);
A: proc options(main);
B: proc;
declare X static internal;
end B;
end A;
C: proc;
Y = ’hello’;
end C;
end Package;
If static variables are initialized using the INITIAL attribute, the initial values must
be restricted expressions. Extent specifications must also be restricted expressions.
Automatic storage and attribute
Automatic variables are allocated on entry to the block in which they are declared.
They can be reallocated many times during the execution of a program. You
control their allocation by your design of the block structure.
AUTOMATIC
Abbreviation: AUTO
AUTOMATIC is the default. Automatic variables are always internal.
In the following example, each time procedure B is invoked, the variables X and Y
are allocated storage. When B terminates, the storage is released, and the values X
and Y contain are lost.
Chapter 9. Storage control
237
Automatic storage and attribute
A: proc;
.
.
.
call B;
B: proc;
declare X,Y auto;
.
.
.
end B;
.
.
.
call B;
The storage that is freed is available for allocation to other variables. Thus,
whenever a block (procedure or begin) is active, storage is allocated for all
variables declared automatic within that block. Whenever a block is inactive, no
storage is allocated for the automatic variables in that block. Only one allocation of
a particular automatic variable can exist, except for those procedures that are called
recursively or by more than one program.
Extents for automatic variables can be specified as expressions. This means that
you can allocate a specific amount of storage when you need it. In the following
example, the character string STR has a length defined by the value of the variable
N when procedure B is invoked.
A: proc;
declare N fixed bin;
.
.
.
B: proc;
declare STR char(N);
If the declare statements are located in the same block, PL/I requires that the
variable N be initialized either to a restricted expression or to an initialized static
variable. In the following example, the length allocated is correct for Str1, but not
for Str2. PL/I does not resolve this type of declaration dependency.
dcl N fixed bin (15) init(10),
M fixed bin (15) init(N),
Str1 char(N),
Str2 char(M);
Controlled storage and attribute
Variables declared as CONTROLLED are allocated only when you specify them in
an ALLOCATE statement. A controlled variable remains allocated until a FREE
statement that names the variable is encountered or until the end of the program.
Controlled variables are partially independent of the program block structure, but
not completely. The scope of a controlled variable can be internal or external.
When it is declared as internal, the scope of the variable is the block in which the
variable is declared and any contained blocks. Any reference to a controlled
variable that is not allocated is in error.
238
Enterprise PL/I for z/OS Language Reference
Controlled storage and attribute
You cannot pass variables that are not declared as CONTROLLED to a procedure
that declares them as CONTROLLED. However, you can pass a variable that is
declared as CONTROLLED to a procedure that does not declare it as
CONTROLLED.
CONTROLLED
Abbreviation: CTL
In the following example, the variable X can be validly referred to within
procedure B and that part of procedure A that follows execution of the CALL
statement.
A: proc;
dcl X controlled;
call B;
.
.
.
B: proc;
allocate X;
.
.
end B;
end A;
Generally, controlled variables are useful when a program requires large data
aggregates with adjustable extents. Statements in the following example allocate
the exact storage required depending on the input data and free the storage when
it is no longer required.
dcl A(M,N) ctl;
get list(M,N);
allocate A;
get list(A);
.
.
.
free A;
This method is more efficient than the alternative of setting up a begin-block,
because block activation and termination are not required.
ALLOCATE statement for controlled variables
The ALLOCATE statement allocates storage for controlled variables, independent
of procedure block boundaries. Controlled parameters can also be allocated. The
bounds of controlled arrays, the lengths of controlled strings, and the size of
controlled areas, as well as their initial values, can be specified in the ALLOCATE
statement.
Chapter 9. Storage control
239
ALLOCATE for controlled variables
,
ALLOCATE controlled-variable
attribute
;
level
attribute:
dimension
CHARACTER(length)
BIT(length)
GRAPHIC(length)
WIDECHAR(length)
AREA(size)
,
INITIAL( item )
INITIAL CALL entry-reference
,
( argument
)
Abbreviation: ALLOC
level
Indicates a level number. If no level number is specified, the
controlled-variable named must be a level-1 variable.
controlled-variable
Specifies a controlled variable or an element of a controlled major structure. A
structure element, other than the major structure, can appear only if the
relative structuring of the entire major structure containing the element appears
as it is in the DECLARE statement for that structure. In this case, dimension
attributes must be specified for all names that are declared with the dimension
attribute.
Both controlled and based variables can be allocated in the same statement. For the
syntax of based variables, refer to “ALLOCATE statement for based variables” on
page 249.
Bounds for arrays, lengths of strings, and sizes of areas (extents) are evaluated at
the execution of an ALLOCATE statement:
v Either the ALLOCATE statement or a DECLARE or DEFAULT statement must
specify any necessary dimension, size, or length attributes (extents) for a
variable. Any expression taken from a DECLARE statement is evaluated at the
point of allocation using the conditions enabled at the ALLOCATE statement.
However, names in the expression refer to those variables whose scope includes
the DECLARE or DEFAULT statement.
v If a bound, length, or size is explicitly specified in an ALLOCATE statement, it
overrides that given in the DECLARE statement for that variable.
v If a bound, length, or size is specified by an asterisk in an ALLOCATE
statement, that extent is taken from the current generation. If no generation of
the variable exists, the extent is undefined and the program is in error.
240
Enterprise PL/I for z/OS Language Reference
ALLOCATE for controlled variables
v If, in either an ALLOCATE or a DECLARE statement, bounds, lengths, or sizes
are specified by expressions that contain references to the variable being
allocated, the expressions are evaluated using the value of the most recent
generation of the variable. For example:
declare X(N) fixed bin ctl;
N = 20;
allocate X;
allocate X(X(1));
In the first allocation of X, the upper bound is specified by the declare statement
and N = 20;. In the second allocation, the upper bound is specified by the value
of the first element of the first generation of X.
The dimension attribute must specify the same number of dimensions as declared.
The dimension attribute can appear with any of the other attributes and must be
the first attribute specified. For example:
declare X(M) char(N) controlled;
M = 20;
N = 5;
allocate X(25) char(6);
The BIT, CHARACTER, GRAPHIC, WIDECHAR and AREA attributes can appear
only for variables having the same attributes, respectively.
Initial values are assigned to a variable upon allocation, if the variable has an
INITIAL attribute in either the DECLARE or ALLOCATE statement. Expressions or
the CALL option in the INITIAL attribute are evaluated at the point of allocation,
using the conditions enabled at the ALLOCATE statement. However, the names are
interpreted in the environment of the declaration. If an INITIAL attribute appears
in both DECLARE and ALLOCATE statements, the INITIAL attribute in the
ALLOCATE statement is used. If initialization involves reference to the variable
being allocated, the reference is to the new generation of the variable. For more
information on initialization, refer to “INITIAL attribute” on page 268.
Any evaluations performed at the time the ALLOCATE statement is executed (for
example, evaluation of expressions in an INITIAL attribute) must not be
interdependent.
If storage for the controlled variable is not available, the STORAGE condition is
raised.
FREE statement for controlled variables
The FREE statement frees the storage allocated for controlled variables. The freed
storage is then available for other allocations. The previously allocated controlled
variable is made available, and subsequent references refer to that allocation.
,
FREE controlled-variable
;
controlled-variable
A level-1, unsubscripted variable.
Chapter 9. Storage control
241
FREE for controlled variables
Both based and controlled variables can be freed in the same statement. For the
syntax of based variables, refer to “FREE statement for based variables” on page
250.
Implicit freeing
A controlled variable need not be explicitly freed by a FREE statement. However, it
is a good practice to explicitly FREE controlled variables.
All controlled storage is freed at the termination of the program.
Multiple generations of controlled variables
An ALLOCATE statement for a variable for which storage was previously allocated
and not freed pushes down or stacks storage for the variable. This stacking creates
a new generation of data for the variable. The new generation becomes the current
generation. The previous generation cannot be directly accessed until the current
generation has been freed. When storage for this variable is freed, using the FREE
statement or at termination of the program in which the storage was allocated,
storage is popped up or removed from the stack.
Asterisk notation
In an ALLOCATE statement, values are inherited from the most recent previous
generation when dimensions, lengths, or sizes are indicated by asterisks. For
arrays, the asterisk must be used for every dimension of the array, not just one of
them. For example:
dcl X(M,N) char(A) ctl;
M=10;
N=20;
A=5;
allocate X;
allocate X(10,10);
allocate X(*,*);
The first generation of X has bounds (10,20); the second and third generations have
bounds (10,10). The elements of each generation of X are all character strings of
length 5.
The asterisk notation can also be used in a DECLARE statement, but has a
different meaning there. For example:
dcl Y char(*) ctl,
N fixed bin;
N=20;
allocate Y char(N);
allocate Y;
The length of the character string Y is taken from the previous generation unless it
is specified in an ALLOCATE statement. In that case, Y is given the specified
length. This allows you to defer the specification of the string length until the
actual allocation of storage.
Adjustable extents
Controlled scalars, arrays, and members of structures and unions can have
adjustable array extents, string lengths, and area sizes. In the following example,
when the structure is allocated, A.B has the extent 1 to 10 and A.C is a varying
character string with maximum length 5.
242
Enterprise PL/I for z/OS Language Reference
Adjustable extents
dcl 1 A ctl,
2 B(N:M),
2 C char(*) varying;
N = -10;
M = 10;
alloc 1 A,
2 B(1:10),
2 C char(5);
free A;
Built-in functions for controlled variables
The ALLOCATION built-in function can be used to determine the number of
generations that have been allocated for a given controlled variable. If the variable
is not allocated, the function returns the value zero.
Based storage and attribute
A declaration of a based variable is a description of the generation: the amount of
storage required and its attributes. (A based variable does not identify the location
of a generation in main storage.) A locator value identifies the location of the
generation. Any reference to a based variable that is not allocated is in error.
BASED
(locator-reference)
locator-reference
Identifies the location of the data.
When reference is made to a based variable, the data and alignment attributes used
are those of the based variable, while the qualifying locator variable identifies the
location of data.
A based variable cannot have the EXTERNAL attribute, but a locator reference for
a based variable can have any storage class, including based.
Extent specifications in BASED declarations
The extents for one BASED variable can depend on the attributes of a second
variable but only if the second variable is declared first. For example, A can be
declared as BASED CHAR(LENGTH(B)) if B is declared before A.
A based structure or union can be declared to contain non-constant extents by
using the REFER option. See “REFER option (self-defining data)” on page 251.
If you do not specify the REFER option, the extent specifications in the BASED
declarations must be restricted expressions with the following exceptions:
v A non-constant array extent in a BASED variable is invalid unless the array
meets all of the following conditions:
– It is one dimensional.
– The lower bound of the array is a constant.
Chapter 9. Storage control
243
Based storage and attribute
– When it is a part of a structure, the extents of all other fields in the structure
are constant, and no fields follow the array and the parent structures, if any,
of the array.
v A non-constant CHAR extent in a BASED variable is invalid unless the string is
a scalar or it meets all of the following conditions:
– It is the last element in a structure.
– It has no parents that are arrays.
– It has one of these attributes: UNALIGNED, NONVARYING, or VARZ.
v Any of the following non-constant extents in a BASED variable are valid only if
the variable is a scalar:
–
–
–
–
The
The
The
The
non-constant AREA extent
non-constant BIT extent
non-constant GRAPHIC extent
non-constant WIDECHAR extent
All of the following declarations are valid:
Example 1:
dcl
1 a1(n) based,
2 b,
3 b1
fixed bin(31),
3 b2
fixed bin(31);
Example 2:
dcl
1 a2 based,
2 b(n),
3 b1
fixed bin(31),
3 b2
fixed bin(31);
Example 3:
dcl
1 a3 based,
2 b,
3 b1
fixed bin(31),
3 b2(n) fixed bin(31);
Example 4:
dcl
1 a4 based,
2 b,
3 b1
fixed bin(31),
3 b2
char(n);
Example 5:
dcl
1 a5 based,
2 b,
3 b1
fixed bin(31),
3 b2(n) char(m);
BASED VARYING string
The maximum length of a based VARYING or VARYINGZ string must be equal to
the maximum length of any string upon which the based VARYING or VARYINGZ
string is overlaid. For example:
244
Enterprise PL/I for z/OS Language Reference
Based storage and attribute
declare A char(50) varying based(Q),
B char(50) varying;
Q=addr(B);
A based VARYING string can only be overlaid on a VARYING string; a based
VARYINGZ string can only be overlaid on a VARYINGZ string.
Storage allocation for BASED variable
Storage for a based variable can be allocated by using the ALLOCATE statement,
the ALLOCATE built-in function, the AUTOMATIC built-in function, or the
LOCATE statement.
A based variable can also be used to access existing data by using the READ
statement (with SET option), or the FETCH statement (with SET option), or the
ADDR built-in function.
Based AREA variables can be allocated using the ALLOCATE statement; PL/I
automatically initializes the area to EMPTY upon allocation. However, if you
obtain storage for the area variable using the ALLOCATE or the AUTOMATIC
built-in function, you must assign EMPTY to the variable after obtaining the
storage.
Locator variables
Because a locator variable identifies the location of any generation, you can refer at
any point in a program to any generation of a based variable by using an
appropriate locator value. The following example declares that references to X,
except when the reference is explicitly qualified, use the locator variable P to locate
the storage for X.
dcl X fixed bin based(P);
The association of a locator reference in this way is not permanent. The locator
reference can be used to identify locations of other based variables and other
locator references can be used to identify other generations of the variable X. When
a based variable is declared without a locator reference, any reference to the based
variable must always be explicitly locator-qualified.
In the following example, the arrays A and C refer to the same storage. The
elements B and C(2,1) also refer to the same storage.
dcl A(3,2) character(5) based(P),
B char(5) based(Q),
C(3,2) character(5);
P = addr(C);
Q = addr(A(2,1));
Note: When a based variable is overlaid in this way, no new storage is allocated.
The based variable uses the same storage as the variable on which it is
overlaid (C(3,2) in the example).
DEFINED and UNION attributes
You can also use the DEFINED and UNION attributes to overlay variable storage,
but DEFINED and UNION overlay the storage permanently. When based variables
are overlaid with a locator reference, the association can be changed at any time in
the program by assigning a new value to the locator variable.
Chapter 9. Storage control
245
Based storage and attribute
For more information on the DEFINED and UNION attributes, see “DEFINED and
POSITION attributes” on page 262, and “Unions” on page 178.
INITIAL attribute
The INITIAL attribute can be specified for a based variable. The initial values are
assigned only upon explicit allocation of the based variable with an ALLOCATE or
LOCATE statement.
Locator data
There are two types of locator data: pointer and offset.
The value of a pointer variable is an address of a location in storage. It can be used
to qualify a reference to a variable with allocated storage in several different
locations.
The value of an offset variable specifies a location within an area variable and
remains valid when the area is assigned to a different part of storage.
A locator value can be assigned only to a locator variable. When an offset value is
assigned to an offset variable, the area variables named in the OFFSET attributes
are ignored.
Locator conversion
Locator data cannot be converted to other data types, except as follows:
v To and from REAL FIXED BINARY (p,0) by using the BINARYVALUE,
POINTERVALUE, and OFFSETVALUE built-in functions
v Between pointer and offset implicitly or explicitly using the POINTER and
OFFSET built-in functions.
When an offset variable is used in a reference, it is implicitly converted to a
pointer value by using the address of the area variable designated in the OFFSET
attribute and the offset variable. Explicit conversion of an offset to a pointer value
is accomplished using the POINTER built-in function. For example, the following
statement assigns a pointer value to P, giving the location of a based variable,
identified by offset O in area B.
dcl P pointer, O offset(A),B area;
P = pointer(O,B);
Because the area variable is different from that associated with the offset variable,
you must ensure that the offset value is valid for the different area. It is valid, for
example, if area A is assigned to area B prior to the invocation of the function.
The OFFSET built-in function, in contrast to the POINTER built-in function, returns
an offset value derived from a given pointer and area. The given pointer value
must identify the location of a based variable in the given area.
A pointer value is converted to offset by using the pointer value and the address of
the area. This conversion is limited to pointer values that relate to addresses within
the area named in the OFFSET attribute.
Except when assigning the NULL or the SYSNULL built-in function value, it is an
error to attempt to convert from or to an offset variable that is not associated with
an area.
246
Enterprise PL/I for z/OS Language Reference
Locator Data
There is no implicit locator conversion in multiple assignments.
Locator reference
A locator reference is either a locator variable that can be qualified or subscripted,
or a function reference that returns a locator value.
A locator reference can be used in the following ways:
v As a locator qualifier, in association with a declaration of a based variable
v In a comparison operation, as in an IF statement
v As an argument in a procedure reference.
Because PL/I implicitly converts an offset to a pointer value, offset references can
be used interchangeably with pointer references.
Locator qualification
Locator qualification is the association of one or more locator references with a
based reference to identify a particular generation of a based variable. This is
called a locator-qualified reference. The composite symbol -> represents “qualified
by” or “points to”. The following syntax diagram is for an explicit qualified
reference.
locator-reference ->
based-locator-reference ->
based-variable
locator-reference
based-locator-reference
Identify the location of the data.
In the following example, X is a based variable, P is a locator variable, and Q is a
based locator variable.
P -> Q -> X
The reference means that it is that generation of X that is identified by the based
locator Q that is also identified by the value of the locator P. X and Q are said to be
explicitly locator-qualified.
When more than one locator qualifier is used, they are evaluated from left to right.
Reference to a based variable can also be implicitly qualified. The locator reference
used to determine the generation of a based variable that is implicitly qualified is
the one declared with the based variable. In the following example, the
ALLOCATE statement sets the pointer variable P so that the reference X applies to
allocated storage.
dcl X fixed bin based(P) init(0);
allocate X;
X = X + 1;
Chapter 9. Storage control
247
Locator Data
The references to X in the assignment statement are implicitly locator-qualified by
P. References to X can also be explicitly locator-qualified as shown in the following
example.
P->X = P->X + 1;
The following assignment statements have the same effect as the previous example:
Q = P;
Q->X = Q->X + 1;
Because the locator declared with a based variable can also be based, a chain of
locator qualifiers can be implied. For example, the following pointer and based
variables can be used:
declare (P(10),Q) pointer,
R pointer based (Q),
V based (P(3)),
W based (R),
Y based;
allocate R,V,W;
Given the previous declaration and allocation, the following references are valid:
P(3) -> V
V
Q -> R -> W
R -> W
W
The first two references are equivalent, and the last three are equivalent. Any
reference to Y must include a qualifying locator variable.
Levels of locator qualification
A pointer that qualifies a based variable represents one level of locator
qualification. An offset represents two levels because it is implicitly qualified
within an area. The number of levels is not affected by a locator being subscripted
and/or an element of a structure or union. In the following example, the references
X, P -> X, and Q -> P -> X represent three levels of locator qualification.
declare X based (P),
P pointer based (Q),
Q offset (A);
POINTER variable and attribute
A pointer variable is declared contextually if it appears in the declaration of a
based variable, as a locator qualifier, in a BASED attribute, or in the SET option of
an ALLOCATE, LOCATE, READ, or FETCH statement. It can also be declared
explicitly.
POINTER
Abbreviation: PTR
The value of a pointer variable that no longer identifies a generation of a based
variable is undefined (for example, when a based variable has been freed). Before a
reference is made to a pointer-qualified variable, the pointer must have a value.
248
Enterprise PL/I for z/OS Language Reference
Built-in functions for based variables
Built-in functions for based variables
The ALLOCATE built-in function can be used to obtain storage for a based
variable, and the PLIFREE built-in subroutine can be used to free such storage. The
AUTOMATIC built-in function can also be used to obtain storage for a based
variable, but such storage must not be explicitly freed. Storage allocated with the
AUTOMATIC built-in function is automatically freed when the block in which it is
allocated terminates.
The ADDR built-in function returns a pointer value that identifies the first byte of
a variable. The ENTRYADDR built-in function returns a pointer value that is the
address of the first executed instruction if the entry were to be invoked. The NULL
and SYSNULL built-in functions return the PL/I null pointer and the system null
pointer respectively.
Note: The NULL and SYSNULL built-in functions can, but do not necessarily,
compare equally. Your application program must not depend on the
functions' equality.
ALLOCATE statement for based variables
The ALLOCATE statement allocates storage for based variables and sets a locator
variable that can be used to identify the location, independent of procedure block
boundaries.
,
ALLOCATE based-variable
location-reference
;
location-reference:
IN(area-variable)
SET(locator-variable)
Abbreviation: ALLOC
based variable
Is a level-1 unsubscripted variable.
IN
Specifies the area variable in which the storage is allocated. For more
information on areas, refer to “Area data and attribute” on page 253.
SET
Specifies a locator variable that is set to the location of the storage allocated. If
the SET option is not specified, the locator used is the one specified in the
declaration of the based variable. For syntax information about declaring based
variables, refer to “Based storage and attribute” on page 243 and “Locator
data” on page 246.
Both based and controlled variables can be allocated in the same statement. For the
syntax of controlled variables, see “ALLOCATE statement for controlled variables”
on page 239.
Chapter 9. Storage control
249
ALLOCATE for based variables
Storage is allocated in an area when the IN option is specified or the SET option
specifies an offset variable. These options can appear in any order. For allocations
in areas:
v If sufficient storage for the based variable does not exist within the area, the
AREA condition is raised.
v If the IN option is not used when using an offset variable, the declaration of the
offset variable must specify an area reference.
When an area is not used, the locator variable must be a pointer variable. If
storage for the based variable is not available, the STORAGE condition is raised.
Note that if a based variable uses REFER, it size will be calculated at run-time. If
this calculation yields a value that is too large to fit in a FIXED BIN(31) variable,
then your program is in error and should be corrected. In this situation, the
STORAGE condition will not be raised; instead the ERROR condition with
ONCODE=3809 will be raised if:
v the SIZE condition is enabled, or
v the BASED structure is mapped via a library call
If neither of these conditions apply, unpredictable results will occur.
The amount of storage allocated for a based variable depends on its attributes, and
on its dimensions, length, or size specifications if these are applicable at the time of
allocation. These attributes are determined from the declaration of the based
variable.
A based structure or union can contain adjustable array bounds or string lengths
or area sizes (see “REFER option (self-defining data)” on page 251). The asterisk
notation for extents is not allowed for based variables.
FREE statement for based variables
The FREE statement frees the storage allocated for based and controlled variables.
,
FREE option
;
option:
based-variable
locator-reference ->
IN(area-variable)
locator-reference ->
Frees a particular generation of a based variable. The composite symbol ->
means “qualified by” or “points to.” If the based variable is not explicitly
locator-qualified, the locator variable declared in the BASED attribute is used
to identify the generation of data to be freed. If no locator has been declared,
the statement is in error.
based variable
Must be a level-1 unsubscripted based variable.
250
Enterprise PL/I for z/OS Language Reference
FREE for based variables
IN Must be specified or the based variable must be qualified by an offset declared
with an associated area, if the storage to be freed was allocated in an area. The
IN option cannot appear if the based variable was not allocated in an area.
Area assignment allocates based storage in the target area. These allocations
can be freed by the IN option naming the target area.
Both based and controlled variables can be freed in the same statement. For the
syntax of controlled variables, see “FREE statement for controlled variables” on
page 241.
A based variable can be used to free storage only if that storage has been allocated
for a based variable having identical data attributes.
The amount of storage freed depends upon the attributes of the based variable,
including bounds and/or lengths at the time the storage is freed. The user is
responsible for determining that this amount coincides with the amount allocated.
If the variable has not been allocated, the results are unpredictable.
Implicit freeing
A based variable need not be explicitly freed by a FREE statement, but it is a good
practice to do so.
All based storage is freed at the termination of the program.
REFER option (self-defining data)
A self-defining structure or union contains information about its own fields, such
as the length of a string. A based structure or union can be declared to manipulate
this data. String lengths, array bounds, and area sizes can all be defined by
variables, known as the refer object, declared within the structure or union. When
the structure or union is allocated (by either an ALLOCATE statement or a
LOCATE statement), the value of an expression is assigned to the refer object
variable. For any other reference to the structure or union, the value of the refer
object is used.
The REFER option is used in the declaration of a based structure or union to
specify that, on allocation of the structure or union, the value of an expression is
assigned to the refer object and represents the length, bound, or size of another
variable in the structure or union. The syntax for a length, bound, or size with a
REFER option is shown in the following diagram.
expression REFER (member-variable)
expression
The value of this expression defines the length, bound, or size of the member
when the structure or union is allocated (using ALLOCATE or LOCATE). The
expression is evaluated and converted to FIXED BINARY (31,0). Any variables
used as operands in the expression must not belong to the structure or union
containing the REFER option.
Subsequent references to the structure or union obtain the REFER option
member's length, bound, or size from the current value of member-variable (refer
object).
Chapter 9. Storage control
251
REFER
member-variable
The refer object must conform to the following rules:
v It must be a member of the same level-1 structure or union, and it must
appear before any member that names it in a REFER option.
v It must be computational.
v It cannot be locator-qualified (see “Locator qualification” on page 247) or
subscripted.
v It cannot be part of an array.
In the following example, the declaration specifies that the based structure STR
consists of an array Y and an element X.
declare 1 STR based(P),
2 X fixed binary(31,0),
2 Y (L refer (X)),
L fixed binary(31,0) init(1000);
When STR is allocated, the upper bound is set to the current value of L which is
assigned to X. For any other reference to Y, such as a READ statement that sets P,
the bound value is taken from X.
If the INITIAL attribute is specified for the member with the REFER option,
initialization of the member occurs after the refer object has been assigned its
value.
Any number of REFER options can be used in the declaration of a structure or
union.
The value of the refer object should not be changed during program execution. It is
an error to free such an aggregate if the value of the refer object has changed.
Note also that any variables used in the expression defining the REFER extent
should be declared in the block (or one of its parent blocks) containing the
DECLARE using that REFER. If one of the variables is not declared, it will be
implicitly declared following the usual rules for implicit declaration, i.e. a
DECLARE for it will be added to the outermost block containing the DECLARE.
This means that in the following code, the declaration of and assignment to the
variable m in the subroutine inner_proc will have no effect on the ALLOCATE
statement: the ALLOCATE statement will use the implicitly declared and
uninitialized m from the main block!
refertst: proc options(main);
dcl
1 a based,
2 n fixed bin(31),
2 c char(m refer(n));
call inner_proc;
inner_proc: proc;
dcl m fixed bin(31);
dcl p pointer;
m = 15;
allocate a set(p);
end;
end;
252
Enterprise PL/I for z/OS Language Reference
Area data and attribute
Area data and attribute
Area variables describe areas of storage that are reserved for the allocation of
based variables. This reserved storage can be allocated to, and freed from, based
variables by the ALLOCATE and FREE statements. Area variables can have any
storage class and must be aligned.
When a based variable is allocated and an area is not specified, the storage is
obtained from wherever it is available. Consequently, allocated based variables can
be scattered widely throughout main storage. This is not significant for internal
operations because items are readily accessed using the pointers. However, if these
allocations are transmitted to a data set, the items have to be collected together.
Items allocated within an area variable are already collected and can be
transmitted or assigned as a unit while still retaining their separate identities.
You might want to identify the locations of based variables within an area variable
relative to the start of the area variable. Offset variables are provided for this
purpose.
An area can be assigned or transmitted complete with its contained allocations;
thus, a set of based allocations can be treated as one unit for assignment and
input/output while each allocation retains its individual identity.
The size of an area is adjustable in the same way as a string length or an array
bound and therefore it can be specified by an expression or an asterisk (for a
controlled area parameter) or by a REFER option (for a based area).
A variable is given the AREA attribute contextually by its appearance in the
OFFSET attribute or an IN option, or by explicit declaration.
AREA
(*)
(expression
)
REFER(variable)
expression
Specifies the size of the area. If expression, or an asterisk is not specified, the
default is 1000.
*
An asterisk can be used to specify the size if the area variable is declared is a
parameter.
REFER
For a description of the REFER option, refer to “REFER option (self-defining
data)” on page 251.
The area size for areas that have the storage classes AUTOMATIC or
CONTROLLED is given by an expression whose value specifies the number of
reserved bytes.
If an area has the BASED attribute, the area size must be a constant unless the area
is a member of a based structure or union and the REFER option is used.
Chapter 9. Storage control
253
Area data and attribute
The size for areas of static storage class must be specified as a restricted
expression.
Examples of AREA declarations are:
declare area1 area(2000),
area2 area;
In addition to the declared size, an extra 16 bytes of control information precedes
the reserved size of an area. The 16 bytes contain such details as the amount of
storage in use.
The amount of reserved storage that is actually in use is known as the extent of the
area. When an area variable is allocated, it is empty, that is, the area extent is zero.
The maximum extent is represented by the area size. Based variables can be
allocated and freed within an area at any time during execution, thus varying the
extent of an area.
When a based variable is freed, the storage it occupied is available for other
allocations. A chain of available storage within an area is maintained; the head of
the chain is held within the control information. Inevitably, as based variables with
different storage requirements are allocated and freed, gaps occur in the area when
allocations do not fit available spaces. These gaps are included in the extent of the
area.
No operators, including comparison, can be applied to area variables.
Offset data and attribute
Offset data is used exclusively with area variables. The value of an offset variable
indicates the location of a based variable within an area variable relative to the
start of the area. Because the based variables are located relatively, if the area
variable is assigned to a different part of main storage, the offset values remain
valid.
Offset variables do not preclude the use of pointer variables within an area.
OFFSET
(area-variable)
The association of an area variable with an offset variable is not permanent. An
offset variable can be associated with any area variable by means of the POINTER
built-in function (see “Locator conversion” on page 246). The advantage of making
such an association in a declaration is that a reference to the offset variable implies
reference to the associated area variable. If no area variable is specified, the offset
can be used as a locator qualifier only through use of the POINTER built-in
function.
Setting offset variables
The value of an offset variable can be set in any one of the following ways:
v By an ALLOCATE statement
254
Enterprise PL/I for z/OS Language Reference
Offset data and attribute
v By assignment of the value of another locator variable, or a locator value
returned by a user-defined function
v The NULL, SYSNULL, ADDR, ENTRYADDR, OFFSETADD, OFFSETSUBTRACT,
OFFSETVALUE, or OFFSET built-in function
If no area variable is specified, the offset can be used only as a locator qualifier
through use of the POINTER built-in function.
Examples of offset variables
Consider the following example:
dcl X
Y
A
O
based(O),
based(P),
area,
offset(A);
allocate X;
allocate Y in(A);
The storage class of area A and offset O is AUTOMATIC by default. The first
ALLOCATE statement is equivalent to:
allocate x in(A) set(O);
The second ALLOCATE statement is equivalent to:
allocate Y in(A) set(P);
The following example shows how a list can be built in an area variable using
offset variables:
dcl A area,
(T,H) offset(A),
1 STR based(H),
2 P offset(A),
2 data;
allocate STR in(A);
T=H;
do loop;
allocate STR set(T->P);
T=T->P;
.
.
.
end;
Built-in functions for area variables
The EMPTY built-in function initializes the area variable to empty, freeing all
allocations it might have. This is the initial state of an area variable in which no
allocations have yet been made. The AVAILABLEAREA built-in function returns
the size of the largest allocation that can be made in the area.
Area assignment
The value of an area reference can be assigned to one or more area variables by an
assignment statement. Area-to-area assignment has the effect of freeing all
allocations in the target area and then assigning the extent of the source area to the
target area, so that all offsets for the source area are valid for the target area.
In the following example:
Chapter 9. Storage control
255
Area assignment
declare X based (O(1)),
O(2) offset (A),
(A,B) area;
alloc X in (A);
X = 1;
alloc X in (A) set (O(2));
O(2) -> X = 2;
B = A;
Using the POINTER built-in function, the references POINTER (O(2),B)->X and
O(2)->X represent the same value allocated in areas B and A, respectively.
If an area containing no allocations is assigned to a target area, the effect is to free
all allocations in the target area.
Area assignment can be used to expand a list of based variables beyond the
bounds of the original area. Attempting to allocate a based variable within an area
that contains insufficient free storage to accommodate it, or attempting to assign an
area to another area that is not large enough raises the AREA condition. The
ON-unit for this condition can be used to change the value of a pointer qualifying
the reference to the inadequate area, so that it points to a different area; on return
from the ON-unit, the allocation is attempted again, within the new area.
Alternatively, you can use the AVAILABLEAREA built-in function to determine
whether the allocation you are about to make can be done in the area without
raising the AREA condition. Also, the ON-unit can write out the area and reset it
to EMPTY.
Input/output of areas
Areas allow input and output of complete lists of based variables as one unit, to
and from RECORD files. On output, the area extent, together with the 16 bytes of
control information, is transmitted, except when the area is in a structure or union
and is not the last item in it—then, the declared size is transmitted. Thus the
unused part of an area does not take up space on the data set.
Because the extents of areas can vary, varying length records should be used. The
maximum record length required is governed by the area length (area size + 16).
List processing
List processing is the name for a number of techniques to help manipulate
collections of data. Although arrays, structures, and unions are also used for
manipulating collections of data, list processing techniques are more flexible since
they allow collections of data to be indefinitely reordered and extended during
program execution. The purpose here is not to illustrate these techniques but is to
show how based variables and locator variables serve as a basis for this type of
processing.
In list processing, a number of based variables with many generations can be
included in a list. Members of the list are linked together by one or more pointers
in one member identifying the location of other members or lists. The allocation of
a based variable cannot specify where in main storage the variable is to be
allocated (except that you can specify the area in which you want it allocated). In
practice, a chain of items can be scattered throughout main storage, but by
accessing each pointer the next member is found. A member of a list is usually a
structure or union that includes a pointer variable. The following example creates a
list of structures:
256
Enterprise PL/I for z/OS Language Reference
List processing
dcl 1 STR based(H),
2 P pointer,
2 data,
T pointer;
allocate STR;
T=H;
do loop;
allocate STR set(T->P);
T=T->P;
T->P=null;
.
.
.
end;
The structures are generations of STR and are linked by the pointer variable P in
each generation. The pointer variable T identifies the previous generation during
the creation of the list. The first ALLOCATE statement sets the pointer H to identify
it. The pointer H identifies the start, or head, of the list. The second ALLOCATE
statement sets the pointer P in the previous generation to identify the location of
this new generation. The assignment statement T=T->P; updates pointer T to
identify the location of the new generation. The assignment statement T->P=NULL;
sets the pointer in the last generation to NULL, giving a positive indication of the
end of the list.
Figure 19 shows a diagrammatic representation of a one-directional chain.
Figure 19. Example of one-directional chain
Unless the value of P in each generation is assigned to a separate pointer variable
for each generation, the generations of STR can be accessed only in the order in
which the list was created. For the above example, the following statements can be
used to access each generation in turn:
do T=H
repeat(T->P)
while (T¬=null);
.
.
.
T->data;
.
.
.
end;
Chapter 9. Storage control
257
List processing
The foregoing examples show a simple list processing technique, the creation of a
unidirectional list. More complex lists can be formed by adding other pointer
variables into the structure or union. If a second pointer is added, it can be made
to point to the previous generation. The list is then bidirectional; from any item in
the list, the previous and next items can be accessed by using the appropriate
pointer value. Instead of setting the last pointer value to the value of NULL, it can
be set to point to the first item in the list, creating a ring or circular list.
A list need not consist only of generations of a single based variable. Generations
of different based structure or unions can be included in a list by setting the
appropriate pointer values. Items can be added and deleted from a list by
manipulating the values of pointers. A list can be restructured by manipulating the
pointers so that the processing of data in the list can be simplified.
ASSIGNABLE and NONASSIGNABLE attributes
The ASSIGNABLE and NONASSIGNABLE attributes specify whether the
associated variable can be the target of an assignment.
ASSIGNABLE
NONASSIGNABLE
Abbreviations: ASGN, NONASGN
Default: ASSIGNABLE
If a variable has the NONASSIGNABLE attribute, the variable cannot be assigned.
If an entry descriptor has the NONASSIGNABLE attribute, the argument is
assumed not to change when the associated ENTRY is invoked. If the argument is
a constant, no dummy argument is created.
The ASSIGNABLE and NONASSIGNABLE attributes are propagated to members
of structures or unions.
ASSIGNABLE
NONASSIGNABLE
Abbreviations: ASGN, NONASGN
Default: ASSIGNABLE
If a variable has the NONASSIGNABLE attribute, the variable cannot be assigned.
If an entry descriptor has the NONASSIGNABLE attribute, the argument is
assumed not to change when the associated ENTRY is invoked. If the argument is
a constant, no dummy argument is created.
258
Enterprise PL/I for z/OS Language Reference
ASSIGNABLE and NONASSIGNABLE
The ASSIGNABLE and NONASSIGNABLE attributes are propagated to members
of structures or unions.
NORMAL and ABNORMAL attributes
The NORMAL and ABNORMAL attributes specify whether the associated variable
is subject to change at any time.
The ABNORMAL attribute specifies that the value of the variable can change
between statements or within a statement. An abnormal variable is fetched from or
stored in storage each time it is needed or each time it is changed. All optimization
is inhibited for an abnormal variable.
NORMAL
ABNORMAL
Default: NORMAL
The NORMAL and ABNORMAL attributes are propagated to members of
structures or unions.
If the ABNORMAL attribute applies to an INTERNAL STATIC variable with an
INITIAL value, the variable (with its initial value) will appear in the generated
object code even if the variable is otherwise unused.
BIGENDIAN and LITTLEENDIAN attributes
The BIGENDIAN and LITTLEENDIAN attributes specify whether the associated
variable is stored with the most or least significant digits first. The BIGENDIAN
and LITTLEENDIAN attributes are ignored except for FIXED BINARY, ORDINAL,
OFFSET, POINTER, and AREA variables and VARYING string variables.
BIGENDIAN
LITTLEENDIAN
Default: BIGENDIAN except on Intel where the default is LITTLEENDIAN
BIGENDIAN indicates that the variable (for varying strings, the length prefix part
of the variable) is stored with its most significant bytes first. This format is the
native style for z/OS and RS/6000.
LITTLEENDIAN indicates that the variable is stored in the opposite format: with
its least significant bytes first. This format is the native style for Windows.
When the LITTLEENDIAN or BIGENDIAN attribute is applied to an AREA, it
affects only the format in which the control values managed by the compiler and
library are held. It has no effect on user variables stored in the AREA or on user
offset variables used to point to the user variables in the AREA.
Chapter 9. Storage control
259
BIGENDIAN and LITTLEENDIAN
The following example illustrates how BIGENDIAN and LITTLEENDIAN variables
are stored. The built-in function HEXIMAGE shows how X and Y are actually
stored.
dcl X fixed bin(15) bigendian;
dcl Y fixed bin(15) littleendian;
X = 258;
Y = 258;
display( heximage( addr(X), stg(X) ) );
display( heximage( addr(Y), stg(Y) ) );
/* displays 0102 */
/* displays 0201 */
In contrast, the HEX built-in function would show for X and Y as given above:
display (hex(X));
display (hex(Y));
/* displays 0102
/* displays 0102
*/
*/
BIGENDIAN and LITTLEENDIAN have no effect on the semantics of any
operations, or on the storage requirements for any variables.
The BIGENDIAN and LITTLEENDIAN attributes are propagated to members of
structures or unions.
For more information on using BIGENDIAN and LITTLEENDIAN, refer to the
Programming Guide.
The NATIVE and NONNATIVE attributes are synonyms for BIGENDIAN and
LITTLEENDIAN, but their meanings can vary across different systems:
v On z/OS and RS/600, NATIVE means BIGENDIAN
v On Windows, NATIVE means LITTLEENDIAN
HEXADEC and IEEE attributes
HEXADEC and IEEE specify whether the associated variable is stored using the
IBM hexadecimal floating point format or using the IEEE format. The HEXADEC
and IEEE attributes are ignored except for floating-point variables.
IEEE
HEXADEC
Default: IEEE except on z/OS where the default is HEXADEC
HEXADEC indicates that the variable is stored in hexadecimal (z/OS) format.
IEEE indicates that the variable is stored using the IEEE format.
The HEXADEC and IEEE suboptions of the DEFAULT compiler option may be
used to change the default for this attribute.
On the Windows and AIX platforms, all computations are done using IEEE
floating-point; variables declared HEXADEC will be converted to IEEE as
necessary.
260
Enterprise PL/I for z/OS Language Reference
HEXADEC and IEEE
On the z/OS platform, floating-point computations can be done using one of 3 sets
of floating-point instructions:
v IBM hexadecimal floating-point
v IEEE binary floating-point
v IEEE decimal floating-point
On the z/OS platform, the choice of which set of instructions is used for a float
calculation is determined by two compiler options:
v under FLOAT(DFP)
– all computations that would yield a FLOAT DEC result are done using the
IEEE decimal floating-point instructions
– all computations that would yield a FLOAT BIN result are done using the
floating-point instructions for the format specified by the HEXADEC and
IEEE suboptions of the DEFAULT compiler option
v under FLOAT(NODFP)
– all computations that would yield a FLOAT result are done using the
floating-point instructions for the format specified by the HEXADEC and
IEEE suboptions of the DEFAULT compiler option
So, under the FLOAT(NODFP) and DEFAULT(HEXADEC) options, all
computations are done using the hexadecimal floating-point instructions, and
variables declared IEEE will be converted to HEXADEC. But, under the
FLOAT(NODFP) and DEFAULT(IEEE) options, all computations are done using the
IEEE binary floating-point instructions, and variables declared HEXADEC will be
converted to IEEE as necessary.
Under the FLOAT(DFP) compiler option, the IEEE and HEXADEC attributes are
valid only for FLOAT BIN, and the DEFAULT(IEEE/HEXADEC) option will be
applied only to FLOAT BIN.
CONNECTED and NONCONNECTED attributes
Elements, arrays, and major structure or unions are always allocated in connected
storage. References to unconnected storage arise only when you refer to an
aggregate that is made up of noncontiguous items from a larger aggregate. (See
“Cross sections of arrays” on page 177.) For example, in the following structure the
interleaved arrays A.B and A.C are both in unconnected storage.
1 A(10),
2 B,
2 C;
NONCONNECTED
CONNECTED
Abbreviations: CONN, NONCONN
Default: NONCONNECTED
Chapter 9. Storage control
261
CONNECTED and NONCONNECTED
The CONNECTED attribute is applicable only to noncontrolled aggregate
parameters and can be specified only on level-1 names. It specifies that the
parameter is a reference to connected storage only, and therefore, allows the
parameter to be used as a target or source in record-oriented I/O, or as a base in
string overlay defining. When the parameter is connected and the CONNECTED
attribute is used, more efficient object code is produced for references to the
connected parameter.
NONCONNECTED should be specified if a parameter occupies noncontiguous
storage. In the following example the NONCONNECTED attribute specifies that
the sum_Slice routine handles 1-dimensional arrays in which the elements may not
be contiguous. In the first invocation, sum_Slice is passed the first row, which is in
connected storage. In the second invocation, however, sum_Slice is passed the first
column, which is in nonconnected storage.
dcl A(10,10) fixed bin(31);
display( sum_Slice( A(1,*) ) );
display( sum_Slice( A(*,1) ) );
/* first row
*/
/* first column */
sum_Slice:proc(X) returns(fixed bin(31));
dcl X (*) fixed bin(31) nonconnected; /* default */
return(sum(X) );
end;
DEFINED and POSITION attributes
The DEFINED attribute specifies that the declared variable is associated with some
or all of the storage associated with the designated base variable.
The UNION attribute allows you to achieve the same end in a much cleaner
manner and also allows variables with different attributes and precisions to be
overlaid. Also, while the DEFINED attribute guarantees that access through
defined or base variables is reflected in all defined variables, in a union only one
member of the union is valid at any given time. For syntax information on the
UNION attribute, refer to “UNION attribute” on page 179.
DEFINED
reference
(reference)
POSITION(expression)
Abbreviations: DEF for DEFINED, POS for POSITION
reference
To the variable (the base variable) whose storage is associated with the declared
variable; the latter is the defined variable. The base variable can be EXTERNAL
or INTERNAL. It can be a parameter (in string overlay defining, the parameter
must refer to connected storage). It cannot be BASED or DEFINED. A change
to the base variable's value is a corresponding change to the value of the
defined variable, and vice versa.
If the base variable is a data aggregate, a defined variable can comprise all the data
or only a specified part of it.
262
Enterprise PL/I for z/OS Language Reference
DEFINED and POSITION
The defined variable does not inherit any attributes from the base variable. The
defined variable must be INTERNAL and a level-1 identifier. It can have the
dimension attribute. It cannot be INITIAL, AUTOMATIC, BASED, CONTROLLED,
STATIC, or a parameter.
There are three types of defining: simple, iSUB and string overlay.
The type of defining in effect is determined as follows:
1. If the POSITION attribute is specified, string overlay defining is in effect.
2. If the subscripts specified in the base variable contain references to iSUB
variables, iSUB defining is in effect.
3. If neither an iSUB variable nor the POSITION attribute is present and if the
base variable and defined variable match according to the criteria given below.
simple defining is in effect.
4. Otherwise, string overlay defining is in effect.
If the POSITION attribute is specified, the base variable must not contain iSUB
references.
A base variable and a defined variable match if the base variable when passed as
an argument matches a parameter which has the attributes of the defined variable
(except for the DEFINED attribute). For this purpose, the parameter is assumed to
have all array bounds, string lengths, and area sizes specified by asterisks.
For simple and iSUB defining, a PICTURE attribute can only be matched by a
PICTURE attribute that is identical except for repetition factors. For a reference to
specify a valid base variable in string overlay defining, the reference must be in
connected storage. You can override the matching rule completely, but this can
cause unwanted side effects within your program.
The values specified or derived for any array bounds, string lengths, or area sizes
in a defined variable do not always have to match those of the base variable.
However, the defined variable must be able to fit into the corresponding base
array, string, or area.
In references to defined data, the STRINGRANGE, SUBSCRIPTRANGE, and
STRINGSIZE conditions are raised for the array bounds and string lengths of the
defined variable, not the base variable.
The determination of values and the interpretation of names occurs in the
following sequence:
1. The array bounds, string lengths, and area sizes of a defined variable are
evaluated on entry to the block that declares the variable.
2. A reference to a defined variable is a reference to the current generation of the
base variable. When a defined variable is passed as an argument without
creation of a dummy, the corresponding parameter refers to the generation of
the base variable that is current when the argument is passed. This remains
true even if the base variable is reallocated within the invoked procedure.
3. When a reference is made to the defined variable, the order of evaluation of the
subscripts of the base and defined variable is undefined.
If the defined variable is a structure or union containing any elements which are
unaligned nonvarying BIT, then all array bounds and string lengths in the defined
variable must be specified as constants.
Chapter 9. Storage control
263
DEFINED and POSITION
If the defined variable has the BIT attribute, unpredictable results can occur under
the following conditions:
v If the base variable is not on a byte boundary
v If the defined variable is not defined on the first position of the base variable
and the defined variable is used as:
– A parameter in a subroutine call (that is, referenced as internally stored data)
– An argument in a PUT statement
– An argument in a built-in function (library call)
– If the base variable is controlled, and the defined variable is dimensioned and
is declared with variable array bounds
v If the defined variable consists entirely of unaligned non varying bit strings, the
array bounds, string lengths and area sizes of the defined variable must be
known at compile time.
Unconnected Storage
The DEFINED attribute can overlay arrays. This allows array expressions to refer
to array elements in unconnected storage (array elements that are not adjacent in
storage). It is possible for an array expression involving consecutive elements to
refer to unconnected storage in the following case:
v Where a string array is defined on a string array that has elements of greater
length. Consecutive elements in the defined array are separated by the difference
between the lengths of the elements of the base and defined arrays, and are held
in unconnected storage.
An array overlay-defined on another array is always assumed to be in
unconnected storage.
Simple Defining
Simple defining allows you to refer to an element, array, or structure variable by
another name. Simple defining is supported only for scalars, for structures with
constant extents matching those in the base variable, and for arrays of such scalars
and structures if they are not based on controlled variables.
The defined and base variables can comprise any data type, but they must match,
as described earlier. The ALIGNED and UNALIGNED attributes must match for
each element in the defined variable and the corresponding element in the base
variable.
The defined variable can have the dimension attribute.
In simple defining of an array:
v The base variable can be a cross-section of an array.
v The number of dimensions specified for the defined variable must be equal to
the number of dimensions specified for the base variable.
v The range specified by a bound pair of the defined array must equal or be
contained within the range specified by the corresponding bound pair of the
base array.
In simple defining of a string, the length of the defined string must be less than or
equal to the length of the base string.
264
Enterprise PL/I for z/OS Language Reference
DEFINED and POSITION
In simple defining of an area, the size of the defined area must be equal to the size
of the base area.
A base variable can be, or can contain, a varying string, provided that the
corresponding part of the defined variable is a varying string of the same
maximum length.
Examples:
DCL A(10,10,10),
X1(2,2,2) DEF A,
X2(10,10) DEF A(*,*,5),
X3 DEF A(L,M,N);
X1 is a three-dimensional array that consists of the first two elements of each row,
column and plane of A. X2 is a two-dimensional array that consists of the fifth
plane of A. X3 is an element that consists of the element identified by the subscript
expressions L, M, and N.
DCL B CHAR(10),
Y CHAR(5) DEF B;
Y is a character string that consists of the first 5 characters of B.
DCL C AREA(500),
Z AREA(500) DEF C;
Z is an area defined on C.
DCL 1 D UNALIGNED,
2 E,
2 F,
3 G CHAR(10) VAR,
3 H,
1 S UNALIGNED DEF D,
2 T,
2 U,
3 V CHAR(10) VAR,
3 W;
S is a structure defined on D. For simple defining, the organization of the two
structures must be identical. A reference to T is a reference to E, V to G, and so on.
iSUB Defining
With iSUB defining, you can create a defined array that consists of designated
elements from a base array. The defined and base arrays must be arrays of scalars,
may comprise any data types, and must have identical attributes (apart from the
dimension attribute).
The defined variable must have the dimension attribute. In the declaration of the
defined array, the base array must be subscripted, and the subscript positions
cannot be specified as asterisks.
A iSUB variable is a reference, in the subscript list for the base array, to the
dimension of the defined array. At least one subscript in the base array's
subscript-list must be an iSUB expression which, on evaluation, gives the required
subscript in the base array. The value of i ranges from 1 to n, where n is the
number of dimensions in the defined array. The number of subscripts for the base
array must be equal to the number of dimensions for the base array.
Chapter 9. Storage control
265
DEFINED and POSITION
If a reference to a defined array does not specify a subscript expression, subscript
evaluation occurs during the evaluation of the expression or assignment in which
the reference occurs.
The value of i is specified as an integer. Within an iSUB expression, an iSUB
variable uis treated as REAL FIXED BINARY(31,0) variable.
A subscript in a reference to a defined variable is evaluated even if there is no
corresponding iSUB in the base variable's subscript list.
An iSUB-defined variable may not appear in the data-list of a GET DATA or PUT
DATA statement.
Examples:
DCL A(10,10) FIXED BIN
X(10) FIXED BIN DEF( A(1SUB,1SUB) );
X is a one-dimensional array that consists of the diagonal of A: X(i) refers to the
same storage as A(i,i).
DCL B(5,10) FIXED BIN
Y(10,5) FIXED BIN DEF( A(2SUB,1SUB) );
Y is a two-dimensional array that consists of the elements of B with the bounds
transposed: Y(i,j) refers to the same storage as X(j,i).
String Overlay Defining
String overlay defining allows you to associate a defined variable with the storage
for a base variable. Both the defined and the base variable must be string or
picture data.
Neither the defined nor the base variable can have the ALIGNED or the VARYING
attributes.
Both the defined and the base variables must belong to:
v The bit class, consisting of:
Fixed-length bit variables
Aggregates of fixed-length bit variables
v The character class, consisting of:
Fixed-length character variables
Character pictured and numeric pictured variables
Aggregates of the two above
v The graphic class, consisting of:
Fixed-length graphic variables
Aggregates of fixed-length graphic variables
v The widechar class, consisting of:
Fixed-length widechar variables
Aggregates of fixed-length widechar variables
Examples:
DCL A CHAR(100),
V(10,10) CHAR(1) DEF A;
V is a two-dimensional array that consists of all the elements in the character
string A.
266
Enterprise PL/I for z/OS Language Reference
DEFINED and POSITION
DCL B(10) CHAR(1),
W CHAR(10) DEF B;
W is a character string that consists of all the elements in the array B.
POSITION attribute
The POSITION attribute can be used only with string-overlay defining and
specifies the bit, character, graphic or widechar within the base variable at which
the defined variable is to begin.
The expression in the POSITION attribute specifies the position relative to the start
of the base variable. The value specified in the expression can range from 1 to n,
where n is defined as
n = N(b) - N(d) + 1
where N(b) is the number of bits, characters, graphics or widechars in the base
variable, and N(d) is the number of bits, characters, graphics or widechars in the
defined variable.
The expression is evaluated and converted to an integer value at each reference to
the defined item.
If the POSITION attribute is omitted, POSITION(1) is the default.
When the defined variable is a bit class aggregate:
v The POSITION attribute can contain only an integer.
v The base variable must not be subscripted.
The base variable must refer to data in connected storage.
Examples:
DCL C(10,10) BIT(1),
X BIT(40) DEF C POS(20);
X is a bit string that consists of 40 elements of C, starting at the 20th element.
DCL E PIC’99V.999’,
Z1(6) CHAR(1) DEF (E),
Z2 CHAR(3) DEF (E) POS(4),
Z3(4) CHAR(1) DEF (E) POS(2);
Z1 is a character string array that consists of all the elements of the decimal
numeric picture E. Z2 is a character string that consists of the elements '999' of the
picture E. Z3 is a character-string array that consists of the elements '9.99' of the
picture E.
DCL A(20) CHAR(10),
B(10) CHAR(5) DEF (A) POSITION(1);
The first 50 characters of B consist of the first 50 characters of A. POSITION(1)
must be explicitly specified. Otherwise, simple defining is used and gives different
results.
Chapter 9. Storage control
267
INITIAL
INITIAL attribute
The INITIAL attribute specifies an initial value or values assigned to a variable at
the time storage is allocated for it. Only one initial value can be specified for an
element variable. More than one can be specified for an array variable. A union
variable can be initialized only by separate initialization of its elementary names,
whether they are element or array variables. A variable that has a defined structure
type can be initialized by using the VALUE type function together with the
INITIAL attribute. The INITIAL attribute cannot be given to constants, defined
data, noncontrolled parameters, and non-LIMITED static entry variables.
The INITIAL attribute has the following forms:
1. The first form, INITIAL, specifies an initial constant, expression, or function
reference, for which the value is assigned to a variable when storage is
allocated to it.
2. The second form, INITIAL CALL, specifies (with the CALL option) that a
procedure is invoked to perform initialization. The variable is initialized by
assignment during the execution of the called routine. (The routine is not
invoked as a function that returns a value to the point of invocation.)
3. The third form, INITIAL TO, specifies that the pointer (or array of pointers) is
initialized with the address of the character string specified in the INITIAL
LIST. The string also has the attributes indicated by the TO keyword.
Note that the INITIAL form is allowed on the elementary names of a DEFINE
STRUCTURE statement, but the INITIAL CALL and INITIAL TO forms are not
allowed. For more information about initializing the typed structure, see “VALUE”
on page 724.
268
Enterprise PL/I for z/OS Language Reference
INITIAL
,
INITIAL ( item
)
item:
*
initial-constant
reference
(expression)
iteration-specification
iteration-specification:
(
iteration-factor
*
)
iteration-item
iteration-item:
*
initial-constant
reference
,
( item
)
initial-constant:
arithmetic-constant
+
bit-constant
character-constant
graphic-constant
entry-constant
file-constant
label-constant
real-constant
+
+
-
INITIAL CALL
entry-reference
generic-name
built-in-name
imaginary-constant
,
( argument
)
Chapter 9. Storage control
269
INITIAL
,
INITIAL TO (
varying
varyingz
nonvarying
)
( item
)
item:
(see description under INITIAL)
Abbreviations: INIT, INIT CALL, INIT TO
*
Specifies that the element is to be left uninitialized, except when the element is
used as an iteration factor.
iteration factor
Specifies the number of times the iteration item is to be repeated in the
initialization of elements of an array.
The iteration factor can be an expression or an asterisk.
v An expression is converted to FIXED BINARY(31). For static variables, it
must be a constant.
v An asterisk indicates that the remaining elements should be initialized to the
specified value.
The use of an asterisk for both the iteration factor and the initial value is not
allowed.
A negative or zero iteration factor specifies no initialization.
constant
reference
expression
These specify an initial value to be assigned to the initialized variable.
INITIAL CALL
For INITIAL CALL, the entry reference and argument list passed must satisfy
the condition stated for block activation as discussed under “Block activation”
on page 89.
INITIAL CALL cannot be used to initialize static data.
The following example initializes all of the elements of A to '00'X without the need
for the INITIAL attribute on each element:
dcl
1
2
2
2
A automatic,
...,
...,
* char(0) initial call plifill( addr(A), ’00’X, stg(A) );
An AUTOMATIC variable that has an INITIAL CALL attribute will be retained
even if otherwise unused (in case the logic of your program requires that the call
to be executed).
If the procedure invoked by the INITIAL CALL statement has been specified in a
FETCH or RELEASE statement and it is not present in main storage, the INITIAL
270
Enterprise PL/I for z/OS Language Reference
INITIAL
CALL statement initiates dynamic loading of the procedure. (For more information
on dynamic loading, refer to “Dynamic loading of an external procedure” on page
102.)
INITIAL TO
Use only with static native pointers. Specifies that the pointer (or array of
pointers) is initialized with the address of the character string specified in the
INITIAL LIST. Also specifies that the string has the attributes indicated by the
TO keyword.
In the following example, pdays is initialized with the addresses of character
varyingz strings containing the names of the weekdays.
dcl pdays(7) static ptr init to(varyingz)
(’Sunday’,
’Monday’,
’Tuesday’,
’Wednesday’,
’Thursday’,
’Friday’,
’Saturday’ );
You should not change a value identified by a pointer initialized with INITIAL TO.
The value can be placed in read-only storage and an attempt to change it could
result in a protection exception. Given the array pdays in the preceding example,
then, the following assignment is illegal:
dcl x char(30) varz based;
pdays(1)->x = ’Sonntag’;
Initializing array variables
Initial values specified for an array are assigned to successive elements of the array
in row-major order (final subscript varying most rapidly). If too many initial
values are specified, the excess values are ignored; if not enough are specified, the
remainder of the array is not initialized.
The initialization of an array of strings can include both string repetition and
iteration factors. Where only one of these is given, it is taken to be a string
repetition factor unless the string constant is placed in parentheses.
The iteration factor can be specified as *, which means that all of the remaining
elements will be initialized with the given value.
The following examples illustrate the use of (and difference between) string
repetition and iteration factors:
((2)’A’) is equivalent to (’AA’)
((2)(’A’)) is equivalent to (’A’,’A’)
((2)(1)’A’) is equivalent to (’A’,’A’)
((*)(1)’A’) is equivalent to (’A’,’A’...’A’)
An area variable is initialized with the value of the EMPTY built-in function, on
allocation. Any INITIAL clause for an area variable will be ignored.
If the attributes of an item in the INITIAL attribute differ from those of the data
item itself, conversion is performed, provided the attributes are compatible.
INITIAL is not allowed on objects of REFER clauses.
Chapter 9. Storage control
271
Initializing unions
Initializing unions
The members of a union can have initial values. However, if the union is static,
only one member of the union can have the initial attribute. For nonstatic unions,
initial attributes are applied in order of appearance. Subsequent initial values
overwrite previous ones.
In the following example, the declaration for NT1 would be invalid if it had the
static storage attribute.
dcl
1 NT1 union automatic,
2 Numeric_translate_table1 char(256)
init( (256)’00’X),
2 *,
3 * char(240),
3 * char(10) init(’0123456789’),
2 * char(0);
dcl
1 NT2 union static,
2 Numeric_translate_table2 char(256),
2 *,
3 * char(
rank(’0’)
)
init((1)(low(rank(’0’))) ),
3 * char(10) init(’0123456789’),
3 * char(
(256-(rank(’0’))-10)
)
init((1)(low( (256-(rank(’0’))-10) )) ),
The declaration for NT2 is valid even though it has static storage class.
Furthermore, the NT2 declaration is portable between EBCDIC and ASCII modes of
execution.
Initializing static variables
For a variable that is allocated when the program is loaded, that is, a static
variable, which remains allocated throughout execution of the program, any value
specified in an INITIAL attribute is assigned only once. (Static storage for fetched
procedures is allocated and initialized each time the procedure is loaded.)
If static variables are initialized using the INITIAL attribute, the initial values must
be specified as restricted expressions. Extent specifications must be restricted
expressions.
The restrictions on initializing static variables are as follows:
v STATIC ENTRY variables must have the LIMITED attribute (see “LIMITED
attribute” on page 123).
v INITIAL is not allowed for static format variables.
v INITIAL is allowed for label variables that are not part of structures or unions
with the following restrictions. When INITIAL is used, the label variable gets the
CONSTANT attribute.
– All initial values must be unsubscripted user statement labels.
– All initial values must be in the same block as the label declaration.
– If the label is an array, it must be completely initialized.
v INITIAL is not valid for AREA variables.
v Only one member of a static union can specify INITIAL.
272
Enterprise PL/I for z/OS Language Reference
Initializing Static Variables
v If a STATIC EXTERNAL item without the RESERVED attribute is given the
INITIAL attribute in more than one declaration, the value specified must be the
same in every case.
Initializing automatic variables
For automatic variables, which are allocated at each activation of the declaring
block, any specified initial value is assigned with each allocation.
Initializing based and controlled variables
For based and controlled variables which are allocated at the execution of
ALLOCATE statements (also LOCATE statements for based variables), any
specified initial value is assigned with each allocation.
When storage for based variables is allocated using the ALLOCATE or the
AUTOMATIC built-in functions, the initial values are not assigned; for area
variables, the area is not implicitly initialized to EMPTY.
Examples
In the following example, when storage is allocated for Name, the character constant
’John Doe’ (padded on the right to 10 characters) is assigned to it.
dcl Name char(10) init(’John Doe’);
In the following example, when Pi is allocated, it is initialized to the value 3.1416.
dcl Pi fixed dec(5,4) init(3.1416);
The following example specifies that A is to be initialized with the value of the
expression B*C:
declare A init((B*C));
The following example results in each of the first 920 elements of A being set to 0.
The next 80 elements consist of 20 repetitions of the sequence 5,5,5,9.
declare A (100,10) initial
((920)0, (20) ((3)5,9));
In the following example, only the first, third, and fourth elements of A are
initialized; the rest of the array is not initialized. The array B is fully initialized,
with the first 25 elements initialized to 0, the next 25 to 1, and the remaining
elements to 0. In the structure C, where the dimension (8) has been inherited by D
and E, only the first element of D is initialized. All the elements of E are initialized.
declare A(15) character(13) initial
(’John Doe’,
*,
’Richard Row’,
’Mary Smith’),
B (10,10) decimal fixed(5)
init((25)0,(25)1,(*)0),
1 C(8),
2 D initial (0),
2 E initial((*)0);
When an array of structures or unions is declared with the LIKE attribute to obtain
the same structuring as a structure or union whose elements have been initialized,
only the first structure or union is initialized.
Chapter 9. Storage control
273
Examples
In the following example only J(1).H and J(1).I are initialized in the array of
structures.
declare 1 G,
2 H initial(0),
2 I initial(0),
1 J(8) like G;
274
Enterprise PL/I for z/OS Language Reference
Chapter 10. Input and output
Data sets . . . . . . . . . . . . .
Consecutive . . . . . . . . . . .
Indexed . . . . . . . . . . . .
Relative . . . . . . . . . . . .
Regional . . . . . . . . . . . .
Files . . . . . . . . . . . . . .
FILE attribute . . . . . . . . . .
File constant. . . . . . . . . .
File variable . . . . . . . . . .
Specifying a file reference . . . . .
RECORD and STREAM attributes . . .
INPUT, OUTPUT, and UPDATE attributes.
SEQUENTIAL and DIRECT attributes . .
BUFFERED and UNBUFFERED attributes .
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
276
276
276
277
277
277
277
277
279
280
280
281
281
282
ENVIRONMENT attribute . . .
KEYED attribute . . . . . .
PRINT attribute . . . . . .
Opening and closing files . . . .
OPEN statement . . . . . .
Implicit opening . . . . . .
Example of file constant . . .
Example of file variable . . .
Example of implicit opening .
Examples of declarations of file
CLOSE statement . . . . . .
FLUSH statement . . . . . .
SYSPRINT and SYSIN . . . . .
. . .
. . .
. . .
. . .
. . .
. . .
. . .
. . .
. . .
constants
. . .
. . .
. . .
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
282
282
282
283
283
285
286
286
286
287
287
288
288
PL/I input and output statements (such as READ, WRITE, GET, PUT) let you
transmit data between the main and auxiliary storage of a computer. A collection
of data external to a program is called a data set. Transmission of data from a data
set to a program is called input. Transmission of data from a program to a data set
is called output. (If you are using a terminal, “data set” can also mean your
terminal.)
PL/I input and output statements are concerned with the logical organization of a
data set and not with its physical characteristics. A program can be designed
without specific knowledge of the input/output devices that is used when 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
employs models of data sets, called files. A file can be associated with different
data sets at different times during the execution of a program.
PL/I uses two types of data transmission: stream and record.
In stream-oriented data transmission, the organization of the data in the data set is
ignored within the program, and the data is treated as though it were a continuous
stream of individual data values in character form. Data is converted from
character form to internal form on input, and from internal form to character form
on output.
For more information on stream-oriented data transmission, refer to Chapter 12,
“Stream-oriented data transmission,” on page 299.
Stream-oriented data transmission can be used for processing input data prepared
in character form and for producing readable output, where editing is required.
Stream-oriented data transmission allows synchronized communication with the
program at run time from a terminal, if the program is interactive.
Stream-oriented data transmission is more versatile than record-oriented data
transmission in its data-formatting abilities, but is less efficient in terms of run
time.
In record-oriented data transmission, the data set is a collection of discrete records.
The record on the external medium is generally an exact copy of the record as it
exists in internal storage. No data conversion takes place during record-oriented
© Copyright IBM Corp. 1999, 2012
275
Input and output
data transmission. On input the data is transmitted exactly as it is recorded in the
data set, and on output it is transmitted exactly as it is recorded internally.
For more information on record-oriented data transmission, refer to Chapter 11,
“Record-oriented data transmission,” on page 289.
Record-oriented data transmission can be used for processing files that contain
data in any representation, such as binary, decimal, or character.
Record-oriented data transmission is more versatile than stream-oriented data
transmission, in both the manner in which data can be processed and the types of
data sets that it can process. Since data is recorded in a data set exactly as it
appears in main storage, any data type is acceptable. No conversions occur, but
you must have a greater awareness of the data structure.
It is possible for the same data set to be processed at different times by either
stream or record data transmission. However, all items in the data set must be in
character form.
The following sections in this chapter discuss the kinds of data sets, the attributes
for describing files, and how you open and close files in order to transmit data. For
more information about the types of data set organizations that PL/I recognizes,
refer to the Programming Guide.
Data sets
In addition to being used as input from and output to your terminal, data sets are
stored on a variety of auxiliary storage media, including magnetic tape and
direct-access storage devices (DASDs). Despite their variety, these media have
characteristics that allow common methods of collecting, storing, and transmitting
data. The organization of a data set determines how data is recorded in a data set
and how the data is subsequently retrieved so that it can be transmitted to the
program. Records are stored in and retrieved from a data set either sequentially on
the basis of successive physical or logical positions, or directly by the use of keys
specified in data transmission statements.
PL/I supports the following types of data set organizations:
Consecutive
Indexed
Relative
Regional
The data set organizations differ in the way they store data and in the means they
use to access data.
Consecutive
In the consecutive data set organization, records are organized solely on the basis
of their successive physical positions. 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 were written.
Indexed
In the indexed data set organization, records are placed in a logical sequence based
on the key of each record. An indexed data set must reside on a direct-access
276
Enterprise PL/I for z/OS Language Reference
Data sets
device. A character string key identifies the record and allows direct retrieval,
replacement, addition, and deletion of records. Sequential processing is also
allowed.
Relative
In the relative data set organization, numbered records are placed in a position
relative to each other. The records are numbered in succession, beginning with one.
A relative data set must reside on a direct-access device. A key that specifies the
record number identifies the record and allows direct retrieval, replacement,
addition, and deletion of records. Sequential processing is also allowed.
Regional
The regional data set organization is divided into numbered regions, each of which
can contain one record. The regions are numbered in succession, beginning with
zero. A region can be accessed by specifying its region number, and perhaps a key,
in a data transmission statement. The key specifies the region number and
identifies the region to allow optimized direct retrieval, replacement, addition, and
deletion of records.
Files
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 employs models of data sets,
called files. These models determine how input and output statements access and
process the associated data set. Unlike a data set, a file data item has significance
only within the source program and does not exist as a physical entity external to
the program.
A name that represents a file has the FILE attribute.
FILE attribute
The FILE attribute specifies that the associated name is a file constant or file
variable.
FILE
The FILE attribute can be implied for a file constant by any of the file description
attributes. A name can be contextually declared as a file constant through its
appearance in the FILE option of any input or output statement, or in an ON
statement for any input/output condition.
File constant
Each data set processed by a PL/I program must be associated with a file constant.
The individual characteristics of each file constant are described with file
description attributes. These attributes fall into two categories: alternative attributes
and additive attributes.
An alternative attribute is one that is chosen from a group of attributes. If no
explicit or implied attribute is given for one of the alternatives in a group and if
one of the alternatives is required, a default attribute is used.
Chapter 10. Input and output
277
File constant
Table 29 lists the PL/I alternative file attributes.
Table 29. Alternative file attributes
Group Type
Alternative Attributes
Default Attribute
Usage
Function
Access
Buffering
STREAM or RECORD
INPUT or OUTPUT or UPDATE
SEQUENTIAL or DIRECT
BUFFERED or UNBUFFERED
STREAM
INPUT
SEQUENTIAL
BUFFERED
(for SEQUENTIAL files);
Scope
EXTERNAL or INTERNAL
UNBUFFERED (for DIRECT files)
EXTERNAL
An additive attribute is one that must be stated explicitly or is implied by another
explicitly stated attribute. The additive attributes are ENVIRONMENT, KEYED and
PRINT. The additive attribute KEYED is implied by the DIRECT attribute. The
additive attribute PRINT can be implied by the output file name SYSPRINT.
Table 30 shows the attributes that apply to each type of data transmission.
Table 30. Attributes by data transmission type
Type of transmission
Attribute
Stream-oriented
ENVIRONMENT
INPUT and OUTPUT
PRINT
STREAM
BUFFERED and UNBUFFERED
DIRECT and SEQUENTIAL
ENVIRONMENT
INPUT, OUTPUT, and UPDATE
KEYED
RECORD
Record-oriented
Table 31 on page 279 shows the valid combinations of file attributes.
278
Enterprise PL/I for z/OS Language Reference
File constant
Table 31. Attributes of PL/I file declarations
File
Type
Data
Set
Organization
S
T
R
E
A
M
C
o
n
s
e
c
u
t
i
v
e
RECORD
Legend:
SEQUENTIAL
DIRECT
C
o
n
s
e
c
u
t
i
v
e
R
e
l
a
t
i
v
e
I
n
d
e
x
e
d
R
e
l
a
t
i
v
e
I
n
d
e
x
e
d
File Attributes
FILE
I
Must be specified or
implied
D
Default
O
Optional
S
Must be specified
-
Invalid
Attributes Implied
I
I
I
I
I
I
INPUT
D
D
D
D
D
D
FILE
OUTPUT
O
O
O
O
O
O
FILE
ENVIRONMENT
O
O
O
O
O
O
FILE
STREAM
D
-
-
-
-
-
FILE
O
-
-
-
-
-
FILE STREAM OUTPUT
RECORD
-
I
I
I
I
I
FILE
2
-
O
O
O
O
O
FILE RECORD
1
PRINT
1
UPDATE
SEQUENTIAL
-
D
D
D
-
-
FILE RECORD
3
-
-
O
O
I
I
FILE RECORD
DIRECT
-
-
-
-
S
S
FILE RECORD KEYED
KEYED
Notes:
1
A file with the INPUT attribute cannot have the PRINT attribute
2
UPDATE is invalid for tape files.
3
KEYED is required for indexed and relative output
Scope is discussed in “Scope of declarations” on page 155.
The FILE attribute can be implied for a file constant by any of the file description
attributes discussed in this chapter. A name can be contextually declared as a file
constant through its appearance in the FILE option of any input or output
statement, or in an ON statement for any input/output condition.
In the following example, the name Master is declared as a file constant:
declare Master file;
File variable
A file variable has the attributes FILE and VARIABLE. It cannot have any of the
file constant description attributes. File constants can be assigned to file variables.
After assignment, a reference to the file variable has the same significance as a
reference to the assigned file constant.
Chapter 10. Input and output
279
File variable
The value of a file variable can be transmitted by record-oriented transmission
statements. The value of the file variable on the data set might not be valid after
transmission.
The VARIABLE attribute is implied under the circumstances described in
“VARIABLE attribute” on page 46.
In the following declaration Account is declared as a file variable, and Acct1 and
Acct2 are declared as file constants. The file constants can subsequently be
assigned to the file variable.
declare Account file variable,
Acct1 file,
Acc2 file;
For syntax information, refer to “VARIABLE attribute” on page 46.
Specifying a file reference
A file reference can be a file constant, a file variable, or a function reference which
returns a value with the FILE attribute. It can be used in the following ways:
v In a FILE or COPY option
v As an argument to be passed to a function or subroutine
v To qualify an input/output condition for ON, SIGNAL, and REVERT statements
v As the expression in a RETURN statement.
On-units can be established for a file constant through a file variable that
represents its value (see “ON-units for file variables” on page 354). In the
following example, the statements labelled L1 and L2 both specify null ON-units
for the same file.
dcl F file,
G file variable;
G=F;
L1: on endfile(G);
L2: on endfile(F);
RECORD and STREAM attributes
The RECORD and STREAM usage attributes specify the kind of data transmission
used for the file.
STREAM
RECORD
Default: STREAM
RECORD indicates that the file consists of a collection of physically separate
records, each of which consists of one or more data items in any form. Each record
is transmitted as an entity to or from a variable.
STREAM indicates that the data of the file is a continuous stream of data items, in
character form, assigned from the stream to variables, or from expressions into the
stream.
280
Enterprise PL/I for z/OS Language Reference
RECORD and STREAM
A file with the STREAM attribute can be specified only in the FILE option of the
OPEN, CLOSE, GET, and PUT input/output statements.
A file with the RECORD attribute can be specified only in the FILE option of the
OPEN, CLOSE, READ, WRITE, REWRITE, LOCATE, and DELETE input/output
statements.
INPUT, OUTPUT, and UPDATE attributes
The INPUT, OUTPUT, and UPDATE function attributes specify the direction of
data transmission allowed for a file. INPUT specifies that data is transmitted from
a data set to the program. OUTPUT specifies that data is transmitted from the
program to a data set, either to create a new data set or to extend an existing one.
UPDATE, which applies to RECORD files only, specifies that the data can be
transmitted in either direction. A declaration of UPDATE for a SEQUENTIAL file
indicates the update-in-place mode.
INPUT
OUTPUT
UPDATE
Default: INPUT
SEQUENTIAL and DIRECT attributes
The SEQUENTIAL and DIRECT access attributes apply only to RECORD files, and
specify how the records in the file are accessed.
SEQUENTIAL
DIRECT
Abbreviation: SEQL for SEQUENTIAL
Default: SEQUENTIAL
The DIRECT attribute specifies that records in a data set are directly accessed. The
location of the record in the data set is determined by a character-string key.
Therefore, the DIRECT attribute implies the KEYED attribute. The associated data
set must be on a direct-access storage device.
The SEQUENTIAL attribute specifies that records in a consecutive or relative data
set are accessed in physical sequence, and that records in an indexed data set are
accessed in key sequence order. For certain data set organizations, a file with the
SEQUENTIAL attribute can also be used for direct access or for a mixture of
random and sequential access. In this case, the file must have the additive attribute
Chapter 10. Input and output
281
SEQUENTIAL and DIRECT
KEYED. Existing records of a data set in a SEQUENTIAL UPDATE file can be
modified, ignored, or, if the data set is indexed, deleted.
BUFFERED and UNBUFFERED attributes
The buffering attributes apply only to RECORD files.
BUFFERED
UNBUFFERED
Abbreviations: BUF for BUFFERED, and UNBUF for UNBUFFERED
Defaults: BUFFERED is the default for SEQUENTIAL files. UNBUFFERED is the
default for DIRECT files.
The BUFFERED attribute specifies that during transmission to and from a data set,
each record of a RECORD file must pass through intermediate storage buffers. This
allows both move and locate mode processing.
The UNBUFFERED attribute indicates that a record in a data set need not pass
through a buffer but can be transmitted directly to and from the main storage
associated with a variable. This allows only move mode processing.
ENVIRONMENT attribute
The characteristic list of the ENVIRONMENT attribute specifies various data set
characteristics that are not part of PL/I. For a full list and description of the
characteristics and their uses, refer to the Programming Guide.
Note: Because the characteristics are not part of the PL/I language, using them in
a file declaration can limit the portability of your application program.
KEYED attribute
The KEYED attribute applies only to RECORD files, and must be associated with
indexed and relative data sets. It specifies that records in the file can be accessed
using one of the key options (KEY, KEYTO, or KEYFROM) of record I/O
statements.
KEYED
The KEYED attribute need not be specified unless one of the key options is used.
PRINT attribute
The PRINT attribute is described in “PRINT attribute” on page 318.
282
Enterprise PL/I for z/OS Language Reference
Opening and closing files
Opening and closing files
Before a file can be used for data transmission, by input or output statements, it
must be associated with a data set. Opening a file associates the file with a data set
and involves checking for the availability of external media, positioning the media,
and allocating required operating system support. When processing is completed,
the file must be closed. Closing a file dissociates the file from the data set.
PL/I provides two statements, OPEN and CLOSE, to perform these functions.
However, use of these statements is optional. If an OPEN statement is not executed
for a file, the file is opened implicitly during the execution of first data
transmission statement for that file. In this case, the file opening uses information
about the file as specified in a DECLARE statement (and defaults derived from the
transmission statement). Similarly, if a file has not been closed before PL/I
termination, PL/I will close it during the termination process.
When a file for stream input, sequential input, or sequential update is opened, the
associated data set is positioned at the first record.
OPEN statement
The OPEN statement associates a file with a data set. It merges attributes specified
on the OPEN statement with those specified on the DECLARE statement. It also
completes the specification of attributes for the file, if a complete set of attributes
has not been declared for the file being opened.
Chapter 10. Input and output
283
OPEN
,
OPEN options-group
;
options-group:
STREAM
INPUT
FILE(file-reference)
RECORD
OUTPUT
UPDATE
BUFFERED
SEQUENTIAL
UNBUFFERED
UNBUFFERED
KEYED
PRINT
DIRECT
BUFFERED
TITLE(expression)
LINESIZE(expression)
PAGESIZE(expression)
The options of the OPEN statement can appear in any order.
FILE
Specifies the name of the file that is associated with a data set.
STREAM, RECORD,
INPUT, OUTPUT, UPDATE,
DIRECT, SEQUENTIAL,
BUFFERED, UNBUFFERED,
KEYED, and PRINT
These options specify attributes that augment the attributes specified in the file
declaration. The same attributes need not be listed in both OPEN and
DECLARE statements for the same file. For a list of attributes for record and
stream input and output, see Table 30 on page 278.
When a STREAM file is opened, the first GET or PUT statement can specify,
with a statement option or format item, the first record to be accessed. The
statement option or format item indicates that n lines are skipped before a
record is accessed. The file is then positioned at the start of the nth record. If
no statement option or format item is encountered, the initial file position is
the start of the first line or record. If the file has the PRINT attribute, it is
physically positioned at column 1 of the first line or record.
Opening a file that is already open does not affect the file.
284
Enterprise PL/I for z/OS Language Reference
OPEN
TITLE
The content of expression determines what is being designated. For more
information on the TITLE attribute refer to the Programming Guide.
LINESIZE
Converted to an integer value, specifies the length in bytes of a line during
subsequent operations on the file. New lines can be started by use of the
printing and control format items or by options in a GET or PUT statement. If
an attempt is made to position a file past the end of a line before explicit
action to start a new line is taken, a new line is started, and the file is
positioned to the start of this new line. The default line size for PRINT file is
120.
The LINESIZE option can be specified only for a STREAM OUTPUT file.
PAGESIZE
Is evaluated and converted to an integer value, and specifies the number of
lines per page. The first attempt to exceed this limit raises the ENDPAGE
condition. During subsequent transmission to the PRINT file, a new page can
be started by use of the PAGE format item or by the PAGE option in the PUT
statement. The default page size is 60.
The PAGESIZE option can be specified only for a file having the PRINT
attribute.
Implicit opening
An implicit opening of a file occurs when a GET, PUT, READ, WRITE, LOCATE,
REWRITE, or DELETE statement is executed for a file for which an OPEN
statement has not already been executed.
If a GET statement contains a COPY option, execution of the GET statement can
cause implicit opening of either the file specified in the COPY option or, if no file
was specified, of the output file SYSPRINT. Implicit opening of the file specified in
the COPY option implies the STREAM and OUTPUT attributes.
Table 32 shows the attributes that are implied when a given statement causes the
file to be implicitly opened:
Table 32. Attributes implied by implicit open
Statement
Implied Attributes
GET
STREAM, INPUT
PUT
STREAM, OUTPUT
READ
RECORD, INPUTNote
WRITE
RECORD, OUTPUTNote
LOCATE
RECORD, OUTPUT, SEQUENTIAL
REWRITE
RECORD, UPDATE
DELETE
RECORD, UPDATE
Note:
INPUT and OUTPUT are default attributes for READ and WRITE statements only if
UPDATE has not been explicitly declared.
Chapter 10. Input and output
285
Implicit opening
When one of the statements listed in Table 32 on page 285 opens a file implicitly, it
is functionally equivalent to using an explicit OPEN statement for the file with the
same attributes specified.
There must be no conflict between the attributes specified in a file declaration and
the attributes implied as the result of opening the file. For example, the attributes
INPUT and UPDATE are in conflict, as are the attributes UPDATE and STREAM.
The implied attributes discussed earlier are applied before the default attributes
listed in Table 32 on page 285 are applied. Implied attributes can also cause a
conflict. If a conflict in attributes exists after the application of default attributes,
the UNDEFINEDFILE condition is raised.
Table 33. Merged and implied attributes
Merged Attributes
Implied Attributes
UPDATE
RECORD
SEQUENTIAL
RECORD
DIRECT
RECORD, KEYED
PRINT
OUTPUT, STREAM
KEYED
RECORD
The following two examples illustrate attribute merging for an explicit opening
using a file constant and a file variable:
Example of file constant
declare Listing file stream;
open file(Listing) print;
Attributes after merge caused by execution of the OPEN statement are STREAM
and PRINT. Attributes after implication are STREAM, PRINT, and OUTPUT.
Attributes after default application are STREAM, PRINT, OUTPUT, and
EXTERNAL.
Example of file variable
declare Account file variable,
(Acct1,Acct2) file
output;
Account = Acct1;
open file(Account) print;
Account = Acct2;
open file(Account) record unbuf;
The file Acct1 is opened with attributes (explicit and implied) STREAM,
EXTERNAL, PRINT, and OUTPUT. The file Acct2 is opened with attributes
RECORD, EXTERNAL, and OUTPUT.
Example of implicit opening
declare Master file keyed internal;
read file (Master)
into (Master_Record)
keyto(Master_Key);
286
Enterprise PL/I for z/OS Language Reference
Implicit opening
Attributes after merge (from the implicit opening caused by execution of the READ
statement) are KEYED, INTERNAL, RECORD, and INPUT. (No additional
attributes are implied.) Attributes after default application are KEYED, INTERNAL,
RECORD, INPUT, and SEQUENTIAL.
Examples of declarations of file constants
declare File3 input direct environment( regional(1) )
This declaration specifies three file attributes: INPUT, DIRECT, and
ENVIRONMENT. Other implied attributes are FILE (implied by each of the
attributes) and RECORD and KEYED (implied by DIRECT). Scope is EXTERNAL,
by default. The ENVIRONMENT attributes specifies that the data set is of the
REGIONAL(1) organization.
For the previous declaration, all necessary attributes are either stated or implied in
the DECLARE statement. None of the stated attributes can be changed (or
overridden) in an OPEN statement.
If the declaration is written as shown in the following example, invntry can be
opened for different purposes.
declare invntry file;
In the following example, the file attributes are the same as those specified (or
implied) in the DECLARE statement in the previous example.
open file (Invntry)
update sequential;
The file might be opened in this way, then closed, and then later opened with a
different set of attributes. For example, the following OPEN statement allows
records to be read with either the KEYTO or the KEY option.
open file (Invntry)
input sequential keyed;
Because the file is SEQUENTIAL, the data set can be accessed in a purely
sequential manner. It can also be accessed directly by means of a READ statement
with a KEY option. A READ statement with a KEY option for a file of this
description obtains a specified record. Subsequent READ statements without a KEY
option access records sequentially, beginning with the next record in KEY
sequence.
CLOSE statement
The CLOSE statement dissociates an opened file from its data set.
,
CLOSE
FILE(file-reference)
FILE(*)
;
FILE
Specifies the name of the file that is dissociated from the data set. CLOSE
FILE(*) closes all open files.
Chapter 10. Input and output
287
CLOSE
The CLOSE statement also dissociates from the file all attributes established for it
by the implicit or explicit opening process. If desired, new attributes can be
specified for the file in a subsequent OPEN statement. However, all attributes
explicitly given to the file constant in a DECLARE statement remain in effect.
Closing a file that was previously closed has no effect. A closed file can be
reopened. If a file is not closed by a CLOSE statement, it is closed at the
termination of the program.
FLUSH statement
The FLUSH statement can be used to flush one or all files.
FLUSH
FILE(file-reference)
FILE(*)
;
FILE
Specifies the name of the output file.
The FLUSH statement flushes the buffers associated with an open output file (or
with all open output files if * is specified). This normally happens when the file is
closed or the program ends, but the FLUSH statement ensures the buffers are
flushed before any other processing occurs.
SYSPRINT and SYSIN
Two files are provided that can be used by any PL/I program. One is the input file
SYSIN, and the other is the output file SYSPRINT. These files need not be declared
or opened explicitly. For SYSIN, the default attributes are STREAM INPUT, and for
SYSPRINT they are STREAM OUTPUT PRINT. Both file names, SYSIN and
SYSPRINT, have the default attribute EXTERNAL, even though SYSPRINT contains
more than 7 characters.
The compiler does not reserve the names SYSIN and SYSPRINT for the specific
purposes described above. They can be used for other purposes besides identifying
SYSIN and SYSPRINT files. Other attributes can be applied to them, but the PRINT
attribute is applied by default to SYSPRINT when it is declared or opened as a
STREAM OUTPUT file unless the INTERNAL attribute is declared for it.
288
Enterprise PL/I for z/OS Language Reference
Chapter 11. Record-oriented data transmission
Data transmitted . . . . . . . .
Unaligned bit strings . . . . . .
Varying length strings . . . . .
Area variables . . . . . . . .
Data transmission statements . . . .
READ statement . . . . . . .
WRITE statement . . . . . . .
REWRITE statement . . . . . .
LOCATE statement . . . . . .
DELETE statement . . . . . .
Options of data transmission statements
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
289
289
290
290
290
290
291
291
292
292
293
FILE option . . .
FROM option . .
IGNORE option .
INTO option . .
KEY option . . .
KEYFROM option .
KEYTO option . .
SET option . . .
Processing modes . .
Move mode . . .
Locate mode . .
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
293
293
293
294
294
295
295
296
296
296
296
This chapter describes features of the input and output statements used in
record-oriented data transmission. Those features of PL/I that apply generally to
record-oriented or stream-oriented data transmission, including declaring files, file
attributes, and opening and closing files, are described in Chapter 10, “Input and
output,” on page 275. For syntax information about the ENVIRONMENT attribute,
refer to “ENVIRONMENT attribute” on page 282. For details about environment
characteristics and record I/O data transmission statements for each data set
organization, refer to the Programming Guide.
In record-oriented data transmission, data in a data set is a collection of records
recorded in any format acceptable to the operating system. No data conversion is
performed during record-oriented data transmission. On input, the READ
statement either transmits a single record to a program variable exactly as it is
recorded in the data set, or sets a pointer to the record. On output, the WRITE,
REWRITE, or LOCATE statement transmits a single record from a program
variable exactly as it is recorded internally. If the information transmitted to the file
has a length N which is less than the established record length M, the resulting
value of the last M-N bytes of the record is undefined.
Data transmitted
Most variables, including parameters and DEFINED variables, can be transmitted
by record-oriented data transmission statements. In general, the information given
in this chapter can be applied equally to all variables.
Note: A data aggregate must be in connected storage. If a graphic string is
specified for input or output, the SCALARVARYING option must be
specified for the file. Other data considerations are described in the
following sections.
Unaligned bit strings
The following cannot be transmitted:
v BASED, DEFINED, parameter, subscripted, or structure-base-element variables
that are unaligned nonvarying bit strings
v Minor structures whose first or last base elements are unaligned nonvarying bit
strings (except where they are also the first or last elements of the containing
major structure)
v Major structures that have the DEFINED attribute or are parameters, and that
have unaligned nonvarying bit strings as their first or last elements.
© Copyright IBM Corp. 1999, 2012
289
Varying length strings
Varying length strings
A locate mode output statement (see “LOCATE statement” on page 292) specifying
a varying length string transmits a field having a length equal to the maximum
length of the string. For VARYINGZ strings, the null terminator is also transmitted.
For VARYING strings, a 2-byte prefix denoting the current length of the string is
also transmitted; for this, the SCALARVARYING option of the ENVIRONMENT
attribute must be specified for the file.
A move mode output statement (see “WRITE statement” on page 291 and
“REWRITE statement” on page 291) specifying a varying length string variable
transmits only the current length of the string. For VARYINGZ strings, the null
terminator is also transmitted. For VARYING strings, a 2-byte prefix is included
only if the SCALARVARYING option of the ENVIRONMENT attribute is specified
for the file.
Reading and writing using varying length strings allows you to access records that
can have undefined or unknown lengths.
Area variables
A locate mode output statement specifying an area variable transmits a field whose
length is the declared size of the area, plus a 16-byte prefix containing control
information.
A move mode statement specifying an element area variable or a structure whose
last element is an area variable transmits only the current extent of the area plus a
16-byte prefix.
Data transmission statements
The data transmission statements that transmit records to or from a data set are
READ, WRITE, LOCATE, and REWRITE. The DELETE statement deletes records
from an UPDATE file. The attributes of the file determine which data transmission
statements can be used. Statement options are described in “Options of data
transmission statements” on page 293. For information about variables in data
transmission statements, see the Programming Guide.
READ statement
The READ statement can be used with any INPUT or UPDATE file. It either
transmits a record from the data set to the program variable or sets a pointer to the
record in storage.
290
Enterprise PL/I for z/OS Language Reference
READ
IGNORE (expression)
READ FILE (file-reference)
INTO(ref)
KEY(expression)
KEYTO(reference)
SET(pointer-ref)
KEY(expression)
KEYTO(reference)
;
The keywords can appear in any order. A READ statement without an INTO, SET,
or IGNORE option is equivalent to a READ with an IGNORE(1).
WRITE statement
The WRITE statement can be used with SEQUENTIAL UPDATE files (if VSAM),
with DIRECT UPDATE files, and with any OUTPUT file. It transmits a record from
the program and adds it to the data set.
WRITE FILE (file-reference) FROM (reference)
;
KEYFROM(expression)
KEYTO(reference)
The keywords can appear in any order.
A WRITE statement cannot be used to update a consecutive data set accessed as a
SEQUENTIAL UPDATE file. In order to update a consecutive data set by a
SEQUENTIAL UPDATE file, you must retrieve a record with a READ statement
before you can update it via a REWRITE statement.
Also, if you want to add records to the end of an existing sequential file, it has to
be opened as OUTPUT and you must specify either DISP=MOD in its DD
statement (if running under z/OS batch) or APPEND(Y) in its environment
variable (if running under Windows, AIX or z/OS UNIX).
REWRITE statement
The REWRITE statement replaces a record in an UPDATE file. For SEQUENTIAL
UPDATE files, the REWRITE statement specifies that the last record read from the
file is rewritten; consequently a record must be read before it can be rewritten. For
DIRECT UPDATE files, any record can be rewritten whether or not it has first been
read.
Chapter 11. Record-oriented data transmission
291
REWRITE
REWRITE FILE (file-reference)
FROM
(reference)
;
KEY
(expression)
The keywords can appear in any order. The FROM option must be specified for
UPDATE files with the DIRECT attribute, or with both the SEQUENTIAL and
UNBUFFERED attributes.
A REWRITE statement that does not specify the FROM option has the following
effect:
v If the last record was read by a READ statement with the INTO option,
REWRITE without FROM has no effect on the record in the data set.
v If the last record was read by a READ statement with the SET option, the record
is updated by whatever assignments were made in the variable identified by the
pointer variable in the SET option.
LOCATE statement
The LOCATE statement can be used only with an OUTPUT SEQUENTIAL
BUFFERED file for locate mode processing. It allocates storage within an output
buffer for a based variable and sets a pointer to the location of the next record. For
further description of locate mode processing, see “Locate mode” on page 296.
LOCATE based-variable FILE (file-reference)
;
SET
(pointer-reference)
KEYFROM (expression)
The keywords can appear in any order.
based-variable
Must be an unsubscripted level-1 based variable.
DELETE statement
The DELETE statement deletes a record from an UPDATE file.
DELETE FILE (file-reference)
;
KEY
(expression)
The keywords can appear in any order. If the KEY option is omitted, the record to
be deleted is the last record that is read. No subsequent DELETE or REWRITE
statement without a KEY is allowed until another READ statement is processed. If
the KEY option is included, that record addressed by the key is deleted if found.
292
Enterprise PL/I for z/OS Language Reference
Options for data transmission statements
Options of data transmission statements
Options that are allowed for record-oriented data transmission statements differ
according to the attributes of the file and the characteristics of the associated data
set.
FILE option
The FILE option must appear in every record-oriented data transmission statement.
It specifies the file upon which the operation takes place. An example of the FILE
option is shown in each of the statements in this section. If the file specified is not
open in the current process, it is opened implicitly.
FROM option
The FROM option specifies the element or aggregate variable from which the
record is written. The FROM option must be used in the WRITE statement for any
OUTPUT or DIRECT UPDATE file. It can also be used in the REWRITE statement
for any UPDATE file.
If the variable is an aggregate, it must be in connected storage. Certain uses of
unaligned nonvarying bit strings are disallowed (for details, see “Data transmitted”
on page 289).
The FROM variable can be an element string variable of varying length. When
using a WRITE statement with the FROM option, only the current length of a
varying length string is transmitted to a data set. For a VARYINGZ string, the null
terminator is attached and also transmitted. For a VARYING string, a 2-byte prefix
specifying the length is attached only if the SCALARVARYING option of the
ENVIRONMENT attribute is specified for the file.
Records are transmitted as an integral number of bytes. If a bit string (or a
structure that starts or ends with a bit string) that is not aligned on a byte
boundary is transmitted, the record is padded with bits at the start or the end of
the string, and the result might be incorrect.
The FROM option can be omitted from a REWRITE statement for SEQUENTIAL
UPDATE files. If the last record was read by a READ statement with the INTO
option, REWRITE without FROM has no effect on the record in the data set. If the
last record was read by a READ statement with the SET option, the record
(updated by whatever assignments were made) is copied back onto the data set.
In the following examples, the statements specify that the value of the variable
Mas_Rec is written into the output file Master.
write file (Master) from (Mas_Rec);
The REWRITE statement specifies that Mas_Rec replaces the last record read from
an UPDATE file.
rewrite file (Master) from (Mas_Rec);
IGNORE option
The IGNORE option can be used in a READ statement for any SEQUENTIAL
INPUT or SEQUENTIAL UPDATE file.
Chapter 11. Record-oriented data transmission
293
IGNORE
The expression in the IGNORE option is evaluated and converted to an integer
value n. If n is greater than zero, n records are ignored. A subsequent READ
statement for the file will access the (n+1)th record. If n is less than 1, the READ
statement has no effect.
The following example specifies that the next three records in the file are to be
ignored:
read file (In) ignore (3);
INTO option
The INTO option specifies an element or aggregate variable into which the logical
record is read. The INTO option can be used in the READ statement for any
INPUT or UPDATE file.
If the variable is an aggregate, it must be in connected storage. Certain uses of
unaligned nonvarying bit strings are disallowed (for details, see “Data transmitted”
on page 289).
The INTO variable can be an element string variable of varying length. For
VARYINGZ strings, each record contains a null terminator. For VARYING strings,
if the SCALARVARYING option of the ENVIRONMENT attribute was specified for
the file, each record contains a 2-byte prefix that specifies the length of the string
data.
If SCALARVARYING was not declared on input, the string length is calculated
from the record length and attached as a 2-byte prefix (for VARYING strings). For
VARYING bit strings, this calculation rounds up the length to a multiple of 8 and
therefore the calculated length might be greater than the maximum declared
length.
The following example specifies that the next sequential record is read into the
variable RECORD_1:
read file (Detail) into (Record_1);
KEY option
The KEY option specifies a character, graphic or widechar key that identifies a
record. It can be used in a READ statement for an INPUT or UPDATE file, or in a
REWRITE statement for a DIRECT UPDATE file.
The KEY option applies only to KEYED files. The KEY option is required if the file
has the DIRECT attribute and optional if the file has the SEQUENTIAL and
KEYED attributes.
The expression in the KEY option is evaluated and, if not character, graphic or
widechar, is converted to a character value that represents a key. It is this character,
graphic or widechar value that determines which record is read.
The following example specifies that the record identified by the character value of
the variable Stkey is read into the variable Item:
read file (Stpck) into (Item) key (Stkey);
294
Enterprise PL/I for z/OS Language Reference
KEYFROM
KEYFROM option
The KEYFROM option specifies a character, graphic or widechar key that identifies
the record on the data set to which the record is transmitted. It can be used in a
WRITE statement for any KEYED OUTPUT or DIRECT UPDATE file, or in a
LOCATE statement.
The KEYFROM option applies only to KEYED files. The expression is evaluated
and, if not character, graphic or widechar, is converted to a character string and is
used as the key of the record when it is written.
Relative data sets can be created using the KEYFROM option. The record number
is specified as the key.
REGIONAL(1) data sets can be created using the KEYFROM option. The region
number is specified as the key.
For indexed data sets, KEYFROM specifies a recorded key whose length must be
equal to the key length specified for the data set.
The following example specifies that the value of Loanrec is written as a record in
the file Loans, and that the character string value of Loanno is used as the key with
which it can be retrieved:
write file (Loans) from (Loanrec) keyfrom (Loanno);
KEYTO option
The KEYTO option specifies the character, graphic or widechar variable to which
the key of a record is assigned. The KEYTO option can specify any string
pseudovariable other than STRING. It cannot specify a variable declared with a
numeric picture specification. The KEYTO option can be used in a READ statement
for a SEQUENTIAL INPUT or SEQUENTIAL UPDATE file.
The KEYTO option applies only to KEYED files.
Assignment to the KEYTO variable always follows assignment to the INTO
variable. If an incorrect key specification is detected, the KEY condition is raised.
The value assigned is as follows:
v For indexed data sets, the record key is padded or truncated on the right to the
declared length of the character variable.
v For relative data sets, a record number is converted to a character string with
leading zeros suppressed, truncated, or padded on the left to the declared length
of the character variable.
v For REGIONAL(1) data sets, the 8-character region-number, padded or truncated
on the left to the declared length of the character variable. If the character
variable is of varying length, any leading zeros in the region number are
truncated and the string length is set to the number of significant digits. An
all-zero region number is truncated to a single zero.
The KEY condition is not raised for this type of padding or truncation.
The following example specifies that the next record in the file Detail is read into
the variable Invntry, and that the key of the record is assigned to the variable
Keyfld:
read file (Detail) into (Invntry) keyto (Keyfld);
Chapter 11. Record-oriented data transmission
295
SET
SET option
The SET option can be used with a READ statement or a LOCATE statement. For
the READ statement, it specifies a pointer variable that is set to point to the record
read. For the LOCATE statement, it specifies a pointer variable that is set to point
to the next record for output.
If the SET option is omitted for the LOCATE statement, the pointer declared with
the record variable is set. If a VARYING string is transmitted, the
SCALARVARYING option must be specified for the file.
The following example specifies that the value of the pointer variable P is set to the
location in the buffer of the next sequential record:
read file (X) set (P);
Processing modes
Record-oriented data transmission has two modes of handling data:
Move mode
processes data by moving it into or out of the variable.
Locate mode
processes data while it remains in a buffer. The execution of a data
transmission statement assigns a pointer variable for the location of the
storage allocated to a record in the buffer. Locate mode is applicable only
to BUFFERED files.
The data transmission statements and options that you specify determine the
processing mode used.
Move mode
In move mode, a READ statement transfers a record from the data set to the
variable named in the INTO option. A WRITE or REWRITE statement transfers a
record from the variable named in the FROM option to the data set. The variables
named in the INTO and FROM options can be of any storage class.
The following is an example of move mode input:
Eof_In = ’0’b;
on endfile(In) Eof_In = ’1’B;
read file(In) into(Data);
do while (¬Eof_In);
.
.
.
/* process record */
read file(In) into(Data);
end;
Locate mode
Locate mode assigns to a pointer variable the location of the buffer. A based
variable described the record. The same data can be interpreted in different ways
by using different based variables. Locate mode can also be used to read
self-defining records, in which information in one part of the record is used to
indicate the structure of the rest of the record. For example, this information could
be an array bound or a code identifying which based structure should be used for
the attributes of the data.
296
Enterprise PL/I for z/OS Language Reference
Locate mode
A READ statement with a SET option sets the pointer variable in the SET option to
a buffer containing the record. The data in the record can then be referenced by a
based variable qualified with the pointer variable.
The pointer value is valid only until the execution of the next READ or CLOSE
statement that refers to the same file.
The pointer variable specified in the SET option or, if SET was omitted, the pointer
variable specified in the declaration of the based variable, is used. The pointer
value is valid only until the execution of the next LOCATE, WRITE, or CLOSE
statement that refers to the same file. It also initializes components of the based
variable that have been specified in REFER options.
The LOCATE statement sets a pointer variable to a large enough area where the
next record can be built.
After execution of the LOCATE statement, values can be assigned directly into the
based variables qualified by the pointer variable set by the LOCATE statement.
The following example shows locate mode input:
dcl 1 Data based(P),
2
.
.
.
;
on endfile(In);
read file(In) set(P);
do while (¬endfile(In));
.
.
.
/* process record */
read file(In) set(P);
end;
The following example shows locate mode output:
dcl 1 Data based(P);
2
.
.
.
;
do while (More_records_to_write);
locate Data file(Out);
.
.
.
/* build record */
end;
Chapter 11. Record-oriented data transmission
297
Locate mode
298
Enterprise PL/I for z/OS Language Reference
Chapter 12. Stream-oriented data transmission
Data transmission statements . . . .
GET statement . . . . . . . .
PUT statement . . . . . . . .
Options of data transmission statements
COPY option . . . . . . . .
Data specification options . . . .
FILE option . . . . . . . . .
LINE option . . . . . . . . .
PAGE option . . . . . . . .
SKIP option . . . . . . . . .
STRING option . . . . . . . .
Transmission of data-list items. . . .
Data-directed data specification . . .
Restrictions on data-directed data . .
Syntax of data-directed data . . .
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
300
300
300
301
301
302
303
304
304
304
305
306
307
307
308
GET data-directed . . . .
PUT data-directed . . . .
Edit-directed data specification
GET edit-directed . . . .
PUT edit-directed . . . .
Example 1 . . . . .
Example 2 . . . . .
Example 3 . . . . .
FORMAT statement . . .
List-directed data specification
Syntax of list-directed data .
GET list-directed . . . .
PUT list-directed . . . .
PRINT attribute . . . . .
DBCS data in stream I/O . .
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
308
310
311
313
313
314
314
314
315
315
315
316
317
318
319
This chapter describes the input and output statements used in stream-oriented
data transmission. Features that apply to stream-oriented and record-oriented data
transmission, including files, file attributes, and opening and closing files, are
described in Chapter 10, “Input and output,” on page 275.
Stream-oriented data transmission treats a data set as a continuous stream of data
values in character, graphic, or mixed character data form. Within a program,
record boundaries are generally ignored. However, a data set consists of a series of
lines of data, and each data set created or accessed by stream-oriented data
transmission has a line size associated with it. In general, a line is equivalent to a
record in the data set, but the line size does not necessarily equal the record size.
The stream-oriented data transmission statements can also be used for internal
data movement, by specifying the STRING option instead of specifying the FILE
option. Although the STRING option is not an input/output operation, its use is
described in this chapter.
Stream-oriented data transmission can be list-directed, data-directed, or
edit-directed.
List-directed data transmission
transmits the values of data-list items without your having to specify the
format of the values in the stream. The values are recorded externally as a
list of constants, separated by blanks or commas.
Data-directed data transmission
transmits the names of the data-list items, as well as their values, without
your having to specify the format of the values in the stream. The
GRAPHIC option of the ENVIRONMENT attribute must be specified if
any variable name contains a DBCS character, even if no DBCS data is
present.
Edit-directed data transmission
transmits the values of data-list items and requires that you specify the
format of the values in the stream. The values are recorded externally as a
string of characters or graphics to be treated character by character (or
graphic by graphic) according to a format list.
© Copyright IBM Corp. 1999, 2012
299
Stream-oriented data transmission
The following sections detail the data transmission statements and their options,
and how to specify the list-, data-, and edit-directed data. How to accommodate
double-byte characters is discussed in “DBCS data in stream I/O” on page 319.
Data transmission statements
Stream-oriented data transmission uses GET and PUT statements. Only consecutive
files can be processed with the GET and PUT statements.
The variables or pseudovariables to which data values are assigned, and the
expressions from which they are transmitted, are generally specified in a
data-specification with each GET or PUT statement. The statements can also
include options that specify the origin or destination of the data values or indicate
where they appear in the stream relative to the preceding data values. Options for
the stream-data transmission statements are described in “Options of data
transmission statements” on page 301.
GET statement
The GET statement is a STREAM input data transmission statement that can either:
v Assign data values from a data set to one or more variables
v Assign data values from a string to one or more variables.
For a stream input file, use the following syntax for the GET statement.
GET
FILE
(expression)
data-specification
;
COPY
SKIP
(file-reference)
(expression)
The keywords can appear in any order. The data specification must appear unless
the SKIP option is specified.
For transmission from a string, use this syntax for the GET statement.
GET STRING (expression) data-specification ;
If FILE or STRING option is not specified FILE(SYSIN) is assumed and SYSIN is
implicitly declared FILE STREAM INPUT EXTERNAL.
PUT statement
The PUT statement is a STREAM output data transmission statement that can:
v Transmit values to a stream output file
v Assign values to a character variable.
300
Enterprise PL/I for z/OS Language Reference
PUT
Use the following syntax of the PUT statement when dealing with stream output
files.
PUT
FILE
(file-reference)
data-specification
;
PAGE
LINE
(expression)
SKIP
LINE
(expression)
(expression)
The keywords can appear in any order. The data specification can be omitted only
if one of the control options (PAGE, SKIP, or LINE) appears.
For transmission to a character string, however, use this syntax of the PUT
statement.
PUT STRING (expression) data-specification ;
Options of data transmission statements
COPY option
The COPY option specifies that the source data stream is written on the specified
STREAM OUTPUT file without alteration. If no file reference is given, the default
is the output file SYSPRINT. Each new record in the input stream starts a new
record on the COPY file. For example:
get file(sysin) data(A,B,C) copy(DPL);
not only transmits the values assigned to A, B, and C in the input stream to the
variables with these names, but also writes them exactly as they appear in the
input stream, on the file DPL. Data values that are skipped on input, and not
transmitted to internal variables, copy intact into the output stream.
If a condition is raised during the execution of a GET statement with a COPY
option and an ON-unit is entered in which another GET statement is executed for
the same file, and if control is returned from the ON-unit to the first GET
statement, that statement executes as if no COPY option was specified. If, in the
ON-unit, a PUT statement is executed for the file associated with the COPY option,
the position of the data transmitted might not immediately follow the most
recently-transmitted COPY data item.
If the COPY option file is not open in the current program, the file is implicitly
opened in the program for stream output transmission.
Chapter 12. Stream-oriented data transmission
301
Data specification
Data specification options
Data specifications in GET and PUT statements specify the data to be transmitted.
(
data-list
)
LIST
DATA
,
(
EDIT
(
data-list-item
data-list
)
(
)
format-list
)
data-list:
,
data-list item
( data-list type-3-DO )
format-list:
,
format-item
n format-item
n (format-list)
If a GET or PUT statement includes a data list that is not preceded by one of the
keywords LIST, DATA, or EDIT, LIST is the default.
Important: In a statement without LIST, DATA, or EDIT preceding the data list,
the data list must immediately follow the GET or PUT keyword. Any
options required must be specified after the data list.
DATA
See “Data-directed data specification” on page 307.
EDIT
See “Edit-directed data specification” on page 311.
LIST
See “List-directed data specification” on page 315.
data-list item
On input, a data-list item for edit-directed and list-directed transmission can be
one of the following: an element, array, or structure variable. For a
data-directed data specification, a data-list item can be an element, array, or
structure variable. None of the names in a data-directed data list can be
subscripted or locator-qualified. However, qualified (that is, structure-member)
or string-overlay-defined names are allowed.
On output, a data list item for edit-directed and list-directed data specifications
can be an element expression, an array expression, or a structure expression.
302
Enterprise PL/I for z/OS Language Reference
Data specification
For a data-directed data specification, a data-list item can be an element, array,
or structure variable. It must not be locator-qualified. It can be qualified (that
is, a member of a structure) or string-overlay-defined.
The data types of a data-list item can be any computational data (as long it
does not have the CONSTANT or VALUE attribute), and in PUT statements,
the data type may also be POINTER. If the data type is non-computational,
then the contents of the item will be transmitted as if the item had been
specified by applying the HEX built-in function applied to the item (and for
PUT DATA, the hex value will be enclosed in quotes followed by a suffix of
BX).
An array or structure variable in a data-list is equivalent to n items in the data
list, where n is the number of element items in the array or structure. For
edit-directed transmission, each element item is associated with a separate use
of a data-format item.
data-list type-3-DO
The syntax for the Type 3 DO specification is described under “DO statement”
on page 207. Data list items with Type 3 DO specifications are not allowed in
data-directed data lists for GET statements.
When the last repetitive specification is completed, processing continues with
the next data-list item.
Each repetitive specification must be enclosed in parentheses, as shown in the
syntax diagram. If a data specification contains only a repetitive specification,
two sets of outer parentheses are required, since the data list is enclosed in
parentheses and the repetitive specification must have a separate set.
When repetitive specifications are nested, the rightmost DO is at the outer level
of nesting. For example:
get list (((A(I,J)
do I = 1 to 2)
do J = 3 to 4));
There are three sets of parentheses, in addition to the set used to delimit the
subscripts. The outermost set is the set required by the data specification. The
next set is that required by the outer repetitive specification. The third set of
parentheses is required by the inner repetitive specification.
This statement is equivalent in function to the following nested do-groups:
do J = 3 to 4;
do I = 1 to 2;
get list (A (I,J));
end;
end;
It assigns values to the elements of the array A in the following order:
A(1,3), A(2,3), A(1,4), A(2,4)
format list
For a description of the format list, see “Edit-directed data specification” on
page 311.
FILE option
The FILE option specifies the file upon which the operation takes place. It must be
a STREAM file. For information on how to declare a file type data item, see “Files”
on page 277.
Chapter 12. Stream-oriented data transmission
303
FILE
If neither the FILE option nor the STRING option appears in a GET statement, the
input file SYSIN is the default; if neither option appears in a PUT statement, the
output file SYSPRINT is the default.
LINE option
The LINE option can be specified only for PRINT files. The LINE option defines a
new current line for the data set. The expression is evaluated and converted to an
integer value, n. The new current line is the nth line of the current page. If at least
n lines have already been written on the current page or if n exceeds the limits set
by the PAGESIZE option of the OPEN statement, the ENDPAGE condition is
raised. If n is less than or equal to zero, a value of 1 is used. If n specifies the
current line, ENDPAGE is raised except when the file is positioned on column 1, in
which case the effect is the same as if a SKIP(0) option were specified.
The LINE option takes effect before the transmission of any values defined by the
data specification (if any). If both the PAGE option and the LINE option appear in
the same statement, the PAGE option is applied first. For example:
put file(List) data(P,Q,R) line(34) page;
prints the values of the variables P, Q, and R in data-directed format on a new
page, commencing at line 34.
For the effect of the LINE option when specified in the first GET statement
following the opening of the file, see “OPEN statement” on page 283.
For output to a terminal in interactive mode, the LINE option skips three lines.
PAGE option
The PAGE option can be specified only for PRINT files. It defines a new current
page within the data set. If PAGE and LINE appear in the same PUT statement,
the PAGE option is applied first. The PAGE option takes effect before the
transmission of any values defined by the data specification (if any).
The page remains current until the execution of a PUT statement with the PAGE
option, until a PAGE format item is encountered, or until the ENDPAGE condition
is raised, resulting in the definition of a new page. A new current page implies line
one.
For output to a terminal in interactive mode, the PAGE option skips three lines.
SKIP option
The SKIP option specifies a new current line (or record) within the data set. The
expression is evaluated and converted to an integer value, n. The data set is
positioned to the start of the nth line (record) relative to the current line (record). If
expression is not specified, the default is SKIP(1).
The SKIP option takes effect before the transmission of values defined by the data
specification (if any). For example:
put list(X,Y,Z) skip(3);
prints the values of the variables X, Y, and Z on the output file SYSPRINT
commencing on the third line after the current line.
304
Enterprise PL/I for z/OS Language Reference
SKIP
For non-PRINT files and input files, if the expression in the SKIP option is less
than or equal to zero, a value of 1 is used. For PRINT files, if n is less than or
equal to zero, the positioning is to the start of the current line.
For the effect of the SKIP option when specified in the first GET statement
following the opening of the file, see “OPEN statement” on page 283.
If fewer than n lines remain on the current page when a SKIP(n) is issued,
ENDPAGE is raised.
When printing at a terminal in conversational mode, SKIP(n) with n greater than 3
is equivalent to SKIP(3). No more than three lines can be skipped.
STRING option
The STRING option in GET and PUT statements transmits data between main
storage locations rather than between the main and a data set. DBCS data items
cannot be used with the STRING option.
The GET statement with the STRING option specifies that data values assigned to
the data list items are obtained from the expression, after conversion to character
string. Each GET operation using this option always begins at the leftmost
character position of the string. If the number of characters in this string is less
than the total number of characters specified by the data specification, the ERROR
condition is raised.
The PUT statement with the STRING option specifies that values of the data-list
items are to be assigned to the specified character variable or pseudovariable. The
PUT operation begins assigning values at the leftmost character position of the
string, after appropriate conversions are performed. Blanks and delimiters are
inserted as in normal I/O operations. If the string is not long enough to
accommodate the data, the ERROR condition is raised.
The NAME condition is not raised for a GET DATA statement with the STRING
option. Instead, the ERROR condition is raised for situations that raise the NAME
condition for a GET DATA statement with the FILE option.
The following restrictions apply to the STRING option:
v The COLUMN control format option cannot be used with the STRING option.
v No pseudovariables are allowed in the STRING option of a PUT statement.
The STRING option is most useful with edit-directed transmission. It allows data
gathering or scattering operations performed with a single statement, and it allows
stream-oriented processing of character strings that are transmitted by
record-oriented statements.
For example:
read file (Inputr) into (Temp);
get string(Temp) edit (Code) (F(1));
If Code = 1 then
get string (Temp) Edit (X,Y,Z)
(X(1), 3 F(10,4));
The READ statement reads a record from the input file Inputr. The first GET
statement uses the STRING option to extract the code from the first byte of the
record and assigns it to Code. If the code is 1, the second GET statement uses the
Chapter 12. Stream-oriented data transmission
305
STRING
STRING option to assign the values in the record to X, Y, and Z. The second GET
statement specifies that the first character in the string Temp is ignored (the X(1)
format item in the format list). This ignored character is the same one assigned to
Code by the first GET statement.
An example of the STRING option in a PUT statement is:
put string (Record) edit
(Name)
(X(1), A(12))
(Pay#)
(X(10), A(7))
(Hours*Rate) (X(10), P’$999V.99’);
write file (Outprt) from (Record);
The PUT statement specifies, by the X(1) spacing format item, that the first
character assigned to the character variable is a single blank, which is the ANS
vertical carriage positioning character that specifies a single space before printing.
Following that, the values of the variables Name and Pay# and of the expression
Hours*Rate are assigned. The WRITE statement specifies that record transmission is
used to write the record into the file Outprt.
The variable referenced in the STRING option should not be referenced by name or
by alias in the data list. For example:
declare S char(8) init(’YYMMDD’);
put string (S) edit
(substr (S, 3, 2), ’/’,
substr (S, 5, 2), ’/’,
substr (S, 1, 2))
(A);
The value of S after the PUT statement is 'MM/bb/MM' and not 'MM/DD/YY'
because S is blanked after the first data item is transmitted. The same effect is
obtained if the data list contains a variable based or defined on the variable
specified in the STRING option.
Transmission of data-list items
If a data-list item is of complex mode, the real part is transmitted before the
imaginary part.
If a data-list item is an array expression, the elements of the array are transmitted
in row-major order; that is, with the rightmost subscript of the array varying most
frequently.
If a data-list item is a structure expression, the elements of the structure are
transmitted in the order specified in the structure declaration.
For example, the statements
declare 1 A (10),
2 B,
2 C;
put file(X) list(A);
result in the output being ordered as follows:
A.B(1) A.C(1) A.B(2) A.C(2) A.B(3)
A.C(3)...
If, however, the declaration is:
306
Enterprise PL/I for z/OS Language Reference
Transmission of data-list items
declare 1 A,
2 B(10),
2 C(10);
the same PUT statement results in the output ordered as follows:
A.B(1) A.B(2) A.B(3) ... A.B(10)
A.C(1) A.C(2) A.C(3) ... A.C(10)
If an input statement for list- or edit-directed transmission assigns a value to a
variable in a data list, the assigned value is used if the variable appears in a later
reference in the data list. For example:
get list (N,(X(I) do I=1 to N),J,K,);
substr (Name, J,K));
When this statement is executed, values are transmitted and assigned in the
following order:
1. A new value is assigned to N.
2. Elements are assigned to the array X as specified in the repetitive specification
in the order X(1),X(2),...X(N), with the new value of N specifying the
number of assigned items.
3. A new value is assigned to J.
4. A new value is assigned to K.
Data-directed data specification
For a description of the syntax of the DATA data specification, refer to “Data
specification options” on page 302.
Names of structure elements in the data-list item need only have enough
qualification to resolve any ambiguity. Full qualification is not required.
Omission of the data list results in a default data list that contains all
computational variables that could be named in a data-directed statement.
On output, all items in the data list are transmitted.
Restrictions on data-directed data
Subscripted variables are not allowed in data-directed input.
References to based variables in a data-list for data-directed input/output cannot
be explicitly locator qualified. For example:
dcl Y based(Q), Z based;
put data(Y);
The variable Z cannot be transmitted since it must be explicitly qualified by a
locator.
A based variable in the data-list has the following restrictions:
v The variable must not be based on an OFFSET variable.
v The pointer on which the variable is based must not be in DEFINED storage.
v If the pointer on which the variable is based is itself BASED, then the chain of
basing pointers must end with a pointer that is neither BASED nor DEFINED.
Chapter 12. Stream-oriented data transmission
307
Data-directed data specification
A defined variable in the data-list must:
v Be a picture or character variable
v Not be defined on a controlled variable
v Not be defined on an element or cross section of an array
v Not be defined with a nonconstant POSITION attribute
Typed structures can not be used in data-directed input/output statements.
Syntax of data-directed data
The stream associated with data-directed data transmission is in the form of a list
of element assignments. The element assignments that have optionally signed
constants, like variable names and equal signs, are in character or graphic form.
,
b
element-variable
=
data-value
;
On input, the element assignments can be separated by either a blank or a comma.
Blanks can surround periods in qualified names, subscripts, subscript parentheses,
and the assignment symbols. On output, the assignments are separated by a blank.
For PRINT files, items are separated according to program tab settings.
Each data-value in the stream has one of the syntaxes described for list-directed
transmission. For a description of list-directed transmission syntax, refer to “Syntax
of list-directed data” on page 315.
The length of the data value in the stream is a function of the attributes declared
for the variable and, because the name is also included, the length of the fully
qualified subscripted name. The length for output items converted from coded
arithmetic data, numeric character data, and bit-string data is the same as that for
list-directed output data, and is governed by the rules for data conversion to
character type as described in Chapter 4, “Data conversion,” on page 73.
Qualified names in the input stream must be fully qualified.
Interleaved subscripts cannot appear in qualified names in the stream. For
example, assume that Y is declared as follows:
declare 1 Y(5,5),
2 A(10),
3 B,
3 C,
3 D;
An element name has to appear in the stream as follows:
Y.A.B(2,3,8)= 8.72
GET data-directed
For more information about the GET statement, see “GET statement” on page 300.
308
Enterprise PL/I for z/OS Language Reference
GET data-directed
If a data list is used, each data-list item must be an element, array, or structure
variable. Names cannot be subscripted, but qualified names are allowed in the data
list. All names in the stream should appear in the data list; however, the order of
the names need not be the same, and the data list can include names that do not
appear in the stream.
If the data list contains a name that is not included in the stream, the value of the
named variable remains unchanged.
If the stream contains an unrecognizable element-variable or a name that does not
have a counterpart in the data list, the NAME condition is raised.
Transmission ends when a semicolon that is not enclosed in quotation marks or an
end-of-file is reached. The recognition of the semicolon or end-of-file determines
the number of element assignments that are actually transmitted by a particular
statement, whether or not a data list is specified.
For example, consider the following data list, where A, B, C, and D are names of
element variables:
Data (B, A, C, D)
This data list can be associated with the following input data stream:
A= 2.5, B= .0047, D= 125, Z= ’ABC’;
Because C appears in the data list but not in the stream, its value remains
unaltered. Z, which is not in the data list, raises the NAME condition.
If the data list includes the name of an array, subscripted references to that array
can appear in the stream although subscripted names cannot appear in the data
list. The entire array need not appear in the stream; only those elements that
actually appear in the stream are assigned. If a subscript is out of range, or is
missing, the NAME condition is raised.
For example:
declare X (2,3);
Consider the following data list and input data stream:
Data Specification
data (X)
Input Data Stream
X(1,1)= 7.95,
X(1,2)= 8085,
X(1,3)= 73;
Although the data list has only the name of the array, the input stream can contain
values for individual elements of the array. In this case, only three elements are
assigned; the remainder of the array is unchanged.
If the data list includes the names of structures, minor structures, or structure
elements, fully qualified names must appear in the stream, although full
qualification is not required in the data list. For example:
dcl 1 In,
2 Partno,
2 Descrp,
2 Price,
3 Retail,
3 Whsl;
Chapter 12. Stream-oriented data transmission
309
GET data-directed
If it is desired to read a value for In.Price.Retail, the input data stream must
have the following form:
In.Price.Retail=1.23;
The data specification can be any of:
data(In)
data(Price)
data(In.Price)
data(Retail)
data(Price.Retail)
data(In.Retail)
data(In.Price.Retail)
PUT data-directed
For more information about the PUT statement, see “PUT statement” on page 300.
A data-list item can be an element, array, or structure variable, or a repetitive
specification. The names appearing in the data list, together with their values, are
transmitted in the form of a list of element assignments separated by blanks and
terminated by a semicolon. For PRINT files, items are separated according to
program tab settings; see “PRINT attribute” on page 318.
A semicolon is written into the stream after the last data item transmitted by each
PUT statement.
Names are transmitted as a mixed string, which can contain SBCS and/or DBCS
characters. Any SBCS characters expressed in DBCS form are first translated to
SBCS. For example:
put data (<.A>B<.Ckk>);
would be transmitted as:
ABC<kk>=value-of-variable
Note: In the previous example, <.A>B<.Ckk> is a scalar variable.
Data-directed output is not valid for subsequent data-directed input when the
character-string value of a numeric character variable does not represent a valid
optionally signed arithmetic constant, or a complex expression.
For character data, the contents of the character string are written out enclosed in
quotation marks. Each quotation mark contained within the character string is
represented by two successive quotation marks.
The following example shows data-directed transmission (both input and output):
declare (A(6), B(7)) fixed;
get file (X) data (B);
do I = 1 to 6;
A (I) = B (I+1) + B (I);
end;
put file (Y) data (A);
input stream:
B(1)=1, B(2)=2, B(3)=3,
B(4)=1, B(5)=2, B(6)=3, B(7)=4;
output stream:
310
Enterprise PL/I for z/OS Language Reference
PUT data-directed
A(1)= 3 A(2)= 5 A(3)= 4 A(4)= 3
A(5)= 5 A(6)= 7;
In the following example:
dcl 1 A,
2 B FIXED,
2 C,
3 D FIXED;
A.B = 2;
A.D = 17;
put data (A);
The data fields in the output stream are as follows:
A.B= 2 A.C.D= 17;
Edit-directed data specification
For information on the syntax of the EDIT data specification, refer to “Data
specification options” on page 302.
,
n
format-item
n format-item
n (format-list)
Specifies an iteration factor, which is either an expression enclosed in
parentheses or an integer. If it is the latter, a blank must separate the integer
and the following format item.
The iteration factor specifies that the associated format item or format list is
used n successive times. A zero or negative iteration factor specifies that the
associated format item or format list is skipped and not used (the data-list item
is associated with the next data-format item).
If an expression is used to represent the iteration factor, it is evaluated and
converted to an integer, once for each set of iterations.
The associated format item or format list is that item or list of items
immediately to the right of the iteration factor.
format item
Specifies either a data-format item, a control-format item, or the remote format
item. Syntax and detailed discussions of the format items appear in Chapter 13,
“Edit-directed format items,” on page 321.
Data-format items
describe the character or graphic representation of a single data item. They
are:
A
character
B
bit
C
complex
E
floating point
F
fixed point
G
graphic
L
line
Chapter 12. Stream-oriented data transmission
311
Edit-directed data specification
P
V
picture
view a line
Control-format items
specify the layout of the data set associated with a file. They are:
COLUMN
LINE
PAGE
SKIP
X
Remote-format item
specifies a label reference whose value is the label constant of a FORMAT
statement located elsewhere. The FORMAT statement contains the remotely
situated format items. The label reference item is:
R(label-reference)
Where label is the label constant name of the FORMAT statement. For
information on specifying the R-format item, see “R-format item” on
page 330.
The first data-format item is associated with the first data-list item, the second
data-format item with the second data-list item, and so on. If a format list contains
fewer data-format items than there are items in the associated data list, the format
list is reused. If there are excessive format items, they are ignored.
Suppose a format list contains five data-format items and its associated data list
specifies ten items to be transmitted. The sixth item in the data list is associated
with the first data-format item, and so forth. Suppose a format list contains ten
data-format items and its associated data list specifies only five items. The sixth
through the tenth format items are ignored.
If a control-format item is encountered, the control action is executed.
The PAGE and LINE control-format items can be used only with PRINT files and,
consequently, can appear only in PUT statements. The SKIP, COLUMN, and
X-format items apply to both input and output.
The PAGE, SKIP, and LINE format items have the same effect as the corresponding
options of the PUT statement (and of the GET statement, in the case of SKIP),
except that the format items take effect when they are encountered in the format
list, while the options take effect before any data is transmitted.
The COLUMN format item cannot be used in a GET STRING or PUT STRING
statement.
For the effects of control-format items when specified in the first GET or PUT
statement following the opening of a file, see “OPEN statement” on page 283.
A value read into a variable can be used in a format item that is associated with
another variable later in the data list.
get edit (M,String_A,I,String_B)(F(2),A(M),X(M),F(2),A(I));
In this example, the first two characters are assigned to M. The value of M specifies
the number of characters assigned to String_A and the number of characters being
ignored before two characters are assigned to I, whose value is used to specify the
number of characters assigned to String_B.
312
Enterprise PL/I for z/OS Language Reference
Edit-directed data specification
The value assigned to a variable during an input operation can be used in an
expression in a format item that is associated with a later data item. An expression
in a format item is evaluated and converted to an integer each time the format
item is used.
The transmission is complete when the last data-list item has been processed.
Subsequent format items, including control-format items, are ignored.
GET edit-directed
For more information about the GET statement, see “GET statement” on page 300.
Data in the stream is a continuous string of characters and graphics with no
delimiters between successive values. The number of characters for each data value
is specified by a format item in the format list. The characters are interpreted
according to the associated format item. When the data list has been processed,
execution of the GET statement stops and any remaining format items are not
processed.
Each data-format item specifies the number of characters or graphics to be
associated with the data-list item and how to interpret the data value. The data
value is assigned to the associated data-list item, with any necessary conversion.
Fixed-point binary and floating-point binary data values must always be
represented in the input stream with their values expressed in decimal digits. The
F-, P-, and E-format items can then be used to access them, and the values are
converted to binary representation upon assignment.
All blanks and quotation marks are treated as characters in the stream. Strings
should not be enclosed in quotation marks. Quotation marks should not be
doubled. The letter B should not be used to identify bit strings or G to identify
graphic strings. If characters in the stream cannot be interpreted in the manner
specified, the CONVERSION condition is raised.
Example:
get edit (Name, Data, Salary)(A(N), X(2), A(6), F(6,2));
This example specifies the following:
v The first N characters in the stream are treated as a character string and assigned
to Name.
v The next two characters are skipped.
v The next six characters are assigned to Data in character format.
v The next six characters are considered an optionally signed decimal fixed-point
constant and assigned to Salary.
PUT edit-directed
For more information about the PUT statement, see “PUT statement” on page 300.
The value of each data-list item is converted to the character or graphic
representation specified by the associated data-format item and placed in the
stream in a field whose width also is specified by the format item. When the data
list has been processed, execution of the PUT statement stops and any remaining
format items are not processed.
Chapter 12. Stream-oriented data transmission
313
PUT edit-directed
On output, binary items are converted to decimal values and the associated F- or
E-format items must state the field width and point placement in terms of the
converted decimal number. For the P-format these are specified by the picture
specification.
On output, blanks are not inserted to separate data values in the output stream.
String data is left-adjusted in the field to the width specified. Arithmetic data is
right-adjusted. Because of the rules for conversion of arithmetic data to character
type which can cause up to 3 leading blanks to be inserted (in addition to any
blanks that replace leading zeros), generally there is at least 1 blank preceding an
arithmetic item in the converted field. Leading blanks do not appear in the stream,
however, unless the specified field width allows for them. Truncation, due to
inadequate field-width specification, is on the left for arithmetic items, and on the
right for string items. SIZE or STRINGSIZE is raised if truncation occurs.
Example 1
put edit(’Inventory=’{Inum,Invcode)(A,F(5));
This example specifies that the character string ’Inventory=’ is concatenated with
the value of Inum and placed in the stream in a field whose width is the length of
the resultant string. Then the value of Invcode is converted to character, as
described by the F-format item, and placed in the stream right-adjusted in a field
with a width of five characters (leading characters can be blanks).
Example 2
The following example shows the use of the COLUMN, LINE, PAGE, and SKIP
format items in combination with one another:
put edit (’Quarterly Statement’)
(page, line(2), A(19))(Acct#, Bought, Sold, Payment, Balance)
(skip(3), A(6), column(14), F(7,2), column(30), F(7,2),
column(45), F(7,2), column(60), F(7,2));
This PUT statement specifies the following:
1. The heading Quarterly Statement is written on line two of a new page in the
output file SYSPRINT.
2. Two lines are skipped. The next line in the output is the third line following the
heading, or the fifth line of the report.
3. The following values are written:
Acct#, beginning at character position 1
Bought, beginning at character position 14
Sold, beginning at character position 30
Payment, beginning at character position 45
Balance at character position 60.
Example 3
In the following example, the value of Name is inserted in the stream as a character
string left-adjusted in a field of N characters.
put edit (Name,Number,City) (A(N),A(N-4),A(10));
Number is left-adjusted in a field of N-4 characters; and City is left-adjusted in a
field of 10 characters.
314
Enterprise PL/I for z/OS Language Reference
FORMAT
FORMAT statement
The FORMAT statement specifies a format list that can be used by edit-directed
data transmission statements to control the format of the data being transmitted.
label:
FORMAT (format-list) ;
label
Same as the label-reference of the remote-format item, R, discussed in
“R-format item” on page 330.
format list
Specified as described under “Edit-directed data specification” on page 311.
A GET or PUT EDIT statement can include an R-format item in its format-list
option. That portion of the format list represented by the R-format item is supplied
by the identified FORMAT statement.
A condition prefix associated with a FORMAT statement is not allowed.
List-directed data specification
For information on the syntax of the LIST data specification, refer to “Data
specification options” on page 302.
Examples of list-directed data specifications are:
list (Card_Rate, Dynamic_Flow)
list ((Thickness(Distance)
do Distance = 1 to 1000))
list (P, Z, M, R)
list (A*B/C, (X+Y)**2)
The specification in the last example can be used only for output, since it contains
expressions. These expressions are evaluated when the statement is executed, and
the result is placed in the stream.
Syntax of list-directed data
Data values in the stream, either input or output, are character or graphic
representations.
Chapter 12. Stream-oriented data transmission
315
Syntax of list-directed data
arithmetic-constant
+
real-constant
+
character-constant
bit-constant
graphic-constant
+
-
imaginary-constant
String repetition factors are not allowed. A blank must not follow a sign preceding
a real constant, and must not precede or follow the central positive (+) or negative
(-) symbol in complex expressions.
The length of the data value in the stream is a function of the attributes of the data
value, including precision and length. Detailed discussions of the conversion rules
and their effect upon precision are listed in the descriptions of conversion to
character type in Chapter 4, “Data conversion,” on page 73.
GET list-directed
For information about the GET statement, see “GET statement” on page 300.
On input, data values in the stream must be separated either by a blank or by a
comma. This separator can be surrounded by one or more blanks. A null field in
the stream is indicated either by the first nonblank character in the data stream
being a comma, or by two commas separated by an arbitrary number of blanks. A
null field specifies that the value of the associated data-list item remains
unchanged.
Transmission of the list of constants or complex expressions on input is terminated
by expiration of the list or at the end-of-file. For transmission of constants, the file
is positioned in the stream ready for the next GET statement.
If the items are separated by a comma, the first character scanned when the next
GET statement is executed is the one immediately following the comma:
Xbb,bbbXX
—
If the items are separated by blanks only, the first item scanned is the next
nonblank character:
XbbbbXXX
—
unless the end-of-record is encountered, in which case the file is positioned at the
end of the record:
Xbb–bbXXX
—
However, if the end-of-record immediately follows a nonblank character (other
than a comma), and the following record begins with blanks, the file is positioned
at the first nonblank character in the following record:
X–bbbXXX
—
316
Enterprise PL/I for z/OS Language Reference
GET list-directed
If the record does terminate with a comma, the next record is not read until the
next GET statement requires it.
If the data is a character constant, the surrounding quotation marks are removed,
and the enclosed characters are interpreted as a character string. A double
quotation mark is treated as a single quotation mark.
If the data is a bit constant, the enclosing quotation marks and the trailing
character B are removed, and the enclosed characters are interpreted as a bit string.
If the data is a hexadecimal constant (X, BX, B4, GX), the enclosing quotation
marks and the suffix are removed, and the enclosed characters are interpreted as a
hexadecimal representation of a character, bit, or graphic string.
If the data is a mixed constant, the enclosing quotation marks and the suffix M are
removed, and the enclosed constant is interpreted as a character string.
If the data is a graphic constant, the enclosing quotation marks and the trailing
character G are removed, and the enclosed graphics are interpreted as a graphic
string.
If the data is an arithmetic constant or complex expression, it is interpreted as
coded arithmetic data with the base, scale, mode, and precision implied by the
constant or by the rules for expression evaluation.
PUT list-directed
For more information about the PUT statement, see “PUT statement” on page 300.
The values of the data-list items are converted to character representations (except
for graphics) and transmitted to the data stream. A blank separates successive data
values transmitted. For PRINT files, items are separated according to program tab
settings (see “PRINT attribute” on page 318).
Arithmetic values are converted to character.
Binary data values are converted to decimal notation before being placed in the
stream.
For numeric character values, the character value is transmitted.
Bit strings are converted to character strings. The character string is enclosed in
quotation marks and followed by the letter B.
Character strings are written out as follows:
v If the file does not have the attribute PRINT, enclosing quotation marks are
supplied, and contained single quotation marks or apostrophes are replaced by
two quotation marks. The field width is the current length of the string plus the
number of added quotation marks.
v If the file has the attribute PRINT, enclosing quotation marks are not supplied,
and contained single quotation marks or apostrophes are unmodified. The field
width is the current length of the string.
Mixed strings are written out as follows:
v If the file does not have the attribute PRINT, SBCS quotation marks and the
letter M are supplied. Contained SBCS quotes are replaced by two quotes.
Chapter 12. Stream-oriented data transmission
317
PUT list-directed
v If the file has the attribute PRINT, the enclosing quotation marks and letter M
are not supplied, and contained single quotation marks are unmodified.
Graphic strings are written out as follows:
v If the file does not have the attribute PRINT, SBCS quotation marks, and the
letter G are supplied. Because the enclosing quotation marks are SBCS,
contained graphic quotation marks are represented by a single graphic quotation
mark (unmodified).
v If the file has the attribute PRINT, the enclosing quotation marks and letter G
are not supplied, and graphic quotation marks are represented by a single
graphic quotation mark (unmodified).
PRINT attribute
The PRINT attribute applies to files with the STREAM and OUTPUT attributes. It
indicates that the file is intended to be printed; that is, the data associated with the
file is to appear on printed pages, although it can first be written on some other
medium.
PRINT
When PRINT is specified, the first data byte of each record of a PRINT file is
reserved for an American National Standard (ANS) printer control character. The
control characters are inserted by PL/I.
Data values transmitted by list- and data-directed data transmission are
automatically aligned on the left margin and on implementation-defined preset tab
positions.
The layout of a PRINT file can be controlled by the use of the options and format
items listed in Table 34.
Table 34. Options and format items for PRINT files
Statement
Statement
Option
Edit directed
format item
OPEN
OPEN
PUT
PUT
PUT
PUT
LINESIZE(n)
PAGESIZE(n)
PAGE
LINE(n)
SKIP[(n)]
–
–
–
PAGE
LINE(n)
SKIP[(n)]
COLUMN(n)
PUT
–
X(n)
Effect
Established line width
Establishes page length
Skip to new page
Skip to specified line
Skip specified number of lines
Skip to specified character position
in line
Places blank characters in line to
establish position.
LINESIZE and PAGESIZE establish the dimensions of the printed area of the page,
excluding footings. The LINESIZE option specifies the maximum number of
characters included in each printed line. If it is not specified for a PRINT file, a
default value of 120 characters is used. There is no default for a non-PRINT file.
318
Enterprise PL/I for z/OS Language Reference
PRINT
The PAGESIZE option specifies the maximum number of lines in each printed
page; if it is not specified, a default value of 60 lines is used. For example:
open file(Report) output stream print PAGESIZE(55) LINESIZE(110);
on endpage(Report) begin;
put file(Report) skip list (Footing);
Pageno = Pageno + 1;
put file(Report) page list (’Page ’||Pageno);
put file(Report) skip (3);
end;
The OPEN statement opens the file Report as a PRINT file. The specification
PAGESIZE(55) indicates that each page contains a maximum of 55 lines. An
attempt to write on a page after 55 lines have already been written (or skipped)
raises the ENDPAGE condition. The implicit action for the ENDPAGE condition is
to skip to a new page, but you can establish your own action through use of the
ON statement, as shown in the example.
LINESIZE(110) indicates that each line on the page can contain a maximum of 110
characters. An attempt to write a line greater than 110 characters places the excess
characters on the next line.
When an attempt is made to write on line 56 (or to skip beyond line 55), the
ENDPAGE condition is raised, and the begin-block shown here is executed. The
ENDPAGE condition is raised only once per page. Consequently, printing can be
continued beyond the specified PAGESIZE after the ENDPAGE condition has been
raised. This can be useful, for example, if you want to write a footing at the
bottom of each page.
The first PUT statement specifies that a line is skipped, and the value of Footing,
presumably a character string, is printed on line 57 (when ENDPAGE is raised, the
current line is always PAGESIZE+1). The page number, Pageno, is incremented, the
file Report is set to the next page, and the character constant ’Page’ is
concatenated with the new page number and printed. The final PUT statement
skips three lines, so that the next printing is on line 4. Control returns from the
begin-block to the PUT statement that raised the ENDPAGE condition. However,
any SKIP or LINE option specified in that statement has no further effect.
DBCS data in stream I/O
If DBCS data is used in list-directed or data-directed transmission, the GRAPHIC
option of the ENVIRONMENT attribute must be specified for that file. It also must
be specified if data-directed transmission uses DBCS names even though no DBCS
data is present. DBCS continuation rules are applied and are the same rules as
those described in “DBCS continuation rules” on page 13. For information on how
graphics are handled for edit-directed transmission, see “Edit-directed data
specification” on page 311.
Chapter 12. Stream-oriented data transmission
319
320
Enterprise PL/I for z/OS Language Reference
Chapter 13. Edit-directed format items
A-format item .
B-format item .
C-format item .
COLUMN format
E-format item .
F-format item .
G-format item .
L-format item .
. .
. .
. .
item
. .
. .
. .
. .
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
321
322
322
323
324
326
328
328
LINE format item .
P-format item . .
PAGE format item .
R-format item . .
Example . . .
SKIP format item .
V-format item . .
X-format item . .
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
329
329
330
330
330
331
331
332
This chapter describes each of the edit-directed format items that can appear in the
format list of a GET, PUT, or FORMAT statement. (See also “Edit-directed data
specification” on page 311.) The format items are described in alphabetic order.
A-format item
The character (or A) format item describes the representation of a character value.
A
(field-width)
field-width
Specifies the number of character positions in the data stream that contain (or
will contain) the string. It is an expression that is evaluated and converted to
an integer value, which must be nonnegative, each time the format item is
used.
If an A-format item is specified without a length in a GET EDIT statement, the
compiler issues a warning message and treats it as an L-format item (rather than
issuing an error message and assigning it a length of 1).
On input, the specified number of characters is obtained from the data stream and
assigned, with any necessary conversion, truncation, or padding, to the data-list
item. The field width is always required on input and, if it is zero, a null string is
obtained. If quotation marks appear in the stream, they are treated as characters in
the string.
Consider the following example:
get file (Infile) edit (Item) (A(20));
The GET statement assigns the next 20 characters in Infile to Item. The value is
converted from its character representation specified by the format item A(20), to
the representation specified by the attributes declared for Item.
On output, the data-list item is converted, if necessary, to a character string and is
truncated or extended with blanks on the right to the specified field-width before
being placed into the data stream. If the field-width is zero, no characters are
placed into the data stream. Enclosing quotation marks are never inserted, nor are
contained quotation marks doubled. If the field width is not specified, the default
© Copyright IBM Corp. 1999, 2012
321
A-format
is equal to the character-string length of the data-list item (after conversion, if
necessary, according to the rules given in Chapter 4, “Data conversion,” on page
73).
B-format item
The bit (or B) format item describes the character representation of a bit value.
Each bit is represented by the character zero or one.
B
(field-width)
field-width
Specifies the number of data-stream character positions that contain (or will
contain) the bit string. It is an expression that is evaluated and converted to an
integer value, which must be nonnegative, each time the format item is used.
On input, the character representation of the bit string can occur anywhere within
the specified field. Blanks, which can appear before and after the bit string in the
field, are ignored. Any necessary conversion occurs when the bit string is assigned
to the data-list item. The field width is always required on input, and if it is zero, a
null string is obtained. Any character other than 0 or 1 in the string, including
embedded blanks, quotation marks, or the letter B, raises the CONVERSION
condition.
On output, the character representation of the bit string is left-adjusted in the
specified field, and necessary truncation or extension with blanks occurs on the
right. Any necessary conversion to bit-string is performed. No quotation marks are
inserted, nor is the identifying letter B. If the field width is zero, no characters are
placed into the data stream. If the field width is not specified, the default is equal
to the bit-string length of the data-list item (after conversion, if necessary,
according to the rules given in Chapter 4, “Data conversion,” on page 73).
In the example:
declare Mask bit(25);
put file(Maskfle) edit (Mask) (B);
The PUT statement writes the value of Mask in Maskfle as a string of 25 characters
consisting of zeros and ones.
C-format item
The complex (or C) format item describes the character representation of a complex
data value. You use one real-format-item to describe both the real and imaginary
parts of the complex data value in the data stream.
C (real-format-item)
322
Enterprise PL/I for z/OS Language Reference
C-format
real-format-item
Specified by one of the F-, E-, or P-format items. The P-format item must
describe numeric character data.
On input, the letter I in the input raises the CONVERSION condition.
On output, the letter I is never appended to the imaginary part. If the second real
format item (or the first, if only one appears) is an F or E item, the sign is
transmitted only if the value of the imaginary part is less than zero. If the real
format item is a P item, the sign is transmitted only if the S or - or + picture
character is specified.
If you require an I to be appended, it must be specified as a separate data item in
the data list, immediately following the variable that specifies the complex item.
The I, then, must have a corresponding format item (either A or P). If a second real
format item is specified, it is ignored.
COLUMN format item
The COLUMN format item positions the file to a specified character position
within the current or following line.
COLUMN (character-position)
character-position
Specifies an expression which is evaluated and converted to an integer value,
which must be nonnegative, each time the format item is used.
The file is positioned to the specified character position in the current line,
provided it has not already passed this position. If the file is already positioned
after the specified character position, the current line is completed and a new line
is started; the format item is then applied to the following line.
Then, if the specified character position lies beyond the rightmost character
position of the current line, or if the value of the expression for the character
position is less than one, the default character position is one.
The rightmost character position is determined as follows:
v For output files, it is determined by the line size.
v For input files, it is determined using the length of the current logical record to
determine the line size and, hence, the rightmost character position.
COLUMN must not be used in a GET STRING or PUT STRING statement.
COLUMN cannot be used with input or output lines that contain graphics or
widechars.
On input, intervening character positions are ignored.
On output, intervening character positions are filled with blanks.
Chapter 13. Edit-directed format items
323
E-format
E-format item
The floating-point (or E) format item describes the character representation of a
real floating-point decimal arithmetic data value.
E (
field-width,fractional-digits
)
,significant-digits
field-width
Specifies the total number of characters in the field. It is evaluated and
converted to an integer value w each time the format item is used. w must be
nonnegative.
fractional-digits
Specifies the number of digits in the mantissa that follow the decimal point. It
is evaluated and converted to an integer value d each time the format item is
used. d must be nonnegative.
significant-digits
Specifies the number of digits that must appear in the mantissa. It is evaluated
and converted to an integer value s each time the format item is used. s must
be nonnegative.
In PUT statements, if w is positive, p is the maximum float decimal precision, and e
is the number of digits to be used to represent the exponent, the following items
must be true:
v s>0
v d <= p
v s <= (p + 1)
v s >= d
v if d = 0, w >= s+e+2
v if d > 0 and s > d, w >= s+e+3
v if d > 0 and s = d, w >= s+e+4
The values for w, d, and s are field-width, fractional-digits, and significant-digits,
respectively. The value for e is determined by the E suboption of the DEFAULT
compiler option.
On input, either the data value in the data stream is an optionally signed real
decimal floating-point or fixed-point constant located anywhere within the
specified field or the CONVERSION condition is raised. (For convenience, the E
preceding a signed exponent can be omitted.)
The field width includes leading and trailing blanks, the exponent position, the
positions for the optional plus or minus signs, the position for the optional letter E,
and the position for the optional decimal point in the mantissa.
The data value can appear anywhere within the specified field; blanks can appear
before and after the data value in the field and are ignored. If the entire field is
blank, the CONVERSION condition is raised. When no decimal point appears,
fractional-digits specifies the number of character positions in the mantissa to the
324
Enterprise PL/I for z/OS Language Reference
E-format
right of the assumed decimal point. If a decimal point does appear in the number,
it overrides the specification of fractional-digits.
If field-width is 0, there is no assignment to the data-list item.
The statement:
get file(A) edit (Cost) (E(10,6));
obtains the next 10 characters from A and interprets them as a floating-point
decimal number. A decimal point is assumed before the rightmost 6 digits of the
mantissa. The value of the number is converted to the attributes of COST and
assigned to this variable.
On output, the data-list item is converted to floating-point and rounded if
necessary. The rounding of data is as follows: if truncation causes a digit to be lost
from the right, and this digit is greater than or equal to 5, 1 is added to the digit to
the left of the truncated digit. This addition might cause adjustment of the
exponent.
The character string written in the stream for output has one of the following
syntaxes:
Note:
1. Blanks are not allowed between the elements of the character strings.
2. The length of the exponent may be either 2 or 4 digits depending on the
float datatype and the setting of the E suboption of the DEFAULT
compiler option. In the discussion below, this length is represented by e.
v For d=0
s-digits
-
E
+
-
exponent
w must be >=s+e+2 for positive values, or >=s+e+3 for negative values.
When the value is nonzero, the exponent is adjusted so that the leading digit of
the mantissa is nonzero. When the value is zero, zero suppression is applied to
all digit positions (except the rightmost) of the mantissa.
v For 0<d<s
s-d-digits
-
.
d-digits
E
+
-
exponent
w must be >=s+e+3 for positive values, or >=s+e+5 for negative values.
Chapter 13. Edit-directed format items
325
E-format
When the value is nonzero, the exponent is adjusted so that the leading digit of
the mantissa is nonzero. When the value is zero, zero suppression is applied to
all digit positions (except the first) to the left of the decimal point. All other digit
positions contain zero.
v For d=s
0. d-digits
-
E
+
-
exponent
w must be >=d+e+5 for positive values, or >=d+e+6 for negative values.
When the value is nonzero, the exponent is adjusted so that the first fractional
digit is nonzero. When the value is zero, each digit position contains zero.
If the field width is such that significant digits or the sign are lost, the SIZE
condition is raised. If the character string does not fill the specified field on output,
the character string is right-adjusted and extended on the left with blanks.
F-format item
The fixed-point (or F) format item describes the character representation of a real
fixed-point decimal arithmetic value.
F (
field-width
)
,fractional-digits
,scaling-factor
field-width
Specifies the total number of characters in the field. It is evaluated and
converted to an integer value w each time the format item is used. The
converted value must be nonnegative.
fractional-digits
Specifies the number of digits in the mantissa that follow the decimal point. It
is evaluated and converted to an integer value d each time the format item is
used. The converted value must be nonnegative. If fractional-digits is not
specified, the default value is 0.
scaling-factor
Specifies the number of digits that must appear in the mantissa. It is evaluated
and converted to an integer value p each time the format item is used.
On input, either the data value in the data stream is an optionally signed real
decimal fixed-point constant located anywhere within the specified field or the
CONVERSION condition is raised. Blanks can appear before and after the data
value in the field and are ignored. If the entire field is blank, it is interpreted as
zero.
326
Enterprise PL/I for z/OS Language Reference
F-format
If no scaling-factor is specified and no decimal point appears in the field, the
expression for fractional-digits specifies the number of digits in the data value to the
right of the assumed decimal point. If a decimal point does appear in the data
value, it overrides the expression for fractional-digits.
If a scaling-factor is specified, it effectively multiplies the data value in the data
stream by 10 raised to the integer value (p) of the scaling-factor. Thus, if p is
positive, the data value is treated as though the decimal point appeared p places to
the right of its given position. If p is negative, the data value is treated as though
the decimal point appeared p places to the left of its given position. The given
position of the decimal point is that indicated either by an actual point, if it
appears, or by the expression for fractional-digits, in the absence of an actual point.
If the field-width is 0, there is no assignment to the data-list item.
On output, the data-list item is converted, if necessary, to fixed-point. Floating
point data converts to FIXED DECIMAL (N,q) where q is the fractional-digits
specified. The data value in the stream is the character representation of a real
decimal fixed-point number, rounded if necessary, and right-adjusted in the
specified field.
The conversion from decimal fixed-point type to character type is performed
according to the normal rules for conversion. Extra characters can appear as blanks
preceding the number in the converted string. And, since leading zeros are
converted to blanks (except for a 0 immediately to the left of the point), additional
blanks can precede the number. If a decimal point or a minus sign appears, either
will cause one leading blank to be replaced.
If only the field-width is specified, only the integer portion of the number is written;
no decimal point appears.
If both the field-width and fractional-digits are specified, both the integer and
fractional portions of the number are written. If the value (d) of fractional-digits is
greater than 0, a decimal point is inserted before the rightmost d digits. Trailing
zeros are supplied when fractional-digits is less than d (the value d must be less
than field-width). If the absolute value of the item is less than 1, a 0 precedes the
decimal point. Suppression of leading zeros is applied to all digit positions (except
the first) to the left of the decimal point.
The rounding of the data value is as follows: if truncation causes a digit to be lost
from the right, and this digit is greater than or equal to 5, 1 is added to the digit to
the left of the truncated digit.
On output, if the data-list item is less than 0, a minus sign is prefixed to the
character representation; if it is greater than or equal to 0, no sign appears.
Therefore, for negative values, the field-width might need to include provision for
the sign, a decimal point, and a 0 before the point.
If the field-width is such that any character is lost, the SIZE condition is raised.
In the example:
declare Total fixed(4,2);
put edit (Total) (F(6,2));
The PUT statement specifies that the value of Total is converted to the character
representation of a fixed-point number and written into the output file SYSPRINT.
Chapter 13. Edit-directed format items
327
F-format
A decimal point is inserted before the last two numeric characters, and the number
is right-adjusted in a field of six characters. Leading zeros are changed to blanks
(except for a zero immediately to the left of the point), and, if necessary, a minus
sign is placed to the left of the first numeric character.
G-format item
For the compiler, the graphic (or G) format item describes the representation of a
graphic string.
G
(field-width)
field-width
Specifies the number of 2-byte positions in the data stream that contain (or will
contain) the graphic string. It is an expression that is evaluated and converted
to an integer value, which must be nonnegative, each time the format item is
used. End-of-line must not occur between the 2 bytes of a graphic.
On input, the specified number of graphics is obtained from the data stream and
assigned, with any necessary truncation or padding, to the data-list item. The
field-width is always required on input, and if it is zero, a null string is obtained.
On output, the data-list item is truncated or extended (with the padding graphic)
on the right to the specified field-width before being placed into the data stream. No
enclosing quotation marks are inserted, nor is the identifying suffix, G, inserted. If
the field-width is zero, no graphics are placed into the data stream. If the field-width
is not specified, it defaults to be equal to the graphic-string length of the data-list
item.
In the following example, if file OUT has the GRAPHIC option, six bytes are
transmitted.
declare A graphic(3);
put file(Out) edit (A) (G(3));
L-format item
On input, L indicates that all data up to the end of the line is assigned to the data
item.
L
On output, L indicates that the data item, padded on the right with blanks, if
necessary, is to fill the remainder of the output line.
328
Enterprise PL/I for z/OS Language Reference
LINE format
LINE format item
The LINE format item specifies the line on the current page of a PRINT file upon
which the next data-list item will be printed, or it raises the ENDPAGE condition.
LINE (line-number)
line-number
Can be represented by an expression, which is evaluated and converted to an
integer value, which must be nonnegative, each time the format item is used.
Blank lines are inserted, if necessary.
If the specified line-number is less than or equal to the current line number, or if the
specified line is beyond the limits set by the PAGESIZE option of the OPEN
statement (or by default), the ENDPAGE condition is raised. An exception is that if
the specified line-number is equal to the current line number, and the column 1
character has not yet been transmitted, the effect is as for a SKIP(0) item, that is, a
carriage return with no line spacing.
If line-number is zero, it defaults to one (1).
P-format item
The picture (or P) format item describes the character representation of real
numeric character values and of character values.
The picture specification of the P-format item, on input, describes the form of the
data item expected in the data stream and, in the case of a numeric character
specification, how the item's arithmetic value is interpreted. If the indicated
character does not appear in the stream, the CONVERSION condition is raised.
On output, the value of the associated element in the data list is converted to the
form specified by the picture specification before it is written into the data stream.
P 'picture-specification'
picture-specification
Is discussed in detail in Chapter 14, “Picture specification characters,” on page
333.
For example:
get edit (Name, Total) (P’AAAAA’,P’9999’);
When this statement is executed, the input file SYSIN is the default. The next five
characters input from SYSIN must be alphabetic or blank and they are assigned to
Name. The next four characters must be digits and they are assigned to Total.
Chapter 13. Edit-directed format items
329
PAGE format
PAGE format item
The PAGE format item specifies that a new page is established. It can be used only
with PRINT files.
PAGE
Starting a new page positions the file to the first line of the next page.
R-format item
The remote (or R) format item specifies that the format list in a FORMAT
statement is to be used (as described under “FORMAT statement” on page 315).
R (label-reference)
label-reference
Has as its value the label constant of a FORMAT statement.
The R-format item and the specified FORMAT statement must be internal to the
same block, and they must be in the same invocation of that block.
A remote FORMAT statement cannot contain an R-format item that references itself
as a label reference, nor can it reference another remote FORMAT statement that
leads to the referencing of the original FORMAT statement.
Conditions enabled for the GET or PUT statement must also be enabled for the
remote FORMAT statement(s) that are referred to.
If the GET or PUT statement is the single statement of an ON-unit, that statement
is a block, and it cannot contain a remote format item.
Example
declare Switch label;
get file(In) list(Code);
if Code = 1 then
Switch = L1;
else
Switch = L2;
get file(In) edit (W,X,Y,Z)
(R(Switch));
L1: format (4 F(8,3));
L2: format (4 E(12,6));
Switch has been declared a label variable. The second GET statement can be made
to operate with either of the two FORMAT statements.
330
Enterprise PL/I for z/OS Language Reference
SKIP format
SKIP format item
The SKIP format item specifies that a new line is to be defined as the current line.
SKIP
(relative-line)
relative-line
Specifies an expression, which is evaluated and converted to an integer value,
n, each time the format item is used. The converted value must be nonnegative
and less than 32,768. It must be greater than zero for non-PRINT files. If it is
zero, or if it is omitted, the default is 1.
The new line is the nth line after the present line.
If n is greater than one, one or more lines are ignored on input; on output, one or
more blank lines are inserted.
The value n can be zero for PRINT files only, in which case the positioning is at
the start of the current line. Characters previously written can be overprinted.
For PRINT files, if the specified relative-line is beyond the limit set by the
PAGESIZE option of the OPEN statement (or the default), the ENDPAGE condition
is raised.
If the SKIP format item is the first item to be executed after a file has been opened,
output commences on the nth line of the first page. If n is zero or 1, it commences
on the first line of the first page.
For example:
get file(In) edit(Man,Overtime)
(skip(1), A(6), COL(60), F(4,2));
This statement positions the data set associated with file In to a new line. The first
6 characters on the line are assigned to Man, and the 4 characters beginning at
character position 60 are assigned to Overtime.
V-format item
On input, V indicates that all data up to the end of the line is assigned to the data
item. However, the characters read with a V-format item are not flushed, they are
only viewed. They will be flushed only when read by some other format item.
V
The V-format item is invalid in output.
Chapter 13. Edit-directed format items
331
X-format
X-format item
The spacing (or X) format item specifies the relative spacing of data values in the
data stream.
X (field-width)
field-width
Specifies an expression that is evaluated and converted to an integer value,
which must be nonnegative, each time the format item is used. The integer
value specifies the number of characters before the next field of the data
stream, relative to the current position in the stream.
On input, the specified number of characters are spaced over in the data stream
and not transmitted to the program.
For example:
get edit (Number, Rebate)
(A(5), X(5), A(5));
The next 15 characters from the input file, SYSIN, are treated as follows: the first
five characters are assigned to Number, the next five characters are ignored, and the
remaining five characters are assigned to Rebate.
On output, the specified number of blank characters are inserted into the stream.
In the example:
put file(Out) edit (Part, Count) (A(4), X(2), F(5));
Four characters that represent the value of Part, then two blank characters, and
finally five characters that represent the fixed-point value of Count, are placed in
the file named Out.
332
Enterprise PL/I for z/OS Language Reference
Chapter 14. Picture specification characters
Picture repetition factor . . . . . . . .
Picture characters for character data . . . .
Picture characters for numeric character data .
Digits and decimal points . . . . . .
Zero suppression . . . . . . . . .
Insertion characters . . . . . . . .
Insertion and decimal point characters .
Defining currency symbols . . . . . .
Signs and currency symbols . . . . .
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
334
334
335
336
338
339
339
340
342
Static use . . . . . . .
Drifting use . . . . . .
Credit, debit, overpunched, and
replacement characters . . .
Credit and debit . . . .
Overpunch . . . . . .
Zero replacement . . . .
Exponent characters . . . .
Scaling factor . . . . . .
. .
. .
zero
. .
. .
. .
. .
. .
. .
.
.
.
.
.
.
. 342
. 342
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
344
344
344
345
346
346
A picture specification consists of a sequence of picture characters enclosed in
single or double quotation marks. The characters describe the contents of each
position of the character or numeric character data item, and the contents of the
output. The specification can be made in two ways:
v As part of the PICTURE attribute in a declaration
v As part of the P-format item (described in “P-format item” on page 329) for
edit-directed input and output.
A picture specification describes either a character data item or a numeric character
data item. The presence of an A or X picture character defines a picture
specification as a character picture specification; otherwise, it is a numeric
character picture specification.
A character pictured item can consist of alphabetic characters, decimal digits, blanks,
currency and punctuation characters.
A numeric character pictured item can consist only of decimal digits, an optional
decimal point, an optional letter E, and, optionally, one or two plus or minus signs.
Other characters generally associated with arithmetic data, such as currency
symbols, can also be specified, but they are not part of the arithmetic value of the
numeric character variable, although the characters are stored with the digits and
are part of the character value of the variable.
Figures in this section illustrate how different picture specifications affect the
representation of values when assigned to a pictured variable or when printed
using the P-format item. Each figure shows the original value of the data, the
attributes of the variable from which it is assigned (or written), the picture
specification, and the character value of the numeric character or pictured character
variable.
The concepts of the two types of picture specifications are described separately in
the sections that follow.
© Copyright IBM Corp. 1999, 2012
333
Picture repetition factor
Picture repetition factor
A picture repetition factor specifies the number of repetitions of the next picture
character in the specification.
(n)
n
An integer. No blanks are allowed within the parentheses. If n is 0, the picture
character is ignored.
For example, the following picture specifications result in the same description:
’999V99’
’(3)9V(2)9’
Picture characters for character data
A character picture specification describes a nonvarying character data item. You
can specify that any position in the data item can contain only characters from
certain subsets of the complete set of available characters. The data can consist of
alphabetic characters, decimal digits, and blanks.
The only valid characters in a character picture specification are X, A, and 9. Each
of these specifies the presence of one character position in the character value,
which can contain the following:
X
Any character of the 256 possible bit combinations represented by the 8-bit
byte.
A
Any alphabetic or extralingual (#, @, $) character, or blank.
9
Any digit, or blank. (Note that the 9 picture specification character allows
blanks only for character data.)
When a character value is assigned, or transferred, to a picture character data item,
the particular character in each position is validated according to the
corresponding picture specification character. If the character data does not match
the specification for that position, the CONVERSION condition is raised for the
invalid character. (However, if you change the value by record-oriented
transmission or by using an alias, there is no checking.) For example:
declare Part# picture ’AAA99X’;
put edit (Part#) (P’AAA99X’);
The following values are valid for Part#:
’ABC12M’
’bbb09/’
’XYZb13’
The following values are not valid for Part# (the invalid characters are
underscored):
’AB123M’
’ABC1/2’
’Mb#A5;’
Table 35 on page 335 shows examples of character picture specifications.
334
Enterprise PL/I for z/OS Language Reference
Picture characters for character data
Table 35. Character picture specification examples
Source Attributes
Source Data
(in constant form)
Picture Specification
Character Value
CHARACTER(5)
CHARACTER(5)
CHARACTER(5)
'9B/2L'
'9B/2L'
'9B/2L'
XXXXX
XXX
XXXXXXX
9B/2L
9B/
9B/2Lbb
CHARACTER(5)
CHARACTER(5)
CHARACTER(5)
'ABCDE'
'ABCDE'
'ABCDE'
AAAAA
AAAAAA
AAA
ABCDE
ABCDEb
ABC
CHARACTER(5)
CHARACTER(5)
'12/34'
'L26.7'
99X99
A99X9
12/34
L26.7
Picture characters for numeric character data
Numeric character data represents numeric values. The picture specification cannot
contain the character data picture characters X or A. The picture characters for
numeric character data can also specify editing of the data.
A numeric character variable can have two values, depending upon how the
variable is used. The types of values are as follows:
Arithmetic
The arithmetic value is the value expressed by the decimal digits of the
data item, the assumed location of a decimal point, possibly a sign, and an
optionally-signed exponent or scaling factor. The arithmetic value of a
numeric character variable is used in the following situations:
v Whenever the variable appears in an expression that results in a coded
arithmetic value or bit value (this includes expressions with the ¬, &, |,
and comparison operators; even comparison with a character string uses
the arithmetic value of a numeric character variable)
v Whenever the variable is assigned to a coded arithmetic, numeric
character, or bit variable
v When used with the C, E, F, B, and P (numeric) format items in
edit-directed I/O.
The arithmetic value of the numeric character variable is converted to internal
coded arithmetic representation.
Character value
The character value is the value expressed by the decimal digits of the data
item, as well as all of the editing and insertion characters appearing in the
picture specification. The character value does not, however, include the
assumed location of a decimal point, as specified by the picture characters
V, K, or F. The character value of a numeric character variable is used:
v Whenever the variable appears in a character expression
v In an assignment to a character variable
v Whenever the data is printed using list-directed or data-directed output
v Whenever a reference is made to a character variable that is defined or
based on the numeric character variable
v Whenever the variable is printed using edit-directed output with the A
or P (character) format items.
No data conversion is necessary.
Chapter 14. Picture specification characters
335
Picture characters for numeric character data
Numeric character data can contain only decimal digits, an optional decimal point,
an optional letter E, and one or two plus or minus signs. Other characters
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 part of the
character value of the variable.
A numeric character specification consists of one or more fields, each field
describing a fixed-point number. A floating-point specification has two fields—one
for the mantissa and one for the exponent. The first field can be divided into
subfields by inserting a V picture specification character. The data preceding the V
(if any) and that following it (if any) are subfields of the specification.
A requirement of the picture specification for numeric character data is that each
field must contain at least one picture character that specifies a digit position. This
picture character, however, need not be the digit character 9. Other picture
characters, such as the zero suppression characters (Z or *), also specify digit
positions.
Note: All characters except K, V, and F specify the occurrence of a character in the
character representation.
The picture characters for numeric character specifications are discussed in the
following sections:
v “Digits and decimal points” describes data specified with the picture characters
9 and V.
v “Zero suppression” on page 338 describes picture data specified with the picture
characters Z and asterisk (*).
v “Insertion characters” on page 339 discusses the use of the insertion characters
(point, comma, slash, and B).
v “Insertion and decimal point characters” on page 339 describes the use of the
decimal point and insertion characters with the V picture character.
v “Defining currency symbols” on page 340 describes how to define your own
character(s) as a currency symbol, and “Signs and currency symbols” on page
342 describes the use of signs and currency symbols.
v “Credit, debit, overpunched, and zero replacement characters” on page 344
discusses the picture characters CR, DB, T, I, R, and Y used for credit, debit,
overpunched, and zero replacement functions.
v “Exponent characters” on page 346 discusses the picture characters K and E
used for exponents.
v “Scaling factor” on page 346 describes the picture character F used for scaling
factors.
v “Picture repetition factor” on page 334 describes the picture repetition character.
Digits and decimal points
The picture characters 9 and V are used in numeric character specifications that
represent fixed-point decimal values.
9
336
Specifies that the associated position in the data item contains a decimal digit.
(Note that the 9 picture specification character for numeric character data is
different from the specification for character data because the corresponding
character cannot be a blank for character data.)
Enterprise PL/I for z/OS Language Reference
Digits and decimal points
A string of n 9 picture characters specifies that the item is a nonvarying
character-string of length n, each of which is a digit (0 through 9). For
example:
dcl digit picture’9’,
Count picture’999’,
XYZ picture ’(10)9’;
An example of use is:
dcl 1 Record,
2 Data char(72),
2 Identification char(3),
2 Sequence pic’99999’;
dcl
Count
fixed dec(5);
.
.
.
Count=Count+1;
Sequence=Count;
write file(Output) from(Record);
V
Specifies that a decimal point is assumed at this position in the associated data
item. However, it does not specify that an actual decimal point or decimal
comma is inserted. The integer value and fractional value of the assigned
value, after modification by the optional scaling factor F(±x), are aligned on the
V character. Therefore, an assigned value can be truncated or extended with
zero digits at either end. (If significant digits are truncated on the left, the
result is undefined and the SIZE condition is raised if enabled.)
If no V character appears in the picture specification of a 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 necessary, to an integer.
The V character cannot appear more than once in a picture specification.
For example:
dcl Value picture ’Z9V999’;
Value = 12.345;
dcl Cvalue char(5);
Cvalue = Value;
Cvalue, after assignment of Value, contains ’12345’.
Table 36 shows examples of digit and decimal point characters.
Table 36. Examples of digit and decimal point characters
Source Attributes
Source Data
(in constant form)
Picture Specification
Character Value
FIXED(5)
FIXED(5)
FIXED(5)
12345
12345
12345
99999
99999V
999V99
12345
12345
undefined
FIXED(5)
FIXED(7)
FIXED(3)
12345
1234567
123
V99999
99999
99999
undefined
undefined
00123
FIXED(5,2)
FIXED(7,2)
FIXED(5,2)
123.45
12345.67
123.45
999V99
9V9
99999
12345
undefined
00123
Note: When the character value is undefined, the SIZE condition is raised.
Chapter 14. Picture specification characters
337
Zero suppression
Zero suppression
The picture characters Z and asterisk (*) specify conditional digit positions in the
character value and can cause leading zeros to be replaced by asterisks or blanks.
Leading zeros are those that occur in the leftmost digit positions of fixed-point
numbers or in the leftmost digit positions of the two parts of floating-point
numbers, that are to the left of the assumed position of a decimal point, and that
are not preceded by any of the digits 1 through 9. The leftmost nonzero digit in a
number and all digits, zeros or not, to the right of it represent significant digits.
Z
Specifies a conditional digit position and causes a leading zero in the
associated data position to be replaced by a blank. Otherwise, the digit in the
position is unchanged. The picture character Z cannot appear in the same field
as the picture character * or a drifting character, nor can it appear to the right
of any of the picture characters in a field.
*
Specifies a conditional digit position. It is used the way the picture character Z
is used, except that leading zeros are replaced by asterisks. The picture
character asterisk cannot appear in the same field as the picture character Z or
a drifting character, nor can it appear to the right of any of the picture
characters in a field.
Table 37 shows examples of zero suppression characters.
Table 37. Examples of zero suppression characters
Source Attributes
Source Data
(in constant form)
Picture Specification
Character Value
FIXED(5)
FIXED(5)
FIXED(5)
12345
00100
00100
ZZZ99
ZZZ99
ZZZZZ
12345
bb100
bb100
FIXED(5)
FIXED(5,2)
FIXED(5,2)
00000
123.45
001.23
ZZZZZ
ZZZ99
ZZZV99
bbbbb
bb123
bb123
FIXED(5)
FIXED(5,2)
FIXED(5,2)
12345
000.08
000.00
ZZZV99
ZZZVZZ
ZZZVZZ
undefined
bbb08
bbbbb
FIXED(5)
FIXED(5)
FIXED(5,2)
00100
00000
000.01
*****
*****
***V**
**100
*****
***01
FIXED(5,2)
FIXED(5,2)
95
12350
$**9.99
$**9.99
$**0.95
$123.50
Note: When the character value is undefined, the SIZE condition is raised.
If one of the picture characters Z or asterisk appears to the right of the picture
character V, all fractional digit positions in the specification, as well as all integer
digit positions, must use the Z or asterisk picture character, respectively. When all
digit positions to the right of the picture character V contain zero suppression
picture characters, fractional zeros of the value are suppressed only if all positions
in the fractional part contain zeros and all integer positions have been suppressed.
The character value of the data item will then consist of blanks or asterisks. No
digits in the fractional part are replaced by blanks or asterisks if the fractional part
contains any significant digit.
338
Enterprise PL/I for z/OS Language Reference
Insertion characters
Insertion characters
The picture characters comma (,), point (.), slash (/), and blank (B) cause the
specified character to be inserted into the associated position of the numeric
character data. They do not indicate digit or character positions, but are inserted
between digits or characters. Each does, however, actually represent a character
position in the character value, whether or not the character is suppressed. The
comma, point, and slash are conditional insertion characters and can be suppressed
within a sequence of zero suppression characters. The blank is an unconditional
insertion character, and always specifies that a blank appears in the associated
position.
Insertion characters are applicable only to the character value. They specify
nothing about the arithmetic value of the data item. They never cause decimal
point or decimal comma alignment in the picture specifications of a fixed-point
decimal number and are not a part of the arithmetic value of the data item.
Decimal alignment is controlled by the picture characters V and F.
Comma (,), point (.), or slash (/)
Inserts a character into the associated position of the numeric character data
when no zero suppression occurs. If zero suppression does occur, the character
is inserted only under the following conditions:
v When an unsuppressed digit appears to the left of the character's position
v When a V appears immediately to the left of the character and the fractional
part of the data item contains any significant digits
v When the character is at the start of the picture specification
v When the character is preceded only by characters that do not specify digit
positions.
In all other cases where zero suppression occurs, a comma, point, or slash
insertion character is treated as a zero suppression character identical to the
preceding character.
B
Specifies that a blank character be inserted into the associated position of the
character value of the numeric character data.
Insertion and decimal point characters
The point, comma, or slash can be used in conjunction with the V to cause
insertion of the point (or comma or slash) in the position that delimits the end of
the integer portion in and the beginning of the fractional portion of a fixed-point
(or floating-point) number, as might be desired in printing, since the V does not
cause printing of a point. The point must immediately precede or immediately
follow the V. If the point precedes the V, it is inserted only if an unsuppressed
digit appears to the left of the V, even if all fractional digits are significant. If the
point immediately follows the V, it is suppressed if all digits to the right of the V
are suppressed, but it appears if there are any unsuppressed fractional digits
(along with any intervening zeros).
The following example shows decimal conventions that are used in different
countries.
declare A picture ’Z,ZZZ,ZZZV.99’,
B picture ’Z.ZZZ.ZZZV,99’,
C picture ’ZBZZZBZZZV,99’;
A,B,C = 1234;
A,B,C = 1234.00;
A, B, and C represent nine-digit numbers with a decimal point or decimal comma
assumed between the seventh and eighth digits. The actual point specified by the
Chapter 14. Picture specification characters
339
Insertion characters and decimal points
decimal point insertion character is not a part of the arithmetic value. It is,
however, part of its character value. The two assignment statements assign the
same character value to A, B, and C as follows:
1,234.00
1.234,00
1 234,00
/* value of A */
/* value of B */
/* value of C */
In the following example, decimal point alignment during assignment occurs on
the character V. If Rate is printed, it appears as ’762.00’, but its arithmetic value is
7.6200.
declare Rate picture ’9V99.99’;
Rate = 7.62;
Table 38 shows examples of insertion characters.
Table 38. Examples of insertion characters
Source Attributes
Source Data
(in constant form)
Picture Specification
Character Value
FIXED(4)
FIXED(6,2)
FIXED(4,2)
1234
1234.56
12.34
9,999
9,999V.99
ZZ.VZZ
1,234
1,234.56
12.34
FIXED(4,2)
FIXED(4,2)
FIXED(4,2)
00.03
00.03
12.34
ZZ.VZZ
ZZV.ZZ
ZZV.ZZ
bbb03
bb.03
12.34
FIXED(4,2)
FIXED(9,2)
FIXED(7,2)
00.00
1234567.89
12345.67
ZZV.ZZ
9,999,999.V99
**,999V.99
bbbbb
1,234,567.89
12,345.67
FIXED(7,2)
FIXED(9,2)
FIXED(6)
00123.45
1234567.89
123456
**,999V.99
9.999.999V,99
99/99/99
***123.45
1.234.567,89
12/34/56
FIXED(6)
FIXED(6)
FIXED(6)
123456
001234
000012
99.9/99.9
ZZ/ZZ/ZZ
ZZ/ZZ/ZZ
12.3/45.6
bbb12/34
bbbbbb12
FIXED(6)
FIXED(6)
FIXED(6)
000000
000000
000000
ZZ/ZZ/ZZ
**/**/**
**B**B**
bbbbbbbb
********
**b**b**
FIXED(6)
FIXED(3)
FIXED(2)
123456
123
12
99B99B99
9BB9BB9
9BB/9BB
12b34b56
1bb2bb3
1bb/2bb
Defining currency symbols
A currency symbol can be used as a picture character denoting a character value of
numeric character data. This symbol can be the dollar sign ($) or any symbol you
choose. The symbol can be any sequence of characters enclosed in < and >
characters.
340
<
char
Enterprise PL/I for z/OS Language Reference
>
Currency symbols
Indicates the start of the currency symbol. It acts as an escape character. If you
want to use the character <, you must specify <<.
<
char
Is any character that will be part of your currency symbol(s).
indicates the end of the currency symbol. If you want to use the character >,
you must specify <>.
>
More than one > indicates a drifting string (discussed in “Drifting use” on
page 342).
See the following examples of general insertion strings:
<DM>
represents the Deutschemark
<Fr>
represents the French Franc
<K$>
represents the Khalistan Dollar
<Sur.f>
represents the Surinam Guilder
<$>
represents the dollar sign
If the character < or > must be included in the sequence, it must be preceded by
another <. Therefore, < acts as an escape character also.
The entire sequence enclosed in < > represents one "symbol" and therefore
represents the character value for one numeric character. If the symbol needs to be
represented as a drifting picture character, you specify > following the "< >" to
represent each occurrence.
For example:
Pic ’<DM>>>.>>9,V99’
represents a 10 character numeric picture, yielding 11 characters after
assignment.
Pic ’<Sur.f>999,V99’
represents a 7 character numeric picture, yielding 11 characters after
assignment.
Pic ’<K$>>>,>>9.V99’
represents a 10 character numeric picture, yielding 11 characters after
assignment.
Pic ’<$>>>,>>9.V99’
represents a 10 character numeric picture, yielding 10 characters after
assignment.
Pic ’$$$,$$9.V99’
has the same value as the previous picture specification.
More examples of currency symbol definition are listed as follows:
dcl P pic’<DM>9.999,V99’;
P = 1234.40;
/* Yields ’DM1.234,40’
*/
dcl P pic’<DM>9.999,V99’;
P =
34.40;
/* Yields ’DM
*/
34,40’
dcl P pic’<DM>>.>>9,V99’;
Chapter 14. Picture specification characters
341
Currency symbols
P = 1234.40;
/* Yields ’DM1.234,40’
*/
dcl P pic’<DM>>.>>9,V99’;
P =
34.40;
/* Yields ’
*/
dcl P pic’9.999,V99<K$>’;
P = 1234.40;
/* Yields ’1.234,40K$’ */
DM34,40’
In this chapter, the term currency symbol and the $ symbol refer to the dollar sign
or any user-defined currency symbol.
Signs and currency symbols
The picture characters S, +, and – specify signs in numeric character data. The
picture character $ (or the currency symbol) specifies a currency symbol in the
character value of numeric character data. Only one type of sign character can
appear in each field.
currency symbol
Specifies the currency symbol.
In the following example:
dcl Price picture ’$99V.99’;
Price = 12.45;
The character value of Price is ’$12.45’. Its arithmetic value is 12.45.
For information on specifying a character as a currency symbol, refer to
“Defining currency symbols” on page 340.
S
Specifies the plus sign character (+) if the data value is >=0; otherwise, it
specifies the minus sign character (-). The rules are identical to those for the
currency symbol.
Consider the following example:
dcl Root picture ’S999’;
The value 50 is held as ’+050’, the value 0 as ’+000’ and the value -243 as
’-243’.
+
Specifies the plus sign character (+) if the data value is >=0; otherwise, it
specifies a blank. The rules are identical to those for the currency symbol.
-
Specifies the minus sign character (-) if the data value is <0; otherwise, it
specifies a blank. The rules are identical to those for the currency symbol.
Signs and currency symbols can be used in either a static or a drifting manner.
Static use
Static use specifies that a sign, a currency symbol, or a blank appears in the
associated position. An S, +, or - used as a static character can appear to the right
or left of all digits in the mantissa and exponent fields of a floating-point
specification, and to the right or left of all digit positions of a fixed-point
specification.
Drifting use
Drifting use specifies that leading zeros are to be suppressed. In this case, the
rightmost suppressed position associated with the picture character will contain a
342
Enterprise PL/I for z/OS Language Reference
Signs and currency symbols
sign, a blank, or a currency symbol (except that where all digit positions are
occupied by drifting characters and the value of the data item is zero, the drifting
character is not inserted).
A drifting character is specified by multiple use of that character in a picture field.
The drifting character must be specified in each digit position through which it can
drift. Drifting characters must appear in a sequence of the same drifting character,
optionally containing a V and one of the insertion characters comma, point, slash,
or B. Any of the insertion characters slash, comma, or point within or immediately
following the string is part of the drifting string. The character B always causes
insertion of a blank, wherever it appears. A V terminates the drifting string, except
when the arithmetic value of the data item is zero; in that case, the V is ignored. A
field of a picture specification can contain only one drifting string. A drifting string
cannot be preceded by a digit position nor can it occur in the same field as the
picture characters * and Z.
The position in the data associated with the characters slash, comma, and point
appearing in a string of drifting characters contains one of the following:
v Slash, comma, or point if a significant digit appears to the left
v The drifting symbol, if the next position to the right contains the leftmost
significant digit of the field
v Blank, if the leftmost significant digit of the field is more than one position to
the right.
If a drifting string contains the drifting character n times, the string is associated
with n-1 conditional digit positions. The position associated with the leftmost
drifting character can contain only the drifting character or blank, never a digit.
Two different picture characters cannot be used in a drifting manner in the same
field.
If a drifting string contains a V within it, the V delimits the preceding portion as a
subfield, and all digit positions of the subfield following the V must also be part of
the drifting string that commences the second subfield.
In the case in which all digit positions after the V contain drifting characters,
suppression in the subfield occurs only if all of the integer and fractional digits are
zero. The resulting edited data item is then all blanks (except for any insertion
characters at the start of the field). If there are any nonzero fractional digits, the
entire fractional portion appears unsuppressed.
If, during or before assignment to a picture, the fractional digits of a decimal
number are truncated so that the resulting value is zero, the sign inserted in the
picture corresponds to the value of the decimal number prior to its truncation.
Thus, the sign in the picture depends on how the decimal value was calculated.
Table 39 shows examples of signs and currency symbol characters.
Table 39. Examples of signs and currency characters
Source Attributes
Source Data
(in constant form)
Picture Specification
Character Value
FIXED(5,2)
FIXED(5,2)
FIXED(5,2)
123.45
012.00
001.23
$999V.99
99$
$ZZZV.99
$123.45
12$
$bb1.23
Chapter 14. Picture specification characters
343
Signs and currency symbols
Table 39. Examples of signs and currency characters (continued)
Source Attributes
Source Data
(in constant form)
Picture Specification
Character Value
FIXED(5,2)
FIXED(1)
FIXED(5,2)
000.00
0
123.45
$ZZZV.ZZ
$$$.$$
$$$9V.99
bbbbbbb
bbbbbb
$123.45
FIXED(5,2)
FIXED(2)
FIXED(4)
001.23
12
1234
$$$9V.99
$$$,999
$$$,999
bb$1.23
bbb$012
b$1,234
FIXED(5,2)
FIXED(5)
FIXED(5)
2.45
214
-4
SZZZV.99
SS,SS9
SS,SS9
+bb2.45
bb+214
bbbb-4
FIXED(5,2)
FIXED(5,2)
FIXED(5,2)
-123.45
-123.45
123.45
+999V.99
-999V.99
999V.99S
b123.45
-123.45
123.45+
FIXED(5,2)
FIXED(5,2)
FIXED(5,2)
001.23
001.23
-001.23
++B+9V.99
- - -9V.99
SSS9V.99
bbb+1.23
bbb1.23
bb-1.23
Credit, debit, overpunched, and zero replacement characters
The picture characters CR, DB, T, I, and R cannot be used with any other sign
characters in the same field.
Credit and debit
The character pairs CR (credit) and DB (debit) specify the signs of real numeric
character data items.
CR Specifies that the associated positions contain the letters CR if the value of the
data is <0. Otherwise, the positions will contain two blanks. The characters CR
can appear only to the right of all digit positions of a field.
DB Specifies that the associated positions contain the letters DB if the value of the
data is <0. Otherwise, the positions will contain two blanks. The characters DB
can appear only to the right of all digit positions of a field.
Overpunch
Any of the picture characters T, I, or R (known as overpunch characters) specifies
that a character represents the corresponding digit and the sign of the data item. A
floating-point specification can contain two—one in the mantissa field and one in
the exponent field. The overpunch character can be specified for any digit position
within a field.
The T, I, and R picture characters specify how the input characters are interpreted,
as shown in Table 40.
Table 40. Interpretation of the T, I, and R picture characters
344
T or I
T or R
Digit with +
Digit with -
Character
Character
Enterprise PL/I for z/OS Language Reference
Digit
Credit, debit, overpunched and zero replacement
Table 40. Interpretation of the T, I, and R picture characters (continued)
{
A
B
C
D
E
F
G
H
I
}
J
K
L
M
N
O
P
Q
R
0
1
2
3
4
5
6
7
8
9
T, I, and R specify the following values:
T
On input, T specifies that the characters { through I and the digits 0 through 9
represent positive values, and that the characters } through R represent
negative values.
On output, T specifies that the associated position contains one of the
characters { through I if the input data represents positive values, and one of
the characters } through R if the input data represents negative values. The T
can appear anywhere a '9' picture specification character occurs. For example:
dcl Credit picture ’ZZV9T’;
The character representation is 4 characters; +21.05 is held as '210E', -0.07 is
held as 'bb0P'.
I
On input, I specifies that the characters { through I and the digits 0 through 9
represent positive values.
On output, I specifies that the associated position contains one of the
characters { through I if the input data represents positive values; otherwise, it
contains one of the digits, 0 through 9.
R
On input, R specifies that the characters } through R represent negative values
and the digits 0 through 9 represent positive values.
On output, R specifies that the associated position contains one of the
characters } through R if the input data represents negative values; otherwise,
it contains one of the digits 0 through 9. For example:
dcl X fixed decimal(3);
get edit (x) (P’R99’);
sets X to 132 on finding '132' in the next three positions of the input stream, but
sets X to -132 on finding 'J32'.
Zero replacement
Y
Specifies that a zero in the specified digit position is replaced unconditionally
by the blank character.
Table 41 on page 346 shows examples of credit, debit, overpunched, and zero
replacement characters.
Chapter 14. Picture specification characters
345
Credit, debit, overpunched and zero replacement
Table 41. Examples of credit, debit, overpunched, and zero replacement characters
Source Attributes
Source Data
(in constant form)
Picture Specification
Character Value
FIXED(3)
FIXED(4,2)
FIXED(4,2)
-123
12.34
-12.34
$Z.99CR
$ZZV.99CR
$ZZV.99DB
$1.23CR
$12.34bb
$12.34DB
FIXED(4,2)
FIXED(4)
FIXED(4)
12.34
1021
-1021
$ZZV.99DB
999I
Z99R
$12.34bb
102A
102J
FIXED(4)
FIXED(5)
FIXED(5)
1021
00100
10203
99T9
YYYYY
9Y9Y9
10B1
bb1bb
1b2b3
FIXED(5,2)
000.04
YYYVY9
bbbb4
Exponent characters
The picture characters K and E delimit the exponent field of a numeric character
specification that describes floating-point decimal numbers. The exponent field is
the last field of a numeric character floating-point picture specification. The picture
characters K and E cannot appear in the same specification.
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 item.
E
Specifies that the associated position contains the letter E, which indicates the
start of the exponent field.
The value of the exponent is adjusted in the character value so that the first
significant digit of the first field (the mantissa) appears in the position associated
with the first digit specifier of the specification (even if it is a zero suppression
character).
Table 42 shows examples of exponent characters.
Table 42. Examples of exponent characters
Source Attributes
Source Data
(in constant form)
Picture Specification
Character Value
FLOAT(5)
FLOAT(5)
FLOAT(5)
.12345E06
.12345E-06
.12345E+06
V.99999E99
V.99999ES99
V.99999KS99
.12345E06
.12345E-06
.12345+06
FLOAT(5)
FLOAT(5)
FLOAT(5)
-123.45E+12
001.23E-01
001.23E+04
S999V.99ES99
SSS9.V99ESS9
ZZZV.99KS99
-123.45E+12
+123.00Eb-3
123.00+02
FLOAT(5)
FLOAT(5)
001.23E+04
001.23E+04
SZ99V.99ES99
SSSSV.99E-99
+123.00E+02
+123.00Eb02
Scaling factor
The picture character F specifies a picture scaling factor for fixed-point decimal
numbers. It can appear only once at the right end of the picture specification.
346
Enterprise PL/I for z/OS Language Reference
Scaling factor
F (
integer)
+
-
F
Specifies the picture scaling factor. The picture scaling factor specifies that the
decimal point in the arithmetic value of the variable is that number of places to
the right (if the picture scaling factor is positive) or to the left (if negative) of
its assumed position in the character value.
The number of digits following the V picture character minus the integer
specified with F must be between -128 and 127.
Table 43 shows examples of the picture scaling factor character.
Table 43. Examples of scaling factor characters
Source Attributes
Source Data
(in constant form)
Picture Specification
Character Value
FIXED(4,0)
FIXED(7,0)
FIXED(5,5)
1200
-1234500
.00012
99F(2)
S999V99F(4)
99F(-5)
12
-12345
12
FIXED(6,6)
.012345
999V99F(-4)
12345
Chapter 14. Picture specification characters
347
Scaling factor
348
Enterprise PL/I for z/OS Language Reference
Chapter 15. Condition handling
Condition prefixes . . . . . . . . .
Scope of the condition prefix . . . .
Raising conditions with OPTIMIZATION
On-units . . . . . . . . . . . .
ON statement . . . . . . . . .
Null ON-unit . . . . . . . . .
Scope of the ON-unit . . . . . . .
Dynamically descendent ON-units . .
ON-units for file variables . . . . .
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
349
351
351
351
352
353
353
353
354
Example 1 . .
Example 2 . .
Example 3 . .
Example 4 . .
REVERT statement .
SIGNAL statement .
RESIGNAL statement.
Multiple conditions .
CONDITION attribute
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
354
354
354
354
355
355
356
356
356
While a PL/I program is running, certain events can occur for which you can do
some testing, issue a response, or take recovery action. These events are called
conditions, and are raised when detected. Conditions can be unexpected errors (e.g.
overflow, input/output transmission error) or expected errors (e.g. end of an input
file). Conditions can be raised directly in a program through the use of the
SIGNAL statement (this can be very useful during testing).
Application control over conditions is accomplished through the enablement of
conditions and the establishment of actions to be performed when an enabled
condition is raised. When a condition is disabled, the compiler assumes that the
condition cannot occur and generates code accordingly. If the condition does occur,
your program is in error. The established action can be an ON-unit or the implicit
action defined for the condition.
When an ON-unit is invoked, it is treated as a procedure without parameters. To
assist you in making use of ON-units, built-in functions and pseudovariables are
provided that you can use to inquire about the cause of a condition.
Pseudovariables are often used for error correction and recovery. Built-in functions
and pseudovariables are listed in Chapter 18, “Built-in functions, pseudovariables,
and subroutines,” on page 383
The implicit action for many conditions is to raise the ERROR condition. This
provides a common condition that can be used to check for a number of different
conditions, rather than checking each condition separately. The ONCODE built-in
function is particularly useful here, as it can be used to identify the specific
circumstances that raised the conditions. Codes corresponding to the conditions
and errors detected are listed in Messages and Codes.
Condition prefixes
You can specify whether or not some conditions are enabled or disabled. If a
condition is enabled, the compiler generates any extra code needed in order to
detect the condition. If a condition is disabled, the compiler generates no extra
code to detect it.
Disabling a condition is equivalent to asserting that the condition cannot occur; if it
does, your program is in error.
For instance, if the SUBSCRIPTRANGE condition is enabled, the compiler
generates extra code to ensure that any array index is within the bounds of its
array. If the SUBSCRIPTRANGE condition is disabled, the extra code is not
generated and using an invalid array index leads to unpredictable results.
© Copyright IBM Corp. 1999, 2012
349
Condition prefixes
If a condition is detected by hardware, disabling the condition has no effect.
Enabling and disabling can be specified for the eligible conditions by a condition
prefix.
,
(
condition
)
:
statement
;
condition
Some conditions are always enabled, and cannot be disabled. Some are enabled
unless you disable them, and some are disabled unless you enable them. The
conditions are listed in Chapter 16, “Conditions,” on page 357.
statement
Condition prefixes are not valid for DECLARE, DEFAULT, FORMAT,
OTHERWISE, END, ELSE, ENTRY, and %statements. For information on the
scope of condition prefixes, refer to “Scope of the condition prefix” on page
351.
In the following example (size): is the condition prefix. The conditional prefix
indicates that the corresponding condition is enabled within the scope of the
prefix.
(size):
L1:
X=(I**N) / (M+L);
Conditions can be enabled using the condition prefix specifying the condition
name. They can be disabled using the condition prefix specifying the condition
name preceded by NO without intervening blanks. Types and status of conditions
are shown in Table 44.
Table 44. Classes and status of conditions
Class and conditions
Computational (for data handling,
expression evaluation, and computation)
CONVERSION
FIXEDOVERFLOW
INVALIDOP
OVERFLOW
UNDERFLOW
ZERODIVIDE
Input/Output
ENDFILE
ENDPAGE
KEY
NAME
RECORD
TRANSMIT
UNDEFINEDFILE
Program checkout (useful for
developing/debugging a program)
SIZE
350
Enterprise PL/I for z/OS Language Reference
Status
Enabled by default
Enabled by default
Enabled by default
Enabled by default
Always enabled
Enabled by default
Always
Always
Always
Always
Always
Always
Always
enabled
enabled
enabled
enabled
enabled
enabled
enabled
Disabled by default
Condition prefixes
Table 44. Classes and status of conditions (continued)
Class and conditions
Status
STRINGRANGE
STRINGSIZE
SUBSCRIPTRANGE
Miscellaneous
ANYCONDITION
AREA
ATTENTION
CONDITION
ERROR
FINISH
STORAGE
Disabled by default
Disabled by default
Disabled by default
Always
Always
Always
Always
Always
Always
Always
enabled
enabled
enabled
enabled
enabled
enabled
enabled
For information about the performance effects of enabling and disabling
conditions, refer to the Programming Guide.
Scope of the condition prefix
The scope of a condition prefix (the part of the program to which it applies) is the
statement or block to which the prefix is attached. The prefix does not necessarily
apply to any procedures or ON-units that can be invoked in the execution of the
statement.
A condition prefix attached to a PACKAGE, PROCEDURE, or BEGIN statement
applies to all the statements up to and including the corresponding END
statement. This includes other PROCEDURE or BEGIN statements nested within
that block.
Condition status can be redefined within a block by attaching a prefix to
statements within the block, including PROCEDURE and BEGIN statements (thus
redefining the enabling or disabling of the condition within nested blocks). The
redefinition applies only to the execution of the statement to which the prefix is
attached. In the case of a nested PROCEDURE or BEGIN statement, it applies only
to the block the statement defines, as well as any blocks contained within that
block.
Raising conditions with OPTIMIZATION
When OPTIMIZATION is in effect, conditions for the same expression that appear
multiple times can be raised only once. In the following example,
SUBSCRIPTRANGE for IX can be raised only once:
call P (55);
(subscriptrange): P: proc (IX);
dcl (Ar, Br, Cr) (10);
Ar(IX) = Ar(IX) + Br(IX);
T = Cr(IX);
End P;
On-units
An implicit action exists for every condition. When an enabled condition is raised,
the implicit action is executed unless an ON-unit for the enabled condition is
established. If the implicit action is to raise ERROR and no ON-unit has been
established for the condition, a message will be written before the ERROR
condition is raised.
Chapter 15. Condition handling
351
ON Statement
ON statement
The ON statement establishes the action to be executed for any subsequent raising
of an enabled condition in the scope of the established condition.
,
ON condition
SNAP
SYSTEM;
ON-unit
condition
Is any one of those described in Chapter 16, “Conditions,” on page 357 or
defined with the CONDITION attribute.
SNAP
Specifies that when the enabled condition is raised, diagnostic information
relating to the condition is printed. The action of the SNAP option precedes the
action of the ON-unit.
If SNAP and SYSTEM are specified, the implicit action is followed immediately
by SNAP information.
SYSTEM
Specifies that the implicit action is taken. The implicit action is not the same
for every condition, although for most conditions a message is printed and the
ERROR condition is raised. The implicit action for each condition is given in
Chapter 16, “Conditions,” on page 357.
ON-unit
Specifies the action to be executed when the condition is raised and is enabled.
The action is defined by the statement or statements in the ON-unit itself.
When the ON statement is executed, the ON-unit is said to be established for
the specified condition. The ON-unit is not executed at the time the ON
statement is executed; it is executed only when the specified enabled condition
is raised.
The ON-unit can be either a single unlabeled simple statement or an unlabeled
begin-block. If it is a simple statement, it can be any statement except BEGIN,
DECLARE, DEFAULT, DO, END, ENTRY, FORMAT, ITERATE, LEAVE,
OTHERWISE, PROCEDURE, RETURN, SELECT, WHEN, or %statements. If the
ON-unit is a begin-block, a RETURN statement can appear only within a
procedure nested within the begin-block; a LEAVE statement can appear only
within a do-group nested within the begin-block.
Except for ON-units consisting only of either a semicolon (;) or the RESIGNAL
statement, an ON-unit is treated as a procedure (without parameters) that is
internal to the block in which it appears. Any names referenced in an ON-unit
are those known in the environment in which the ON statement for that
ON-unit was executed, rather than the environment in which the condition
was raised.
When execution of the ON-unit is complete, control generally returns to the
block from which the ON-unit was entered. Just as with a procedure, control
can be transferred out of an ON-unit by a GO TO statement. In this case,
control is transferred to the point specified in the GO TO, and a normal return
does not occur.
352
Enterprise PL/I for z/OS Language Reference
ON Statement
The specific point to which control returns from an ON-unit varies for different
conditions. Normal return for each condition is described in Chapter 16,
“Conditions,” on page 357.
Null ON-unit
The effect of a null statement ON-unit is to execute normal return from the
condition.
Use of the null ON-unit is different from disabling a condition for two reasons:
v A null ON-unit can be specified for any condition, but not all conditions can be
disabled.
v Disabling a condition, if possible, can save time by avoiding any checking for
this condition. (If a null ON-unit is specified, the PL/I must still check for the
raising of the condition.)
Scope of the ON-unit
The execution of an ON statement establishes an action specification for a
condition. Once this action is established, it remains established throughout that
block and throughout all dynamically descendent blocks until it is overridden by
the execution of another ON statement or a REVERT statement or until termination
of the block in which the ON statement is executed. (For information on
dynamically descendent ON-units, refer to “Dynamically descendent ON-units.”)
When another ON statement specifies the same conditions:
v If a later ON statement specifies the same condition as a prior ON statement and
this later ON statement is executed in a block which is a dynamic descendant of
the block containing the prior ON statement, the action specification of the 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
containing the later ON statement.
When control returns from a block, all established actions that existed at the
time of its activation are reestablished. This makes it impossible for a subroutine
to alter the action established for the block that invoked the subroutine.
v If the later ON statement and the prior ON statement are internal to the same
invocation of the same block, the effect of the prior ON statement is logically
nullified. No reestablishment is possible, except through execution of another
ON statement (or re-execution of an overridden ON statement).
Dynamically descendent ON-units
It is possible to raise a condition during execution of an ON-unit that specifies
another ON-unit. An ON-unit entered because a condition is either raised or
signalled in another ON-unit is a dynamically descendent ON-unit. A normal
return from a dynamically descendent ON-unit reestablishes the environment of
the ON-unit in which the condition was raised.
A loop can occur if an ERROR condition raised in an ERROR ON-unit executes the
same ERROR ON-unit, raising the ERROR condition again. In any situation where
a loop can cause the maximum nesting level to be exceeded, a message is printed
and the application is terminated. To avoid a loop caused by this situation, use the
following technique:
Chapter 15. Condition handling
353
Dynamically descendent ON-units
on error begin;
on error system;
.
.
.
end;
ON-units for file variables
An ON statement that specifies a file variable refers to the file constant that is the
current value of the variable when the ON-unit is established.
Example 1
dcl
F file,
G file variable;
G = F;
L1: on endfile(G);
L2: on endfile(F);
The statements labeled L1 and L2 are equivalent.
Example 2
declare FV file variable,
FC1 file,
FC2 file;
FV = FC1;
on endfile(FV) go to Fin;
.
.
.
FV = FC2;
read file(FC1) into (X1);
read file(FV) into (X2);
An ENDFILE condition raised during the first READ statement causes the ON-unit
to be entered, because the ON-unit refers to file FC1. If the condition is raised in
the second READ statement, however, the ON-unit is not entered, because this
READ refers to file FC2.
Example 3
E: procedure;
declare F1 file;
on endfile (F1) goto L1;
call E1 (F1);
.
.
.
E1: procedure (F2);
declare F2 file;
on endfile (F2) go to L2;
read file (F1);
read file (F2);
end E1;
An end-of-file encountered for F1 in E1 causes the ON-unit for F2 in E1 to be
entered. If the ON-unit in E1 was not specified, an ENDFILE condition
encountered for either F1 or F2 would cause entry to the ON-unit for F1 in E.
Example 4
declare FV file variable,
FC1 file,
FC2 file;
354
Enterprise PL/I for z/OS Language Reference
ON-units for file variables
do FV=FC1,FC2;
on endfile(FV) go to Fin;
end;
If an ON statement specifying a file variable is executed more than once, and the
variable has a different value each time, a different ON-unit is established at each
execution.
REVERT statement
Execution of the REVERT statement in a given block cancels the ON-unit for the
condition that executed in that block. The ON-unit that was established at the time
the block was activated is then reestablished. REVERT affects only ON statements
that are internal to the block in which the REVERT statement occurs and that have
been executed in the same invocation of that block.
,
REVERT condition
;
condition
Is any one of those described in Chapter 16, “Conditions,” on page 357 or
defined with the CONDITION attribute.
The REVERT statement cancels an ON-unit only if both of the following conditions
are true:
1. An ON statement that is eligible for reversion, and that specifies a condition
listed in the REVERT statement, was executed after the block was activated.
2. A REVERT statement with the specified condition was not previously executed
in the same block.
If either of these two conditions is not met, the REVERT statement is treated as a
null statement.
SIGNAL statement
You can raise a condition by means of the SIGNAL statement. This statement can
be used in program testing to verify the action of an ON-unit and to determine
whether the correct action is associated with the condition. The established action
is taken unless the condition is disabled.
If the specified condition is disabled, the SIGNAL statement becomes equivalent to
a null statement.
SIGNAL condition ;
Chapter 15. Condition handling
355
SIGNAL statement
condition
Is any condition described in Chapter 16, “Conditions,” on page 357 or defined
with the CONDITION attribute.
RESIGNAL statement
The RESIGNAL statement terminates the current ON-unit and allows another
ON-unit for the same condition to get control. The processing continues as if the
ON-unit executing the RESIGNAL did not exist and was never given control. It
allows multiple ON-units to get control for the same condition.
RESIGNAL ;
RESIGNAL is valid only within an ON-unit or its dynamic descendants.
Multiple conditions
A multiple condition is the simultaneous raising of two or more conditions.
The conditions for which a multiple condition can occur are:
RECORD, discussed in “RECORD condition” on page 369
TRANSMIT, discussed in “TRANSMIT condition” on page 373
The TRANSMIT condition is always processed first. The RECORD condition is
ignored unless there is a normal return from the TRANSMIT ON-unit.
Multiple conditions are processed successively. When one of the following events
occurs, no subsequent conditions are processed:
v Condition processing terminates the program, through implicit action for the
condition, normal return from an ON-unit, or abnormal termination in the
ON-unit.
v A GO TO statement transfers control from an ON-unit, so that a normal return is
prevented.
CONDITION attribute
The CONDITION attribute specifies that the declared name identifies a
programmer-defined condition.
CONDITION
A name that appears with the CONDITION condition in an ON, SIGNAL, or
REVERT statement is contextually declared to be a condition name.
The default scope is EXTERNAL. An example of the CONDITION condition
appears in “CONDITION condition” on page 360.
356
Enterprise PL/I for z/OS Language Reference
Chapter 16. Conditions
ANYCONDITION condition
AREA condition . . . .
ATTENTION condition . .
CONDITION condition . .
CONVERSION condition .
ENDFILE condition . . .
ENDPAGE condition . . .
ERROR condition . . . .
FINISH condition . . . .
FIXEDOVERFLOW condition
INVALIDOP condition . .
KEY condition . . . . .
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
357
358
359
360
361
362
363
364
365
365
366
367
NAME condition . . . . .
OVERFLOW condition . . .
RECORD condition . . . .
SIZE condition . . . . . .
STORAGE condition . . . .
STRINGRANGE condition . .
STRINGSIZE condition . . .
SUBSCRIPTRANGE condition .
TRANSMIT condition . . .
UNDEFINEDFILE condition .
UNDERFLOW condition . .
ZERODIVIDE condition . . .
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
367
368
369
370
370
371
372
373
373
374
375
376
This chapter describes conditions in alphabetic order. In general, the following
information is given for each condition:
v Status—an indication of the enabled/disabled status of the condition at the start
of the program, and how the condition can be disabled (if possible) or enabled.
Table 44 on page 350 classifies the conditions into types, shows their status, and
lists the conditions for disabling an enabled one.
v Result—the result of the operation that raised the condition. This applies when
the condition is disabled as well as when it is enabled. In some cases, the result
is undefined.
v Cause and syntax—a discussion of the condition, including the circumstances
under which the condition can be raised. Raising conditions with the SIGNAL
statement is discussed in “SIGNAL statement” on page 355.
v Implicit action—the action taken when an enabled condition is raised and no
ON-unit is currently established for the condition.
v Normal return—the point to which control is returned as a result of the normal
termination of the ON-unit. A GO TO statement that transfers control out of an
ON-unit is an abnormal ON-unit termination. If a condition (except the ERROR
condition) has been raised by the SIGNAL statement, the normal return is
always to the statement immediately following SIGNAL.
v Condition codes—the codes corresponding to the conditions and errors for
which the program is checked. An explanation for each code is given in the
“Condition codes” chapter of the Messages and Codes.
ANYCONDITION condition
Status
ANYCONDITION is always enabled.
Result
The result is the same as for the underlying condition.
Cause and syntax
SIGNAL ANYCONDITION is not allowed. ANYCONDITION can be used only
in ON (and REVERT) statements to establish (and cancel) an ON-unit which
will trap any condition, including the CONDITION condition, that occurs in a
block and which is not trapped by some other eligible ON-unit in that block.
© Copyright IBM Corp. 1999, 2012
357
ANYCONDITION
In the following example, all ERROR conditions would be handled in the
begin-block, the FINISH condition would be handled by the system, and all
other conditions would be handled by the call to the routine named
handle_All_Others.
on error
begin;
.
.
.
end;
on finish system;
on anycondition call Handle_all_others;
Note: To avoid infinite loops, the use of ON FINISH (as in the previous
example) may be necessary when ON ANYCONDITION is used.
Note that when a condition is raised, the call stack will be walked (backwards)
to search for a block that has an ON-unit for that condition. The search will
stop when the first block with such an ON-unit or with an ON
ANYCONDITION ON-unit is found. If no such ON-units are found and the
implicit action for the condition is to promote it to ERROR, the stack will then
(and only then) be walked again to search for an ON ERROR ON-unit.
You can use the ONCONDID built-in function in an ANYCONDITION
ON-unit to determine what condition is being handled, and the
ONCONDCOND built-in function to determine the name of the CONDITION
condition. Other ON built-in functions, such as ONFILE, can be used to
determine the exact cause and other related information. These built-in
functions are listed in Chapter 18, “Built-in functions, pseudovariables, and
subroutines,” on page 383.
ANYCONDITION
Abbreviation
ANYCOND
Implicit action
The implicit action is that of the underlying condition.
Normal return
Normal return is the same as for the underlying condition.
Condition codes
There are no condition codes unique to the ANYCONDITION.
AREA condition
Status
AREA is always enabled.
Result
An attempted allocation or assignment that raises the AREA condition has no
effect.
358
Enterprise PL/I for z/OS Language Reference
AREA
Cause and syntax
The AREA condition is raised in either of the following circumstances:
v When an attempt is made to allocate a based variable within an area that
contains insufficient free storage for the allocation to be made.
v When an attempt is made to perform an area assignment, and the target area
contains insufficient storage to accommodate the allocations in the source
area
You can retrieve the name of the AREA reference that raised an AREA
condition by using the ONAREA built-in function in the ON-unit. For more
information about the ONAREA built-in function, see “ONAREA” on page 555
in Chapter 18, “Built-in functions, pseudovariables, and subroutines,” on page
383.
AREA
Implicit action
A message is printed and the ERROR condition is raised.
Normal return
On normal return from the ON-unit, the action is as follows:
v If the condition was raised by an allocation and the ON-unit is a null
ON-unit, the allocation is not attempted again.
v If the condition was raised by an allocation, the allocation is attempted
again. Before the attempt is made, the area reference is reevaluated. Thus, if
the ON-unit has changed the value of a pointer qualifying the reference to
the inadequate area so that it points to another area, the allocation is
attempted again within the new area.
v If the condition was raised by an area assignment, or by a SIGNAL
statement, execution continues from the point at which the condition was
raised.
Condition codes
360, 361, 362
ATTENTION condition
Status
ATTENTION is always enabled.
Result
Raising the condition causes an ATTENTION ON-unit to be entered. If there is
no ATTENTION ON-unit, the application is terminated.
Cause and syntax
The ATTENTION condition is raised when the user hits a specific key
combination to interrupt an application. The specific key is determined by the
operating system as follows:
v On Windows, CTRL-BRK and CTRL-C. No ATTENTION ON-units will be
driven on Windows as a result of the user entering CTRL-BRK or CTRL-C
key combinations. The implicit action will be taken.
v On the host, the ATTN key, if available.
The condition can also be raised by a SIGNAL ATTENTION statement.
Chapter 16. Conditions
359
ATTENTION
ATTENTION
Abbreviation
ATTN
Implicit action
The application is terminated.
Normal return
On return from an ATTENTION ON-unit, processing is resumed at a point in
the program immediately following the point at which the condition was
raised.
Condition code
400
CONDITION condition
Status
CONDITION is always enabled.
Result
The CONDITION condition allows you to establish an ON-unit that will be
executed whenever a SIGNAL statement for the appropriate CONDITION
condition is executed.
As a debugging aid, the CONDITION condition can be used to establish an
ON-unit that prints information about the current status of the program.
Cause and syntax
The CONDITION condition is raised by a SIGNAL statement. The name
specified in the SIGNAL statement determines which CONDITION condition is
raised. The ON-unit can be executed from any point in the program through
placement of a SIGNAL statement. Normal rules of name scope apply. A
condition name is external by default, but can be declared INTERNAL.
The following example shows the use of the CONDITION condition.
dcl Test condition;
on condition (Test)
begin;
.
.
.
end;
The begin-block is executed whenever the following statement is executed:
signal condition (Test);
CONDITION (name)
Abbreviation
COND
360
Enterprise PL/I for z/OS Language Reference
CONDITION
Implicit action
A message is printed and execution continues with the statement following
SIGNAL.
Normal return
Execution continues with the statement following the SIGNAL statement.
Condition code
500
CONVERSION condition
Status
CONVERSION is enabled throughout the program, except within the scope of
the NOCONVERSION condition prefix. You can use the ONSOURCE,
ONCHAR, ONGSORCE and ONWSOURCE pseudovariables in CONVERSION
ON-units to correct conversion errors.
Result
When CONVERSION is raised, the contents of the entire result field are
undefined.
Cause and syntax
The CONVERSION computational condition is raised whenever an invalid
conversion is attempted on character, widechar or graphic data. This attempt
can be made internally or during an input/output operation. For example, the
condition is raised when:
v A character other than 0 or 1 exists in character data being converted to bit
data.
v A character value being converted to a numeric character field, or to a coded
arithmetic value, contains characters which are not the representation of an
optionally signed arithmetic constant, or an expression to represent a
complex constant.
v A graphic (DBCS) string being converted to character contains a graphic
which cannot be converted to SBCS.
v A value being converted to a character pictured item contains characters not
allowed by the picture specification.
All conversions of character data are carried out character-by-character in a
left-to-right sequence. The condition is raised for each invalid character. The
condition is also raised if all the characters are blank, with the following
exceptions:
v For input with the F-format item, a value of zero is assumed
v For input with the E-format item, be aware that sometimes the ON-unit will
be repeatedly entered.
Note that if a null string or a string of one or more blanks is assigned to a
numeric variable, the CONVERSION condition will not be raised.
When an invalid character is encountered, the current action specification for
the condition is executed (provided that CONVERSION is not disabled). If the
action specification is an ON-unit, the invalid character can be replaced within
the unit.
v For character source data, use the ONSOURCE or ONCHAR
pseudovariables.
v For widechar source data, use the ONWSOURCE or ONWCHAR
pseudovariables.
Chapter 16. Conditions
361
CONVERSION
v For graphic source data, use the ONGSOURCE pseudovariable.
If the CONVERSION condition is raised and it is disabled, the program is in
error.
If the CONVERSION condition is raised during conversion from graphic data
to nongraphic data, the ONCHAR and ONSOURCE built-in functions do not
contain valid source data. The ONGSOURCE built-in function contains the
original graphic source data. The graphic conversion is retried if the
ONGSOURCE pseudovariable is used in the CONVERSION ON-unit to
attempt to fix the graphic data that raised the CONVERSION condition. If the
ONGSOURCE pseudovariable is not used in the CONVERSION ON-unit, the
ERROR condition is raised.
CONVERSION
Abbreviation
CONV
Implicit action
A message is printed and the ERROR condition is raised.
Normal return
If CONVERSION was raised on a character string source (not graphic source)
and either ONSOURCE or ONCHAR pseudovariables are used in the ON-unit,
the program retries the conversion on return from the ON-unit.
If CONVERSION was raised on a graphic source and the ONGSOURCE
pseudovariable is used in the ON-unit, the program retries the conversion on
return from the ON-unit.
If CONVERSION was raised on a widechar source and the ONWSOURCE
pseudovariable is used in the ON-unit, the program retries the conversion on
return from the ON-unit.
If the conversion error is not corrected using these pseudovariables, the
program loops.
Condition codes
600-672
ENDFILE condition
Status
The ENDFILE condition is always enabled.
Result
If the specified file is not closed after the condition is raised, subsequent GET
or READ statements to the file are unsuccessful and cause additional ENDFILE
conditions to be raised.
But the file must not be closed in its ENDFILE ON-unit: it should be closed
only after that ON-unit has been exited.
Cause and syntax
The ENDFILE input/output condition can be raised during an operation by an
362
Enterprise PL/I for z/OS Language Reference
ENDFILE
attempt to read past the end of the file specified in the GET or READ
statement. It applies only to SEQUENTIAL INPUT, SEQUENTIAL UPDATE,
and STREAM INPUT files.
In record-oriented data transmission, ENDFILE is raised whenever an end of
file is encountered during the execution of a READ statement.
In stream-oriented data transmission, ENDFILE is raised during the execution
of a GET statement if an end of file is encountered either before any items in
the GET statement data list have been transmitted or between transmission of
two of the data items. If an end of file is encountered while a data item is
being processed, or if it is encountered while an X-format item is being
processed, the ERROR condition is raised.
ENDFILE
(file-reference)
file-reference
The file reference must be a scalar reference. If a file reference is
omitted, SYSIN is assumed.
Implicit action
A message is printed and the ERROR condition is raised.
Normal return
Execution continues with the statement immediately following the GET or
READ statement that raised the ENDFILE.
If a file is closed in an ON-unit for this condition, the results of normal return
are undefined. Exit from the ON-unit with the closed file must be achieved
with a GO TO statement.
Condition code
70
ENDPAGE condition
Status
ENDPAGE is always enabled.
Result
When ENDPAGE is raised, the current line number is one greater than that
specified by the PAGESIZE option (default is 60) so that it is possible to
continue writing on the same page. The ON-unit can start a new page by
execution of a PAGE option or a PAGE format item, which sets the current line
to one.
If the ON-unit does not start a new page, the current line number can increase
indefinitely. If a subsequent LINE option or LINE format item specifies a line
number that is less than or equal to the current line number, ENDPAGE is not
raised, but a new page is started with the current line set to one. An exception
is that if the current line number is equal to the specified line number, and the
file is positioned on column one of the line, ENDPAGE is not raised.
If ENDPAGE is raised during data transmission, on return from the ON-unit,
the data is written on the current line, which might have been changed by the
Chapter 16. Conditions
363
ENDPAGE
ON-unit. If ENDPAGE results from a LINE or SKIP option, on return from the
ON-unit, the action specified by LINE or SKIP is ignored.
Cause and syntax
The ENDPAGE input/output condition is raised when a PUT statement results
in an attempt to start a new line beyond the limit specified for the current
page. This limit can be specified by the PAGESIZE option in an OPEN
statement; if PAGESIZE has not been specified, a default limit of 60 is applied.
The attempt to exceed the limit can be made during data transmission
(including associated format items, if the PUT statement is edit-directed), by
the LINE option, or by the SKIP option. ENDPAGE can also be raised by a
LINE option or LINE format item that specified a line number less than the
current line number. ENDPAGE is raised only once per page, except when it is
raised by the SIGNAL statement.
ENDPAGE
(file-reference)
file-reference
The file reference must be a scalar reference. If a file reference is
omitted, SYSPRINT is assumed.
Implicit action
A new page is started. If the condition is signalled, execution is unaffected and
continues with the statement following the SIGNAL statement.
Normal return
Execution of the PUT statement continues in the manner described above.
Condition code
90
ERROR condition
Status
ERROR is always enabled.
Result
An error message is issued if no ON-unit is active when the ERROR condition
arises or if the ON-unit does not use a GOTO (to exit the block) to recover
from the condition.
Cause and syntax
The ERROR condition is the implicit action for many conditions. This provides
a common condition that can be used to check for a number of different
conditions, rather than checking each condition separately.
The ERROR condition is raised under the following circumstances:
v As a result of the implicit action for a condition, which is to raise the
ERROR condition
v As a result of the normal return action for some conditions, such as
SUBSCRIPTRANGE CONVERSION or when no retry is attempted
v As a result of an error (for which there is no other PL/I-defined condition)
during program execution
v As a result of a SIGNAL ERROR statement
364
Enterprise PL/I for z/OS Language Reference
ERROR
In order to prevent a loop of ERROR conditions, the first statement in any ON
ERROR block should be ON ERROR SYSTEM;
ERROR
Implicit action
The message is printed and the FINISH condition is raised.
Normal return
The implicit action is taken.
Condition codes
All codes 1000 and above are ERROR conditions.
FINISH condition
Status
FINISH is always enabled.
Result
Control passes to the FINISH ON-unit and processing continues.
Cause and syntax
The FINISH condition is raised during execution of a statement that would
terminate the procedures. The following actions take place:
v If the termination is normal—the FINISH ON-unit, if established, is given
control only if the main procedure is PL/I.
v If the termination is abnormal—the FINISH ON-unit, if established in an
active block, is given control.
FINISH
Implicit action
v If the condition is raised in the major task, no action is taken and processing
continues from the point where the condition was raised.
v If the condition is raised as part of the implicit action for another condition,
the program is terminated.
Normal return
Processing resumes at the point where the condition was raised. This point is
the statement following the SIGNAL statement if the conditions was signalled.
Condition code
4
FIXEDOVERFLOW condition
Status
FIXEDOVERFLOW is enabled throughout the program, except within the
scope of the NOFIXEDOVERFLOW condition prefix.
Chapter 16. Conditions
365
FIXEDOVERFLOW
Result
The result of the invalid FIXED DECIMAL operation is undefined.
Cause and syntax
The FIXEDOVERFLOW computational condition is raised when the length of
the result of a FIXED DECIMAL arithmetic operation exceeds the maximum
length allowed by the implementation.
The FIXEDOVERFLOW condition is not raised for FIXED BINARY operations.
The FIXEDOVERFLOW condition differs from the SIZE condition in that SIZE
is raised when a result exceeds the declared size of a variable, while
FIXEDOVERFLOW is raised when a result exceeds the maximum allowed by
the computer.
If the FIXEDOVERFLOW condition is raised and it is disabled, the program is
in error.
FIXEDOVERFLOW
Abbreviation
FOFL
Implicit action
A message is printed and the ERROR condition is raised.
Normal return
Control returns to the point immediately following the point at which the
condition was raised.
Condition code
310
Note: If the SIZE condition is disabled, an attempt to assign an oversize number to
a fixed decimal variable can raise the FIXEDOVERFLOW condition.
INVALIDOP condition
Status
INVALIDOP is enabled throughout the program, except within the scope of the
NOINVALIDOP condition prefix.
Result
The result of the invalid operation is undefined.
Cause and syntax
The INVALIDOP computational condition is raised when any of the following
are detected during the evaluation of IEEE floating-point expressions.
v Subtraction of two infinities
v Multiplication of infinity by 0
v Division of two infinities
v Division of zero by zero
v Invalid floating-point data
366
Enterprise PL/I for z/OS Language Reference
INVALIDOP
INVALIDOP
Implicit action
The ERROR condition is raised.
Normal return
A message is printed and the ERROR condition is raised.
Condition code
290
KEY condition
Status
KEY is always enabled.
Result
The keyed record is undefined, and the statement in which it appears is
ignored.
Cause and syntax
The KEY input/output condition is raised when a record with a specified key
cannot be found. The condition can be raised only during operations on keyed
records. It is raised for the condition codes listed below.
When a LOCATE statement is used for the data set, the KEY condition for this
LOCATE statement is not raised until the next WRITE or LOCATE statement
for the file, or when the file is closed.
KEY (file-reference)
The file-reference must be a scalar reference.
Implicit action
A message is printed and the ERROR condition is raised.
Normal return
Control passes to the statement immediately following the statement that
raised KEY.
If a file is closed in an ON-unit for this condition, the results of normal return
are undefined. Exit from the ON-unit with the closed file must be achieved
with a GO TO statement.
Condition codes
50-58
NAME condition
Status
NAME is always enabled.
Result
The named data is undefined.
Chapter 16. Conditions
367
NAME
Cause and syntax
The NAME input/output condition can be raised only during execution of a
data-directed GET statement with the FILE option. It is raised in any of the
following situations:
v The syntax is not correct, as described under “Syntax of data-directed data”
on page 308.
v The name is missing or invalid, for example:
– No counterpart is found in the data list.
– If there is no data list, the name is not known in the block.
– A qualified name is not fully qualified.
– DBCS contains a byte outside the valid range '41'X to 'FE'X.
v A subscript list is missing or invalid, for example.
– A subscript is missing.
– The number of subscripts is incorrect.
– More than 10 digits are in a subscript (leading zeros ignored).
– A subscript is outside the allowed range of the current allocation of the
variable.
You can retrieve the incorrect data field by using the built-in function
DATAFIELD in the ON-unit.
NAME (file-reference)
The file-reference must be a scalar reference.
Implicit action
The incorrect data field is ignored, a message is printed, and execution of the
GET statement continues.
Normal return
The execution of the GET statement continues with the next name in the
stream.
Condition code
10
OVERFLOW condition
Status
OVERFLOW is enabled throughout the program, except within the scope of
the NOOVERFLOW condition prefix.
Result
The value of such an invalid floating-point number is undefined.
Cause and syntax
The OVERFLOW computational condition is raised when the magnitude of a
floating-point number exceeds the maximum allowed.
The OVERFLOW condition differs from the SIZE condition in that SIZE is
raised when a result exceeds the declared size of a variable, while OVERFLOW
is raised when a result exceeds the maximum allowed by the computer.
If the OVERFLOW condition is raised and it is disabled, the program is in
error.
368
Enterprise PL/I for z/OS Language Reference
OVERFLOW
OVERFLOW
Abbreviation
OFL
Implicit action
A message is printed and the ERROR condition is raised.
Normal return
The ERROR condition is raised.
Condition code
300
RECORD condition
Status
RECORD is always enabled.
Result
The length prefix for the specified file can be inaccurately transmitted.
Cause and syntax
The RECORD input/output condition is raised if the specified record is
truncated. The condition can be raised only during a READ, WRITE, LOCATE,
or REWRITE operation.
If the SCALARVARYING option is applied to the file (it must be applied to a
file using locate mode to transmit varying-length strings), a 2-byte length
prefix is transmitted with an element varying-length string. The length prefix is
not reset if the RECORD condition is raised. If the SCALARVARYING option is
not applied to the file, the length prefix is not transmitted. On input, the
current length of a varying-length string is set to the shorter of the record
length and the maximum length of the string.
RECORD (file-reference)
The file-reference must be a scalar reference.
Implicit action
A message is printed and the ERROR condition is raised.
Normal return
Execution continues with the statement immediately following the one for
which RECORD was raised.
If a file is closed in an ON-unit for this condition, the results of normal return
are undefined. Exit from the ON-unit with the closed file must be achieved
with a GO TO statement.
Condition codes
20-24
Chapter 16. Conditions
369
SIZE
SIZE condition
Status
SIZE is disabled throughout the program, except within the scope of the SIZE
condition prefix.
Result
The result of the assignment is undefined.
Cause and syntax
The SIZE computational condition is raised only when high-order (that is,
leftmost) significant binary or decimal digits are lost in an attempted
assignment to a variable or an intermediate result or in an input/output
operation. This loss can result from a conversion involving different data types,
different bases, different scales, or different precisions. Even if the SIZE
condition is disabled, any conversion that is not done inline may cause the
condition to be raised.
SIZE is raised when the size of the value being assigned to a data item exceeds
the declared (or default) size of the data item, even if this is not the actual size
of the storage that the item occupies. For example, a fixed binary item of
precision (20) occupies a fullword in storage, but SIZE is raised if a value
whose size exceeds FIXED BINARY(20) is assigned to it.
In optimized code, FOFL may be raised instead of SIZE.
Because checking sizes requires substantial overhead in both storage space and
run time, the SIZE condition is primarily used for program testing. It can be
removed from production programs. For more information on test and
production application programs, see the Programming Guide.
The SIZE condition differs from the FIXEDOVERFLOW condition in that
FIXEDOVERFLOW is raised when the size of a calculated fixed-point value
exceeds the maximum allowed by the implementation. SIZE can be raised on
assignment of a value regardless of whether or not FIXEDOVERFLOW was
raised in the calculation of that value.
If the SIZE condition is raised and it is disabled, the program is in error.
SIZE
Implicit action
A message is printed and the ERROR condition is raised.
Normal return
Control returns to the point immediately following the point at which the
condition was raised.
Condition codes
340, 341
STORAGE condition
Status
STORAGE is always enabled.
370
Enterprise PL/I for z/OS Language Reference
STORAGE
Result
The result depends on the type of variable for which attempted storage
allocation raised the condition.
v After an ALLOCATE statement for a controlled variable, that variable's
generation is not allocated. A reference to that controlled variable results in
accessing the generation (if any) before the ALLOCATE statement.
v After an ALLOCATE statement for a based variable, the variable is not
allocated and its associated pointer is undefined.
v After an ALLOCATE built-in function for a based variable, the variable is
not allocated and the use of the associated pointer is undefined.
Cause and syntax
The STORAGE condition allows the program to gain control for the failure of
an ALLOCATE built-in function or ALLOCATE statement that attempted to
allocate BASED or CONTROLLED storage outside of an AREA. Failure of an
ALLOCATE statement in an AREA raises the AREA condition.
Failure of the AUTOMATIC built-in function does not raise the STORAGE
condition.
The ON-unit for the STORAGE condition can attempt to free allocated storage.
If the ON-unit is unable to free sufficient storage, it can provide the necessary
steps to terminate the program without losing diagnostic information.
STORAGE
Implicit action
The ERROR condition is raised.
Normal return
The ERROR condition is raised.
Condition codes
450, 451
STRINGRANGE condition
Status
STRINGRANGE is disabled throughout the program, except within the scope
of the STRINGRANGE condition prefix.
Result
The value of the specified SUBSTR is altered.
Cause and syntax
The STRINGRANGE program-checkout condition is raised whenever the
values of the arguments to a SUBSTR reference fail to comply with the rules
described for the SUBSTR built-in function. It is raised for each reference to an
invalid argument.
STRINGRANGE
Chapter 16. Conditions
371
STRINGRANGE
Abbreviation
STRG
Implicit action
A message is printed and processing continues as described for normal return.
Normal return
Execution continues with a revised SUBSTR reference for which the value is
defined as follows:
Assuming that the length of the source string (after execution of the ON-unit,
if specified) is k, the starting point is i, and the length of the substring is j:
v If i is greater than k, the value is the null string.
v If i is less than or equal to k, the value is that substring beginning at the mth
character, bit, widechar or graphic of the source string and extending n
characters, bits, widechars or graphics, where m and n are defined by:
M = max( I,1 )
N = max( 0,min( J + min(I,1) - 1,K - M + 1 ))
if J is specified.
N = K - M + 1
if J is not specified.
This means that the new arguments are forced within the limits.
The values of i and j are established before entry to the ON-unit. They are not
reevaluated on return from the ON-unit.
The value of k might change in the ON-unit if the first argument of SUBSTR is
a varying-length string. The value n is computed on return from the ON-unit
using any new value of k.
Condition code
350
STRINGSIZE condition
Status
STRINGSIZE is disabled throughout the program, except within the scope of
the STRINGSIZE condition prefix.
Result
After the condition action, the truncated string is assigned to its target string.
The right-hand characters, bits, widechars or graphics of the source string are
truncated so that the target string can accommodate the source string.
Cause and syntax
The STRINGSIZE program-checkout condition is raised when you attempt to
assign a string to a target with a shorter maximum length.
STRINGSIZE
Abbreviation
STRZ
372
Enterprise PL/I for z/OS Language Reference
STRINGSIZE
Implicit action
A message is printed and processing continues.
Normal return
Execution continues from the point at which the condition was raised.
Condition codes
150, 151
SUBSCRIPTRANGE condition
Status
SUBSCRIPTRANGE is disabled throughout the program, except within the
scope of the SUBSCRIPTRANGE condition prefix.
Result
When SUBSCRIPTRANGE has been raised, the value of the invalid subscript is
undefined, and, hence, the reference is also undefined.
Cause and syntax
The SUBSCRIPTRANGE program-checkout condition is raised whenever a
subscript is evaluated and found to lie outside its specified bounds. The order
of raising SUBSCRIPTRANGE relative to evaluation of other subscripts is
undefined.
SUBSCRIPTRANGE
Abbreviation
SUBRG
Implicit action
A message is printed and the ERROR condition is raised.
Normal return
Normal return from a SUBSCRIPTRANGE ON-unit raises the ERROR
condition.
Condition codes
520
TRANSMIT condition
Status
TRANSMIT is always enabled.
Result
Raising the TRANSMIT condition indicates that any data transmitted is
potentially incorrect.
Cause and syntax
The TRANSMIT input/output condition can be raised during any
input/output operation. It is raised by an uncorrectable transmission error of a
record (or of a block, if records are blocked), which is an input/output error
that could not be corrected during execution. It can be caused by a damaged
recording medium, or by incorrect specification or setup.
Chapter 16. Conditions
373
TRANSMIT
During input, TRANSMIT is raised after transmission of the potentially
incorrect record. If records are blocked, TRANSMIT is raised for each
subsequent record in the block.
During output, TRANSMIT is raised after transmission. If records are blocked,
transmission occurs when the block is complete rather than after each output
statement.
When a spanned record is being updated, the TRANSMIT condition is raised
on the last segment of a record only. It is not raised for any subsequent records
in the same block, although the integrity of these records cannot be assumed.
TRANSMIT (file-reference)
The file-reference must be a scalar reference.
Implicit action
A message is printed and the ERROR condition is raised.
Normal return
Processing continues as though no error had occurred, allowing another
condition (for example, RECORD) to be raised by the statement or data item
that raised the TRANSMIT condition.
If a file is closed in an ON-unit for this condition, the results of normal return
are undefined. Exit from the ON-unit with the closed file must be achieved
with a GO TO statement.
Condition codes
40-46
UNDEFINEDFILE condition
Status
UNDEFINEDFILE is always enabled.
Result
Specified files are undefined to the application program.
Cause and syntax
The UNDEFINEDFILE input/output condition is raised whenever an
unsuccessful attempt to open a file is made. If the attempt is made by means
of an OPEN statement that specifies more than one file, the condition is raised
after attempts to open all specified files.
If UNDEFINEDFILE is raised for more than one file in the same OPEN
statement, ON-units are executed according to the order of appearance (taken
from left to right) of the file names in that OPEN statement.
If UNDEFINEDFILE is raised by an implicit file opening in a data transmission
statement, upon normal return from the ON-unit, processing continues with
the remainder of the data transmission statement. If the file was not opened in
the ON-unit, the statement cannot continue and the ERROR condition is raised.
The UNDEFINEDFILE condition is raised not only by conflicting attributes
(such as DIRECT with PRINT), but also by the following:
v Block size smaller than record size (except when records are spanned)
374
Enterprise PL/I for z/OS Language Reference
UNDEFINEDFILE
v LINESIZE exceeding the maximum allowed
v KEYLENGTH zero or not specified for creation of INDEXED data sets
v Specifying a KEYLOC option, for an INDEXED data set, with a value
resulting in KEYLENGTH + KEYLOC exceeding the record length
v Specifying a V-format logical record length of less than 18 bytes for
STREAM data sets
v Specifying a block size that is not an integral multiple of the record size for
FB-format records
v Specifying a logical record length that is not at least 4 bytes smaller than the
specified block size for VB-format records.
UNDEFINEDFILE (file-reference)
The file-reference must be a scalar reference.
Abbreviation
UNDF
Implicit action
A message is printed and the ERROR condition is raised.
Normal return
Upon the normal completion of the final ON-unit, control is given to the
statement immediately following the statement that raised the condition.
Condition codes
80-89, 91-95
UNDERFLOW condition
Status
UNDERFLOW is enabled throughout the program, except within the scope of
the NOUNDERFLOW condition prefix.
Result
The invalid floating-point value is set to 0 except for IEEE floating-point on
z/OS when the result is undefined.
Cause and syntax
The UNDERFLOW computational condition is raised when the magnitude of a
floating-point number is smaller than the minimum allowed. save
UNDERFLOW is not raised when equal numbers are subtracted (often called
significance error).
The expression X(-Y) (where Y>0) can be evaluated by taking the reciprocal of
XY; hence, the OVERFLOW condition might be raised instead of the
UNDERFLOW condition.
UNDERFLOW
Chapter 16. Conditions
375
UNDERFLOW
Abbreviation
UFL
Implicit action
Unless the exception is raised while evaluating an IEEE floating-point
expression (in either binary or decimal) on z/OS, a message is printed, and
execution continues from the point at which the condition was raised; if raised
while evaluating an IEEE floating-point exception on z/OS, a message is
printed and the ERROR condition is raised.
Normal return
Unless the exception is raised while evaluating an IEEE floating-point
expression (in either binary or decimal) on z/OS, control returns to the point
immediately following the point at which the condition was raised; if raised
while evaluating an IEEE floating-point exception on z/OS, the ERROR
condition is raised.
Condition code
330
ZERODIVIDE condition
Status
ZERODIVIDE is enabled throughout the program, except within the scope of
the NOZERODIVIDE condition prefix.
Result
The result of a division by zero is undefined.
Cause and syntax
The ZERODIVIDE computational condition is raised when an attempt is made
to divide by zero. This condition is raised for fixed-point and floating-point
division. If the numerator of a floating-point divide is also zero, INVALIDOP is
raised.
If the ZERODIVIDE condition is raised and it is disabled, the program is in
error.
ZERODIVIDE
Abbreviation
ZDIV
Implicit action
A message is printed and the ERROR condition is raised.
Normal return
The ERROR condition is raised.
Condition code
320
376
Enterprise PL/I for z/OS Language Reference
Chapter 17. Multithreading facility
Creating a thread . .
ATTACH statement .
Examples . . . .
Terminating a thread .
Waiting for a thread to
Detaching a thread .
. . .
. . .
. . .
. . .
complete
. . .
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
378
378
379
379
379
380
Condition handling . . . .
Task data and attribute . . .
THREADID built-in function
Sharing data between threads .
Sharing files between threads .
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
380
380
381
381
381
A PL/I program is a set of one or more procedures. The program normally
executes as a single execution unit, or as part of a single execution unit. 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. This execution with a single flow of control is synchronous
flow.
When using the PL/I multithreading facility, the invoking procedure does not
relinquish control to the invoked procedure. Instead, an additional flow of control
is established so that both procedures are executed concurrently. The execution of
such concurrent procedures is called asynchronous flow.
The PL/I multithreading facility allows the execution of parts of a PL/I program
asynchronously in multiple threads. A thread is a unit of work that competes for
the resources of the computing system. A thread is not the equivalent of a task in
OS PL/I. Except for the main thread in a program, a thread is always independent
of and unrelated to other threads in the program. When a procedure invokes
another procedure as a thread, this action is known as attaching, or creating the
thread.
Execution of one or more threads occurs in a process, which can be thought of as a
PL/I program. PL/I does not provide the capabilities to create and manage
multiple processes or tasks, but it does allow creation and management of multiple
threads in a single program (process).
There is normally one application thread per process. Multiple threads can be
attached (created) to:
v Perform a piece of work in a shorter elapsed time. Such applications can be
batch applications that are not interacting with the user. For example, one
procedure could attach a thread which would compile a PL/I program.
v Perform high response parts of a program in one thread and I/O parts in
another thread, and typical response parts in a third.
v Use computing system resources that might be idle. These resources can include
I/O devices as well as the CPUs.
v Implement real-time multi-user applications where the response time is critical.
v Isolate independent pieces of work for reliability. That is, the failure of a part of
a job can be isolated while other independent parts are processed.
Note: Operating system services must not be directly used when PL/I provides
the appropriate function.
© Copyright IBM Corp. 1999, 2012
377
Creating a thread
Creating a thread
A thread:
v Is an independent unit of work
v Executes concurrently and independently of other threads in the process and
system
v Can attach other threads
v Can wait for a thread to complete
v Can stop itself or another thread
Any procedures or functions synchronously invoked by the thread become part of
the thread’s execution.
ATTACH statement
A thread is attached (or created) by the execution of the ATTACH statement. You
can specify explicit characteristics for the thread if the defaults are not what you
want.
ATTACH entry-reference
THREAD (task-reference)
;
ENVIRONMENT (
)
TSTACK(expression)
entry
Specifies the name of a limited entry variable, or the name of an external entry
or level-1 procedure. It cannot be the name of an internal procedure or a
fetchable procedure. The ATTACHed entry must be declared as having no
parameters or as having exactly one BYVALUE POINTER parameter. However,
you can fetch a procedure, assign it to a limited entry variable, and then attach
the entry variable as a thread.
Arguments can be passed to the new thread just as you would pass arguments
to a synchronous entry in a CALL statement.
THREAD (task reference)
Specifies the name of a task variable that becomes associated with the thread.
The task variable can then be used to refer to the thread.
Unless explicitly declared, the named variable is given a contextual declaration.
If the THREAD option is not specified, the attached thread cannot be stopped
or waited upon by another thread.
If a thread is attached with the THREAD option, it should be detached using
the DETACH statement (see “Detaching a thread” on page 380) to free all the
system resources associated with the thread.
Operating system services must not be used directly to create a thread.
ENVIRONMENT (abbrev: ENV)
Specifies environmental characteristics and is usually operating system
dependent.
378
Enterprise PL/I for z/OS Language Reference
ATTACH statement
TSTACK (expression)
On Intel, specifies the size of the stack to be used for the attached thread. The
expression should be FIXED BINARY(31,0). If the stack size is not specified,
the run-time default will be used.
On z/OS, TSTACK is ignored, and the size of the stack is determined by LE.
Examples
attach input (File1);
attach input (File2)
thread (T2);
An attached procedure may have any supported linkage.
Terminating a thread
A thread is terminated when any of the following occurs:
v The END statement corresponding to the first procedure (the initial procedure in
the thread) is reached.
v The ERROR condition is raised and either there is no ERROR ON-unit or the
ERROR ON-unit terminates normally (reaches the END statement for the
ON-unit or executes a RESIGNAL statement).
v The EXIT statement is executed in any procedure within the thread.
v The initial thread in the program terminates.
v The STOP statement is executed in any thread within the program. This stops
the entire program, causing all threads, including the main thread, to be
terminated.
The FINISH condition is raised only in the thread initiating program termination.
Any ON-units established within the thread are given control before the thread
actually terminates.
Except as noted above, when a thread terminates, no other threads are terminated,
unless the thread being terminated is the main thread. In that case, all other
threads are stopped and terminated before the main thread is terminated.
When a thread terminates, only its stack space is released. All other resources such
as allocated storage, open files, etc. remain intact. The user must ensure that any
resources a thread has acquired are released and open files are closed, unless they
are needed by other threads that are still active.
When the main thread terminates, all resources are released and files are closed.
Waiting for a thread to complete
To wait for a thread, use the WAIT statement.
WAIT THREAD (task-reference) ;
THREAD (task-reference)
The THREAD option specifies the thread upon which the process is waiting.
Chapter 17. Multithreading facility
379
Waiting for a thread
The current thread is suspended until the specified thread terminates. As soon
as the specified thread has terminated, the current thread resumes.
WAIT THREAD (TI1);
Detaching a thread
The DETACH statement should be used to free the system resources associated
with a thread that was attached with the THREAD option.
DETACH THREAD (task-reference) ;
THREAD (task-reference)
The THREAD option specifies the thread to be detached.
Normally, this statement would be executed immediately after the WAIT statement
for the terminating thread.
Condition handling
When a new thread is created, no ON-units are assumed to be established. The
ON-units which are in effect at the time a thread is created are not inherited by the
new attached thread. Conditions that occur within a thread are handled within the
thread and are not handled across thread boundaries.
For example, assume that thread A opens file F; then, A creates thread T. T then
causes the ENDFILE condition to be raised. If an ON ENDFILE condition, is not
established in thread T itself, the ERROR condition is raised in T and the usual
condition handling takes place all within thread T. Whether or not A has
established ON-units for ENDFILE or ERROR does not affect the execution of
thread T.
A thread must establish ON-units for appropriate conditions if it wishes to handle
them. There is no mechanism to signal conditions across threads.
If CTRL-BREAK is used to raise the ATTENTION condition, the ATTENTION
condition is raised only in the main thread, not in any threads created by ATTACH
statements.
Task data and attribute
Task variables hold thread related information, such as thread identification,
service category, and dispatching priority. A variable is given the TASK attribute by
explicit declaration, or implicitly by appearing in a THREAD option.
TASK
380
Enterprise PL/I for z/OS Language Reference
Task data and attribute
A task variable is associated with a thread by the task reference in the THREAD
option of the ATTACH statement creating the thread. A task variable is active if it
is associated with a thread that is active. A task variable must be allocated before it
is associated with a thread and must not be freed while it is active. An active task
variable cannot be associated with another thread.
THREADID built-in function
THREADID (short for thread identifier) returns a POINTER value that is the
address of the operating system thread identifier for an attached thread.
THREADID (
x )
The value used by this built-in function can be used as a parameter to system
functions such as DosSetPriority, but it should not be used as a parameter to
DosKillThread.
x
Task reference. The value of x should have been set previously in the THREAD
option of the ATTACH statement.
Sharing data between threads
All static and controlled data is shared between threads. All other data can also be
shared via arguments/parameters and via based references, as long as the data is
allocated and is not freed until all of the threads have finished using the data. For
example, if automatic variables in the attaching thread are shared with the attached
thread, the attaching block must not terminate until the attached thread has
finished using the shared variables.
Serialization of data is the responsibility of the user. If new generations of
controlled data are allocated or if existing generations are freed, it is possible to
have certain threads still accessing an older generation or a generation that no
longer exists. This can lead to unpredictable results.
All allocated storage, unless freed explicitly, is not freed until program termination.
PL/I does not serialize either ALLOCATEs or FREEs in AREA variables.
Sharing files between threads
All files are shared between threads. If a thread (other than MAIN) opens a file, it
must be closed before that thread terminates.
A file opened in a MAIN thread is not closed until it is explicitly closed or the
program ends. Except for the Language Environment message file on z/OS, if you
do not serialize your file usage, you might get unpredictable results, possibly
including abends.
Serialization is the responsibility of the user. Refer to “Sharing data between
threads.”
The message file and the display statement are automatically serialized by PL/I.
Chapter 17. Multithreading facility
381
382
Enterprise PL/I for z/OS Language Reference
Chapter 18. Built-in functions, pseudovariables, and
subroutines
Declaring and invoking built-in functions,
pseudovariables, and built-in subroutines . . . .
BUILTIN attribute . . . . . . . . . . .
Example 1 . . . . . . . . . . . .
Invoking built-in functions and pseudovariables
Invoking built-in subroutines . . . . . . .
Specifying arguments for built-in functions,
pseudovariables, and built-in subroutines . . . .
Aggregate arguments. . . . . . . . . .
Null and optional arguments . . . . . . .
Accuracy of mathematical functions . . . . . .
Categories of built-in functions . . . . . . .
Arithmetic built-in functions . . . . . . .
Array-handling built-in functions. . . . . .
Buffer-management built-in functions . . . .
Condition-handling built-in functions . . . .
Date/time built-in functions . . . . . . .
Floating-point inquiry built-in functions . . .
Floating-point manipulation built-in functions
Input/output built-in functions . . . . . .
Integer manipulation built-in functions . . . .
Mathematical built-in functions . . . . . .
Miscellaneous built-in functions . . . . . .
Ordinal-handling built-in functions . . . . .
Precision-handling built-in functions . . . .
Pseudovariables . . . . . . . . . . .
Storage control built-in functions . . . . . .
String-handling built-in functions. . . . . .
Subroutines . . . . . . . . . . . . .
ABS . . . . . . . . . . . . . . . .
ACOS . . . . . . . . . . . . . . . .
ADD . . . . . . . . . . . . . . . .
ADDR. . . . . . . . . . . . . . . .
ADDRDATA . . . . . . . . . . . . .
ALL . . . . . . . . . . . . . . . .
ALLCOMPARE. . . . . . . . . . . . .
ALLOCATE . . . . . . . . . . . . . .
ALLOCATION . . . . . . . . . . . . .
ALLOCSIZE . . . . . . . . . . . . . .
ANY . . . . . . . . . . . . . . . .
ASIN . . . . . . . . . . . . . . . .
ATAN . . . . . . . . . . . . . . . .
ATAND . . . . . . . . . . . . . . .
ATANH . . . . . . . . . . . . . . .
AUTOMATIC . . . . . . . . . . . . .
AVAILABLEAREA . . . . . . . . . . .
Example . . . . . . . . . . . . . .
BINARY . . . . . . . . . . . . . . .
BINARYVALUE . . . . . . . . . . . .
BIT . . . . . . . . . . . . . . . . .
BITLOCATION . . . . . . . . . . . . .
BOOL . . . . . . . . . . . . . . . .
BYTE . . . . . . . . . . . . . . . .
CDS . . . . . . . . . . . . . . . .
© Copyright IBM Corp. 1999, 2012
386
386
387
387
387
388
388
388
388
389
389
390
390
391
392
394
395
395
396
396
397
398
398
399
399
401
402
404
405
406
407
408
409
410
411
412
413
414
415
416
417
418
419
420
420
421
422
423
424
425
426
427
CEIL . . . . . . . .
CENTERLEFT . . . . .
Example . . . . . .
CENTRELEFT . . . . .
CENTERRIGHT . . . .
Example . . . . . .
CENTRERIGHT . . . .
CHARACTER . . . . .
Example . . . . . .
CHARGRAPHIC . . . .
Example 1 . . . . .
Example 2 . . . . .
CHARVAL . . . . . .
CHECKSTG . . . . . .
COLLATE . . . . . .
COMPARE . . . . . .
Example . . . . . .
COMPLEX . . . . . .
CONJG . . . . . . .
COPY . . . . . . . .
COS . . . . . . . .
COSD . . . . . . . .
COSH . . . . . . . .
COUNT . . . . . . .
CS . . . . . . . . .
CURRENTSIZE. . . . .
CURRENTSTORAGE . . .
DATAFIELD. . . . . .
DATE . . . . . . . .
DATETIME . . . . . .
DAYS . . . . . . . .
Example . . . . . .
DAYSTODATE . . . . .
DAYSTOSECS . . . . .
DECIMAL . . . . . .
DIMENSION . . . . .
DIVIDE . . . . . . .
EDIT . . . . . . . .
Example . . . . . .
EMPTY . . . . . . .
ENDFILE. . . . . . .
ENTRYADDR . . . . .
ENTRYADDR pseudovariable
EPSILON . . . . . . .
ERF . . . . . . . .
ERFC . . . . . . . .
EXP . . . . . . . .
EXPONENT . . . . . .
FILEDDINT . . . . . .
FILEDDTEST . . . . .
FILEDDWORD . . . . .
FILEID . . . . . . .
FILEOPEN . . . . . .
FILEREAD . . . . . .
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
428
429
429
430
431
431
432
433
433
434
434
434
435
436
437
438
438
439
440
441
442
443
444
445
446
448
449
450
451
452
453
453
454
455
456
457
458
459
459
460
461
462
463
464
465
466
467
468
469
470
471
472
473
474
383
Built-in functions, pseudovariables, and subroutines
FILESEEK . . . .
FILETELL . . . .
FILEWRITE . . . .
FIXED . . . . . .
FIXEDBIN . . . .
FIXEDDEC . . . .
FLOAT . . . . .
FLOATBIN . . . .
FLOATDEC . . . .
FLOOR . . . . .
GAMMA . . . . .
GETENV . . . . .
GRAPHIC . . . .
Example 1 . . .
Example 2 . . .
HANDLE . . . .
HBOUND . . . .
HBOUNDACROSS .
HEX . . . . . .
Example 1 . . .
Example 2 . . .
HEXIMAGE . . . .
HIGH . . . . . .
HUGE . . . . . .
IAND . . . . . .
IEOR . . . . . .
IMAG . . . . . .
IMAG pseudovariable
INDEX . . . . .
Example . . . .
INDICATORS . . .
INOT . . . . . .
Examples . . . .
IOR . . . . . .
ISFINITE . . . . .
ISIGNED . . . . .
Examples . . . .
ISINF . . . . . .
ISLL . . . . . .
Examples . . . .
ISMAIN . . . . .
ISNAN . . . . .
ISNORMAL . . . .
ISRL . . . . . .
Examples . . . .
ISZERO . . . . .
IUNSIGNED . . .
Examples . . . .
LBOUND. . . . .
LBOUNDACROSS. .
LEFT . . . . . .
Example . . . .
LENGTH . . . . .
LINENO . . . . .
LOCATION . . . .
Example . . . .
LOG . . . . . .
LOGGAMMA . . .
LOG2 . . . . . .
LOG10 . . . . .
LOW . . . . . .
384
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
Enterprise PL/I for z/OS Language Reference
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
475
476
477
478
479
480
481
482
483
484
485
486
487
487
487
489
490
491
492
492
492
494
495
496
497
498
499
500
501
501
502
503
503
504
505
506
506
507
508
508
509
510
511
512
512
513
514
514
515
516
517
517
518
519
520
520
521
522
523
524
525
LOWERCASE . . . . . . . . . . . .
LOWER2 . . . . . . . . . . . . . .
Examples . . . . . . . . . . . . .
MAX . . . . . . . . . . . . . . .
MAXEXP . . . . . . . . . . . . . .
Example (Intel Values) . . . . . . . .
Example (AIX Values) . . . . . . . .
Example (z/OS Hexdecimal Values) . . . .
Example (z/OS IEEE Binary Floating Point
Values) . . . . . . . . . . . . .
Example (z/OS IEEE Decimal Floating Point
Values) . . . . . . . . . . . . .
MAXLENGTH . . . . . . . . . . . .
Example . . . . . . . . . . . . .
MEMCONVERT . . . . . . . . . . .
MEMCU12 . . . . . . . . . . . . .
MEMCU14 . . . . . . . . . . . . .
MEMCU21 . . . . . . . . . . . . .
MEMCU24 . . . . . . . . . . . . .
MEMCU41 . . . . . . . . . . . . .
MEMCU42 . . . . . . . . . . . . .
MEMINDEX. . . . . . . . . . . . .
Example . . . . . . . . . . . . .
MEMSEARCH . . . . . . . . . . . .
Example . . . . . . . . . . . . .
MEMSEARCHR . . . . . . . . . . .
Example . . . . . . . . . . . . .
MEMVERIFY . . . . . . . . . . . .
Example . . . . . . . . . . . . .
MEMVERIFYR . . . . . . . . . . . .
Example . . . . . . . . . . . . .
MIN . . . . . . . . . . . . . . .
MINEXP . . . . . . . . . . . . . .
Example (Intel Values) . . . . . . . .
Example (AIX Values) . . . . . . . .
Example (z/OS Hexadecimal Values) . . .
Example (z/OS IEEE Binary Floating Point
Values) . . . . . . . . . . . . .
Example (z/OS IEEE Decimal Floating Point
Values) . . . . . . . . . . . . .
MOD . . . . . . . . . . . . . . .
Example . . . . . . . . . . . . .
MPSTR . . . . . . . . . . . . . .
MULTIPLY . . . . . . . . . . . . .
NULL . . . . . . . . . . . . . . .
OFFSET . . . . . . . . . . . . . .
OFFSETADD . . . . . . . . . . . .
OFFSETDIFF . . . . . . . . . . . .
OFFSETSUBTRACT . . . . . . . . . .
OFFSETVALUE. . . . . . . . . . . .
OMITTED . . . . . . . . . . . . .
ONAREA . . . . . . . . . . . . .
ONCHAR . . . . . . . . . . . . .
ONCHAR pseudovariable . . . . . . . .
ONCODE . . . . . . . . . . . . .
ONCONDCOND . . . . . . . . . . .
ONCONDID . . . . . . . . . . . .
ONCOUNT . . . . . . . . . . . . .
ONFILE . . . . . . . . . . . . . .
ONGSOURCE . . . . . . . . . . . .
ONGSOURCE pseudovariable . . . . . . .
.
.
.
.
.
.
.
.
526
527
527
528
529
529
529
529
. 529
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
529
530
530
531
532
533
534
535
536
537
538
538
539
539
540
540
541
541
542
542
543
544
544
544
544
. 544
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
544
545
545
546
547
548
549
550
551
552
553
554
555
556
557
558
559
560
561
562
563
564
Built-in functions, pseudovariables, and subroutines
ONKEY . . . . . . . . . . . . . .
ONLINE . . . . . . . . . . . . . .
ONLOC . . . . . . . . . . . . . .
ONOFFSET . . . . . . . . . . . . .
ONSOURCE. . . . . . . . . . . . .
ONSOURCE pseudovariable . . . . . . .
ONSUBCODE . . . . . . . . . . . .
ONWCHAR . . . . . . . . . . . . .
ONWCHAR pseudovariable . . . . . . .
ONWSOURCE . . . . . . . . . . . .
ONWSOURCE pseudovariable . . . . . .
ORDINALNAME . . . . . . . . . . .
ORDINALPRED . . . . . . . . . . .
ORDINALSUCC . . . . . . . . . . .
PACKAGENAME . . . . . . . . . . .
PAGENO . . . . . . . . . . . . . .
PICSPEC . . . . . . . . . . . . . .
PLACES . . . . . . . . . . . . . .
Example (Intel Values) . . . . . . . .
Example (AIX Values) . . . . . . . .
Example (z/OS Hexadecimal Values) . . .
Example (z/OS IEEE Binary Floating Point
Values) . . . . . . . . . . . . .
Example (z/OS IEEE Decimal Floating Point
Values) . . . . . . . . . . . . .
PLIASCII . . . . . . . . . . . . . .
PLICANC . . . . . . . . . . . . .
PLICKPT . . . . . . . . . . . . . .
PLIDELETE . . . . . . . . . . . . .
PLIDUMP . . . . . . . . . . . . .
PLIEBCDIC . . . . . . . . . . . . .
PLIFILL . . . . . . . . . . . . . .
Example . . . . . . . . . . . . .
PLIFREE . . . . . . . . . . . . . .
PLIMOVE . . . . . . . . . . . . .
Example . . . . . . . . . . . . .
PLIOVER. . . . . . . . . . . . . .
PLIREST . . . . . . . . . . . . . .
PLIRETC . . . . . . . . . . . . . .
PLIRETV . . . . . . . . . . . . . .
PLISAXA . . . . . . . . . . . . . .
PLISAXB . . . . . . . . . . . . . .
PLISAXC . . . . . . . . . . . . . .
PLISAXD . . . . . . . . . . . . . .
PLISRTA . . . . . . . . . . . . . .
PLISRTB . . . . . . . . . . . . . .
PLISRTC . . . . . . . . . . . . . .
PLISRTD . . . . . . . . . . . . . .
PLITRAN11 . . . . . . . . . . . . .
PLITRAN12 . . . . . . . . . . . . .
PLITRAN21 . . . . . . . . . . . . .
PLITRAN22 . . . . . . . . . . . . .
POINTER . . . . . . . . . . . . .
POINTERADD . . . . . . . . . . . .
POINTERDIFF . . . . . . . . . . . .
POINTERSUBTRACT. . . . . . . . . .
POINTERVALUE . . . . . . . . . . .
POLY . . . . . . . . . . . . . . .
POPCNT . . . . . . . . . . . . . .
PRECISION . . . . . . . . . . . . .
PRED . . . . . . . . . . . . . . .
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
565
566
567
568
569
570
571
572
573
574
575
576
577
578
579
580
581
582
582
582
582
. 582
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
582
583
584
585
586
587
588
589
589
590
591
591
592
593
594
595
596
597
598
599
600
601
602
603
604
605
606
607
608
609
610
611
612
613
614
615
616
PRESENT . . . . . . . . . . . .
PROCEDURENAME . . . . . . . . .
PROD . . . . . . . . . . . . . .
PUTENV . . . . . . . . . . . . .
RADIX . . . . . . . . . . . . .
RAISE2 . . . . . . . . . . . . .
Example . . . . . . . . . . . .
RANDOM . . . . . . . . . . . .
RANK. . . . . . . . . . . . . .
REAL . . . . . . . . . . . . . .
REAL pseudovariable . . . . . . . .
REG12. . . . . . . . . . . . . .
REM . . . . . . . . . . . . . .
REPATTERN . . . . . . . . . . .
REPEAT . . . . . . . . . . . . .
REPLACEBY2 . . . . . . . . . . .
REVERSE. . . . . . . . . . . . .
Example . . . . . . . . . . . .
RIGHT . . . . . . . . . . . . .
Example . . . . . . . . . . . .
ROUND . . . . . . . . . . . . .
ROUND of FIXED. . . . . . . . .
ROUND of IEEE decimal floating point .
ROUND of IEEE binary floating point . .
ROUND of IBM hexadecimal floating point
ROUNDDEC . . . . . . . . . . .
SAMEKEY . . . . . . . . . . . .
SCALE . . . . . . . . . . . . .
SEARCH . . . . . . . . . . . . .
Example 1 . . . . . . . . . . .
Example 2 . . . . . . . . . . .
SEARCHR . . . . . . . . . . . .
Example . . . . . . . . . . . .
SECS . . . . . . . . . . . . . .
Example . . . . . . . . . . . .
SECSTODATE . . . . . . . . . . .
SECSTODAYS . . . . . . . . . . .
SIGN . . . . . . . . . . . . . .
SIGNED . . . . . . . . . . . . .
SIN. . . . . . . . . . . . . . .
SIND . . . . . . . . . . . . . .
SINH . . . . . . . . . . . . . .
SIZE . . . . . . . . . . . . . .
Example . . . . . . . . . . . .
SOURCEFILE . . . . . . . . . . .
SOURCELINE . . . . . . . . . . .
SQRT . . . . . . . . . . . . . .
SQRTF . . . . . . . . . . . . .
STACKADDR . . . . . . . . . . .
STORAGE . . . . . . . . . . . .
STRING . . . . . . . . . . . . .
STRING pseudovariable . . . . . . . .
SUBSTR . . . . . . . . . . . . .
SUBSTR pseudovariable . . . . . . . .
SUBTRACT . . . . . . . . . . . .
SUCC . . . . . . . . . . . . . .
SUM . . . . . . . . . . . . . .
SYSNULL . . . . . . . . . . . .
SYSTEM . . . . . . . . . . . . .
TALLY . . . . . . . . . . . . .
Example . . . . . . . . . . . .
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
Chapter 18. Built-in functions, pseudovariables, and subroutines
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
617
618
619
620
621
622
622
623
624
625
626
627
628
629
630
631
632
632
633
633
634
634
634
635
635
636
637
638
639
639
639
641
641
642
642
643
644
645
646
647
648
649
650
650
652
653
654
655
656
657
658
660
661
662
663
664
665
666
667
668
668
385
Built-in functions, pseudovariables, and subroutines
TAN . . . . . . .
TAND . . . . . . .
TANH . . . . . . .
THREADID . . . . .
TIME . . . . . . .
TINY . . . . . . .
TRANSLATE . . . .
Example . . . . .
TRIM . . . . . . .
Example . . . . .
TRUNC . . . . . .
TYPE . . . . . . .
TYPE pseudovariable. .
ULENGTH . . . . .
ULENGTH8 . . . . .
ULENGTH16 . . . .
UNALLOCATED . . .
UNSIGNED . . . . .
UNSPEC . . . . . .
UNSPEC pseudovariable
Example . . . . .
UPOS . . . . . . .
UPPERCASE . . . .
USUBSTR . . . . .
USUPPLEMENTARY . .
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
669
670
671
672
673
674
675
675
676
676
677
678
679
680
681
682
683
684
685
687
687
688
689
690
691
UTF8 . . . . .
UTF8TOCHAR . .
UTF8TOWCHAR .
UVALID . . . .
UWIDTH. . . .
VALID . . . .
VALIDDATE . .
Example . . .
VARGLIST . . .
VARGSIZE . . .
VERIFY . . . .
Example . . .
VERIFYR . . . .
Example . . .
WCHARVAL . .
WEEKDAY . . .
WHIGH . . . .
WIDECHAR. . .
WLOW . . . .
XMLCHAR . . .
Example of using
Y4DATE . . . .
Y4JULIAN . . .
Y4YEAR . . . .
. . . .
. . . .
. . . .
. . . .
. . . .
. . . .
. . . .
. . . .
. . . .
. . . .
. . . .
. . . .
. . . .
. . . .
. . . .
. . . .
. . . .
. . . .
. . . .
. . . .
XMLCHAR
. . . .
. . . .
. . . .
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
692
693
694
695
697
698
699
699
700
701
702
702
703
703
704
705
706
707
708
709
709
711
712
713
A large number of common tasks are available in the form of built-in functions,
subroutines, and pseudovariables. When you use them, you can write less code
more quickly with greater reliability.
The built-in functions, subroutines, and pseudovariables are listed in alphabetic
order in this chapter. In general, each description has the following format:
v A heading showing the syntax of the reference
v A description of the value returned or, for a pseudovariable, the value set
v A description of any arguments
v Any other qualifications on using the function or pseudovariable
The abbreviations for built-in functions have separate declarations (explicit or
contextual) and name scopes. In the following example:
dcl (Dim, Dimension) builtin;
is not a multiple declaration, and
dcl Binary file;
X = Bin (var, 6,3);
is valid even though Bin is an abbreviation of the Binary built-in function.
Declaring and invoking built-in functions, pseudovariables, and built-in
subroutines
Built-in functions, pseudovariables, and subroutines can be contextually or
explicitly declared.
BUILTIN attribute
The BUILTIN attribute specifies that the name is a built-in function,
pseudovariable, or a subroutine.
386
Enterprise PL/I for z/OS Language Reference
BUILTIN
BUILTIN
Built-in names can be used as programmer-defined names. BUILTIN can be
declared for a built-in name in any block that has inherited, from a containing
block, a programmer-defined declaration or use of the same name. The following
example shows built-in names with the BUILTIN attribute.
Example 1
1
2
3
A: procedure;
declare Sqrt float binary;
X = Sqrt;
B:
Begin;
Declare Sqrt builtin;
Z = Sqrt(P);
end B;
end A;
In this example:
1
Sqrt is a programmer-defined name.
2
The assignment to the variable X is a reference to the programmer-defined
name Sqrt.
3
Sqrt is declared with the BUILTIN attribute so that any reference to Sqrt
within B is recognized as a reference to the built-in function and not to the
programmer-defined name Sqrt declared in 1.
Invoking built-in functions and pseudovariables
The following syntax is used to invoke built-in functions and pseudovariables.
name
,
( )
argument
Invoking built-in subroutines
The following syntax is used to invoke built-in subroutines.
CALL name
;
(
)
,
argument
Chapter 18. Built-in functions, pseudovariables, and subroutines
387
Arguments
Specifying arguments for built-in functions, pseudovariables, and
built-in subroutines
Arguments, which can be expressions, are evaluated and converted to a data type
suitable for the built-in function according to the rules for data conversion.
Aggregate arguments
All built-in functions and pseudovariables that can have arguments can have array
arguments (if more than one is an array, the bounds must be identical).
v ADDR, ALLOCATION, CURRENTSIZE, SIZE, STRING, and the array-handling
functions return an element value.
v Under the compiler option USAGE(UNSPEC(ANS)), UNSPEC returns an
element value; Under USAGE(UNSPEC(IBM)) returns an array of values.
v All other functions return an array of values.
Specifying an array argument is equivalent to placing the function reference or
pseudovariable in a do-group where one or more arguments is a subscripted array
reference that is modified by the control variable.
For example:
dcl A(2) char(2) varying;
dcl B(2) char(2)
init(’AB’,’CD’);
dcl C(2) fixed bin
init(1,2);
A=substr(B,1,C);
results in A(1) having the value A and A(2) having the value CD.
The built-in functions and pseudovariables that can accept structure or union
arguments are listed in Table 45.
Table 45. Built-in functions and pseudovariables that accept structure or union arguments
Built-in functions and pseudovariables
ADDR
CURRENTSIZE
PRESENT
ADDRDATA
INDICATORS
SIZE
ALLOCATION
LOCATION
STRING
BITLOCATION
OMITTED
UNSPEC1
XMLCHAR
1. UNSPEC may be applied to a structure or union only if the compiler option
USAGE(UNSPEC(ANS)) is in effect.
Null and optional arguments
Some built-ins do not require arguments. You must either explicitly declare these
with the BUILTIN attribute or contextually declare them by including a null
argument list in the reference—for example, ONCHAR(). Otherwise, the name is
not recognized as a built-in.
Accuracy of mathematical functions
The accuracy of a result is influenced by two factors:
v The accuracy of the argument
v The accuracy of the algorithm
388
Enterprise PL/I for z/OS Language Reference
Accuracy of mathematical functions
Most arguments contain errors. An error in a given argument can accumulate over
several steps before the evaluation of a function. Even data fresh from input
conversion can contain errors. The effect of argument error on the accuracy of a
result depends entirely on the nature of the mathematical function, and not on the
algorithm that computes the result. This book does not discuss argument errors of
this type.
The mathematical built-in functions that are implemented using inline machine
instructions produce results of different accuracy.
Categories of built-in functions
The following sections list built-in functions, subroutines, and pseudovariables.
Only full function names are listed in these tables. Existing abbreviations are
provided in the sections that describe each built-in function, subroutine, and
pseudovariable.
In the discussions of conversions that follow:
v M is the maximum precision for FIXED BINARY. This is the value M2 from the
compiler option LIMITS(FIXEDBIN(M1,M2)).
v N is the maximum precision for FIXED DECIMAL. This is the value N2 from the
compiler option LIMITS(FIXEDDEC(N1,N2)).
Arithmetic built-in functions
The arithmetic built-in functions allow you to do the following:
v Determine properties of arithmetic values. For example, the SIGN function
indicates the sign of an arithmetic variable.
v Perform routine arithmetic operations.
Table 46 lists the arithmetic built-in functions and a short description of each.
Some of the arithmetic functions derive the data type of their results from one or
more arguments. When the data types of the arguments differ, they are converted
as described in Chapter 4, “Data conversion,” on page 73.
Table 46. Arithmetic built-in functions
Function
Description
ABS
Calculates the absolute value of a value
CEIL
Calculates the smallest integer value greater than or equal to a value
COMPLEX
Returns the complex number with given real and imaginary parts
CONJG
Returns the complex conjugate of a value
FLOOR
Calculates the largest integer value less than or equal to a value
IMAG
Returns the imaginary part of a complex number
MAX
Calculates the maximum of 2 or more values
MIN
Calculates the minimum of 2 or more values
MOD
Returns the modular equivalent of the remainder of one value divided
by another
RANDOM
Returns a pseudo-random value
REAL
Returns the real part of a complex number
Chapter 18. Built-in functions, pseudovariables, and subroutines
389
Arithmetic
Table 46. Arithmetic built-in functions (continued)
Function
Description
REM
Calculates the remainder of one value divided by another
ROUND
Rounds a value at a specified digit
ROUNDDEC
Rounds a decimal value at a specified digit
SIGN
Returns a -1, 0 or 1 if a value is negative, zero, or positive, respectively
TRUNC
Calculates the nearest integer for value rounded towards zero
Array-handling built-in functions
The array-handling built-in functions operate on array arguments and return an
element value. Any conversion of arguments required for these functions is noted
in the function description. Table 47 lists the array-handling built-in functions.
Table 47. Array-handling built-in functions
Function
Description
ALL
Calculates the bitwise “and” of all the elements of an array
ANY
Calculates the bitwise “or” of all the elements of an array
DIMENSION
Returns the number of elements in a dimension of an array
HBOUND
Returns the upper bound for a dimension of an array
HBOUNDACROSS
Returns the upper bound in a DIMACROSS array
LBOUND
Returns the lower bound for a dimension of an array
LBOUNDACROSS
Returns the lower bound in a DIMACROSS array
POLY
Returns floating-point approximate of two arrays
PROD
Calculates the product of all the elements of an array
SUM
Calculates the sum of all the elements of an array
Buffer-management built-in functions
The buffer-management built-in functions operate on a "buffer", which is an area of
storage specified by an address and a number of bytes. The PLIFILL, PLIMOVE
and PLIOVER built-in subroutines are also useful in managing buffers.Table 48 lists
the buffer-management built-in functions.
Table 48. Buffer-management built-in functions
390
Function
Description
COMPARE
Compares two buffers
HEXIMAGE
Returns a character string that is the hex representation of a buffer
MEMCONVERT
Converts the data in a source buffer from the specified source codepage
to a a specified target codepage, stores the result in a target buffer, and
returns an unscaled REAL FIXED BINARY value specifying the number
of bytes written to the target buffer.
MEMCU12
Converts the data in a source buffer from UTF-8 to UTF-16, stores the
result in a target buffer, and returns an unscaled REAL FIXED BINARY
value specifying the number of bytes written to the target buffer.
Enterprise PL/I for z/OS Language Reference
Array-handling
Table 48. Buffer-management built-in functions (continued)
Function
Description
MEMCU14
Converts the data in a source buffer from UTF-8 to UTF-32, stores the
result in a target buffer, and returns an unscaled REAL FIXED BINARY
value specifying the number of bytes written to the target buffer.
MEMCU21
Converts the data in a source buffer from UTF-16 to UTF-8, stores the
result in a target buffer, and returns an unscaled REAL FIXED BINARY
value specifying the number of bytes written to the target buffer.
MEMCU24
Converts the data in a source buffer from UTF-16 to UTF-32, stores the
result in a target buffer, and returns an unscaled REAL FIXED BINARY
value specifying the number of bytes written to the target buffer.
MEMCU41
Converts the data in a source buffer from UTF-32 to UTF-8, stores the
result in a target buffer, and returns an unscaled REAL FIXED BINARY
value specifying the number of bytes written to the target buffer.
MEMCU42
Converts the data in a source buffer from UTF-32 to UTF-16, stores the
result in a target buffer, and returns an unscaled REAL FIXED BINARY
value specifying the number of bytes written to the target buffer.
MEMINDEX
Finds the location of one string or buffer within a buffer
MEMSEARCH
Searches for the first occurrence of any one of the elements of a string
within a buffer
MEMSEARCHR
Searches for the first occurrence of any one of the elements of a string
within a buffer, but the search starts from the right
MEMVERIFY
Searches for the first nonoccurrence of any one of the elements of a
string within a buffer
MEMVERIFYR
Searches for the first occurrence of any one of the elements of a string
within a buffer, but the search starts from the right
XMLCHAR
Writes XML corresponding to a structure to a buffer
Condition-handling built-in functions
The condition-handling built-in functions enable you to determine the cause of a
condition that has occurred.
Use of these functions is valid only within the scope of an ON-unit or dynamic
descendant for:
v the condition specific to the built-in function
v the ERROR or FINISH condition when raised as an implicit action
All other uses are out of context.
Table 49. Condition-handling built-in functions
Function
Description
DATAFIELD
Returns the value of a string that raised the NAME condition
ONAREA
Returns the name of the AREA reference for which an AREA condition
is raised
ONCHAR
Returns the value of a character that caused a conversion condition
ONCODE
Returns the condition code value
ONCONDCOND
Returns the name of CONDITION condition being processed
ONCONDID
Returns a number which identifies a particular condition
ONCOUNT
Returns the number of outstanding conditions
Chapter 18. Built-in functions, pseudovariables, and subroutines
391
Condition-handling
Table 49. Condition-handling built-in functions (continued)
Function
Description
ONFILE
Returns the name of a file for which a condition is raised
ONGSOURCE
Returns the value of a graphic string that caused a conversion condition
ONKEY
Returns the key of a record that raised a condition
ONLINE
Returns the line number from the source in which a condition occurred
ONLOC
Returns the name of the procedure in which a condition occurred
ONOFFSET
Returns the offset within a block in which a condition occurred
ONSOURCE
Returns the value of a string that caused a conversion condition
ONSUBCODE
Returns an integer value that gives additional information about certain
I/O errors
ONWCHAR
Returns the value of a widechar that caused a conversion condition
ONWSOURCE
Returns the value of a widechar string that caused a conversion
condition
Date/time built-in functions
These built-in functions return or manipulate date and time information in terms
of days, seconds, and character date/time stamps. Some of these built-in functions
allow you to specify the date/time patterns to be used. Table 50 lists the supported
date/time built-in functions. Table 51 on page 394 lists the supported date/time
patterns.
The time zone and accuracy for these functions are system dependent.
Lilian format: The Lilian format, named in honor of Luigi Lilio, the creator of the
Gregorian calendar, represents a date as the number of days or
seconds from the beginning of the Gregorian calendar. This format
is useful for performing calculations involving elapsed time.
The Lilian format counts days that have elapsed since October 14,
1582; day one is Friday, October 15, 1582. For example, 16 May 1988
is 148138 Lilian days. The valid range of Lilian days is 1 to
3,074,324 (15 October 1582 to 31 December 9999).
For the number of elapsed seconds, the Lilian format counts
elapsed seconds starting at 00:00:00 14 October 1582. For example,
00:00:01 on 15 October 1582 is 86,401 (24*60*60+1) Lilian seconds,
and 19:01:01 16 May 1988 is 12,799,191,661 Lilian seconds. The valid
range of Lilian seconds is 86,400 to 265,621,679,999.999 (23:59:59:999
31 December 9999) seconds.
Table 50. Date/time built-in functions
392
Function
Description
DATE
Returns the current date in the pattern YYMMDD
DATETIME
Returns the current date and time in the user-specified pattern or in the
default pattern YYYYMMDDHHMISS999
DAYS
Returns the number of days corresponding to a date/time pattern string,
or the number of days for today's date
DAYSTODATE
Converts a number of days to a date/time pattern string
Enterprise PL/I for z/OS Language Reference
Date/time
Table 50. Date/time built-in functions (continued)
Function
Description
DAYSTOSECS
Converts a number of days to a number of seconds
REPATTERN
Takes a value holding a date in one pattern and returns that value
converted to a date in a second pattern
SECS
Returns the number of seconds corresponding to a date/time pattern
string, or the number of seconds for today's date
SECSTODATE
Converts a number of seconds to a date/time pattern string
SECSTODAYS
Converts a number of seconds to a number of days
TIME
Returns the current time in the pattern HHMISS999
VALIDDATE
Indicates if a string holds a valid date
WEEKDAY
Returns the day of the week corresponding to the current day or
specified DAYS value
Y4DATE
Takes a date value with the pattern 'YYMMDD' and returns the date
value with the two-digit year widened to a four-digit year
Y4JULIAN
Takes a date value with the pattern 'YYDDD' and returns the date value
with the two-digit year widened to a four-digit year
Y4YEAR
Takes a date value with the pattern 'YY' and returns the date value with
the two-digit year widened to a four-digit year
Table 51 on page 394 uses the following formats:
YYYY Four-digit year
YY
Two-digit year
ZY
Two-digit year with any leading zero suppressed
MM
Two-digit month
ZM
Two-digit month with any leading zero suppressed
MMM Three-letter month (Ex: DEC)
Mmm Three-letter month (Ex: Dec)
DD
Two-digit day within a given month
ZD
Two-digit day within a given month with any leading zero suppressed
DDD Number of days within a given year
HH
Number of hours within a given day
MI
Number of minutes within a given hour
SS
Number of seconds within a given minute
999
Number of milliseconds within a given second
Note: For the three-letter month patterns, the uppercase/lowercase characters must
correspond exactly.
The only supported pattern using any of HH, MI, SS or 999 is the pattern
'YYYYMMDDHHMISS999'.
Chapter 18. Built-in functions, pseudovariables, and subroutines
393
Date/time
Table 51. Date/time patterns
Four-digit years
Two-digit years
Year first
YYYYMMDD
YYYYMMMDD
YYYYMmmDD
YYYYDDD
YYYYMM
YYYYMMM
YYYYMmm
YYYY
YYYYMMDDHHMISS999
YYMMDD
YYMMMDD
YYMmmDD
YYDDD
YYMM
YYMMM
YYMmm
YY
Month first
MMDDYYYY
MMMDDYYYY
MmmDDYYYY
MMYYYY
MMMYYYY
MmmYYYY
MMDDYY
MMMDDYY
MmmDDYY
MMYY
MMMYY
MmmYY
Day first
DDMMYYYY
DDMMMYYYY
DDMmmYYYY
DDDYYYY
DDMMYY
DDMMMYY
DDMmmYY
DDDYY
DB2 formats
YYYY-MM-DD
MM/DD/YYYY
DD.MM.YYYY
YY-MM-DD
MM/DD/YY
DD.MM.YY
without zeros
ZY-ZM-ZD
YY-ZM-ZD
ZM/ZD/ZY
ZM/ZD/YY
ZD.ZM.ZY
ZD.ZM.YY
When the day is omitted from a pattern, it is assumed to have the value 1. If the
month and day are both omitted, they are also assumed to have the value 1.
When using MMM, the date must be written in three uppercase letters; when
using Mmm, the date must be written with the first letter in uppercase, and the
letters following in lowercase.
On input, the date value for the patterns "without zeros" may be less than 8
characters, for example, the date 20 Jan 2008 may be specified as 8-1-20 to match
the pattern "ZY-ZM-ZD". On output, the string produced for one of these patterns
will always be 8 characters with any suppressed zeros compensated by trailing
blanks.
Floating-point inquiry built-in functions
The floating-point inquiry built-in functions return information about the
floating-point variable arguments that you specify.
Table 52. Floating-point inquiry built-in functions
394
Function
Description
EPSILON
Returns the spacing around 1
HUGE
Returns the largest positive finite value that a floating-point variable can
hold
Enterprise PL/I for z/OS Language Reference
Floating-point inquiry
Table 52. Floating-point inquiry built-in functions (continued)
Function
Description
ISFINITE
Indicates if a floating point value is not a NAN and not positive or
negative infinity
ISINF
Indicates if a floating point value is an infinity
ISNAN
Indicates if a floating point value is a NAN
ISNORMAL
Indicates if a floating point value is not a zero, subnormal, infinity or
NaN
ISZERO
Indicates if a floating point value is a zero
MAXEXP
Returns the maximum value for an exponent
MINEXP
Returns the minimum value for an exponent
PLACES
Returns the model precision for a floating point value
RADIX
Returns the model base for a floating point value
TINY
Returns the smallest positive value that a floating-point variable can
hold
Floating-point manipulation built-in functions
The floating-point manipulation built-in functions perform mathematical
operations on floating-point variables that you specify and return the result of the
operation.
Table 53. Floating-point manipulation built-in functions
Function
Description
EXPONENT
Returns the exponent part of a floating point value
PRED
Returns the next representable value before a floating-point value
SCALE
Multiplies a floating-point number by an integral power of the radix
SUCC
Returns the next representable value after a floating-point value
Input/output built-in functions
The input and output built-in functions allow you to determine the current state of
a file.
Table 54. Input/output built-in functions
Function
Description
COUNT
Returns the number of data items transmitted during the last GET or
PUT
ENDFILE
Indicates if a file is open and end-of-file has been reached for it
FILEDDINT
Returns a value for the designated file attribute
FILEDDTEST
Returns the value 1 if the designated attribute applies to the specified
file
FILEDDWORD
Returns a character string for the designated file attribute
FILEID
Returns a system token value for a file
FILEOPEN
Indicates if a file is open
FILEREAD
Reads from a file
FILESEEK
Changes the current file position to a new location
Chapter 18. Built-in functions, pseudovariables, and subroutines
395
Input/output
Table 54. Input/output built-in functions (continued)
Function
Description
FILETELL
Returns a value indicating the current position of a file
FILEWRITE
Writes to a file
LINENO
Returns the current line number associated with a print file
PAGENO
Returns the current page number associated with a print file
SAMEKEY
Indicates if a record is followed by another with the same key
Integer manipulation built-in functions
The integer manipulation built-in functions perform operations on integer variables
and return the result of the operation.
Table 55. Integer manipulation built-in functions
Function
Description
IAND
Calculates the bitwise “and” of 2 or more fixed binary values
IEOR
Calculates the bitwise “exclusive-or” of 2 fixed binary values
INOT
Calculates the bitwise “not” of a fixed binary value
IOR
Calculates the bitwise “or” of 2 or more fixed binary values
ISIGNED
Casts an integer to a signed integer without changing its bit pattern
ISLL
Shifts a fixed binary value “logically” to the left
ISRL
Shifts a fixed binary value “logically” to the right
IUNSIGNED
Casts an integer to an unsigned integer without changing its bit pattern
LOWER2
Divides a fixed binary value by an integral power of 2
RAISE2
Multiplies a fixed binary value by an integral power of 2
Mathematical built-in functions
All of these functions operate on floating-point values to produce a floating-point
result. Any argument that is not floating-point is converted. The accuracy of these
functions is discussed in “Accuracy of mathematical functions” on page 388.
Table 56 lists the mathematical built-in functions.
Table 56. Mathematical built-in functions
396
Function
Description
ACOS
Calculates the arc cosine
ASIN
Calculates the arc sine
ATAN
Calculates the arc tangent
ATAND
Calculates the arc tangent in degrees
ATANH
Calculates the hyperbolic arc tangent
COS
Calculates the cosine
COSD
Calculates the cosine for a value in degrees
COSH
Calculates the hyperbolic cosine
ERF
Calculates the error function
ERFC
Calculates the complement of the error function
EXP
Calculates e to a power
Enterprise PL/I for z/OS Language Reference
Mathematical
Table 56. Mathematical built-in functions (continued)
Function
Description
GAMMA
Calculates the gamma function
LOG
Calculates the natural logarithm
LOG10
Calculates the base 10 logarithm
LOG2
Calculates the base 2 logarithm
LOGGAMMA
Calculates the log of the gamma function
SIN
Calculates the sine
SIND
Calculates the sine for a value in degrees
SINH
Calculates the hyperbolic sine
SQRT
Calculates the square root
SQRTF
Calculates SQRT inline if hardware architecture permits
TAN
Calculates the tangent
TAND
Calculates the tangent for a value in degrees
TANH
Calculates the hyperbolic tangent
Miscellaneous built-in functions
The built-in functions do not fit into any of the other categories are those listed in
Table 57.
Table 57. Miscellaneous built-in functions
Function
Description
ALLCOMPARE
Returns a BIT(1) value that indicates the result of comparing two
structures
BYTE
Synonym for CHARVAL
CDS
Returns a FIXED BINARY(31) value that indicates if the old and
current values in a compare double and swap were equal
CHARVAL
Returns the character value corresponding to an integer
COLLATE
Returns a character(256) string specifying the collating order
CS
Returns a FIXED BINARY(31) value that indicates if the old and
current values in a compare and swap were equal
GETENV
Returns a value representing a specified environment variable
HEX
Returns a character string that is the hex representation of a value
INDICATORS
Returns a value that gives the number of elements at the next
logical level in a structure
ISMAIN
Indicates if the current procedure is main
OMITTED
Indicates if a parameter was not supplied on a call
PACKAGENAME
Returns the name of the containing package
PLIRETV
Returns the PL/I return code value
POPCNT
Returns a FIXED BIN value holding in each byte the number of bits
equal to 1 in the corresponding byte
PRESENT
Indicates if a parameter was supplied on a call
PROCEDURENAME
Returns the name of the most closely nested procedure
Chapter 18. Built-in functions, pseudovariables, and subroutines
397
Miscellaneous
Table 57. Miscellaneous built-in functions (continued)
Function
Description
PUTENV
Adds new environment variables or modifies the values of existing
environment variables
RANK
Returns the integer value corresponding to a character or widechar
REG12
Returns the address of the current dynamic save area
SOURCEFILE
Returns the name of the containing file
SOURCELINE
Returns the number of the containing line
STACKADDR
Returns the address of the current dynamic save area
STRING
Returns a string that is the concatenation of all the elements of a
string aggregate
SYSTEM
Returns the value returned by a command
THREADID
Returns the thread identifier for a task
UNSPEC
Returns a bit string that is the internal representation of a value
VALID
Indicates if the contents of a variable are valid for its declaration
WCHARVAL
Returns the widechar value corresponding to an integer
Ordinal-handling built-in functions
The ordinal-handling built-in functions return information about a specified
ordinal.
Table 58. Ordinal-handling built-in functions
Function
Description
ORDINALNAME Returns a character string giving an ordinal’s name
ORDINALPRED
Returns the next lower value for an ordinal
ORDINALSUCC
Returns the next higher value for an ordinal
Precision-handling built-in functions
The precision-handling built-in functions allow you to manipulate variables with
specified precisions, and they return the value resulting from the operation.
Table 59. Precision-handling built-in functions
398
Function
Description
ADD
Adds, with a specified precision, two values
BINARY
Converts a value to binary
DECIMAL
Converts a value to decimal
DIVIDE
Divides, with a specified precision, two values
FIXED
Converts a value to fixed
FIXEDBIN
Converts a value to fixed binary
FIXEDDEC
Converts a value to fixed decimal
FLOAT
Converts a value to float
FLOATBIN
Converts a value to float binary
FLOATDEC
Converts a value to float decimal
MULTIPLY
Multiplies, with a specified precision, two values
Enterprise PL/I for z/OS Language Reference
Precision-handling built-in functions
Table 59. Precision-handling built-in functions (continued)
Function
Description
PRECISION
Converts a value to specified precision
SIGNED
Converts a value to signed fixed binary
SUBTRACT
Subtracts, with a specified precision, two values
UNSIGNED
Converts a value to unsigned fixed binary
Pseudovariables
Pseudovariables represent receiving fields. They cannot be nested. For example, the
following is invalid:
unspec(substr(A,1,2)) = ’00’B;
A pseudovariable can appear only:
v on the left side of an assignment statement
v as the target in a DO-specification and then only if it is one of SUBSTR, REAL,
IMAG or UNSPEC
v in the data list of a GET statement or in the STRING option of a PUT statement
v as the string name in a KEYTO or REPLY option
The pseudovariables are:
Table 60. Built-in pseudovariables
Function
Description
ENTRYADDR
Sets an entry variable with the address of the entry to be invoked
IMAG
Assigns the imaginary part of a complex number
ONCHAR
Sets the value of a character that caused a conversion condition
ONGSOURCE
Sets the value of a graphic string that caused a conversion condition
ONSOURCE
Sets the value of a string that caused a conversion condition
REAL
Assigns the real part of a complex number
STRING
Assigns a string that is the concatenation of all the elements of a string
aggregate
SUBSTR
Assigns a substring of a string
ONWCHAR
Sets the value of a widechar that caused a conversion condition
ONWSOURCE
Sets the value of a widechar string that caused a conversion condition
TYPE
Assigns a typed structure or union to storage located by a handle
UNSPEC
Assigns a bit string that is the internal representation of a value
Storage control built-in functions
The storage control built-in functions allow you to determine the storage
requirements and location of variables, to assign special values to area and locator
variables, to perform conversion between offset and pointer values, to obtain the
number of generations of a controlled variable, and to reference data and methods
of objects and classes. Table 61 on page 400 lists the storage control built-in
functions.
Chapter 18. Built-in functions, pseudovariables, and subroutines
399
Storage control
Table 61. Storage control built-in functions
400
Function
Description
ADDR
Returns the address of a variable
ADDRDATA
Returns the address of the first data byte of a string when applied
to a varying string
ALLOCATE
Allocates storage of the specified size in the heap
ALLOCATION
Returns the current number of generations of a controlled variable
ALLOCSIZE
Returns a FIXED BIN(N,0) value giving the amount of storage
allocated with a specific pointer
AUTOMATIC
Allocates storage of the specified size in the stack
AVAILABLEAREA
Returns the size of the largest single allocation that can be made in
an area
BINARYVALUE
Converts a pointer, offset, or ordinal to an integer
BITLOCATION
Returns the bit offset of a variable within a byte
CHECKSTG
Returns a bit(1) value determining whether allocated storage is
uncorrupted
CURRENTSIZE
Returns the current size of a variable
CURRENTSTORAGE
Synonym for CURRENTSIZE
EMPTY
Returns an “empty” area
ENTRYADDR
Returns the address of the routine associated with an entry
HANDLE
Returns a handle to a typed structure or union
LOCATION
Returns the byte offset of a variable within a structure
NULL
Returns a null pointer value
OFFSET
Converts a pointer to an offset
OFFSETADD
Adds an integer to an offset
OFFSETDIFF
Subtracts two offsets
OFFSETSUBTRACT
Subtracts an integer from an offset
OFFSETVALUE
Converts an integer to an offset
POINTER
Converts an offset to a pointer
POINTERADD
Adds an integer to a pointer
POINTERDIFF
Subtracts two pointers
POINTERSUBTRACT
Subtracts an integer from a pointer
POINTERVALUE
Converts an integer or handle to a pointer
SIZE
Returns the maximum size of a variable
STORAGE
Synonym for SIZE
SYSNULL
Returns a system null pointer value
TYPE
Returns the typed structure or union located by a handle
UNALLOCATED
Returns a bit(1) value indicating if a specified pointer value is the
start of allocated storage
VARGLIST
Returns the address of the first optional parameter passed to a
procedure
VARGSIZE
Returns the number of bytes occupied by a byvalue parameter
Enterprise PL/I for z/OS Language Reference
String-handling
String-handling built-in functions
The string-handling built-in functions simplify the processing of bit, character,
graphic and widechar strings. The string arguments can be represented by an
arithmetic expression that will be converted to string either according to data
conversion rules or according to the rules given in the function description.
Note: Some of these functions, such as LOWERCASE, TRANSLATE, TRIM and
UPPERCASE, support only CHARACTER data.
Table 62. String-handling built-in functions
Function
Description
BIT
Converts a value to bit
BOOL
Performs Boolean operation on 2 bit strings
CENTERLEFT
Returns a string with a value centered (to the left) in it
CENTERRIGHT
Returns a string with a value centered (to the right) in it
CENTRELEFT
Synonym for CENTERLEFT
CENTRERIGHT
Synonym for CENTERRIGHT
CHARACTER
Converts a value to a character string
CHARGRAPHIC
Converts a GRAPHIC string to a mixed character string
COPY
Returns a string consisting of n copies of a string
EDIT
Returns a string consisting of a value converted to a given picture
specification
GRAPHIC
Converts a value to graphic
HIGH
Returns a character string consisting of n copies of the highest
character in the collating sequence
INDEX
Finds the location of one string within another
LEFT
Returns a string with a value left-justified in it
LENGTH
Returns the current length of a string
LOW
Returns a character string consisting of n copies of the lowest
character in the collating sequence
LOWERCASE
Returns a character string with all the characters from A to Z
converted to their corresponding lowercase character.
MAXLENGTH
Returns the maximum length of a string
MPSTR
Truncates a string at a logical boundary and returns a mixed
character string
PICSPEC
Returns a string consisting of a value assumed to have a given
picture specification
REPEAT
Returns a string consisting of n+1 copies of a string
REPLACEBY2
Returns a string with some characters "translated" to a pair of
characters
REVERSE
Returns a reversed image of a string
RIGHT
Returns a string with a value right-justified in it
SEARCH
Searches for the first occurrence of any one of the elements of a
string within another string
SEARCHR
Searches for the first occurrence of any one of the elements of a
string within another string but the search starts from the right
SUBSTR
Assigns a substring of a string
Chapter 18. Built-in functions, pseudovariables, and subroutines
401
String-handling
Table 62. String-handling built-in functions (continued)
Function
Description
TALLY
Returns the number of times one string occurs in another
TRANSLATE
Translates a string based on two translation strings
TRIM
Trims specified characters from the left and right sides of a string
ULENGTH
Returns the number of UTF characters in a CHAR or WIDECHAR
string
ULENGTH8
Returns the length of a CHAR string needed if the UTF characters
in a CHAR or WIDECHAR string were converted to UTF-8
ULENGTH16
Returns the length of a WIDECHAR string needed if the UTF
characters in a CHAR or WIDECHAR string were converted to
UTF-16
UPOS
Returns the position of the nth UTF character in a CHAR or
WIDECHAR string
UPPERCASE
Returns a character string with all the characters from a to z
converted to their corresponding uppercase character
USUBSTR
Returns a substring of a UTF string
USUPPLEMENTARY
Returns the index of the first UTF surrogate pair in a CHAR or
WIDECHAR string
UTF8
Returns a CHAR value that is the UTF-8 equivalent of x
UTF8TOCHAR
Returns a CHAR value holding x converted from UTF-8
UTF8TOWCHAR
Returns a WCHAR value holding x converted from UTF-8 to
UTF-16
UVALID
Indicates if a CHAR or WIDECHAR string contains valid UTF data
UWIDTH
Returns the width of the nth UTF character in a CHAR or
WIDECHAR string
VERIFY
Searches for first nonoccurrence of any one of the elements of a
string within another string
VERIFYR
Searches for first nonoccurrence of any one of the elements of a
string within another string but the search starts from the right
WHIGH
Returns a widechar string consisting of n copies of the highest
widechar ('ffff'wx)
WIDECHAR
Converts a value to a widechar string
WLOW
Returns a widechar string consisting of n copies of the lowest
widechar ('0000'wx)
Subroutines
Built-in subroutines perform miscellaneous operations that do not necessarily
return a result as built-in functions do.
Table 63. Built-in subroutines
402
Function
Description
PLIASCII
Converts from EBCDIC to ASCII
PLICANC
Cancels the automatic restart facility (z/OS only)
PLICKPT
Takes a checkpoint for later restart (z/OS only)
PLIDELETE
Frees the storage associated with a handle
Enterprise PL/I for z/OS Language Reference
Subroutines
Table 63. Built-in subroutines (continued)
Function
Description
PLIDUMP
Dumps information about currently open files, the calling path to the
current location, etc.
PLIEBCDIC
Converts from ASCII to EBCDIC
PLIFILL
Fills n bytes at an address with a specified byte value
PLIFREE
Frees the storage associated with a pointer to heap storage
PLIMOVE
Moves n bytes from one address to another
PLIOVER
Moves n bytes from one address to another, compensating for possible
overlap of the source and target
PLIREST
Restarts program execution (z/OS only)
PLIRETC
Sets the PL/I return code value
PLISAXA
Allows you to perform SAX-style parsing of an XML document residing
in a buffer in your program
PLISAXB
Allows you to perform SAX-style parsing of an XML document residing
in a file
PLISAXC
Allows you to perform SAX-style parsing of an XML document residing
in a buffer in your program
PLISAXD
Allows you to perform SAX-style parsing with XML validation of an
XML document residing in a buffer in your program
PLISRTA
Allows the use of DFSORT to sort an input file to produce a sorted
output file
PLISRTB
Allows the use of DFSORT to sort input records provided by an E15
PL/I exit procedure to produce a sorted output file
PLISRTC
Allows the use of DFSORT to sort an input file to produce sorted
records that are processed by an E35 PL/I exit procedure
PLISRTD
Allows the use of DFSORT to sort input records provided by an E15
PL/I exit procedure to produce sorted records that are processed by an
E35 PL/I exit procedure
PLITRANxy
Translates an x-byte buffer to a y-byte buffer where x and y may be any
combination of 1 and 2.
Chapter 18. Built-in functions, pseudovariables, and subroutines
403
ABS
ABS
ABS returns the absolute value of x. It is the positive value of x.
ABS(x)
x
Expression.
The mode of the result is REAL. The result has the base, scale, and precision of x,
except when x is COMPLEX FIXED(p,q). In the latter case, the result is REAL
FIXED(min(n,p+1),q) where n is N for DECIMAL and M for BINARY.
404
Enterprise PL/I for z/OS Language Reference
ACOS
ACOS
ACOS returns a real floating-point value that is an approximation of the inverse
(arc) cosine in radians of x.
ACOS(x)
x
Real expression, where ABS(x) <= 1.
The result is in the range:
0 ≤ ACOS(x) ≤ π
and has the base and precision of x.
Chapter 18. Built-in functions, pseudovariables, and subroutines
405
ADD
ADD
ADD returns the sum of x and y with a precision specified by p and q. The base,
scale, and mode of the result are determined by the rules for expression evaluation
unless overruled by the PRECTYPE compiler option.
ADD(x,y,p
)
,q
x and y
Expressions.
p
Restricted expression. It specifies the number of digits to be maintained
throughout the operation.
q
Restricted expression specifying the scaling factor of the result. For a
fixed-point result, if q is omitted, a scaling factor of zero is the default. For a
floating-point result, q must be omitted.
ADD can be used for subtraction by prefixing a minus sign to the operand to be
subtracted.
406
Enterprise PL/I for z/OS Language Reference
ADDR
ADDR
ADDR returns the pointer value that identifies the generation of x.
ADDR(x)
x
Reference. It refers to a variable of any data type, data organization, alignment,
and storage class except:
v A subscripted reference to a variable that is an unaligned fixed-length bit
string
v A reference to a DEFINED or BASED variable or simple parameter, which is
an unaligned fixed-length bit string
v A minor structure or union whose first base element is an unaligned
fixed-length bit string (except where it is also the first element of the
containing major structure or union)
v A major structure or union that has the DEFINED attribute or is a
parameter, and that has an unaligned fixed-length bit string as its first
element
v A reference that is not to connected storage
If x is a reference to:
v An aggregate parameter, it must have the CONNECTED attribute
v An aggregate, the returned value identifies the first element
v A component or cross section of an aggregate, the returned value takes into
account subscripting and structure or union qualification
v A varying string, the returned value identifies the 2-byte prefix
v An area, the returned value identifies the control information
v A controlled variable that is not allocated in the current program, the null
pointer value is returned
v A based variable, the result is the value of the pointer explicitly qualifying x
(if it appears), or associated with x in its declaration (if it exists), or a null
pointer
v A parameter, and a dummy argument has been created, the returned value
identifies the dummy argument
Chapter 18. Built-in functions, pseudovariables, and subroutines
407
ADDRDATA
ADDRDATA
ADDRDATA returns the pointer value that identifies the generation of x.
ADDRDATA(x)
x
Reference.
ADDRDATA behaves the same as the ADDR built-in function except in the
following instance:
v When applied to a varying string, ADDRDATA returns the address of the first
data byte of the string (rather than of the length field).
408
Enterprise PL/I for z/OS Language Reference
ALL
ALL
ALL returns a bit string in which each bit is 1 if the corresponding bit in each
element of x exists and is 1. The length of the result is equal to that of the longest
element.
ALL(x)
x
Computational array expression. If x is not a bit string array, then x is
converted to a bit string array.
Chapter 18. Built-in functions, pseudovariables, and subroutines
409
ALLCOMPARE
ALLCOMPARE
ALLCOMPARE(x, y, z) returns a BIT(1) value that indicates the result of comparing
two structures.
ALLCOMPARE (x,y
)
,z
x
Structure reference
y
Structure reference
z
A CHAR(2) constant. When uppercased, the constant must have one of these
values: EQ, LE, LT, GT, GE, or NE. If you do not specify z, EQ is the default
value.
EQ Equal to
LE Less than or equal to
LT Less than
GT Greater than
GE Greater than or equal to
NE Not equal to
x and y must be similar structure references.
The corresponding elements of x and y must be comparable.
For example, ALLCOMPARE(x, y, 'lt') returns ’1’B if each leaf element of x is less
than the corresponding leaf element of y.
410
Enterprise PL/I for z/OS Language Reference
ALLOCATE
ALLOCATE
ALLOCATE allocates storage of size n in heap storage and returns the pointer to
the allocated storage.
ALLOCATE(n)
Abbreviation: ALLOC
n
Expression. n must be nonnegative. If necessary, n is converted to REAL FIXED
BINARY(31,0).
If the requested amount of storage is not available, the STORAGE condition is
raised.
Chapter 18. Built-in functions, pseudovariables, and subroutines
411
ALLOCATION
ALLOCATION
ALLOCATION returns a FIXED BINARY(31,0) specifying the number of
generations that can be accessed in the current program for x.
ALLOCATION(x)
Abbreviation: ALLOCN
x
Level-1 unsubscripted controlled variable.
If x is not allocated in the current program, the result is zero.
412
Enterprise PL/I for z/OS Language Reference
ALLOCSIZE
ALLOCSIZE
ALLOCSIZE returns a FIXED BIN(31,0) value giving the amount of storage
allocated with a specified pointer. To use this built-in function, you must also
specify the CHECK(STORAGE) compile-time option.
ALLOCSIZE(p)
p
Pointer expression.
ALLOCSIZE returns 0 if the pointer does not point to the start of a piece of
allocated storage.
Note that the pointer passed to ALLOCSIZE is "rounded down" to the nearest
doubleword and that rounded value is compared against all allocated addresses
when similarly rounded down.
Chapter 18. Built-in functions, pseudovariables, and subroutines
413
ANY
ANY
ANY returns a bit string in which each bit is 1 if the corresponding bit in any
element of x exists and is 1. The length of the result is equal to that of the longest
element.
ANY(x)
x
414
Computational array expression. If x is not a bit string array, then x is
converted to a bit string array.
Enterprise PL/I for z/OS Language Reference
ASIN
ASIN
ASIN returns a real floating-point value that is an approximation of the inverse
(arc) sine in radians of x.
ASIN(x)
x
Real expression, where ABS(x) <= 1.
The result is in the range:
-π/2 ≤ ASIN(x) ≤ π/2
and has the base and precision of x.
Chapter 18. Built-in functions, pseudovariables, and subroutines
415
ATAN
ATAN
ATAN returns a floating-point value that is an approximation of the inverse (arc)
tangent in radians of x or of a ratio x/y.
ATAN(x
)
,y
x and y
Expressions.
If x alone is specified, the result has the base and precision of x, and is in the
range:
-π/2 < ATAN(x) < π/2
If x and y are specified, each must be real. An error exists if x and y are both
zero. The result for all other values of x and y has the precision of the longer
argument, a base determined by the rules for expressions, and a value given
by:
ATAN(x/y)
π/2
-π/2
π + ATAN(x/y)
-π + ATAN(x/y)
416
Enterprise PL/I for z/OS Language Reference
for
for
for
for
for
y>0
y=0
y=0
y<0
y<0
and
and
and
and
x>0
x<0
x>=0
x<0
ATAND
ATAND
ATAND returns a real floating-point value that is an approximation of the inverse
(arc) tangent in degrees of x or of a ratio x/y.
ATAND(x
)
,y
x and y
Expressions.
If x alone is specified it must be real. The result has the base and precision of
x, and is in the range:
-90 < ATAND(x) < 90
If x and y are specified, each must be real. The value of the result is given by:
(180/π) * ATAN(x,y)
For argument requirements and attributes of the result see “ATAN” on page 416.
Chapter 18. Built-in functions, pseudovariables, and subroutines
417
ATANH
ATANH
ATANH returns a floating-point value that has the base, mode, and precision of x,
and is an approximation of the inverse (arc) hyperbolic tangent of x.
ATANH(x)
x
Expression. ABS(x)<1.
The result has a value given by:
LOG((1 + x)/(1 - x))/2
418
Enterprise PL/I for z/OS Language Reference
AUTOMATIC
AUTOMATIC
AUTOMATIC allocates storage of size n automatic storage and returns the pointer
to the allocated storage.
AUTOMATIC(n)
Abbreviation: AUTO
n
Expression. n must be nonnegative. If necessary, n is converted to REAL FIXED
BINARY(31,0).
The storage acquired cannot be explicitly freed; the storage is automatically freed
when the block terminates.
Chapter 18. Built-in functions, pseudovariables, and subroutines
419
AVAILABLEAREA
AVAILABLEAREA
AVAILABLEAREA returns a FIXED BINARY(31,0) value. The value returned by
AVAILABLEAREA is the size of the largest single allocation that can be obtained
from the area x.
AVAILABLEAREA(x)
A reference with the AREA attribute.
x
Example
dcl Uarea area(1000);
dcl Pz ptr;
dcl C99z char(99) varyingz based(Pz);
dcl (SizeBefore, SizeAfter) fixed bin(31);
SizeBefore = availablearea(Uarea);
/* returns 1000
Alloc C99z in(Uarea);
SizeAfter = availablearea(Uarea);
/* returns 896
dcl C9 char(896) based(Pz);
Alloc C9 in(Uarea);
420
Enterprise PL/I for z/OS Language Reference
*/
*/
BINARY
BINARY
BINARY returns the binary value of x, with a precision specified by p and q. The
result has the mode and scale of x.
BINARY(x
)
,p
,q
Abbreviation: BIN
x
Expression.
p
Restricted expression. Specifies the number of digits to be maintained
throughout the operation; it must not exceed the implementation limit.
q
Restricted expression. It specifies the scaling factor of the result. For a
fixed-point result, if p is given and q is omitted, a scaling factor of zero is the
default. For a floating-point result, q must be omitted.
If both p and q are omitted, the precision of the result is determined from the rules
for base conversion.
Chapter 18. Built-in functions, pseudovariables, and subroutines
421
BINARYVALUE
BINARYVALUE
BINARYVALUE returns a FIXED BINARY(31,0) value that is the converted value
of x; x can be a pointer, offset, or ordinal.
BINARYVALUE(x)
Abbreviation: BINVALUE
x
422
Expression.
Enterprise PL/I for z/OS Language Reference
BIT
BIT
BIT returns a result that is the bit value of x, and has a length specified by y.
BIT(x
)
,y
x
Expression.
y
Expression. If necessary, y is converted to a real fixed-point binary value. If y is
omitted, the length is determined by the rules for type conversion. If y = 0, the
result is the null bit string. y must not be negative.
Chapter 18. Built-in functions, pseudovariables, and subroutines
423
BITLOCATION
BITLOCATION
BITLOCATION returns a FIXED BINARY(31,0) result that is the location of bit x
within the byte that contains x. The value returned is always between 0 and 7 (0 ≤
value ≤ 7).
BITLOCATION(x)
Abbreviation: BITLOC
x
Reference of type unaligned bit. If x does not have type unaligned bit, a value
of 0 is returned.
x must not be subscripted.
BITLOCATION can be used in restricted expressions, with the following
limitations. If BITLOC(x) is used to set:
v The extent of a variable y that must have constant extents, or
v The value of a variable y that must have a constant value,
then x must be declared before y.
For examples, see “LOCATION” on page 520.
424
Enterprise PL/I for z/OS Language Reference
BOOL
BOOL
BOOL returns a bit string that is the result of the Boolean operation z, on x and y.
The length of the result is equal to that of the longer operand, x or y.
BOOL(x,y,z)
x and y
Expressions. x and y are converted to bit strings, if necessary. If x and y are of
different lengths, the shorter is padded on the right with zeros to match the
longer.
z
Expression. z is converted to a bit string of length 4, if necessary. When a bit
from x is matched with a bit from y, the corresponding bit of the result is
specified by a selected bit of z, as follows:
x
0
0
1
1
y
0
1
0
1
Result
bit 1 of
bit 2 of
bit 3 of
bit 4 of
z
z
z
z
Chapter 18. Built-in functions, pseudovariables, and subroutines
425
BYTE
BYTE
BYTE is a synonym for CHARVAL. For more information, refer to “CHARVAL” on
page 435.
426
Enterprise PL/I for z/OS Language Reference
CDS
CDS
CDS returns a FIXED BINARY(31) value that indicates if the old and current
values in a compare double and swap were equal.
CDS(p,q,x)
p
Address of the old FIXED BINARY(63) value.
q
Address of the current FIXED BINARY(63) value.
x
The new FIXED BINARY(63) value.
CDS compares the "current" and "old" values. If they are equal, the "new" value is
copied over the "current", and a value of 0 is returned. If they are unequal, the
"current" value is copied over the "old", and a value of 1 is returned.
On z/OS, the CDS built-in function implements the CDS instruction. For a detailed
description of this function, read the appendices in the Principles of Operations
manual.
On Intel, the CDS built-in function uses the Intel cmpxchg8 instruction in the same
manner that the CS built-in function uses the cmpxchg4 instruction.
Chapter 18. Built-in functions, pseudovariables, and subroutines
427
CEIL
CEIL
CEIL determines the smallest integer value greater than or equal to x, and assigns
this value to the result.
CEIL(x)
x
Real expression.
The result has the mode, base, scale, and precision of x, except when x is
fixed-point with precision (p,q). The precision of the result is then given by:
(min(N,max(p-q+1,1)),0)
where N is the maximum number of digits allowed.
428
Enterprise PL/I for z/OS Language Reference
CENTERLEFT
CENTERLEFT
CENTERLEFT returns a string that is the result of inserting string x in the center
(or one position to the left of center) of a string with length y and padded on the
left and on the right with the character z as needed. Specifying a value for z is
optional.
CENTERLEFT
CENTRELEFT
(x,y
)
,z
Abbreviation: CENTER
x
Expression that is converted to character.
y
Expression that is converted to FIXED BINARY(31,0).
z
Optional expression. If specified, z must be CHARACTER(1) NONVARYING
type.
Example
dcl Source char value(’Feel the Power’);
dcl Target20 char(20);
dcl Target21 char(21);
Target20 = center (Source, length(Target20), ’*’);
/* ’***Feel the Power***’ - exactly centered */
Target21 = center (Source, length(Target21), ’*’);
/* ’***Feel the Power****’ - leaning left! */
If z is omitted, a blank is used as the padding character.
Chapter 18. Built-in functions, pseudovariables, and subroutines
429
CENTRELEFT
CENTRELEFT
Abbreviation: CENTRE
CENTRELEFT is a synonym for CENTERLEFT.
430
Enterprise PL/I for z/OS Language Reference
CENTERRIGHT
CENTERRIGHT
CENTERRIGHT returns a string that is the result of inserting string x in the center
(or one position to the right of center) of a string with length y and padded on the
left and on the right with the character z as needed. Specifying a value for z is
optional.
CENTERRIGHT
CENTRERIGHT
(x,y
)
,z
x
Expression that is converted to character.
y
Expression that is converted to FIXED BINARY(31,0).
z
Optional expression. If specified, z must be CHARACTER(1) NONVARYING
type.
Example
dcl Source char value(’Feel the Power’);
dcl Target20 char(20);
dcl Target21 char(21);
Target20 = centerright (Source, length(Target20), ’*’);
/* ’***Feel the Power***’ - exactly centered */
Target21 = centerright (Source, length(Target21), ’*’);
/* ’****Feel the Power***’ - leaning right! */
If z is omitted, a blank is used as the padding character.
Chapter 18. Built-in functions, pseudovariables, and subroutines
431
CENTRERIGHT
CENTRERIGHT
CENTRERIGHT is a synonym for CENTERRIGHT.
432
Enterprise PL/I for z/OS Language Reference
CHARACTER
CHARACTER
CHARACTER returns the character value of x, with a length specified by y.
CHARACTER also supports conversion from graphic to character type.
CHARACTER(x
)
,y
Abbreviation: CHAR
Expression.
x
x must have a computational type.
When x is nongraphic, CHARACTER returns x converted to character.
When x is GRAPHIC, CHARACTER returns x converted to SBCS characters. If
a DBCS character cannot be translated to an SBCS equivalent, the
CONVERSION condition is raised.
The values of x are not checked.
Expression. If necessary, y is converted to a real fixed-point binary value.
y
If y is omitted, the length is determined by the rules for type conversion.
y cannot be negative.
If y = 0, the result is the null character string.
Example
Conversion from graphic to character:
dcl X graphic(6);
dcl A char (6);
A = char(X);
For X with value
.A.B.C.D.E.F
Intermediate Result
ABCDEF
A is assigned
ABCDEF
Chapter 18. Built-in functions, pseudovariables, and subroutines
433
CHARGRAPHIC
CHARGRAPHIC
CHARGRAPHIC converts a GRAPHIC (DBCS) string x to a mixed character string
with a length specified by y.
CHARGRAPHIC(x
)
,y
Abbreviation: CHARG
x
Expression.
x must be a GRAPHIC string. CHARACTER returns x converted to a mixed
character string.
y
Expression. If necessary, y is converted to a real fixed-point binary value.
If y is omitted, the length is determined by the rules for type conversion.
y cannot be negative.
If y = 0, the result is the null character string.
The following rules apply:
v If y = 1, the result is a character string of 1 blank.
v If y is greater than the length needed to contain the character string, the
result is padded with SBCS blanks.
v If y is less than the length needed to contain the character string, the result
is truncated. The integrity is preserved by truncating after a graphic, and
appending an SBCS blank if necessary, to complete the length of the string.
Example 1
Conversion from graphic to character, where y is long enough to contain the result:
dcl X graphic(6);
dcl A char (12);
A = char(X,12);
For X with value
Intermediate Result
A is assigned
.A.B.C.D.E.F
.A.B.C.D.E.F
.A.B.C.D.E.F
Example 2
Conversion from graphic to character, where y is too short to contain the result:
dcl X graphic(6);
dcl A char (12);
A = char(X,11);
434
For X with value
Intermediate Result
A is assigned
.A.B.C.D.E.F
.A.B.C.D.E.F
.A.B.C.D.Eb
Enterprise PL/I for z/OS Language Reference
CHARVAL
CHARVAL
CHARVAL returns the CHARACTER(1) value corresponding to an integer.
CHARVAL ( n )
n
Expression converted to UNSIGNED FIXED BIN(8) if necessary.
CHARVAL(n) has the same bit value as n (that is, UNSPEC(CHARVAL(n)) is equal
to UNSPEC(n)), but it has the attributes CHARACTER(1).
CHARVAL is the inverse of RANK (when applied to character).
Chapter 18. Built-in functions, pseudovariables, and subroutines
435
CHECKSTG
CHECKSTG
CHECKSTG returns a bit(1) value which indicates whether a specified pointer
value is the start of a piece of uncorrupted allocated storage. If no pointer value is
supplied, CHECKSTG determines whether all allocated storage is uncorrupted. To
use this built-in function, you must also specify the CHECK(STORAGE)
compile-time option.
CHECKSTG(
)
p
p
Pointer expression.
When an allocation is made, it is followed by eight extra bytes which are set to
'ff'x. The allocation is considered uncorrupted if those bytes have not been altered.
The pointer expression must point to storage allocated for a BASED variable.
436
Enterprise PL/I for z/OS Language Reference
COLLATE
COLLATE
COLLATE returns a CHARACTER(256) string comprising the 256 possible
CHARACTER(1) values one time each in the collating order.
COLLATE
()
Chapter 18. Built-in functions, pseudovariables, and subroutines
437
COMPARE
COMPARE
COMPARE returns a FIXED BINARY(31,0) value that is:
v Zero, if the z bytes at the addresses x and y are identical
v Negative, if the z bytes at x are less than those at y
v Positive, if the z bytes at x are greater than those at y
COMPARE(x,y,z)
x and y
Expressions. Both must have the POINTER or OFFSET type. If OFFSET, the
expression must be declared with the AREA qualification.
Expression that is converted to FIXED BINARY(31,0).
z
Example
dcl Result fixed bin;
dcl 1 Str1,
2 B fixed bin(31),
2 C pointer,
2 * union,
3 D char(4),
3 E fixed bin(31),
3 *,
4 * char(3),
4 F fixed bin(8) unsigned,
2 * char(0);
dcl 1 Template nonasgn static,
2 * fixed bin(31) init(16),
2 * pointer init(null()),
2 * char(4) init(’’),
2 * char(0);
/* ’’X */
call plimove(addr(Str1), addr(Template), stg(Str1));
Result = compare(addr(Str1), addr(Template), stg(Str1));
D = ’DSA ’;
Result = compare(addr(Str1), addr(Template), stg(Str1));
B = 15;
/* ’00000F00’X */
D = ’DSA ’;
Result = compare(addr(Str1), addr(Template), stg(Str1));
438
Enterprise PL/I for z/OS Language Reference
/*
0 */
/*
1 */
/* -1 */
COMPLEX
COMPLEX
COMPLEX returns the complex value x + yI.
COMPLEX(x,y)
Abbreviation: CPLX
x and y
Real expressions.
If x and y differ in base, the decimal argument is converted to binary. If they
differ in scale, the fixed-point argument is converted to floating-point. The
result has the common base and scale.
If fixed-point, the precision of the result is given by the following:
(min(N,max(p1-q1,p2-q2)+max(q1,q2)),max(q1,q2))
In this example, (p1,q1) and (p2,q2) are the precisions of x and y, respectively, and
N is the maximum number of digits allowed.
After any necessary conversions have been performed, if the arguments are
floating-point, the result has the precision of the longer argument.
Chapter 18. Built-in functions, pseudovariables, and subroutines
439
CONJG
CONJG
CONJG returns the conjugate of x, that is, the value of the expression with the sign
of the imaginary part reversed.
CONJG(x)
x
Expression.
If x is real, it is converted to complex. The result has the base, scale, mode, and
precision of x.
440
Enterprise PL/I for z/OS Language Reference
COPY
COPY
COPY returns a string consisting of y concatenated copies of the string x.
COPY(x,y)
x
Expression.
x must have a computational type and should have a string type. If not, it is
converted to character.
y
An integer expression with a nonnegative value. It specifies the number of
repetitions. It must have a computational type and is converted to FIXED
BINARY(31,0).
If y is zero, the result is a null string.
Considering the following code:
copy(’Walla
’,1)
repeat(’Walla
’,1)
/*
returns ’Walla
’
*/
/*
returns ’Walla
Walla
’
*/
In the preceding example, repeat(x,n) is equivalent to copy(x,n+1).
Chapter 18. Built-in functions, pseudovariables, and subroutines
441
COS
COS
COS returns a floating-point value that has the base, precision, and mode of x, and
is an approximation of the cosine of x.
COS(x)
x
442
Expression with a value in radians.
Enterprise PL/I for z/OS Language Reference
COSD
COSD
COSD returns a real floating-point value that has the base and precision of x, and
is an approximation of the cosine of x.
COSD(x)
x
Real expression with a value in degrees.
Chapter 18. Built-in functions, pseudovariables, and subroutines
443
COSH
COSH
COSH returns a floating-point value that has the base, precision, and mode of x,
and is an approximation of the hyperbolic cosine of x.
COSH(x)
x
444
Expression.
Enterprise PL/I for z/OS Language Reference
COUNT
COUNT
COUNT returns an unscaled REAL FIXED BINARY value specifying the number of
data items transmitted during the last GET or PUT operation on x.
COUNT(x)
x
File-reference. The file must be open and have the STREAM attribute.
The count of transmitted items for a GET or PUT operation on x is initialized to
zero before the first data item is transmitted, and is incremented by one after the
transmission of each data item in the list. If x is not open in the current program, a
value of zero is returned.
If an ON-unit or procedure is entered during a GET or PUT operation, and within
that ON-unit or procedure, a GET or PUT operation is executed for x, the value of
COUNT is reset for the new operation. It is restored when the original GET or
PUT is continued.
The BIFPREC compiler option determines the precision of the result returned.
Chapter 18. Built-in functions, pseudovariables, and subroutines
445
CS
CS
CS returns a FIXED BINARY(31) value that indicates if the old and current values
in a compare and swap were equal.
CS(p,q,x)
p
Address of the old FIXED BINARY(31) value.
q
Address of the current FIXED BINARY(31) value.
x
The new FIXED BINARY(31) value.
CS compares the "current" and "old" values. If they are equal, the "new" value is
copied over the "current", and a value of 0 is returned. If they are unequal, the
"current" value is copied over the "old", and a value of 1 is returned.
So, CS could be implemented as the following PL/I function, but then it would not
be atomic at all. :
cs: proc( old_Addr, current_Addr, new )
returns( fixed bin(31) byvalue )
options( byvalue );
dcl old_Addr
pointer;
dcl current_Addr pointer;
dcl new
fixed bin(31);
dcl old
dcl current
fixed bin(31) based(old_addr);
fixed bin(31) based(current_addr);
if current = old then
do;
current = new;
return( 0 );
end;
else
do;
old = current;
return( 1 );
end;
end;
On z/OS, the CS built-in function implements the CS instruction. For a detailed
description of this function, read the appendices in the Principles of Operations
manual.
On Intel, the CDS built-in function uses the Intel cmpxchg4 instruction. The
cmpxchg4 instruction takes the address of a "current" value, a "new" value and an
"old" value. It returns the original "current" value and updates it with the "new"
value only if it equaled the "old" value.
So, on Intel, the CS built-in function is implemented via the following inline
function:
cs: proc( old_Addr, current_Addr, new )
returns( fixed bin(31) byvalue )
options( byvalue );
446
Enterprise PL/I for z/OS Language Reference
CS
dcl old_Addr
pointer;
dcl current_Addr pointer;
dcl new
fixed bin(31);
dcl old
dcl current
fixed bin(31) based(old_addr);
fixed bin(31) based(current_addr);
if cmpxchg4( current_Addr, new, old ) = old then
do;
return( 0 );
end;
else
do;
old = current;
return( 1 );
end;
end;
Chapter 18. Built-in functions, pseudovariables, and subroutines
447
CURRENTSIZE
CURRENTSIZE
CURRENTSIZE returns a FIXED BINARY value giving the implementation-defined
storage, in bytes, required by x.
CURRENTSIZE(x)
x
A variable of any data type, data organization, and storage class except:
v A BASED, DEFINED, parameter, subscripted, or structure or union
base-element variable that is an unaligned fixed-length bit string
v A minor structure or union whose first or last base element is an unaligned
fixed-length bit string (except where it is also the first or last element of the
containing major structure or union)
v A major structure or union that has the BASED, DEFINED, or parameter
attribute, and which has an unaligned fixed-length bit string as its first or
last element
v A variable not in connected storage
The value returned by CURRENTSIZE(x) is defined as the number of bytes that
would be transmitted in the following circumstances:
declare F file record output
environment(scalarvarying);
write file(F) from(S);
If x is a scalar varying-length string, the returned value includes the length-prefix
of the string and the number of currently-used bytes. It does not include any
unused bytes in the string.
If x is a scalar area, the returned value includes the area control bytes and the
current extent of the area. It does not include any unused bytes at the end of the
area.
If x is an aggregate containing areas or varying-length strings, the returned value
includes the area control bytes, the maximum sizes of the areas, the length prefixes
of the strings, and the number of bytes in the maximum lengths of the strings. The
exception to this rule is:
If x is a structure or union whose last element is a nondimensioned area, the
returned value includes that area's control bytes and the current extent of that
area. It does not include any unused bytes at the end of that area.
The CURRENTSIZE built-in function must not be used on a BASED variable with
adjustable extents if that variable has not been allocated.
Under the CMPAT(V3) compiler option, CURRENTSIZE returns a FIXED BIN(63)
value. Under all other CMPAT options, it returns a FIXED BIN(31) value.
For examples of the CURRENTSIZE built-in function, refer to the “SIZE” on page
650.
448
Enterprise PL/I for z/OS Language Reference
CURRENTSTORAGE
CURRENTSTORAGE
Abbreviation: CSTG
CURRENTSTORAGE is a synonym for CURRENTSIZE. For more information, see
“CURRENTSIZE” on page 448.
Chapter 18. Built-in functions, pseudovariables, and subroutines
449
DATAFIELD
DATAFIELD
DATAFIELD is in context in a NAME condition ON-unit (or any of its dynamic
descendants). It returns a character string whose value is the contents of the field
that raised the condition. It is also in context in an ON-unit (or any of its dynamic
descendants) for an ERROR or FINISH condition raised as part of the implicit
action for the NAME condition.
DATAFIELD
()
If the string that raised the condition contains DBCS identifiers, GRAPHIC data, or
mixed character data, DATAFIELD returns a mixed character string.
If DATAFIELD is used out of context, a null string is returned.
450
Enterprise PL/I for z/OS Language Reference
DATE
DATE
DATE returns a nonvarying character(6) string containing the date in the format,
YYMMDD.
DATE
()
Chapter 18. Built-in functions, pseudovariables, and subroutines
451
DATETIME
DATETIME
DATETIME returns a character string timestamp of today's date in either the
default or a user-specified format.
DATETIME
(
)
y
y
Expression
If present, it specifies the date/time pattern in which the date is returned. If y
is missing, it is assumed to be the default date/time pattern
'YYYYMMDDHHMISS999'.
See Table 51 on page 394 for the allowed patterns.
y must have computational type and should have character type. If not, it is
converted to character.
See “DAYS” on page 453 for an example of using DATETIME.
452
Enterprise PL/I for z/OS Language Reference
DAYS
DAYS
DAYS returns a FIXED BINARY(31,0) value which is the number of days (in Lilian
format) corresponding to the date d.
DAYS
(
)
d
,p
,w
String expression representing a date. If omitted, it is assumed to be the value
returned by DATETIME().
d
The value for d must have computational type and should have character type.
If not, d is converted to character.
One of the supported date/time patterns. If omitted, it is assumed to be the
value 'YYYYMMDDHHMISS9999'.
p
p must have computational type and should have character type. If not, it is
converted to character.
An integer expression that defines a century window to be used to handle any
two-digit year formats.
v If the value is positive, such as 1950, it is treated as a year.
v If negative or zero, the value specifies an offset to be subtracted from the
current, system-supplied year.
w
v If omitted, w defaults to the value specified in the WINDOW compile-time
option.
Example
dcl
dcl
dcl
dcl
dcl
dcl
Date_format value (’MMDDYYYY’) char;
Todays_date char(length(Date_format));
Sep2_1993 char(length(Date_format));
Days_of_July4_1993 fixed bin(31);
Msg char(100) varying;
Date_due char(length(Date_format));
Todays_date = datetime(date_format);
/* e.g. 06161993
*/
Days_of_July4_1993 = days(’07041993’,’MMDDYYYY’);
Sep2_1993 = daystodate(days_of_July4_1993 + 60, Date_format);
/* 09021993
*/
Date_due = daystodate(days() + 60, Date_format);
/* assuming today is July 4, 1993, this would be Sept. 2, 1993
*/
Msg = ’Please pay amount due on or before ’ {
substr(Date_due, 1, 2) { ’/’ {
substr(Date_due, 3,2) { ’/’ {
substr(Date_due, 5);
The allowed patterns are listed in Table 51 on page 394. For an explanation of
Lilian format, see “Date/time built-in functions” on page 392.
Chapter 18. Built-in functions, pseudovariables, and subroutines
453
DAYSTODATE
DAYSTODATE
DAYSTODATE returns a nonvarying character string containing the date in the
form p that corresponds to d days (in Lilian format).
DAYSTODATE ( d
)
,p
,w
d
The number of days (in Lilian format). d must have a computational type and
is converted to FIXED BINARY(31,0) if necessary.
p
One of the supported date/time patterns.
If omitted, p is assumed to be the default date/time pattern
'YYYYMMDDHHMISS999' (same as the default format returned by
DATETIME).
w
An integer expression that defines a century window to be used to handle any
two-digit year formats.
v If the value is positive, such as 1950, it is treated as a year.
v If negative or zero, the value specifies an offset to be subtracted from the
current, system-supplied year.
v If omitted, w defaults to the value specified in the WINDOW compile-time
option.
The allowed patterns are listed in Table 51 on page 394. For an explanation of
Lilian format, see “Date/time built-in functions” on page 392.
See “DAYS” on page 453 for an example using DAYSTODATE.
454
Enterprise PL/I for z/OS Language Reference
DAYSTOSECS
DAYSTOSECS
DAYSTOSECS returns a FLOAT BINARY(53) value that is the number of seconds
corresponding to the number of days x.
DAYSTOSECS(x)
x
Expression.
x must have a computational type and is converted to FIXED BINARY(31,0) if
necessary.
DAYSTOSECS(x) is the same as x*(24*60*60).
Chapter 18. Built-in functions, pseudovariables, and subroutines
455
DECIMAL
DECIMAL
DECIMAL returns the decimal value of x, with a precision specified by p and q.
The result has the mode and scale of x.
DECIMAL(x
)
,p
,q
Abbreviation: DEC
x
Reference.
p
Restricted expression specifying the number of digits to be maintained
throughout the operation.
q
Restricted expression specifying the scaling factor of the result. For a
fixed-point result, if p is given and q is omitted, a scaling factor of zero is
assumed. For a floating-point result, q must be omitted.
If both p and q are omitted, the precision of the result is determined from the rules
for base conversion.
456
Enterprise PL/I for z/OS Language Reference
DIMENSION
DIMENSION
DIMENSION returns a FIXED BINARY value specifying the current extent of
dimension y of x.
DIMENSION(x
)
,y
Abbreviation: DIM
x
Array reference. x must not have less than y dimensions.
y
Expression specifying a particular dimension of x. If necessary, y is converted
to a FIXED BINARY(31,0). y must be greater than or equal to 1. If y is not
supplied, it defaults to 1.
y can be omitted only if the array is one-dimensional.
If y exceeds the number of dimensions of x, the DIMENSION function returns an
undefined value.
Under the CMPAT(V3) compiler option, DIMENSION returns a FIXED BIN(63)
value. Under the CMPAT(V2) and CMPAT(LE) compiler options, DIMENSION
returns a FIXED BIN(31) value, while under the CMPAT(V1) compiler option, it
returns a FIXED BIN(15) value.
Using LBOUND and HBOUND instead of DIMENSION is recommended.
Chapter 18. Built-in functions, pseudovariables, and subroutines
457
DIVIDE
DIVIDE
DIVIDE returns the quotient of x/y with a precision specified by p and q. The base,
scale, and mode of the result follow the rules for expression evaluation unless
overruled by the PRECTYPE compiler option.
DIVIDE(x,y,p
)
,q
458
x
Expression.
y
Expression. If y = 0, the ZERODIVIDE condition is raised.
p
Restricted expression specifying the number of digits to be maintained
throughout the operation.
q
Restricted expression specifying the scaling factor of the result. For a
fixed-point result, if q is omitted, a scaling factor of zero is the default. For a
floating-point result, q must be omitted.
Enterprise PL/I for z/OS Language Reference
EDIT
EDIT
EDIT returns a character string of length LENGTH(y). Its value is equivalent to
what would result if x were assigned to a variable declared with the picture
specification given by y.
For the valid picture characters, see Chapter 14, “Picture specification characters,”
on page 333.
EDIT(x,y)
Expression
x
x must have computational type.
String expression.
y
y must have character type and must contain picture characters that are valid
for a PICTURE data item. If y does not contain a valid picture specification, the
ERROR condition is raised.
Example
dcl
dcl
dcl
z =
z =
z =
z =
z =
z =
z =
z =
z =
pic1 char(9) init (’ZZZZZZZZ9’);
pic2 char(7) init (’ZZ9V.99’);
num fixed dec (9) init (123456789);
edit (num, pic1);
edit (num, pic2);
edit (num, substr(pic1,8));
edit (num, substr(pic2,1,5));
edit (num, substr(pic1,7,3));
edit (num, substr(pic2,3,5));
edit (’1’, substr(pic1,7,3));
edit (’PL/I’, ’AAXA’);
edit (’PL/I’, ’AAAA’);
/* ’123456789’
/*
’789.00’
/*
’89’
/*
’789.’
/*
’789’
/*
’9.00’
/*
’ 1’
/*
’PL/I’
/* raises conversion
*/
*/
*/
*/
*/
*/
*/
*/
*/
If x cannot be edited into the picture specification given by y, the conditions raised
are those that would be raised if x were assigned to a PICTURE data item which
has the same picture specification contained in y.
Chapter 18. Built-in functions, pseudovariables, and subroutines
459
EMPTY
EMPTY
EMPTY returns an area of zero extent. It can be used to free all allocations in an
area.
EMPTY
()
The value of this function is assigned to an area variable when the variable is
allocated. Consider this example:
declare A area,
I based (P),
J based (Q);
allocate I in(A), J in (A);
A = empty();
/* Equivalent to:
460
Enterprise PL/I for z/OS Language Reference
free I in (A), J in (A); */
ENDFILE
ENDFILE
ENDFILE returns a '1'B when the end of the file is reached; '0'B if the end is not
reached. If the file is not open, the ERROR condition is raised.
ENDFILE(x)
x
File reference.
ENDFILE can be used to detect the end-of-file condition for bytestream files; for
example, files that require the use of the FILEREAD built-in function.
Chapter 18. Built-in functions, pseudovariables, and subroutines
461
ENTRYADDR
ENTRYADDR
ENTRYADDR returns a pointer value that is the address of the first executed
instruction if the entry x is invoked. The entry x must represent a non-nested
procedure.
ENTRYADDR(x)
x
Entry reference.
If x is a fetchable entry constant, it must be fetched before ENTRYADDR is
executed. However, if x has been released, then ENTRYADDR will return
SYSNULL.
462
Enterprise PL/I for z/OS Language Reference
ENTRYADDR pseudovariable
ENTRYADDR pseudovariable
The ENTRYADDR pseudovariable initializes an entry variable, x, with the address
of the entry to be invoked.
ENTRYADDR(x)
x
Entry reference.
Note: If the address supplied to the ENTRYADDR variable is the address of an
internal procedure, the results are unpredictable.
Chapter 18. Built-in functions, pseudovariables, and subroutines
463
EPSILON
EPSILON
EPSILON returns a floating-point value that is the spacing between x and the next
positive number when x is 1. It has the base, mode, and precision of x.
EPSILON(x)
x
REAL FLOAT expression.
EPSILON(x) is a constant and can be used in restricted expressions.
464
Enterprise PL/I for z/OS Language Reference
ERF
ERF
ERF returns a real floating-point value that is an approximation of the error
function of x.
ERF(x)
x
Real expression.
The result has the base and precision of x, and a value given by:
(2/ '(π) ) ∫x0 EXP(-(t2 ))dt
Chapter 18. Built-in functions, pseudovariables, and subroutines
465
ERFC
ERFC
ERFC returns a real floating-point value that is an approximation of the
complement of the error function of x.
ERFC(x)
x
Real expression.
The result has the base and precision of x, and a value given by:
1 - ERF(x)
466
Enterprise PL/I for z/OS Language Reference
EXP
EXP
EXP returns a floating-point value that is an approximation of the base, e, of the
natural logarithm system raised to the power x.
EXP(x)
x
Expression.
The result has the base, mode, and precision of x.
Chapter 18. Built-in functions, pseudovariables, and subroutines
467
EXPONENT
EXPONENT
EXPONENT returns a FIXED BINARY(31,0) value that is the exponent part of x.
EXPONENT(x)
x
Expression. x must be declared as REAL FLOAT.
EXPONENT(x) is not the “mathematical” exponent of x. If x = 0,
EXPONENT(x) = 0. For other values of x, EXPONENT(x) is the unique number e
such that:
(e-1)
radix(x)
e
<= abs(x) < radix(x)
Consequently, EXPONENT(1e0) equals 1 and not 0.
468
Enterprise PL/I for z/OS Language Reference
FILEDDINT
FILEDDINT
FILEDDINT returns a FIXED BIN(31) value that is the value of attribute c for file x.
FILEDDINT(x,c)
x
File reference.
c
Character string that holds the attribute to be queried.
When using FILEDDINT, the following are valid values for c:
blksize
bufsize
delay
filesize
keylen
keyloc
recsize
retry
The ERROR condition with oncode 1010 is raised when the file is not open or the
attribute is invalid for the file being queried.
FILEDDINT(x,'BLKSIZE') is valid only on z/OS. FILEDDINT(x,'BLKSIZE') will
return the blocksize for a CONSECUTIVE file. It will return 0 for an HFS file and
will return 0 for a VSAM file.
FILEDDINT(x,'FILESIZE') will, on z/OS, return a value of 0 except for HFS files.
FILEDDINT(x,'KEYLOC') and FILEDDINT(x,'KEYLEN') are valid only for VSAM
KSDS files.
Chapter 18. Built-in functions, pseudovariables, and subroutines
469
FILEDDTEST
FILEDDTEST
FILEDDTEST returns a FIXED BIN(31) value that holds the value 1 if the attribute
c applies to file x. Otherwise, a value of 0 is returned.
FILEDDTEST(x,c)
x
File reference.
c
Character string that holds the attribute to be queried.
When using FILEDDTEST, the following are valid values for c:
append
bkwd
ctlasa
delimit
descendkey
genkey
graphic
lrmskip
print
prompt
scalarvarying
skip0
The ERROR condition with oncode 1010 is raised when the file is not open or the
attribute is invalid for the file being queried.
470
Enterprise PL/I for z/OS Language Reference
FILEDDWORD
FILEDDWORD
FILEDDWORD returns a character string that is the value of the attribute c for file
x.
FILEDDWORD(x,c)
x
File reference.
c
Character string that holds the attribute to be queried.
When using FILEDDWORD, the following are valid options for c:
access
amthd
action
charset
filename
organization
putpage
recfm
share
type
typef
These options return the following values:
v ACCESS returns SEQUENTIAL or DIRECT.
v ACTION returns INPUT, OUTPUT, or UPDATE.
v AMTHD returns VSAM KSDS, VSAM ESDS or VSAM RRDS on the z/OS
platform and FILESYS, DDM, BTRIEVE or ISAM on the Windows or AIX
platforms.
v CHARSET returns ASCII or EBCDIC.
v On the z/OS platform, FILENAME returns the fully qualified path name for
HFS files and the MVS data set name for all other files except it returns the
value 'NULLFILE' for files specified with either DSN=NULLFILE and DD
DUMMY. For a MVS data set that is a member of a PDS or PDSE, the name
returned includes the member name. On the Windows and AIX platforms, it
returns the fully qualified path name of the file .
v ORGANIZATION returns CONSECUTIVE, RELATIVE, REGIONAL(1) or
INDEXED.
v RECFM returns the appropriate record format setting for the file, and U for
VSAM files. This option is only valid on z/OS.
v SHARE returns NONE, READ or ALL.
v TYPE returns RECORD or STREAM.
v TYPEF returns the type of the native file.
The ERROR condition with oncode 1010 is raised when the file is not open or the
attribute is invalid for the file being queried.
FILEDDWORD(x,'RECFM') is valid only under z/OS.
Chapter 18. Built-in functions, pseudovariables, and subroutines
471
FILEID
FILEID
FILEID returns a FIXED BIN(31) value that is the system token for a PL/I file
constant or variable.
FILEID(x)
x
File reference.
This token should not be used for any purpose which could be accomplished by a
PL/I statement.
On z/OS, the token holds the address of the DCB associated with a RECORD or
STREAM file or of the ACB associated with a VSAM RECORD file. The token is
not valid for other files. Note: the DCB or ACB address is provided so that
applications can read the DCB or ACB. The DCB and ACB must not be altered.
The ERROR condition with oncode 1010 is raised when the file is not open.
472
Enterprise PL/I for z/OS Language Reference
FILEOPEN
FILEOPEN
FILEOPEN returns '1'B if the file x is open and '0'B if the file is not open.
FILEOPEN(x)
x
File reference.
Chapter 18. Built-in functions, pseudovariables, and subroutines
473
FILEREAD
FILEREAD
FILEREAD attempts to read z storage units (bytes) from file x into location y. It
returns the number of storage units actually read.
FILEREAD(x,y,z)
x
File reference.
y
Expression with type POINTER or OFFSET. If the type is OFFSET, the
expression must be an OFFSET variable declared with the AREA attribute.
z
Expression with computational type that is converted to FIXED BIN(31,0).
FILEREAD can read only TYPE(U) files.
474
Enterprise PL/I for z/OS Language Reference
FILESEEK
FILESEEK
FILESEEK changes the current file position associated with file x to a new location
within the file. The next operation on the file takes place at the new location. It
also returns a FIXED BIN(31) value that is 0 if the change in file position is
successful and non-zero otherwise. FILESEEK is equivalent to the fseek function in
C.
FILESEEK(x,y,z)
x
File reference.
y
A FIXED BINARY(31) value that indicates the number of positions the file
pointer is to be moved relative to z.
z
A FIXED BINARY(31) value that indicates the origin from which the file
pointer is to be moved. The following values are valid:
-1
Beginning of the file
0
Current position of the file pointer
1
End of the file.
FILESEEK can be used only on TYPE(U) files.
Chapter 18. Built-in functions, pseudovariables, and subroutines
475
FILETELL
FILETELL
FILETELL returns a FIXED BINARY(31) value indicating the current position of the
file x. The value returned is an offset relative to the beginning of the file.
FILETELL is equivalent to the ftell function in C.
FILETELL(x)
x
File reference.
FILETELL can be used only on TYPE(U) files.
476
Enterprise PL/I for z/OS Language Reference
FILEWRITE
FILEWRITE
FILEWRITE attempts to write z storage units (bytes) to file x from location y It
returns the number of storage units actually written.
FILEWRITE(x,y,z)
x
File reference.
y
Expression with type POINTER or OFFSET. If the type is OFFSET, the
expression must be an OFFSET variable declared with the AREA attribute.
z
Expression with computational type that is converted to FIXED BIN(31,0).
FILEWRITE can write only to TYPE(U) files.
Chapter 18. Built-in functions, pseudovariables, and subroutines
477
FIXED
FIXED
FIXED returns the fixed-point value of x, with a precision specified by p and q. The
result has the base and mode of x.
FIXED(x
)
,p
,q
x
Expression.
p
Restricted expression that specifies the total number of digits in the result. It
must not exceed the implementation limit.
q
Restricted expression that specifies the scaling factor of the result. If q is
omitted, a scaling factor of zero is assumed.
If both p and q are omitted, the default values, (15,0) for a binary result or (5,0) for
a decimal result, are used.
478
Enterprise PL/I for z/OS Language Reference
FIXEDBIN
FIXEDBIN
FIXEDBIN returns a FIXED BIN value with precision and scale derived from the
source unless explicitly specified as parameters to the function.
FIXEDBIN(x
)
,p
,q
x
Expression.
p
Restricted expression that specifies the total number of digits in the result. It
must not exceed the implementation limit.
q
Restricted expression that specifies the scaling factor of the result. If q is
omitted, a scaling factor of zero is assumed.
If both p and q are omitted, the precision of the result is determined from the
source according to this table:
source
result
FIXED BIN(p,q)
FIXED BIN(p,q)
FIXED DEC(p,q)
FIXED BIN(r,s)
where r = min(M,1+CEIL(p*3.32))
and s = CEIL(ABS(q*3.32))*SIGN(q)
FLOAT BIN(p)
FIXED BIN(p,0)
FLOAT DEC(p)
FIXED BIN(r,0)
where r = min(M,CEIL(p*3.32))
BIT
FIXED BIN(M,0)
CHAR, GRAPHIC or
WIDECHAR
FIXED BIN(r,0)
where r = min(M,1+CEIL(N*3.32))
Chapter 18. Built-in functions, pseudovariables, and subroutines
479
FIXEDDEC
FIXEDDEC
FIXEDDEC returns a FIXED DEC value with precision and scale derived from the
source unless explicitly specified as parameters to the function.
FIXEDDEC(x
)
,p
,q
x
Expression.
p
Restricted expression that specifies the total number of digits in the result. It
must not exceed the implementation limit.
q
Restricted expression that specifies the scaling factor of the result. If q is
omitted, a scaling factor of zero is assumed.
If both p and q are omitted, the precision of the result is determined from the
source according to this table:
480
source
result
FIXED BIN(p,q)
FIXED DEC(r,s)
where r = min(N,1+CEIL(p/3.32))
and s=CEIL(ABS(q/3.32))*SIGN(q)
FIXED DEC(p,q)
FIXED DEC(p,q)
FLOAT BIN(p)
FIXED DEC(r,0)
where r = min(N,CEIL(p/3.32)
FLOAT DEC(p)
FIXED DEC(p,0)
BIT
FIXED DEC(r,0)
where where r = min(N,1+CEIL(M/3.32))
CHAR, GRAPHIC or
WIDECHAR
FIXED DEC(N,0)
Enterprise PL/I for z/OS Language Reference
FLOAT
FLOAT
FLOAT returns the approximate floating-point value of x, with a precision
specified by p. The result has the base and mode of x.
FLOAT(x
)
,p
x
Expression.
p
Restricted expression that specifies the minimum number of digits in the
result.
If p is omitted, the precision of the result is determined from the rules for base
conversion.
If p is omitted, the default value, 15 for a binary result or 5 for a decimal
result, is used.
Chapter 18. Built-in functions, pseudovariables, and subroutines
481
FLOATBIN
FLOATBIN
FLOATBIN returns a FLOAT BIN value with precision derived from the source
unless explicitly specified as a parameter to the function.
FLOATBIN(x
)
,p
x
Expression.
p
Restricted expression that specifies the total number of digits in the result. It
must not exceed the implementation limit.
If p is omitted, the precision of the result is determined from the source according
to this table:
482
source
result
FIXED BIN(p,q)
FLOAT BIN(p)
FIXED DEC(p,q)
FLOAT BIN(r)
where r = CEIL(p*3.32)
FLOAT BIN(p)
FLOAT BIN(p)
FLOAT DEC(p)
FLOAT BIN(r)
where r = CEIL(p*3.32)
BIT
FLOAT BIN(M)
CHAR, GRAPHIC or
WIDECHAR
FLOAT BIN(r)
where r = CEIL(N*3.32)
Enterprise PL/I for z/OS Language Reference
FLOATDEC
FLOATDEC
FLOATDEC returns a FLOAT DEC value with precision derived from the source
unless explicitly specified as a parameter to the function.
FLOATDEC(x
)
,p
x
Expression.
p
Restricted expression that specifies the total number of digits in the result. It
must not exceed the implementation limit.
If p is omitted, the precision of the result is determined from the source according
to this table:
source
result
FIXED BIN(p,q)
FLOAT DEC(r)
where r = CEIL(p/3.32)
FIXED DEC(p,q)
FLOAT DEC(p)
FLOAT BIN(p)
FLOAT DEC(r)
where r = CEIL(p/3.32)
FLOAT DEC(p)
FLOAT DEC(p)
BIT
FLOAT DEC(r)
where r = CEIL(M/3.32)
CHAR, GRAPHIC or
WIDECHAR
FLOAT DEC(N)
Chapter 18. Built-in functions, pseudovariables, and subroutines
483
FLOOR
FLOOR
FLOOR returns the largest integer value less than or equal to x.
FLOOR(x)
x
Real expression.
The mode, base, scale, and precision of the result match the argument. Except
when x is fixed-point with precision (p,q), the precision of the result is given by:
(min(n,max(p-q+1,1)),0)
where n is the maximum number of digits allowed and is N for FIXED DECIMAL
or M for FIXED BINARY.
484
Enterprise PL/I for z/OS Language Reference
GAMMA
GAMMA
GAMMA is an approximation of the gamma of x, as given by the following
equation:
gamma(x) =
∫∞0 (ux-1)(e-x)du
GAMMA returns a floating-point value that has the base, mode, and precision of x.
GAMMA(x)
x
Real expression. The value of x must be greater than zero.
Chapter 18. Built-in functions, pseudovariables, and subroutines
485
GETENV
GETENV
GETENV returns a character value representing a specified environment variable.
GETENV(x)
x
486
Expression naming an environment variable.
Enterprise PL/I for z/OS Language Reference
GRAPHIC
GRAPHIC
GRAPHIC can be used to explicitly convert character (or mixed character) data to
GRAPHIC data. All other data first converts to character, and then to the
GRAPHIC data type.
GRAPHIC returns the graphic value of x, with a length in graphic symbols
specified by y.
Characters convert to graphics. The content of x is checked for validity during
conversion, using the same rules as for checking graphic and mixed character
constants.
GRAPHIC(x
)
,y
x
Expression. When x is GRAPHIC, it is subject to a length change, with
applicable padding or truncation. When x is nongraphic, it is converted to
character, if necessary. SBCS characters are converted to equivalent DBCS
characters.
y
Expression. If necessary, y is converted to a real fixed-point binary value. If y is
omitted, the length is determined by the rules for type conversion.
y must not be negative.
If y = 0, the result is the null graphic string.
The following rules apply:
v If y is greater than the length needed to contain the graphic string, the result
is padded with graphic blanks.
v If y is less than the length needed to contain the graphic string, the result is
truncated.
Example 1
Conversion from CHARACTER to GRAPHIC, where the target is long enough to
contain the result:
dcl X char (11) varying;
dcl A graphic (11);
A = graphic(X,8);
For X with values
Intermediate Result
A is assigned
ABCDEFGHIJ
123
123A.B.C
.A.B.C.D.E.F.G.H.I.J
.1.2.3
.1.2.3.A.B.C
.A.B.C.D.E.F.G.H.b.b.b
.1.2.3.b.b.b.b.b.b.b.b
.1.2.3.A.B.C.b.b.b.b.b
where .b is a DBCS blank.
Example 2
Conversion from CHARACTER to GRAPHIC, where the target is too short to
contain the result:
Chapter 18. Built-in functions, pseudovariables, and subroutines
487
GRAPHIC
dcl X char (10) varying;
dcl A graphic (8);
A = graphic(X);
488
For X with value
Intermediate Result
A is assigned
ABCDEFGHIJ
.A.B.C.D.E.F.G.H.I.J
.A.B.C.D.E.F.G.H
Enterprise PL/I for z/OS Language Reference
HANDLE
HANDLE
HANDLE returns a handle to the typed structure x.
HANDLE(x)
x
Typed structure.
Chapter 18. Built-in functions, pseudovariables, and subroutines
489
HBOUND
HBOUND
HBOUND returns a FIXED BINARY value specifying the current upper bound of
dimension y of x.
HBOUND(x
)
,y
x
Array reference. x must not have less than y dimensions.
y
Expression specifying a particular dimension of x. If necessary, y is converted
to FIXED BINARY(31,0). y must be greater than or equal to 1. If y is not
supplied, it defaults to 1.
y can be omitted only if the array is one-dimensional.
Under the CMPAT(V3) compiler option, HBOUND returns a FIXED BIN(63) value.
Under the CMPAT(V2) and CMPAT(LE) compiler options, HBOUND returns a
FIXED BIN(31) value, while under the CMPAT(V1) compiler option, it returns a
FIXED BIN(15) value.
490
Enterprise PL/I for z/OS Language Reference
HBOUNDACROSS
HBOUNDACROSS
HBOUNDACROSS returns a FIXED BINARY value specifying the current upper
bound of a DIMACROSS reference x.
HBOUNDACROSS(x)
x
DIMACROSS reference.
Under the CMPAT(V3) compiler option, HBOUNDACROSS returns a FIXED
BIN(63) value. Under the CMPAT(V2) and CMPAT(LE) compiler options,
HBOUNDACROSS returns a FIXED BIN(31) value, while under the CMPAT(V1)
compiler option, it returns a FIXED BIN(15) value.
The following example shows the use of HBOUNDACROSS:
dcl jx fixed bin(31);
dcl
1 a,
2 b fixed bin,
2 c fixed bin;
dcl 1 xa( 100 ) like a dimacross;
...
do jx = 1 to hboundacross(xa);
a = xa, by dimacross(jx);
...
end;
Chapter 18. Built-in functions, pseudovariables, and subroutines
491
HEX
HEX
HEX returns a character string that is the hexadecimal representation of the storage
that contains x.
HEX(x
)
,z
HEX(x) returns a character string of length 2 * size(x).
HEX(x,z) returns a character string that contains x with the character z inserted
between every set of eight characters in the output string. Its length is 2 * size(x)
+ ((size(x) - 1)/4).
Under the compiler option USAGE(HEX(CSTG)), the length used in the above
calculations is based, for VARYING and VARYINGZ strings, on cstg(x) rather
than on stg(x).
x
Expression that represents any variable. The whole number of bytes that
contain x is converted to hexadecimal.
z
Expression. If specified, z must have the type CHARACTER(1) NONVARYING.
Integer, offset and pointer values will be presented in bigendian form.
Example 1
dcl
dcl
dcl
dcl
Sweet char(5) init(’Sweet’);
Sixteen fixed bin(31) init(16) littleendian;
XSweet char(size(Sweet)*2+(size(Sweet)-1)/4);
XSixteen char(size(Sixteen)*2+(size(Sixteen)-1)/4);
XSweet = hex(Sweet,’-’);
/* ’53776565-74’ */
XSweet = heximage(addr(Sweet),length(Sweet),’-’);
/* ’53776565-74’ */
XSixteen = hex(Sixteen,’-’);
/* ’00000010’ - bytes reversed */
XSixteen = heximage(addr(Sixteen),stg(Sixteen),’-’);
/* ’10000000’ - bytes NOT reversed */
Example 2
dcl X fixed bin(15) littleendian;
dcl Y fixed bin(15) bigendian;
492
X = 258;
Y = 258;
/* stored as ’0201’B4 */
/* stored as ’0102’B4 */
display (hex(X));
display (hex(Y));
/* displays 0102 */
/* displays 0102 */
display (heximage( addr(X), stg(X) ));
display (heximage( addr(Y), stg(Y) ));
/* displays 0201 */
/* displays 0102 */
Enterprise PL/I for z/OS Language Reference
HEX
Note: This function does not return an exact image of x in storage. If an exact
image is required, use the HEXIMAGE built-in function.
Chapter 18. Built-in functions, pseudovariables, and subroutines
493
HEXIMAGE
HEXIMAGE
HEXIMAGE returns a character string that is the hexadecimal representation of the
storage at a specified location.
HEXIMAGE(p,n
)
,z
HEXIMAGE(p,n) returns a character string that is the hexadecimal representation
of n bytes of storage at location p. Its length is 2 * n.
HEXIMAGE(p,n,z) returns a character string that is the hexadecimal representation
of n bytes of storage at location p with character z inserted between every set of
eight characters in the output string. Its length is (2 * n) + ((n - 1)/4).
p
Restricted expression that must have a locator type (POINTER or OFFSET). If p
is OFFSET, it must have the AREA attribute.
n
Expression. n must have a computational type and is converted to FIXED
BINARY(31,0).
z
If specified, z must have the type CHARACTER(1) NONVARYING.
For examples of the HEXIMAGE built-in function, see “HEX” on page 492.
494
Enterprise PL/I for z/OS Language Reference
HIGH
HIGH
HIGH returns a character string of length x, where each character is the highest
character in the collating sequence (hexadecimal FF).
HIGH(x)
x
Expression. If necessary, x is converted to a positive real fixed-point binary
value. If x = 0, the result is the null character string.
Chapter 18. Built-in functions, pseudovariables, and subroutines
495
HUGE
HUGE
HUGE returns a floating-point value that is the largest positive value x can
assume. It has the base, mode, and precision of x.
HUGE(x)
x
Expression. x must have the attributes REAL FLOAT.
HUGE(x) is a constant and can be used in restricted expressions.
496
Enterprise PL/I for z/OS Language Reference
IAND
IAND
IAND returns the logical AND of its arguments
,
IAND( x, y
)
x and y
Expressions that must have a computational type.
If any argument is not REAL FIXED BIN(p,0), then it is converted to SIGNED
REAL FIXED BIN(p,0).
If any argument is SIGNED, then any UNSIGNED arguments are converted to
SIGNED.
The result is REAL FIXED BIN( max(p1,p2,...), 0 ). It is UNSIGNED if all the
arguments are UNSIGNED.
Chapter 18. Built-in functions, pseudovariables, and subroutines
497
IEOR
IEOR
IEOR returns the logical exclusive-OR of x and y. The result is unsigned if all
arguments are unsigned.
IEOR(x,y)
x and y
Expressions that must have a computational type.
If any argument is not REAL FIXED BIN(p,0), then it is converted to SIGNED
REAL FIXED BIN(p,0).
If any argument is SIGNED, then any UNSIGNED arguments are converted to
SIGNED.
The result is REAL FIXED BIN( max(p1,p2,...), 0 ). It is UNSIGNED if all the
arguments are UNSIGNED.
498
Enterprise PL/I for z/OS Language Reference
IMAG
IMAG
IMAG returns the imaginary part of x. The mode of the result is real and has the
base, scale, and precision of x.
IMAG(x)
x
Expression. If x is real, it is converted to complex, and an appropriate zero
value is returned.
Chapter 18. Built-in functions, pseudovariables, and subroutines
499
IMAG pseudovariable
IMAG pseudovariable
The IMAG pseudovariable assigns a real value or the real part of a complex value
to the coefficient of the imaginary part of x.
IMAG(x)
x
500
Complex reference.
Enterprise PL/I for z/OS Language Reference
INDEX
INDEX
INDEX returns an unscaled REAL FIXED BINARY value indicating the starting
position within x of a substring identical to y. You can also specify the location
within x where processing begins.
INDEX(x,y
)
,n
x
String-expression to be searched.
y
Target string-expression of the search.
n
n specifies the location within x at which to begin processing. It must have a
computational type and is converted to FIXED BINARY(31,0).
If y does not occur in x, or if either x or y have zero length, the value zero is
returned.
If n is less than 1 or if n is greater than 1 + length(x), the STRINGRANGE
condition will be raised, and the result will be 0.
The BIFPREC compiler option determines the precision of the result returned.
Example
dcl tractatus char
value( ’Wovon man nicht sprechen kann, ’ {
’darueber muss man schweigen.’ );
dcl pos fixed bin init(1);
pos = index( tractatus, ’man’, pos+1 ); /* pos = 07 */
pos = index( tractatus, ’man’, pos+1 ); /* pos = 46 */
pos = index( tractatus, ’man’, pos+1 ); /* pos = 00 */
Chapter 18. Built-in functions, pseudovariables, and subroutines
501
INDICATORS
INDICATORS
INDICATORS returns a FIXED BIN value giving the number of the elements at the
next logical level in a structure x.
INDICATORS(x)
x
Expression.
x must be a structure reference.
INDICATORS(x) always forms a restricted expression.
The INDICATORS built-in function is useful in declaring an indicator array for use
in SQL statements.
502
Enterprise PL/I for z/OS Language Reference
INOT
INOT
INOT returns the logical NOT of x.
INOT(x)
x
Expression. x must have a computational type.
If x is REAL FIXED BIN(p,0), then the result is REAL FIXED BIN(p,0) and it is
UNSIGNED if x is UNSIGNED. Otherwise, x is converted to SIGNED REAL FIXED
BIN(p,0) and the result has the same attributes.
Although INOT(x) has the opposite sign of x, INOT(x) is not the same as -x.
Examples
inot(0)
inot(-1)
inot(+1)
/*
/*
/*
produces -1 */
produces 0 */
produces -2 */
Chapter 18. Built-in functions, pseudovariables, and subroutines
503
IOR
IOR
IOR returns the logical OR of its arguments.
,
IOR( x, y
)
x and y
Expressions that must have a computational type.
If any argument is not REAL FIXED BIN(p,0), then it is converted to SIGNED
REAL FIXED BIN(p,0).
If any argument is SIGNED, then any UNSIGNED arguments are converted to
SIGNED.
The result is REAL FIXED BIN( max(p1,p2,...), 0 ). It is UNSIGNED if all the
arguments are UNSIGNED.
504
Enterprise PL/I for z/OS Language Reference
ISFINITE
ISFINITE
ISFINITE returns a '1'B if if the argument with which it is invoked is not a NAN
and not positive or negative infinity. Otherwise it returns a '0'B.
ISFINITE(x)
x
REAL FLOAT DECIMAL expression.
The FLOAT(DFP) compiler option must be in effect.
No floating-point exceptions will be raised no matter what the format of the
argument.
Chapter 18. Built-in functions, pseudovariables, and subroutines
505
ISIGNED
ISIGNED
ISIGNED(x) returns the result of casting x to a signed integer value without
changing its bit pattern.
ISIGNED(x)
x
Expression. x must have a computational type.
If x is not an integer, that is, if x is not REAL FIXED BIN with zero scale factor,
then it is converted to REAL FIXED BIN(p,0).
ISIGNED( x ) returns, for integer x, a value with the same bit pattern as x but the
attributes SIGNED FIXED BIN(p).
If x is UNSIGNED, p is given by:
v If precision(x) = 8, 16, 32 or 64, then p = precision(x) - 1 else p = precision(x).
v If x is SIGNED, p is equal to the precision of x.
Examples
ISIGNED(’ff_ff_ff_ff’xu) equals the SIGNED FIXED BIN(31) value -1.
506
Enterprise PL/I for z/OS Language Reference
ISINF
ISINF
ISINF returns a '1'B if if the argument with which it is invoked is an infinity.
Otherwise it returns a '0'B.
ISINF(x)
x
REAL FLOAT DECIMAL expression.
The FLOAT(DFP) compiler option must be in effect.
No floating-point exceptions will be raised no matter what the format of the
argument.
Chapter 18. Built-in functions, pseudovariables, and subroutines
507
ISLL
ISLL
ISLL(x,n) returns the result of logically shifting x to the left by n places, and
padding on the right with zeroes.
ISLL(x,n)
x
Expression. x must have a computational type.
n
Expression. n must have a computational type.
If x is REAL FIXED BIN(p,0) and SIGNED, the result is SIGNED REAL FIXED
BIN(r,0) where if p <= M1, r = M1; if p > M1, r = M2.
If x is REAL FIXED BIN(p,0) and UNSIGNED, the result is UNSIGNED REAL
FIXED BIN(r+1,0) where if p <= (M1+1), r = (M1+1); if p > (M1+1), r = (M2+1).
Otherwise, x is converted to SIGNED REAL FIXED BIN(p,0) and the result has the
same attributes as above.
If n is negative or if n is greater than r, the result is undefined.
Note: Unlike RAISE2(x,n), ISLL(x,n) can have a different sign than x does.
Examples
isll(+6,1)
isll(2147483645,1)
508
Enterprise PL/I for z/OS Language Reference
/* produces 12
*/
/* produces -6
*/
ISMAIN
ISMAIN
ISMAIN() returns a '1'B if the procedure in which it is invoked has the
OPTIONS(MAIN) attribute. Otherwise it returns a '0'B.
ISMAIN ( )
Chapter 18. Built-in functions, pseudovariables, and subroutines
509
ISNAN
ISNAN
ISNAN returns a '1'B if if the argument with which it is invoked is a NAN.
Otherwise it returns a '0'B.
ISNAN(x)
x
REAL FLOAT DECIMAL expression.
The FLOAT(DFP) compiler option must be in effect.
No floating-point exceptions will be raised no matter what the format of the
argument.
510
Enterprise PL/I for z/OS Language Reference
ISNORMAL
ISNORMAL
ISNORMAL returns a '1'B if if the argument with which it is invoked is not a zero,
subnormal, infinity or NaN. Otherwise it returns a '0'B.
ISNORMAL(x)
x
REAL FLOAT DECIMAL expression.
The FLOAT(DFP) compiler option must be in effect.
No floating-point exceptions will be raised no matter what the format of the
argument.
Chapter 18. Built-in functions, pseudovariables, and subroutines
511
ISRL
ISRL
ISRL(x,n) returns the result of logically shifting x to the right by n places, and
padding on the left with zeroes.
ISRL(x,n)
x
Expression. x must have a computational type.
n
Expression. n must have a computational type.
If x is REAL FIXED BIN(p,0) and:
v x is SIGNED, then the result is SIGNED REAL FIXED BIN(p,0).
v x is UNSIGNED, the result is UNSIGNED REAL FIXED BIN(p,0).
Otherwise, x is converted to SIGNED REAL FIXED BIN(p,0) and the result has the
same attributes.
The result is undefined if n is negative or if n is greater than M.
If x is nonnegative, ISRL(x,n) is equivalent to LOWER2(x,n); if x is negative,
ISRL(x,n) is positive, unless n=0.
Examples
isrl(+6,1)
isrl(-6,1)
512
Enterprise PL/I for z/OS Language Reference
/*
/*
produces 3
produces 2147483645
*/
*/
ISZERO
ISZERO
ISZERO returns a '1'B if if the argument with which it is invoked is a zero.
Otherwise it returns a '0'B.
ISZERO(x)
x
REAL FLOAT DECIMAL expression.
The FLOAT(DFP) compiler option must be in effect.
No floating-point exceptions will be raised no matter what the format of the
argument.
Chapter 18. Built-in functions, pseudovariables, and subroutines
513
IUNSIGNED
IUNSIGNED
IUNSIGNED(x) returns the result of casting x to an unsigned integer value without
changing its bit pattern.
IUNSIGNED(x)
x
Expression. x must have a computational type.
If x is not an integer, that is, if x is not REAL FIXED BIN with zero scale factor,
then it is converted to REAL FIXED BIN(p,0).
IUNSIGNED(x) returns, for integer x, a value with the same bit pattern as x but
the attributes UNSIGNED FIXED BIN(p).
If x is SIGNED, p is given by:
v If precision(x) = 7, 15, 31 or 63, then p = precision(x) + 1 else p = precision(x).
v If x is UNSIGNED, p is equal to the precision of x.
Examples
IUNSIGNED(’ff_ff_ff_ff’xn) equals the largest UNSIGNED FIXED BIN(32) value.
514
Enterprise PL/I for z/OS Language Reference
LBOUND
LBOUND
LBOUND returns a FIXED BINARY value specifying the current lower bound of
dimension y of x.
LBOUND(x
)
,y
x
Array reference. x must not have less than y dimensions.
y
Expression specifying a particular dimension of x. If necessary, y is converted
to FIXED BINARY(31,0). The value for y must be greater than or equal to 1.
and if y is not supplied, it defaults to 1.
The value for y can be omitted only if the array is one-dimensional.
Under the CMPAT(V3) compiler option, LBOUND returns a FIXED BIN(63) value.
Under the CMPAT(V2) and CMPAT(LE) compiler options, LBOUND returns a
FIXED BIN(31) value, while under the CMPAT(V1) compiler option, it returns a
FIXED BIN(15) value.
Chapter 18. Built-in functions, pseudovariables, and subroutines
515
LBOUNDACROSS
LBOUNDACROSS
LBOUNDACROSS returns a FIXED BINARY value specifying the current lower
bound of a DIMACROSS reference x.
LBOUNDACROSS(x)
x
DIMACROSS reference.
Under the CMPAT(V3) compiler option, LBOUNDACROSS returns a FIXED
BIN(63) value. Under the CMPAT(V2) and CMPAT(LE) compiler options,
LBOUNDACROSS returns a FIXED BIN(31) value, while under the CMPAT(V1)
compiler option, it returns a FIXED BIN(15) value.
516
Enterprise PL/I for z/OS Language Reference
LEFT
LEFT
LEFT returns a string that is the result of inserting string x at the left end of a
string with length n and padded on the right with the character z as needed.
LEFT(x,n
)
,z
x
Expression. x must have a computational type and should have a character
type. If not, it is converted to CHARACTER.
n
Expression. n must have a computational type and should have a character
type. If n does not have the attributes FIXED BINARY(31,0), it is converted to
them.
z
Expression. If specified, z must have the type CHARACTER(1) NONVARYING
type.
Example
dcl Source char value(’One Hundred SCIDS Marks’);
dcl Target char(30);
Target = left (Source, length(Target), ’*’);
/* ’One Hundred SCIDS Marks*******’
*/
If z is omitted, a blank is used as the padding character.
Chapter 18. Built-in functions, pseudovariables, and subroutines
517
LENGTH
LENGTH
LENGTH returns an unscaled REAL FIXED BINARY value specifying the current
length of x.
LENGTH(x)
x
String-expression. If x is binary, it is converted to bit string; otherwise, any
other conversion required is to character string.
For an example of the LENGTH built-in function, refer to “MAXLENGTH” on
page 530.
The BIFPREC compiler option determines the precision of the result returned.
518
Enterprise PL/I for z/OS Language Reference
LINENO
LINENO
LINENO returns an unscaled REAL FIXED BINARY specifying the current line
number of x.
LINENO(x)
x
File-reference.
The file must be open and have the PRINT attribute. If the file is not open or does
not have the PRINT attribute, 0 is returned.
The BIFPREC compiler option determines the precision of the result returned.
Chapter 18. Built-in functions, pseudovariables, and subroutines
519
LOCATION
LOCATION
LOCATION returns a FIXED BINARY value specifying the byte location of x
within the level-1 structure or union that has member x.
LOCATION(x)
Abbreviation: LOC
Structure or union member name. If x is not a member of a structure or union,
a value of 0 is returned. If x has the BIT attribute, the value returned by
LOCATION is the location of the byte that contains x.
x
The value for x must not be subscripted.
LOCATION can be used in restricted expressions, with a limitation. The value for x
must be declared before y if LOC(x) is used to set either of the following:
v The extent of a variable y that must have constant extents
v The value of a variable y that must have a constant value.
Under the CMPAT(V3) compiler option, LOCATION returns a FIXED BIN(63)
value. Under all other CMPAT options, it returns a FIXED BIN(31) value.
Example
dcl 1 Table static,
2 Tab2loc fixed bin(15) nonasgn init(loc(Tab2)),
/* location is 0; gets initialized to 8 */
2 Tab3loc fixed bin(15) nonasgn init(loc(Tab3)),
/* location is 2; gets initialized to 808 */
2 Length fixed bin nonasgn init(loc(End)),
/* location is 4 */
2 * fixed bin,
2 Tab2(20,20)
fixed bin,
/* location is 8 */
2 Tab3(20,20)
fixed bin,
/* location is 808 */
2 F2_loc fixed bin nonasgn init(loc(F2)),
/* location is 1608; gets initialized to 1612 */
2 F2_bitloc fixed bin nonasgn init(bitloc(F2)),
/* location is 1610; gets initialized to 1 */
2 Flags,
/* location is 1612 */
3 F1 bit(1),
3 F2 bit(1), /* bitlocation is 1 */
3 F3 bit(1),
2 Bits(16) bit, /* location is 1613 */
2 End char(0);
520
Enterprise PL/I for z/OS Language Reference
LOG
LOG
LOG returns a floating-point value that is an approximation of the natural
logarithm (the logarithm to the base e) of x. It has the base, mode, and precision of
x.
LOG(x)
x
Expression. x must be greater than zero.
Chapter 18. Built-in functions, pseudovariables, and subroutines
521
LOGGAMMA
LOGGAMMA
LOGGAMMA returns a floating-point value that is an approximation of the log of
gamma of x. The gamma of x is given by the following equation:
gamma(x) =
∫∞0 (ux-1)(e-x)du
LOGGAMMA has the base, mode, and precision of x.
LOGGAMMA(x)
x
522
Real expression. The value of x must be greater than 0.
Enterprise PL/I for z/OS Language Reference
LOG2
LOG2
LOG2 returns a real floating-point value that is an approximation of the binary
logarithm (the logarithm to the base 2) of x. It has the base and precision of x.
LOG2(x)
x
Real expression. The value of x must be greater than zero.
Chapter 18. Built-in functions, pseudovariables, and subroutines
523
LOG10
LOG10
LOG10 returns a real floating-point value that is an approximation of the common
logarithm (the logarithm to the base 10) of x. It has the base and precision of x.
LOG10(x)
x
524
Real expression. It must be greater than zero.
Enterprise PL/I for z/OS Language Reference
LOW
LOW
LOW returns a character string of length x, where each character is the lowest
character in the collating sequence (hexadecimal 00).
LOW(x)
x
Expression. If necessary, x is converted to a positive real fixed-point binary
value. If x = 0, the result is the null character string.
Chapter 18. Built-in functions, pseudovariables, and subroutines
525
LOWERCASE
LOWERCASE
LOWERCASE returns a character string with all the alphabetic characters from A
to Z converted to their lowercase equivalent.
LOWERCASE(x)
x
Expression. If necessary, x is converted to character.
LOWERCASE(x) is equivalent to
TRANSLATE( x,
’abcdefghijklmnopqrstuvwxyz’,
’ABCDEFGHIJKLMNOPQRSTUVWXYZ’ )
526
Enterprise PL/I for z/OS Language Reference
LOWER2
LOWER2
LOWER2(x,n) returns the value:
LOWER2(x,n)
Note: LOWER2(x,n) is equivalent to the assembler SRA(x,n).
x
Expression. x must have a computational type.
n
Expression. n must have a computational type.
If x is SIGNED REAL FIXED BIN(p,0), then the result has the same attributes.
Otherwise, x is converted to SIGNED REAL FIXED BIN(p,0) and the result has the
same attributes.
The result is undefined if n is negative or if n is greater than M.
Examples
lower2 (+6,1)
/*
Produces 3
*/
lower2 (-6,1)
/*
Produces -3
*/
lower2 (-7,1)
/*
Produces -4
*/
Chapter 18. Built-in functions, pseudovariables, and subroutines
527
MAX
MAX
MAX returns the largest value from a set of two or more expressions.
,
MAX( x, y
)
x and y
Expressions.
All the arguments must be real. The result is real, with the common base and scale
of the arguments.
If the arguments are fixed-point with precisions:
(p1,q1),(p2,q2),...,(pn,qn)
then the precision of the result is given by:
(min(N,max(p1-q1,p2-q2,...,pn-qn) + max(q1,q2,...,qn)),max(q1,q2,...,qn))
where N is the maximum number of digits allowed.
If the arguments are floating-point with precisions:
p1,p2,p3,...pn
then the precision of the result is given by:
max(p1,p2,p3,...pn)
The maximum number of arguments allowed is 64.
528
Enterprise PL/I for z/OS Language Reference
MAXEXP
MAXEXP
MAXEXP returns a FIXED BINARY(31,0) value that is the maximum value that
EXPONENT(x) could assume.
MAXEXP(x)
x
Expression. x must have the REAL and FLOAT attributes.
MAXEXP(x) is a constant and can be used in restricted expressions.
Example (Intel Values)
maxexp(x) = 128
maxexp(x) = 1024
maxexp(x) = 16384
for x float bin(p), p <= 21
for x float bin(p), 21 < p <= 53
for x float bin(p), 53 < p
maxexp(x) = 128
maxexp(x) = 1024
maxexp(x) = 16384
for x float dec(p), p <= 6
for x float dec(p), 6 < p <= 16
for x float dec(p), 16 < p
Example (AIX Values)
maxexp(x) = 128
maxexp(x) = 1024
maxexp(x) = 1024
for x float bin(p), p <= 21
for x float bin(p), 21 < p <= 53
for x float bin(p), 53 < p
maxexp(x) = 128
maxexp(x) = 1024
maxexp(x) = 1024
for x float dec(p), p <= 6
for x float dec(p), 6 < p <= 16
for x float dec(p), 16 < p
Example (z/OS Hexdecimal Values)
maxexp(x) = 63
maxexp(x) = 63
maxexp(x) = 63
for x float bin(p), p <= 21
for x float bin(p), 21 < p <= 53
for x float bin(p), 53 < p
maxexp(x) = 63
maxexp(x) = 63
maxexp(x) = 63
for x float dec(p), p <= 6
for x float dec(p), 6 < p <= 16
for x float dec(p), 16 < p
Example (z/OS IEEE Binary Floating Point Values)
maxexp(x) = 128
maxexp(x) = 1024
maxexp(x) = 16384
for x float bin(p), p <= 21
for x float bin(p), 21 < p <= 53
for x float bin(p), 53 < p
maxexp(x) = 128
maxexp(x) = 1024
maxexp(x) = 16384
for x float dec(p), p <= 6
for x float dec(p), 6 < p <= 16
for x float dec(p), 16 < p
Example (z/OS IEEE Decimal Floating Point Values)
maxexp(x) = 97
maxexp(x) = 385
maxexp(x) = 6145
for x float dec(p), p <= 7
for x float dec(p), 7 < p <= 16
for x float dec(p), 16 < p
Chapter 18. Built-in functions, pseudovariables, and subroutines
529
MAXLENGTH
MAXLENGTH
MAXLENGTH returns the maximum length of a string.
MAXLENGTH(x)
Expression. x must have a computational type and should have a string type.
If not, it is converted to character.
x
Example
dcl x char(20);
dcl y char(20) varying;
x, y = ’’;
x = copy( ’*’, length(x) );
y = copy( ’*’, length(y) );
/* fills x with ’*’
*/
/* leaves y unchanged */
x = copy( ’-’, maxlength(x) ); /* fills x with ’-’
y = copy( ’-’, maxlength(y) ); /* fills y with ’-’
*/
*/
Note that the first assignment to y leaves it unchanged because length(y) will return
zero when it is used in the code snippet above (since y is VARYING and was
previously set to '').
However, the second assignment to y fills it with 20 - signs because maxlength(y)
will return 20 (the declared length of y).
530
Enterprise PL/I for z/OS Language Reference
MEMCONVERT
MEMCONVERT
MEMCONVERT converts the data in a source buffer from the specified source
codepage to a a specified target codepage, stores the result in a target buffer, and
returns an unscaled REAL FIXED BINARY value specifying the number of bytes
written to the target buffer.
MEMCONVERT (
p
,
n
,
c ,
p
Address of the target buffer.
n
Length of the target buffer.
c
Target code page.
q
Address of the source buffer.
m
Length of the source buffer.
d
Source code page.
q ,
m
, d
)
The buffer lengths must have computational type and will be converted to FIXED
BINARY(31,0).
The buffer lengths must be nonnegative.
If either buffer length is zero, the result is zero.
The code page must have computational type and will be converted to FIXED
BINARY(31,0).
The code pages must specify valid, supported code pages.
Chapter 18. Built-in functions, pseudovariables, and subroutines
531
MEMCU12
MEMCU12
MEMCU12 converts the data in a source buffer from UTF-8 to UTF-16, stores the
result in a target buffer, and returns an unscaled REAL FIXED BINARY value
specifying the number of bytes written to the target buffer.
MEMCU12 (
p
,
n ,
q
,
p
Address of the target buffer.
n
Length of the target buffer.
q
Address of the source buffer.
m
Length of the source buffer.
m
)
The buffer lengths must have computational type and will be converted to FIXED
BINARY(31,0).
The buffer lengths must be nonnegative.
If the target buffer is too small or if the source UTF-8 is invalid, a value of -1 is
returned.
532
Enterprise PL/I for z/OS Language Reference
MEMCU14
MEMCU14
MEMCU14 converts the data in a source buffer from UTF-8 to UTF-32, stores the
result in a target buffer, and returns an unscaled REAL FIXED BINARY value
specifying the number of bytes written to the target buffer.
MEMCU14 (
p ,
n
,
q
, m
p
Address of the target buffer.
n
Length of the target buffer.
q
Address of the source buffer.
m
Length of the source buffer.
)
The buffer lengths must have computational type and will be converted to FIXED
BINARY(31,0).
The buffer lengths must be nonnegative.
If the target buffer is too small or if the source UTF-8 is invalid, a value of -1 is
returned.
Chapter 18. Built-in functions, pseudovariables, and subroutines
533
MEMCU21
MEMCU21
MEMCU21 converts the data in a source buffer from UTF-16 to UTF-8, stores the
result in a target buffer, and returns an unscaled REAL FIXED BINARY value
specifying the number of bytes written to the target buffer.
MEMCU21 (
p
,
n ,
q
,
p
Address of the target buffer.
n
Length of the target buffer.
q
Address of the source buffer.
m
Length of the source buffer.
m
)
The buffer lengths must have computational type and will be converted to FIXED
BINARY(31,0).
The buffer lengths must be nonnegative.
If the target buffer is too small or if the source UTF-16 is invalid, a value of -1 is
returned.
534
Enterprise PL/I for z/OS Language Reference
MEMCU24
MEMCU24
MEMCU24 converts the data in a source buffer from UTF-16 to UTF-32, stores the
result in a target buffer, and returns an unscaled REAL FIXED BINARY value
specifying the number of bytes written to the target buffer.
MEMCU24 (
p ,
n
,
q
, m
p
Address of the target buffer.
n
Length of the target buffer.
q
Address of the source buffer.
m
Length of the source buffer.
)
The buffer lengths must have computational type and will be converted to FIXED
BINARY(31,0).
The buffer lengths must be nonnegative.
If the target buffer is too small or if the source UTF-16 is invalid, a value of -1 is
returned.
Chapter 18. Built-in functions, pseudovariables, and subroutines
535
MEMCU41
MEMCU41
MEMCU41 converts the data in a source buffer from UTF-32 to UTF-8, stores the
result in a target buffer, and returns an unscaled REAL FIXED BINARY value
specifying the number of bytes written to the target buffer.
MEMCU41 (
p
,
n ,
q
,
p
Address of the target buffer.
n
Length of the target buffer.
q
Address of the source buffer.
m
Length of the source buffer.
m
)
The buffer lengths must have computational type and will be converted to FIXED
BINARY(31,0).
The buffer lengths must be nonnegative.
If the target buffer is too small or if the source UTF-32 is invalid, a value of -1 is
returned.
536
Enterprise PL/I for z/OS Language Reference
MEMCU42
MEMCU42
MEMCU42 converts the data in a source buffer from UTF-32 to UTF-16, stores the
result in a target buffer, and returns an unscaled REAL FIXED BINARY value
specifying the number of bytes written to the target buffer.
MEMCU42 (
p ,
n
,
q
, m
p
Address of the target buffer.
n
Length of the target buffer.
q
Address of the source buffer.
m
Length of the source buffer.
)
The buffer lengths must have computational type and will be converted to FIXED
BINARY(31,0).
The buffer lengths must be nonnegative.
If the target buffer is too small or if the source UTF-32 is invalid, a value of -1 is
returned.
Chapter 18. Built-in functions, pseudovariables, and subroutines
537
MEMINDEX
MEMINDEX
MEMINDEX returns an unscaled REAL FIXED BINARY value indicating the
starting position within a buffer of a specified substring.
With 3 arguments, the function's syntax is :
MEMINDEX (
p
,
n
,
x )
p
Address of buffer to be searched
n
Length of buffer to be searched.
x
String-expression to use as the target of the search.
With 4 arguments, the function's syntax is
MEMINDEX (
p
, n
,
q
,
m )
p
Address of first buffer to be searched.
n
Length of first buffer to be searched.
q
Address of second buffer to use as the target of the search.
m
Length of second buffer to use as the target of the search.
The buffer lengths must have a computational type and will be converted to
FIXED BINARY(31,0).
The buffer lengths must be nonnegative
With 3 arguments, the target string-expression must have type CHARACTER
(including PICTURE), GRAPHIC or WIDECHAR. The buffer length is interpreted
as the number of units of that string type.
With 4 arguments, the buffer lengths specify a number of bytes and the search
performed is a character search.
For a VARYING or VARYINGZ string X and string Y, the function MEMINDEX(
ADDRDATA(X), LENGTH(X), Y ) will return the same value as INDEX( X, Y ).
Example
dcl cb(128*1024) char(1);
dcl wb(128*1024) widechar(1);
dcl pos fixed bin(31);
/* 128K bytes searched for the character string ’test’ */
pos = memindex( addr(cb), stg(cb), ’test’ );
/* 256K bytes searched for the string ’test’ as widechar */
pos = memindex( addr(wb), stg(wb), wchar(’<’) );
538
Enterprise PL/I for z/OS Language Reference
MEMSEARCH
MEMSEARCH
MEMSEARCH returns an unscaled REAL FIXED BINARY value specifying the first
position (from the left) in a buffer at which any character, graphic or widechar in a
given string appears.
MEMSEACRH (
p
,
n ,
x
)
p
Address of buffer to be searched.
n
Length of buffer to be searched.
x
String-expression.
The buffer length must have a computational type and will be converted to FIXED
BINARY(31,0).
The buffer length must be nonnegative.
The string-expression x must have type CHARACTER (including PICTURE),
GRAPHIC or WIDECHAR. The buffer length is interpreted as the number of units
of that string type.
The address p and the length n specify the "string" in which to search for any
character, graphic or widechar that appears in x.
If either the buffer length n is zero or x is the null string, the result is zero.
If x does not occur in the buffer, the result is zero.
Example
dcl cb(128*1024) char(1);
dcl wb(128*1024) widechar(1);
dcl pos fixed bin(31);
/* 128K bytes searched from the left for a numeric */
pos = memsearch( addr(cb), stg(cb), ’012345789’ );
/* 256K bytes searched from the left for a widechar ’0’ or ’1’ */
pos = memsearch( addr(wb), stg(wb), ’0030_0031’wx );
Chapter 18. Built-in functions, pseudovariables, and subroutines
539
MEMSEARCHR
MEMSEARCHR
MEMSEARCHR returns an unscaled REAL FIXED BINARY value specifying the
first position (from the right) in a buffer at which any character, graphic or
widechar in a given string appears
MEMSEACRHR (
p
, n
,
x
)
p
Address of buffer to be searched.
n
Length of buffer to be searched.
x
String-expression.
The buffer length must have a computational type and will be converted to FIXED
BINARY(31,0).
The buffer length must be nonnegative.
The string-expression x must have type CHARACTER (including PICTURE),
GRAPHIC or WIDECHAR. The buffer length is interpreted as the number of units
of that string type.
The address p and the length n specify the "string" in which to search for any
character, graphic or widechar that appears in x.
If either the buffer length n is zero or x is the null string, the result is zero.
If x does not occur in the buffer, the result is zero.
Example
dcl cb(128*1024) char(1);
dcl wb(128*1024) widechar(1);
dcl pos fixed bin(31);
/* 128K bytes searched from the right for a numeric */
pos = memsearchr( addr(cb), stg(cb), ’012345789’ );
/* 256K bytes searched from the right for a widechar ’0’ or ’1’ */
pos = memsearchr( addr(wb), stg(wb), ’0030_0031’wx );
540
Enterprise PL/I for z/OS Language Reference
MEMVERIFY
MEMVERIFY
MEMVERIFY returns an unscaled REAL FIXED BINARY value specifying the
position in a buffer of the first (from the left) character, graphic or widechar that is
not in a specified string.
MEMVERIFY (
p
,
n ,
x
)
p
Address of buffer to be searched.
n
Length of buffer to be searched.
x
String-expression.
The buffer length must have a computational type and will be converted to FIXED
BINARY(31,0).
The buffer length must be nonnegative.
The string-expression x must have type CHARACTER (including PICTURE),
GRAPHIC or WIDECHAR. The buffer length is interpreted as the number of units
of that string type.
The address p and the length n specify the "string" in which to search for any
character, graphic or widechar that does not appear in x.
If either the buffer length n is zero or x is the null string, the result is zero.
If all the characters, graphics or widechars in the buffer do appear in x, the result
is zero.
Example
dcl cb(128*1024) char(1);
dcl wb(128*1024) widechar(1);
dcl pos fixed bin(31);
/* 128K bytes searched from the left for a non-numeric */
pos = memverify( addr(cb), stg(cb), ’012345789’ );
/* 256K bytes searched from the left for the a non-blank widechar */
pos = memverify( addr(wb), stg(wb), ’0020’wx );
Chapter 18. Built-in functions, pseudovariables, and subroutines
541
MEMVERIFYR
MEMVERIFYR
MEMVERIFYR returns an unscaled REAL FIXED BINARY value specifying the
position in a buffer of the first (from the right) character, graphic or widechar that
is not in a specified string.
MEMVERIFYR (
p
, n
,
x
)
p
Address of buffer to be searched.
n
Length of buffer to be searched.
x
String-expression.
The buffer length must have a computational type and will be converted to FIXED
BINARY(31,0).
The buffer length must be nonnegative.
The string-expression x must have type CHARACTER (including PICTURE),
GRAPHIC or WIDECHAR. The buffer length is interpreted as the number of units
of that string type.
The address p and the length n specify the "string" in which to search for any
character, graphic or widechar that does not appear in x.
If either the buffer length n is zero or x is the null string, the result is zero.
If all the characters, graphics or widechars in the buffer do appear in x, the result
is zero.
Example
dcl cb(128*1024) char(1);
dcl wb(128*1024) widechar(1);
dcl pos fixed bin(31);
/* 128K bytes searched from the right for a non-numeric */
pos = memverify( addr(cb), stg(cb), ’012345789’ );
/* 256K bytes searched from the right for the a non-blank widechar */
pos = memverify( addr(wb), stg(wb), ’0020’wx );
542
Enterprise PL/I for z/OS Language Reference
MIN
MIN
MIN returns the smallest value from a set of one or more expressions.
,
MIN( x, y
)
x and y
Expressions.
All the arguments must be real. The result is real with the common base and scale
of the arguments.
The precision of the result is the same as that described in “MAX” on page 528.
The maximum number of arguments allowed is 64.
Chapter 18. Built-in functions, pseudovariables, and subroutines
543
MINEXP
MINEXP
MINEXP returns a FIXED BINARY(31,0) value that is the minimum value that
EXPONENT(x) could assume.
MINEXP(x)
x
Expression. x must have the REAL and FLOAT attributes.
MINEXP(x) is a constant and can be used in restricted expressions.
Example (Intel Values)
minexp(x) = -125
for x float bin(p), p <= 21
minexp(x) = -1021
for x float bin(p), 21 < p <= 53
minexp(x) = -16831
for x float bin(p), 53 < p
minexp(x) = -125
for x float dec(p), p <= 6
minexp(x) = -1021
for x float dec(p), 6 < p <= 16
minexp(x) = -16831
for x float dec(p), 16 < p
Example (AIX Values)
minexp(x) = -125
minexp(x) = -1021
minexp(x) = -968
for x float bin(p), p <= 21
for x float bin(p), 21 < p <= 53
for x float bin(p), 53 < p
minexp(x) = -125
minexp(x) = -1021
minexp(x) = -968
for x float dec(p), p <= 6
for x float dec(p), 6 < p <= 16
for x float dec(p), 16 < p
Example (z/OS Hexadecimal Values)
minexp(x) = -64
minexp(x) = -64
minexp(x) = -50
for x float bin(p), p <= 21
for x float bin(p), 21 < p <= 53
for x float bin(p), 53 < p
minexp(x) = -64
minexp(x) = -64
minexp(x) = -50
for x float dec(p), p <= 6
for x float dec(p), 6 < p <= 16
for x float dec(p), 16 < p
Example (z/OS IEEE Binary Floating Point Values)
minexp(x) = -125
for x float bin(p), p <= 21
minexp(x) = -1021 for x float bin(p), 21 < p <= 53
minexp(x) = -16381 for x float bin(p), 53 < p
minexp(x) = -125
for x float dec(p), p <= 6
minexp(x) = -1021 for x float dec(p), 6 < p <= 16
minexp(x) = -16381 for x float dec(p), 16 < p
Example (z/OS IEEE Decimal Floating Point Values)
minexp(x) = -94
minexp(x) = -382
minexp(x) = -6142
544
Enterprise PL/I for z/OS Language Reference
for x float dec(p), p <= 7
for x float dec(p), 7 < p <= 16
for x float dec(p), 16 < p
MOD
MOD
MOD returns the smallest nonnegative value, R, such that:
(x - R)/y = n
In this example, the value for n is an integer value. That is, R is the smallest
nonnegative value that must be subtracted from x to make it divisible by y.
MOD(x,y)
x
Real expression.
y
Real expression. If y = 0, the ZERODIVIDE condition is raised.
The result, R, is real with the common base and scale of the arguments. If the
result is floating-point, the precision is the greater of those of x and y. If the result
is fixed-point, the precision is given by the following:
(min(n,p2-q2+max(q1,q2)),max(q1,q2))
In this example, (p1,q1) and (p2,q2) are the precisions of x and y, respectively, and
n is N for FIXED DECIMAL or M for FIXED BINARY.
If x and y are fixed-point with different scaling factors, the argument with the
smaller scaling factor is converted to the larger scaling factor before R is calculated.
If the conversion fails, the result is unpredictable.
If the result has the attributes FIXED BIN and one or more of the operands has the
attributes UNSIGNED FIXED BIN, the result has the SIGNED attribute unless both
of the following conditions are true:
v All of the operands are UNSIGNED FIXED BIN.
v The RULES(ANS) compiler option is in effect.
If any of the conditions above is not true, each UNSIGNED operand is converted
to SIGNED. If the operand is too large, the conversion would:
v Raise the SIZE condition if SIZE is enabled.
v Produce a negative value if SIZE is not enabled.
The following example contrasts the MOD and REM built-in functions.
For information on the REM built-in function, see “REM” on page 628.
Example
rem( +10, +8 ) = 2
mod( +10, +8 ) = 2
rem( +10, -8 ) = 2
mod( +10, -8 ) = 2
rem( -10, +8 ) = -2
mod( -10, +8 ) = 6
rem( -10, -8 ) = -2
mod( -10, -8 ) = 6
Chapter 18. Built-in functions, pseudovariables, and subroutines
545
MPSTR
MPSTR
MPSTR truncates a string at a logical boundary and returns a mixed character
string. It does not truncate a double-byte character between bytes. The length of
the returned string is equal to the length of the expression x, or to the value
specified by y. The processing of the string is determined by the rules selected by
the expression r, as described below.
MPSTR(x,r
)
,y
x
Expression that yields the character string result. The value of x is converted to
character if necessary.
r
Expression that yields a character result. The expression cannot be GRAPHIC
and is converted to character if necessary.
The expression r specifies the rules to be used for processing the string. The
characters that can be used in r and the rules for them are as follows:
V or v
Validates the mixed string x and returns a mixed string.
S or s
Removes any null DBCS strings, creates a new string, and returns a mixed
string.
If both V and S are specified, V takes precedence over S, regardless of the
order in which they were specified.
If S is specified without V, the string x is assumed to be a valid string. If the
string is not valid, undefined results occur.
Note: The parameter r is ignored on Intel and AIX.
y
546
Expression. If necessary, y is converted to a real fixed-point binary value. If y is
omitted, the length is determined by the rules for type conversion. The value
of y cannot be negative. If y = 0, the result is the null character string. If y is
greater than the length needed to contain x, the result is padded with blanks. If
y is less than the length needed to contain x, the result is truncated by
discarding excess characters from the right (if they are SBCS characters), or by
discarding as many DBCS characters (2-byte pairs) as needed.
Enterprise PL/I for z/OS Language Reference
MULTIPLY
MULTIPLY
MULTIPLY returns the product of x and y, with a precision specified by p and q.
The base, scale, and mode of the result are determined by the rules for expression
evaluation unless overruled by the PRECTYPE compiler option.
MULTIPLY(x,y,p
)
,q
x and y
Expressions.
p
Restricted expression that specifies the number of digits to be maintained
throughout the operation.
q
Restricted expression that specifies the scaling factor of the result. For a
fixed-point result, if q is omitted, a scaling factor of zero is assumed. For a
floating-point result, q must be omitted.
Note that when applied to FIXED DECIMAL, then if the mathematical result is too
big for the specified precision p but less than the maximum implementation value,
v if SIZE is disabled, the FIXEDOVERFLOW condition will not be raised and the
result will be truncated
v if SIZE is enabled, the SIZE condition will be raised
Note that the above text is false when the non-default compiler option
DECIMAL(FOFLONMULT) is in effect. In that case, FIXEDOVERFLOW will be
raised if SIZE is disabled (and the result is too big).
Chapter 18. Built-in functions, pseudovariables, and subroutines
547
NULL
NULL
NULL returns the null pointer value. The null pointer value does not identify any
generation of a variable. The null pointer value can be assigned to and compared
with handles. The null pointer value can be converted to OFFSET by assignment of
the built-in function value to an offset variable.
NULL
()
548
Enterprise PL/I for z/OS Language Reference
OFFSET
OFFSET
OFFSET returns an offset value derived from a pointer reference x and relative to
an area y. If x is the null pointer value, the null offset value is returned.
OFFSET ( x , y
)
x
Pointer reference. It must identify a generation of a based variable within the
area y, or be the null pointer value.
y
Area reference.
If x is an element reference, y must be an element variable.
Chapter 18. Built-in functions, pseudovariables, and subroutines
549
OFFSETADD
OFFSETADD
OFFSETADD returns the sum of the arguments.
OFFSETADD(x,y)
550
x
Expression. x must be specified as OFFSET.
y
Expression. y must have a computational type and is converted to FIXED
BINARY(31,0).
Enterprise PL/I for z/OS Language Reference
OFFSETDIFF
OFFSETDIFF
OFFSETDIFF returns a FIXED BINARY(31,0) value that is the arithmetic difference
between the arguments.
OFFSETDIFF(x,y)
x and y
Expressions. Both must be specified as OFFSET.
Chapter 18. Built-in functions, pseudovariables, and subroutines
551
OFFSETSUBTRACT
OFFSETSUBTRACT
OFFSETSUBTRACT is equivalent to OFFSETADD(x,-y).
OFFSETSUBTRACT(x,y)
552
x
Expressions. x must be specified as OFFSET.
y
Expression. y must have a computational type and is converted to FIXED
BINARY(31,0).
Enterprise PL/I for z/OS Language Reference
OFFSETVALUE
OFFSETVALUE
OFFSETVALUE returns an offset value that is the converted value of x.
OFFSETVALUE(x)
x
Expression. x must have a computational type and is converted to FIXED
BINARY(31,0).
Chapter 18. Built-in functions, pseudovariables, and subroutines
553
OMITTED
OMITTED
OMITTED returns a BIT(1) value that is '1'B if the parameter named x was omitted
in the invocation to its containing procedure.
OMITTED(x)
x
Level-1 unsubscripted parameter with the BYADDR attribute.
Note: This argument must be declared as OPTIONAL in the corresponding
ENTRY declaration in the calling code.
554
Enterprise PL/I for z/OS Language Reference
ONAREA
ONAREA
ONAREA returns a character string whose value is the name of the AREA
reference for which an AREA condition is raised. If the reference includes DBCS
names, the string returned is a mixed character string. It is in context in an
ON-unit (or any of its dynamic descendants) for the AREA condition, or for the
ERROR or FINISH condition raised as the implicit action for an AREA condition.
ONAREA
()
If the ONAREA built-in function is used out of context, a null string is returned.
If the AREA reference is excessively long or complicated, a null string is returned.
Chapter 18. Built-in functions, pseudovariables, and subroutines
555
ONCHAR
ONCHAR
ONCHAR returns a character(1) string containing the character that caused the
CONVERSION condition to be raised. It is in context in an ON-unit (or any of its
dynamic descendants) for the CONVERSION condition or for the ERROR or
FINISH condition raised as the implicit action for the CONVERSION condition.
ONCHAR
()
If the ONCHAR built-in function is used out of context, a blank is returned.
556
Enterprise PL/I for z/OS Language Reference
ONCHAR pseudovariable
ONCHAR pseudovariable
The ONCHAR pseudovariable sets the current value of the ONCHAR built-in
function. The element value assigned to the pseudovariable is converted to a
character value of length 1. The new character is used when the conversion is
attempted again. (See conversions in Chapter 4, “Data conversion,” on page 73.)
ONCHAR
()
The pseudovariable must not be used out of context.
Chapter 18. Built-in functions, pseudovariables, and subroutines
557
ONCODE
ONCODE
The ONCODE built-in function provides a fixed-point binary value that depends
on the cause of the last condition. ONCODE can be used to distinguish between
the various circumstances that raise a particular condition—for instance, the
ERROR condition. For codes corresponding to the conditions and errors detected,
refer to the specific condition.
ONCODE returns a real fixed-point binary value that is the condition code. It is in
context in any ON-unit or its dynamic descendant. All condition codes are defined
in Messages and Codes.
ONCODE
()
If ONCODE is used out of context, zero is returned.
558
Enterprise PL/I for z/OS Language Reference
ONCONDCOND
ONCONDCOND
ONCONDCOND returns a nonvarying character string whose value is the name of
the condition for which a CONDITION condition is raised. If the name is a DBCS
name, it will be returned as a mixed character string. It is in context in the
following circumstances:
v In a CONDITION ON-unit, or any of its dynamic descendants
v In an ANYCONDITION ON-unit that traps a CONDITION condition, or any
dynamic descendants of such an ON-unit.
ONCONDCOND
()
If ONCONDCOND is used out of context, a null string is returned.
Chapter 18. Built-in functions, pseudovariables, and subroutines
559
ONCONDID
ONCONDID
ONCONDID (short for ON-condition identifier) returns a FIXED BINARY(31,0)
value that identifies the condition being handled by an ON-unit. It is in context in
any ON-unit or one of its dynamic descendants.
ONCONDID
()
The values returned by ONCONDID are given in the following DECLARE
statement:
declare (
condid_area
condid_attention
condid_condition
condid_conversion
condid_endfile
condid_endpage
condid_error
condid_finish
condid_fixedoverflow
condid_invalidop
condid_key
condid_name
condid_overflow
condid_record
condid_size
condid_storage
condid_stringrange
condid_stringsize
condid_subscriptrange
condid_transmit
condid_undefinedfile
condid_underflow
condid_zerodivide
) fixed bin(31);
value(1),
value(2),
value(3),
value(4),
value(5),
value(6),
value(7),
value(8),
value(9),
value(10),
value(11),
value(12),
value(13),
value(14),
value(15),
value(16),
value(17),
value(18),
value(19),
value(20),
value(21),
value(22),
value(23)
If ONCONDID is used out of context, a value of zero is returned.
560
Enterprise PL/I for z/OS Language Reference
ONCOUNT
ONCOUNT
ONCOUNT returns an unscaled REAL FIXED BINARY value specifying the
number of conditions that remain to be handled when an ON-unit is entered. (See
“Multiple conditions” on page 356.) It is in context in any ON-unit, or any
dynamic descendant of an ON-unit.
ONCOUNT
()
If ONCOUNT is used out of context, zero is returned.
The BIFPREC compiler option determines the precision of the result returned.
Chapter 18. Built-in functions, pseudovariables, and subroutines
561
ONFILE
ONFILE
ONFILE returns a character string whose value is the name of the file for which an
input or output condition is raised. If the name is a DBCS name, it is returned as a
mixed character string. It is in context in an ON-unit (or any of its dynamic
descendants) for an input or output condition, or for the ERROR or FINISH
condition raised as the implicit action for an input or output condition.
ONFILE
()
If ONFILE is used out of context, a null string is returned.
562
Enterprise PL/I for z/OS Language Reference
ONGSOURCE
ONGSOURCE
ONGSOURCE returns a graphic string containing the DBCS character that caused
the CONVERSION condition to be raised. It is in context in an ON-unit (or any of
its dynamic descendants) for the CONVERSION condition or for the ERROR or
FINISH condition raised as the implicit action for a CONVERSION condition.
ONGSOURCE
()
If the ONGSOURCE built-in function is used out of context, a null GRAPHIC
string is returned.
Chapter 18. Built-in functions, pseudovariables, and subroutines
563
ONGSOURCE pseudovariable
ONGSOURCE pseudovariable
The ONGSOURCE pseudovariable sets the current value of the ONGSOURCE
built-in function. The element value assigned to the pseudovariable is converted
graphic. The string is used when the conversion is attempted again.
ONGSOURCE
()
The pseudovariable must not be used out of context.
564
Enterprise PL/I for z/OS Language Reference
ONKEY
ONKEY
ONKEY returns a character string whose value is the key of the record that raised
an input/output condition. For indexed files, if the key is GRAPHIC, the string is
returned as a mixed character string. ONKEY is in context for the following:
v An ON-unit, or any of its dynamic descendants
v Any input/output condition, except ENDFILE
v The ERROR or FINISH condition raised as implicit action for an input/output
condition.
ONKEY is always set for operations on a KEYED file, even if the statement that
raised the condition does not specified the KEY, KEYTO, or KEYFROM options.
ONKEY
()
The result of specifying ONKEY is:
v For any input/output condition (other than ENDFILE), or for the ERROR or
FINISH condition raised as implicit action for these conditions, the result is the
value of the recorded key from the I/O statement causing the error.
v For relative data sets, the result is a character string representation of the relative
record number. If the key was incorrectly specified, the result is the last 8
characters of the source key. If the source key is less than 8 characters, it is
padded on the right with blanks to make it 8 characters. If the key was correctly
specified, the character string consists of the relative record number in character
form padded on the left with blanks, if necessary.
v For a REWRITE statement that attempts to write an updated record on to an
indexed data set when the key of the updated record differs from that of the
input record, the result is the value of the embedded key of the input record.
If ONKEY is used out of context, a null string is returned.
Chapter 18. Built-in functions, pseudovariables, and subroutines
565
ONLINE
ONLINE
ONLINE returns a FIXED BIN(31) value which is the line number in the source in
which a condition was raised.
ONLINE
()
The source program must have been compiled with the GONUMBER option, and
on Windows it must also have been linked with the /debug option.
If ONLINE is used out of context, a value of zero is returned.
566
Enterprise PL/I for z/OS Language Reference
ONLOC
ONLOC
ONLOC returns a character string whose value is the name of the entry-point used
for the current invocation of the procedure in which a condition was raised.
ONLOC always returns the leftmost name of a multiple label specification,
regardless of which name appears in the CALL or GOTO statement.
If the name is a DBCS name, it is returned as a mixed-character string. It is in
context in any ON-unit, or in any of its dynamic descendants.
ONLOC
()
If ONLOC is used out of context, a null string is returned.
Chapter 18. Built-in functions, pseudovariables, and subroutines
567
ONOFFSET
ONOFFSET
ONOFFSET returns a FIXED BIN(31) value which is the offset from the start of the
user procedure (or BEGIN block) in which a condition was raised.
ONOFFSET
()
If ONOFFSET is used out of context, a value of zero is returned.
568
Enterprise PL/I for z/OS Language Reference
ONSOURCE
ONSOURCE
ONSOURCE returns a character string whose value is the contents of the field that
was being processed when the CONVERSION condition was raised. It is in context
in an ON-unit (or any of its dynamic descendants) for the CONVERSION
condition or for the ERROR or FINISH condition raised as the implicit action for a
CONVERSION condition.
ONSOURCE
()
If ONSOURCE is used out of context, a null string is returned.
If the source in a failed conversion is a COMPLEX value, then ONSOURCE() will
show only the REAL or IMAG half of that value.
Chapter 18. Built-in functions, pseudovariables, and subroutines
569
ONSOURCE pseudovariable
ONSOURCE pseudovariable
The ONSOURCE pseudovariable sets the current value of the ONSOURCE built-in
function. The element value assigned to the pseudovariable is converted to a
character string and, if necessary, is padded on the right with blanks or truncated
to match the length of the field that raised the CONVERSION condition. The string
is used when the conversion is attempted again.
ONSOURCE
()
When conversion is retried, the string assigned to the pseudovariable is processed
as a single data item. For this reason, the error correction process must not assign a
string containing more than one data item when the conversion occurs during the
execution of a GET LIST or GET DATA statement. The presence of blanks or
commas in the string could raise CONVERSION again.
The pseudovariable must not be used out of context.
If ONSOURCE is not a binary constant, then the ONSOURCE pseudovariable must
not set it to one. For example, if ONSOURCE() is ’ERR’, you must must not set
ONSOURCE() to ’0’B.
570
Enterprise PL/I for z/OS Language Reference
ONSUBCODE
ONSUBCODE
ONSUBCODE returns a FIXED BINARY(31,0) value that gives more information
about an I/O error that occurred. This corresponds to the SUBCODE1 values
documented for messages IBM0236I and IBM0265I. These values are defined in
Messages and Codes.
ONSUBCODE()
Chapter 18. Built-in functions, pseudovariables, and subroutines
571
ONWCHAR
ONWCHAR
ONWCHAR returns a widechar(1) string containing the widechar that caused the
CONVERSION condition to be raised. It is in context in an ON-unit (or any of its
dynamic descendants) for the CONVERSION condition or for the ERROR or
FINISH condition raised as the implicit action for the CONVERSION condition.
ONWCHAR
()
If the ONWCHAR built-in function is used out of context, a widechar blank is
returned.
572
Enterprise PL/I for z/OS Language Reference
ONWCHAR pseudovariable
ONWCHAR pseudovariable
The ONWCHAR pseudovariable sets the current value of the ONWCHAR built-in
function. The element value assigned to the pseudovariable is converted to a
widechar value of length 1. The new widechar is used when the conversion is
attempted again. (See conversions in Chapter 4, “Data conversion,” on page 73.)
ONWCHAR
()
The pseudovariable must not be used out of context.
Chapter 18. Built-in functions, pseudovariables, and subroutines
573
ONWSOURCE
ONWSOURCE
ONWSOURCE returns a widechar string whose value is the contents of the field
that was being processed when the CONVERSION condition was raised. It is in
context in an ON-unit (or any of its dynamic descendants) for the CONVERSION
condition or for the ERROR or FINISH condition raised as the implicit action for a
CONVERSION condition.
ONWSOURCE
()
If ONWSOURCE is used out of context, a null string is returned.
574
Enterprise PL/I for z/OS Language Reference
ONWSOURCE pseudovariable
ONWSOURCE pseudovariable
The ONWSOURCE pseudovariable sets the current value of the ONWSOURCE
built-in function. The element value assigned to the pseudovariable is converted to
a widechar string and, if necessary, is padded on the right with widechar blanks or
truncated to match the length of the field that raised the CONVERSION condition.
The string is used when the conversion is attempted again.
ONWSOURCE
()
When conversion is retried, the string assigned to the pseudovariable is processed
as a single data item. For this reason, the error correction process must not assign a
string containing more than one data item when the conversion occurs during the
execution of a GET LIST or GET DATA statement. The presence of blanks or
commas in the string could raise CONVERSION again.
The pseudovariable must not be used out of context.
Chapter 18. Built-in functions, pseudovariables, and subroutines
575
ORDINALNAME
ORDINALNAME
ORDINALNAME returns a nonvarying character string that is the member of the
set associated with the ordinal x.
ORDINALNAME(x)
x
Reference. It must have ordinal type.
ORDINALs cannot be used in computational expressions and cannot be converted
to character, but ORDINALNAME provides a way to obtain a displayable value for
an ORDINAL and can be very useful in debugging.
576
Enterprise PL/I for z/OS Language Reference
ORDINALPRED
ORDINALPRED
ORDINALPRED returns an ordinal that is the next lower value that the ordinal x
could assume.
ORDINALPRED(x)
x
Reference. It must have ordinal type.
The returned ordinal has the same type as ordinal x.
Chapter 18. Built-in functions, pseudovariables, and subroutines
577
ORDINALSUCC
ORDINALSUCC
ORDINALSUCC returns an ordinal that is the next higher value the ordinal x
could assume.
ORDINALSUCC(x)
x
Reference. It must have ordinal type.
The returned ordinal has the same type as ordinal x.
578
Enterprise PL/I for z/OS Language Reference
PACKAGENAME
PACKAGENAME
PACKAGENAME returns a nonvarying character string containing the name of the
package in which it is invoked. If there is no package in the current compilation
unit, PACKAGENAME returns the name of the outermost procedure.
PACKAGENAME
()
Chapter 18. Built-in functions, pseudovariables, and subroutines
579
PAGENO
PAGENO
PAGENO returns an unscaled REAL FIXED BINARY31 value that is the current
page number associated with file x.
PAGENO(x)
x
File reference. The file must be open and have the PRINT attribute.
If the file is not a PRINT file, the ERROR condition is raised.
The BIFPREC compiler option determines the precision of the result returned.
580
Enterprise PL/I for z/OS Language Reference
PICSPEC
PICSPEC
The PICSPEC built-in function casts data from CHARACTER to PICTURE type.
PICSPEC (
x ,
y
x
Expression.
y
Picture specification.
)
The expression x must be CHARACTER NONVARYING with a length known at
compile time.
y must be a character literal that specifies a valid PICTURE with an external
representation that has the same length as the first argument.
The result has the PICTURE type specified by the second argument.
Unlike the EDIT built-in function, no conversion is done and no checks are made
to see if the first argument holds data valid for the picture.
Like the UNSPEC built-in function, only the "type" of the data is changed.
So, for example given PICSPEC(x,'(5)9'), x must be CHAR(5) (since while the
picture specification '(5)9' was 4 characters in length, its external representation
requires 5 characters), but x will not be checked to see if it actually contains 5
numeric digits.
A statement of the N = N + PICSPEC(X,'(5)9') will not cause x to be converted
from CHAR to PIC'(5)9', a conversion that would require a library call, but will
cause the contents of x to be treated as if it were declared as PIC'(5)9'.
Chapter 18. Built-in functions, pseudovariables, and subroutines
581
PLACES
PLACES
PLACES returns a FIXED BINARY(31,0) value that is the model-precision used to
represent the floating-point expression x.
PLACES(x)
x
Expression. x must be declared REAL FLOAT.
PLACES(x) is a constant and can be used in restricted expressions.
Example (Intel Values)
places(x) = 24
places(x) = 53
places(x) = 64
for x float bin(p), p <= 21
for x float bin(p), 21 < p <= 53
for x float bin(p), 53 < p
places(x) = 24
places(x) = 53
places(x) = 64
for x float dec(p), p <= 6
for x float dec(p), 6 < p <= 16
for x float dec(p), 16 < p
Example (AIX Values)
places(x) = 024
places(x) = 053
places(x) = 106
for x float bin(p), p <= 21
for x float bin(p), 21 < p <= 53
for x float bin(p), 53 < p
places(x) = 024
places(x) = 053
places(x) = 106
for x float dec(p), p <= 6
for x float dec(p), 6 < p <= 16
for x float dec(p), 16 < p
Example (z/OS Hexadecimal Values)
places(x) = 6
places(x) = 14
places(x) = 28
for x float bin(p), p <= 21
for x float bin(p), 21 < p <= 53
for x float bin(p), 53 < p
places(x) = 6
places(x) = 14
places(x) = 28
for x float dec(p), p <= 6
for x float dec(p), 6 < p <= 16
for x float dec(p), 16 < p
Example (z/OS IEEE Binary Floating Point Values)
places(x) = 24
places(x) = 53
places(x) = 113
for x float bin(p), p <= 21
for x float bin(p), 21 < p <= 53
for x float bin(p), 53 < p
places(x) = 24
places(x) = 53
places(x) = 113
for x float dec(p), p <= 6
for x float dec(p), 6 < p <= 16
for x float dec(p), 16 < p
Example (z/OS IEEE Decimal Floating Point Values)
places(x) = 7
places(x) = 16
places(x) = 34
582
Enterprise PL/I for z/OS Language Reference
for x float dec(p), p <= 7
for x float dec(p), 7 < p <= 16
for x float dec(p), 16 < p
PLIASCII
PLIASCII
PLIASCII converts z storage units (bytes) at location y from EBCDIC to ASCII at
location x. The storage at location x and y must not overlap unless they specify the
same location.
PLIASCII(x,y,z)
x and y
Expressions with type POINTER or OFFSET. If the type is OFFSET, the
expression must be an OFFSET variable declared with the AREA attribute.
z
Expression with computational type that is converted to FIXED BIN(31,0).
Chapter 18. Built-in functions, pseudovariables, and subroutines
583
PLICANC
PLICANC
This built-in subroutine allows you to cancel the automatic restart facility.
PLICANC
()
For more information about using PLICANC, see the Programming Guide.
584
Enterprise PL/I for z/OS Language Reference
PLICKPT
PLICKPT
This built-in subroutine allows you to take a checkpoint for later restart.
PLICKPT(argument
)
,argument
For more information about using PLICKPT, see the Programming Guide.
Chapter 18. Built-in functions, pseudovariables, and subroutines
585
PLIDELETE
PLIDELETE
This built-in subroutine frees the storage associated with the handle x.
PLIDELETE(x)
x
Handle expression.
PLIDELETE(x) is the best way to free the storage associated with a handle; this
storage is usually acquired by the NEW type function.
CALL PLIDELETE(x) is equivalent to CALL PLIFREE(PTRVALUE(x)).
586
Enterprise PL/I for z/OS Language Reference
PLIDUMP
PLIDUMP
This built-in subroutine allows you to obtain a formatted dump of selected parts of
storage used by your program.
PLIDUMP(argument
)
,argument
For more information about using PLIDUMP, see the Programming Guide.
Chapter 18. Built-in functions, pseudovariables, and subroutines
587
PLIEBCDIC
PLIEBCDIC
PLIEBCDIC converts z storage units (bytes) at location y from ASCII to EBCDIC at
location x. The storage at location x and y must not overlap unless they specify the
same location.
PLIEBCDIC(x,y,z)
x and y
Expressions with type POINTER or OFFSET. If the type is OFFSET, the
expression must be an OFFSET variable declared with the AREA attribute.
z
588
Expression with computational type that is converted to FIXED BIN(31,0).
Enterprise PL/I for z/OS Language Reference
PLIFILL
PLIFILL
This built-in subroutine moves z copies of the byte y to the location x without any
conversions, padding, or truncation.
PLIFILL(x,y,z)
x
Expression. x must be declared POINTER or OFFSET. If it is OFFSET, x must
be declared with the AREA attribute.
y
Must be declared CHARACTER(1) NONVARYING.
z
Expression that is converted to FIXED BINARY(31,0).
Example
dcl 1 Str1,
2 B fixed bin(31),
2 C pointer,
2 * union,
3 D char(4),
3 E fixed bin(31),
3 *,
4 * char(3),
4 F fixed bin(8) unsigned,
2 * char(0)
initial call plifill( addr(Str1), ’00’x, stg(Str1) );
Chapter 18. Built-in functions, pseudovariables, and subroutines
589
PLIFREE
PLIFREE
This built-in subroutine frees the heap storage associated with the pointer p that
was allocated using the ALLOCATE built-in function.
PLIFREE(p)
p
Locator expression.
PLIFREE is the opposite of ALLOCATE (ALLOC).
590
Enterprise PL/I for z/OS Language Reference
PLIMOVE
PLIMOVE
This built-in subroutine moves z storage units (bytes) from location y to location x,
without any conversions, padding, or truncation. Unlike the PLIOVER built-in
subroutine, storage at locations x and y is assumed to be unique. If storage
overlaps, unpredictable results can occur.
PLIMOVE(x,y,z)
x and y
Expressions declared as POINTER or OFFSET. If the type is OFFSET, x or y
must be declared with the AREA attribute.
Expression. z must have a computational type and is converted to FIXED
BINARY(31,0).
z
Example
dcl 1 Str1,
2 B fixed bin(31),
2 C pointer,
2 * union,
3 D char(4),
3 E fixed bin(31),
3 *,
4 * char(3),
4 F fixed bin(8) unsigned,
2 * char(0);
dcl 1 Template nonasgn static,
2 * fixed bin(31) init(200),
2 * pointer init(null()),
2 * char(4) init(’’),
2 * char(0);
call plimove(addr(Str1), addr(Template), stg(Str1));
Chapter 18. Built-in functions, pseudovariables, and subroutines
591
PLIOVER
PLIOVER
This built-in subroutine moves z storage units (bytes) from location y to location x,
without any conversions, padding, or truncation. Unlike the PLIMOVE built-in
subroutine, the storage at locations x and y can overlap.
PLIOVER(x,y,z)
x and y
Expressions declared as POINTER or OFFSET. If the type is OFFSET, x or y
must be declared with the AREA attribute.
z
Expression. z must have a computational type and is converted to FIXED
BINARY(31,0).
Usage of PLIOVER is the same as PLIMOVE, with the exception that storage
for x and y can overlap (see “PLIMOVE” on page 591).
592
Enterprise PL/I for z/OS Language Reference
PLIREST
PLIREST
This built-in subroutine allows you to restart program execution.
PLIREST
()
For more information about using PLIREST, see the Programming Guide.
Chapter 18. Built-in functions, pseudovariables, and subroutines
593
PLIRETC
PLIRETC
This built-in subroutine allows you to set a return code that can be examined by
the program that invoked this PL/I program or by another PL/I procedure via the
PLIRETV built-in function.
PLIRETC(x)
x
594
An expression yielding a FIXED BINARY(31,0) return code.
Enterprise PL/I for z/OS Language Reference
PLIRETV
PLIRETV
PLIRETV returns a FIXED BINARY(31,0) value that is the PL/I return code.
PLIRETV
()
The value of the PL/I return code is the most recent value specified by a CALL
PLIRETC statement.
Chapter 18. Built-in functions, pseudovariables, and subroutines
595
PLISAXA
PLISAXA
This built-in subroutine allows you to perform SAX-style parsing of an XML
document residing in a buffer in your program.
PLISAXA(e,p,x,n
)
,c
e
An event structure
p
A pointer value or "token" that will be passed back to the parsing events
x
The address of the buffer containing the input XML
n
The number of bytes of data in that buffer
c
A numeric expression specifying the purported codepage of that XML
Note that if the XML is contained in a CHARACTER VARYING or a WIDECHAR
VARYING string, then the ADDRDATA built-in function should be used to obtain
the address of the first data byte.
Also note that if the XML is contained in a WIDECHAR string, the value for the
number of bytes is twice the value returned by the LENGTH built-in function.
For more information, see the Programming Guide.
596
Enterprise PL/I for z/OS Language Reference
PLISAXB
PLISAXB
This built-in subroutine allows you to perform SAX-style parsing of an XML
document residing in a file.
PLISAXB(e,p,x
)
,c
e
An event structure
p
A pointer value or "token" that will be passed back to the parsing events
x
A character string expression specifying the input file
c
A numeric expression specifying the purported codepage of that XML
For more information, see the Programming Guide.
Chapter 18. Built-in functions, pseudovariables, and subroutines
597
PLISAXC
PLISAXC
This built-in subroutine allows you to perform SAX-style parsing of an XML
document residing in one or more buffers in your program.
PLISAXC(e,p,x,n
)
,c
e
An event structure
p
A pointer value or "token" that will be passed back to the parsing events
x
The address of the buffer containing the XML document
n
The number of bytes of data in that buffer
c
A numeric expression specifying the codepage of that XML document
PLISAXC uses the z/OS XML System Services parser and is supported only on
z/OS.
For more information, see the Enterprise PL/I for z/OS Programming Guide.
598
Enterprise PL/I for z/OS Language Reference
PLISAXD
PLISAXD
The PLISAXD built-in subroutine provides SAX-style parsing with XML validation
of an XML document.
PLISAXD(e,p,x,n,o
)
,c
e
An event structure
p
A pointer value or "token" that will be passed back to the parsing events
x
The address of s buffer that contains the XML document
n
The number of bytes of data in that buffer
o
The address of a buffer that contains an Optimized Schema Representation
(OSR)
c
A numeric expression specifying the codepage of that XML document
PLISAXD uses the z/OS XML System Services parser and is supported only on
z/OS.
For more information, see the chapter Using the PLISAXD XML parser in the
Enterprise PL/I for z/OS Programming Guide.
Note: An OSR is a pre-processed version of a schema. For more information about
OSR, see the XML System Services User’s Guide and Reference.
Chapter 18. Built-in functions, pseudovariables, and subroutines
599
PLISRTA
PLISRTA
This built-in subroutine allows you to sort an input file to produce a sorted output
file.
,
PLISRTA( argument
)
For more information, see the Programming Guide.
600
Enterprise PL/I for z/OS Language Reference
PLISRTB
PLISRTB
This built-in subroutine allows you to sort input records provided by an E15 PL/I
exit procedure to produce a sorted output file.
,
PLISRTB( argument
)
For more information, see the Programming Guide.
Chapter 18. Built-in functions, pseudovariables, and subroutines
601
PLISRTC
PLISRTC
This built-in subroutine allows you to sort an input file to produce sorted records
that are processed by an E35 PL/I exit procedure.
,
PLISRTC( argument
)
For more information, see the Enterprise PL/I for z/OS Programming Guide.
602
Enterprise PL/I for z/OS Language Reference
PLISRTD
PLISRTD
This built-in subroutine allows you to sort input records provided by an E15 PL/I
exit procedure to produce sorted records that are processed by an E35 PL/I exit
procedure.
,
PLISRTD( argument
)
For more information, see the Programming Guide.
Chapter 18. Built-in functions, pseudovariables, and subroutines
603
PLITRAN11
PLITRAN11
PLITRAN11 translates one-byte data from a source buffer to one-byte data in a
target buffer.
PLITRAN11 (
p ,
q
,
n ,
t )
p
Address of the target buffer.
q
Address of the source buffer.
n
Length of the source buffer.
t
Address of the 256-byte translate table.
The buffer length must have computational type and will be converted to FIXED
BINARY(31,0).
The buffer length must be nonnegative.
The target buffer must be at least as large as the source buffer.
The translate table must be aligned on a doubleword boundary.
604
Enterprise PL/I for z/OS Language Reference
PLITRAN12
PLITRAN12
PLITRAN12 translates one-byte data from a source buffer to two-byte data in a
target buffer.
PLITRAN12 (
p
,
q ,
n
,
t
)
p
Address of the target buffer.
q
Address of the source buffer.
n
Length of the source buffer.
t
Address of the 512-byte translate table.
The buffer length must have computational type and will be converted to FIXED
BINARY(31,0).
The buffer length must be nonnegative.
The target buffer must be at least twice as large as the source buffer.
The translate table must be aligned on a doubleword boundary.
Chapter 18. Built-in functions, pseudovariables, and subroutines
605
PLITRAN21
PLITRAN21
PLITRAN21 translates two-byte data from a source buffer to one-byte data in a
target buffer.
PLITRAN21 (
p ,
q
,
n ,
t )
p
Address of the target buffer.
q
Address of the source buffer.
n
Length of the source buffer.
t
Address of the 64K-byte translate table.
The buffer length must have computational type and will be converted to FIXED
BINARY(31,0).
The buffer length must be nonnegative.
The target buffer must be at least half as large as the source buffer.
The translate table must be aligned on a doubleword boundary.
606
Enterprise PL/I for z/OS Language Reference
PLITRAN22
PLITRAN22
PLITRAN22 translates two-byte data from a source buffer to two-byte data in a
target buffer.
PLITRAN22 (
p
,
q ,
n
,
t
)
p
Address of the target buffer.
q
Address of the source buffer.
n
Length of the source buffer.
t
Address of the 128K-byte translate table.
The buffer length must have computational type and will be converted to FIXED
BINARY(31,0).
The buffer length must be nonnegative.
The target buffer must be at least as large as the source buffer.
The translate table must be aligned on a doubleword boundary.
Chapter 18. Built-in functions, pseudovariables, and subroutines
607
POINTER
POINTER
POINTER returns a pointer value that identifies the generation specified by an
offset reference x, in an area specified by y. If x is the null offset value, the null
pointer value is returned.
POINTER(x,y)
Abbreviation: PTR
x
Offset reference. It can be the null offset value. If it is not, x must identify a
generation of a based variable, but not necessarily in y. If it is not in y, the
generation must be equivalent to a generation in y.
y
Area reference.
Generations of based variables in different areas are equivalent if, up to the
allocation of the latest generation, the variables have been allocated and freed the
same number of times as each other.
608
Enterprise PL/I for z/OS Language Reference
POINTERADD
POINTERADD
POINTERADD returns a pointer value that is the sum of its arguments.
POINTERADD(x,y)
Abbreviation: PTRADD
x
Pointer expression.
y
Expression that must have a computational type and is converted to FIXED
BINARY(31,0).
POINTERADD can be used as a locator for a based variable.
POINTERADD can be used for subtraction by prefixing the operand to be
subtracted with a minus sign.
There is no need to use POINTERADD to increment a pointer - you can simply
increment the pointer as you would an integer. For example, there is no need to
write:
p = pointeradd(p,2);
Instead, you could write either of the following equivalent statements:
p = p + 2;
p += 2;
However, POINTERADD can be useful in dereferencing the storage at a location
offset from a pointer, as in the following example:
dcl x fixed bin(31), b based fixed bin(31);
x = pointeradd(p,2)->b;
Note, however, since a locator in PL/I must be a reference, you cannot write
x = (p + 2)->b;
Chapter 18. Built-in functions, pseudovariables, and subroutines
609
POINTERDIFF
POINTERDIFF
POINTERDIFF returns a FIXED BINARY(31,0) result that is the difference between
the two pointers x and y.
POINTERDIFF(x,y)
Abbreviation: PTRDIFF
x and y
Expressions declared as POINTER.
610
Enterprise PL/I for z/OS Language Reference
POINTERSUBTRACT
POINTERSUBTRACT
POINTERSUBTRACT is equivalent to POINTERADD(x,-y).
POINTERSUBTRACT(x,y)
Abbreviation: PTRSUBTRACT
x
Must be a pointer expression.
y
Expression that must have a computational type and is converted to FIXED
BINARY(31,0).
Chapter 18. Built-in functions, pseudovariables, and subroutines
611
POINTERVALUE
POINTERVALUE
POINTERVALUE returns a pointer value that is the converted value of x.
POINTERVALUE(x)
Abbreviation: PTRVALUE
x
Expression that must have either the HANDLE attribute, or have a
computational type. If x has a computational type, it is converted to FIXED
BINARY(31,0).
POINTERVALUE(x) can be used to initialize static pointer variables if x is a
constant.
612
Enterprise PL/I for z/OS Language Reference
POLY
POLY
POLY returns a floating-point value that is an approximation of a polynomial
formed from an one-dimensional array expressions x. The returned value has the
same attributes as the first argument. The syntax for POLY is:
POLY
( x
, y
)
x
An array expression.
y
An element expression.
x must be REAL FLOAT and y is converted to the attributes of x, if necessary.
If x has lower bound