PL1

Enterprise PL/I for z/OS and OS/390 IBM
Programming Guide
Version 3 Release 2.0
SC27-1457-02
Enterprise PL/I for z/OS and OS/390 IBM
Programming Guide
SC27-1457-02
Note!
Before using this information and the product it supports, be sure to read the general information under “Notices” on page 361.
Fourth Edition (September 2002)
This edition applies to Version 3 Release 2 of Enterprise PL/I for z/OS and OS/390, 5655-H31, and to any subsequent releases 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 HHX/H1
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.
 International Business Machines Corporation 1998,2002. All rights reserved.

Contents
Part 1. Introduction . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . xiii
About This Book . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . xiv

Using your documentation . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . xiv
Notation conventions used in this book . . . . . . . . . . . . . . . . . . . . . . . . xv
Conventions used . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . xvi
How to read the syntax notation . . . . . . . . . . . . . . . . . . . . . . . . . . xvi
How to read the notational symbols . . . . . . . . . . . . . . . . . . . . . . . . xviii
Enhancements in this release . . . . . . . . . . . . . . . . . . . . . . . . . . . . . xix
Enhancements in recent releases . . . . . . . . . . . . . . . . . . . . . . . . . . . xxi
Part 2. Compiling your program . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1
Chapter 1. Using compiler options and facilities . . . . . . . . . . . . . . . . . 3

Compile-time option descriptions . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3
AGGREGATE . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 5
ARCH . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 5
ATTRIBUTES . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 6
BLANK . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 7
CHECK . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 7
CMPAT . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 7
CODEPAGE . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 8
COMPACT . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 9
COMPILE . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 9
CSECT . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 10
CURRENCY . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 11
DBCS . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 11
DD . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 11
DEFAULT . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 12
DISPLAY . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 19
DLLINIT . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 19
EXIT . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 19
EXTRN . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 19
FLAG . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 20
FLOAT . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 20
GONUMBER . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 20
GRAPHIC . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 21
INCAFTER . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 21
INCDIR . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 21
INCLUDE . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 22
INSOURCE . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 22
INTERRUPT . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 23
LANGLVL . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 24
LIMITS . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 24
LINECOUNT . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 25
LIST . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 25
MACRO . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 25
MAP . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 26
 Copyright IBM Corp. 1991, 2002 iii

MARGINI . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 26
MARGINS . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 26
MAXMEM . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 27
MAXMSG . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 28
MAXSTMT . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 28
MDECK . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 28
NAMES . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 29
NAME . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 29
NATLANG . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 30
NEST . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 30
NOT . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 30
NUMBER . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 31
OBJECT . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 31
OFFSET . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 31
OPTIMIZE . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 31
OPTIONS . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 32
OR . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 33
PP . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 33
PPTRACE . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 34
PREFIX . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 34
PROCEED . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 34
REDUCE . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 35
RENT . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 36
RESPECT . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 37
RULES . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 37
SEMANTIC . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 41
SERVICE . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 42
SOURCE . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 42
SPILL . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 42
STDSYS . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 42
STMT . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 43
STORAGE . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 43
SYNTAX . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 43
SYSPARM . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 44
SYSTEM . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 44
TERMINAL . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 45
TEST . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 46
TUNE . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 47
USAGE . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 48
WIDECHAR . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 48
WINDOW . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 49
WRITABLE . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 49
XINFO . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 50
XREF . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 51
Specifying options in the %PROCESS or *PROCESS statements . . . . . . . . 52
Using % statements . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 53
Using the %INCLUDE statement . . . . . . . . . . . . . . . . . . . . . . . . . . 53
Using the compiler listing . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 55
Heading information . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 55
Options used for compilation . . . . . . . . . . . . . . . . . . . . . . . . . . . . 55
Preprocessor input . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 55
SOURCE program . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 56
Statement nesting level . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 56
ATTRIBUTE and cross-reference table . . . . . . . . . . . . . . . . . . . . . . 56
iv Enterprise PL/I Programming Guide

Aggregate length table . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 57
Statement offset addresses . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 57
Storage offset listing . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 59
File reference table . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 60
Messages and return codes . . . . . . . . . . . . . . . . . . . . . . . . . . . . 60
Chapter 2. PL/I preprocessors . . . . . . . . . . . . . . . . . . . . . . . . . . . 62

Include preprocessor . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 64
Macro preprocessor . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 65
Macro preprocessor options . . . . . . . . . . . . . . . . . . . . . . . . . . . . 65
Macro preprocessor example . . . . . . . . . . . . . . . . . . . . . . . . . . . . 65
SQL preprocessor . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 66
Programming and compilation considerations . . . . . . . . . . . . . . . . . . 67
SQL preprocessor options . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 68
Coding SQL statements in PL/I applications . . . . . . . . . . . . . . . . . . . 72
Additional Information on Large Object (LOB) support . . . . . . . . . . . . . 80
CICS Preprocessor . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 85
CICS preprocessor options . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 85
Coding CICS statements in PL/I applications . . . . . . . . . . . . . . . . . . . 85
Writing CICS transactions in PL/I . . . . . . . . . . . . . . . . . . . . . . . . . 86
Chapter 3. Using PL/I cataloged procedures . . . . . . . . . . . . . . . . . . 87

IBM-supplied cataloged procedures . . . . . . . . . . . . . . . . . . . . . . . . . . 87
Compile only (IBMZC) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 88
Compile and bind (IBMZCB) . . . . . . . . . . . . . . . . . . . . . . . . . . . . 89
Compile, bind, and run (IBMZCBG) . . . . . . . . . . . . . . . . . . . . . . . . 91
Compile, prelink, and link-edit (IBMZCPL) . . . . . . . . . . . . . . . . . . . . 92
Compile, prelink, link-edit, and run (IBMZCPLG) . . . . . . . . . . . . . . . . . 94
Compile, prelink, load and run (IBMZCPG) . . . . . . . . . . . . . . . . . . . . 95
Invoking a cataloged procedure . . . . . . . . . . . . . . . . . . . . . . . . . . . . 97
Specifying multiple invocations . . . . . . . . . . . . . . . . . . . . . . . . . . . 97
Modifying the PL/I cataloged procedures . . . . . . . . . . . . . . . . . . . . . . . 98
EXEC statement . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 99
DD statement . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 99
Chapter 4. Compiling your program . . . . . . . . . . . . . . . . . . . . . . . 101

Invoking the compiler under OS/390 UNIX . . . . . . . . . . . . . . . . . . . . . 101
Input files . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 101
Specifying compile-time options under OS/390 UNIX . . . . . . . . . . . . . . 102
-qoption_keyword . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 102
Single and multiletter flags . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 103
Invoking the compiler under OS/390 using JCL . . . . . . . . . . . . . . . . . . . 104
EXEC statement . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 104
DD statements for the standard data sets . . . . . . . . . . . . . . . . . . . . 104
Listing (SYSPRINT) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 106
Source Statement Library (SYSLIB) . . . . . . . . . . . . . . . . . . . . . . . . 106
Specifying options . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 107
Specifying options in the EXEC statement . . . . . . . . . . . . . . . . . . . . 107
Specifying options in the EXEC statement using options file . . . . . . . . . . 107
Compiling for CICS . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 108
Chapter 5. Link-editing and running . . . . . . . . . . . . . . . . . . . . . . . 109

Link-edit considerations . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 109
Contents v
Using the binder . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 109
Using the prelinker . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 110
Run-time considerations . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 110
Formatting conventions for PRINT files . . . . . . . . . . . . . . . . . . . . . . 110
Changing the format on PRINT files . . . . . . . . . . . . . . . . . . . . . . . . 110
Automatic prompting . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 111
Punctuating long input lines . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 112
Punctuating GET LIST and GET DATA statements . . . . . . . . . . . . . . . 112
ENDFILE . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 113
SYSPRINT considerations . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 113
Using FETCH in your routines . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 114
FETCHing Enterprise PL/I routines . . . . . . . . . . . . . . . . . . . . . . . . 114
FETCHing OS/390 C routines . . . . . . . . . . . . . . . . . . . . . . . . . . . 122
FETCHing assembler routines . . . . . . . . . . . . . . . . . . . . . . . . . . . 122
Invoking MAIN under USS . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 123
vi Enterprise PL/I Programming Guide

Part 3. Using I/O facilities . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 125
Chapter 6. Using data sets and files . . . . . . . . . . . . . . . . . . . . . . . 128

Associating data sets with files under OS/390 . . . . . . . . . . . . . . . . . . . . 128
Associating several files with one data set . . . . . . . . . . . . . . . . . . . . 130
Associating several data sets with one file . . . . . . . . . . . . . . . . . . . . 130
Concatenating several data sets . . . . . . . . . . . . . . . . . . . . . . . . . . 131
Accessing HFS files under OS/390 . . . . . . . . . . . . . . . . . . . . . . . . 131
Associating data sets with files under OS/390 UNIX . . . . . . . . . . . . . . . . 132
Using environment variables . . . . . . . . . . . . . . . . . . . . . . . . . . . . 132
Using the TITLE option of the OPEN statement . . . . . . . . . . . . . . . . . 132
Attempting to use files not associated with data sets . . . . . . . . . . . . . . 133
How PL/I finds data sets . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 133
Specifying characteristics using DD_DDNAME environment variables . . . . 133
Establishing data set characteristics . . . . . . . . . . . . . . . . . . . . . . . . . 139
Blocks and records . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 139
Record formats . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 140
Data set organization . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 142
Labels . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 143
Data Definition (DD) statement . . . . . . . . . . . . . . . . . . . . . . . . . . . 143
Associating PL/I files with data sets . . . . . . . . . . . . . . . . . . . . . . . . 145
Specifying characteristics in the ENVIRONMENT attribute . . . . . . . . . . . 146
Data set types used by PL/I record I/O . . . . . . . . . . . . . . . . . . . . . . 154
Setting environment variables . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 154
PL/I standard files (SYSPRINT and SYSIN) . . . . . . . . . . . . . . . . . . . . . 155
Redirecting standard input, output, and error devices . . . . . . . . . . . . . . . 155
Chapter 7. Using libraries . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 156

Types of libraries . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 156
How to use a library . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 156
Creating a library . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 157
SPACE parameter . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 157
Creating and updating a library member . . . . . . . . . . . . . . . . . . . . . . . 158
Examples . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 158
Extracting information from a library directory . . . . . . . . . . . . . . . . . . . . 160
Chapter 8. Defining and using consecutive data sets . . . . . . . . . . . . . 162

Using stream-oriented data transmission . . . . . . . . . . . . . . . . . . . . . . . 162
Defining files using stream I/O . . . . . . . . . . . . . . . . . . . . . . . . . . . 162
Specifying ENVIRONMENT options . . . . . . . . . . . . . . . . . . . . . . . . 163
Creating a data set with stream I/O . . . . . . . . . . . . . . . . . . . . . . . . 165
Accessing a data set with stream I/O . . . . . . . . . . . . . . . . . . . . . . . 168
Using PRINT files with stream I/O . . . . . . . . . . . . . . . . . . . . . . . . . 169
Using SYSIN and SYSPRINT files . . . . . . . . . . . . . . . . . . . . . . . . . 173
Controlling input from the terminal . . . . . . . . . . . . . . . . . . . . . . . . . . 174
Format of data . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 175
Stream and record files . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 175
Capital and lowercase letters . . . . . . . . . . . . . . . . . . . . . . . . . . . . 176
End-of-file . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 176
COPY option of GET statement . . . . . . . . . . . . . . . . . . . . . . . . . . 176
Controlling output to the terminal . . . . . . . . . . . . . . . . . . . . . . . . . . . 176
Format of PRINT files . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 176
Contents vii
Capital and lowercase characters . . . . . . . . . . . . . . . . . . . . . . . . . 177
Output from the PUT EDIT command . . . . . . . . . . . . . . . . . . . . . . . 177
Using record-oriented data transmission . . . . . . . . . . . . . . . . . . . . . . . 177
Specifying record format . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 178
Defining files using record I/O . . . . . . . . . . . . . . . . . . . . . . . . . . . 178
Creating a data set with record I/O . . . . . . . . . . . . . . . . . . . . . . . . 181
Accessing and updating a data set with record I/O . . . . . . . . . . . . . . . 181
Chapter 9. Defining and using regional data sets . . . . . . . . . . . . . . . 186

Defining files for a regional data set . . . . . . . . . . . . . . . . . . . . . . . . . 188
Using keys with REGIONAL data sets . . . . . . . . . . . . . . . . . . . . . . 189
Using REGIONAL(1) data sets . . . . . . . . . . . . . . . . . . . . . . . . . . . . 190
Creating a REGIONAL(1) data set . . . . . . . . . . . . . . . . . . . . . . . . . 190
Accessing and updating a REGIONAL(1) data set . . . . . . . . . . . . . . . 192
Essential information for creating and accessing regional data sets . . . . . . . 195
Chapter 10. Defining and using VSAM data sets . . . . . . . . . . . . . . . . 197

Using VSAM data sets . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 197
How to run a program with VSAM data sets . . . . . . . . . . . . . . . . . . . 197
Pairing an Alternate Index Path with a File . . . . . . . . . . . . . . . . . . . . 197
VSAM organization . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 198
Keys for VSAM data sets . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 200
Choosing a data set type . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 201
Defining files for VSAM data sets . . . . . . . . . . . . . . . . . . . . . . . . . . . 202
Performance options . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 204
Defining Files for Alternate Index Paths . . . . . . . . . . . . . . . . . . . . . . . 205
Defining VSAM data sets . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 205
Entry-sequenced data sets . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 206
Loading an ESDS . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 206
Using a SEQUENTIAL file to access an ESDS . . . . . . . . . . . . . . . . . 207
Key-sequenced and indexed entry-sequenced data sets . . . . . . . . . . . . . 209
Loading a KSDS or indexed ESDS . . . . . . . . . . . . . . . . . . . . . . . . 210
Using a SEQUENTIAL file to access a KSDS or indexed ESDS . . . . . . . 212
Using a DIRECT file to access a KSDS or indexed ESDS . . . . . . . . . . . 212
Alternate Indexes for KSDSs or Indexed ESDSs . . . . . . . . . . . . . . . . . . 215
Unique Key Alternate Index Path . . . . . . . . . . . . . . . . . . . . . . . . . 215
Nonunique Key Alternate Index Path . . . . . . . . . . . . . . . . . . . . . . . 216
Detecting Nonunique Alternate Index Keys . . . . . . . . . . . . . . . . . . . . 217
Using Alternate Indexes with ESDSs . . . . . . . . . . . . . . . . . . . . . . . 218
Using Alternate Indexes with KSDSs . . . . . . . . . . . . . . . . . . . . . . . 218
Relative-record data sets . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 221
Loading an RRDS . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 223
Using a SEQUENTIAL file to access an RRDS . . . . . . . . . . . . . . . . . 225
Using a DIRECT file to access an RRDS . . . . . . . . . . . . . . . . . . . . . 226
Part 4. Improving your program . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 229
Chapter 11. Improving performance . . . . . . . . . . . . . . . . . . . . . . . 230

Selecting compiler options for optimal performance . . . . . . . . . . . . . . . . 230
viii Enterprise PL/I Programming Guide

OPTIMIZE . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 230
GONUMBER . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 230
ARCH . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 230
REDUCE . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 231
RULES . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 231
PREFIX . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 232
DEFAULT . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 233
Summary of compiler options that improve performance . . . . . . . . . . . . 236
Coding for better performance . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 236
DATA-directed input and output . . . . . . . . . . . . . . . . . . . . . . . . . . 236
Input-only parameters . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 237
GOTO statements . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 237
String assignments . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 237
Loop control variables . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 238
PACKAGEs versus nested PROCEDUREs . . . . . . . . . . . . . . . . . . . . 238
REDUCIBLE Functions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 239
DESCLOCATOR or DESCLIST . . . . . . . . . . . . . . . . . . . . . . . . . . 240
DEFINED versus UNION . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 240
Named constants versus static variables . . . . . . . . . . . . . . . . . . . . . 241
Avoiding calls to library routines . . . . . . . . . . . . . . . . . . . . . . . . . . 242
Part 5. Using interfaces to other products . . . . . . . . . . . . . . . . . . . . . . . . . . . 243
Chapter 12. Using the Sort program . . . . . . . . . . . . . . . . . . . . . . . 245

Preparing to use Sort . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 245
Choosing the type of Sort . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 246
Specifying the sorting field . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 248
Specifying the records to be sorted . . . . . . . . . . . . . . . . . . . . . . . . 250
Determining storage needed for Sort . . . . . . . . . . . . . . . . . . . . . . . 251
Calling the Sort program . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 251
Determining whether the Sort was successful . . . . . . . . . . . . . . . . . . 254
Establishing data sets for Sort . . . . . . . . . . . . . . . . . . . . . . . . . . . 254
Sort data input and output . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 256
Data input and output handling routines . . . . . . . . . . . . . . . . . . . . . . . 256
E15—Input handling routine (Sort Exit E15) . . . . . . . . . . . . . . . . . . . 256
E35—Output handling routine (Sort Exit E35) . . . . . . . . . . . . . . . . . . 259
Calling PLISRTA example . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 260
Calling PLISRTB example . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 260
Calling PLISRTC example . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 262
Calling PLISRTD example . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 263
Sorting variable-length records example . . . . . . . . . . . . . . . . . . . . . 264
Chapter 13. ILC with C . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 266

Equivalent data types . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 266
Simple type equivalence . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 266
Struct type equivalence . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 267
Enum type equivalence . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 267
File type equivalence . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 268
Using C functions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 268
Matching simple parameter types . . . . . . . . . . . . . . . . . . . . . . . . . 269
Matching string parameter types . . . . . . . . . . . . . . . . . . . . . . . . . . 271
Functions returning ENTRYs . . . . . . . . . . . . . . . . . . . . . . . . . . . . 272
Linkages . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 273
Contents ix
Summary . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 275
Chapter 14. Interfacing with Java . . . . . . . . . . . . . . . . . . . . . . . . . 276

What is the Java Native Interface (JNI)? . . . . . . . . . . . . . . . . . . . . . . . 276
JNI Sample Program #1 - "Hello World" . . . . . . . . . . . . . . . . . . . . . . . 277
Writing Java Sample Program #1 . . . . . . . . . . . . . . . . . . . . . . . . . . . 277
Step 1: Writing the Java Program . . . . . . . . . . . . . . . . . . . . . . . . . 277
Step 2: Compiling the Java Program . . . . . . . . . . . . . . . . . . . . . . . 278
Step 3: Writing the PL/I Program . . . . . . . . . . . . . . . . . . . . . . . . . 278
Step 4: Compiling and Linking the PL/I Program . . . . . . . . . . . . . . . . 280
Step 5: Running the Sample Program . . . . . . . . . . . . . . . . . . . . . . . 280
JNI Sample Program #2 - Passing a String . . . . . . . . . . . . . . . . . . . . . 281
JNI Sample Program #3 - Passing an Integer . . . . . . . . . . . . . . . . . . . . 285
Determining equivalent Java and PL/I data types . . . . . . . . . . . . . . . . 290
Full contents of jni_md.inc include file . . . . . . . . . . . . . . . . . . . . . . . . 291
Full contents of jni.inc include file . . . . . . . . . . . . . . . . . . . . . . . . . . . 292
Part 6. Specialized programming tasks . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 315
Chapter 15. Using the SAX parser . . . . . . . . . . . . . . . . . . . . . . . . . 317

Overview . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 317
The PLISAXA built-in subroutine . . . . . . . . . . . . . . . . . . . . . . . . . . . 318
The PLISAXB built-in subroutine . . . . . . . . . . . . . . . . . . . . . . . . . . . 318
The SAX event structure . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 318
start_of_document . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 319
version_information . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 319
encoding_declaration . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 319
standalone_declaration . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 319
document_type_declaration . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 319
end_of_document . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 320
start_of_element . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 320
attribute_name . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 320
attribute_characters . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 320
attribute_predefined_reference . . . . . . . . . . . . . . . . . . . . . . . . . . . 320
attribute_character_reference . . . . . . . . . . . . . . . . . . . . . . . . . . . . 320
end_of_element . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 320
start_of_CDATA_section . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 321
end_of_CDATA_section . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 321
content_characters . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 321
content_predefined_reference . . . . . . . . . . . . . . . . . . . . . . . . . . . 321
content_character_reference . . . . . . . . . . . . . . . . . . . . . . . . . . . . 321
x Enterprise PL/I Programming Guide

processing_instruction . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 321
comment . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 322
unknown_attribute_reference . . . . . . . . . . . . . . . . . . . . . . . . . . . . 322
unknown_content_reference . . . . . . . . . . . . . . . . . . . . . . . . . . . . 322
start_of_prefix_mapping . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 322
end_of_prefix_mapping . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 322
exception . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 322
Parameters to the event functions . . . . . . . . . . . . . . . . . . . . . . . . . 322
Coded character sets for XML documents . . . . . . . . . . . . . . . . . . . . . . 323
Supported EBCDIC code pages . . . . . . . . . . . . . . . . . . . . . . . . . . 324
Supported ASCII code pages . . . . . . . . . . . . . . . . . . . . . . . . . . . . 324
Specifying the code page . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 324
Exceptions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 325
Example . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 326
Exception codes . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 336
Chapter 16. Using PLIDUMP . . . . . . . . . . . . . . . . . . . . . . . . . . . . 342

PLIDUMP usage notes . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 343
Chapter 17. Interrupts and attention processing . . . . . . . . . . . . . . . . 345

Using ATTENTION ON-units . . . . . . . . . . . . . . . . . . . . . . . . . . . . 346
Interaction with a debugging tool . . . . . . . . . . . . . . . . . . . . . . . . . . 346
Chapter 18. Using the Checkpoint/Restart facility . . . . . . . . . . . . . . . 347

Requesting a checkpoint record . . . . . . . . . . . . . . . . . . . . . . . . . . . . 347
Defining the checkpoint data set . . . . . . . . . . . . . . . . . . . . . . . . . . 348
Requesting a restart . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 349
Automatic restart after a system failure . . . . . . . . . . . . . . . . . . . . . . 349
Automatic restart within a program . . . . . . . . . . . . . . . . . . . . . . . . 349
Getting a deferred restart . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 349
Modifying checkpoint/restart activity . . . . . . . . . . . . . . . . . . . . . . . . 350
Chapter 19. Using user exits . . . . . . . . . . . . . . . . . . . . . . . . . . . . 351

Procedures performed by the compiler user exit . . . . . . . . . . . . . . . . . . 351
Activating the compiler user exit . . . . . . . . . . . . . . . . . . . . . . . . . . . . 352
The IBM-supplied compiler exit, IBMUEXIT . . . . . . . . . . . . . . . . . . . 352
Customizing the compiler user exit . . . . . . . . . . . . . . . . . . . . . . . . 352
Modifying SYSUEXIT . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 352
Writing your own compiler exit . . . . . . . . . . . . . . . . . . . . . . . . . . . 353
Structure of global control blocks . . . . . . . . . . . . . . . . . . . . . . . . . 353
Writing the initialization procedure . . . . . . . . . . . . . . . . . . . . . . . . . 355
Writing the message filtering procedure . . . . . . . . . . . . . . . . . . . . . . 355
Writing the termination procedure . . . . . . . . . . . . . . . . . . . . . . . . . 356
Chapter 20. PL/I - Language Environment descriptors . . . . . . . . . . . . 357

Passing an argument . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 357
Argument passing by descriptor list . . . . . . . . . . . . . . . . . . . . . . . . 357
Argument passing by descriptor-locator . . . . . . . . . . . . . . . . . . . . . . 358
Descriptor header . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 358
String descriptors . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 359
Array descriptors . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 360
Notices . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 361
Trademarks . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 362
Contents xi
Bibliography . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 363
Enterprise PL/I publications . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 363
PL/I for MVS & VM . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 363
z/OS Language Environment . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 363
CICS Transaction Server . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 363
DB2 UDB for OS/390 and z/OS . . . . . . . . . . . . . . . . . . . . . . . . . . . . 363
DFSORT . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 363
IMS/ESA . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 363
z/OS MVS . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 363
z/OS UNIX System Services . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 363
z/OS TSO/E . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 363
z/Architecture . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 364
Unicode and character representation . . . . . . . . . . . . . . . . . . . . . . . 364
Glossary . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 365
Index . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 379
xii Enterprise PL/I Programming Guide

Part 1. Introduction
About This Book . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . xiv
Using your documentation . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . xiv
PL/I information . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . xv
Language Environment information . . . . . . . . . . . . . . . . . . . . . . . . xv
Notation conventions used in this book . . . . . . . . . . . . . . . . . . . . . . . . xv
Conventions used . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . xvi
How to read the syntax notation . . . . . . . . . . . . . . . . . . . . . . . . . . xvi
How to read the notational symbols . . . . . . . . . . . . . . . . . . . . . . . . xviii
Example of notation . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . xix
Enhancements in this release . . . . . . . . . . . . . . . . . . . . . . . . . . . . . xix
Improved performance . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . xix
Easier migration . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . xix
Improved usability . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . xx
Enhancements in recent releases . . . . . . . . . . . . . . . . . . . . . . . . . . . xxi
 Copyright IBM Corp. 1991, 2002 xiii

About This Book
This book is for PL/I programmers and system programmers. It helps you
understand how to use Enterprise PL/I for z/OS and OS/390 in order to compile
PL/I programs. It also describes the operating system features that you might need
to optimize program performance or handle errors.
Important: Enterprise PL/I for z/OS and OS/390 will be referred to as Enterprise
PL/I throughout this book.
Enterprise PL/I uses Language Environment as its run-time environment. It

conforms to Language Environment architecture and can share the run-time
environment with other Language Environment-conforming languages.
Language Environment provides a common set of run-time options and callable

services. It also improves interlanguage communication (ILC) between high-level
languages (HLL) and assembler by eliminating language-specific initialization and
termination on each ILC invocation.
Using your documentation

The publications provided with Enterprise PL/I are designed to help you program
with PL/I. The publications provided with Language Environment are designed to
help you manage your run-time environment for applications generated with
Enterprise PL/I. Each publication helps you perform a different task.
The following tables show you how to use the publications you receive with
Enterprise PL/I and Language Environment. You'll want to know information about
both your compiler and run-time environment. For the complete titles and order
numbers of these and other related publications, see “Bibliography” on page 363.
xiv  Copyright IBM Corp. 1991, 2002

PL/I information
Table 1. How to use Enterprise PL/I publications
To... Use...
Evaluate Enterprise PL/I Fact Sheet
Understand warranty information Licensed Programming Specifications
Plan for and install Enterprise PL/I Enterprise PL/I Program Directory
Understand compiler and run-time changes and Compiler and Run-Time Migration Guide
adapt programs to Enterprise PL/I and Language
Environment
Prepare and test your programs and get details on Programming Guide
compiler options
Get details on PL/I syntax and specifications of Language Reference
language elements
Diagnose compiler problems and report them to IBM Diagnosis Guide
Get details on compile-time messages Compile-Time Messages and Codes
Language Environment information

Table 2. How to use OS/390 Language Environment publications
To... Use...
Evaluate Language Environment Concepts Guide
Plan for Language Environment Concepts Guide
Run-Time Migration Guide
Install Language Environment on OS/390 OS/390 Program Directory
Customize Language Environment on OS/390 Customization
Understand Language Environment program models Concepts Guide
and concepts Programming Guide
Find syntax for Language Environment run-time Programming Reference
options and callable services
Develop applications that run with Language Programming Guide and your language
Environment Programming Guide
Debug applications that run with Language Debugging Guide and Run-Time Messages
Environment, get details on run-time messages,
diagnose problems with Language Environment
Develop interlanguage communication (ILC) Writing Interlanguage Applications
applications
Migrate applications to Language Environment Run-Time Migration Guide and the migration
guide for each Language Environment-enabled
language
Notation conventions used in this book

This book uses the conventions, diagramming techniques, and notation described
in “Conventions used” on page xvi and “How to read the notational symbols” on
page xviii to illustrate PL/I and non-PL/I programming syntax.
About This Book xv

Conventions used
Some of the programming syntax in this book uses type fonts to denote different
elements:
Items shown in UPPERCASE letters indicate key elements that must be typed
exactly as shown.
Items shown in lowercase letters indicate user-supplied variables for which you
must substitute appropriate names or values. The variables begin with a letter
and can include hyphens, numbers, or the underscore character (_).
The term digit indicates that a digit (0 through 9) should be substituted.
The term do-group indicates that a do-group should be substituted.
Underlined items indicate default options.
Examples are shown in monocase type.
Unless otherwise indicated, separate repeatable items from each other by one
or more blanks.
Note: Any symbols shown that are not purely notational, as described in “How to
read the notational symbols” on page xviii, are part of the programming syntax
itself.
For an example of programming syntax that follows these conventions, see

“Example of notation” on page xix.
How to read the syntax notation

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
Keywords, their allowable synonyms, and reserved parameters, appear in
uppercase for MVS and OS/2 platforms, and lowercase for UNIX
platforms. These items must be entered exactly as shown.
Variables appear in lowercase italics (for example, column-name). They
represent user-defined parameters or suboptions.
When entering commands, separate parameters and keywords by at least
one blank if there is no intervening punctuation.
Enter punctuation marks (slashes, commas, periods, parentheses,
quotation marks, equal signs) and numbers exactly as given.
Footnotes are shown by a number in parentheses, for example, (1).
xvi Enterprise PL/I Programming Guide

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.
┌──
─────────────────┐
─repeatable_item─┴───────────────────────────────

──REQUIRED_ITEM───
If the repeat arrow contains a comma, you must separate repeated items with
a comma.
┌─,───────────────┐
─repeatable_item─┴───────────────────────────────

──REQUIRED_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.
About This Book xvii

┌─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─┬──KEYWORD──┬─item 5─┬────────────────────────────────────┤
└─item 4─┘ └─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 '*'.

──/MSVERIFY──┬─MSNAME──msname─┬────────────────────────────────────────────

└─SYSID──sysid#──┘
The MSNAME keyword in the example supports a name value and the SYSID
keyword supports a number value.
How to read the notational symbols

Some of the programming syntax in this book is presented using notational
symbols. This is to maintain consistency with descriptions of the same syntax in
other IBM publications, or to allow the syntax to be shown on single lines within a
table or heading.
Braces, { }, indicate a choice of entry. Unless an item is underlined, indicating
a default, or the items are enclosed in brackets, you must choose at least one
of the entries.
Items separated by a single vertical bar, |, are alternative items. You can
select only one of the group of items separated by single vertical bars. (Double
vertical bars, ||, specify a concatenation operation, not alternative items. See
the PL/I Language Reference for more information on double vertical bars.)
Anything enclosed in brackets, [ ], is optional. If the items are vertically
stacked within the brackets, you can specify only one item.
xviii Enterprise PL/I Programming Guide

An ellipsis, ..., indicates that multiple entries of the type immediately preceding
the ellipsis are allowed.
Example of notation
The following example of PL/I syntax illustrates the notational symbols described In
“How to read the notational symbols” on page xviii:
DCL file-reference FILE STREAM
{INPUT | OUTPUT [PRINT]}
ENVIRONMENT(option ...);
Interpret this example as follows:

You must spell and enter the first line as shown, except for file-reference, for
which you must substitute the name of the file you are referencing.
In the second line, you can specify INPUT or OUTPUT, but not both. If you
specify OUTPUT, you can optionally specify PRINT as well. If you do not
specify either alternative, INPUT takes effect by default.
You must enter and spell the last line as shown (including the parentheses and
semicolon), except for option ..., for which you must substitute one or more
options separated from each other by one or more blanks.
Enhancements in this release

This release provides the following functional enhancements described in this and
the other Enterprise PL/I books.
Improved performance
The compiler now handles even more conversions by generating inline code
which means these conversions will be done much faster than previously. Also,
all conversions done by library call are now flagged by the compiler.
The compiler-generated code now uses, in various situations, less stack
storage.
The compiler now generates much better code for references to the
TRANSLATE built-in function.
The compiler-generated code for SUBSCRIPTRANGE checking is now, for
arrays with known bounds, twice as fast as before.
The ARCH and TUNE options now support 4 as a suboption, thereby allowing
exploitation of instructions new to the zSeries machines.
ARCH(2), FLOAT(AFP) and TUNE(3) are now the default.
Easier migration
Compiler defaults have been changed for easier migration and compatibility.
The changed defaults are:
– CSECT
– CMPAT(V2)
– LIMITS(EXTNAME(7))
– NORENT
About This Book xix

The compiler now honors the NOMAP, NOMAPIN and NOMAP attributes for
PROCs and ENTRYs with OPTIONS(COBOL).
The compiler now supports PROCs with ENTRY statements that have differing
RETURNS attribute in the same manner as did the old host compiler.
The compiler will now assume OPTIONS(RETCODE) for PROCs and ENTRYs
with OPTIONS(COBOL).
The SIZE condition is no longer promoted to ERROR if unhandled.
Various changes have been made to reduce compile time and storage
requirements.
The OFFSET option will now produce a statement offset table much like the
ones it produced under the older PL/I compilers.
The FLAG option now has exactly the same meaning as it had under the old
compilers, while the new MAXMSG option lets you decide if the compiler
should terminate after a specified number of messages of a given severity. For
example, with FLAG(I) MAXMSG(E,10), you can now ask to see all I-level
messages while terminating the compilation after 10 E-level messages.
The AGGREGATE listing now includes structures with adjustable extents.
The STMT option is now supported for some sections of the listing.
The maximum value allowed for LINESIZE has been changed to 32759 for
F-format files and to 32751 for V-format files.
Improved usability
The defaults for compiler options may now be changed at installation.
The integrated SQL preprocessor now supports DB2 Unicode.
The compiler now generates information that allows Debug Tool to support
Auto Monitor, whereby immediately before each statement is executed, all the
values of all the variables used in the statement are displayed.
The new NOWRITABLE compiler option lets you specify that even under
NORENT and at the expense of optimal performance, the compiler should use
no writable static when generating code to handle FILEs and CONTROLLED.
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.
The new STDSYS compiler option lets you specify that the compiler should
cause the SYSPRINT file to be equated to the C stdout file.
The new COMPACT compiler option lets you direct the compiler to favour those
optimizations which tend to limit the growth of the code.
The LRECL for SYSPRINT has been changed to 137 to match that of the
C/C++ compiler.
POINTERs are now allowed in PUT LIST and PUT EDIT statements: the 8-byte
hex value will be output.
If specified on a STATIC variable, the ABNORMAL attribute will cause that
variable to be retained even if unused.
xx Enterprise PL/I Programming Guide

Enhancements in recent releases
This release also provides all of the functional enhancements offered in Enterprise
PL/I V3R1, including the following:
Support for Multithreading on 390
Support for IEEE floating-point on 390
Support for the ANSWER statement in the macro prepreprocessor
SAX-style XML parsing via the PLISAXA and PLISAXB built-in subroutines
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:
Initial UTF-16 support via the WIDECHAR attribute
There is currently no support yet for
– 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.
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:
– ACOSF
– ASINF
– ATANF
– CHARVAL
– COSF
– EXPF
– ISIGNED
– IUNSIGNED
– LOG10F
About This Book xxi

– LOGF
– ONWCHAR
– ONWSOURCE
– SINF
– TANF
– 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
- SUBSTR
- SYSPARM
- SYSTEM
- SYSVERSION
- TRANSLATE
- VERIFY
xxii Enterprise PL/I Programming Guide

Part 2. Compiling your program
Chapter 1. Using compiler options and facilities . . . . . . . . . . . . . . . . . 3
Compile-time option descriptions . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3
AGGREGATE . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 5
ARCH . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 5
ATTRIBUTES . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 6
BLANK . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 7
CHECK . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 7
CMPAT . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 7
CODEPAGE . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 8
COMPACT . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 9
COMPILE . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 9
CSECT . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 10
CURRENCY . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 11
DBCS . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 11
DD . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 11
DEFAULT . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 12
DISPLAY . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 19
DLLINIT . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 19
EXIT . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 19
EXTRN . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 19
FLAG . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 20
FLOAT . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 20
GONUMBER . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 20
GRAPHIC . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 21
INCAFTER . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 21
INCDIR . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 21
INCLUDE . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 22
INSOURCE . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 22
INTERRUPT . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 23
LANGLVL . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 24
LIMITS . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 24
LINECOUNT . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 25
LIST . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 25
MACRO . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 25
MAP . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 26
MARGINI . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 26
MARGINS . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 26
MAXMEM . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 27
MAXMSG . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 28
MAXSTMT . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 28
MDECK . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 28
NAMES . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 29
NAME . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 29
NATLANG . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 30
NEST . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 30
NOT . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 30
NUMBER . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 31
OBJECT . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 31
OFFSET . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 31
OPTIMIZE . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 31
 Copyright IBM Corp. 1991, 2002 1

OPTIONS . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 32
OR . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 33
PP . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 33
PPTRACE . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 34
PREFIX . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 34
PROCEED . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 34
REDUCE . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 35
RENT . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 36
RESPECT . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 37
RULES . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 37
SEMANTIC . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 41
SERVICE . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 42
SOURCE . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 42
SPILL . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 42
STDSYS . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 42
STMT . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 43
STORAGE . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 43
SYNTAX . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 43
SYSPARM . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 44
SYSTEM . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 44
TERMINAL . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 45
TEST . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 46
TUNE . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 47
USAGE . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 48
WIDECHAR . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 48
WINDOW . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 49
WRITABLE . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 49
XINFO . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 50
XREF . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 51
Specifying options in the %PROCESS or *PROCESS statements . . . . . . . . 52
Using % statements . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 53
Using the %INCLUDE statement . . . . . . . . . . . . . . . . . . . . . . . . . . 53
Using the compiler listing . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 55
Heading information . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 55
Options used for compilation . . . . . . . . . . . . . . . . . . . . . . . . . . . . 55
Preprocessor input . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 55
SOURCE program . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 56
Statement nesting level . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 56
ATTRIBUTE and cross-reference table . . . . . . . . . . . . . . . . . . . . . . 56
Attribute table . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 56
Cross-reference table . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 57
Aggregate length table . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 57
Statement offset addresses . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 57
Storage offset listing . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 59
File reference table . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 60
Messages and return codes . . . . . . . . . . . . . . . . . . . . . . . . . . . . 60
Chapter 2. PL/I preprocessors . . . . . . . . . . . . . . . . . . . . . . . . . . . 62
2 Enterprise PL/I Programming Guide

Chapter 1. Using compiler options and facilities
This chapter describes the options that you can use for the compiler, along with
their abbreviations and IBM-supplied defaults. It's important to remember that PL/I
requires access to Language Environment run time when you compile your
applications. You can override most defaults when you compile your PL/I program.
You can also override the defaults when you install the compiler.
Compile-time option descriptions

There are three types of compiler options; however, most compiler options have a
positive and negative form. The negative form is the positive with 'NO' added at
the beginning (as in TEST and NOTEST). Some options have only a positive form
(as in SYSTEM). The three types of compiler options are:
1. Simple pairs of keywords: a positive form that requests a facility, and an
alternative negative form that inhibits that facility (for example, NEST and
NONEST).
2. Keywords that allow you to provide a value list that qualifies the option (for
example, FLAG(W)).
3. A combination of 1 and 2 above (for example, NOCOMPILE(E)).
Table 3 lists all the compiler options with their abbreviations (if any) and their
IBM-supplied default values. If an option has any suboptions which may be
abbreviated, those abbreviations are described in the full description of the option.
For the sake of brevity, some of the options are described loosely in the table (for
example, only one suboption of LANGLVL is mandatory, and similarly, if you
specify one suboption of TEST, you do not have to specify the other). The full and
completely accurate syntax is described in the pages that follow.
The paragraphs following Table 3 describe the options in alphabetical order. For
those options specifying that the compiler is to list information, only a brief
description is included; the generated listing is described under “Using the compiler
listing” on page 55.
Table 3 (Page 1 of 3). Compile-time options, abbreviations, and IBM-supplied defaults

Compile-Time Option Abbreviated Name OS/390 Default
AGGREGATE | NOAGGREGATE AG | NAG NOAGGREGATE
ARCH(n) − ARCH(2)
ATTRIBUTES[(FULL|SHORT)] | A | NA NA [(FULL)]1
NOATTRIBUTES
BLANK('c') − BLANK('t')2
CHECK(STORAGE | NOSTORAGE) − CHECK(NSTG)
CMPAT(LE | V1 | V2) − CMPAT(V2)
CODEPAGE(n) CP CODEPAGE(1140)
COMPACT | NOCOMPACT − NOCOMPACT
COMPILE | NOCOMPILE[(W | E | S)] C | NC NOCOMPILE(S)
CSECT | NOCSECT CSE | NOCSE CSECT
CURRENCY('c') CURR CURRENCY($)
DBCS | NODBCS − NODBCS

DD(ddname-list) − DD(SYSPRINT,SYSIN,SYSLIB,
SYSPUNCH,SYSLIN)
DEFAULT(attribute | option) DFT See page 18
DISPLAY(STD | WTO) − DISPLAY(WTO)
DLLINIT | NODLLINIT − NODLLINIT
EXIT | NOEXIT − NOEXIT
EXTRN(FULL | SHORT) − EXTRN(SHORT)
FLAG[(I | W | E | S)] F FLAG(W)
FLOAT(AFP | NOAFP) − FLOAT(AFP)
GONUMBER | NOGONUMBER GN | NGN NOGONUMBER
GRAPHIC | NOGRAPHIC GR | NGR NOGRAPHIC
INCAFTER([PROCESS(filename)]) − INCAFTER()
INCDIR('directory name') − INCDIR()
INCLUDE[(EXT('include extension'))] INC INC(EXT('inc'))
INSOURCE[(FULL|SHORT)] | NOINSOURCE IS | NIS NOINSOURCE
INTERRUPT | NOINTERRUPT INT | NINT NOINTERRUPT
LANGLVL(SAA | SAA2[,NOEXT | OS]) − LANGLVL(SAA2,OS)
LIMITS(options) − See page 24
LINECOUNT(n) LC LINECOUNT(60)
LIST | NOLIST − NOLIST
MACRO | NOMACRO M | NM NOMACRO
MAP | NOMAP − NOMAP
MARGINI('c') | NOMARGINI MI | NMI NOMARGINI
MARGINS(m,n[,c]) MAR(m,n) MARGINS
F-format: (2,72)
V-format: (10,100)
MAXMEM(n) MAXM MAXMEM(1048576)
MAXMSG(I | W | E | S,n) − MAXMSG(W,250)
MAXSTMT(n) − MAXSTMT(4096)
MDECK | NOMDECK MD | NMD NOMDECK
NAME[('external name')] | NONAME N NAME
NAMES('lower'[,upper]) − NAMES('#@$','#@$')
NATLANG(ENU | UEN) − NATLANG(ENU)
NEST | NONEST − NONEST
NOT − NOT('¬')
NUMBER | NONUMBER NUM | NNUM NUMBER
OBJECT | NOOBJECT OBJ | NOBJ OBJECT
OFFSET | NOOFFSET OF | NOF NOOFFSET
OPTIMIZE(TIME | 0 | 2) | NOOPTIMIZE OPT | NOPT OPT(0)
OPTIONS | NOOPTIONS OP | NOP NOOPTIONS
OR('c') − OR(' | ')
PP(pp-name) | NOPP − NOPP
PPTRACE | NOPPTRACE − NOPPTRACE
PREFIX(condition) − See page 34
PROCEED | NOPROCEED[(W | E | S)] PRO | NPRO NOPROCEED(S)
REDUCE | NOREDUCE − REDUCE
RENT | NORENT − NORENT
RESPECT([DATE]) − RESPECT()
RULES(options) LAXCOM | NOLAXCOM See page 37
SEMANTIC | NOSEMANTIC[(W | E | S)] SEM | NSEM NOSEMANTIC(S)

SERVICE('service string') | NOSERVICE SERV | NOSERV NOSERVICE
SOURCE | NOSOURCE S | NS NOSOURCE
SPILL(n) SP SPILL(512)
STDSYS | NOSTDSYS − NOSTDSYS
STMT | NOSTMT − NOSTMT
STORAGE | NOSTORAGE STG | NSTG NOSTORAGE
SYNTAX | NOSYNTAX[(W | E | S)] SYN | NSYN NOSYNTAX(S)
SYSPARM('string') − SYSPARM('')
SYSTEM(MVS | CICS | IMS | TSO | OS) − SYSTEM(MVS)
TERMINAL | NOTERMINAL TERM | NTERM
TEST(ALL | NONE | STMT,SYM | ,NOSYM) | NOTEST − NOTEST(ALL,SYM)3
TUNE(n) − TUNE(3)
USAGE(options) − See page 48
WIDECHAR(BIGENDIAN | LITTLEENDIAN) WCHAR WIDECHAR(BIGENDIAN)
WINDOW(w) − WINDOW(1950)
WRITABLE | NOWRITABLE − WRITABLE
XINFO(options) − XINFO(NODEF,NOXML)
XREF[(FULL | SHORT)] | NOXREF X | NX NX [(FULL)]1
Notes:
1. FULL is the default suboption if the suboption is omitted with ATTRIBUTES or XREF.
2. The default value for the BLANK character is the tab character with value '05'x.
3. (ALL,SYM) is the default suboption if the suboption is omitted with TEST.
AGGREGATE
The AGGREGATE option creates an Aggregate Length Table that gives the lengths
of arrays and major structures in the source program in the compiler listing.
┌─NOAGGREGATE─┐

──┴─AGGREGATE───┴──────────────────────────────────────────────────────────────

ABBREVIATIONS: AG, NAG
In the Aggregate Length Table, the length of an undimensioned major or minor

structure is always expressed in bytes and might not be accurate if the major or
minor structure contains unaligned bit elements.
The Aggregate Length Table includes structures but not arrays that have
non-constant extents, but the sizes and offsets of elements within structures with
non-constant extents may be inaccurate or specified as *.
ARCH
The ARCH option specifies the architecture for which the executable program's
instructions are to be generated. It allows the optimizer to take advantage of
specific hardware instruction sets. A subparameter specifies the group to which a
model number belongs.
┌─2─┐

──ARCH──(──┴─n─┴──)────────────────────────────────────────────────────────────

Chapter 1. Using compiler options and facilities 5

The current values that may be specified for the ARCH level are:
0 Produces code that is executable on all models.
1 Produces code that executes only on the following and follow-on models:
9021-520, 9021-640, 9021-660, 9021-740, 9021-820, 9021-860, and
9021-900
9021-xx1 and 9021-xx2
9672-Rx1, 9672-Rx2(G1), 9672-Exx, and 9672-Pxx
9672-Rx3(G2), 9672-Rx4(G3), 9672-Rx5(G4), and 2003
Specifically, these ARCH(2) machines and their follow-ons include the Branch
Relative instruction set (Branch Relative and Save - BRAS), and the Halfword
Immediate instruction set (for example, Add Halfword Immediate - AHI).
9672-xx6 (G5) and 9672-xx7 (G6)
Specifically, these ARCH(3) machines and their follow-ons include a set of
facilities for IEEE floating-point representation, as well as 12 additional
floating-point registers and some new floating-point support instructions.
ARCH(3) (or higher) is required for execution of a program that uses IEEE
floating-point.
4 Produces code that is optimized for the zSeries models.
Specifically, these ARCH(4) machines include the ALCR and SLBR
instructions which are useful in 8-byte integer arithmetic.
Note: The "x" in the model numbers above (such as 9672-Rx4 is a "wildcard" and
stands for any alphanumeric machine of that type, such as 9627-RA4).
Note: Code that is compiled at ARCH(n) runs on machines in the ARCH(m) group
if and only if m >= n.
ATTRIBUTES
The ATTRIBUTES option specifies that the compiler includes a table of
source-program identifiers and their attributes in the compiler listing.
┌─NOATTRIBUTES─┐

──┴─ATTRIBUTES───┴──┬─────────────────┬────────────────────────────────────────

│ ┌─FULL──┐ │
└─(──┴─SHORT─┴──)─┘
ABBREVIATIONS: A, NA, F, S
FULL
All identifiers and attributes are included in the compiler listing. FULL is the
default.
SHORT
Unreferenced identifiers are omitted, making the listing more manageable.
If you include both ATTRIBUTES and XREF (creates a cross-reference table), the

two tables are combined. However, if the SHORT and FULL suboptions are in
conflict, the last option specified is used. For example, if you specify
ATTRIBUTES(SHORT) XREF(FULL), FULL applies to the combined listing.
BLANK
The BLANK option specifies up to ten alternate symbols for the blank character.
┌──
──────┐

──BLANK──(──'───char─┴─'──)────────────────────────────────────────────────────

Note: Do not code any blanks between the quotes.
The IBM-supplied default code point for the BLANK symbol is X'05'.
char
A single SBCS character.
You cannot specify any of the alphabetic characters, digits, and special characters
defined in the PL/I Language Reference.
If you specify the BLANK option, the standard blank symbol is still recognized as a
blank.
CHECK
The CHECK option alters the behavior of the ALLOCATE and FREE statements.
┌─NOSTORAGE─┐

──CHECK──(──┴─STORAGE───┴──)───────────────────────────────────────────────────

ABBREVIATIONS: STG, NSTG
When you specify CHECK(STORAGE), the compiler calls slightly different library
routines for ALLOCATE and FREE statements (except when these statements
occur within an AREA). The following built-in functions, described in the PL/I
Language Reference, can be used only when CHECK(STORAGE) has been
specified:
ALLOCSIZE
CHECKSTG
UNALLOCATED
CMPAT
The CMPAT option specifies whether object compatibility with OS PL/I Version 1,
OS PL/I Version 2, PL/I for MVS and VM, VisualAge PL/I for OS/390 or Enterprise
PL/I for z/OS is to be maintained for programs sharing strings, AREAs, arrays
and/or structures.
┌─V2─┐

──CMPAT──(──┼─LE─┼──)──────────────────────────────────────────────────────────

└─V1─┘

LE Under CMPAT(LE), your program can share strings, AREAs, arrays and/or
structures only with programs compiled with VisualAge PL/I for OS/390 or
Enterprise PL/I for z/OS and only as long as the CMPAT(V1) and CMPAT(V2)
options were not used when they were compiled.
V1 Under CMPAT(V1), you can share strings, AREAs, arrays and/or structures
with programs compiled with the OS PL/I Version 1 compiler and with programs
compiled with later PL/I compilers as long as the the CMPAT(V1) option was
used.
V2 Under CMPAT(V2), you can share strings, AREAs, arrays and/or structures
with programs compiled with the OS PL/I Version 2 compiler (and later
compilers) as long as the the CMPAT(V2) option was used.
DB2 stored procedures must be compiled with CMPAT(V1) or CMPAT(V2).
All the modules in an application must be compiled with the same CMPAT option.
Mixing old and new code still has some restrictions:

CONTROLLED variables cannot be shared between old and new code
FILE variables and constants cannot be shared between old and new code.
However, a file written out by old code can be read by new - and vice versa
the new code must be compiled with the NORENT and LIMITS(EXTNAME(7))
options
when old code is used, all fetch/release restrictions from the older product
apply. In particular, If a new MAIN does successfully FETCH and CALL an old
module, the old module cannot perform a subsequent FETCH of another
module
old code, even if compiled with PL/I for MVS & VM, cannot FETCH a new
module linked as a DLL
for old code compiled with OS PL/I V2R3 or earlier
– an old MAIN not linked with LE cannot FETCH a new module
– a new MAIN cannot CALL or FETCH an old module unless either the old or
new module is linked with SCEELKED and with INCLUDE
SYSLIB(CEESG010)
The DFT(DESCLIST) option conflicts with the CMPAT(V1) or CMPAT(V2) option,

and if it is specified with either the CMPAT(V1) or the CMPAT(V2) option, a
message will be issued and the DFT(DESCLOCATOR) option assumed.
CODEPAGE
The CODEPAGE option specifies the code page used for:
conversions between CHARACTER and WIDECHAR
the default code page used by the PLISAX built-in subroutines
──CODEPAGE──(──ccsid──)────────────────────────────────────────────────────────

The supported CCSID's are:

01047 01145 00273 00297
01140 01146 00277 00500
01141 01147 00278 00871
01142 01148 00280 00819
01143 01149 00284 00813
01144 00037 00285 00920
The default CCSID 1140 is an equivalent of CCSID 37 (EBCDIC Latin-1, USA) but
includes the Euro symbol.
COMPACT
During optimizations performed during code generation, choices must be made
between those optimizations which tend to result in faster but larger code and those
which tend to result in smaller but slower code. The COMPACT option influences
these choices. When the COMPACT option is used, the compiler favours those
optimizations which tend to limit the growth of the code. Because of the interaction
between various optimizations, including inlining, code compiled with the
COMPACT option may not always generate smaller code and data.
┌─NOCOMPACT─┐

──┴─COMPACT───┴────────────────────────────────────────────────────────────────

To evaluate the use of the COMPACT option for your application:

Compare the size of the objects generated with COMPACT and NOCOMPACT
Compare the size of the modules generated with COMPACT and
NOCOMPACT
Compare the execution time of a representative workload with COMPACT and
NOCOMPACT
If the objects and modules are smaller with an acceptable change in execution
time, then you can consider using COMPACT.
As new optimizations are added to the compiler, the behavior of the COMPACT
option may change. You should re-evaluate the use of this option for each new
release of the compiler and when the user changes the application code.
COMPILE
The COMPILE option causes the compiler to stop compiling after all semantic
checking of the source program if it produces a message of a specified severity
during preprocessing or semantic checking. Whether the compiler continues or not
depends on the severity of the error detected, as specified by the NOCOMPILE
option in the list below. The NOCOMPILE option specifies that processing stops
unconditionally after semantic checking.
┌─NOCOMPILE──┬─────────────┬─┐
│ │ ┌─S─┐ │ │
│ └─(──┼─W─┼──)─┘ │
│ └─E─┘ │

──┴─COMPILE────────────────────┴───────────────────────────────────────────────

ABBREVIATIONS: C, NC

COMPILE
Generates code unless a severe error or unrecoverable error is detected.
Equivalent to NOCOMPILE(S).
NOCOMPILE
Compilation stops after semantic checking.
NOCOMPILE(W)
No code generation if a warning, error, severe error, or unrecoverable error is
detected.
NOCOMPILE(E)
No code generation if an error, severe error, or unrecoverable error is detected.
NOCOMPILE(S)
No code generation if a severe error or unrecoverable error is detected.
If the compilation is terminated by the NOCOMPILE option, the cross-reference

listing and attribute listing can be produced; the other listings that follow the source
program will not be produced.
CSECT
The CSECT option ensures that the object module, if generated, contains named
CSECTs. Use this option if you will be using SMP/E to service your product or to
aid in debugging your program.
┌─CSECT───┐

──┴─NOCSECT─┴──────────────────────────────────────────────────────────────────

ABBREVIATIONS: CSE, NOCSE
Under the NOCSECT option, the code and static sections of your object module
are given default names.
Under the CSECT option, the code and static sections of your object module are
given names that depend on the "package name" which is defined as follows:
if the package statement was used, the "package name" is the leftmost label on
the package statement
otherwise, the "package name" is the leftmost label on the first procedure
statement.
A "modified package name" of length 7 is then formed as follows:

when the package name is less than 7 characters long, "*"'s are prefixed to it to
make a modified package name that is 7 characters long
when the package name is more than 7 characters long, the first 4 and last 3
characters are used to make the modified package name
otherwise the package name is copied to the modified package name
The code csect name is built by taking the modified package name and appending
a '1' to it.

The static csect name is built by taking the modified package name and appending
a '2' to it.
So, for a package named "SAMPLE", the code csect name would be "*SAMPLE1",
and the static csect name would be "*SAMPLE2", and
CURRENCY
The CURRENCY option allows you to specify an alternate character to be used in
picture strings instead of the dollar sign.
┌─$─┐

──CURRENCY──(──'──┴─x─┴──'──)──────────────────────────────────────────────────

ABBREVIATIONS: CURR
x Character that you want the compiler and runtime to recognize and accept as
the dollar sign in picture strings.
DBCS
The DBCS option ensures that the listing, if generated, is sensitive to the possible
presence of DBCS even though the GRAPHIC option has not been specified.
┌─NODBCS─┐

──┴─DBCS───┴───────────────────────────────────────────────────────────────────

The NODBCS option will cause the listing, if generated, to show all DBCS
shift-codes as ".".
The NODBCS option should not be specified if the GRAPHIC option is also
specified.
DD
The DD option allows you to specify alternate DD names for the compiler listing,
the primary source file, the default include dataset and the mdeck dataset.
──DD──┬─────────────────────────────────────────────────────────────────────────────┬─────

└─(──SYSPRINT──┬─────────────────────────────────────────────────────────┬──)─┘
└─,──SYSIN──┬───────────────────────────────────────────┬─┘
└─,──SYSLIB──┬────────────────────────────┬─┘
└─,──SYSPUNCH──┬───────────┬─┘
└─,──SYSLIN─┘
Up to five DD names may be specified. In order, they specify alternate DD names

for
SYSPRINT
SYSIN
SYSLIB
SYSPUNCH
SYSLIN

If you wanted to use ALTIN as the DD name for the primary compiler source file,
you would have to specify DD(SYSPRINT,ALTIN). If you specified DD(ALTIN),
SYSIN would be used as the DDNAME for the primary compiler source file and
ALTIN would be used as the DD name for the compiler listing.
You can also use * to indicate that the default DD name should be used. Thus
DD(*,ALTIN) is equivalent to DD(SYSPRINT,ALTIN).
DEFAULT
The DEFAULT option specifies defaults for attributes and options. These defaults
are applied only when the attributes or options are not specified or implied in the
source.
──DEFAULT──(──┬────────────────────────────────────────────────┬──)───────────────────────

│ ┌─┬───┬──────────────────────────────────────┐ │
│ │ └─,─┘ │ │
│ │ ┌─IBM─┐ │ │

└───┬─┴─ANS─┴────────────────────────────────┬─┴─┘
│ ┌─EBCDIC─┐ │
├─┴─ASCII──┴─────────────────────────────┤
│ ┌─ASSIGNABLE────┐ │
├─┴─NONASSIGNABLE─┴──────────────────────┤
│ ┌─BYADDR──┐ │
├─┴─BYVALUE─┴────────────────────────────┤
│ ┌─NONCONNECTED─┐ │
├─┴─CONNECTED────┴───────────────────────┤
│ ┌─DESCRIPTOR───┐ │
├─┴─NODESCRIPTOR─┴───────────────────────┤
│ ┌─NATIVE────┐ │
├─┴─NONNATIVE─┴──────────────────────────┤
│ ┌─NATIVEADDR────┐ │
├─┴─NONNATIVEADDR─┴──────────────────────┤
│ ┌─NOINLINE─┐ │
├─┴─INLINE───┴───────────────────────────┤
│ ┌─ORDER───┐ │
├─┴─REORDER─┴────────────────────────────┤
│ ┌─OPTLINK─┐ │
├─LINKAGE──(──┴─SYSTEM──┴──)─────────────┤
│ ┌─EVENDEC───┐ │
├─┴─NOEVENDEC─┴──────────────────────────┤
│ ┌─NULL37K─┐ │
├─┴─NULLSYS─┴────────────────────────────┤
│ ┌─NONRECURSIVE─┐ │
├─┴─RECURSIVE────┴───────────────────────┤
│ ┌─DESCLOCATOR─┐ │
├─┴─DESCLIST────┴────────────────────────┤
│ ┌─BYADDR──┐ │
├─RETURNS──(──┴─BYVALUE─┴──)─────────────┤
│ ┌─NOINITFILL─────────────────────────┐ │
├─┴─INITFILL──┬──────────────────────┬─┴─┤
│ └─(────init_value────)─┘ │
│ ┌─HEXADEC─┐ │
├─SHORT──(──┴─IEEE────┴──)───────────────┤
│ ┌─ALIGNED───┐ │
├─DUMMY──(──┴─UNALIGNED─┴──)─────────────┤
│ ┌─LOWERINC─┐ │
├─┴─UPPERINC─┴───────────────────────────┤
│ ┌─NORETCODE─┐ │
├─┴─RETCODE───┴──────────────────────────┤
│ ┌─ALIGNED───┐ │
├─┴─UNALIGNED─┴──────────────────────────┤
│ ┌─MIN─┐ │
├─ORDINAL──(──┴─MAX─┴──)─────────────────┤
│ ┌─NOOVERLAP─┐ │
├─┴─OVERLAP───┴──────────────────────────┤
├─┴─IEEE────┴────────────────────────────┤
└─E──(──┴─IEEE────┴──)───────────────────┘
ABBREVIATIONS: DFT, ASGN, NONASGN, NONCONN, CONN, INL, NOINL

IBM or ANS
Use IBM or ANS SYSTEM defaults. The arithmetic defaults for IBM and ANS
are the following:
Attributes DEFAULT(IBM) DEFAULT(ANS)

FIXED DECIMAL (5,0) (10,0)
FIXED BINARY (15,0) (31,0)
FLOAT DECIMAL (6) (6)
FLOAT BINARY (21) (21)
Under the IBM suboption, variables with names beginning from I to N default to
FIXED BINARY and any other variables default to FLOAT DECIMAL. If you
select the ANS suboption, the default for all variables is FIXED BINARY.
IBM is the default.
ASCII | EBCDIC
Use this option to set the default for the character set used for the internal
representation of character problem program data.
Specify ASCII only when compiling programs that depend on the ASCII
character set collating sequence. Such a dependency exists, for example, if
your program relies on the sorting sequence of digits or on lowercase and
uppercase alphabetics. This dependency also exists in programs that create
an uppercase alphabetic character by changing the state of the high-order bit.
Note: The compiler supports A and E as suffixes on character strings. The A
suffix indicates that the string is meant to represent ASCII data, even if the
EBCDIC compiler option is in effect. Alternately, the E suffix indicates that the
string is EBCDIC, even when you select DEFAULT(ASCII).
'123'A is the same as '313233'X
'123'E is the same as 'F1F2F3'X
EBCDIC is the default.
ASSIGNABLE | NONASSIGNABLE
This option causes the compiler to apply the specified attribute to all static
variables that are not declared with the ASSIGNABLE or NONASSIGNABLE
attribute. The compiler flags statements in which NONASSIGNABLE variables
are the targets of assignments.
ASSIGNABLE is the default.
BYADDR | BYVALUE
Set the default for whether arguments or parameters are passed by address or
by value. BYVALUE applies only to certain arguments and parameters. See
the PL/I Language Reference for more information.
BYADDR is the default.
CONNECTED | NONCONNECTED
Set the default for whether parameters are connected or nonconnected.
CONNECTED allows the parameter to be used as a target or source in
record-oriented I/O or as a base in string overlay defining.
NONCONNECTED is the default.

DESCRIPTOR | NODESCRIPTOR
Using DESCRIPTOR with a PROCEDURE indicates that a descriptor list was
passed, while DESCRIPTOR with ENTRY indicates that a descriptor list should
be passed. NODESCRIPTOR results in more efficient code, but has the
following restrictions:
For PROCEDURE statements, NODESCRIPTOR is invalid if any of the

parameters have:
– An asterisk (*) specified for the bound of an array, the length of a
string, or the size of an area except if it is a VARYING or VARYINGZ
string with the NONASSIGNABLE attribute
– The NONCONNECTED attribute
– The UNALIGNED BIT attribute
For ENTRY declarations, NODESCRIPTOR is invalid if an asterisk (*) is
specified for the bound of an array, the length of a string, or the size of an
area in the ENTRY description list.
DESCRIPTOR is the default.
NATIVE | NONNATIVE
This option affects only the internal representation of fixed binary, ordinal,
offset, area, and varying string data. When the NONNATIVE suboption is in
effect, the NONNATIVE attribute is applied to all such variables not declared
with the NATIVE attribute.
You should specify NONNATIVE only to compile programs that depend on the
nonnative format for holding these kind of variables.
If your program bases fixed binary variables on pointer or offset variables (or
conversely, pointer or offset variables on fixed binary variables), specify either:
Both the NATIVE and NATIVEADDR suboptions

Both the NONNATIVE and NONNATIVEADDR suboptions.
Other combinations produce unpredictable results.

NATIVE is the default.
NATIVEADDR | NONNATIVEADDR
This option affects only the internal representation of pointers. When the
NONNATIVEADDR suboption is in effect, the NONNATIVE attribute is applied
to all pointer variables not declared with the NATIVE attribute.
If your program bases fixed binary variables on pointer or offset variables (or
conversely, pointer or offset variables on fixed binary variables), specify either:
Both the NATIVE and NATIVEADDR suboptions

Both the NONNATIVE and NONNATIVEADDR suboptions.
Other combinations produce unpredictable results.

NATIVEADDR is the default.
INLINE | NOINLINE
This option sets the default for the inline procedure option.
Specifying INLINE allows your code to run faster but, in some cases, also
creates a larger executable file. For more information on how inlining can

improve the performance of your application, see Chapter 11, “Improving
performance” on page 230.
NOINLINE is the default.
ORDER | REORDER
Affects optimization of the source code. Specifying REORDER allows further
optimization of your source code, see Chapter 11, “Improving performance” on
page 230.
ORDER is the default.
LINKAGE
The linkage convention for procedure invocations is:
OPTLINK
The default linkage convention for Enterprise PL/I. This linkage provides
the best performance.
SYSTEM
The standard linking convention for system APIs.
LINKAGE(OPTLINK) should be used for all routines called by or calling to

JAVA, and it should also be used for all routines called by or calling to C
(unless the C code has been compiled with a non-default linkage).
LINKAGE(SYSTEM) should be used for all non-PL/I routines that expect the
high-order bit to be on in the address of the last (and only the last) parameter.
LINKAGE(OPTLINK) is the default.
EVENDEC | NOEVENDEC
This suboption controls the compiler's tolerance of fixed decimal variables
declared with an even precision.
Under NOEVENDEC, the precision for any fixed decimal variable is rounded up
to the next highest odd number.
If you specify EVENDEC and then assign 123 to a FIXED DEC(2) variable, the
SIZE condition is raised. If you specify NOEVENDEC, the SIZE condition is not
raised.
EVENDEC is the default.
NULLSYS | NULL370
This suboption determines which value is returned by the NULL built-in
function. If you specify NULLSYS, binvalue(null()) is equal to 0. If you want
binvalue(null()) to equal 'ff_00_00_00'xn as is true with previous releases of
PL/I, specify NULL370.
NULL370 is the default.
RECURSIVE | NONRECURSIVE
When you specify DEFAULT(RECURSIVE), the compiler applies the
RECURSIVE attribute to all procedures. If you specify
DEFAULT(NONRECURSIVE), all procedures are nonrecursive except
procedures with the RECURSIVE attribute.
NONRECURSIVE is the default.

DESCLIST | DESCLOCATOR
When you specify DEFAULT(DESCLIST), the compiler passes all descriptors in
a list as a 'hidden' last parameter.
If you specify DEFAULT(DESCLOCATOR), parameters requiring descriptors
are passed using a locator or descriptor in the same way as previous releases
of PL/I. This allows old code to continue to work even if it passed a structure
from one routine to a routine that was expecting to receive a pointer.
The DFT(DESCLIST) option conflicts with the CMPAT(V1) or CMPAT(V2)
option, and if it is specified with either the CMPAT(V1) or the CMPAT(V2)
option, a message will be issued and the DFT(DESCLOCATOR) option
assumed.
DESCLOCATOR is the default.
RETURNS (BYVALUE | BYADDR)

Sets the default for how values are returned by functions. See the PL/I
Language Reference for more information.
You should specify RETURNS(BYADDR) if your application contains ENTRY
statements and the ENTRY statements or the containing procedure statement
have the RETURNS option. You must also specify RETURNS(BYADDR) on
the entry declarations for such entries.
RETURNS(BYADDR) is the default.
INITFILL | NOINITFILL
This suboption controls the default initialization of automatic variables.
If you specify INITFILL with a hex value (nn), that value is used to initialize the
storage used by all automatic variables in a block each time that block is
entered. If you do not enter a hex value, the default is '00'.
Note that the hex value may be specified without or without quotes, but if it is
specified with quotes, the string should not have an X suffix.
Under NOINITFILL, the storage used by an automatic variable may hold
arbitrary bit patterns unless the variable is explicitly initialized.
INITIFILL can cause programs to run significantly slower and should not be
specified in production programs. However, the INITFILL option produces code
that runs faster than the LE STORAGE option. Also, during program
development, this option is very useful for detecting uninitialized automatic
variables: a program that runs correctly with DFT(INITFILL('00')) and with with
DFT(INITFILL('ff')) probably has no uninitialized automatic variables.
NOINITIFILL is the default.
SHORT (HEXADEC | IEEE)

This suboption improves compatibility with other non-IBM UNIX compilers.
SHORT (HEXADEC) maps FLOAT BIN (p) to a short (4-byte) floating point
number for p <= 21. SHORT (IEEE) maps FLOAT BIN (p) to a short (4-byte)
floating point number for p <= 24.
SHORT (HEXADEC) is the default.
DUMMY (ALIGNED | UNALIGNED)

This suboption reduces the number of situations in which dummy arguments
get created.

DUMMY(ALIGNED) indicates that a dummy argument should be created even if
an argument differs from a parameter only in its alignment.
DUMMY(UNALIGNED) indicates that no dummy argument should be created
for a scalar (except a nonvarying bit) or an array of such scalars if it differs
from a parameter only in its alignment.
Consider the following example:
dcl
1 a1 unaligned,
2 b1 fixed bin(31),
2 b2 fixed bin(15),
2 b3 fixed bin(31),
2 b4 fixed bin(15);
dcl x entry( fixed bin(31) );
call x( b3 );
If you specified DEFAULT(DUMMY(ALIGNED)), a dummy argument would be
created, while if you specified DEFAULT(DUMMY(UNALIGNED)), no dummy
argument would be created.
DUMMY(ALIGNED) is the default.
LOWERINC | UPPERINC
If you specify LOWERINC, the compiler requires that the actual file names of
INCLUDE files are in lowercase. If you specify UPPERINC, the compiler
requires that the names are in uppercase.
Note: This suboption applies only to compilations under OS/390 UNIX.
Under OS/390 UNIX, the include name is built using the EXT suboption of the
INCLUDE option. So, for example, under the DFT(LOWERINC) and
INCLUDE(EXT('inc')) option, the statement %INCLUDE STANDARD; will cause
the compiler to try to include standard.inc.
LOWERINC is the default.
RETCODE | NORETCODE
If you specify RETCODE, for any external procedure that does not have the
RETURNS attribute, the compiler will generate extra code so that the
procedure returns the integer value obtained by invoking the PLIRETV built-in
function just prior to returning from that procedure.
If you specify NORETCODE, no special code is generated for procedures that
do not have the RETURNS attribute.
NORETCODE is the default.
ALIGNED | UNALIGNED
This suboption allows you to force byte-alignment on all of your variables.
If you specify ALIGNED, all variables other than character, bit, graphic, and
picture are given the ALIGNED attribute unless the UNALIGNED attribute is
explicitly specified (possibly on a parent structure) or implied by a DEFAULT
statement.
If you specify UNALIGNED, all variables are given the UNALIGNED attribute
unless the ALIGNED attribute is explicitly specified (possibly on a parent
structure) or implied by a DEFAULT statement.

ALIGNED is the default.
ORDINAL(MIN | MAX)
If you specify ORDINAL(MAX), all ordinals whose definition does not include a
PRECISION attribute is given the attribute PREC(31). Otherwise, they are
given the smallest precision that covers their range of values.
ORDINAL(MIN) is the default.
OVERLAP | NOOVERLAP
If you specify OVERLAP, the compiler presumes the source and target in an
assignment can overlap and generates, as needed, extra code in order to
ensure that the result of the assignment is okay.
NOOVERLAP will produce code that performs better; however, if you use
NOOVERLAP, you must insure that the source and target never overlap.
NOOVERLAP is the default.
HEXADEC | IEEE
This suboption allows you to specify the default representation used to hold all
FLOAT variables and all floating-point intermediate results.
Programs that communicate with JAVA should probably use the IEEE option,
and programs that pass data to or receive data from platforms where IEEE is
the default representation for floating-point data might also want to use the
IEEE option.
If use DFT(IEEE) and extended-precision floating point, you must link and run
with z/OS 1.2 or later.
HEXADEC is the default.
E (HEXADEC | IEEE)
The E suboption determines how many digits will be used for the exponent in
E-format items.
If you specify E(IEEE), 4 digits will be used for the exponent in E-format items.
If you specify E(HEXADEC), 2 digits will be used for the exponent in E-format
items.
If DFT( E(HEXADEC) ) is specified, an attempt to use an expression whose
exponent has an absolute value greater than 99 will cause the SIZE condition
to be raised.
If the compiler option DFT(IEEE) is in effect, you should normally also use the
option DFT( E(IEEE) ). However, under this option, some E format items that
would be valid under DFT( E(HEXADEC) ) would not be valid. For instance,
under DFT( E(IEEE) ), the statement "put skip edit(x) ( e(15,8));" would be
flagged because the E format item is invalid.
E(HEXADEC) is the default.
Default: DEFAULT( IBM EBCDIC ASSIGNABLE BYADDR NONCONNECTED

DESCRIPTOR NATIVE NATIVEADDR NOINLINE ORDER LINKAGE(OPTLINK)
EVENDEC NOINITFILL LOWERINC NULL370 NONRECURSIVE DESCLOCATOR
RETURNS(BYADDR) SHORT(HEXADEC) DUMMY(ALIGNED) NORETCODE
ALIGNED ORDINAL(MIN) NOOVERLAP HEXADEC E(HEXADEC) )

DISPLAY
The DISPLAY option determines how the DISPLAY statement performs I/O.
┌─WTO─┐

──DISPLAY──(──┴─STD─┴──)───────────────────────────────────────────────────────

STD
All DISPLAY statements are completed by writing the text to stdout and
reading any REPLY text from stdin.
WTO
All DISPLAY statements are completed via WTOs. This is the default.
DLLINIT
The DLLINIT option applies OPTIONS(FETCHABLE) to all external procedures that
are not MAIN. It should be used only on compilation units containing one external
procedure, and then that procedure should be linked as a DLL.
┌─NODLLINIT─┐

──┴─DLLINIT───┴────────────────────────────────────────────────────────────────

NODLLINIT has no effect on your programs.
EXIT
The EXIT option enables the compiler user exit to be invoked.
┌─NOEXIT────────────────────────────┐

──┴─EXIT──┬─────────────────────────┬─┴────────────────────────────────────────

└─(────inparm_string────)─┘
inparm_string
A string that is passed to the compiler user exit routine during initialization.
The string can be up to 31 characters long.
EXTRN
The EXTRN option controls when EXTRNs are emitted for external entry constants.
┌─SHORT─┐

──EXTRN──(──┴─FULL──┴──)───────────────────────────────────────────────────────

FULL
EXTRNs are emitted for all declared external entry constants.
SHORT
EXTRNs are emitted only for those constants that are referenced. This is the
default.

FLAG
The FLAG option specifies the minimum severity of error that requires a message
listed in the compiler listing.
──FLAG──┬─────────────┬────────────────────────────────────────────────────────

│ ┌─W─┐ │
└─(──┼─I─┼──)─┘
├─E─┤
└─S─┘
ABBREVIATION: F
I List all messages.
W List all except information messages.
E List all except warning and information messages.
S List only severe error and unrecoverable error messages.
If messages are below the specified severity or are filtered out by a compiler exit
routine, they are not listed.
FLOAT
The FLOAT option controls the use of additional floating-point registers.
┌─AFP───┐

──FLOAT──(──┴─NOAFP─┴──)───────────────────────────────────────────────────────

FLOAT(NOAFP)
Compiler-generated code uses the traditional 4 floating-point registers.
FLOAT(AFP)
Compiler-generated code uses 16 floating-point registers.
GONUMBER
The GONUMBER option specifies that the compiler produces additional information
that allows line numbers from the source program to be included in run-time
messages.
┌─NOGONUMBER─┐

──┴─GONUMBER───┴───────────────────────────────────────────────────────────────

ABBREVIATIONS: GN, NGN
Alternatively, the line numbers can be derived by using the offset address, which is
always included in run-time messages, and either the table produced by the
OFFSET option or the assembler listing produced by the LIST option.
GONUMBER is forced by the ALL and STMT suboptions of the TEST option.
Note that there is no GOSTMT option. The only option that will produce
information at run-time identifying where an error has occurred is the GONUMBER

option. Also note that when the GONUMBER option is used, the term "statement"
in the run-time error messages will refer to line numbers as used by the NUMBER
compiler option - even if the STMT option was in effect.
GRAPHIC
The GRAPHIC option specifies that the source program can contain double-byte
characters. The hexadecimal codes '0E' and '0F' are treated as the shift-out and
shift-in control codes, respectively, wherever they appear in the source program,
including occurrences in comments and string constants.
┌─NOGRAPHIC─┐

──┴─GRAPHIC───┴────────────────────────────────────────────────────────────────

ABBREVIATIONS: GR, NGR
The GRAPHIC option must be specified if the source program uses any of the
following:
DBCS identifiers
Graphic string constants
Mixed-string constants
Shift codes anywhere else in the source
INCAFTER
The INCAFTER option specifies a file to be included after a particular statement in
your source program.
──INCAFTER──(──┬─────────────────────────┬──)──────────────────────────────────

└─PROCESS──(──filename──)─┘
filename
Name of the file to be included after the last PROCESS statement.
Currently, PROCESS is the only suboption and specifies the name of a file to be
included after the last PROCESS statement.
Consider the following example:

INCAFTER(PROCESS(DFTS))
This example is equivalent to having the statement %INCLUDE DFTS; after the last
PROCESS statement in your source.
INCDIR
The INCDIR compiler option specifies a directory to be added to the search path
used to locate of include files.
Note: This option applies only to compilations under OS/390 UNIX.
──INCDIR──(──'directory name'──)───────────────────────────────────────────────


directory name
Name of the directory that should be searched for include files. You can
specify the INCDIR option more than once and the directories are searched in
order.
The compiler looks for INCLUDE files in the following order:

1. Current directory
2. Directories specified with the –I flag or with the INCDIR compiler option
3. /usr/include directory
INCLUDE
The INCLUDE option specifies the file name extensions under which include files
are searched.
──INCLUDE──┬──────────────────────────────────────┬────────────────────────────

└─(──EXT──(──'include extension'──)──)─┘
ABBREVIATION: INC
The include extension string can be up to 31 characters long, but it is truncated to

the first three characters. If the extension strings conform to the rules for PL/I
identifiers, you do not need to enclose them in quotes.
The compiler folds these strings to uppercase under DFT(UPPERINC) and to

lowercase under DFT(LOWERINC).
If you specify more than one file name extension, the compiler searches for include
files with the left most extension you specify first. It then searches for extensions
that you specified from left to right. You can specify a maximum of 7 extensions.
The default include extension string is 'inc'.
Do not use PLI as an extension for an include file.
INSOURCE
The INSOURCE option specifies that the compiler should include a listing of the
source program before the PL/I macro preprocessor translates it.
┌─NOINSOURCE────────────────────┐

──┴─INSOURCE──┬─────────────────┬─┴────────────────────────────────────────────

│ ┌─FULL──┐ │
└─(──┴─SHORT─┴──)─┘
ABBREVIATION: IS, NIS
FULL
The INSOURCE listing will ignore %NOPRINT statements and will contain all
the source before the preprocessor translates it.
FULL is the default.

SHORT
The INSOURCE listing will heed %PRINT and %NOPRINT statements.
The INSOURCE listing has no effect unless the MACRO option is in effect.
Under the INSOURCE option, text is included in the listing not according to the
logic of the program, but as each file is read. So, for example, consider the
following simple program which has a %INCLUDE statement between its PROC
and END statements.
insource: proc options(main);

%include member;
end;
The INSOURCE listing will contain all of the main program before any of the
included text from the file "member" (and it would contain all of that file before any
text included by it - and so on).
Under the INSOURCE(SHORT) option, text included by a %INCLUDE statement

inherits the print/noprint status that was in effect when the %INCLUDE statement
was executed, but that print/noprint status is restored at the end of the included text
(however, in the SOURCE listing, the print/noprint status is not restored at the end
of the included text).
INTERRUPT
The INTERRUPT option causes the compiled program to respond to attention
requests (interrupts).
┌─NOINTERRUPT─┐

──┴─INTERRUPT───┴──────────────────────────────────────────────────────────────

ABBREVIATION: INT, NINT
This option determines the effect of attention interrupts when the compiled PL/I
program runs under an interactive system. This option will have an effect only on
programs running under TSO. If you have written a program that relies on raising
the ATTENTION condition, you must compile it with the INTERRUPT option. This
option allows attention interrupts to become an integral part of programming. This
gives you considerable interactive control of the program.
If you specify the INTERRUPT option, an established ATTENTION ON-unit gets

control when an attention interrupt occurs. When the execution of an ATTENTION
ON-unit is complete, control returns to the point of interrupt unless directed
elsewhere by means of a GOTO statement. If you do not establish an ATTENTION
ON-unit, the attention interrupt is ignored.
If you specify NOINTERRUPT, an attention interrupt during a program run does not
give control to any ATTENTION ON-units.
If you require the attention interrupt capability only for testing purposes, use the
TEST option instead of the INTERRUPT option. For more information see “TEST”
on page 46.

See Chapter 17, “Interrupts and attention processing” on page 345 for more
information about using interrupts in your programs.
LANGLVL
The LANGLVL option specifies the level of PL/I language definition that you want
the compiler to accept.
┌─┬───┬─────────┐
│ └─,─┘ │
│ ┌─SAA2─┐ │

──LANGLVL──(────┬─┴─SAA──┴──┬─┴──)─────────────────────────────────────────────

│ ┌─OS────┐ │
└─┴─NOEXT─┴─┘
SAA
The compiler flags keywords and other language constructs that are not
supported by OS PL/I Version 2 Release 3, and the compiler does not
recognize any built-in functions not supported by OS PL/I Version 2 Release 3.
SAA2
The compiler accepts the PL/I language definition contained in the PL/I
Language Reference.
NOEXT
The only ENVIRONMENT options accepted are:
Bkwd Genkey Keyloc Relative

Consecutive Graphic Organization Scalarvarying
Ctlasa Indexed Recsize Vsam
Deblock Keylength Regional
OS
All ENVIRONMENT options are allowed. For a complete list of the
ENVIRONMENT options, see Table 13 on page 147.
LIMITS
The LIMITS option specifies various implementation limits.
┌─┬───┬─────────────────────────────────────┐
│ └─,─┘ │
│ ┌─7─┐ │

──LIMITS──(────┬─EXTNAME──(──┴─n─┴──)──────────────────┬─┴──)──────────────────

│ ┌─15─┐ │
├─FIXEDDEC──(──┴─31─┴──)────────────────┤
│ ┌─31─┐ │
├─FIXEDBIN──(──┴─63─┴──┬───────────┬──)─┤
│ └─,──┬─31─┬─┘ │
│ └─63─┘ │
│ ┌─1##─┐ │
└─NAME──(──┴─n───┴──)───────────────────┘
EXTNAME
Specifies the maximum length for EXTERNAL name. The maximum value for n
is 100; the minimum value is 7.
FIXEDDEC
Specifies the maximum precision for FIXED DECIMAL.

FIXEDBIN
Specifies the maximum precision for SIGNED FIXED BINARY to be either 31 or
63. The default is 31.
If FIXEDBIN(31,63) is specified, then you may declare 8-byte integers, but
unless an expression contains an 8-byte integer, all arithmetic will done using
4-byte integers.
FIXEDBIN(63,31) is not allowed.
The maximum precision for UNSIGNED FIXED BINARY is one greater, that is,
32 and 64.
NAME
Specifies the maximum length of variable names in your program. The
maximum value for n is 100; the minimum value is 31.
LINECOUNT
The LINECOUNT option specifies the number of lines per page for compiler
listings, including blank and heading lines.
┌─6#─┐

────LINECOUNT────(──┴─n──┴──)──────────────────────────────────────────────────

ABBREVIATION: LC
n The number of lines in a page in the listing. The value can be from 10 to
32,767.
LIST
The LIST option specifies that the compiler should produce a pseudo-assembler
listing.
┌─NOLIST─┐

──┴─LIST───┴───────────────────────────────────────────────────────────────────

Specifying the LIST option will increase time and region required for a compilation.
The OFFSET and MAP options may provide the information you need at much less
cost.
MACRO
The MACRO option invokes the MACRO preprocessor.
┌─NOMACRO─┐

──┴─MACRO───┴──────────────────────────────────────────────────────────────────

You may also invoke the MACRO preprocessor via the PP(MACRO) option. For
more discussion of the PP option, see “PP” on page 33.
For more discussion of the MACRO preprocessor, see “Macro preprocessor” on

page 65.

MAP
The MAP option specifies that the compiler produces additional information that can
be used to locate static and automatic variables in dumps.
┌─NOMAP─┐

──┴─MAP───┴────────────────────────────────────────────────────────────────────

MARGINI
The MARGINI option specifies a character that the compiler will place in the column
preceding the left-hand margin, and also in the column following the right-hand
margin, of the listings produced by the INSOURCE and SOURCE options.
┌─NOMARGINI─┐

──┴─MARGINI───┴──(──'──c──'──)─────────────────────────────────────────────────

ABBREVIATIONS: MI, NMI
c The character to be printed as the margin indicator.
Note: NOMARGINI is equivalent to MARGINI(' ').
MARGINS
The MARGINS option specifies which part of each compiler input record contains
PL/I statements, and the position of the ANS control character that formats the
listing, if the SOURCE and/or INSOURCE options apply. The compiler does not
process data that is outside these limits, but it does include it in the source listings.
The PL/I source is extracted from the source input records so that the first data
byte of a record immediately follows the last data byte of the previous record. For
variable records, you must ensure that when you need a blank you explicitly insert
it between margins of the records.
┌─2─┐ ┌─72─┐

──MARGINS──(──┴─m─┴──,──┴─n──┴──┬──────┬──)────────────────────────────────────

└─,──c─┘
ABBREVIATION: MAR
m The column number of the leftmost character (first data byte) that is processed
by the compiler. It must not exceed 100.
n The column number of the rightmost character (last data byte) that is
processed by the compiler. It should be greater than m, but must not exceed
200, except under MVS batch where it must not exceed 100.
Variable-length records are effectively padded with blanks to give them the
maximum record length.
c The column number of the ANS printer control character. It must not exceed
200, except under MVS batch where it must not exceed 100, and it should be
outside the values specified for m and n. A value of 0 for c indicates that no
ANS control character is present. Only the following control characters can be
used:

(blank) Skip one line before printing
0 Skip two lines before printing
– Skip three lines before printing
+ No skip before printing
1 Start new page
Any other character is an error and is replaced by a blank.

Do not use a value of c that is greater than the maximum length of a source
record, because this causes the format of the listing to be unpredictable. To
avoid this problem, put the carriage control characters to the left of the source
margins for variable-length records.
Specifying MARGINS(,,c) is an alternative to using %PAGE and %SKIP
statements (described in PL/I Language Reference).
The IBM-supplied default for fixed-length records is MARGINS(2,72). For

variable-length and undefined-length records, the IBM-supplied default is
MARGINS(10,100). This specifies that there is no printer control character.
Use the MARGINS option to override the default for the primary input in a program.
The secondary input must have the same margins as the primary input.
MAXMEM
When compiling with OPTIMIZE, the MAXMEM option limits the amount of memory
used for local tables of specific, memory intensive optimizations to the specified
number of kilobytes. The minimum number of kilobytes that may be specified is 1.
The maximum number of kilobytes that may be specified is 2097152, and the
default is 1048576.
If you specify the maximum value of 2097152, the compiler will assume that
unlimited memory is available. If you specify any smaller value for MAXMEM, the
compiler, especially when the OPT(2) option is in effect, may issue a message
saying that optimization is inhibited and that you should try using a larger value for
MAXMEM.
Use the MAXMEM option if you know that less (or more) memory is available than
implied by the default value.
If the memory specified by the MAXMEM option is insufficient for a particular

optimization, the compilation is completed in such a way that the quality of the
optimization is reduced, and a warning message is issued.
──MAXMEM──(──size──)───────────────────────────────────────────────────────────

ABBREVIATIONS: MAXM
When a large size is specified for MAXMEM, compilation may be aborted because
of insufficient virtual storage, depending on the source file being compiled, the size
of the subprogram in the source, and the virtual storage available for the
compilation.

The advantage of using the MAXMEM option is that, for large and complex
applications, the compiler produces a slightly less-optimized object module and
generates a warning message, instead of terminating the compilation with an error
message of "insufficient virtual storage".
MAXMSG
The MAXMSG option specifies the maximum number of messages with a given
severity (or higher) that the compilation should produce.
──MAXMSG──┬───────────────────────┬────────────────────────────────────────────

│ ┌─┬───┬───────┐ │
│ │ └─,─┘ │ │
│ │ ┌─W─┐ │ │
└─(────┬─┼─I─┼───┬─┴──)─┘
│ ├─E─┤ │
│ └─S─┘ │
│ ┌─25#─┐ │
└─┴─n───┴─┘
I Count all messages.
W Count all except information messages.
E Count all except warning and information messages.
S Count only severe error and unrecoverable error messages.
n Terminate the compilation if the number of messages exceeds this value. If

messages are below the specified severity or are filtered out by a compiler exit
routine, they are not counted in the number. The value of n can range from 0
to 32767. If you specify 0, the compilation terminates when the first error of the
specified severity is encountered.
MAXSTMT
Under the MAXSTMT option, optimization will be turned off for any block that has
more than the specified number of statements. Use the MAXSTMT option - with a
reasonable limit to the number of statements - if you want the compiler to optimize
the code generated for a program and are willing for the compiler to optimize only
the reasonably sized blocks in that program.
──MAXSTMT──(──size──)──────────────────────────────────────────────────────────

When a large size is specified for MAXSTMT and some blocks have a large
number of statements, compilation may be aborted if there is not enough virtual
storage available.
The default for MAXSTMT is 4096.
MDECK
The MDECK option specifies that the preprocessor produces a copy of its output
either on the file defined by the SYSPUNCH DD statement under OS/390, or on the
.dek file under OS/390 UNIX.

┌─NOMDECK─┐

──┴─MDECK───┴──────────────────────────────────────────────────────────────────

ABBREVIATIONS: MD, NMD
The MDECK option allows you to retain the output from the preprocessor as a file
of 80-column records. This option is applicable only when the MACRO option is in
effect.
NAMES
The NAMES option specifies the extralingual characters that are allowed in
identifiers. Extralingual characters are those characters other than the 26
alphabetic, 10 digit, and special characters defined in PL/I Language Reference.
┌──
──────────────┐

──NAMES──(──'──extraling_char┴─'──┬─────────────────────────────────┬──)───────

│ ┌──
──────────────────┐ │
└──┬───┬─'──upp_extraling_char┴─'─┘
└─,─┘
extralingual_char
An extralingual character
upp_extraling_char
The extralingual character that you want interpreted as the uppercase version
of the corresponding character in the first suboption.
If you omit the second suboption, PL/I uses the character specified in the first
suboption as both the lowercase and the uppercase values. If you specify the
second suboption, you must specify the same number of characters as you specify
in the first suboption.
The default is NAMES('#@$' '#@$').
NAME
The NAME option specifies that the TEXT file created by the compiler will contain a
NAME record.
┌─NONAME─────────────────┐

──┴─NAME──┬──────────────┬─┴───────────────────────────────────────────────────

└─(──'name'──)─┘
ABBREVIATIONS: N
If no 'name' is specified as a suboption of the NAME option, then the 'name' used
is determined as follows
if there is a PACKAGE statement, the leftmost name on it is used
otherwise, the leftmost name on the first PROCEDURE statement is used
The length of the 'name' must not be greater than 8 characters if the
LIMITS(EXTNAME(n)) option is used with n <= 8.

NATLANG
The NATLANG option specifies the "language" for compiler messages, headers,
etc.
┌─ENU─┐

──NATLANG──(──┴─UEN─┴──)───────────────────────────────────────────────────────

ENU
All compiler messages, headers etc will be in mixedcase English.
UEN
All compiler messages, headers etc will be in uppercase English.
NEST
The NEST option specifies that the listing resulting from the SOURCE option
indicates the block level and the do-group level for each statement.
┌─NONEST─┐

──┴─NEST───┴───────────────────────────────────────────────────────────────────

NOT
The NOT option specifies up to seven alternate symbols that can be used as the
logical NOT operator.
┌──
──────┐

──NOT──(──'───char─┴─'──)──────────────────────────────────────────────────────

char
defined in PL/I Language Reference, except for the logical NOT symbol (¬).
When you specify the NOT option, the standard NOT symbol is no longer
recognized unless you specify it as one of the characters in the character string.
For example, NOT('˜') means that the tilde character, X'A1', will be recognized as
the logical NOT operator, and the standard NOT symbol, '¬', X'5F', will not be
recognized. Similarly, NOT('˜¬') means that either the tilde or the standard NOT
symbol will be recognized as the logical NOT operator.
The IBM-supplied default code point for the NOT symbol is X'5F'. The logical
NOT sign might appear as a logical NOT symbol (¬) or a caret symbol (^) on your
keyboard.

NUMBER
The number option specifies that statements in the source program are to be
identified by the line and file number of the file from which they derived and that
this pair of numbers is used to identify statements in the compiler listings resulting
from the AGGREGATE, ATTRIBUTES, LIST, MAP, OFFSET, SOURCE and XREF
options. The File Reference Table at the end of the listing shows the number
assigned to each of the input files read during the compilation.
┌─NUMBER───┐

──┴─NONUMBER─┴─────────────────────────────────────────────────────────────────

Note that if a preprocessor has been used, more than one line in the source listing
may be identified by the same line and file numbers. For example, almost every
EXEC CICS statement generates several lines of code in the source listing, but
these would all be identified by one line and file number.
Also note that in the pseudo-assembler listing produced by the LIST option, the file
number is left blank for the first file,and for all other files, the file number shown is
one less than the file number given in the File Reference Table.
The default is NUMBER.
OBJECT
The OBJECT option specifies that the compiler either creates an object module and
stores it in a data set defined by the DD statement with the name SYSLIN under
OS/390, or creates a .o file under OS/390 UNIX.
┌─OBJECT───┐

──┴─NOOBJECT─┴─────────────────────────────────────────────────────────────────

ABBREVIATIONS: OBJ, NOBJ
OFFSET
The OFFSET option specifies that the compiler is to print a table of line numbers
for each procedure and BEGIN block with their offset addresses relative to the
primary entry point of the procedure. This table can be used to identify a statement
from a run-time error message if the GONUMBER option is not used.
┌─NOOFFSET─┐

──┴─OFFSET───┴─────────────────────────────────────────────────────────────────

OPTIMIZE
The OPTIMIZE option specifies the type of optimization required:
┌─NOOPTIMIZE─┐

──┴─OPTIMIZE───┴──(──┬─TIME─┬──)───────────────────────────────────────────────

├─K────┤
└─2────┘
ABBREVIATIONS: OPT, NOPT

OPTIMIZE(TIME)
Optimizes the machine instructions generated to produce a more efficient
object program. This type of optimization can also reduce the amount of main
storage required for the object module.
It is strongly recommended that the DFT(REORDER) option be used with the
OPTIMIZE option. In fact, the effect of OPTIMIZE is severely limited for any
PROCEDURE or BEGIN-block for which all of the following are true:
The ORDER option applies to the block.

The block contains ON-units for hardware-detected conditions (such as
ZERODIVIDE).
The block has labels that are the (potential) target of branches out of those
ON-units.
The use of OPTIMIZE(TIME) could result in a substantial increase in compile

time over NOOPTIMIZE and a substantial increase in the space required. For
example, compiling a large program at OPT(TIME) might take several minutes
and could require a region of 75M or more.
During optimization the compiler can move code to increase run-time efficiency.
As a result, statement numbers in the program listing might not correspond to
the statement numbers used in run-time messages.
OPTIMIZE(0)
The equivalent of NOOPTIMIZE.
OPTIMIZE(2)
The equivalent of OPTIMIZE(TIME).
NOOPTIMIZE
Specifies fast compilation speed, but inhibits optimization.
For more information on choosing the best options to improve the performance of
your code, see Chapter 11, “Improving performance” on page 230.
OPTIONS
The OPTIONS option specifies that the compiler includes a list showing the
compiler options to be used during this compilation in the compiler listing.
┌─NOOPTIONS─┐

──┴─OPTIONS───┴────────────────────────────────────────────────────────────────

ABBREVIATIONS: OP, NOP
This list includes all options applied by default, those specified in the PARM
parameter of an EXEC statement or in the invoking command (pli), those specified
in a %PROCESS statement, those specified in the IBM_OPTIONS environment
variable under OS/390, and all those incorporated from any options file.

OR
The OR option specifies up to seven alternate symbols as the logical OR operator.
These symbols are also used as the concatenation operator, which is defined as
two consecutive logical OR symbols.
┌──
──────────────────┐

──OR────(──'──char──'──)─┴─────────────────────────────────────────────────────

Note: Do not code any blanks between the quotes.
The IBM-supplied default code point for the OR symbol (|) is X'4F'.
char
defined in the PL/I Language Reference, except for the standard logical OR symbol
(|).
If you specify the OR option, the standard OR symbol is no longer recognized

unless you specify it as one of the characters in the character string.
For example, OR('\') means that the backslash character, X'E0', will be
recognized as the logical OR operator, and two consecutive backslashes will be
recognized as the concatenation operator. The standard OR symbol, '|', X'4F',
will not be recognized as either operator. Similarly, OR('\|') means that either the
backslash or the standard OR symbol will be recognized as the logical OR
operator, and either symbol or both symbols can be used to form the concatenation
operator.
PP
The PP option specifies which (and in what order) preprocessors are invoked prior
to compilation.
┌─NOPP───────────────────────────────────────┐
│ ┌─┬───┬────────────────────────┐ │
│ │ └─,─┘ │ │

──┴─PP──(────pp-name──┬─────────────────┬─┴──)─┴───────────────────────────────

└─(──pp-string──)─┘
pp-name
The name given to a particular preprocessor. CICS, INCLUDE, MACRO and
SQL are the only preprocessors currently supported. Using an undefined name
causes a diagnostic error.
pp-string
A string, delimited by quotes, of up to 100 characters representing the options
for the corresponding preprocessor. For example, PP(MACRO('CASE(ASIS)'))
invokes the MACRO preprocessor with the option CASE(ASIS).
Preprocessor options are processed from left to right, and if two options conflict, the
last (rightmost) option is used. For example, if you invoke the MACRO
preprocessor with the option string 'CASE(ASIS) CASE(UPPER)', then the option
CASE(UPPER) is used.

The same preprocessor can be specified multiple times, and you can specify a
maximum of 31 preprocessor steps.
The MACRO option and the PP(MACRO) option both cause the macro facility to be
invoked prior to compilation. If both MACRO and PP(MACRO) are specified, the
macro facility is invoked twice.
For more discussion of the preprocessors, see Chapter 2, “PL/I preprocessors” on

page 62.
PPTRACE
The PPTRACE option specifies that, when a deck file is written for a preprocessor,
every nonblank line in that file is preceded by a line containing a %LINE directive.
The directive indicates the original source file and line to which the nonblank line
should be attributed.
┌─NOPPTRACE─┐

──┴─PPTRACE───┴────────────────────────────────────────────────────────────────

PREFIX
The PREFIX option enables or disables the specified PL/I conditions in the
compilation unit being compiled without your having to change the source program.
The specified condition prefixes are logically prefixed to the beginning of the first
PACKAGE or PROCEDURE statement.
──PREFIX──(──┬───────────────┬──)──────────────────────────────────────────────

│ ┌─┬───┬─────┐ │
│ │ └─,─┘ │ │
└───condition─┴─┘
condition
Any condition that can be enabled/disabled in a PL/I program, as explained in
PL/I Language Reference.
Default: PREFIX(CONVERSION FIXEDOVERFLOW INVALIDOP OVERFLOW

NOSIZE NOSTRINGRANGE NOSTRINGSIZE NOSUBSCRIPTRANGE
UNDERFLOW ZERODIVIDE)
PROCEED
The PROCEED option stops the compiler after processing by a preprocessor is
completed depending on the severity of messages issued by previous
preprocessors.
┌─NOPROCEED──┬─────────────┬─┐
│ │ ┌─S─┐ │ │
│ └─(──┼─W─┼──)─┘ │
│ └─E─┘ │

──┴─PROCEED────────────────────┴───────────────────────────────────────────────

ABBREVIATIONS: PRO, NPRO

PROCEED
Is equivalent to NOPROCEED(S).
NOPROCEED
Ends the processing after the preprocessor has finished compiling.
NOPROCEED(S)
The invocation of preprocessors and the compiler does not continue if a severe
or unrecoverable error is detected in this stage of preprocessing.
NOPROCEED(E)
The invocation of preprocessors and the compiler does not continue if an error,
severe error, or unrecoverable error is detected in this stage of preprocessing.
NOPROCEED(W)
The invocation of preprocessors and the compiler does not continue if a
warning, error, severe error, or unrecoverable error is detected in this stage of
preprocessing.
REDUCE
The REDUCE option specifies that the compiler is permitted to reduce an
assignment of a null string to a structure into a simple copy operation - even if that
means padding bytes might be overwritten.
┌─REDUCE───┐

──┴─NOREDUCE─┴─────────────────────────────────────────────────────────────────

The NOREDUCE option specifies that the compiler must decompose an

assignment of a null string to a structure into a series of assignments of the null
string to the base members of the structure.
The REDUCE option will cause less executable code to be generated for an
assignment of a null string to a structure, and that will usually mean your code will
run much faster. However, under the REDUCE option, any assignment of a null
string to a structure that is reduced to a simple copy will also cause any padding
bytes in that structure to be filled with '00'x.
For instance, in the following structure, there is one byte of padding between
field11 and field12.
dcl
1 struc,
5 field1K bin fixed(31),
5 field11 dec fixed(13)
5 field12 bin fixed(15),
5 field13 char(2);
Under the NOREDUCE option, the assignment struc = ''; will cause four
assignments to be generated, but the padding byte will be unchanged. However,
under the REDUCE option, the assigment would be reduced to one simple copy (a
MVC), but the padding byte will be set to a '00'x.

RENT
┌─NORENT─┐

──┴─RENT───┴───────────────────────────────────────────────────────────────────

Your code is "naturally reentrant" if it does not alter any of its static variables.
The RENT option specifies that the compiler is to take code that is not naturally
reentrant and make it reentrant. Refer to the OS/390 Language Environment
Programming Guide for a detailed description of reentrancy. If you use the RENT
option, the Linkage Editor cannot directly process the object module that is
produced: you must use either the binder or the prelinker.
The NORENT option specifies that the compiler is not to specifically generate
reentrant code from non-reentrant code. Any naturally reentrant code remains
reentrant.
If you use the RENT option, then when you link FETCHABLE modules, you must
specify DYNAM=DLL on the link step.
If you use the RENT option and CICS 4.1 or earlier, then since CICS 4.1 doesn't
support the new Program Object format created by the binder, you must link your
application via the prelinker.
Note that independent of whether you specify RENT or NORENT, for all
FETCHABLE modules, either you must specify OPTION(FETCHABLE) on the
procedure statement of the entry point to be FETCHed or you must link the module
with an apropriate ENTRY card.
If you specify the options NORENT and LIMITS(EXTNAME(n)) (with n <= 7), then
the text decks generated by the compiler will have the same format as those
generated by the older PL/I compilers. This means that the prelinker would not be
needed to create a PDS-style load module. If you use any other options, you must
use either the prelinker or PDSE's.
The code generated under the NORENT option may not be reentrant unless the
NOWRITABLE option is also specified.
The use of the NORENT does preclude the use of some features of the compiler.
In particular:
DLLs cannot be built
reentrant, writeable static is not supported
a STATIC ENTRY VARIABLE cannot have an INITIAL value
You may mix RENT and NORENT code subject to the following restrictions:
code compiled with RENT cannot be mixed with code compiled with NORENT if
they share any EXTERNAL STATIC variables
code compiled with RENT cannot call an ENTRY VARIABLE set in code
compiled with NORENT
code compiled with RENT cannot call an ENTRY CONSTANT that was
FETCHed in code compiled with NORENT

code compiled with RENT can FETCH a module containing code compiled with
NORENT if one of the following is true
– all the code in the FETCHed module was compiled with NORENT
– the code containing the entry point to the module was compiled with RENT
code compiled with NORENT code cannot FETCH a module containing any
code compiled with RENT
code compiled with NORENT WRITABLE cannot be mixed with code compiled
with NORENT NOWRITABLE if they share any external CONTROLLED
variables or any external FILEs
Given the above restrictions, the following is still valid:

a NORENT routine, called say mnorent, statically links and calls a RENT
routine, called say mrent
the RENT routine mrent then FETCHes and CALLs a separately-linked module
with an entry point compiled with RENT
RESPECT
The RESPECT option causes the compiler to honor any specification of the DATE
attribute and to apply the DATE attribute to the result of the DATE built-in function.
──RESPECT──(──┬──────┬──)──────────────────────────────────────────────────────

└─DATE─┘
Using the default, RESPECT(), causes the compiler to ignore any specification of the
DATE attribute and ensures that the compiler does not apply the DATE attribute to
the result of the DATE built-in function.
RULES
The RULES option allows or disallows certain language capabilities and lets you
choose semantics when alternatives are available. It can help you diagnose
common programming errors.

┌─┬───┬────────────────┐
│ └─,─┘ │
│ ┌─IBM─┐ │

──RULES──(────┬─┴─ANS─┴──────────┬─┴──)────────────────────────────────────────

│ ┌─BYNAME───┐ │
├─┴─NOBYNAME─┴─────┤
│ ┌─GOTO───┐ │
├─┴─NOGOTO─┴───────┤
│ ┌─NOLAXBIF─┐ │
├─┴─LAXBIF───┴─────┤
│ ┌─NOLAXCTL─┐ │
├─┴─LAXCTL───┴─────┤
│ ┌─LAXDCL───┐ │
├─┴─NOLAXDCL─┴─────┤
│ ┌─LAXIF───┐ │
├─┴─NOLAXIF─┴──────┤
│ ┌─LAXLINK───┐ │
├─┴─NOLAXLINK─┴────┤
│ ┌─LAXMARGINS───┐ │
├─┴─NOLAXMARGINS─┴─┤
│ ┌─LAXPUNC───┐ │
├─┴─NOLAXPUNC─┴────┤
│ ┌─LAXQUAL───┐ │
├─┴─NOLAXQUAL─┴────┤
│ ┌─NOLAXSTRZ─┐ │
├─┴─LAXSTRZ───┴────┤
│ ┌─MULTICLOSE───┐ │
└─┴─NOMULTICLOSE─┴─┘
IBM | ANS
Under the IBM suboption:
For operations requiring string data, data with the BINARY attribute is
converted to BIT.
Conversions in arithmetic operations or comparisons occur as described in
the PL/I Language Reference.
Conversions for the ADD, DIVIDE, MULTIPLY, and SUBTRACT built-in
functions occur as described in the PL/I Language Reference except that
operations specified as scaled fixed binary are evaluated as scaled fixed
decimal.
Nonzero scale factors are permitted in FIXED BIN declares.
If the result of any precision-handling built-in function (ADD, BINARY, etc.)
has FIXED BIN attributes, the specified or implied scale factor can be
nonzero.
Even if all arguments to the MAX or MIN built-in functions are UNSIGNED
FIXED BIN, the result is always SIGNED.
Even when you add, multiply, or divide two UNSIGNED FIXED BIN
operands, the result has the SIGNED attribute.
Even when you apply the MOD or REM built-in functions to two
UNSIGNED FIXED BIN operands, the result has the SIGNED attribute.
Under the ANS suboption:
For operations requiring string data, data with the BINARY attribute is
converted to CHARACTER.
Conversions in arithmetic operations or comparisons occur as described in
the PL/I Language Reference.

Conversions for the ADD, DIVIDE, MULTIPLY, and SUBTRACT built-in
functions occur as described in the PL/I Language Reference.
Nonzero scale factors are not permitted in FIXED BIN declares.
If the result of any precision-handling built-in function (ADD, BINARY, etc.)
has FIXED BIN attributes, the specified or implied scale factor must be
zero.
If all arguments to the MAX or MIN built-in functions are UNSIGNED FIXED
BIN, the result is UNSIGNED.
When you add, multiply or divide two UNSIGNED FIXED BIN operands,
the result has the UNSIGNED attribute.
When you apply the MOD or REM built-in functions to two UNSIGNED
FIXED BIN operands, the result has the UNSIGNED attribute.
Also, under RULES(ANS), the following errors, which the old compilers ignored,
will produce E-level messages
Specifying a string constant as the argument to the STRING built-in

Giving too many asterisks as subscripts in an array reference
Qualifying a CONTROLLED variable with a POINTER reference (as if the
CONTROLLED variable were BASED)
BYNAME | NOBYNAME
Specifying NOBYNAME causes the compiler to flag all BYNAME assignments
with an E-level message.
GOTO|NOGOTO
Specifying NOGOTO causes all GOTO statements to be flagged.
LAXBIF | NOLAXBIF
Specifying LAXBIF causes the compiler to build a contextual declaration for
built-in functions, such as NULL, even when used without an empty parameter
list.
LAXCTL | NOLAXCTL
Specifying LAXCTL allows a CONTROLLED variable to be declared with a
constant extent and yet to be allocated with a differing extent. NOLAXCTL
requires that if a CONTROLLED variable is to be allocated with a varying
extent, then that extent must be specified as an asterisk or as a non-constant
expression.
The following code is illegal under NOLAXCTL:
dcl a bit(8) ctl;
alloc a;
alloc a bit(16);
But this code would still be valid under NOLAXCTL:
dcl b bit(n) ctl;
dcl n fixed bin(31) init(8);
alloc b;
alloc b bit(16);

LAXDCL | NOLAXDCL
Specifying LAXDCL allows implicit declarations. NOLAXDCL disallows all
implicit and contextual declarations except for BUILTINs and for files SYSIN
and SYSPRINT.
LAXIF | NOLAXIF
Specifying LAXIF allows IF, WHILE, UNTIL, and WHEN clauses to evaluate to
other than BIT(1) NONVARYING. NOLAXIF allows IF, WHILE, UNTIL, and
WHEN clauses to evaluate to only BIT(1) NONVARYING.
The following are illegal under NOLAXIF:
dcl i fixed bin;
dcl b bit(8);
..
.
if i then ...
if b then ...
LAXLINK | NOLAXLINK
Specifying LAXLINK causes the compiler to ignore the LINKAGE and other
options specified in the declarations of two ENTRY variables or constants when
you assign or compare one with the other.
Under RULES(NOLAXLINK), the following errors will also be flagged with
E-level messages:
Using RETURN without an expression in a procedure with the RETURNS

option
Using RETURN with an expression in a procedure without the RETURNS
option
Assigning or comparing ENTRYs with parameter and returns description
that do not match
Declaring a variable as BUILTIN when its name is not that of a built-in
function (as long as the variable is not used - if it is used, an S-level
message will be generated even under the option RULES(LAXLINK))
LAXMARGINS | NOLAXMARGINS
Specifying NOLAXMARGINS causes the compiler to flag any line containing
non-blank characters after the right margin. This can be useful in detecing
code, such as a closing comment, that has accidentally been pushed out into
the right margin.
LAXPUNC | NOLAXPUNC
Specifying NOLAXPUNC causes the compiler to flag with an E-level message
any place where it assumes punctuation that is missing.
For instance, given the statement "I = (1 * (2);", the compiler assumes that a
closing right parenthesis was meant before the semicolon. Under
RULES(NOLAXPUNC), this statement would be flagged with an E-level
message; otherwise it would be flagged with a W-level message.
LAXQUAL | NOLAXQUAL
Specifying NOLAXQUAL causes the compiler to flag any reference to structure
members that are not level 1 and are not dot qualified. Consider the following
example:

dcl
1 a,
2 b fixed bin,
2 c fixed bin;
c = 15; /] would be flagged ]/

a.c = 15; /] would not be flagged ]/
LAXSTRZ | NOLAXSTRZ
Specifying LAXSTRZ causes the compiler not to flag any bit or character
variable that is initialized to or assigned a constant value that is too long if the
excess bits are all zeros (or if the excess characters are all blank).
MULTICLOSE | NOMULTICLOSE
NOMULTICLOSE causes the compiler to flag all statements that force the
closure of multiple groups of statement with an E-level message.
Default: RULES (IBM BYNAME GOTO NOLAXBIF NOLAXCTL LAXDCL LAXIF

LAXLINK LAXPUNC LAXMARGINS LAXQUAL NOLAXSTRZ MULTICLOSE)
SEMANTIC
The SEMANTIC option specifies that the execution of the compiler's semantic
checking stage depends on the severity of messages issued prior to this stage of
processing.
┌───NOSEMANTIC────┬─────────────┬─┐
│ │ ┌─S─┐ │ │
│ └─(──┼─W─┼──)─┘ │
│ └─E─┘ │

──┴─SEMANTIC────────────────────────┴──────────────────────────────────────────

ABBREVIATIONS: SEM, NSEM
SEMANTIC
Equivalent to NOSEMANTIC(S).
NOSEMANTIC
Processing stops after syntax checking. No semantic checking is performed.
NOSEMANTIC (S)
No semantic checking is performed if a severe error or an unrecoverable error
has been encountered.
NOSEMANTIC (E)
No semantic checking is performed if an error, a severe error, or an
unrecoverable error has been encountered.
NOSEMANTIC (W)
No semantic checking is performed if a warning, an error, a severe error, or an
unrecoverable error has been encountered.
Semantic checking is not performed if certain kinds of severe errors are found. If
the compiler cannot validate that all references resolve correctly (for example, if
built-in function or entry references are found with too few arguments) the suitability
of any arguments in any built-in function or entry reference is not checked.

SERVICE
The SERVICE option places a string in the object module, if generated. This string
is loaded into memory with any load module into which this object is linked, and if
the LE dump includes a traceback, this string will be included in that traceback.
┌─NOSERVICE───────────────────────┐

──┴─SERVICE──(──'service string'──)─┴──────────────────────────────────────────

ABBREVIATIONS: SERV, NOSERV
The string is limited to 64 characters in length.
To ensure that the string remains readable across locales, only characters from the
invariant character set should be used.
SOURCE
The SOURCE option specifies that the compiler includes a listing of the source
program in the compiler listing. The source program listed is either the original
source input or, if any preprocessors were used, the output from the last
preprocessor.
┌─NOSOURCE─┐

──┴─SOURCE───┴─────────────────────────────────────────────────────────────────

ABBREVIATIONS: S, NS
SPILL
The SPILL option specifies the size of the spill area to be used for the compilation.
When too many registers are in use at once, the compiler dumps some of the
registers into temporary storage that is called the spill area.
──SPILL──(──size──)────────────────────────────────────────────────────────────

ABBREVIATIONS: SP
If you have to expand the spill area, you will receive a compiler message telling you
the size to which you should increase it. Once you know the spill area that your
source program requires, you can specify the required size (in bytes) as shown in
the syntax diagram above. The maximum spill area size is 3900. Typically, you will
need to specify this option only when compiling very large programs with
OPTIMIZE.
STDSYS
The STDSYS option specifies that the compiler should cause the SYSPRINT file to
be equated to the C stdout file.
┌─NOSTDSYS─┐

──┴─STDSYS───┴─────────────────────────────────────────────────────────────────


Using the STDSYS option may make it easier to develop and debug a mixed PL/I
and C application.
STMT
The STMT option specifies that statements in the source program are to be
counted and that this "statement number" is used to identify statements in the
compiler listings resulting from the AGGREGATE, ATTRIBUTES, SOURCE and
XREF options.
┌─NOSTMT─┐

──┴─STMT───┴───────────────────────────────────────────────────────────────────

The default is NOSTMT.
When the STMT option is specified, the source listing will include both the logical
statement numbers and the source file numbers.
Note that there is no GOSTMT option. The only option that will produce
information at run-time identifying where an error has occurred is the GONUMBER
option. Also note that when the GONUMBER option is used, the term "statement"
in the run-time error messages will refer to line numbers as used by the NUMBER
compiler option - even if the STMT option was in effect.
STORAGE
The STORAGE option determines whether or not the compiler flags statements
using an excessive amount of storage for compiler-generated temporaries.
┌─NOSTORAGE──────────────┐

──┴─STORAGE──┬───────────┬─┴───────────────────────────────────────────────────

└─(──max──)─┘
ABBREVIATIONS: STG, NSTG
max
The limit for the number of bytes that can be used for compiler-generated
temporaries. The compiler flags any statement that uses more bytes than
those specified by max. The default for max is 1000.
You should examine statements that are flagged under this option - if you code
them differently, you may be able to reduce the amount of stack storage required
by your code.
SYNTAX
The SYNTAX option specifies that the compiler continues into syntax checking after
preprocessing when you specify the MACRO option, unless an unrecoverable error
has occurred. Whether the compiler continues with the compilation depends on the
severity of the error, as specified by the NOSYNTAX option.

┌───NOSYNTAX────┬─────────────┬─┐
│ │ ┌─S─┐ │ │
│ └─(──┼─W─┼──)─┘ │
│ └─E─┘ │

──┴─SYNTAX────────────────────────┴────────────────────────────────────────────

ABBREVIATIONS: SYN, NSYN
SYNTAX
Continues syntax checking after preprocessing unless a severe error or an
unrecoverable error has occurred. SYNTAX is equivalent to NOSYNTAX(S).
NOSYNTAX
Processing stops unconditionally after preprocessing.
NOSYNTAX(W)
No syntax checking if a warning, error, severe error, or unrecoverable error is
detected.
NOSYNTAX(E)
No syntax checking if the compiler detects an error, severe error, or
unrecoverable error.
NOSYNTAX(S)
No syntax checking if the compiler detects a severe error or unrecoverable
error.
If the NOSYNTAX option terminates the compilation, no cross-reference listing,

attribute listing, or other listings that follow the source program is produced.
You can use this option to prevent wasted runs when debugging a PL/I program
that uses the preprocessor.
If the NOSYNTAX option is in effect, any specification of the CICS preprocessor via
the CICS, XOPT or XOPTS options will be ignored. This allows the MACRO
preprocessor to be invoked before invoking the CICS translator.
SYSPARM
The SYSPARM option allows you to specify the value of the string that is returned
by the macro facility built-in function SYSPARM.
──SYSPARM──(──'string'──)──────────────────────────────────────────────────────

string
Can be up to 64 characters long. A null string is the default.
For more information about the macro facility, see PL/I Language Reference.
SYSTEM
The SYSTEM option specifies the format used to pass parameters to the MAIN PL/I
procedure, and generally indicates the host system under which the program runs.

┌─MVS──┐

──SYSTEM──(──┼─CICS─┼──)───────────────────────────────────────────────────────

├─IMS──┤
├─OS───┤
└─TSO──┘
Table 4 shows the type of parameter list you can expect, and how the program
runs under the specified host system. It also shows the implied settings of
NOEXECOPS. Your MAIN procedure must receive only those types of parameter
lists that are indicated as valid in this table. Additional run-time information for the
SYSTEM option is provided in OS/390 Language Environment Programming Guide.
.
Table 4. SYSTEM option table

SYSTEM option Type of parameter list Program runs as NOEXECOPS
implied
SYSTEM(MVS) Single varying OS/390 application NO
character string or no program
parameters.
Otherwise, arbitrary YES
parameter list.
SYSTEM(CICS) Pointer(s) CICS transaction YES
SYSTEM(IMS) Pointer(s) IMS application YES
program
SYSTEM(OS) USS parameter list USS application YES
program
SYSTEM(TSO) Pointer to CCPL TSO command YES
processor
Under SYSTEM(IMS), all pointers are presumed to be passed BYVALUE, but under
SYSTEM(MVS) they are presumed to be passed BYADDR.
TERMINAL
The TERMINAL option determines whether or not diagnostic and information
messages produced during compilation are displayed on the terminal.
┌─TERMINAL───┐

──┴─NOTERMINAL─┴───────────────────────────────────────────────────────────────

ABBREVIATIONS: TERM, NTERM
TERMINAL
Messages are displayed on the terminal.
NOTERMINAL
No information or diagnostic compiler messages are displayed on the terminal.

TEST
The TEST option specifies the level of testing capability that the compiler generates
as part of the object code. It allows you to control the location of test hooks and to
control whether or not the symbol table will be generated.
┌─NOTEST──────────────────────────────────────────┐

──┴─TEST──┬───────────────────────────────────────┬─┴──────────────────────────

│ ┌─ALL───┐ │
└─(──┬─┼─NONE──┼──┬──────────────┬─┬──)─┘
│ ├─BLOCK─┤ │ ┌─SYM───┐ │ │
│ ├─STMT──┤ └─,──┴─NOSYM─┴─┘ │
│ └─PATH──┘ │
│ ┌─SYM───┐ │
└─┴─NOSYM─┴──┬──────────────┬─┘
│ ┌─ALL───┐ │
└─,──┼─NONE──┼─┘
├─BLOCK─┤
├─STMT──┤
└─PATH──┘
STMT
Inserts hooks at statement boundaries and block boundaries. STMT generates
a statement table.
PATH
Tells the compiler to insert hooks:
Before the first statement enclosed by an iterative DO statement

Before the first statement of the true part of an IF statement
Before the first statement of the false part of an IF statement
Before the first statement of a true WHEN or OTHERWISE statement of a
SELECT group
Before the statement following a user label
At CALLs or function references - both before and after control is passed to
the routine
At block boundaries
When PATH is specified, the compiler generates a statement table.
BLOCK
Tells the compiler to insert hooks at block boundaries (block entry and block
exit).
ALL
Inserts hooks at all possible locations and generates a statement table.
Note: Under opt(2), hooks are set only at block boundaries.
NONE
No hooks are put into the program.
SYM
Creates a symbol table that allows you to examine variables by name.

NOSYM
No symbol table is generated.
NOTEST
Suppresses the generation of all testing information.
Any TEST option other than NOTEST and TEST(NONE,NOSYM) will automatically
provide the attention interrupt capability for program testing.
If the program has an ATTENTION ON-unit that you want invoked, you must
compile the program with either of the following:
The INTERRUPT option
A TEST option other than NOTEST or TEST(NONE,NOSYM)
Note: ATTENTION is supported only under TSO.
The TEST option will imply GONUMBER.
Because the TEST option can increase the size of the object code and can affect
performance, you might want to limit the number and placement of hooks.
If the TEST option is specified, no inlining will occur.
Structures with REFER are supported in the symbol table only if the REFER usage
is "simple" - this means the REFER must occur on an item where
the item must have logical level 2
the item must not itself be a structure, and
the item must be either a char string or an array of numerics or pointers where
all but the upper bound of the first dimension is constant
If TEST(SYM) is in effect, tables will be generated to enable the AutoMonitor

feature of DebugTool. These tables may substantially increase the size of the
object module. Under Automonitor, the value of variables used in a statement will
be displayed before the statement executes - as long as the variable has
computational type or has the attribute POINTER, OFFSET or HANDLE. The target
in an assignment will not be shown unless it is also used as part of the source in
the assignment.
TUNE
The TUNE option specifies the architecture for which the executable program will
be optimized. This option allows the optimizer to take advantage of architectural
differences such as scheduling of instructions.
┌─3─┐

──TUNE──(──┴─n─┴──)────────────────────────────────────────────────────────────

Note: If TUNE level is lower than ARCH, TUNE is forced to ARCH.
The current values that may be specified for the TUNE level are:
0 Generates code that is executable on all models, but that does not take
advantage of any architectural differences.

1 Generates code that is executable on all models but is optimized for the
models specified under ARCH(1).
USAGE
The USAGE option lets you choose IBM or ANS semantics for selected built-in
functions.
┌─┬───┬─────────────────────┐
│ └─,─┘ │
│ ┌─IBM─┐ │

──USAGE──(────┬─ROUND──(──┴─ANS─┴──)──┬─┴──)───────────────────────────────────

│ ┌─IBM─┐ │
└─UNSPEC──(──┴─ANS─┴──)─┘
ROUND( IBM | ANS )

Under the ROUND(IBM) suboption, the second argument to the ROUND built-in
function is ignored if the first argument has the FLOAT attribute.
Under the ROUND(ANS) suboption, the ROUND built-in function is
implemented as described in the PL/I Language Reference.
UNSPEC( IBM | ANS )

Under the UNSPEC(IBM) suboption, UNSPEC cannot be applied to a structure
and, if applied to an array, returns an array of bit strings.
Under the UNSPEC(ANS) suboption, UNSPEC can be applied to structures
and, when applied to a structure or an array, UNSPEC returns a single bit
string.
Default: USAGE( ROUND(IBM) UNSPEC(IBM) )
WIDECHAR
The WIDECHAR option specifies the format in which WIDECHAR data will be
stored.
┌─BIGENDIAN────┐

──WIDECHAR──(──┴─LITTLEENDIAN─┴──)─────────────────────────────────────────────

BIGENDIAN
Indicates that WIDECHAR data will be stored in bigendian format. For
instance, the WIDECHAR value for the UTF-16 character '1' will be stored as
'0031'x.
LITTLEENDIAN
Indicates that WIDECHAR data will be stored in littleendian format. For
instance, the WIDECHAR value for the UTF-16 character '1' will be stored as
'3100'x.

WX constants should always be specified in bigendian format. Thus the value '1'
should always be specified as '0031'wx, even if under the
WIDECHAR(LITTLEENDIAN) option, it is stored as '3100'x.
WINDOW
The WINDOW option sets the value for the w window argument used in various
date-related built-in functions.
┌─195#─┐

──WINDOW──(──┴─w────┴──)───────────────────────────────────────────────────────

w Either an unsigned integer that represents the start of a fixed window or a

negative integer that specifies a “sliding” window. For example, WINDOW(-2K)
indicates a window that starts 20 years prior to the year when the program
runs.
WRITABLE
The WRITABLE option specifies that the compiler may treat static storage as
writable (and if it does, this would make the resultant code non-reentrant).
┌─WRITABLE───┐

──┴─NOWRITBALE─┴───────────────────────────────────────────────────────────────

This option has no effect on programs compiled with the RENT option.
The NORENT WRITABLE options allow the compiler to use a static pointer
as the base for the stack that tracks a CONTROLLED variable
as the handle for the storage that represents a FILE
So, under the NORENT WRITABLE options, a module using CONTROLLED

variables or performing I/O would not be reentrant.
Under the NORENT NOWRITABLE options, an application may not perform as well
as if it were compiled with the RENT or WRITABLE options if the application
uses CONTROLLED variables
assigns FILE CONSTANTs to FILE VARIABLEs
The performance of an application under NORENT NOWRITABLE may be

especially bad if it uses many CONTROLLED variables in many PROCEDUREs.
Code compiled with NORENT WRITABLE cannot be mixed with code compiled with
NORENT NOWRITABLE if they share any external CONTROLLED variables. In
general, you should avoid mixing code compiled with WRITABLE with code
compiled with NOWRITABLE.

XINFO
The XINFO option specifies that the compiler should generate additional files with
extra information about the current compilation unit.
┌─┬───┬─────────┐
│ └─,─┘ │
│ ┌─NODEF─┐ │

──XINFO──(────┬─┴─DEF───┴─┬─┴──)───────────────────────────────────────────────

│ ┌─NOXML─┐ │
└─┴─XML───┴─┘
DEF
A definition side-deck file is created. This file lists, for the compilation unit, all:
defined EXTERNAL procedures

defined EXTERNAL variables
statically referenced EXTERNAL routines and variables
dynamically called FETCHED modules
Under batch, this file is written to the file specified by the SYSDEFSD DD
statement. Under Unix Systems Services, this file is written to the same
directory as the object deck and has the extension "def".
For instance, given the program:
defs: proc;
dcl (b,c) ext entry;
dcl x ext fixed bin(31) init(1729);
dcl y ext fixed bin(31) reserved;
call b(y);
fetch c;
call c;
end;
The following def file would be produced:
EXPORTS CODE
DEFS
EXPORTS DATA
X
IMPORTS
B
Y
FETCH
C
The def file can be used to be build a dependency graph or cross-reference
analysis of your application.
NODEF
No definition side-deck file is created.
XML
An XML side-file is created. This XML file includes:
the file reference table for the compilation

the block structure of the program compiled

the messages produced during the compilation
Under batch, this file is written to the file specified by the SYSXMLSD DD
statement. Under Unix Systems Services, this file is written to the same
directory as the object deck and has the extension "xml".
The DTD file for the XML produced is:
<?xml encoding="UTF-8"?>
<!ELEMENT compilation ((procedure)],(message)],FileReferenceTable)>

<!ELEMENT procedure (blockFile,blockLine,(procedure)],(beginBlock)])>
<!ELEMENT beginBlock (blockFile,blockLine,(procedure)],(beginBlock)])>
<!ELEMENT message (msgNumber,msgLine?,msgFile?,msgText)>
<!ELEMENT File (FileNumber,IncludedFromFile?,IncludedOnLine?,FileName)>
<!ELEMENT FileReferenceTable (FileCount,File+)>
<!ELEMENT blockFile (#PCDATA)>

<!ELEMENT blockLine (#PCDATA)>
<!ELEMENT msgNumber (#PCDATA)>
<!ELEMENT msgLine (#PCDATA)>
<!ELEMENT msgFile (#PCDATA)>
<!ELEMENT msgText (#PCDATA)>
<!ELEMENT FileCount (#PCDATA)>
<!ELEMENT FileNumber (#PCDATA)>
<!ELEMENT FileName (#PCDATA)>
<!ELEMENT IncludedFromFile (#PCDATA)>
<!ELEMENT IncludedOnLine (#PCDATA)>
NOXML
No XML side-file is created.
XREF
The XREF option provides a cross-reference table of names used in the program
together with the numbers of the statements in which they are declared or
referenced in the compiler listing.
┌─NOXREF────────────────────────┐

──┴───XREF────┬─────────────────┬─┴────────────────────────────────────────────

│ ┌─FULL──┐ │
└─(──┴─SHORT─┴──)─┘
ABBREVIATIONS: X, NX
FULL
Includes all identifiers and attributes in the compiler listing.
SHORT
Omits unreferenced identifiers from the compiler listing.
The only names not included in the cross reference listing created when using the
XREF option are label references on END statements. For example, assume that
statement number 20 in the procedure PROC1 is END PROC1;. In this situation,
statement number 20 does not appear in the cross reference listing for PROC1.)

If you specify both the XREF and ATTRIBUTES options, the two listings are
combined. If there is a conflict between SHORT and FULL, the usage is
determined by the last option specified. For example, ATTRIBUTES(SHORT)
XREF(FULL) results in the FULL option for the combined listing.
For a description of the format and content of the cross-reference table, see
“Cross-reference table” on page 57.
For more information about sorting identifiers and storage requirements with
DBCSOS, see “ATTRIBUTE and cross-reference table” on page 56.
Specifying options in the %PROCESS or *PROCESS statements

You can use either %PROCESS or *PROCESS in your program; they are equally
acceptable. For consistency and readability in this book, we will always refer to
%PROCESS but you can use either %PROCESS or *PROCESS whenever this
statement is used.
The %PROCESS statement identifies the start of each external procedure and
allows compiler options to be specified for each compilation. The options you
specify in adjacent %PROCESS statements apply to the compilation of the source
statements to the end of input, or the next %PROCESS statement.
To specify options in the %PROCESS statement, code as follows:

%PROCESS options;
where options is a list of compiler options. You must end the list of options with a
semicolon, and the options list should not extend beyond the default right-hand
source margin. The percent sign (%) or asterisk (*) must appear in the first column
of the record. The keyword PROCESS can follow in the next byte (column) or after
any number of blanks. You must separate option keywords by a comma or at least
one blank.
The number of characters is limited only by the length of the record. If you do not
wish to specify any options, code:
%PROCESS;
If you find it necessary to continue the %PROCESS statement onto the next record,
terminate the first part of the list after any delimiter, and continue on the next
record. You cannot split keywords or keyword arguments across records. You can
continue a %PROCESS statement on several lines, or start a new %PROCESS
statement. An example of multiple adjacent %PROCESS statements is as follows:
%PROCESS INT F(I) AG A(F) OP STG NEST X(F) SOURCE ;
%PROCESS LIST TEST ;
Compile-time options, their abbreviated syntax, and their IBM-supplied defaults are
shown in Table 3 on page 3.

Using % statements
Statements that direct the operation of the compiler begin with a percent (%)
symbol. % statements allow you to control the source program listing and to
include external strings in the source program. % statements must not have label
or condition prefixes and cannot be a unit of a compound statement. You should
place each % statement on a line by itself.
The usage of each % control statement—%INCLUDE, %PRINT, %NOPRINT,

%OPTION, %PAGE, %POP, %PUSH, and %SKIP—is listed below. For a
complete description of these statements, see PL/I Language Reference.
%INCLUDE Directs the compiler to incorporate external strings of characters
and/or graphics into the source program.
%PRINT Directs the compiler to resume printing the source and insource
listings.
%NOPRINT Directs the compiler to suspend printing the source and insource
listings until a %PRINT statement is encountered.
%OPTION Specifies one of a selected subset of compiler options for a
segment of source code.
%PAGE Directs the compiler to print the statement immediately after a
%PAGE statement in the program listing on the first line of the next
page.
%POP Directs the compiler to restore the status of the %PRINT,
%NOPRINT, and %OPTION saved by the most recent %PUSH.
%PUSH Saves the current status of the %PRINT, %NOPRINT, and
%OPTION in a push down stack on a last-in, first-out basis.
%SKIP Specifies the number of lines to be skipped.
Using the %INCLUDE statement

%INCLUDE statements are used to include additional PL/I files at specified points
in a compilation unit. The PL/I Language Reference describes how to use the
%INCLUDE statement to incorporate source text from a library into a PL/I program.
For an OS/390 environment
A library is an OS/390 partitioned data set that can be used to store other
data sets called members. Source text that you might want to insert into a
PL/I program using a %INCLUDE statement must exist as a member within a
library. “Source Statement Library (SYSLIB)” on page 106 further describes
the process of defining a source statement library to the compiler.
The statement:
%INCLUDE DD1 (INVERT);
specifies that the source statements in member INVERT of the library defined
by the DD statement with the name DD1 are to be inserted consecutively into
the source program. The compilation job step must include appropriate DD
statements.
If you omit the ddname, the ddname SYSLIB is assumed. In such a case,
you must include a DD statement with the name SYSLIB. (The IBM-supplied

cataloged procedures do not include a DD statement with this name in the
compilation procedure step.)
For an OS/390 UNIX environment
The name of the actual include file must be lowercase, unless you specify
UPPERINC. For example, if you used the include statement %include
sample, the compiler would find the file sample.inc, but would not find the file
SAMPLE.inc. Even if you used the include statement %include SAMPLE, the
compiler would still look for sample.inc.
The compiler searches for include files in the following order:
1. Current directory
2. Directories specified with the -I flag or INCDIR compiler option
3. The /usr/include directory
The first file found by the compiler is included into your source.
A %PROCESS statement in source text included by a %INCLUDE statement

results in an error in the compilation.
Figure 1 shows the use of a %INCLUDE statement to include the source

statements for FUN in the procedure TEST. The library HPU8.NEWLIB is defined
in the DD statement with the qualified name PLI.SYSLIB, which is added to the
statements of the cataloged procedure for this job. Since the source statement
library is defined by a DD statement with the name SYSLIB, the %INCLUDE
statement need not include a ddname.
It is not necessary to invoke the preprocessor if your source program, and any text
to be included, does not contain any macro statements.
//OPT4#9 JOB
//STEP3 EXEC IBMZCBG,PARM.PLI='INC,S,A,X,NEST'
//PLI.SYSLIB DD DSN=HPU8.NEWLIB,DISP=OLD
//PLI.SYSIN DD ]
TEST: PROC OPTIONS(MAIN) REORDER;
DCL ZIP PIC '99999'; /] ZIP CODE ]/
DCL EOF BIT INIT('K'B);
ON ENDFILE(SYSIN) EOF = '1'B;
GET EDIT(ZIP) (COL(1), P'99999');
DO WHILE(¬EOF);
PUT SKIP EDIT(ZIP, CITYFUN(ZIP)) (P'99999', A(16));
GET EDIT(ZIP) (COL(1), P'99999');
END;
%PAGE;
%INCLUDE FUN;
END; /] TEST ]/
//GO.SYSIN DD ]
95141
95K3K
941K1
//
Figure 1. Including source statements from a library

Using the compiler listing
During compilation, the compiler generates a listing, most of which is optional, that
contains information about the source program, the compilation, and the object
module. The following description of the listing refers to its appearance on a
printed page.
Of course, if compilation terminates before reaching a particular stage of

processing, the corresponding listings do not appear.
Heading information
The first page of the listing is identified by the product number, the compiler version
number, and the date and the time compilation commenced. This page and
subsequent pages are numbered.
Near the end of the listing you will find either a statement that no errors or warning
conditions were detected during the compilation, or a message that one or more
errors were detected. The format of the messages is described under “Messages
and return codes” on page 60. The second to the last line of the listing shows the
CPU time taken for the compilation. The last line of the listing is END OF
COMPILATION OF xxxx. where xxxx is the external procedure name. If you
specify the NOSYNTAX compiler option, or the compiler aborts early in the
compilation, the external procedure name xxxx is not included and the line
truncates to END OF COMPILATION.
The following sections describe the optional parts of the listing in the order in which
they appear.
Options used for compilation

If you specify the OPTIONS option, a complete list of the options specified for the
compilation, including the default options, appears on the first pages.
The OPTIONS listing will start with a line showing the initial install options (those
are the options set at install time and which are applied before any other options).
Under USS, the next line would show the options set via the IBM_OPTIONS
environment variable. Then the listing will show any *PROCESS or %PROCESS
lines in the source. Finally the will end with a line showing the final install options
(those are the options set at install time and which are applied after any other
options).
The rest of the OPTIONS listing will show the settings of all the options finally in
effect during the compilation. If the setting of an option differs from the default
setting after the initial install options were applied, then that line will be marked with
a+
Preprocessor input
If you specify both the MACRO and INSOURCE options, the compiler lists input to
the preprocessor, one record per line, each line numbered sequentially at the left.
If the preprocessor detects an error, or the possibility of an error, it prints a

message on the page or pages following the input listing. The format of these
messages is the same as the format for the compiler messages described under
“Messages and return codes” on page 60.

SOURCE program
If you specify the SOURCE option, the compiler lists one record per line. If the
input records contain printer control characters, or %SKIP or %PAGE statements,
the lines are spaced accordingly. Use %NOPRINT and %PRINT statements to
stop and restart the printing of the listing.
If you specify the MACRO option, the source listing shows the included text in
place of the %INCLUDE statements in the primary input data set.
Statement nesting level

If you specify the NEST option, the block level and the DO-level are printed to the
right of the statement or line number under the headings LEV and NT respectively,
as in the following example:
Line.File LV NT
1.1 A: PROC OPTIONS(MAIN);
2.1 1 B: PROC;
3.1 2 DCL K(1K,1K) FIXED BIN (15);
4.1 2 DCL Y FIXED BIN (15) INIT (6);
5.1 2 DO I=1 TO 1K;
6.1 2 1 DO J=1 TO 1K;
7.1 2 2 K(I,J) = N;
8.1 2 2 END;
9.1 2 1 BEGIN;
1K.1 3 1 K(1,1)=Y;
11.1 3 1 END;
12.1 2 1 END B;
13.1 1 END A;
ATTRIBUTE and cross-reference table

If you specify the ATTRIBUTES option, the compiler prints an attribute table
containing a list of the identifiers in the source program together with their declared
and default attributes.
If you specify the XREF option, the compiler prints a cross-reference table
containing a list of the identifiers in the source program together with the file and
line numbers of the statements in which they appear.
If you specify both ATTRIBUTES and XREF, the two tables are combined. In these
tables, if you explicitly declare an identifier, the compiler will list file number and line
number of its DECLARE. Contextually declared variables are marked by +++++,
and other implicitly declared variables are marked by *****.
Attribute table
The compiler never includes the attributes INTERNAL and REAL. You can assume
them unless the respective conflicting attributes, EXTERNAL and COMPLEX,
appear.
For a file identifier, the attribute FILE always appears, and the attribute EXTERNAL
appears if it applies; otherwise, the compiler lists only explicitly declared attributes.
The compiler prints the dimension attribute for an array first. It prints the bounds as
in the array declaration, but expressions are replaced by asterisks unless they have

been reduced by the compiler to a constant, in which case the value of the
constant is shown.
For a character string, a bit string, a graphic string, or an area variable, the
compiler prints the length, as in the declaration, but expressions are replaced by
asterisks unless they have been reduced by the compiler to a constant, in which
case the value of the constant is shown.
Cross-reference table
If you combine the cross-reference table with the attribute table, the list of attributes
for a name is identified by file number and line number. An identifier appears in the
Sets: part of the cross-reference table if it is:
The target of an assignment statement
Used as a loop control variable in DO loops
Used in the SET option of an ALLOCATE or LOCATE statement
Used in the REPLY option of a DISPLAY statement
If you specify ATTRIBUTES and XREF, the two tables are combined.
If there are unreferenced identifiers, they are displayed in a separate table.
Aggregate length table

An aggregate length table is obtained by using the AGGREGATE option. The table
includes structures but not arrays that have non-constant extents, but the sizes and
offsets of elements within structures with non-constant extents may be inaccurate
or specified as *. For the aggregates listed, the table contains the following
information:
Where the aggregate is declared.
The name of the aggregate and each element within the aggregate.
The byte offset of each element from the beginning of the aggregate.
The length of each element.
The total length of each aggregate, structure, and substructure.
The total number of dimensions for each element.
Please be careful when interpreting the data offsets indicated in the data length
table. An odd offset does not necessarily represent a data element without
halfword, fullword, or even double word alignment. If you specify or infer the
aligned attribute for a structure or its elements, the proper alignment requirements
are consistent with respect to other elements in the structure, even though the table
does not indicate the proper alignment relative to the beginning of the table.
If there is padding between two structure elements, a /*PADDING*/ comment

appears, with appropriate diagnostic information.
Statement offset addresses

If the LIST compile option is used, the compiler includes a pseudo-assembler listing
in the compiler listing. This listing includes, for each instruction, the offset from the
primary entry point for the function to which it belongs. These offsets can be used
with the offset given in a run-time error message to determine the statement to
which the message applies.

The OFFSET option produces a table that gives for each statement, the offset of
the first instruction belonging to that statement.
In the example shown in Figure 2, the message indicates that the condition was
raised at offset +58 from the SUB1 entry. The compiler listing excerpt shows this
offset associated with line number 8. The run-time output from this erroneous
statement is shown if Figure 3 on page 59.
Compiler Source
Line.File
2.1 TheMain: proc options( main );
3.1 call sub1();
4.1 Sub1: proc;
5.1 dcl (i, j) fixed bin(31);
6.1
7.1 i = K;
8.1 j = j / i;
9.1 end Sub1;
1K.1 end TheMain;
. . .
OFFSET OBJECT CODE LINE# FILE# P S E U D O A S S E M B L Y L I S T I N G

KKKKKK KKKK2 | THEMAIN DS KD
. . .
KKKK4C 58KK C1F4 KKKK2 | L rK,_CEECAA_(,r12,5KK)

KKKK5K 5KKK DK98 KKKK2 | ST rK,#_CEECAACRENT_1(,r13,152)
KKKK54 581K DK98 KKKKK | L r1,#_CEECAACRENT_1(,r13,152)
KKKK58 582K 3K62 KKKKK | L r2,=Q(@STATIC)(,r3,98)
KKKK5C 4152 1KKK KKKKK | LA r5,=Q(@STATIC)(r2,r1,K)
KKKK6K 18BD KKKK3 | LR r11,r13
KKKK62 58KK DK98 KKKK3 | L rK,#_CEECAACRENT_1(,r13,152)
KKKK66 5KKK C1F4 KKKK3 | ST rK,_CEECAA_(,r12,5KK)
KKKK6A 58FK 3K66 KKKK3 | L r15,=A(SUB1)(,r3,1K2)
KKKK6E K5EF KKKK3 | BALR r14,r15
KKKK7K KKK1K | @1L1 DS KH
KKKK7K 581K 5KKK KKK1K | L r1,IBMQEFSH(,r5,K)
KKKK74 58FK 1KK8 KKK1K | L r15,&Func_&WSA(,r1,8)
KKKK78 58KK 1KKC KKK1K | L rK,&Func_&WSA(,r1,12)
KKKK7C 5KKK C1F4 KKK1K | ST rK,_CEECAA_(,r12,5KK)
KKKK8K K5EF KKK1K | BALR r14,r15
KKKK82 KKK1K | @1L4 DS KH
KKKK82 58KK DK98 KKKK2 | L rK,#_CEECAACRENT_1(,r13,152)
KKKK86 5KKK C1F4 KKKK2 | ST rK,_CEECAA_(,r12,5KK)
. . .
KKKKKK KKKK4 | SUB1 DS KD
. . .
KKKK48 41KK KKKK KKKK7 | LA rK,K

KKKK4C 5KKK DK98 KKKK7 | ST rK,I(,r13,152)
KKKK5K 584K DK9C KKKK8 | L r4,J(,r13,156)
KKKK54 8E4K KK2K KKKK8 | SRDA r4,32
KKKK58 1D4K KKKK8 | DR r4,rK
KKKK5A 18K5 KKKK8 | LR rK,r5
KKKK5C 5KKK DK9C KKKK8 | ST rK,J(,r13,156)
Figure 2. Finding statement number (compiler listing example)

Message :
IBMK3K1S ONCODE=32K The ZERODIVIDE condition was raised.

From entry point SUB1 at compile unit offset +KKKKKK58 at
address KD3K12CK.
Figure 3. Finding statement number (run-time message example)
Entry offsets given in dump and ON-unit SNAP error messages can be compared
with this table and the erroneous statement discovered. The statement is identified
by finding the section of the table that relates to the block named in the message
and then finding the largest offset less than or equal to the offset in the message.
The statement number associated with this offset is the one needed.
Storage offset listing

If the MAP compile option is used, the compiler includes a storage offset listing in
the compiler listing. This listing gives the location in storage of the following level-1
variables if they are used in the program:
AUTOMATIC
CONTROLLED except for PARAMETERs
STATIC excpet for ENTRY CONSTANTs that are not FETCHABLE
The listing may also include some compiler generated temporaries.
For an AUTOMATIC variable with adjustable extents, there will be two entries in
this table:
an entry with '_addr' prefixing the variable name - this entry gives the location
of the address of the variable
an entry with '_desc' prefixing the variable name - this entry gives the location
of the address of the variable's descriptor
For STATIC and CONTROLLED variables, the storage location will depend on the
RENT/NORENT compiler option, and if the the NORENT option is in effect, the
location of CONROLLED variables will also depend on the
WRITABLE/NOWRITABLE compiler option.
The first column in the Storage Offset Listing is labeled IDENTIFIER and holds the
name of the variable whose location appears in the fourth column.
The second column in the Storage Offset Listing is labeled DEFINITION and holds
a string in the format "B-F:N" where
B is the number of the block where the variable is declared
You can find the name of the block corresponding to this block number in the
Block Name List which will proceed the Storage Offset Listing (and the Pseudo
Assembly Listing, if any)
F is the number of the source file where the variable is declared
You can find the name of the file corresponding to this file number in the File
Reference Table which will appear very near the end of the entire compilation
listing.

N is the number of the source line where the variable is declared in that source
file
The third column in the Storage Offset Listing is labeled ATTRIBUTES and
indicates the storage class of the variable.
The fourth column in the Storage Offset Listing is unlabeled and tells how to find
the location of the variable.
File reference table

The file reference table consists of three columns which list the following
information about the files read during the compile:
the number assigned by the compiler to the file
the included-from data for the file
the name of the file
The first entry in the included-from column is blank because the first file listed is the
source file. Subsequent entries in this column show the line number of the include
statement followed by a period and the file number of the source file containing the
include.
If the file is a member of a PDS or PDSE, the file name lists the fully qualified
dataset name and the member name.
If the file is included via a subsystem (such as Librarian), then the file name will
have the form DD:ddname(member), where
ddname is the ddname specified on the %INCLUDE statement (or SYSLIB if no
ddname was specified)
member is the member name specified on the %INCLUDE statement.
Messages and return codes

If the preprocessor or the compiler detects an error, or the possibility of an error,
messages are generated. Messages generated by the preprocessor appear in the
listing immediately after the listing of the statements processed by the
preprocessor. You can generate your own messages in the preprocessing stage
by use of the %NOTE statement. Such messages might be used to show how
many times a particular replacement had been made. Messages generated by the
compiler appear at the end of the listing.
Messages are displayed in the following format:

PPPnnnnI X
where PPP is the prefix identifying the origin of the message (for example, IBM
indicates the PL/I compiler), nnnn is the 4-digit message number, and X identifies
the severity code. All messages are graded according to their severity, and the
severity codes are I, W, E, S, and U.
For every compilation job or job step, the compiler generates a return code that
indicates to the operating system the degree of success or failure it achieved. For
OS/390, this code appears in the end-of-step message that follows the listing of the
job control statements and job scheduler messages for each step.

Table 5 on page 61 provides an explanation of the severity codes and the
comparable return code for each:
Table 5. Description of PL/I error codes and return codes

Severity Return Message Description
Code Code Type
I 0000 Informational The compiled program should run correctly. The compiler
might inform you of a possible inefficiency in your code or
some other condition of interest.
W 0004 Warning A statement might be in error (warning) even though it is
syntactically valid. The compiled program should run
correctly, but it might produce different results than expected
or be significantly inefficient.
E 0008 Error A simple error fixed by the compiler. The compiled program
should run correctly, but it might product different results than
expected.
S 0012 Severe An error not fixed by the compiler. If the program is compiled
and an object module is produced, it should not be used.
U 0016 Unrecoverable An error that forces termination of the compilation. An object
module is not successfully created.
Note: Compiler messages are printed in groups according to these severity levels.
The compiler lists only messages that have a severity equal to or greater than that
specified by the FLAG option, as shown in Table 6.
Table 6. Using the FLAG option to select the lowest

message severity listed
Type of Message Option
Information FLAG(I)
Warning FLAG(W)
Error FLAG(E)
Severe Error FLAG(S)
Unrecoverable Error Always listed
The text of each message, an explanation, and any recommended programmer

response, are given in Enterprise PL/I Messages and Codes.

PL/I preprocessors
Chapter 2. PL/I preprocessors

Include preprocessor . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 64
Macro preprocessor . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 65
Macro preprocessor options . . . . . . . . . . . . . . . . . . . . . . . . . . . . 65
Macro preprocessor example . . . . . . . . . . . . . . . . . . . . . . . . . . . . 65
SQL preprocessor . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 66
SQL preprocessor options . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 68
Coding SQL statements in PL/I applications . . . . . . . . . . . . . . . . . . . 72
Defining the SQL communications area . . . . . . . . . . . . . . . . . . . . 72
Defining SQL descriptor areas . . . . . . . . . . . . . . . . . . . . . . . . . 73
Embedding SQL statements . . . . . . . . . . . . . . . . . . . . . . . . . . . 74
Using host variables . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 75
Determining equivalent SQL and PL/I data types . . . . . . . . . . . . . . . 77
Additional Information on Large Object (LOB) support . . . . . . . . . . . . . 80
General information on LOBs . . . . . . . . . . . . . . . . . . . . . . . . . . 80
PL/I variable declarations for LOB Support . . . . . . . . . . . . . . . . . . 81
Determining compatibility of SQL and PL/I data types . . . . . . . . . . . . 81
Using host structures . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 82
Using indicator variables . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 82
Host structure example . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 83
DECLARE TABLE statement . . . . . . . . . . . . . . . . . . . . . . . . . . 84
DECLARE STATEMENT statement . . . . . . . . . . . . . . . . . . . . . . 84
CICS Preprocessor . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 85
CICS preprocessor options . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 85
Coding CICS statements in PL/I applications . . . . . . . . . . . . . . . . . . . 85
Embedding CICS statements . . . . . . . . . . . . . . . . . . . . . . . . . . 85
Writing CICS transactions in PL/I . . . . . . . . . . . . . . . . . . . . . . . . . 86
62  Copyright IBM Corp. 1991, 2002

PL/I preprocessors
The PL/I compiler allows you to select one or more of the integrated preprocessors
as required for use in your program. You can select the include preprocessor, the
macro preprocessor, the SQL preprocessor, or the CICS preprocessor and the
order in which you would like them to be called.
The include preprocessor processes special include directives and incorporates
external source files.
The macro preprocessor, based on %statements and macros, modifies your
source program.
The SQL preprocessor modifies your source program and translates EXEC
SQL statements into PL/I statements.
The CICS preprocessor modifies your source program and translates EXEC
CICS statements into PL/I statements.
Each preprocessor supports a number of options to allow you to tailor the

processing to your needs.
The three compile-time options MDECK, INSOURCE, and SYNTAX are meaningful
only when you also specify the PP option. For more information about these
options, see MDECK on page 28, INSOURCE on page 22, and SYNTAX on
page 43.
Chapter 2. PL/I preprocessors 63

Include preprocessor
Include preprocessor
The include preprocessor allows you to incorporate external source files into your
programs by using include directives other than the PL/I directive %INCLUDE.
The following syntax diagram illustrates the options supported by the INCLUDE
preprocessor:

──PP──(──INCLUDE──(──'──ID(<directive>)──'──)──)───────────────────────────────

ID Specifies the name of the include directive. Any line that starts with this
directive as the first set of nonblank characters is treated as an include
directive.
The specified directive must be followed by one or more blanks, an include
member name, and finally an optional semicolon. Syntax for
ddname(membername) is not supported.
In the following example, the first include directive is valid and the second one
is not:
++include payroll
++include syslib(payroll)
This first example causes all lines that start with -INC (and possibly preceding
blanks) to be treated as include directives:
pp( include( 'id(-inc)'))
This second example causes all lines that start with ++INCLUDE (and possibly
preceding blanks) to be treated as include directives:
pp( include( 'id(++include)'))

Macro preprocessor
Macro preprocessor
Macros allow you to write commonly used PL/I code in a way that hides
implementation details and the data that is manipulated, and exposes only the
operations. In contrast with a generalized subroutine, macros allow generation of
only the code that is needed for each individual use.
The macro preprocessing facilities of the compiler are described in the PL/I
Language Reference.
Macro preprocessor options

You can invoke the macro preprocessor by specifying either the MACRO option or
the PP(MACRO) option. You can specify pp(macro) without any options or include
any of the following:

──PP──(──MACRO──(──'──┬──────────────────────────┬──┬───────────────────────┬───
│ ┌─DECIMAL─┐ │ │ ┌─UPPER─┐ │
└─FIXED──(──┴─BINARY──┴──)─┘ └─CASE──(──┴─ASIS──┴──)─┘

──'──)──)───────────────────────────────────────────────────────────────────────

FIXED (DECIMAL or BINARY)

This option specifies the default base for FIXED variables as either DECIMAL
or BINARY.
Under FIXED(DECIMAL), FIXED variables have the attributes REAL FIXED
DEC(5), while Under FIXED(BINARY), FIXED variables have the attributes
REAL SIGNED FIXED BIN(31). (See Language Reference for more
information).
CASE (ASIS or UPPER)

This option specifies if the input text should be converted to uppercase. ASIS
specifies that the input text is left "as is". UPPER specifies that the input text is
to be converted to upper case.
Macro preprocessor example

A simple example of the use of the preprocessor to produce a source deck is
shown in Figure 4 on page 66. According to the value assigned to the
preprocessor variable USE, the source statements will represent either a subroutine
(CITYSUB) or a function (CITYFUN). The DSNAME used for SYSPUNCH specifies
a source program library on which the preprocessor output will be placed. Normally
compilation would continue and the preprocessor output would be compiled.

SQL preprocessor
that is placed on a source program library

//OPT4#8 JOB
//STEP2 EXEC IBMZC,PARM.PLI='MACRO,MDECK,NOCOMPILE,NOSYNTAX'
//PLI.SYSPUNCH DD DSNAME=HPU8.NEWLIB(FUN),DISP=(NEW,CATLG),UNIT=SYSDA,
// SPACE=(TRK,(1,1,1)),DCB=(RECFM=FB,LRECL=8K,BLKSIZE=4KK)
//PLI.SYSIN DD ]
/] GIVEN ZIP CODE, FINDS CITY ]/
%DCL USE CHAR;
%USE = 'FUN' /] FOR SUBROUTINE, %USE = 'SUB' ]/ ;
%IF USE = 'FUN' %THEN %DO;
CITYFUN: PROC(ZIPIN) RETURNS(CHAR(16)) REORDER; /] FUNCTION ]/
%END;
%ELSE %DO;
CITYSUB: PROC(ZIPIN, CITYOUT) REORDER; /] SUBROUTINE ]/
DCL CITYOUT CHAR(16); /] CITY NAME ]/
%END;
DCL (LBOUND, HBOUND) BUILTIN;
DCL ZIPIN PIC '99999'; /] ZIP CODE ]/
DCL 1 ZIP_CITY(7) STATIC, /] ZIP CODE - CITY NAME TABLE ]/
2 ZIP PIC '99999' INIT(
95141, 95K14, 95K3K,
95K51, 95K7K, 95KK8,
K), /] WILL NOT LOOK AT LAST ONE ]/
2 CITY CHAR(16) INIT(
'SAN JOSE', 'CUPERTINO', 'LOS GATOS',
'SANTA CLARA', 'SARATOGA', 'CAMPBELL',
'UNKNOWN CITY'); /] WILL NOT LOOK AT LAST ONE ]/
DCL I FIXED BIN(31);
DO I = LBOUND(ZIP,1) TO /] SEARCH FOR ZIP IN TABLE ]/
HBOUND(ZIP,1)-1 /] DON'T LOOK AT LAST ELEMENT ]/
WHILE(ZIPIN ¬= ZIP(I));
END;
%IF USE = 'FUN' %THEN %DO;
RETURN(CITY(I)); /] RETURN CITY NAME ]/
%END;
%ELSE %DO;
CITYOUT=CITY(I); /] RETURN CITY NAME ]/
%END;
END;
Figure 4. Using the macro preprocessor to produce a source deck
SQL preprocessor
In general, the coding for you PL/I program will be the same whether or not you
want it to access a DB2 database. However, to retrieve, update, insert, and delete
DB2 data and use other DB2 services, you must use SQL statements. You can
use dynamic and static EXEC SQL statements in PL/I applications.
To communicate with DB2, you need to do the following:

Code any SQL statements you need, delimiting them with EXEC SQL
Use the DB2 precompiler or, if using DB2 for OS/390 Version 7 Release 1 or
later. compile with the PL/I PP(SQL()) compiler option
Before you can take advantage of EXEC SQL support, you must have authority to
access a DB2 system. Contact your local DB2 Database Administrator for your
authorization.
Note: The PL/I SQL Preprocessor currently does not support DBCS.

SQL preprocessor
Programming and compilation considerations

When you use the PL/I SQL Preprocessor the PL/I compiler handles your source
program containing embedded SQL statements at compile time, without your
having to use a separate precompile step. Although the use of a separate
precompile step continues to be supported, use of the PL/I SQL Preprocessor is
recommended. Interactive debugging with Debug Tool is enhanced when you use
the PL/I SQL Preprocessor because you see only the SQL statements while
debugging (and not the generated PL/I source). However, you must have DB2 for
OS/390 Version 7 Release 1 or later to use the SQL preprocessor.
In addition, using the PL/I SQL Preprocessor lifts some of the DB2 precompiler's
restrictions on SQL programs. When you process SQL statements with the PL/I
SQL Preprocessor, you can now
use fully-qualified names for structured host variables
include SQL statements at any level of a nested PL/I program, instead of in
only the top-level source file
use nested SQL INCLUDE statements
Compiling with the PL/I SQL Preprocessor option generates a DB2 database
request module (DBRM) along with the usual PL/I compiler outputs such as object
module and listing. As input to the DB2 bind process, the DBRM data set contains
information about the SQL statements and host variables in the program.
The PL/I compiler listing includes the error diagnostics (such as syntax errors in the
SQL statements) that the PL/I SQL Preprocessor generates.
To use the PL/I SQL Preprocessor, you need to do the following things:
Specify the following option when you compile your program
PP(SQL('options'))
This compiler option indicates that you want the compiler to invoke the PL/I
SQL preprocessor. Specify a list of SQL processing options in the parenthesis
after the SQL keyword. The options can be separated by a comma or by a
space.
For example, PP(SQL('DATE(USA),TIME(USA)') tells the preprocessor to use the
USA format for both DATE and TIME data types.
In addition, for LOB support you must specify the option
LIMITS( FIXEDBIN(31,63) FIXEDDEC(31) )
Include DD statements for the following data sets in the JCL for your compile
step:
– DB2 load library (prefix.SDSNLOAD)
The PL/I SQL preprocessor calls DB2 modules to do the SQL statement
processing. You therefore need to include the name of the DB2 load
library data set in the STEPLIB concatenation for the compile step.
– Library for SQL INCLUDE statements
If your program contains SQL INCLUDE member-name statements that
specify secondary input to the source program, you need to include the

SQL preprocessor
name of the data set that contains member-name in the SYSLIB

concatenation for the compile step.
– DBRM library
The compilation of the PL/I program generates a DB2 database request
module (DBRM) and the DBRMLIB DD statement is required to designate
the data set to which the DBRM is written.
– For example, you might have the following lines in your JCL:
//STEPLIB DD DSN=DSN71K.SDSNLOAD,DISP=SHR
//SYSLIB DD DSN=PAYROLL.MONTHLY.INCLUDE,DISP=SHR
//DBRMLIB DD DSN=PAYROLL.MONTHLY.DBRMLIB.DATA(MASTER),DISP=SHR
SQL preprocessor options

The following syntax diagram illustrates all of the options supported by the SQL
preprocessor.

────PP────(────SQL────(──'──┬─────────────────────────┬──┬──────────────────┬───
│ ┌─TSO───┐ │ │ ┌─2─┐ │
└─ATTACH──(──┼───────┼──)─┘ └─CONNECT(─┼───┼─)─┘
├─CAF───┤ └─1─┘
└─RRSAF─┘

──┬───────────────────────┬──┬───────────────────┬──┬───────────────────────┬────
└─DATE──(──┬───────┬──)─┘ │ ┌─15─┐ │ │ ┌─S39K─┐ │

├─ISO───┤ └─DEC──(──┼────┼──)─┘ └─FLOAT──(──┼──────┼──)─┘
├─USA───┤ └─31─┘ └─IEEE─┘
├─EUR───┤
├─JIS───┤
└─LOCAL─┘
┌─ONEPASS─┐ ┌─OPTIONS───┐

──┼─────────┼──┬───────────────────┬──┬───────┬──┼───────────┼───────────────────
└─TWOPASS─┘ └─LEVEL─┬────────┬──┘ └─NOFOR─┘ └─NOOPTIONS─┘

└─(aaaa)─┘

──┬──────────────────────────────────────────────────────┬───────────────────────
└─SQLFLAG──(──┬───────────────────────────────────┬──)─┘
├─STD─┬──────────────────────────┬──┤
│ └─(ssname─┬────────────┬─)─┘ │
│ └─,qualifier─┘ │
└─IBM───────────────────────────────┘

──┬───────────────────────┬──┬───────────────────────┬───────────────────────────
│ ┌─NO──┐ │ └─TIME──(──┬───────┬──)─┘
└─STDSQL──(──┼─────┼──)─┘ ├─ISO───┤
└─YES─┘ ├─USA───┤
├─EUR───┤
├─JIS───┤
└─LOCAL─┘

──┬────────────────────┬──┬─────────────────────────┬──'──)──)──────────────────

│ ┌─DB2─┐ │ └─VERSION──(──┬──────┬──)─┘
└─SQL──(──┼─────┼──)─┘ ├─aaaa─┤
└─ALL─┘ └─AUTO─┘
The table uses a vertical bar(|) to separate mutually exclusive options, and brackets
( ) to indicate that you can sometimes omit the enclosed option.
ATTACH(TSO|CAF|RRSAF)
Specifies the attachment facility that the application uses to access DB2. TSO,
CAF and RRSAF applications that load the attachment facility can use this
option to specify the correct attachment facility, instead of coding a dummy
DSNHLI entry point.
The default is ATTACH(TSO).

SQL preprocessor
CONNECT(2|1)
Determines whether to apply type 1 or type 2 CONNECT statement rules.
CONNECT(2) Apply rules for the CONNECT (Type 2) statement.

CONNECT(1) Apply rules for the CONNECT (Type 1) statement.
The default is CONNECT(2).

For more information about this option, refer to the DB2 SQL Reference
manual.
The CONNECT option can be abbreviated to CT.
DATE(ISO|USA|EUR|JIS|LOCAL)
Specifies that date output should always be returned in a particular format,
regardless of the format specified as the location default. For a description of
these formats, refer to the DB2 SQL Reference manual.
The default is in the field DATE FORMAT on the Application Programming
Defaults Panel 2 when DB2 is installed.
You cannot use the LOCAL option unless you have a date exit routine.
DEC(15|31)
Specifies the maximum precision for decimal arithmetic operations.
The default is in the field DECIMAL ARITHMETIC on the Application
Programming Defaults Panel 1 when DB2 is installed.
FLOAT(S390|IEEE)
Determines whether the contents of floating point host variables are in
System/390 hexadeciimal format or in IEEE format. An error message is
issued if this FLOAT option is different than the PL/I compiler's
DEFAULT(HEXADEC|IEEE) option.
The default setting is FLOAT(S390).
GRAPHIC
Indicates that the source code might use mixed data, and that X'0E' and X'0F'
are special control characters (shift-out and shift-in) for EBCDIC data.
GRAPHIC and NOGRAPHIC are mutually exclusive options. The default is in
the field MIXED DATA on the Application Programming Defaults Panel 1 when
DB2 is installed.
LEVEL(aaaa)
Defines the level of a module, where aaaa is any alphanumeric value of up to
seven characters. This option is not recommended for general use, and the
DSNH CLIST and the DB2I panels do not support it.
You can omit the suboption (aaaa). The resulting consistency token is blank.
The LEVEL option can be abbreviated to L.
NOFOR
In static SQL, NOFOR eliminates the need for the FOR UPDATE of FOR
UPDATE OF clause in DECLARE CURSOR statements. When you use
NOFOR, your program can make positioned updates to any columns that the
program has DB2 authority to update.
When you do not use NOFOR, if you want to make positioned updates to any
columns that the program has DB2 authority to update, you need to specify

SQL preprocessor
FOR UPDATE with no column list in your DECLARE CURSOR statements.

The FOR UPDATE clause with no column list applies to static or dynamic SQL
statements.
Whether you use or do not use NOFOR, you can specify FOR UPDATE OF
with a column list to restrict updates to only the columns named in the clause
and specify the acquisition of update locks.
You imply NOFOR when you use the option STDSQL(YES).
If the resulting DBRM is very large, you might need extra storage when you
specify NOFOR or use the FOR UPDATE clause with no column list.
NOGRAPHIC
Indicates the use of X'0E' and X'0F' in a string, but not as control characters.
GRAPHIC and NOGRAPHIC are mutually exclusive options. The default is in
the field MIXED DATA on the Application Programming Defaults Panel 1 when
DB2 is installed.
NOOPTIONS
Suppresses the SQL Preprocessor options listing.
The NOOPTIONS option can be abbreviated to NOOPTN.
ONEPASS
Processes in one pass, to avoid the additional processing time for making two
passes. Declarations must appear before SQL references if the ONEPASS
option is used.
ONEPASS and TWOPASS are mutually exclusive options.
The default is ONEPASS.
The ONEPASS option can be abbreviated to ON.
OPTIONS
Lists SQL Preprocessor options.
The default is OPTIONS.
The OPTIONS option can be abbreviated to OPTN.
SQL(ALL|DB2)
Indicates whether the source contains SQL statements other than those
recognized by DB2 for OS/390 and z/OS.
SQL(ALL) is recommended for application programs whose SQL statements
must execute on a server other than DB2 for OS/390 and z/OS using DRDA
access. SQL(ALL) indicates that the SQL statements in the program are not
necessarily for DB2 for OS/390 and z/OS. Accordingly, the SQL statement
processor then accepts statements that do not conform to the DB2 syntax
rules. The SQL statement processor interprets and processes SQL statements
according to distributed relational database architecture (DRDA) rules. The
SQL statement processor also issues an informational message if the program
attempts to use an IBM SQL reserved words as ordinary identifiers. SQL(ALL)
does not affect the limits of the SQL statement processor.
SQL(DB2), the default, means to interpret SQL statements and check syntax
for use by DB2 for OS/390 and z/OS. SQL(DB2) is recommended when the
database server is DB2 for OS/390 and z/OS.

SQL preprocessor
SQLFLAG(IBM|STD(ssname,qualifier))
Specifies the standard used to check the syntax of SQL statements. When
statements deviate from the standard, the SQL statement processor writes
informational messages (flags) to the output listing. The SQLFLAG option is
independent of other SQL statement processor options, including SQL and
STDSQL.
IBM checks SQL statements against the syntax of IBM SQL Version 1.
STD checks SQL statements against the syntax of the entry level of the
ANSI/ISO SQL standard of 1992. You can also use 86 for option, as in
releases before Version 7.
ssname requests semantics checking, using the specified DB2 subsystem
name for catalog access. If you do not specify ssname, the SQL statement
processor checks only the syntax.
qualifier specifies the qualifier used for flagging. If you specify a qualifier, you
must always specify the ssname first. If qualifier is not specified, the default is
the authorization ID of the process that started the SQL statement processor.
STDSQL(NO|YES)
Indicates to which rules the output statements should conform.
STDSQL(YES) indicates that the precompiled SQL statements in the source
program conform to certain rules of the SQL standard. STDSQL(NO) indicates
conformance to DB2 rules.
The default is in the field STD SQL LANGUAGE on the Application
Programming Defaults Panel 2 when DB2 is installed.
STDSQL(YES) automatically implies the NOFOR option.
TIME(ISO|USA|EUR|JIS|LOCAL)
Specifies that time output should always be returned in a particular format,
regardless of the format specified as the location default. For a description of
these formats, refer to the DB2 SQL Reference manual.
The default is in the field TIME FORMAT on the Application Programming
Defaults Panel 2 when DB2 is installed.
You cannot use the LOCAL option unless you have a date exit routine.
TWOPASS
Processes in two passes, so that declarations need not precede references.
ONEPASS and TWOPASS are mutually exclusive options.
The default is ONEPASS.
The TWOPASS option can be abbreviated to TW.
VERSION(aaaa|AUTO)
Defines the version identifier of a package, program, and the resulting DBRM.
When you specify VERSION, the SQL statement processor creates a version
identifier in the program and DBRM. This affects the size of the load module
and DBRM. DB2 uses the version identifier when you bind the DBRM to a plan
or package.
If you do not specify a version at precompile time, then an empty string is the
default version identifier. If you specify AUTO, the SQL statement processor
uses the consistency token to generate the version identifier. If the consistency

SQL preprocessor
token is a timestamp, the timestamp is converted into ISO character format and
used as the version identifier. The timestamp used is based on the
System/370 Store Clock value.
Coding SQL statements in PL/I applications

You can code SQL statements in your PL/I applications using the language defined
in DB2 UDB for OS/390 and z/OS V7 SQL Reference (SC26-9944-1). Specific
requirements for your SQL code are described in the sections that follow.
Defining the SQL communications area

A PL/I program that contains SQL statements must include either an SQLCODE
variable (if the STDSQL(86) preprocessor option is used) or an SQL
communications area (SQLCA). As shown in Figure 5 on page 73, part of an
SQLCA consists of an SQLCODE variable and an SQLSTATE variable.
The SQLCODE value is set by the Database Services after each SQL
statement is executed. An application can check the SQLCODE value to
determine whether the last SQL statement was successful.
The SQLSTATE variable can be used as an alternative to the SQLCODE
variable when analyzing the result of an SQL statement. Like the SQLCODE
variable, the SQLSTATE variable is set by the Database Services after each
SQL statement is executed.
The SQLCA should be included by using the EXEC SQL INCLUDE statement:
exec sql include sqlca;

SQL preprocessor
The SQLCA must not be defined within an SQL declare section. The scope of the
SQLCODE and SQLSTATE declaration must include the scope of all SQL
statements in the program.
Dcl
1 Sqlca,
2 sqlcaid char(8), /] Eyecatcher = 'SQLCA ' ]/
2 sqlcabc fixed binary(31), /] SQLCA size in bytes = 136 ]/
2 sqlcode fixed binary(31), /] SQL return code ]/
2 sqlerrmc char(7K) var, /] Error message tokens ]/
2 sqlerrp char(8), /] Diagnostic information ]/
2 sqlerrd(K:5) fixed binary(31), /] Diagnostic information ]/
2 sqlwarn, /] Warning flags ]/
3 sqlwarnK char(1),
3 sqlwarn1 char(1),
3 sqlwarn2 char(1),
3 sqlwarn3 char(1),
3 sqlwarn4 char(1),
3 sqlwarn5 char(1),
3 sqlwarn6 char(1),
3 sqlwarn7 char(1),
2 sqlext,
3 sqlwarn8 char(1),
3 sqlwarn9 char(1),
3 sqlwarna char(1),
3 sqlstate char(5); /] State corresponding to SQLCODE ]/
Figure 5. The PL/I declaration of SQLCA
Defining SQL descriptor areas

The following statements require an SQLDA:
PREPARE statement-name INTO descriptor-name FROM host-variable
EXECUTE...USING DESCRIPTOR descriptor-name
FETCH...USING DESCRIPTOR descriptor-name
OPEN...USING DESCRIPTOR descriptor-name
DESCRIBE statement-name INTO descriptor-name
Unlike the SQLCA, there can be more than one SQLDA in a program, and an
SQLDA can have any valid name. An SQLDA should be included by using the
EXEC SQL INCLUDE statement:
exec sql include sqlda;
The SQLDA must not be defined within an SQL declare section.

SQL preprocessor
Dcl
1 Sqlda based(Sqldaptr),
2 sqldaid char(8), /] Eye catcher = 'SQLDA ' ]/
2 sqldabc fixed binary(31), /] SQLDA size in bytes=16+44]SQLN]/
2 sqln fixed binary(15), /] Number of SQLVAR elements]/
2 sqld fixed binary(15), /] # of used SQLVAR elements]/
2 sqlvar(Sqlsize refer(sqln)), /] Variable Description ]/
3 sqltype fixed binary(15), /] Variable data type ]/
3 sqllen fixed binary(15), /] Variable data length ]/
3 sqldata pointer, /] Pointer to variable data value]/
3 sqlind pointer, /] Pointer to Null indicator]/
3 sqlname char(3K) var ; /] Variable Name ]/
Dcl
1 Sqlda2 based(Sqldaptr),
2 sqldaid2 char(8), /] Eye catcher = 'SQLDA ' ]/
2 sqldabc2 fixed binary(31), /] SQLDA size in bytes=16+44]SQLN]/
2 sqln2 fixed binary(15), /] Number of SQLVAR elements]/
2 sqld2 fixed binary(15), /] # of used SQLVAR elements]/
2 sqlvar2(Sqlsize refer(sqln2)), /] Variable Description ]/
3 sqlbiglen,
4 sqllongl fixed binary(31),
4 sqlrsvdl fixed binary(31),
3 sqldatal pointer,
3 sqltname char(3K) var;
dcl Sqlsize fixed binary(15); /] number of sqlvars (sqln) ]/

dcl Sqldaptr pointer;
dcl Sqltripled char(1) initial('3');
dcl Sqldoubled char(1) initial('2');
dcl Sqlsingled char(1) initial(' ');
Figure 6. The PL/I declaration of an SQL descriptor area
Embedding SQL statements

The first statement of your program must be a PROCEDURE or a PACKAGE
statement. You can add SQL statements to your program wherever executable
statements can appear. Each SQL statement must begin with EXEC (or
EXECUTE) SQL and end with a semicolon (;).
For example, an UPDATE statement might be coded as follows:

exec sql update DSN871K.DEPT
set Mgrno = :Mgr_Num
where Deptno = :Int_Dept;
Comments: In addition to SQL statements, comments can be included in

embedded SQL statements wherever a blank is allowed.
Continuation for SQL statements: The line continuation rules for SQL
statements are the same as those for other PL/I statements.
Including code: SQL statements or PL/I host variable declaration statements can
be included by placing the following SQL statement at the point in the source code
where the statements are to be embedded:
exec sql include member;
Margins: SQL statements must be coded in columns m through n where m and n

are specified in the MARGINS(m,n) compiler option.

SQL preprocessor
Names: Any valid PL/I variable name can be used for a host variable and is
subject to the following restriction: Do not use host variable names or external entry
names that begin with 'SQL', 'DSN', or 'IBM'. These names are reserved for
the database manager and PL/I. The length of a host variable name must not
exceed the value n specified in the LIMITS(NAME(n)) compiler option.
Statement labels: With the exception of the END DECLARE SECTION statement,
and the INCLUDE text-file-name statement, executable SQL statements, like PL/I
statements, can have a label prefix.
WHENEVER statement: The target for the GOTO clause in an SQL WHENEVER
statement must be a label in the PL/I source code and must be within the scope of
any SQL statements affected by the WHENEVER statement.
Using host variables

All host variables used in SQL statements must be explicitly declared. If the
ONEPASS option is in effect, a host variable used in an SQL statement must be
declared prior to its first use in an SQL statement.
In addition:
All host variables within an SQL statement must be preceded by a colon (:).
The names of host variables must be unique within the program, even if the
host variables are in different blocks or procedures.
An SQL statement that uses a host variable must be within the scope of the
statement in which the variable was declared.
Host variables cannot be declared as an array, although an array of indicator
variables is allowed when the array is associated with a host structure.
Declaring host variables: Host variable declarations can be made at the same
place as regular PL/I variable declarations.
Only a subset of valid PL/I declarations are recognized as valid host variable
declarations. The preprocessor does not use the data attribute defaults specified in
the PL/I DEFAULT statement. If the declaration for a variable is not recognized,
any statement that references the variable might result in the message “The host
variable token ID is not valid”.
Only the names and data attributes of the variables are used by the preprocessor;
the alignment, scope, and storage attributes are ignored.
Numeric host variables: The following figure shows the syntax for valid numeric
host variable declarations.
──┬─DECLARE─┬──┬─variable-name───────┬──────────────────────────────────────────
└─DCL─────┘ │ ┌─,───────────┐ │
└─(──variable-name┴─)─┘
─────┬─────────┬──┬─FIXED──┬─────────────────────────┬─┬─────────────────────────
├─BINARY──┤ │ └─(precision─┬────────┬─)─┘ │
├─BIN─────┤ │ └─,scale─┘ │
├─DECIMAL─┤ └─FLOAT─┬─────────────────┬──────────┘
└─DEC─────┘ └─(──precision──)─┘
──┬───────────────────────────────────────┬── ; ────────────────────────────────

└─Alignment and/or Scope and/or Storage─┘

SQL preprocessor
Notes
BINARY/DECIMAL and FIXED/FLOAT can be specified in either order.

The precision and scale attributes can also follow BINARY/DECIMAL.
A value for scale can be specified only for DECIMAL FIXED.
Refer to Table 7 on page 77 for more detailed information.
Character host variables: The following figure shows the syntax for valid character
host variables.

└─DCL─────┘ │ ┌─,───────────┐ │

──┬─CHARACTER─┬──┬──────────┬──┬─────────┬───────────────────────────────────────
└─CHAR──────┘ └─(length)─┘ ├─VARYING─┤

└─VAR─────┘

──┬───────────────────────────────────────┬── ; ────────────────────────────────

Notes
For non-varying character host variables, length must be a constant no greater

than the maximum length of SQL CHAR data.
For varying-length character host variables, length must be a constant no
greater than the maximum length of SQL LONG VARCHAR data.
Graphic host variables: The following figure shows the syntax for valid graphic
host variables.

──┬─DECLARE─┬──┬─variable-name───────┬──GRAPHIC──┬──────────┬──┬─────────┬──────
└─DCL─────┘ │ ┌─,───────────┐ │ └─(length)─┘ ├─VARYING─┤

└─(──variable-name┴─)─┘ └─VAR─────┘

──┬───────────────────────────────────────┬── ; ────────────────────────────────

Notes
For non-varying graphic host variables, length must be a constant no greater

than the maximum length of SQL GRAPHIC data.
For varying-length graphic host variables, length must be a constant no greater
than the maximum length of SQL LONG VARGRAPHIC data.
Result set locators: The following figure shows the syntax for valid result set
locator declarations.

└─DCL─────┘ │ ┌─,───────────┐ │

────SQL TYPE IS RESULT_SET_LOCATOR────┬─────────┬────────────────────────────────
├─VARYING─┤
└─VAR─────┘

──┬───────────────────────────────────────┬── ; ────────────────────────────────

Table locators: The following figure shows the syntax for valid table locators.

SQL preprocessor
└─DCL─────┘ │ ┌─,───────────┐ │

────SQL TYPE IS TABLE LIKE table-name AS LOCATOR──── ; ─────────────────────────

LOB Variables and Locators: The following figure shows the syntax for
declarations of BLOB, CLOB, and DBCLOB host variables and locators.

──┬─Declare─┬──PL/I host identifier──SQL TYPE IS──┤ PL/I LOB type ├────────────

└─Dcl─────┘
PL/I LOB type:
├──┬─┬─┬─Binary Large Object─┬────┬──(──length──┬───┬──)─┬────────────────────────┤
│ │ └─BLOB────────────────┘ │ ├─K─┤ │
│ ├─┬─Character Large Object─┬─┤ ├─M─┤ │
│ │ ├─Char Large Object──────┤ │ └─G─┘ │
│ │ └─CLOB───────────────────┘ │ │
│ └─DBCLOB─────────────────────┘ │
└─┬─BLOB_LOCATOR───┬──────────────────────────────────┘
├─CLOB_LOCATOR───┤
└─DBCLOB_LOCATOR─┘
ROWIDs: The following figure shows the syntax for valid declarations of ROWID
variables.

──┬─DECLARE─┬──┬─variable-name───────┬────SQL TYPE IS ROWID──── ; ─────────────

└─DCL─────┘ │ ┌─,───────────┐ │
Determining equivalent SQL and PL/I data types

The base SQLTYPE and SQLLEN of host variables are determined according to
the following table. If a host variable appears with an indicator variable, the
SQLTYPE is the base SQLTYPE plus one.
Table 7 (Page 1 of 2). SQL data types generated from PL/I declarations
SQLTYPE SQLLEN of SQL Data Type
of Host Host
PL/I Data Type Variable Variable
BIN FIXED(n), n < 16 500 2 SMALLINT
BIN FIXED(n), n ranges from 16 to 496 4 INTEGER
31
DEC FIXED(p,s) 484 p (byte 1) DECIMAL(p,s)
0<=p<=15 and s (byte 2)
0<=s<=p
BIN FLOAT(p), 480 4 REAL or FLOAT(n)
1 ≤ p ≤ 21 1<=n<=21
BIN FLOAT(p), 480 8 DOUBLE PRECISION or
22 ≤ p ≤ 53 FLOAT(n)
22<=n<=53
DEC FLOAT(m), 480 4 FLOAT (single precision)
1≤m≤6
DEC FLOAT(m), 480 8 FLOAT (double precision)
7 ≤ m ≤ 16
CHAR(n), 452 n CHAR(n)
CHAR(n) VARYING, 448 n VARCHAR(n)
1 ≤ n ≤ 255

SQL preprocessor
Table 7 (Page 2 of 2). SQL data types generated from PL/I declarations
of Host Host
CHAR(n) VARYING, n > 255 456 n VARCHAR(n)
GRAPHIC(n), 468 n GRAPHIC(n)
1 ≤ n ≤ 127
GRAPHIC(n) VARYING, 464 n VARGRAPHIC(n)
1 ≤ n ≤ 2000
GRAPHIC(n) VARYING, n > 2000 472 n LONG VARGRAPHIC
Table 8. SQL data types generated from Meta PL/I declarations

of Host Host
SQL TYPE IS 972 4 Result Set Locator
RESULT_SET_LOCATOR
SQL TYPE IS TABLE LIKE 976 4 Table Locator (1)
table-name AS LOCATOR
SQL TYPE IS BLOB_LOCATOR 960 4 BLOB Locator (1)
SQL TYPE IS CLOB_LOCATOR 964 4 CLOB Locator (1)
SQL TYPE IS 968 4 DBCLOB Locator (1)
DBCLOB_LOCATOR
SQL TYPE IS BLOB(n) 404 n BLOB(n)
1<n<2147483647
SQL TYPE IS CLOB(n) 408 n CLOB(n)
1<n<2147483647
SQL TYPE IS DBCLOB(n) 412 n DBCLOB(n) (2)
1<n<1073741823 (2)
SQL TYPE IS ROWID 904 40 ROWID
Note:
1. Do not use this data type as a column type.
2. n is the number of double-byte characters.

SQL preprocessor
The following tables can be used to determine the PL/I data type that is equivalent
to a given SQL data type.
Table 9. SQL data types mapped to PL/I declarations

SQL Data Type PL/I Equivalent Notes
SMALLINT BIN FIXED(15)
INTEGER BIN FIXED(31)
DECIMAL(p,s) DEC FIXED(p) or p = precision and s = scale;
DEC FIXED(p,s) 1 ≤ p ≤ 31 and 0 ≤ s ≤ p
REAL or FLOAT(n) BIN FLOAT(p) or 1 ≤ n ≤ 21,
DEC FLOAT(m) 1 ≤ p ≤ 21 and
1≤m≤6
DOUBLE PRECISION, DOUBLE, BIN FLOAT(p) or 22 ≤ n ≤ 53,
or FLOAT(n) DEC FLOAT(m) 22 ≤ p ≤ 53 and
7 ≤ m ≤ 16
CHAR(n) CHAR(n) 1 ≤ n ≤ 255
VARCHAR(n) CHAR(n) VAR
GRAPHIC(n) GRAPHIC(n) n is a positive integer from 1 to 127 that refers to the
number of double-byte characters, not to the number
of bytes
VARGRAPHIC(n) GRAPHIC(n) VAR n is a positive integer that refers to the number of
double-byte characters, not to the number of bytes; 1
≤ n ≤ 2000
LONG VARGRAPHIC GRAPHIC(n) VAR n > 2000
DATE CHAR(n) n must be at least 10
TIME CHAR(n) n must be at least 8
TIMESTAMP CHAR(n) n must be at least 26
Table 10. SQL data types mapped to Meta PL/I declarations

SQL Data Type PL/I Equivalent Notes
Result set locator SQL TYPE IS Use this data type only for receiving result sets. Do
RESULT_SET_LOCATOR not use this data type as a column type.
Table locator SQL TYPE IS TABLE LIKE Use this data type only in a user-defined function or
table-name AS LOCATOR stored procedure to receive rows of a transition table.
Do not use this data type as a column type.
BLOB locator SQL TYPE IS BLOB_LOCATOR Use this data type only to manipulate data in BLOB
columns. Do not use this data type as a column type.
CLOB locator SQL TYPE IS CLOB_LOCATOR Use this data type only to manipulate data in CLOB
columns. Do not use this data type as a column type.
DBCLOB locator SQL TYPE IS Use this data type only to manipulate data in DBCLOB
DBCLOB_LOCATOR columns. Do not use this data type as a column type.
BLOB(n) SQL TYPE IS BLOB(n) 1<n<2147483647
CLOB(n) SQL TYPE IS CLOB(n) 1<n<2147483647
DBCLOB(n) SQL TYPE IS DBCLOB(n) n is the number of double-byte characters.
1<n<1073741823
ROWID SQL TYPE IS ROWID

SQL preprocessor
Additional Information on Large Object (LOB) support
General information on LOBs

LOBS, CLOBS, and BLOBS can be as large as 2,147,483,647 bytes long (2
Gigabytes). Double Byte CLOBS can be 1,073,741,823 characters long (1
Gigabyte).
BLOB, CLOB, and DBCLOB data types

The variable declarations for BLOBs, CLOBs, and DBCLOBs are transformed
by the PL/I SQL preprocessor.
For example, consider the following declare:
DCL my-identifier-name SQL TYPE IS lob-type-name (length);
The SQL preprocessor would transform the declare into this structure:
DEFINE STRUCTURE
1 lob-type-name_length,
2 LOB_VAR_LENGTH FIXED BIN(31),
2 LOB_VAR_DATA,
3 LOB_VAR_DATA1(size1) CHAR(32767),
3 LOB_VAR_DATA2 CHAR(size2),
DCL my-identifier-name TYPE lob-type-name_length;
In this structure, my-identifier-name is the name of your PL/I host identifier
and lob-type-name_length is a name generated by the preprocessor consisting
of the LOB type and the length. size1 is an integer value that is the truncated
value of length/32767. size2 is the remainder of length/32767.
For DBCLOB data types, the generated structure looks a little different:
DEFINE STRUCTURE
1 lob-type-name_length,
2 LOB_VAR_DATA,
3 LOB_VAR_DATA1(size1) GRAPHIC(16383),
3 LOB_VAR_DATA2 GRAPHIC(size2),
In this structure, my-identifier-name is the name of your PL/I host identifier
and lob-type-name_length is a name generated by the preprocessor consisting
of the LOB type and the length. size1 is an integer value that is the truncated
value of length/16383. size2 is the remainder of length/16383.
BLOB, CLOB, and DBCLOB LOCATOR data types

The variable declarations for BLOB, CLOB, and DBCLOB locators are also
transformed by the PL/I SQL preprocessor.
For example, consider the following declare:
DCL my-identifier-name SQL TYPE IS lob-type_LOCATOR;
The SQL preprocessor would transform this declare into the following code:
DEFINE ALIAS lob-type_LOCATOR FIXED BIN(31);
Dcl my-identifier-name TYPE lob-type_LOCATOR;

In this case, my-identifier-name is your PL/I host identifier and
lob-type_LOCATOR is a name generated by the preprocessor consisting of the
LOB type and the string LOCATOR.

SQL preprocessor
PL/I variable declarations for LOB Support

The following examples provide sample PL/I variable declarations and their
corresponding transformations for LOB support.
Example 1
DCL my_blob SQL TYPE IS BLOB(2KKK);
After transform:
DEFINE STRUCTURE
1 BLOB_2KKK,
2 LOB_VAR_DATA,
3 LOB_VAR_DATA1(1) CHAR(2KKK);
DCL my_blob TYPE BLOB_2KKK;
Example 2
DCL my_dbclob SQL TYPE IS DBCLOB(4KKKK);
After transform:
DEFINE STRUCTURE
1 DBCLOB_4KKKK,
2 LOB_VAR_DATA,
3 LOB_VAR_DATA1(25K) GRAPHIC(16383),
3 LOB_VAR_DATA2 GRAPHIC(25K);
DCL my_dbclob TYPE DBCLOB_4KKKK;
Example 3
DCL my_clob_locator SQL TYPE IS CLOB_LOCATOR;
After transform:
DEFINE ALIAS CLOB_LOCATOR FIXED BIN(31);
DCL my_clob_locator TYPE CLOB_LOCATOR;
Determining compatibility of SQL and PL/I data types

PL/I host variables in SQL statements must be type compatible with the columns
which use them:
Numeric data types are compatible with each other. A SMALLINT, INTEGER,
DECIMAL, or FLOAT column is compatible with a PL/I host variable of BIN
FIXED(15), BIN FIXED(31), DECIMAL(p,s), BIN FLOAT(n) where n is from 22
to 53, or DEC FLOAT(m) where m is from 7 to 16.
Character data types are compatible with each other. A CHAR or VARCHAR
column is compatible with a fixed-length or varying-length PL/I character host
variable.
Datetime data types are compatible with character host variables. A DATE,
TIME, or TIMESTAMP column is compatible with a fixed-length or
varying-length PL/I character host variable.
When necessary, the Database Manager automatically converts a fixed-length
character string to a varying-length string or a varying-length string to a
fixed-length character string.

SQL preprocessor
Using host structures

A PL/I host structure name can be a structure name with members that are not
structures or unions. For example:
dcl 1 A,
2 B,
3 C1 char(...),
3 C2 char(...);
In this example, B is the name of a host structure consisting of the scalars C1 and
C2.
Host structures are limited to two levels. A host structure can be thought of as a
named collection of host variables.
You must terminate the host structure variable by ending the declaration with a
semicolon. For example:
dcl 1 A,
2 B char,
2 (C, D) char;
dcl (E, F) char;
Host variable attributes can be specified in any order acceptable to PL/I. For
example, BIN FIXED(31), BINARY FIXED(31), BIN(31) FIXED, and FIXED BIN(31)
are all acceptable.
The following diagram shows the syntax for valid host structures.

──┬─DECLARE─┬──level──variable-name──┬──────────────────────┬──,───────────────────────────
└─DCL─────┘ └─Scope and/or storage─┘

┌─,──────────────────────────────────────────┐

────level──┬─var-1───────────┬──┤ Attributes ├─┴──;────────────────────────────────────────

│ ┌─,─────┐ │
└─(────var-2─┴──)─┘
Attributes:
├──────┬─┬─BINARY──┬──┬─FIXED──┬─────────────────────────────┬─┬─┬───────────────────────────┤
│ ├─BIN─────┤ │ └─(──precision──┬────────┬──)─┘ │ │
│ ├─DECIMAL─┤ │ └─,scale─┘ │ │
│ └─DEC─────┘ └─FLOAT──┬─────────────────┬─────────────┘ │
│ └─(──precision──)─┘ │
└─┬─CHARACTER─┬──┬───────────────┬──┬─────────┬───────────┘
└─CHAR──────┘ └─(──integer──)─┘ ├─VARYING─┤
└─VAR─────┘
Using indicator variables

An indicator variable is a two-byte integer (BIN FIXED(15)). On retrieval, an
indicator variable is used to show whether its associated host variable has been
assigned a null value. On assignment to a column, a negative indicator variable is
used to indicate that a null value should be assigned.
Indicator variables are declared in the same way as host variables and the
declarations of the two can be mixed in any way that seems appropriate to the
programmer.

SQL preprocessor
Given the statement:

exec sql fetch Cls_Cursor into :Cls_Cd,
:Day :Day_Ind,
:Bgn :Bgn_Ind,
:End :End_Ind;
Variables can be declared as follows:
exec sql begin declare section;
dcl Cls_Cd char(7);
dcl Day bin fixed(15);
dcl Bgn char(8);
dcl End char(8);
dcl (Day_Ind, Bgn_Ind, End_Ind) bin fixed(15);
exec sql end declare section;
The following diagram shows the syntax for a valid indicator variable.
──┬─DECLARE─┬──variable-name──┬─BINARY─┬──FIXED(15)──;─────────────────────────

└─DCL─────┘ └─BIN────┘
The following diagram shows the syntax for a valid indicator array.
──┬─DECLARE─┬──┬─variable-name──(──dimension──)───────────┬──┬─BINARY─┬─────────
└─DCL─────┘ │ ┌─,──────────────────────────────┐ │ └─BIN────┘

└─(────variable-name──(──dimension──)─┴──)─┘
──FIXED(15)──;──────────────────────────────────────────────────────────────────

Host structure example

The following example shows the declaration of a host structure and an indicator
array followed by two SQL statements that are equivalent, either of which could be
used to retrieve the data into the host structure.
dcl 1 games,
5 sunday,
1K opponents char(3K),
1K gtime char(1K),
1K tv char(6),
1K comments char(12K) var;
dcl indicator(4) fixed bin (15);
exec sql
fetch cursor_a
into :games.sunday.opponents:indicator(1),
:games.sunday.gtime:indicator(2),
:games.sunday.tv:indicator(3),
:games.sunday.comments:indicator(4);
exec sql
fetch cursor_a
into :games.sunday:indicator;

SQL preprocessor
DECLARE TABLE statement

The preprocessor ignores all DECLARE TABLE statements.
DECLARE STATEMENT statement

The preprocessor ignores all DECLARE STATEMENT statements.

CICS Preprocessor
CICS Preprocessor
You can use EXEC CICS statements in PL/I applications that run as transactions
under CICS.
If you do not specify the PP(CICS) option, EXEC CICS statements are parsed and
variable references in them are validated. If they are correct, no messages are
issued as long as the NOCOMPILE option is in effect. Without invoking the CICS
translator, real code cannot be generated.
Programming and compilation considerations

When you are developing programs for execution under CICS, all the EXEC CICS
commands must be translated in one of two ways:
by the command language translator provided by CICS in a job step prior to the
PL/I compilation
by the PL/I CICS preprocessor as part of the PL/I compilation (this requires
CICS TS 2.2 or later)
To use the CICS preprocessor, you must also specify the PP(CICS) compile-time
option.
If your CICS program is a MAIN procedure, you must also compile it with the
SYSTEM(CICS) option. NOEXECOPS is implied with this option and all
parameters passed to the MAIN procedure must be POINTERs. For a description
of the SYSTEM compile-time option, see “SYSTEM” on page 44.
If your CICS program includes any files or uses any macros that contain EXEC
CICS statements, you must also run the MACRO preprocessor before your code is
translated (in either of the ways described above). If you are using the CICS
preprocessor, you can specify this with one PP option as illustrated in the following
example:
pp (macro(...) cics(...) )
Finally, in order to use the CICS preprocessor, you must have the CICS
SDFHLOAD dataset as part of the STEPLIB DD for the PL/I compiler.
CICS preprocessor options

There are many options supported by CICS translator. For a description of these
options, see the CICS Application Programming Guide, SC33-1687-34.
Coding CICS statements in PL/I applications

You can code CICS statements in your PL/I applications using the language
defined in CICS on Open Systems Application Programming Guide, SC33-1568.
Specific requirements for your CICS code are described in the sections that follow.
Embedding CICS statements

If you use the CICS translator, rather than the integrated preprocessor, then the
first statement of your PL/I program must be a PROCEDURE statement. You can
add CICS statements to your program wherever executable statements can appear.
Each CICS statement must begin with EXEC (or EXECUTE) CICS and end with a
semicolon (;).

CICS Preprocessor
For example, the GETMAIN statement might be coded as follows:

EXEC CICS GETMAIN SET(BLK_PTR) LENGTH(STG(BLK));
Comments: In addition to the CICS statements, PL/I comments can be included

in embedded CICS statements wherever a blank is allowed.
Continuation for CICS statements: Line continuation rules for CICS statements
are the same as those for other PL/I statements.
Including code: If included code contains EXEC CICS statements or your

program uses PL/I macros that generate EXEC CICS statements, you must use
one of the following:
The MACRO compile-time option
The MACRO option of the PP option (before the CICS option of the PP option)
Margins: CICS statements must be coded within the columns specified in the
MARGINS compile-time option.
Statement labels: EXEC CICS statements, like PL/I statements, can have a label
prefix.
Writing CICS transactions in PL/I

You can use PL/I with CICS facilities to write application programs (transactions) for
CICS subsystems. If you do this, CICS provides facilities to the PL/I program that
would normally be provided directly by the operating system. These facilities
include most data management facilities and all job and task management facilities.
You must observe the following restrictions of PL/I CICS programs:

Macro-level CICS is not supported.
PL/I input or output cannot be used except for:
– PUT FILE(SYSPRINT)
– CALL PLIDUMP
The PLISRTx built-in subroutines cannot be used.
Routines written in a language other than PL/I cannot be called from a PL/I
CICS program if those routines contain their own EXEC CICS statements. If
you want to communicate with a non-PL/I program that contains EXEC CICS
statements, you must use EXEC CICS LINK or EXEC CICS XCTL to do so.
Although PUT FILE(SYSPRINT) is permitted under CICS, you should generally not
use it in production programs as it will degrade performance.

Chapter 3. Using PL/I cataloged procedures
This chapter describes the standard cataloged procedures supplied by IBM for use
with the IBM Enterprise PL/I for OS/390 compiler. It explains how to invoke them,
and how to temporarily or permanently modify them. The Language Environment
SCEERUN data set must be located in STEPLIB and accessable to the compiler
when you use any of the cataloged procedures described in this chapter.
A cataloged procedure is a set of job control statements, stored in a library, that

includes one or more EXEC statements, each of which can be followed by one or
more DD statements. You can retrieve the statements by naming the cataloged
procedure in the PROC parameter of an EXEC statement in the input stream.
You can use cataloged procedures to save time and reduce Job Control Language
(JCL) errors. If the statements in a cataloged procedure do not match your
requirements exactly, you can easily modify them or add new statements for the
duration of a job. You should review these procedures and modify them to obtain
the most efficient use of the facilities available and to allow for your own
conventions.
IBM-supplied cataloged procedures

The PL/I cataloged procedures supplied for use with Enterprise PL/I for z/OS and
OS/390 are:
IBMZC Compile only
IBMZCB Compile and bind
IBMZCPL Compile, prelink, and link-edit
IBMZCBG Compile, bind, and run
IBMZCPLG Compile, prelink, link-edit, and run
IBMZCPG Compile, prelink, load, and run
Cataloged procedures IBMZCB and IBMZCBG use features of the program

management binder introduced in DFSMS/MVS 1.4 in place of the prelinker
supplied with Language Environment. These procedures produce a program object
in a PDSE.
Cataloged procedures IBMZCPL, IBMZCPLG and IBMZCPG use the prelinker

supplied with Language Environment and produce a load module in PDS. Use
these procedures if you do not want to use a PDSE. The information in this section
describes the procedure steps of the different cataloged procedures. For a
description of the individual statements for compiling and link editing, see “Invoking
the compiler under OS/390 using JCL” on page 104 and OS/390 Language
Environment Programming Guide. These cataloged procedures do not include a
DD statement for the input data set; you must always provide one. The example
shown in Figure 7 on page 88 illustrates the JCL statements you might use to
invoke the cataloged procedure IBMZCBG to compile, bind, and run a PL/I
program.
Enterprise PL/I requires a minimum REGION size of 512K. Large programs require
more storage. If you do not specify REGION on the EXEC statement that invokes
the cataloged procedure you are running, the compiler uses the default REGION

size for your site. The default size might or might not be adequate, depending on
the size of your PL/I program.
If you ccompile your programs with optimization turned on, the REGION size (and
time) required may be much, much larger.
For an example of specifying REGION on the EXEC statement, see Figure 7.
//COLEGO JOB
//STEP1 EXEC IBMZCBG, REGION.PLI=1M
//PLI.SYSIN DD ]
.
.
.
(insert PL/I program to be compiled here)
.
.
.
/]
Figure 7. Invoking a cataloged procedure
Compile only (IBMZC)

The IBMZC cataloged procedure, shown in Figure 8 on page 89, includes only one
procedure step, in which the options specified for the compilation are OBJECT and
OPTIONS. (IBMZPLI is the symbolic name of the compiler.) In common with the
other cataloged procedures that include a compilation procedure step, IBMZC does
not include a DD statement for the input data set; you must always supply an
appropriate statement with the qualified ddname PLI.SYSIN.
The OBJECT compile-time option causes the compiler to place the object module,
in a syntax suitable for input to the linkage editor, in the standard data set defined
by the DD statement with the name SYSLIN. This statement defines a temporary
data set named &&LOADSET on a sequential device; if you want to retain the
object module after the end of your job, you must substitute a permanent name for
&&LOADSET (that is, a name that does not start with &&) and specify KEEP in the
appropriate DISP parameter for the last procedure step that used the data set. You
can do this by providing your own SYSLIN DD statement, as shown below. The
data set name and disposition parameters on this statement will override those on
the IBMZC procedure SYSLIN DD statement. In this example, the compile step is
the only step in the job.
//PLICOMP EXEC IBMZC
//PLI.SYSLIN DD DSN=MYPROG,DISP=(MOD,KEEP)
//PLI.SYSIN DD ...
The term MOD in the DISP parameter in Figure 8 on page 89 allows the compiler
to place more than one object module in the data set, and PASS ensures that the
data set is available to a later procedure step providing a corresponding DD
statement is included there.
The SYSLIN SPACE parameter allows an initial allocation of 1 cylinder and, if

necessary, 15 further allocations of 1 cylinder (a total of 16 cylinders).

//IBMZC PROC LNGPRFX='IBMZ.V3R2MK',LIBPRFX='CEE',
// SYSLBLK=32KK
//]
//]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]
//] ]
//] LICENSED MATERIALS - PROPERTY OF IBM ]
//] ]
//] 5655-H31 (C) COPYRIGHT IBM CORP. 1999, 2KK1 ]
//] ALL RIGHTS RESERVED. ]
//] ]
//] US GOVERNMENT USERS RESTRICTED RIGHTS - USE, ]
//] DUPLICATION OR DISCLOSURE RESTRICTED BY GSA ]
//] ADP SCHEDULE CONTRACT WITH IBM CORP. ]
//] ]
//]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]
//]
//] IBM ENTERPRISE PL/I FOR Z/OS AND OS/39K
//] VERSION 3 RELEASE 2 MODIFICATION K
//]
//] COMPILE A PL/I PROGRAM
//]
//] PARAMETER DEFAULT VALUE USAGE
//] LNGPRFX IBMZ.V3R2MK PREFIX FOR LANGUAGE DATA SET NAMES
//] LIBPRFX CEE PREFIX FOR LIBRARY DATA SET NAMES
//] SYSLBLK 32KK BLKSIZE FOR OBJECT DATA SET
//]
//] USER MUST SUPPLY //PLI.SYSIN DD STATEMENT THAT IDENTIFIES
//] LOCATION OF COMPILER INPUT
//]
//]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]
//] COMPILE STEP
//]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]
//PLI EXEC PGM=IBMZPLI,PARM='OBJECT,OPTIONS',REGION=512K
//STEPLIB DD DSN=&LNGPRFX..SIBMZCMP,DISP=SHR
// DD DSN=&LIBPRFX..SCEERUN,DISP=SHR
//SYSPRINT DD SYSOUT=]
//SYSOUT DD SYSOUT=]
//SYSLIN DD DSN=&&LOADSET,DISP=(MOD,PASS),UNIT=SYSALLDA,
// SPACE=(CYL,(1,1)),DCB=(LRECL=8K,BLKSIZE=&SYSLBLK)
//SYSUT1 DD DSN=&&SYSUT1,UNIT=SYSALLDA,
// SPACE=(1K24,(2KK,5K),,CONTIG,ROUND),DCB=BLKSIZE=1K24
Figure 8. Cataloged Procedure IBMZC
Compile and bind (IBMZCB)

The IBMZCB cataloged procedure, shown in Figure 9 on page 90, includes two
procedure steps: PLI, which is identical to cataloged procedure IBMZC, and BIND,
which invokes the Program Management binder (symbolic name IEWBLINK) to bind
the object module produced in the first procedure step.
Input data for the compilation procedure step requires the qualified ddname
PLI.SYSIN. The COND parameter in the EXEC statement BIND specifies that this
procedure step should be bypassed if the return code produced by the compiler is
greater than 8 (that is, if a severe or unrecoverable error occurs during
compilation).
Chapter 3. Using PL/I cataloged procedures 89

//IBMZCB PROC LNGPRFX='IBMZ.V3R2MK',LIBPRFX='CEE',
// SYSLBLK=32KK,GOPGM=GO
//]
//]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]
//] ]
//] ]
//] ]
//] ]
//]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]
//]
//]
//] COMPILE AND BIND A PL/I PROGRAM
//]
//] GOPGM GO MEMBER NAME FOR PROGRAM OBJECT
//]
//]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]
//] COMPILE STEP
//]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]
//]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]
//] BIND STEP
//]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]
//BIND EXEC PGM=IEWBLINK,COND=(8,LT,PLI),
// PARM='XREF,COMPAT=PM3',REGION=2K48K
//SYSLIB DD DSN=&LIBPRFX..SCEELKED,DISP=SHR
//SYSLIN DD DSN=].PLI.SYSLIN,DISP=(OLD,DELETE)
// DD DDNAME=SYSIN
//SYSLMOD DD DSN=&&GOSET(&GOPGM),DISP=(MOD,PASS),UNIT=SYSALLDA,
// SPACE=(1K24,(5K,2K,1)),DSNTYPE=LIBRARY
//SYSDEFSD DD DUMMY
//SYSIN DD DUMMY
Figure 9. Cataloged Procedure IBMZCB
The Program Management binder always places the program objects it creates in
the standard data set defined by the DD statement with the name SYSLMOD. This
statement in the cataloged procedure specifies a new temporary library &&GOSET,
in which the program object will be placed and given the member name GO. In
specifying a temporary library, the cataloged procedure assumes that you will run
the program object in the same job; if you want to retain the program object, you
must substitute your own statement for the DD statement with the name
SYSLMOD.

Compile, bind, and run (IBMZCBG)
The IBMZCBG cataloged procedure, shown in Figure 10, includes three procedure
steps: PLI, BIND, and GO. PLI and BIND are identical to the two procedure steps
of IBMZCB, and GO runs the program object created in the step BIND. The GO
step is executed only if no severe or unrecoverable errors occurred in the
preceding procedure steps.
Input data for the compilation procedure step should be specified in a DD statement
with the name PLI.SYSIN, and for the GO step in a DD statement with the name
GO.SYSIN.
//IBMZCBG PROC LNGPRFX='IBMZ.V3R2MK',LIBPRFX='CEE',

// SYSLBLK=32KK,GOPGM=GO
//]
//]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]
//] ]
//] ]
//] ]
//] ]
//]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]
//]
//]
//] COMPILE, BIND, AND RUN A PL/I PROGRAM
//]
//] GOPGM GO MEMBER NAME FOR PROGRAM OBJECT
//]
//]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]
//] COMPILE STEP
//]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]
Figure 10 (Part 1 of 2). Cataloged Procedure IBMZCBG

//]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]
//] BIND STEP
//]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]
//BIND EXEC PGM=IEWBLINK,COND=(8,LT,PLI),
// PARM='XREF,COMPAT=PM3',REGION=2K48K
//SYSLIN DD DSN=].PLI.SYSLIN,DISP=(OLD,DELETE)
// DD DDNAME=SYSIN
// SPACE=(1K24,(5K,2K,1)),DSNTYPE=LIBRARY
//SYSDEFSD DD DUMMY
//SYSIN DD DUMMY
//]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]
//] RUN STEP
//]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]
//GO EXEC PGM=].BIND.SYSLMOD,COND=((8,LT,PLI),(8,LE,BIND)),
// REGION=2K48K
//STEPLIB DD DSN=&LIBPRFX..SCEERUN,DISP=SHR
//CEEDUMP DD SYSOUT=]
//SYSUDUMP DD SYSOUT=]
Figure 10 (Part 2 of 2). Cataloged Procedure IBMZCBG
Compile, prelink, and link-edit (IBMZCPL)

The IBMZCPL cataloged procedure, shown in Figure 11, includes three procedure
steps: PLI, which is identical to cataloged procedure IBMZC; PLKED, which
invokes the Language Environment prelinker; and LKED, which invokes the linkage
editor (symbolic name IEWL) to link-edit the object module produced in the first
procedure step.
Input data for the compilation procedure step requires the qualified ddname
PLI.SYSIN. The COND parameter in the EXEC statement LKED specifies that this
procedure step should be bypassed if the return code produced by the compiler is
greater than 8 (that is, if a severe or unrecoverable error occurs during
compilation).
//IBMZCPL PROC LNGPRFX='IBMZ.V3R2MK',LIBPRFX='CEE',

// SYSLBLK=32KK,PLANG=EDCPMSGE,GOPGM=GO
//]
//]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]
//] ]
//] ]
//] ]
//] ]
//]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]

//]
//]
//] COMPILE, PRELINK, LINK-EDIT A PL/I PROGRAM
//]
//] PLANG EDCPMSGE PRELINKER MESSAGES MEMBER NAME
//] GOPGM GO MEMBER NAME FOR LOAD MODULE
//]
//]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]
//] COMPILE STEP
//]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]
//]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]
//] PRE-LINK-EDIT STEP
//]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]
//PLKED EXEC PGM=EDCPRLK,COND=(8,LT,PLI),REGION=2K48K
//SYSMSGS DD DSN=&LIBPRFX..SCEEMSGP(&PLANG),DISP=SHR
//SYSLIB DD DUMMY
//SYSMOD DD DSN=&&PLNK,DISP=(,PASS),
// UNIT=SYSALLDA,SPACE=(CYL,(1,1)),
// DCB=(RECFM=FB,LRECL=8K,BLKSIZE=&SYSLBLK)
//SYSIN DD DSN=&&LOADSET,DISP=(OLD,DELETE)
//]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]
//] LINK-EDIT STEP
//]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]
//LKED EXEC PGM=IEWL,PARM='XREF',COND=((8,LT,PLI),(8,LE,PLKED)),
// REGION=2K48K
//SYSLIN DD DSN=].PLKED.SYSMOD,DISP=(OLD,DELETE)
// DD DDNAME=SYSIN
// SPACE=(1K24,(5K,2K,1))
//SYSUT1 DD DSN=&&SYSUT1,UNIT=SYSALLDA,SPACE=(1K24,(2KK,2K)),
// DCB=BLKSIZE=1K24
//SYSIN DD DUMMY
Figure 11 (Part 2 of 2). Cataloged Procedure IBMZCPL
The linkage editor always places the load modules it creates in the standard data
set defined by the DD statement with the name SYSLMOD. This statement in the
cataloged procedure specifies a new temporary library &&GOSET, in which the
load module will be placed and given the member name GO. In specifying a
temporary library, the cataloged procedure assumes that you will run the load
module in the same job; if you want to retain the module, you must substitute your
own statement for the DD statement with the name SYSLMOD.
The SYSLIN DD statement in Figure 11 on page 92 shows how to concatenate a

data set defined by a DD statement named SYSIN with the primary input (SYSLIN)
to the linkage editor. You could place linkage editor control statements in the input

stream by this means, as described in the OS/390 Language Environment
Programming Guide.
Compile, prelink, link-edit, and run (IBMZCPLG)

The IBMZCPLG cataloged procedure, shown in Figure 12, includes four procedure
steps: PLI, PLKED, LKED, and GO. PLI, PLKED, and LKED are identical to the
three procedure steps of IBMZCPL, and GO runs the load module created in the
step LKED. The GO step is executed only if no severe or unrecoverable errors
occurred in the preceding procedure steps.
Input data for the compilation procedure step should be specified in a DD statement
with the name PLI.SYSIN, and for the GO step in a DD statement with the name
GO.SYSIN.
//IBMZCPLG PROC LNGPRFX='IBMZ.V3R2MK',LIBPRFX='CEE',

// SYSLBLK=32KK,PLANG=EDCPMSGE,GOPGM=GO
//]
//]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]
//] ]
//] ]
//] ]
//] ]
//]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]
//]
//]
//] COMPILE, PRELINK, LINK-EDIT AND RUN A PL/I PROGRAM
//]
//] GOPGM GO MEMBER NAME FOR LOAD MODULE
//]
//]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]
//] COMPILE STEP
//]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]
Figure 12 (Part 1 of 2). Cataloged Procedure IBMZCPLG

//]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]
//]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]
//SYSLIB DD DUMMY
//SYSMOD DD DSN=&&PLNK,DISP=(,PASS),UNIT=SYSALLDA,SPACE=(CYL,(1,1)),
//SYSIN DD DSN=].PLI.SYSLIN,DISP=(OLD,DELETE)
//]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]
//] LINK-EDIT STEP
//]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]
//LKED EXEC PGM=IEWL,PARM='XREF',COND=((8,LT,PLI),(8,LE,PLKED)),
// REGION=2K48K
// DD DDNAME=SYSIN
// SPACE=(1K24,(5K,2K,1))
//SYSUT1 DD DSN=&&SYSUT1,UNIT=SYSALLDA,SPACE=(1K24,(2KK,2K)),
// DCB=BLKSIZE=1K24
//SYSIN DD DUMMY
//]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]
//] RUN STEP
//]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]
//GO EXEC PGM=].LKED.SYSLMOD,
// COND=((8,LT,PLI),(8,LE,PLKED),(8,LE,LKED)),
// REGION=2K48K
Figure 12 (Part 2 of 2). Cataloged Procedure IBMZCPLG
Compile, prelink, load and run (IBMZCPG)

The IBMZCPG cataloged procedure, shown in Figure 13 on page 96, achieves the
same results as IBMZCPLG but uses the loader instead of the linkage editor.
Instead of using four procedure steps (compile, prelink, link-edit, and run), it has
only three (compile, prelink, and load-and-run). The third procedure step runs the
loader program. The loader program processes the object module produced by the
compiler and runs the resultant executable program immediately. You must provide
input data for the compilation step by supplying a qualified ddname PLI.SYSIN.
The use of the loader imposes certain restrictions on your PL/I program; before
using this cataloged procedure, see OS/390 Language Environment Programming
Guide, which explains how to use the loader.

//IBMZCPG PROC LNGPRFX='IBMZ.V3R2MK',LIBPRFX='CEE',
// SYSLBLK=32KK,PLANG=EDCPMSGE
//]
//]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]
//] ]
//] ]
//] ]
//] ]
//]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]
//]
//]
//] COMPILE, PRELINK, LOAD AND RUN A PL/I PROGRAM
//]
//]
//]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]
//] COMPILE STEP
//]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]
//]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]
//]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]
//SYSLIB DD DUMMY
//SYSMOD DD DSN=&&PLNK,DISP=(,PASS),
// UNIT=SYSALLDA,SPACE=(CYL,(1,1)),
//SYSIN DD DSN=].PLI.SYSLIN,DISP=(OLD,DELETE)

//]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]
//] LOAD AND RUN STEP
//]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]
//GO EXEC PGM=LOADER,PARM='MAP,PRINT',
// COND=((8,LT,PLI),(8,LE,PLKED)),
// REGION=2K48K
//SYSLOUT DD SYSOUT=]
Figure 13 (Part 2 of 2). Cataloged Procedure IBMZCPG
For more information on other cataloged procedures, see OS/390 Language

Environment Programming Guide.
Invoking a cataloged procedure

To invoke a cataloged procedure, specify its name in the PROC parameter of an
EXEC statement. For example, to use the cataloged procedure IBMZC, you could
include the following statement in the appropriate position among your other job
control statements in the input stream:
//stepname EXEC PROC=IBMZC
You do not need to code the keyword PROC. If the first operand in the EXEC
statement does not begin PGM= or PROC=, the job scheduler interprets it as the
name of a cataloged procedure. The following statement is equivalent to that given
above:
//stepname EXEC IBMZC
If you include the parameter MSGLEVEL=1 in your JOB statement, the operating
system will include the original EXEC statement in its listing, and will add the
statements from the cataloged procedure. In the listing, cataloged procedure
statements are identified by XX or X/ as the first two characters; X/ signifies a
statement that was modified for the current invocation of the cataloged procedure.
You might be required to modify the statements of a cataloged procedure for the
duration of the job step in which it is invoked, either by adding DD statements or by
overriding one or more parameters in the EXEC or DD statements. For example,
cataloged procedures that invoke the compiler require the addition of a DD
statement with the name SYSIN to define the data set containing the source
statements. Also, whenever you use more than one standard link-edit procedure
step in a job, you must modify all but the first cataloged procedure that you invoke
if you want to run more than one of the load modules.
Specifying multiple invocations

You can invoke different cataloged procedures, or invoke the same cataloged
procedure several times, in the same job. No special problems are likely to arise
unless more than one of these cataloged procedures involves a link-edit procedure
step, in which case you must take the following precautions to ensure that all your
load modules can be run.

When the linkage editor creates a load module, it places the load module in the
standard data set defined by the DD statement with the name SYSLMOD. When
the binder creates a program object, it places the program object in the PDSE
defined by the DD statement with the name SYSLMOD. In the absence of a
linkage editor NAME statement, the linkage editor or the binder uses the member
name specified in the DSNAME parameter as the name of the module. In the
standard cataloged procedures, the DD statement with the name SYSLMOD always
specifies a temporary library &&GOSET with the member name GO.
If you use the cataloged procedure IBMZCBG twice within the same job to compile,
bind, and run two PL/I programs, and do not name each of the two program objects
that the binder creates, the first program object runs twice, and the second one not
at all.
To prevent this, use one of the following methods:

Delete the library &&GOSET at the end of the GO step. In the first invocation
of the cataloged procedure at the end of the GO step, add a DD statement with
the syntax:
//GO.SYSLMOD DD DSN=&&GOSET,
// DISP=(OLD,DELETE)
Modify the DD statement with the name SYSLMOD in the second and
subsequent invocations of the cataloged procedure so as to vary the names of
the load modules. For example:
//BIND.SYSLMOD DD DSN=&&GOSET(GO1)
and so on.
Use the NAME linkage editor option to give a different name to each program
object and change each job step EXEC statement to specify the running of the
program object with the name for that job step.
To assign a membername to the program object, you can use the linkage editor
NAME option with the DSNAME parameter on the SYSLMOD DD statement.
When you use this procedure, the membername must be identical to the name on
the NAME option if the EXEC statement that runs the program refers to the
SYSLMOD DD statement for the name of the module to be run.
Another option is to give each program a different name by using GOPGM on the
EXEC procedure statement. For example:
// EXEC IBMZCBG,GOPGM=GO2
Modifying the PL/I cataloged procedures

You can modify a cataloged procedure temporarily by including parameters in the
EXEC statement that invokes the cataloged procedure, or by placing additional DD
statements after the EXEC statement. Temporary modifications apply only for the
duration of the job step in which the procedure is invoked. They do not affect the
master copy of the cataloged procedure in the procedure library.
Temporary modifications can apply to EXEC or DD statements in a cataloged

procedure. To change a parameter of an EXEC statement, you must include a
corresponding parameter in the EXEC statement that invokes the cataloged
procedure. To change one or more parameters of a DD statement, you must

include a corresponding DD statement after the EXEC statement that invokes the
cataloged procedure. Although you cannot add a new EXEC statement to a
cataloged procedure, you can always include additional DD statements.
EXEC statement
If a parameter of an EXEC statement that invokes a cataloged procedure has an
unqualified name, the parameter applies to all the EXEC statements in the
cataloged procedure. The effect on the cataloged procedure depends on the
parameters, as follows:
PARM applies to the first procedure step and nullifies any other PARM
parameters.
COND and ACCT apply to all the procedure steps.
TIME and REGION apply to all the procedure steps and override existing
values.
For example, the statement:

//stepname EXEC IBMZCBG,PARM='OFFSET',REGION=512K
Invokes the cataloged procedure IBMZCBG.
Substitutes the option OFFSET for OBJECT and OPTIONS in the EXEC
statement for procedure step PLI.
Nullifies the PARM parameter in the EXEC statement for procedure step BIND.
Specifies a region size of 512K for all three procedure steps.
To change the value of a parameter in only one EXEC statement of a cataloged

procedure, or to add a new parameter to one EXEC statement, you must identify
the EXEC statement by qualifying the name of the parameter with the name of the
procedure step. For example, to alter the region size for procedure step PLI only in
the preceding example, code:
//stepname EXEC PROC=IBMZCBG,PARM='OFFSET',REGION.PLI=512K
A new parameter specified in the invoking EXEC statement overrides completely

the corresponding parameter in the procedure EXEC statement.
You can nullify all the options specified by a parameter by coding the keyword and
equal sign without a value. For example, to suppress the bulk of the linkage editor
listing when invoking the cataloged procedure IBMZCBG, code:
//stepname EXEC IBMZCBG,PARM.BIND=
DD statement
To add a DD statement to a cataloged procedure, or to modify one or more
parameters of an existing DD statement, you must include a DD statement with the
form procstepname.ddname in the appropriate position in the input stream. If ddname
is the name of a DD statement already present in the procedure step identified by
procstepname, the parameters in the new DD statement override the corresponding
parameters in the existing DD statement; otherwise, the new DD statement is
added to the procedure step. For example, the statement:
//PLI.SYSIN DD ]

adds a DD statement to the procedure step PLI of cataloged procedure IBMZC and
the effect of the statement:
//PLI.SYSPRINT DD SYSOUT=C
is to modify the existing DD statement SYSPRINT (causing the compiler listing to
be transmitted to the system output device of class C).
Overriding DD statements must appear after the procedure invocation and in the
same order as they appear in the cataloged procedure. Additional DD statements
can appear after the overriding DD statements are specified for that step.
To override a parameter of a DD statement, code either a revised form of the

parameter or a replacement parameter that performs a similar function (for
example, SPLIT for SPACE). To nullify a parameter, code the keyword and equal
sign without a value. You can override DCB subparameters by coding only those
you wish to modify; that is, the DCB parameter in an overriding DD statement does
not necessarily override the entire DCB parameter of the corresponding statement
in the cataloged procedures.

Chapter 4. Compiling your program
This chapter describes how to invoke the compiler under OS/390 UNIX System
Services (OS/390 UNIX) and the job control statements used for compiling under
OS/390. The Language Environment SCEERUN data set must be accessible to
the compiler when you compile your program.
Invoking the compiler under OS/390 UNIX

To compile your program under the OS/390 UNIX environment, use the pli
command.
──pli──┬─────────────────────────────────────────┬─────────────────────────────

│ ┌──
─────────────────────┐ ┌──────────────┐ │
└───command_line_option─┴────input_file─┴─┘
command_line_option
You can specify a command_line_option in the following ways:
-qoption
Option flag (usually a single letter preceded by -)
If you choose to specify compile-time options on the command line, the format
differs from either setting them in your source file using %PROCESS
statements. See “Specifying compile-time options under OS/390 UNIX” on
page 102.
input_file
The OS/390 UNIX file specification for your program files. If you omit the
extension from your file specification, the compiler assumes an extension of
.pli. If you omit the complete path, the current directory is assumed.
Input files
The pli command compiles PL/I source files, links the resulting object files with any
object files and libraries specified on the command line in the order indicated, and
produces a single executable file.
The pli command accepts the following types of files:
Source files—.pli
All .pli files are source files for compilation. The pli command sends source
files to the compiler in the order they are listed. If the compiler cannot find a
specified source file, it produces an error message and the pli command
proceeds to the next file if one exists.
Object files—.o
All .o files are object files. The pli command sends all object files along with
library files to the linkage editor at link-edit time unless you specify the -c option.
After it compiles all the source files, the compiler invokes the linkage editor to
link-edit the resulting object files with any object files specified in the input file
list, and produces a single executable output file.

Specifying compile-time options
Library files—.a
The pli command sends all of the library files (.a files) to the linkage editor at
link-edit time.
Specifying compile-time options under OS/390 UNIX

Enterprise PL/I provides compile-time options to change any of the compiler's
default settings. You can specify options on the command line, and they remain in
effect for all compilation units in the file, unless %PROCESS statements in your
source program override them.
Refer to “Compile-time option descriptions” on page 3 for a description of these

options.
When you specify options on the command line, they override the default settings
of the option. They are overridden by options set in the source file.
You can specify compile-time options on the command line in three ways:
-qoption_keyword (compiler-specific)
Single and multiletter flags
-q@/u/myopts.txt
-qoption_keyword
You can specify options on the command line using the -qoption format.

──-q──option_keyword──┬─────────────────────────────────┬──────────────────────

│ ┌─:──────────────────────┐ │
└─ = ────┬─suboption──────────┬─┴─┘
└─suboption=argument─┘
You can have multiple -qoptions on the same command line, but they must be
separated by blanks. Option keywords can appear in either uppercase or
lowercase, but you must specify the -q in lowercase.
Some compile-time options allow you to specify suboptions. These suboptions are
indicated on the command line with an equal sign following the -qoption_keyword.
Multiple suboptions must be separated with a colon(:) and no intervening blanks.
An option, for example, that contains multiple suboptions is RULES (“RULES” on

page 37). To specify RULES(LAXDCL) on the command line, you would enter:
-qrules=ibm:laxdcl
The LIMITS option (“LIMITS” on page 24) is slightly more complex since each of its
suboptions also has an argument. You would specify
LIMITS(EXTNAME(31),FIXEDDEC(15)) on the command line as shown in the
following example:
-qlimits=extname=31:fixeddec=15

Single and multiletter flags
The OS/390 UNIX family of compilers uses a number of common conventional
flags. Each language has its own set of additional flags.
Some flag options have arguments that form part of the flag, for example:
pli samp.pli -I/home/test3/include
In this case, /home/test3/include is an include directory to be searched for
INCLUDE files.
You can specify flags that do not take arguments in one string:
pli -Ogc samp1.pli
Specifying the flags in one string has the same effect as specifying the same
options separately.
pli -O -g -c samp1.pli
Both examples compile the PL/I source file samp1.pli with optimization (-O) and
produce symbolic information used by the debugger (-g), but do not invoke the
linkage editor (-c).
You can specify one flag option that takes arguments as part of a single string, but
it must be the last option specified. For example, you can use the -I flag (to specify
the name of an include directory to be searched for INCLUDE files) together with
the other flags, only if the -I flag and its argument are specified last:
pli -OgI/home/test3/include
The string of flags in the preceding example is equivalent to the following:
pli -O -g -I/home/test3/include
Table 11. Compile-time option flags supported by Enterprise PL/I under OS/390 UNIX
Option Description
-c Compile only.
-e Create names and entries for a FETCHable load module.
-g Produce symbolic information used by the debugger. This option is equivalent to
-qGN.
-I<dir>* Add path <dir> to the directories to be searched for INCLUDE files. -I must be
followed by a path and only a single path is allowed per -I option. To add
multiple paths, use multiple -I options. There shouldn't be any spaces between
-I and the path name.
-O, -O2 Optimize generated code. This option is equivalent to -qOPT=2.
-q<option>* Pass it to the compiler. <option> is a compile-time option. Each option should
be delimited by a comma and each suboption should be delimited by an equal
sign or colon. There shouldn't be any spaces between -q and <option>.
-v Display compile and link steps and execute them.
-# Display compile and link steps, but do not execute them.
Note: *You must specify an argument where indicated; otherwise, the results are unpredictable.
Chapter 4. Compiling your program 103

Invoking the compiler under OS/390 using JCL
Although you will probably use cataloged procedures rather than supply all the JCL
required for a job step that invokes the compiler, you should be familiar with these
statements so that you can make the best use of the compiler and, if necessary,
override the statements of the cataloged procedures.
So-called "batch compilation", whereby one compilation produced more than one
object deck, is not supported.
The following section describes the JCL needed for compilation. The IBM-supplied
cataloged procedures described in “IBM-supplied cataloged procedures” on page
87 contain these statements. You need to code them yourself only if you are not
using the cataloged procedures.
EXEC statement
The basic EXEC statement is:
//stepname EXEC PGM
512K is required for the REGION parameter of this statement.
If you compile your programs with optimization turned on, the REGION size (and
time) required may be much, much larger.
The PARM parameter of the EXEC statement can be used to specify one or more
of the optional facilities provided by the compiler. These facilities are described
under “Specifying options in the EXEC statement” on page 107. See Chapter 1,
“Using compiler options and facilities” on page 3 for a description of the options.
DD statements for the standard data sets

The compiler requires several standard data sets, the number of data sets depends
on the optional facilities specified. You must define these data sets in DD
statements with the standard ddnames shown, together with other characteristics of
the data sets, in Table 12 on page 105. The DD statements SYSIN, SYSUT1, and
SYSPRINT are always required.
You can store any of the standard data sets on a direct-access device, but you
must include the SPACE parameter in the DD statement. This parameter defines
the data set to specify the amount of auxiliary storage required. The amount of
auxiliary storage allocated in the IBM-supplied cataloged procedures should suffice
for most applications.

Table 12. Compiler standard data sets
Contents of data Possible Record Record
Standard set device format size BLKSIZE
DDNAME classes1 (RECFM) (LRECL)
SYSIN Input to the compiler SYSSQ F,FB,U <101(100) —
VB,V <105(104)
SYSLIN Object module SYSSQ FB 80 80
SYSPUNCH Preprocessor output, SYSSQ FB 80 80
compiler output SYSCP
SYSUT1 Temporary workfile SYSDA F 4051 —
SYSPRINT Listing, including SYSSQ VBA 137 —
messages
SYSLIB Source statements for SYSDA F,FB,U <101 —
preprocessor V,VB <105
Notes:
The only value for compile-time SYSPRINT that can be overridden is BLKSIZE.
1. The possible device classes are:
SYSSQ Sequential device
SYSDA Direct-access device
SYSCP Card-punch device.
Block size can be specified except for SYSUT1. The block size and logical record length for
SYSUT1 is chosen by the compiler.
Input (SYSIN)
Input to the compiler must be a data set defined by a DD statement with the name
SYSIN. This data set must have CONSECUTIVE organization. The input must be
one or more external PL/I procedures. If you want to compile more than one
external procedure in a single job or job step, precede each procedure, except
possibly the first, with a %PROCESS statement.
80-byte records are commonly used as the input medium for PL/I source programs.
The input data set can be on a direct-access device or some other sequential
media. The input data set can contain either fixed-length records (blocked or
unblocked), variable-length records (coded or uncoded), or undefined-length
records. The maximum record size is 100 bytes.
When data sets are concatenated for input to the compiler, the concatenated data
sets must have similar characteristics (for example, block size and record format).
Output (SYSLIN, SYSPUNCH)

Output in the form of one or more object modules from the compiler will be stored
in the data set SYSLIN if you specify the OBJECT compile-time option. This data
set is defined by the DD statement.
The object module is always in the form of 80-byte fixed-length records, blocked or
unblocked. If the BLKSIZE is specified for SYSLIN and is something other than 80,
then the LRECL must be specified as 80.
The SYSLIN DD must specify a sequential dataset, not a PDS or PDSE.

The data set defined by the DD statement with the name SYSPUNCH is also used
to store the output from the preprocessor if you specify the MDECK compile-time
option.
Temporary workfile (SYSUT1)

The compiler requires a data set for use as a temporary workfile. It is defined by a
DD statement with the name SYSUT1, and is known as the spill file. It must be on
a direct-access device, and must not be allocated as a multi-volume data set.
The spill file is used as a logical extension to main storage and is used by the
compiler and by the preprocessor to contain text and dictionary information. The
LRECL and BLKSIZE for SYSUT1 is chosen by the compiler based on the amount
of storage available for spill file pages.
The DD statements given in this publication and in the cataloged procedures for
SYSUT1 request a space allocation in blocks of 1024 bytes. This is to insure that
adequate secondary allocations of direct-access storage space are acquired.
Listing (SYSPRINT)
The compiler generates a listing that includes all the source statements that it
processed, information relating to the object module, and, when necessary,
messages. Most of the information included in the listing is optional, and you can
specify those parts that you require by including the appropriate compile-time
options. The information that can appear, and the associated compile-time options,
are described under “Using the compiler listing” on page 55.
You must define the data set, in which you wish the compiler to store its listing, in a
DD statement with the name SYSPRINT. This data set must have CONSECUTIVE
organization. Although the listing is usually printed, it can be stored on any
sequential or direct-access device. For printed output, the following statement will
suffice if your installation follows the convention that output class A refers to a
printer:
//SYSPRINT DD SYSOUT=A
Source Statement Library (SYSLIB)

If you use the MACRO preprocessor %INCLUDE statement to introduce source
statements into the PL/I program from a library, you can either define the library in
a DD statement with the name SYSLIB, or you can choose your own ddname (or
ddnames) and specify a ddname in each %INCLUDE statement. (For further
information on the MACRO and other preprocessors, see Chapter 2, “PL/I
preprocessors” on page 62.)
If the statements are included from a SYSLIB, they must have a form that is similar
to the %INCLUDE statement. For example, they must have the same record
format (fixed, variable, undefined), the same logical record length, and matching left
and right margins.
The BLOCKSIZE of the library must be less than or equal to 32,760 bytes.

Specifying options
For each compilation, the IBM-supplied or installation default for a compile-time
option applies unless it is overridden by specifying the option in a %PROCESS
statement or in the PARM parameter of an EXEC statement.
An option specified in the PARM parameter overrides the default value, and an
option specified in a %PROCESS statement overrides both that specified in the
PARM parameter and the default value.
Note: When conflicting attributes are specified either explicitly or implicitly by the
specification of other options, the latest implied or explicit option is
accepted. No diagnostic message is issued to indicate that any options are
overridden in this way.
Specifying options in the EXEC statement

To specify options in the EXEC statement, code PARM= followed by the list of
options, in any order separating the options with commas and enclosing the list
within single quotation marks, for example:
//STEP1 EXEC PGM=IBMZPLI,PARM='OBJECT,LIST'
Any option that has quotation marks, for example MARGINI('c'), must have the
quotation marks duplicated. The length of the option list must not exceed 100
characters, including the separating commas. However, many of the options have
an abbreviated syntax that you can use to save space. If you need to continue the
statement onto another line, you must enclose the list of options in parentheses
(instead of in quotation marks) enclose the options list on each line in quotation
marks, and ensure that the last comma on each line except the last line is outside
of the quotation marks. An example covering all the above points is as follows:
//STEP1 EXEC PGM=IBMZPLI,PARM=('AG,A',
// 'C,F(I)',
// 'M,MI(''X''),NEST,STG,X')
If you are using a cataloged procedure, and want to specify options explicitly, you
must include the PARM parameter in the EXEC statement that invokes it, qualifying
the keyword PARM with the name of the procedure step that invokes the compiler.
For example:
//STEP1 EXEC nnnnnnn,PARM.PLI='A,LIST'
Specifying options in the EXEC statement using options file

Another way to specify options in the EXEC statement is by declaring all your
options in an options file and coding the following:
//STEP1 EXEC PGM=IBMZPLI,PARM='+DD:OPTIONS'
This method allows you to provide a consistent set of options that you frequently
use. This is especially effective if you want other programmers to use a common
set of options. It also gets you past the 100-character limit.
The MARGINS option does not apply to options files: the data in column 1 will be
read as part of the options. Also, if the file is F-format, any data after column 72 will
be ignored.

The parm string can contain "normal" options and can point to more than one
options file. For instance, to specify the option LIST as well as from both the file in
the GROUP DD and in the PROJECT DD, you could specify
PARM='LIST +DD:GROUP +DD:PROJECT'
The options in the PROJECT file would have precedence over options in the
GROUP file.
Also, in this case, the LIST option might be turned off by a NOLIST option specified
in either of the options files. To insure that the LIST option is on, you could specify
PARM='+DD:GROUP +DD:PROJECT LIST'
Options files may also be used under USS. For example, in USS, to compile
sample.pli with options from the file /u/pli/group.opt, you would specify
pli -q+/u/pli/group.opt sample.pli
Earlier releases of the compiler used the character '@' as the trigger character that
preceded the options file specification. This character is not part of the invariant
set of ebcdic code points, and for that reason the character '+', which is invariant, is
preferred. However, the '@' character may be still be used as long as it is
specified with the hex value '7C'x.
Compiling for CICS

When coding a CICS transaction in PL/I, all of your EXEC CICS commands must
be translated in one of two ways:
by the command language translator provided by CICS in a job step prior to the
PL/I compilation
by the PL/I CICS preprocessor as part of the PL/I compilation (this requires
CICS TS 2.2 or later)
You can find information on the CICS Command Language Translator in
CICS/ESA Application Programmer's Reference Manual.
If your CICS program is a MAIN procedure, you must also compile it with the
SYSTEM(CICS) option. NOEXECOPS is implied with this option and all
parameters passed to the MAIN procedure must be POINTERs. For a description
of the SYSTEM compile-time option, see “SYSTEM” on page 44.

Chapter 5. Link-editing and running
After compilation, your program consists of one or more object modules that
contain unresolved references to each other, as well as references to the Language
Environment run-time library. These references are resolved during link-editing
(statically) or during execution (dynamically). There are two ways to link-edit
statically:
1. Use the prelinker prior to the traditional link step
2. Link without the prelinker, which is similar to linking with PL/I for MVS & VM
except that depending on which compile-time options you use, you may now
need to use a PDSE to hold the resultant load module.
After you compile your PL/I program, the next step is to link and run your program
with test data to verify that it produces the results you expect. When using
Enterprise PL/I we recommend you select the method of linking without the
prelinker (as described in Item 2 above).
Language Environment provides the run-time environment and services you need
to execute your program. For instructions on linking and running PL/I and all other
Language Environment-conforming language programs, refer to OS/390 Language
Environment Programming Guide. For information about migrating your existing
PL/I programs to Language Environment, see Enterprise PL/I for z/OS and OS/390
Compiler and Run-Time Migration Guide.
Link-edit considerations
If you compile with the option RENT or the option LIMITS(EXTNAME(n)) with n > 8,
then you must use the prelinker or use a PDSE for your linker output.
Using the binder

You must place the binder output into a PDSE.
When linking a DLL, you must specify any needed definition side-decks during the
bind step.
You can use the binder in place of the prelinker and linkage-editor, with the
following exceptions:
CICS Prior to CICS 1.3, PDSEs are not supported. From CICS Transaction
Server 1.3 onwards, there is support in CICS for PDSEs. Please refer to the
CICS Transaction Server for OS/390 Release Guide, GC34-5701, where there
are several references to PDSEs, and a list of prerequisite APAR fixes.
MTF MTF does not support PDSEs. If your program targets MTF, you cannot
use the binder.

Using the prelinker
If you use the prelinker, you must prelink together in one job step all object decks
defining external references in any of the input object decks.
For instance, if A and B are separately compiled programs and A statically calls B,
then you cannot prelink A and B separately and then later link them together.
Instead. you must link A and B together in one prelink job.
Run-time considerations
You can specify run-time options as parameters passed to the program initialization
routine. You can also specify run-time options in the PLIXOPT variable. It might
also prove beneficial, from a performance standpoint, if you alter your existing
programs by using the PLIXOPT variable to specify your run-time options and
recompiling your programs. For a description of using PLIXOPT, see Language
Environment Programming Guide.
To simplify input/output at the terminal, various conventions have been adopted for
stream files that are assigned to the terminal. Three areas are affected:
1. Formatting of PRINT files
2. The automatic prompting feature
3. Spacing and punctuation rules for input.
Note: No prompting or other facilities are provided for record I/O at the terminal,
so you are strongly advised to use stream I/O for any transmission to or from a
terminal.
Formatting conventions for PRINT files

When a PRINT file is assigned to the terminal, it is assumed that it will be read as
it is being printed. Spacing is therefore reduced to a minimum to reduce printing
time. The following rules apply to the PAGE, SKIP, and ENDPAGE keywords:
PAGE options or format items result in three lines being skipped.
SKIP options or format items larger than SKIP (2) result in three lines being
skipped. SKIP (2) or less is treated in the usual manner.
The ENDPAGE condition is never raised.
Changing the format on PRINT files

If you want normal spacing to apply to output from a PRINT file at the terminal, you
must supply your own tab table for PL/I. This is done by declaring an external
structure called PLITABS in the main program and initializing the element
PAGELENGTH to the number of lines that can fit on your page. This value differs
from PAGESIZE, which defines the number of lines you want to print on the page
before ENDPAGE is raised (see Figure 15 on page 111). If you require a
PAGELENGTH of 64 lines, declare PLITABS as shown in Figure 14 on page 111.
For information on overriding the tab table, see “Overriding the tab control table” on
page 172.

DCL 1 PLITABS STATIC EXTERNAL,
( 2 OFFSET INIT (14),
2 PAGESIZE INIT (6K),
2 LINESIZE INIT (12K),
2 PAGELENGTH INIT (64),
2 FILL1 INIT (K),
2 FILL2 INIT (K),
2 FILL3 INIT (K),
2 NUMBER_OF_TABS INIT (5),
2 TAB1 INIT (25),
2 TAB2 INIT (49),
2 TAB3 INIT (73),
2 TAB4 INIT (97),
2 TAB5 INIT (121)) FIXED BIN (15,K);
Figure 14. Declaration of PLITABS. This declaration gives the standard page size, line size
and tabulating positions
┌─────────────────────────────┐ ─┐
│ │ │
┌─ │ ─────────────────────── │ │
│ │ ─────────────────────── │ │
│ │ ─────────────────────── │ │
│ │ ─────────────────────── │ │
│ │ ─────────────────────── │ │
│ │ ─────────────────────── │ │
PAGESIZE ─┤ │ ─────────────────────── │ ├─ PAGELENGTH
│ │ ─────────────────────── │ │
│ │ ─────────────────────── │ │
│ │ ─────────────────────── │ │
│ │ ─────────────────────── │ │
│ │ ─────────────────────── │ │
└─ │ ─────────────────────── │ │
│ │ │
│ ──────────19 │ │
└─────────────────────────────┘ ─┘
PAGELENGTH: the number of lines that can be printed on a page
PAGESIZE: the number of lines that will be printed on a page

before the ENDPAGE condition is raised
Figure 15. PAGELENGTH and PAGESIZE. PAGELENGTH defines the size of your paper,
PAGESIZE the number of lines in the main printing area.
Automatic prompting
When the program requires input from a file that is associated with a terminal, it
issues a prompt. This takes the form of printing a colon on the next line and then
skipping to column 1 on the line following the colon. This gives you a full line to
enter your input, as follows:
:
(space for entry of your data)
This type of prompt is referred to as a primary prompt.
Overriding automatic prompting: You can override the primary prompt by

making a colon the last item in the request for the data. You cannot override the
secondary prompt. For example, the two PL/I statements:
PUT SKIP EDIT ('ENTER TIME OF PERIHELION') (A);
GET EDIT (PERITIME) (A(1K));
result in the terminal displaying:
Chapter 5. Link-editing and running 111

ENTER TIME OF PERIHELION
: (automatic prompt)
(space for entry of data)
However, if the first statement has a colon at the end of the output, as follows:
PUT EDIT ('ENTER TIME OF PERIHELION:') (A);
the sequence is:
ENTER TIME OF PERIHELION: (space for entry of data)
Note: The override remains in force for only one prompt. You will be
automatically prompted for the next item unless the automatic prompt is again
overridden.
Punctuating long input lines

Line continuation character: To transmit data that requires 2 or more lines of
space at the terminal as one data-item, type an SBCS hyphen as the last character
in each line except the last line. For example, to transmit the sentence “this data
must be transmitted as one unit.” you enter:
:'this data must be transmitted -
+:as one unit.'
Transmission does not occur until you press ENTER after “unit.'”. The hyphen is
removed. The item transmitted is called a “logical line.”
Note: To transmit a line whose last data character is a hyphen or a PL/I minus
sign, enter two hyphens at the end of the line, followed by a null line as the
next line. For example:
xyz--
(press ENTER only, on this line)
Punctuating GET LIST and GET DATA statements

For GET LIST and GET DATA statements, a comma is added to the end of each
logical line transmitted from the terminal, if the programmer omits it. Thus there is
no need to enter blanks or commas to delimit items if they are entered on separate
logical lines. For the PL/I statement GET LIST(A,B,C); you can enter at the
terminal:
:1
+:2
+:3
This rule also applies when entering character-string data. Therefore, a character
string must transmit as one logical line. Otherwise, commas are placed at the
break points. For example, if you enter:
:'COMMAS SHOULD NOT BREAK
+:UP A CLAUSE.'
the resulting string is: “COMMAS SHOULD NOT BREAK, UP A CLAUSE.” The
comma is not added if a hyphen was used as a line continuation character.
Automatic padding for GET EDIT: For a GET EDIT statement, there is no need
to enter blanks at the end of the line. The data will be padded to the specified
length. Thus, for the PL/I statement:
GET EDIT (NAME) (A(15));

you can enter the 5 characters SMITH. The data will be padded with ten blanks so
that the program receives the fifteen characters:
'SMITH '
Note: A single data item must transmit as a logical line. Otherwise, the first line
transmitted will be padded with the necessary blanks and taken as the complete
data item.
Use of SKIP for terminal input: All uses of SKIP for input are interpreted as
SKIP(1) when the file is allocated to the terminal. SKIP(1) is treated as an
instruction to ignore all unused data on the currently available logical line.
ENDFILE
The end-of-file can be entered at the terminal by keying in a logical line that
consists of the two characters “/*”. Any further attempts to use the file without
closing it result in the ENDFILE condition being raised.
SYSPRINT considerations
The PL/I standard SYSPRINT file is shared by multiple enclaves within an
application. You can issue I/O requests, for example STREAM PUT, from the
same or different enclaves. These requests are handled using the standard PL/I
SYSPRINT file as a file which is common to the entire application. The SYSPRINT
file is implicitly closed only when the application terminates, not at the termination
of the enclave.
The standard PL/I SYSPRINT file contains user-initiated output only, such as
STREAM PUTs. Run-time library messages and other similar diagnostic output are
directed to the Language Environment MSGFILE. See the OS/390 V2R10
Language Environment Programming Guide for details on redirecting SYSPRINT
file output to the Language Environment MSGFILE.
To be shared by multiple enclaves within an application, the PL/I SYSPRINT file

must be declared as an EXTERNAL FILE constant with a file name of SYSPRINT
and also have the attributes STREAM and OUTPUT as well as the (implied)
attribute of PRINT, when OPENed. This is the standard SYSPRINT file as
defaulted by the compiler.
There exists only one standard PL/I SYSPRINT FILE within an application and this
file is shared by all enclaves within the application. For example, the SYSPRINT
file can be shared by multiple nested enclaves within an application or by a series
of enclaves that are created and terminated within an application by the Language
Environment preinitialization function. To be shared by an enclave within an
application, the PL/I SYSPRINT file must be declared in that enclave. The
standard SYSPRINT file cannot be shared by passing it as a file argument between
enclaves. The declared attributes of the standard SYSPRINT file should be the
same throughout the application, as with any EXTERNALly declared constant. PL/I
does not enforce this rule. Both the TITLE option and the MSGFILE(SYSPRINT)
option attempt to route SYSPRINT to another data set. As such, if the two options
were used together, there will be a conflict and the TITLE option will be ignored.
Having a common SYSPRINT file within an application can be an advantage to

applications that utilize enclaves that are closely tied together. However, since all

enclaves in an application write to the same shared data set, this might require
some coordination among the enclaves.
The SYSPRINT file is opened (implicitly or explicitly) when first referenced within an
enclave of the application. When the SYSPRINT file is CLOSEd, the file resources
are released (as though the file had never been opened) and all enclaves are
updated to reflect the closed status.
If SYSPRINT is utilized in a multiple enclave application, the LINENO built-in

function only returns the current line number until after the first PUT or OPEN in an
enclave has been issued. This is required in order to maintain full compatibility with
old programs.
The COUNT built-in function is maintained at an enclave level. It always returns a

value of zero until the first PUT in the enclave is issued. If a nested child enclave
is invoked from a parent enclave, the value of the COUNT built-in function is
undefined when the parent enclave regains control from the child enclave.
When opened, the TITLE option can be used to associate the standard SYSPRINT
file with different operating system data sets. This association is retained across
enclaves for the duration of the open.
PL/I condition handling associated with the standard PL/I SYSPRINT file retains its
current semantics and scope. For example, an ENDPAGE condition raised within a
child enclave will only invoke an established ON-unit within that child enclave. It
does not cause invocation of an ON-unit within the parent enclave.
The tabs for the standard PL/I SYSPRINT file can vary when PUTs are done from
different enclaves, if the enclaves contain a user PLITABS table.
If the PL/I SYSPRINT file is utilized as a RECORD file or as a STREAM INPUT file,
PL/I supports it at an individual enclave or task level, but not as a shareble file
among enclaves. If the PL/I SYSPRINT file is open at the same time with different
file attributes (e.g. RECORD and STREAM) in different enclaves of the same
application, results are unpredictable.
Using FETCH in your routines

In Enterprise PL/I, you can FETCH routines compiled by PL/I, C, COBOL or
assembler.
FETCHing Enterprise PL/I routines

Almost all the restrictions imposed by the older PL/I compilers on FETCHed
modules have been removed. So a FETCHed module can now:
FETCH other modules
Perform any I/O operations on any PL/I file. The file can be opened either by
the FETCHed module, by the main module, or by some other FETCHed
module.
ALLOCATE and FREE its own CONTROLLED variables
There are, however, a few restrictions on a Enterprise PL/I module that is to be

FETCHed. These restrictions are:

1. OPTIONS(FETCHABLE) should be specified on the PROCEDURE statement
for the entry point of any PL/I routine to be FETCHed.
2. Unless the NORENT option has been specified, the ENTRY declaration in the
routine that FETCHes must not specify OPTIONS(COBOL) or
OPTIONS(ASM)—these should be specified only for COBOL or ASM routines
not linked as DLLs.
3. OPTIONS(FETCHABLE) must be specified on the PROCEDURE statement for
the entry point of the FETCHABLE routine or the procedure must be compiled
with the DLLINIT option.
4. Unless the NORENT option has been specified, a PROCEDURE specifiying
OPTIONS(FETCHABLE) must be linked as a DLL.
As an illustration of these restrictions, consider the compiler user exit. If you

specify the EXIT compile-time option, the compiler will FETCH and call a Enterprise
PL/I module named IBMUEXIT.
First note that the compiler user exit must be compiled with the RENT option since
the compiler expects it to be a DLL.
In accordance with Item 1 above, the DECLARE in the compiler for this routine
looks like:
dcl ibmuexit ext entry( pointer byvalue, pointer byvalue );
In accordance with Item 2 above, the PROCEDURE statement for this routine looks
like:
ibmuexit:
proc ( addr_Userexit_Interface_Block,
addr_Request_Area )
options( fetchable );
dcl addr_Userexit_Interface_Block pointer byvalue;
dcl addr_Request_Area pointer byvalue;
In accordance with Item 3 above, the linker option DYNAM=DLL must be specified
when linking the user exit into a DLL. The DLL must be linked either into a PDSE
or into a temporary dataset (in which case DSNTYPE=LIBRARY must be specified
on the SYSLMOD DD statement).
All the JCL to compile, link, and invoke the user exit is given in the JCL below in
Figure 16 on page 116. The one significant difference between the sample below
and the code excerpts above is that, in the code below, the FETCHed user exit
does not receive two BYVALUE pointers to structures, but instead it receives the
two structures BYADDR. In order to make this change work, the code specifies
OPTIONS(NODESCRIPTOR) on each of its PROCEDURE statements.

//]
//]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]
//] compile the user exit
//]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]
//PLIEXIT EXEC PGM=IBMZPLI,
// REGION=256K
//STEPLIB DD DSN=IBMZ.V3R2MK.SIBMZCMP,DISP=SHR
//SYSLIN DD DSN=&&LOADSET,DISP=(MOD,PASS),UNIT=SYSSQ,
// SPACE=(CYL,(3,1))
//SYSUT1 DD DSN=&&SYSUT1,UNIT=SYSDA,
//SYSIN DD ]
]Process or('|') not('!');
]Process limits(extname(31));
/]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]/
/] ]/
/] NAME - IBMUEXIT.PLI ]/
/] ]/
/] DESCRIPTION ]/
/] User-exit sample program. ]/
/] ]/
/] Licensed Materials - Property of IBM ]/
/] 5639-A83, 5639-A24 (C) Copyright IBM Corp. 1992,2KK1. ]/
/] All Rights Reserved. ]/
/] US Government Users Restricted Rights-- Use, duplication or ]/
/] disclosure restricted by GSA ADP Schedule Contract with ]/
/] IBM Corp. ]/
/] ]/
/] DISCLAIMER OF WARRANTIES ]/
/] The following "enclosed" code is sample code created by IBM ]/
/] Corporation. This sample code is not part of any standard ]/
/] IBM product and is provided to you solely for the purpose of ]/
/] assisting you in the development of your applications. The ]/
/] code is provided "AS IS", without warranty of any kind. ]/
/] IBM shall not be liable for any damages arising out of your ]/
/] use of the sample code, even if IBM has been advised of the ]/
/] possibility of such damages. ]/
/] ]/
/]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]/
/]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]/
/] ]/
/] During initialization, IBMUEXIT is called. It reads ]/
/] information about the messages being screened from a text ]/
/] file and stores the information in a hash table. IBMUEXIT ]/
/] also sets up the entry points for the message filter service ]/
/] and termination service. ]/
/] ]/
/] For each message generated by the compiler, the compiler ]/
/] calls the message filter registered by IBMUEXIT. The filter ]/
/] looks the message up in the hash table previously created. ]/
/] ]/
/] The termination service is called at the end of the compile ]/
/] but does nothing. It could be enhanced to generates reports ]/
/] or do other cleanup work. ]/
/] ]/
/]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]/
Figure 16 (Part 1 of 7). Sample JCL to compile, link, and invoke the user exit

pack: package exports(]);
Dcl
1 Uex_UIB native Based( null() ),
2 Uex_UIB_Length fixed bin(31),
2 Uex_UIB_Exit_token pointer, /] for user exit's use]/
2 Uex_UIB_User_char_str pointer, /] to exit option str ]/

2 Uex_UIB_User_char_len fixed bin(31),
2 Uex_UIB_Filename_str pointer, /] to source filename ]/

2 Uex_UIB_Filename_len fixed bin(31),
2 Uex_UIB_return_code fixed bin(31), /] set by exit procs ]/

2 Uex_UIB_reason_code fixed bin(31), /] set by exit procs ]/
2 Uex_UIB_Exit_Routs, /] exit entries setat

initialization ]/
3 ( Uex_UIB_Termination,
Uex_UIB_Message_Filter, /] call for each msg ]/
], ], ], ] )
limited entry (
], /] to Uex_UIB ]/
] /] to a request area ]/
);
/]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]/
/] ]/
/] Request Area for Initialization exit ]/
/] ]/
/]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]/
Dcl 1 Uex_ISA native based( null() ),

2 Uex_ISA_Length fixed bin(31);
/]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]/
/] ]/
/] Request Area for Message_Filter exit ]/
/] ]/
/]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]/
Dcl 1 Uex_MFA native based( null() ),

2 Uex_MFA_Length fixed bin(31),
2 Uex_MFA_Facility_Id char(3),
2 ] char(1),
2 Uex_MFA_Message_no fixed bin(31),
2 Uex_MFA_Severity fixed bin(15),
2 Uex_MFA_New_Severity fixed bin(15); /] set by exit proc ]/
/]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]/
/] ]/
/] Request Area for Terminate exit ]/
/] ]/
/]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]/
Dcl 1 Uex_TSA native based( null() ),

2 Uex_TSA_Length fixed bin(31);

/]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]/
/] ]/
/] Severity Codes ]/
/] ]/
/]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]/
dcl uex_Severity_Normal fixed bin(15) value(K);

dcl uex_Severity_Warning fixed bin(15) value(4);
dcl uex_Severity_Error fixed bin(15) value(8);
dcl uex_Severity_Severe fixed bin(15) value(12);
dcl uex_Severity_Unrecoverable fixed bin(15) value(16);
/]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]/
/] ]/
/] Return Codes ]/
/] ]/
/]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]/
dcl uex_Return_Normal fixed bin(15) value(K);

dcl uex_Return_Warning fixed bin(15) value(4);
dcl uex_Return_Error fixed bin(15) value(8);
dcl uex_Return_Severe fixed bin(15) value(12);
dcl uex_Return_Unrecoverable fixed bin(15) value(16);
/]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]/
/] ]/
/] Reason Codes ]/
/] ]/
/]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]/
dcl uex_Reason_Output fixed bin(15) value(K);

dcl uex_Reason_Suppress fixed bin(15) value(1);
dcl hashsize fixed bin(15) value(97);

dcl hashtable(K:hashsize-1) ptr init((hashsize) null());
dcl 1 message_item native based,

2 message_Info,
3 facid char(3),
3 msgno fixed bin(31),
3 newsev fixed bin(15),
3 reason fixed bin(31),
2 link pointer;
ibmuexit:
proc ( ue, ia )
options( fetchable nodescriptor);
dcl 1 ue like uex_Uib byaddr;

dcl 1 ia like uex_Isa byaddr;
ue.uex_Uib_Message_Filter = message_Filter;
ue.uex_Uib_Termination = exitterm;
end;

message_Filter: proc ( ue, mf )
options( nodescriptor);

dcl 1 mf like uex_Mfa byaddr;
dcl sysuexit file stream input env(recsize(8K));

dcl p pointer;
dcl bucket fixed bin(31);
dcl based_Chars char(8) based;
dcl title_Str char(8) var;
ue.uex_Uib_Message_Filter = message_Filter;
ue.uex_Uib_Termination = exitterm;
on undefinedfile(sysuexit)
begin;
put edit (']] User exit unable to open exit file ')
(A) skip;
put skip;
signal error;
end;
if ue.uex_Uib_User_Char_Len = K then
do;
open file(sysuexit);
end;
else
do;
title_Str
= substr( ue.uex_Uib_User_Char_Str->based_Chars,
1, ue.uex_Uib_User_Char_Len );
open file(sysuexit) title(title_Str);
end;
on error, endfile(sysuexit)
goto done;
allocate message_item set(p);
/]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]/
/] ]/
/] Skip header lines and read first data line ]/
/] ]/
/]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]/
get file(sysuexit) list(p->message_info) skip(3);

do loop;
/]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]/
/] ]/
/] Put message information in hash table ]/
/] ]/
/]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]/
bucket = mod(p->msgno, hashsize);

p->link = hashtable(bucket);
hashtable(bucket) = p;
/]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]/
/] ]/
/] Read next data line ]/
/] ]/
/]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]/
allocate message_item set(p);

get file(sysuexit) skip;
get file(sysuexit) list(p->message_info);
end;
/]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]/
/] ]/
/] Clean up ]/
/] ]/
/]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]/
done:
free p->message_Item;
close file(sysuexit);
end;
message_Filter: proc ( ue, mf );

dcl 1 mf like uex_Mfa byaddr;
dcl p pointer;
dcl bucket fixed bin(15);
on error snap system;
ue.uex_Uib_Reason_Code = uex_Reason_Output;
ue.uex_Uib_Return_Code = K;
mf.uex_Mfa_New_Severity = mf.uex_Mfa_Severity;

/]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]/
/] ]/
/] Calculate bucket for error message ]/
/] ]/
/]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]/
bucket = mod(mf.uex_Mfa_Message_No, hashsize);
/]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]/
/] ]/
/] Search bucket for error message ]/
/] ]/
/]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]/
do p = hashtable(bucket) repeat (p->link) while(p!=null())

until (p->msgno = mf.uex_Mfa_Message_No &
p->facid = mf.Uex_Mfa_Facility_Id);
end;
if p = null() then;
else
do;
/]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]/
/] ]/
/] Filter error based on information in has table ]/
/] ]/
/]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]/
ue.uex_Uib_Reason_Code = p->reason;
if p->newsev < K then;
else
mf.uex_Mfa_New_Severity = p->newsev;
end;
end;
exitterm: proc ( ue, ta );

dcl 1 ta like uex_Tsa byaddr;
ue.uex_Uib_return_Code = K;
ue.uex_Uib_reason_Code = K;
end;
end pack;

//]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]
//] link the user exit
//]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]
//LKEDEXIT EXEC PGM=IEWL,PARM='XREF,LIST,LET,DYNAM=DLL',
// COND=(9,LT,PLIEXIT),REGION=5KKKK
//SYSLIB DD DSN=IBMZ.V3R2MK.CEE.SCEELKED,DISP=SHR
//SYSLMOD DD DSN=&&EXITLIB(IBMUEXIT),DISP=(NEW,PASS),UNIT=SYSDA,
// SPACE=(TRK,(7,1,1)),DSNTYPE=LIBRARY
//SYSUT1 DD DSN=&&SYSUT1,UNIT=SYSDA,SPACE=(CYL,(3,1)),
// DCB=BLKSIZE=1K24
//SYSPRINT DD SYSOUT=X
//SYSDEFSD DD DUMMY
//SYSLIN DD DSN=&&LOADSET,DISP=SHR
// DD DDNAME=SYSIN
//LKED.SYSIN DD ]
ENTRY IBMUEXIT
//]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]
//] compile main
//]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]
//PLI EXEC PGM=IBMZPLI,PARM='F(I),EXIT',
// REGION=256K
//STEPLIB DD DSN=IBMZ.V3R2MK.SIBMZCMP,DISP=SHR
// DD DSN=&&EXITLIB,DISP=SHR
//SYSLIN DD DSN=&&LOADSET2,DISP=(MOD,PASS),UNIT=SYSSQ,
// SPACE=(CYL,(3,1))
//SYSUT1 DD DSN=&&SYSUT1,UNIT=SYSDA,
//SYSIN DD ]
]process;
MainFet: Proc Options(Main);
/] the exit will suppress the message for the next dcl ]/
dcl one_byte_integer fixed bin(7);
End ;
//]
//SYSUEXIT DD ]
Fac Id Msg No Severity Suppress Comment
+--------+--------+----------+----------+-------------------------------
'IBM' 1K42 -1 1 String spans multiple lines
'IBM' 1K44 -1 1 FIXED BIN 7 mapped to 1 byte
FETCHing OS/390 C routines

Unless the NORENT option has been specified, the ENTRY declaration in the
routine that FETCHes an OS/390 C routine must not specify OPTIONS(COBOL) or
OPTIONS(ASM)—these should be specified only for COBOL or ASM routines not
linked as DLLs
The OS/390 C documentation provides instructions on how to compile and link an

OS/390 C DLL.
FETCHing assembler routines

Unless the NORENT option has been specified, the ENTRY declaration in the
routine that FETCHes an assembler routine must specify OPTIONS(ASM).

Invoking MAIN under USS
Under USS, if you compile a MAIN program with the SYSTEM(MVS) option, the
program will be passed, as usual, one CHARACTER VARYING string containing
the parameters specified when it was invoked.
However, under USS, if you compile a MAIN program with the SYSTEM(OS)
option, the program will be passed 7 parameters as specified in the USS manuals.
These 7 parameters include:
the argument count (which includes the name of the executable as the first
"argument"
the address of an array of addresses of the lengths of the arguments
the address of an array of addresses of the arguments as null-terminated
character strings
the count of environment variables set
the address of an array of addresses of the lengths of the environment
variables
the address of an array of addresses of the environment variables as
null-terminated character strings
The program in Figure 17 uses the SYSTEM(OS) interface to address and display
the individual arguments and environment variables.
]process display(std) system(os);
sayargs:
proc(argc, pArgLen, pArgStr, envc, pEnvLen, pEnvStr, pParmSelf)
options( main, noexecops );
dcl argc fixed bin(31) nonasgn byaddr;

dcl pArgLen pointer nonasgn byvalue;
dcl pArgStr pointer nonasgn byvalue;
dcl envc fixed bin(31) nonasgn byaddr;
dcl pEnvLen pointer nonasgn byvalue;
dcl pEnvStr pointer nonasgn byvalue;
dcl pParmSelf pointer nonasgn byvalue;
dcl q(4K95) pointer based;

dcl bxb fixed bin(31) based;
dcl bcz char(31) varz based;
display( 'argc = ' || argc );

do jx = 1 to argc;
display( 'pargStr(jx) =' || pArgStr->q(jx)->bcz );
end;
display( 'envc = ' || envc );
do jx = 1 to envc;
display( 'pEnvStr(jx) =' || pEnvStr->q(jx)->bcz );
end;
end;
Figure 17. Sample program to display USS args and environment variables

Part 3. Using I/O facilities
Chapter 6. Using data sets and files . . . . . . . . . . . . . . . . . . . . . . . 128
Associating data sets with files under OS/390 . . . . . . . . . . . . . . . . . . . . 128
Associating several files with one data set . . . . . . . . . . . . . . . . . . . . 130
Associating several data sets with one file . . . . . . . . . . . . . . . . . . . . 130
Concatenating several data sets . . . . . . . . . . . . . . . . . . . . . . . . . . 131
Accessing HFS files under OS/390 . . . . . . . . . . . . . . . . . . . . . . . . 131
Associating data sets with files under OS/390 UNIX . . . . . . . . . . . . . . . . 132
Using environment variables . . . . . . . . . . . . . . . . . . . . . . . . . . . . 132
Attempting to use files not associated with data sets . . . . . . . . . . . . . . 133
How PL/I finds data sets . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 133
Specifying characteristics using DD_DDNAME environment variables . . . . 133
APPEND . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 134
ASA . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 134
BUFSIZE . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 134
CHARSET for record I/O . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 135
CHARSET for stream I/O . . . . . . . . . . . . . . . . . . . . . . . . . . . . 135
DELAY . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 135
DELIMIT . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 135
LRECL . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 136
LRMSKIP . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 136
PROMPT . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 136
PUTPAGE . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 136
RECCOUNT . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 137
RECSIZE . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 137
SAMELINE . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 137
SKIP0 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 138
TYPE . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 138
Establishing data set characteristics . . . . . . . . . . . . . . . . . . . . . . . . . 139
Blocks and records . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 139
Record formats . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 140
Fixed-length records . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 140
Variable-length records . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 141
Undefined-length records . . . . . . . . . . . . . . . . . . . . . . . . . . . . 142
Data set organization . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 142
Labels . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 143
Data Definition (DD) statement . . . . . . . . . . . . . . . . . . . . . . . . . . . 143
Use of the conditional subparameters . . . . . . . . . . . . . . . . . . . . . 143
Data set characteristics . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 144
Associating PL/I files with data sets . . . . . . . . . . . . . . . . . . . . . . . . 145
Specifying characteristics in the ENVIRONMENT attribute . . . . . . . . . . . 146
Data set types used by PL/I record I/O . . . . . . . . . . . . . . . . . . . . . . 154
Setting environment variables . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 154
PL/I standard files (SYSPRINT and SYSIN) . . . . . . . . . . . . . . . . . . . . . 155
Redirecting standard input, output, and error devices . . . . . . . . . . . . . . . 155
Chapter 7. Using libraries . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 156

Types of libraries . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 156
How to use a library . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 156

Creating a library . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 157
SPACE parameter . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 157
Creating and updating a library member . . . . . . . . . . . . . . . . . . . . . . . 158
Examples . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 158
Extracting information from a library directory . . . . . . . . . . . . . . . . . . . . 160
Chapter 8. Defining and using consecutive data sets . . . . . . . . . . . . . 162

Using stream-oriented data transmission . . . . . . . . . . . . . . . . . . . . . . . 162
Defining files using stream I/O . . . . . . . . . . . . . . . . . . . . . . . . . . . 162
CONSECUTIVE . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 163
Record format options . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 163
RECSIZE . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 164
Defaults for record format, BLKSIZE, and RECSIZE . . . . . . . . . . . . . 164
GRAPHIC option . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 165
Creating a data set with stream I/O . . . . . . . . . . . . . . . . . . . . . . . . 165
Essential information . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 165
Examples . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 166
Accessing a data set with stream I/O . . . . . . . . . . . . . . . . . . . . . . . 168
Record format . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 168
Example . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 169
Using PRINT files with stream I/O . . . . . . . . . . . . . . . . . . . . . . . . . 169
Controlling printed line length . . . . . . . . . . . . . . . . . . . . . . . . . . 170
Overriding the tab control table . . . . . . . . . . . . . . . . . . . . . . . . . 172
Using SYSIN and SYSPRINT files . . . . . . . . . . . . . . . . . . . . . . . . . 173
Controlling input from the terminal . . . . . . . . . . . . . . . . . . . . . . . . . . 174
Format of data . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 175
Capital and lowercase letters . . . . . . . . . . . . . . . . . . . . . . . . . . . . 176
End-of-file . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 176
COPY option of GET statement . . . . . . . . . . . . . . . . . . . . . . . . . . 176
Controlling output to the terminal . . . . . . . . . . . . . . . . . . . . . . . . . . . 176
Format of PRINT files . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 176
Capital and lowercase characters . . . . . . . . . . . . . . . . . . . . . . . . . 177
Output from the PUT EDIT command . . . . . . . . . . . . . . . . . . . . . . . 177
Using record-oriented data transmission . . . . . . . . . . . . . . . . . . . . . . . 177
Specifying record format . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 178
Defining files using record I/O . . . . . . . . . . . . . . . . . . . . . . . . . . . 178
CONSECUTIVE . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 179
ORGANIZATION(CONSECUTIVE) . . . . . . . . . . . . . . . . . . . . . . . 179
DEBLOCK . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 179
CTLASA|CTL360 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 179
Creating a data set with record I/O . . . . . . . . . . . . . . . . . . . . . . . . 181
Accessing and updating a data set with record I/O . . . . . . . . . . . . . . . 181
Example of consecutive data sets . . . . . . . . . . . . . . . . . . . . . . . 183
Chapter 9. Defining and using regional data sets . . . . . . . . . . . . . . . 186

Defining files for a regional data set . . . . . . . . . . . . . . . . . . . . . . . . . 188

REGIONAL option . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 189
Using keys with REGIONAL data sets . . . . . . . . . . . . . . . . . . . . . . 189
Using REGIONAL(1) data sets . . . . . . . . . . . . . . . . . . . . . . . . . . . . 190
Dummy Records . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 190
Creating a REGIONAL(1) data set . . . . . . . . . . . . . . . . . . . . . . . . . 190
Example . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 191
Accessing and updating a REGIONAL(1) data set . . . . . . . . . . . . . . . 192
Sequential access . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 192
Direct access . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 192
Example . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 192
Essential information for creating and accessing regional data sets . . . . . . . 195
Chapter 10. Defining and using VSAM data sets . . . . . . . . . . . . . . . . 197

Using VSAM data sets . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 197
How to run a program with VSAM data sets . . . . . . . . . . . . . . . . . . . 197
Pairing an Alternate Index Path with a File . . . . . . . . . . . . . . . . . . . . 197
VSAM organization . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 198
Keys for VSAM data sets . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 200
Keys for indexed VSAM data sets . . . . . . . . . . . . . . . . . . . . . . . 200
Relative byte addresses (RBA) . . . . . . . . . . . . . . . . . . . . . . . . . 200
Relative record numbers . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 201
Choosing a data set type . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 201
Defining files for VSAM data sets . . . . . . . . . . . . . . . . . . . . . . . . . . . 202
BKWD option . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 203
GENKEY option . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 204
REUSE option . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 204
VSAM option . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 204
Performance options . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 204
Defining Files for Alternate Index Paths . . . . . . . . . . . . . . . . . . . . . . . 205
Defining VSAM data sets . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 205
Entry-sequenced data sets . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 206
Loading an ESDS . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 206
Using a SEQUENTIAL file to access an ESDS . . . . . . . . . . . . . . . . . 207
Defining and loading an ESDS . . . . . . . . . . . . . . . . . . . . . . . . . 207
Updating an ESDS . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 208
Key-sequenced and indexed entry-sequenced data sets . . . . . . . . . . . . . 209
Loading a KSDS or indexed ESDS . . . . . . . . . . . . . . . . . . . . . . . . 210
Using a SEQUENTIAL file to access a KSDS or indexed ESDS . . . . . . . 212
Using a DIRECT file to access a KSDS or indexed ESDS . . . . . . . . . . . 212
Alternate Indexes for KSDSs or Indexed ESDSs . . . . . . . . . . . . . . . . . . 215
Unique Key Alternate Index Path . . . . . . . . . . . . . . . . . . . . . . . . . 215
Nonunique Key Alternate Index Path . . . . . . . . . . . . . . . . . . . . . . . 216
Detecting Nonunique Alternate Index Keys . . . . . . . . . . . . . . . . . . . . 217
Using Alternate Indexes with ESDSs . . . . . . . . . . . . . . . . . . . . . . . 218
Using Alternate Indexes with KSDSs . . . . . . . . . . . . . . . . . . . . . . . 218
Relative-record data sets . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 221
Loading an RRDS . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 223
Using a SEQUENTIAL file to access an RRDS . . . . . . . . . . . . . . . . . 225
Using a DIRECT file to access an RRDS . . . . . . . . . . . . . . . . . . . . . 226
Part 3. Using I/O facilities 127

Chapter 6. Using data sets and files
Your PL/I programs process and transmit units of information called records. A
collection of records is called a data set. Data sets are physical collections of
information external to PL/I programs; they can be created, accessed, or modified
by programs written in PL/I or other languages or by the utility programs of the
operating system.
Your PL/I program recognizes and processes information in a data set by using a
symbolic or logical representation of the data set called a file. This chapter
describes how to associate data sets with the files known within your program. It
introduces the five major types of data sets, how they are organized and accessed,
and some of the file and data set characteristics you need to know how to specify.
Note: INDEXED is supported only under batch.
Associating data sets with files under OS/390

A file used within a PL/I program has a PL/I file name. The physical data set
external to the program has a name by which it is known to the operating system:
a data set name or dsname. In some cases the data set has no name; it is known
to the system by the device on which it exists.
The operating system needs a way to recognize which physical data set is referred
to by your program, so you must write a data definition or DD statement, external to
your program, that associates the PL/I file name with a dsname. For example, if
you have the following file declaration in your program:
DCL STOCK FILE STREAM INPUT;
you should create a DD statement with a data definition name (ddname) that
matches the name of the PL/I file. The DD statement specifies a physical data set
name (dsname) and gives its characteristics:
//GO.STOCK DD DSN=PARTS.INSTOCK, . . .
You'll find some guidance in writing DD statements in this manual, but for more
detail refer to the job control language (JCL) manuals for your system.
There is more than one way to associate a data set with a PL/I file. You associate
a data set with a PL/I file by ensuring that the ddname of the DD statement that
defines the data set is the same as one of the following:
The declared PL/I file name
The character-string value of the expression specified in the TITLE option of
the associated OPEN statement.
You must choose your PL/I file names so that the corresponding ddnames conform
to the following restrictions:
If a file is opened implicitly, or if no TITLE option is included in the OPEN
statement that explicitly opens the file, the ddname defaults to the file name. If
the file name is longer than 8 characters, the default ddname is composed of
the first 8 characters of the file name.
The character set of the JCL does not contain the break character (_).
Consequently, this character cannot appear in ddnames. Do not use break

characters among the first 8 characters of file names, unless the file is to be
opened with a TITLE option with a valid ddname as its expression. The
alphabetic extender characters $, @, and #, however, are valid for ddnames,
but the first character must be one of the letters A through Z.
Since external names are limited to 7 characters, an external file name of more
than 7 characters is shortened into a concatenation of the first 4 and the last 3
characters of the file name. Such a shortened name is not, however, the name
used as the ddname in the associated DD statement.
Consider the following statements:

1. OPEN FILE(MASTER);
2. OPEN FILE(OLDMASTER);
3. READ FILE(DETAIL) ...;
When statement number 1 is run, the file name MASTER is taken to be the same
as the ddname of a DD statement in the current job step. When statement number
2 is run, the name OLDMASTE is taken to be the same as the ddname of a DD
statement in the current job step. (The first 8 characters of a file name form the
ddname. If OLDMASTER is an external name, it will be shortened by the compiler
to OLDMTER for use within the program.) If statement number 3 causes implicit
opening of the file DETAIL, the name DETAIL is taken to be the same as the
ddname of a DD statement in the current job step.
In each of the above cases, a corresponding DD statement must appear in the job
stream; otherwise, the UNDEFINEDFILE condition is raised. The three DD
statements could start as follows:
1. //MASTER DD ...
2. //OLDMASTE DD ...
3. //DETAIL DD ...
If the file reference in the statement which explicitly or implicitly opens the file is not
a file constant, the DD statement name must be the same as the value of the file
reference. The following example illustrates how a DD statement should be
associated with the value of a file variable:
DCL PRICES FILE VARIABLE,
RPRICE FILE;
PRICES = RPRICE;
OPEN FILE(PRICES);
The DD statement should associate the data set with the file constant RPRICE,
which is the value of the file variable PRICES, thus:
//RPRICE DD DSNAME=...
Use of a file variable also allows you to manipulate a number of files at various
times by a single statement. For example:
Chapter 6. Using data sets and files 129

DECLARE F FILE VARIABLE,
A FILE,
B FILE,
C FILE;
.
.
.
DO F=A,B,C;
READ FILE (F) ...;
.
.
.
END;
The READ statement reads the three files A, B, and C, each of which can be
associated with a different data set. The files A, B, and C remain open after the
READ statement is executed in each instance.
The following OPEN statement illustrates use of the TITLE option:

OPEN FILE(DETAIL) TITLE('DETAIL1');
For this statement to be executed successfully, you must have a DD statement in
the current job step with DETAIL1 as its ddname. It could start as follows:
//DETAIL1 DD DSNAME=DETAILA,...
Thus, you associate the data set DETAILA with the file DETAIL through the
ddname DETAIL1.
Associating several files with one data set

You can use the TITLE option to associate two or more PL/I files with the same
external data set at the same time. This is illustrated in the following example,
where INVNTRY is the name of a DD statement defining a data set to be
associated with two files:
OPEN FILE (FILE1) TITLE('INVNTRY');
OPEN FILE (FILE2) TITLE('INVNTRY');
If you do this, be careful. These two files access a common data set through
separate control blocks and data buffers. When records are written to the data set
from one file, the control information for the second file will not record that fact.
Records written from the second file could then destroy records written from the
first file. PL/I does not protect against data set damage that might occur. If the
data set is extended, the extension is reflected only in the control blocks associated
with the file that wrote the data; this can cause an abend when other files access
the data set.
Associating several data sets with one file

The file name can, at different times, represent entirely different data sets. In the
above example of the OPEN statement, the file DETAIL1 is associated with the
data set named in the DSNAME parameter of the DD statement DETAIL1. If you
closed and reopened the file, you could specify a different ddname in the TITLE
option to associate the file with a different data set.

Use of the TITLE option allows you to choose dynamically, at open time, one
among several data sets to be associated with a particular file name. Consider the
following example:
DO IDENT='A','B','C';
OPEN FILE(MASTER)
TITLE('MASTER1'||IDENT);
.
.
.
CLOSE FILE(MASTER);
END;
In this example, when MASTER is opened during the first iteration of the do-group,
the associated ddname is taken to be MASTER1A. After processing, the file is
closed, dissociating the file name and the ddname. During the second iteration of
the do-group, MASTER is opened again. This time, MASTER is associated with
the ddname MASTER1B. Similarly, during the final iteration of the do-group,
MASTER is associated with the ddname MASTER1C.
Concatenating several data sets

For input only, you can concatenate two or more sequential or regional data sets
(that is, link them so that they are processed as one continuous data set) by
omitting the ddname from all but the first of the DD statements that describe them.
For example, the following DD statements cause the data sets LIST1, LIST2, and
LIST3 to be treated as a single data set for the duration of the job step in which the
statements appear:
//GO.LIST DD DSNAME=LIST1,DISP=OLD
// DD DSNAME=LIST2,DISP=OLD
// DD DSNAME=LIST3,DISP=OLD
When read from a PL/I program, the concatenated data sets need not be on the
same volume. You cannot process concatenated data sets backward.
Accessing HFS files under OS/390

You can access HFS files from a batch program by specifying the HFS file name in
the DD statement or in the TITLE option of the OPEN statement.
For example, to access the HFS file /u/USER/sample.txt via the DD HFS, you
would code the DD statement as follows:
//HFS DD PATH='/u/USER/sample.txt',PATHOPTS=ORDONLY,DSNTYPE=HFS
To access the same file by using the TITLE option of the OPEN statement, you
would code:
OPEN FILE(HFS) TITLE('//u/USER/sample.txt');
Note the two forward slashes in the TITLE option: the first indicates that what
follows is a file name (rather than a DD name), and the second is the start of the
fully qualified HFS file name (and fully qualified names have to be used when HFS
files are referenced under batch since there is no "current directory" that could be
used to complete a file specification).

Associating data sets with files under OS/390 UNIX

A file used within a PL/I program has a PL/I file name. A data set also has a name
by which it is known to the operating system.
PL/I needs a way to recognize the data set(s) to which the PL/I files in your
program refer, so you must provide an identification of the data set to be used, or
allow PL/I to use a default identification.
You can identify the data set explicitly using either an environment variable or the
TITLE option of the OPEN statement.
Using environment variables

You use the export command to establish an environment variable that identifies
the data set to be associated with a PL/I file, and, optionally, to specify the
characteristics of that data set. The information provided by the environment
variable is called data definition (or DD) information.
These environment variable names have the form DD_DDNAME where the
DDNAME is the name of a PL/I file constant (or an alternate DDNAME, as defined
below). For example:
declare MyFile stream output;
export DD_MYFILE=/datapath/mydata.dat
If you are familiar with the IBM mainframe environment, you can think of the
environment variable much like you do the:
DD statement in OS/390
ALLOCATE statement in TSO
For more about the syntax and options you can use with the DD_DDNAME
environment variable, see “Specifying characteristics using DD_DDNAME
environment variables” on page 133.
Using the TITLE option of the OPEN statement

You can use the TITLE option of the OPEN statement to identify the data set to be
associated with a PL/I file, and, optionally, to provide additional characteristics of
that data set.
──TITLE──(──expression──)──────────────────────────────────────────────

The expression must yield a character string with the following syntax:

──┬─alternate_ddname────────────────┬──────────────────────────────────

│ ┌──
──────────────────┐ │
┬────────────────┬┴──┘
└─/filespec──
└──,──dd_option──┘
alternate_ddname
The name of an alternate DD_DDNAME environment variable. An alternate
DD_DDNAME environment variable is one not named after a file constant. For
example, if you had a file named INVENTRY in your program, and you

establish two DD_DDNAME environment variables—the first named INVENTRY

and the second named PARTS—you could associate the file with the second
one using this statement:
open file(Inventry) title('PARTS');
filespec
Any valid file specification on the system you are using.
dd_option
One or more options allowed in a DD_DDNAME environment variable.
For more about options of the DD_DDNAME environment variable, see “Specifying
characteristics using DD_DDNAME environment variables.”
Here is an example of using the OPEN statement in this manner:

open file(Payroll) title('/June.Dat,append(n),recsize(52)');
With this form, PL/I obtains all DD information either from the TITLE expression or
from the ENVIRONMENT attribute of a file declaration - a DD_DDNAME
environment variable is not referenced.
Attempting to use files not associated with data sets

If you attempt to use a file that has not been associated with a data set, (either
through the use of the TITLE option of the OPEN statement or by establishing a
DD_DDNAME environment variable), the UNDEFINEDFILE condition is raised.
The only exceptions are the files SYSIN and SYSPRINT; these default to stdin and
stdout, respectively.
How PL/I finds data sets

PL/I establishes the path for creating new data sets or accessing existing data sets
in one of the following ways:
The current directory.
The paths as defined by the export DD_DDNAME environment variable.
Specifying characteristics using DD_DDNAME environment variables

You use the export command to establish an environment variable that identifies
the data set to be associated with a PL/I file, and, optionally, provide additional
characteristics of that data set. This information provided by the environment
variable is called data definition (or DD) information.
The syntax of the DD_DDNAME environment variable is:

┌──
───────────────┐
┬─────────────┬┴─────────────────────────────────

──DD_DDNAME=filespec──
└──,──option──┘
Blanks are acceptable within the syntax. In addition, the syntax of the statement is
not checked at the time the command is entered. It is verified when the data set is
opened. If the syntax is wrong, UNDEFINEDFILE is raised with the oncode 96.
DD_DDNAME
Specifies the name of the environment variable. The DDNAME must be in
upper case and can be either the name of a file constant or an alternate

DDNAME that you specify in the TITLE option of your OPEN statement. The
TITLE option is described in “Using the TITLE option of the OPEN statement”
on page 132.
If you use an alternate DDNAME, and it is longer than 31 characters, only the
first 31 characters are used in forming the environment variable name.
filespec
Specifies a file or the name of a device to be associated with the PL/I file.
option
The options you can specify as DD information.
The options that you can specify as DD information are described in the pages that
follow, beginning with “APPEND” and ending with “TYPE” on page 138.
APPEND
The APPEND option specifies whether an existing data set is to be extended or
recreated.
┌─Y─┐

──APPEND──(──┴─N─┴──)──────────────────────────────────────────────────────────

Y Specifies that new records are to be added to the end of a sequential data set,
or inserted in a relative or indexed data set.
N Specifies that, if the file exists, it is to be recreated.
The APPEND option applies only to OUTPUT files. APPEND is ignored if:
The file does not exist
The file does not have the OUTPUT attribute
The organization is REGIONAL(1)
ASA
The ASA option applies to printer-destined files. This option specifies when the
ANS control character in each record is to be interpreted.
┌─N─┐

──ASA──(──┴─Y─┴──)─────────────────────────────────────────────────────────────

N Specifies that the ANS print control characters are to be translated to IBM
Proprinter control characters as records are written to the data set.
Y Specifies that the ANS print control characters are not to be translated; instead
they are to be left as is for subsequent translation by a process you determine.
If the file is not a printer-destined file, the option is ignored.
BUFSIZE
The BUFSIZE option specifies the number of bytes for a buffer.
──BUFSIZE──(──n──)─────────────────────────────────────────────────────────────


RECORD output is buffered by default and has a default value for BUFSIZE of 64k.
STREAM output is buffered, but not by default, and has a default value for
BUFSIZE of zero.
If the value of zero is given to BUFSIZE, the number of bytes for buffering is equal
to the value specified in the RECSIZE or LRECL option.
The BUFSIZE option is valid only for a consecutive binary file. If the file is used for
terminal input, you should assign the value of zero to BUFSIZE for increased
efficiency.
CHARSET for record I/O

This version of the CHARSET option applies only to consecutive files using record
I/O. It gives the user the capability of using ASCII data files as input files, and
specifying the character set of output files.
┌─ASIS───┐
──CHARSET──(──┼─EBCDIC─┼──)────────────────────────────────────────────────────

└─ASCII──┘
Choose a suboption of CHARSET based on what form the file has (input) or what
form you want the file have (output).
CHARSET for stream I/O

This version of the CHARSET option applies for stream input and output files. It
gives the user the capability of using ASCII data files as input files, and specifying
the character set of output files. If you attempt to specify ASIS when using stream
I/O, no error is issued and character sets are treated as EBCDIC.
┌─EBCDIC─┐
──CHARSET──(──┴─ASCII──┴──)────────────────────────────────────────────────────

Choose a suboption of CHARSET based on what form the file has (input) or what
form you want the file to have (output).
DELAY
The DELAY option specifies the number of milliseconds to delay before retrying an
operation that fails when a file or record lock cannot be obtained by the system.
┌─#─┐
──DELAY──(──┴─n─┴──)───────────────────────────────────────────────────────────

This option is applicable only to DDM files.
DELIMIT
The DELIMIT option specifies whether the input file contains field delimiters or not.
A field delimiter is a blank or a user-defined character that separates the fields in a
record. This is applicable for sort input files only.
┌─N─┐
──DELIMIT──(──┴─Y─┴──)─────────────────────────────────────────────────────────


The sort utility distinguishes text files from binary files with the presence of field
delimiters. Input files that contain field delimiters are processed as text files;
otherwise, they are considered to be binary files. The library needs this information
in order to pass the correct parameters to the sort utility.
LRECL
The LRECL option is the same as the RECSIZE option.
──LRECL──(──n──)───────────────────────────────────────────────────────────────

If LRECL is not specified and not implied by a LINESIZE value (except for
TYPE(FIXED) files, the default is 1024.
LRMSKIP
The LRMSKIP option allows output to commence on the nth (n refers to the value
specified with the SKIP option of the PUT or GET statement) line of the first page
for the first SKIP format item to be executed after a file is opened.
┌─N─┐

──LRMSKIP──(──┴─Y─┴──)─────────────────────────────────────────────────────────

If n is zero or 1, output commences on the first line of the first page.
PROMPT
The PROMPT option specifies whether or not colons should be visible as prompts
for stream input from the terminal.
┌─N─┐

──PROMPT──(──┴─Y─┴──)──────────────────────────────────────────────────────────

PUTPAGE
The PUTPAGE option specifies whether or not the form feed character should be
followed by a carriage return character. This option applies only to printer-destined
files. Printer-destined files are stream output files declared with the PRINT
attribute, or record output files declared with the CTLASA environment option.
┌─NOCR─┐

──PUTPAGE──(──┴─CR───┴──)──────────────────────────────────────────────────────

NOCR
Indicates that the form feed character ('0C'x) is not followed by a carriage
return character ('0D'x).
CR
Indicates that the carriage return character is appended to the form feed
character. This option should be specified if output is sent to non-IBM printers.

RECCOUNT
The RECCOUNT option specifies the maximum number of records that can be
loaded into a relative or regional data set that is created during the PL/I file opening
process.
──RECCOUNT──(──n──)────────────────────────────────────────────────────────────

The RECCOUNT option is ignored if PL/I does not create, or recreate, the data set.
The default for the RECCOUNT option is 50.
RECSIZE
The RECSIZE option specifies the length, n, of records in the data set.
┌─512─┐
──RECSIZE──(──┴─n───┴──)───────────────────────────────────────────────────────

For regional and fixed-length data sets, RECSIZE specifies the length of each
record in the data set; for all other data set types, RECSIZE specifies the maximum
length records may have.
SAMELINE
The SAMELINE option specifies whether the system prompt occurs on the same
line as the statement that prompts for input.
┌─N─┐
──SAMELINE──(──┴─Y─┴──)────────────────────────────────────────────────────────

The following examples show the results of certain combinations of the PROMPT
and SAMELINE options:
Example 1
Given the statement PUT SKIP LIST('ENTER:');, output is as follows:
prompt(y), sameline(y) ENTER: (cursor)

prompt(n), sameline(y) ENTER: (cursor)
prompt(y), sameline(n) ENTER:
(cursor)
prompt(n), sameline(n) ENTER:
(cursor)
Example 2
Given the statement PUT SKIP LIST('ENTER');, output is as follows:
prompt(y), sameline(y) ENTER: (cursor)

prompt(n), sameline(y) ENTER (cursor)
prompt(y), sameline(n) ENTER
:
(cursor)
prompt(n), sameline(n) ENTER
(cursor)

SKIP0
The SKIP0 option specifies where the line cursor moves when SKIP(0) statement is
coded in the source program. SKIP0 applies to terminal files that are not linked as
PM applications.
┌─N─┐

──SKIPK──(──┴─Y─┴──)───────────────────────────────────────────────────────────

SKIP0(N)
Specifies that the cursor is to be moved to the beginning of the next line.
SKIP0(Y)
Specifies that the cursor to be moved to the beginning of the current line.
The following example shows how you could make the output to the terminal skip
zero lines so that the cursor moves to the beginning of the current output line:
export DD_SYSPRINT='stdout:,SKIPK(Y)'
TYPE
The TYPE option specifies the format of records in a native file.
┌─LF──────┐

──TYPE──(──┼─CRLF────┼──)──────────────────────────────────────────────────────

├─TEXT────┤
├─FIXED───┤
├─CRLFEOF─┤
└─U───────┘
CRLF
Specifies that records are delimited by the CR - LF character combination.
('CR' and 'LF' represent the ASCII values of carriage return and line feed,
'0D'x and '0A'x, respectively. For an output file, PL/I places the characters at
the end of each record; for an input file, PL/I discards the characters. For both
input and output, the characters are not counted in consideration for RECSIZE.
The data set must not contain any record that is longer than the value
determined for the record length of the data set.
LF Specifies that records are delimited by the LF character combination. ('LF'

represents the ASCII values of feed or '0A'x.) For an output file, PL/I places
the characters at the end of each record; for an input file, PL/I discards the
characters. For both input and output, the characters are not counted in
consideration for RECSIZE.
The data set must not contain any record that is longer than the value
determined for the record length of the data set.
TEXT
Equivalent to LF.
FIXED
Specifies that each record in the data set has the same length. The length
determined for records in the data set is used to recognize record boundaries.
All characters in a TYPE(FIXED) file are considered as data, including control
characters if they exist. Make sure the record length you specify reflects the

presence of these characters or make sure the record length you specify
accounts for all characters in the record.
CRLFEOF
Except for output files, this suboption specifies the same information as CRLF.
When one of these files is closed for output, an end-of-file marker is appended
to the last record.
U Indicates that records are unformatted. These unformatted files cannot be

used by any record or stream I/O statements except OPEN and CLOSE. You
can read from a TYPE(U) file only by using the FILEREAD built-in function.
You can write to a TYPE(U) file only by using the FILEWRITE built-in function.
The TYPE option applies only to CONSECUTIVE files, except that it is ignored for
printer-destined files with ASA(N) applied.
If your program attempts to access an existing data set with TYPE(FIXED) in effect
and the length of the data set is not a multiple of the logical record length you
specify, PL/I raises the UNDEFINEDFILE condition.
When using nonprint files with the TYPE(FIXED) attribute, SKIP is replaced by
trailing blanks to the end of the line. If TYPE(LF) is being used, SKIP is replaced
by LF with no trailing blanks.
Establishing data set characteristics

A data set consists of records stored in a particular format which the operating
system data management routines understand. When you declare or open a file in
your program, you are describing to PL/I and to the operating system the
characteristics of the records that file will contain. You can also use JCL or an
expression in the TITLE option of the OPEN statement to describe to the operating
system the characteristics of the data in data sets or in the PL/I files associated
with them.
You do not always need to describe your data both within the program and outside
it; often one description will serve for both data sets and their associated PL/I files.
There are, in fact, advantages to describing your data's characteristics in only one
place. These are described later in this chapter and in following chapters.
To effectively describe your program data and the data sets you will be using, you
need to understand something of how the operating system moves and stores data.
Blocks and records

The items of data in a data set are arranged in blocks separated by interblock gaps
(IBG). (Some manuals refer to these as interrecord gaps.)
A block is the unit of data transmitted to and from a data set. Each block contains
one record, part of a record, or several records. You can specify the block size in
the BLKSIZE parameter of the DD statement or in the BLKSIZE option of the
ENVIRONMENT attribute.
A record is the unit of data transmitted to and from a program. You can specify the
record length in the LRECL parameter of the DD statement, in the TITLE option of
the OPEN statement, or in the RECSIZE option of the ENVIRONMENT attribute.

When writing a PL/I program, you need consider only the records that you are
reading or writing; but when you describe the data sets that your program will
create or access, you must be aware of the relationship between blocks and
records.
Blocking conserves storage space in a magnetic storage volume because it

reduces the number of interblock gaps, and it can increase efficiency by reducing
the number of input/output operations required to process a data set. Records are
blocked and deblocked by the data management routines.
Information interchange codes: The normal code in which data is recorded is

the Extended Binary Coded Decimal Interchange Code (EBCDIC).
Each character in the ASCII code is represented by a 7-bit pattern and there are
128 such patterns. The ASCII set includes a substitute character (the SUB control
character) that is used to represent EBCDIC characters having no valid ASCII
code. The ASCII substitute character is translated to the EBCDIC SUB character,
which has the bit pattern 00111111.
Record formats
The records in a data set have one of the following formats:
Fixed-length
Variable-length
Undefined-length.
Records can be blocked if required. The operating system will deblock fixed-length
and variable-length records, but you must provide code in your program to deblock
undefined-length records.
You specify the record format in the RECFM parameter of the DD statement, in the
TITLE option of the OPEN statement, or as an option of the ENVIRONMENT
attribute.
Fixed-length records
You can specify the following formats for fixed-length records:
F Fixed-length, unblocked
FB Fixed-length, blocked
FS Fixed-length, unblocked, standard
FBS Fixed-length, blocked, standard.
In a data set with fixed-length records, as shown in Figure 18 on page 141, all
records have the same length. If the records are blocked, each block usually
contains an equal number of fixed-length records (although a block can be
truncated). If the records are unblocked, each record constitutes a block.

Unblocked records (F─format):
┌────────┐ ┌────────┐ ┌────────┐

│ Record │ IBG │ Record │ ... IBG │ Record │
└────────┘ └────────┘ └────────┘
Blocked records (FB─format):
┌───────────Block──────────┐
┌────────┬────────┬────────┐ ┌────────┬────────┬────────┐
│ Record │ Record │ Record │ IBG │ Record │ Record │ Record │ ...
└────────┴────────┴────────┘ └────────┴────────┴────────┘
Figure 18. Fixed-length records
Because it bases blocking and deblocking on a constant record length, the

operating system processes fixed-length records faster than variable-length records.
Variable-length records
You can specify the following formats for variable-length records:
V Variable-length, unblocked
VB Variable-length, blocked
VS Variable-length, unblocked, spanned
VBS Variable-length, blocked, spanned
V-format allows both variable-length records and variable-length blocks. A 4-byte

prefix of each record and the first 4 bytes of each block contain control information
for use by the operating system (including the length in bytes of the record or
block). Because of these control fields, variable-length records cannot be read
backward.
V-format signifies unblocked variable-length records. Each record is treated as a

block containing only one record. The first 4 bytes of the block contain block
control information, and the next 4 contain record control information.
VB-format signifies blocked variable-length records. Each block contains as many

complete records as it can accommodate. The first 4 bytes of the block contain
block control information, and a 4-byte prefix of each record contains record control
information.
Spanned Records: A spanned record is a variable-length record in which the length

of the record can exceed the size of a block. If this occurs, the record is divided
into segments and accommodated in two or more consecutive blocks by specifying
the record format as either VS or VBS. Segmentation and assembly are handled
by the operating system. The use of spanned records allows you to select a block
size, independently of record length, that will combine optimum use of auxiliary
storage with maximum efficiency of transmission.
VS-format is similar to V-format. Each block contains only one record or segment of
a record. The first 4 bytes of the block contain block control information, and the
next 4 contain record or segment control information (including an indication of
whether the record is complete or is a first, intermediate, or last segment).
VBS-format differs from VS-format in that each block contains as many complete
records or segments as it can accommodate; each block is, therefore,
approximately the same size (although there can be a variation of up to 4 bytes,
since each segment must contain at least 1 byte of data).

Undefined-length records
U-format allows the processing of records that do not conform to F- and V-formats.
The operating system and the compiler treat each block as a record; your program
must perform any required blocking or deblocking.
Data set organization

The data management routines of the operating system can handle a number of
types of data sets, which differ in the way data is stored within them and in the
allowed means of access to the data. The three main types of non-VSAM data
sets and the corresponding keywords describing their PL/I organization1 are as
follows:
Type of data set PL/I organization

Sequential CONSECUTIVE or ORGANIZATION(consecutive)
Indexed INDEXED or ORGANIZATION(indexed)
Direct REGIONAL or ORGANIZATION(relative)
A fourth type, partitioned, has no corresponding PL/I organization.
PL/I also provides support for three types of VSAM data organization: ESDS,
KSDS, and RRDS. For more information about VSAM data sets, see Chapter 10,
“Defining and using VSAM data sets” on page 197.
In a sequential (or CONSECUTIVE) data set, records are placed in physical

sequence. Given one record, the location of the next record is determined by its
physical position in the data set. Sequential organization can be selected for
direct-access devices.
An indexed sequential (or INDEXED) data set must reside on a direct-access

volume. An index or set of indexes maintained by the operating system gives the
location of certain principal records. This allows direct retrieval, replacement,
addition, and deletion of records, as well as sequential processing.
A direct (or REGIONAL) data set must reside on a direct-access volume. The data
set is divided into regions, each of which contains one or more records. A key that
specifies the region number allows direct-access to any record; sequential
processing is also possible.
In a partitioned data set, independent groups of sequentially organized data, each

called a member, reside in a direct-access data set. The data set includes a
directory that lists the location of each member. Partitioned data sets are often
called libraries. The compiler includes no special facilities for creating and
accessing partitioned data sets. Each member can be processed as a
CONSECUTIVE data set by a PL/I program. The use of partitioned data sets as
libraries is described under Chapter 7, “Using libraries” on page 156.
1 Do not confuse the terms “sequential” and “direct” with the PL/I file attributes SEQUENTIAL and DIRECT. The attributes refer to
how the file is to be processed, and not to the way the corresponding data set is organized.

Labels
The operating system uses internal labels to identify direct-access volumes and to
store data set attributes (for example, record length and block size). The attribute
information must originally come from a DD statement or from your program.
IBM standard labels have two parts: the initial volume label and header labels.
The initial volume label identifies a volume and its owner; the header labels
precede and follow each data set on the volume. Header labels contain system
information, device-dependent information (for example, recording technique), and
data-set characteristics.
Direct-access volumes have IBM standard labels. Each volume is identified by a

volume label, which is stored on the volume. This label contains a volume serial
number and the address of a volume table of contents (VTOC). The table of
contents, in turn, contains a label, termed a data set control block (DSCB), for each
data set stored on the volume.
Data Definition (DD) statement

A data definition (DD) statement is a job control statement that defines a data set to
the operating system, and is a request to the operating system for the allocation of
input/output resources. If the data sets are not dynamically allocated, each job step
must include a DD statement for each data set that is processed by the step.
Your OS/390 JCL User's Guide describes the syntax of job control statements.
The operand field of the DD statement can contain keyword parameters that
describe the location of the data set (for example, volume serial number and
identification of the unit on which the volume will be mounted) and the attributes of
the data itself (for example, record format).
The DD statement enables you to write PL/I source programs that are independent
of the data sets and input/output devices they will use. You can modify the
parameters of a data set or process different data sets without recompiling your
program.
The following paragraphs describe the relationship of some operands of the DD

statement to your PL/I program.
Write validity checking, which was standard in PL/I Version 1, is no longer

performed. Write validity checking can be requested through the OPTCD
subparameter of the DCB parameter of the JCL DD statement. See OS/VS2 Job
Control Language manual.
Use of the conditional subparameters

If you use the conditional subparameters of the DISP parameter for data sets
processed by PL/I programs, the step abend facility must be used. The step abend
facility is obtained as follows:
1. The ERROR condition should be raised or signaled whenever the program is to
terminate execution after a failure that requires the application of the conditional
subparameters.
2. The PL/I user exit must be changed to request an ABEND.

Data set characteristics
The DCB (data control block) parameter of the DD statement allows you to
describe the characteristics of the data in a data set, and the way it will be
processed, at run time. Whereas the other parameters of the DD statement deal
chiefly with the identity, location, and disposal of the data set, the DCB parameter
specifies information required for the processing of the records themselves. The
subparameters of the DCB parameter are described in your OS/390 JCL User's
Guide.
The DCB parameter contains subparameters that describe:

The organization of the data set and how it will be accessed (CYLOFL,
DSORG, LIMCT, NTM, and OPTCD subparameters)
Device-dependent information such as the line spacing for a printer (CODE,
FUNC, MODE, OPTCD=J, PRTSP, and STACK subparameters)
The record format (BLKSIZE, KEYLEN, LRECL, and RECFM subparameters)
The ASA control characters (if any) that will be inserted in the first byte of each
record (RECFM subparameter).
You can specify BLKSIZE, LRECL, KEYLEN, and RECFM (or their equivalents) in
the ENVIRONMENT attribute of a file declaration in your PL/I program instead of in
the DCB parameter.
You cannot use the DCB parameter to override information already established for
the data set in your PL/I program (by the file attributes declared and the other
attributes that are implied by them). DCB subparameters that attempt to change
information already supplied are ignored.
An example of the DCB parameter is:

DCB=(RECFM=FB,BLKSIZE=4KK,LRECL=4K)
which specifies that fixed-length records, 40 bytes in length, are to be grouped
together in a block 400 bytes long.
Using the TITLE option of the OPEN statement

You can use the TITLE option of the OPEN statement to identify the data set to be
associated with a PL/I file and, optionally, to provide additional characteristics of the
data set.
──TITLE──(──expression──)──────────────────────────────────────────────────────

The expression must yield a character string with the following syntax:
──┬─alternate_ddname────────────────────┬──────────────────────────────────────

│ ┌──
─────────────────────────────────┐ │
└───/filespec──┬───┬──┬───────────┬─┴─┘
└─,─┘ └─dd_option─┘
alternate_ddname
The name of an alternate DD_DDNAME environment variable. An alternate
DD_DDNAME environment variable is one not named after a file constant.
For example, if you had a file named INVENTRY in your program, and you

establish two DD_DDNAME environment variables—the first named
INVENTRY and the second named PARTS—you could associate the file with
the second one using this statement:
open file(Inventry) title('PARTS');
filespec
Any valid OS/390 UNIX or OS/390 PDS file specification.
dd_option
One or more options allowed in a DD_DDNAME environment variable.
For more information about options of the DD_DDNAME variable, see “Specifying
characteristics using DD_DDNAME environment variables” on page 133.
Here is an example of using the OPEN statement in this manner:

open file(Payroll) title('/June.Dat, append(n),recsize(52)');
With this form, PL/I obtains all DD information either from the TITLE expression or
from the ENVIRONMENT attribute of a file declaration. A DD_DDNAME
environment variable is not referenced.
Associating PL/I files with data sets

Opening a file: The execution of a PL/I OPEN statement associates a file with a
data set. This requires merging of the information describing the file and the data
set. If any conflict is detected between file attributes and data set characteristics,
the UNDEFINEDFILE condition is raised.
Subroutines of the PL/I library create a skeleton data control block for the data set.
They use the file attributes from the DECLARE and OPEN statements and any
attributes implied by the declared attributes, to complete the data control block as
far as possible. (See Figure 19 on page 146.) They then issue an OPEN macro
instruction, which calls the data management routines to check that the correct
volume is mounted and to complete the data control block.
The data management routines examine the data control block to see what
information is still needed and then look for this information, first in the DD
statement, and finally, if the data set exists and has standard labels, in the data set
labels. For new data sets, the data management routines begin to create the
labels (if they are required) and to fill them with information from the data control
block.
Neither the DD statement nor the data set label can override information provided
by the PL/I program; nor can the data set label override information provided by the
DD statement.
When the DCB fields are filled in from these sources, control returns to the PL/I
library subroutines. If any fields still are not filled in, the PL/I OPEN subroutine
provides default information for some of them. For example, if LRECL is not
specified, it is provided from the value given for BLKSIZE.

PL/I PROGRAM DCL MASTER FILE ENV(FB BLKSIZE(400),
RECSIZE(40));
OPEN FILE(MASTER);
DATA CONTROL BLOCK
DD STATEMENT //MASTER DD UNIT=2400 Record format FB

VOLUME=SER= 1791, Block size 400
DSNAME=LIST,
D CB = ( B U F N O = 3 , Record length 40
RECFM= F, Device type 2400
BLKSIZE=400,
LRECL=100) Number of buffers 3
Recording density 1600
DATA SET LABEL Record format=F

Record length=100
Blocking factor=4
Recording density=1600
Note: Information from the PL/I program overrides that from the DD statement and the data set label.
Information from the DD statement overrides that from the data set label.
Figure 19. How the operating system completes the DCB
Closing a file: The execution of a PL/I CLOSE statement dissociates a file from
the data set with which it was associated. The PL/I library subroutines first issue a
CLOSE macro instruction and, when control returns from the data management
routines, release the data control block that was created when the file was opened.
The data management routines complete the writing of labels for new data sets and
update the labels of existing data sets.
Specifying characteristics in the ENVIRONMENT attribute

You can use various options in the ENVIRONMENT attribute. Each type of file has
different attributes and environment options, which are listed below.
The ENVIRONMENT attribute: You use the ENVIRONMENT attribute of a PL/I

file declaration file to specify information about the physical organization of the data
set associated with a file, and other related information. The format of this
information must be a parenthesized option list.
──ENVIRONMENT──(──option-list──)───────────────────────────────────────────────

Abbreviation: ENV
You can specify the options in any order, separated by blanks or commas.
The following example illustrates the syntax of the ENVIRONMENT attribute in the
context of a complete file declaration (the options specified are for VSAM and are
discussed in Chapter 10, “Defining and using VSAM data sets” on page 197).

DCL FILENAME FILE RECORD SEQUENTIAL
INPUT ENV(VSAM GENKEY);
Table 13 summarizes the ENVIRONMENT options and file attributes. Certain

qualifications on their use are presented in the notes and comments for the figure.
Those options that apply to more than one data set organization are described in
the remainder of this chapter. In addition, in the following chapters, each option is
described with each data set organization to which it applies.
Table 13. Attributes of PL/I file declarations

S
t
Data set r
Record
type e
a
m
Legend:
Sequential Direct C Checked for VSAM
Consecutive Regional T D Default
e
l I Must be specified or implied
C e N Ignored for VSAM
o U U p
n n n r O Optional
File
Type s B b B b o R S Must be specified
e u u u u c I e I
- Invalid
c f f f f e n g n
u f f f f s d i d
t e e e e s e V o e V
i r r r r i x S n x S
v e e e e n e A a e A
e d d d d g d M l d M
File attributes1 Attributes implied
File I I I I I I I I I I I
Input1 D D D D D D D D D D D File
Output O O O O O O O O O O O File
Environment I I I S S S S S S S S File
Stream D - - - - - - - - - - File
Print1 O - - - - - - - - - - File stream output
Record - I I I I I I I I I I File
Update - O O O O - O O O O O File record
Sequential - D D D D - D D - - D File record
Buffered - D - D - I D D - - S File record
Keyed2 - - - O O I O O I I O File record
Direct - - - - - - - S S S S File record keyed
ENVIRONMENT options Comments

F|FB|FS|FBS|V| I S S - - - - N - - N VS and VBS are invalid with Stream
VB|VS|VBS||U
F|FB|U S S - - - - - N - - N ASCII data sets only
F|V|U - - - S S - - N S - N Only F for REGIONAL(1)
F|FB|V|VB - - - - - - S N - S N
RECSIZE(n) I I I I I S I C I I C RECSIZE and/or BLKSIZE must be specified
BLKSIZE(n) I I I I I - I N I I N for consecutive, indexed, and regional files
SCALARVARYING - O O O O - O O O O O Invalid for ASCII data sets
CONSECUTIVE D D D - - - - O - - O Allowed for VSAM ESDS
CTLASA|CTL360 - O O - - - - - - - - Invalid for ASCII data sets
GRAPHIC O - - - - - - - - - -
INDEXED - - - - - - S O - S O Allowed for VSAM ESDS
KEYLOC(n) - - - - - - O - - O -
ORGANIZATION D - - - -
INPUT or UPDATE files only;
GENKEY - - - - O O -
- - O O KEYED is required
REGIONAL(1) - - - S S - - - S - -
VSAM - - - - - - - S - - S
BKWD - - - - - - - O - - O
REUSE - - - - - - - O - - O OUTPUT file only
Notes:
1. A file with the INPUT attribute cannot have the PRINT attribute.
2. Keyed is required for INDEXED and REGIONAL output.
Data set organization options: The options that specify data set organization
are:

──┬─CONSECUTIVE───────┬────────────────────────────────────────────────────────

├─INDEXED───────────┤
├─REGIONAL──(──1──)─┤
└─VSAM──────────────┘
Each option is described in the discussion of the data set organization to which it
applies.
Other ENVIRONMENT options: You can use a constant or variable with those
ENVIRONMENT options that require integer arguments, such as block sizes and
record lengths. The variable must not be subscripted or qualified, and must have
attributes FIXED BINARY(31,0) and STATIC.
The list of equivalents for ENVIRONMENT options and DCB parameters are:
ENVIRONMENT option DCB subparameter
Record format RECFM1

RECSIZE LRECL
BLKSIZE BLKSIZE
CTLASA|CTL360 RECFM
KEYLENGTH KEYLEN
Record formats for record-oriented data transmission: Record formats

supported depend on the data set organization.
──┬─F───┬──────────────────────────────────────────────────────────────────────

├─FS──┤
├─FB──┤
├─FBS─┤
├─V───┤
├─VS──┤
├─VB──┤
├─VBS─┤
└─U───┘
Records can have one of the following formats:
Fixed-length F unblocked
FB blocked
FS unblocked, standard
FBS blocked, standard
Variable-length V unblocked
VB blocked
VS spanned
VBS blocked, spanned
Undefined-length U (cannot be blocked)
When U-format records are read into a varying-length string, PL/I sets the length of
the string to the block length of the retrieved data.
These record format options do not apply to VSAM data sets. If you specify a
record format option for a file associated with a VSAM data set, the option is
ignored.
You can only specify VS-format records for data sets with consecutive organization.

Record formats for stream-oriented data transmission: The record format
options for stream-oriented data transmission are discussed in “Using
stream-oriented data transmission” on page 162.
RECSIZE option: The RECSIZE option specifies the record length.
──RECSIZE──(──record-length──)─────────────────────────────────────────────────

For files associated with VSAM data sets, record-length is the sum of:
1. The length required for data. For variable-length and undefined-length records,
this is the maximum length.
2. Any control bytes required. Variable-length records require 4 (for the
record-length prefix); fixed-length and undefined-length records do not require
any.
For VSAM data sets, the maximum and average lengths of the records are
specified to the Access Method Services utility when the data set is defined. If you
include the RECSIZE option in the file declaration for checking purposes, you
should specify the maximum record size. If you specify RECSIZE and it conflicts
with the values defined for the data set, the UNDEFINEDFILE condition is raised.
You can specify record-length as an integer or as a variable with attributes FIXED

BINARY(31,0) STATIC.
The value is subject to the following conventions:

Maximum:
Fixed-length, and undefined (except ASCII data sets): 32760
V-format, and VS- and VBS-format with UPDATE files: 32756
VS- and VBS-format with INPUT and OUTPUT files: 16777215
ASCII data sets: 9999
VSAM data sets: 32761
Note: For VS- and VBS-format records longer than 32,756 bytes, you must
specify the length in the RECSIZE option of ENVIRONMENT, and for the DCB
subparameter of the DD statement you must specify LRECL=X. If RECSIZE
exceeds the allowed maximum for INPUT or OUTPUT, either a record
condition occurs or the record is truncated.
Zero value:
A search for a valid value is made first:
In the DD statement for the data set associated with the file, and second
In the data set label.
If neither of these provides a value, default action is taken (see “Record format,
BLKSIZE, and RECSIZE defaults” on page 151).
Negative Value:
The UNDEFINEDFILE condition is raised.
BLKSIZE option: The BLKSIZE option specifies the maximum block size on the
data set.

──BLKSIZE──(──block-size──)────────────────────────────────────────────────────

block-size is the sum of:

1. The total length(s) of one of the following:
A single record
A single record and either one or two record segments
Several records
Several records and either one or two record segments
Two record segments
A single record segment.
For variable-length records, the length of each record or record segment
includes the 4 control bytes for the record or segment length.
The above list summarizes all the possible combinations of records and record
segments options: fixed- or variable-length blocked or unblocked
2. Any further control bytes required.
Variable-length blocked records require 4 (for the block size).
Fixed-length and undefined-length records do not require any further control
bytes.
3. Any block prefix bytes required (ASCII data sets only).
block-size can be specified as an integer, or as a variable with attributes FIXED

BINARY(31,0) STATIC.
The value is subject to the following conventions:

Maximum:
32760
Zero value:
If you set BLKSIZE to 0, under OS/390 the Data Facility Product sets the block
size. For an elaboration of this topic, see “Record format, BLKSIZE, and
RECSIZE defaults” on page 151. BLKSIZE defaults.
Negative value:
The UNDEFINEDFILE condition is raised.
The relationship of block size to record length depends on the record format:
FB-format or FBS-format
The block size must be a multiple of the record length.
VB-format:
The block size must be equal to or greater than the sum of:
VS-format or VBS-format:
The block size can be less than, equal to, or greater than the record length.
1. The maximum length of any record
2. Four control bytes.
Notes:
Use the BLKSIZE option with unblocked (F- or V-format) records in either of the
following ways:

– Specify the BLKSIZE option, but not the RECSIZE option. Set the record
length equal to the block size (minus any control or prefix bytes), and leave
the record format unchanged.
– Specify both BLKSIZE and RECSIZE and ensure that the relationship of
the two values is compatible with blocking for the record format you use.
Set the record format to FB or VB, whichever is appropriate.
If for FB-format or FBS-format records the block size equals the record length,
the record format is set to F.
The BLKSIZE option does not apply to VSAM data sets, and is ignored if you
specify it for one.
Record format, BLKSIZE, and RECSIZE defaults: If you do not specify either
the record format, block size, or record length for a non-VSAM data set, the
following default action is taken:
Record format:
A search is made in the associated DD statement or data set label. If the
search does not provide a value, the UNDEFINEDFILE condition is raised,
except for files associated with dummy data sets or the foreground terminal, in
which case the record format is set to U.
Block size or record length:
If one of these is specified, a search is made for the other in the associated
DD statement or data set label. If the search provides a value, and if this
value is incompatible with the value in the specified option, the
UNDEFINEDFILE condition is raised. If the search is unsuccessful, a value is
derived from the specified option (with the addition or subtraction of any control
or prefix bytes).
If neither is specified, the UNDEFINEDFILE condition is raised, except for files
associated with dummy data sets, in which case BLKSIZE is set to 121 for
F-format or U-format records and to 129 for V-format records. For files
associated with the foreground terminal, RECSIZE is set to 120.
If you are using OS/390 with the Data Facility Product system-determined
block size, DFP determines the optimum block size for the device type
assigned. If you specify BLKSIZE(0) in either the DD assignment or the
ENVIRONMENT statement, DFP calculates BLKSIZE using the record length,
record format, and device type.
GENKEY option — key classification: The GENKEY (generic key) option

applies only to INDEXED and VSAM key-sequenced data sets. It enables you to
classify keys recorded in a data set and to use a SEQUENTIAL KEYED INPUT or
SEQUENTIAL KEYED UPDATE file to access records according to their key
classes.
──GENKEY───────────────────────────────────────────────────────────────────────

A generic key is a character string that identifies a class of keys; all keys that begin
with the string are members of that class. For example, the recorded keys “ABCD”,
“ABCE”, and “ABDF” are all members of the classes identified by the generic keys
“A” and “AB”, and the first two are also members of the class “ABC”; and the three
recorded keys can be considered to be unique members of the classes “ABCD”,
“ABCE”, and “ABDF”, respectively.

The GENKEY option allows you to start sequential reading or updating of a VSAM
data set from the first record that has a key in a particular class, and for an
INDEXED data set from the first nondummy record that has a key in a particular
class. You identify the class by including its generic key in the KEY option of a
READ statement. Subsequent records can be read by READ statements without
the KEY option. No indication is given when the end of a key class is reached.
Although you can retrieve the first record having a key in a particular class by using
a READ with the KEY option, you cannot obtain the actual key unless the records
have embedded keys, since the KEYTO option cannot be used in the same
statement as the KEY option.
In the following example, a key length of more than 3 bytes is assumed:

DCL IND FILE RECORD SEQUENTIAL KEYED
UPDATE ENV (GENKEY);
.
.
.
READ FILE(IND) INTO(INFIELD)
KEY ('ABC');
.
.
.
NEXT: READ FILE (IND) INTO (INFIELD);
.
.
.
GO TO NEXT;
The first READ statement causes the first nondummy record in the data set whose
key begins with “ABC” to be read into INFIELD; each time the second READ
statement is executed, the nondummy record with the next higher key is retrieved.
Repeated execution of the second READ statement could result in reading records
from higher key classes, since no indication is given when the end of a key class is
reached. It is your responsibility to check each key if you do not wish to read
beyond the key class. Any subsequent execution of the first READ statement
would reposition the file to the first record of the key class “ABC”.
If the data set contains no records with keys in the specified class, or if all the
records with keys in the specified class are dummy records, the KEY condition is
raised. The data set is then positioned either at the next record that has a higher
key or at the end of the file.
The presence or absence of the GENKEY option affects the execution of a READ
statement which supplies a source key that is shorter than the key length specified
in the KEYLEN subparameter. This KEYLEN subparameter is found in the DD
statement that defines the indexed data set. If you specify the GENKEY option, it
causes the source key to be interpreted as a generic key, and the data set is
positioned to the first nondummy record in the data set whose key begins with the
source key. If you do not specify the GENKEY option, a READ statement's short
source key is padded on the right with blanks to the specified key length, and the
data set is positioned to the record that has this padded key (if such a record
exists). For a WRITE statement, a short source key is always padded with blanks.

Use of the GENKEY option does not affect the result of supplying a source key
whose length is greater than or equal to the specified key length. The source key,
truncated on the right if necessary, identifies a specific record (whose key can be
considered to be the only member of its class).
SCALARVARYING option — varying-length strings: You use the

SCALARVARYING option in the input/output of varying-length strings; you can use
it with records of any format.
──SCALARVARYING────────────────────────────────────────────────────────────────

When storage is allocated for a varying-length string, the compiler includes a 2-byte
prefix that specifies the current length of the string. For an element varying-length
string, this prefix is included on output, or recognized on input, only if
SCALARVARYING is specified for the file.
When you use locate mode statements (LOCATE and READ SET) to create and
read a data set with element varying-length strings, you must specify
SCALARVARYING to indicate that a length prefix is present, since the pointer that
locates the buffer is always assumed to point to the start of the length prefix.
When you specify SCALARVARYING and element varying-length strings are

transmitted, you must allow two bytes in the record length to include the length
prefix.
A data set created using SCALARVARYING should be accessed only by a file that
also specifies SCALARVARYING.
You must not specify SCALARVARYING and CTLASA/CTL360 for the same file, as
this causes the first data byte to be ambiguous.
KEYLENGTH option: Use the KEYLENGTH option to specify the length of the
recorded key for KEYED files where n is the length. You can specify KEYLENGTH
for INDEXED files.
──KEYLENGTH──(──n──)───────────────────────────────────────────────────────────

If you include the KEYLENGTH option in a VSAM file declaration for checking
purposes, and the key length you specify in the option conflicts with the value
defined for the data set, the UNDEFINEDFILE condition is raised.
ORGANIZATION option: The ORGANIZATION option specifies the organization

of the data set associated with the PL/I file.
┌─CONSECUTIVE─┐
──ORGANIZATION──(──┼─INDEXED─────┼──)──────────────────────────────────────────

└─RELATIVE────┘
CONSECUTIVE
Specifies that the files is associated with a consecutive data set. A
consecutive file can be either a native data set or a VSAM, ESDS, RRDS, or
KSDS data set.

RELATIVE
Specifies that the file is associated with a relative data set. RELATIVE
specifies that the data set contains records that do not have recorded keys.
A relative file is a VSAM direct data set. Relative keys range from 1 to nnnn.
Data set types used by PL/I record I/O

Data sets with the RECORD attribute are processed by record-oriented data
transmission in which data is transmitted to and from auxiliary storage exactly as it
appears in the program variables; no data conversion takes place. A record in a
data set corresponds to a variable in the program.
Table 14 shows the facilities that are available with the various types of data sets
that can be used with PL/I Record I/O.
Table 14. A comparison of data set types available to PL/I record I/O
VSAM VSAM VSAM REGIONAL
KSDS ESDS RRDS INDEXED CONSECUTIVE (1)
SEQUENCE Key Entry Num- Key Entry By
order order bered order order region
DEVICES DASD DASD DASD DASD DASD, DASD
card, etc.
ACCESS
1 By key
2 Sequential 123 123 123 12 2 12
Alternate
index 123 123 No No No No
access
as above
How With At In With At In
extended new end empty new end empty
keys slots keys slots
DELETION
1 Space reusable Yes, 1 No Yes, 1 Yes, 2 No Yes, 2
2 Space not
reusable
The following chapters describe how to use Record I/O data sets for different types
of data sets:
Chapter 8, “Defining and using consecutive data sets” on page 162
Chapter 9, “Defining and using regional data sets” on page 186
Chapter 10, “Defining and using VSAM data sets” on page 197
OS/390 UNIX System Services Only
Setting environment variables

There are a number of environment variables that can be set and exported for use
with OS/390 UNIX.
To set the environment variables system wide so all users have access to them,
add the lines suggested in the subsections to the file /etc/profile. To set them

for a specific user only, add them to the file .profile in the user's home directory.
The variables are set the next time the user logs on.
The following example illustrates how to set environment variables:

LANG=ja_JP
NLSPATH=/usr/lib/nls/msg/%L/%N:/usr/lib/nls/msg/prime/%N
LIBPATH=/home/joe/usr/lib:/home/joe/mylib:/usr/lib
export LANG NLSPATH LIBPATH
Rather than using the last statement in the previous example, you could have
added export to each of the preceding lines (export LANG=ja_JP...).
You can use the ECHO command to determine the current setting of an
environment variable. To define the value of BYPASS, you can use either of the
following two examples:
echo $LANG
echo $LIBPATH
PL/I standard files (SYSPRINT and SYSIN)

SYSIN is read from stdin and SYSPRINT is directed to stdout by default. If you
want either to be associated differently, you must use the TITLE option of the
OPEN statement, or establish a DD_DDNAME environment variable naming a data
set or another device. Environment variables are discussed above in “Setting
environment variables” on page 154.
Redirecting standard input, output, and error devices

You can also redirect standard input, standard output, and standard error devices
to a file. You could use redirection in the following program:
Hello2: proc options(main);
put list('Hello!');
end;
After compiling and linking the program, you could invoke it from the command line
by entering:
hello2 > hello2.out
If you want to combine stdout and stderr in a single file, enter the following
command:
hello2 > hello2.out 2>&1
As is true with display statements, the greater than sign redirects the output to the
file that is specified after it, in this case hello2.out. This means that the word
'Hello' is written in the file hello2.out. Note also that the output includes printer
control characters since the PRINT attribute is applied to SYSPRINT by default.
READ statements can access data from stdin; however, the record into which the
data is to be put must have an LRECL equal to 1.
End of OS/390 UNIX System Services Only

Chapter 7. Using libraries
Within the OS/390 operating system, the terms “partitioned data set,” “partitioned
data set/extension,” and “library” are synonymous and refer to a type of data set
that can be used for the storage of other data sets (usually programs in the form of
source, object or load modules). A library must be stored on direct-access storage
and be wholly contained in one volume. It contains independent, consecutively
organized data sets, called members. Each member has a unique name, not more
than 8 characters long, which is stored in a directory that is part of the library. All
the members of one library must have the same data characteristics because only
one data set label is maintained.
You can create members individually until there is insufficient space left for a new
entry in the directory, or until there is insufficient space for the member itself. You
can access members individually by specifying the member name.
Use DD statements or their conversational mode equivalent to create and access

members.
You can delete members by means of the IBM utility program IEHPROGM. This
deletes the member name from the directory so that the member can no longer be
accessed, but you cannot use the space occupied by the member itself again
unless you recreate the library or compress the unused space using, for example,
the IBM utility program IEBCOPY. If you attempt to delete a member by using the
DISP parameter of a DD statement, it causes the whole data set to be deleted.
Types of libraries
You can use the following types of libraries with a PL/I program:
The system program library SYS1.LINKLIB or its equivalent. This can contain
all system processing programs such as compilers and the linkage editor.
Private program libraries. These usually contain user-written programs. It is
often convenient to create a temporary private library to store the load module
output from the linkage editor until it is executed by a later job step in the same
job. The temporary library will be deleted at the end of the job. Private
libraries are also used for automatic library call by the linkage editor and the
loader.
The system procedure library SYS1.PROCLIB or its equivalent. This contains
the job control procedures that have been cataloged for your installation.
How to use a library

A PL/I program can use a library directly. If you are adding a new member to a
library, its directory entry will be made by the operating system when the
associated file is closed, using the member name specified as part of the data set
name.
If you are accessing a member of a library, its directory entry can be found by the
operating system from the member name that you specify as part of the data set
name.

More than one member of the same library can be processed by the same PL/I
program, but only one such output file can be open at any one time. You access
different members by giving the member name in a DD statement.
Creating a library
To create a library include in your job step a DD statement containing the
information given in Table 15. The information required is similar to that for a
consecutively organized data set (see “Defining files using record I/O” on
page 178) except for the SPACE parameter.
Table 15. Information required when creating a library

Information Required Parameter of DD statement
Type of device that will be used UNIT=
Serial number of the volume that will contain the library VOLUME=SER
Name of the library DSNAME=
Amount of space required for the library SPACE=
Disposition of the library DISP=
SPACE parameter
The SPACE parameter in a DD statement that defines a library must always be of
the form:
SPACE=(units,(quantity,increment,directory))
Although you can omit the third term (increment), indicating its absence by a
comma, the last term, specifying the number of directory blocks to be allocated,
must always be present.
The amount of auxiliary storage required for a library depends on the number and
sizes of the members to be stored in it and on how often members will be added or
replaced. (Space occupied by deleted members is not released.) The number of
directory blocks required depends on the number of members and the number of
aliases. You can specify an incremental quantity in the SPACE parameter that
allows the operating system to obtain more space for the data set, if such is
necessary at the time of creation or at the time a new member is added; the
number of directory blocks, however, is fixed at the time of creation and cannot be
increased.
For example, the DD statement:

// PDS DD UNIT=SYSDA,VOL=SER=3412,
// DSNAME=ALIB,
// SPACE=(CYL,(5,,1K)),
// DISP=(,CATLG)
requests the job scheduler to allocate 5 cylinders of the DASD with a volume serial
number 3412 for a new library name ALIB, and to enter this name in the system
catalog. The last term of the SPACE parameter requests that part of the space
allocated to the data set be reserved for ten directory blocks.
Chapter 7. Using libraries 157

Creating and updating a library member
The members of a library must have identical characteristics. Otherwise, you might
later have difficulty retrieving them. Identical characteristics are necessary because
the volume table of contents (VTOC) will contain only one data set control block
(DSCB) for the library and not one for each member. When using a PL/I program
to create a member, the operating system creates the directory entry; you cannot
place information in the user data field.
When creating a library and a member at the same time, your DD statement must
include all the parameters listed under “Creating a library” on page 157 (although
you can omit the DISP parameter if the data set is to be temporary). The DSNAME
parameter must include the member name in parentheses. For example,
DSNAME=ALIB(MEM1) names the member MEM1 in the data set ALIB. If the
member is placed in the library by the linkage editor, you can use the linkage editor
NAME statement or the NAME compile-time option instead of including the member
name in the DSNAME parameter. You must also describe the characteristics of the
member (record format, etc.) either in the DCB parameter or in your PL/I program.
These characteristics will also apply to other members added to the data set.
When creating a member to be added to an existing library, you do not need the
SPACE parameter. The original space allocation applies to the whole of the library
and not to an individual member. Furthermore, you do not need to describe the
characteristics of the member, since these are already recorded in the DSCB for
the library.
To add two more members to a library in one job step, you must include a DD
statement for each member, and you must close one file that refers to the library
before you open another.
Examples
The use of the cataloged procedure IBMZC to compile a simple PL/I program and
place the object module in a new library named EXLIB is shown in Figure 20 on
page 159. The DD statement that defines the new library and names the object
module overrides the DD statement SYSLIN in the cataloged procedure. (The PL/I
program is a function procedure that, given two values in the form of the character
string produced by the TIME built-in function, returns the difference in milliseconds.)
The use of the cataloged procedure IBMZCL to compile and link-edit a PL/I
program and place the load module in the existing library HPU8.CCLM is shown in
Figure 21 on page 159.

//OPT1K#1 JOB
//TR EXEC IBMZC
//PLI.SYSLIN DD UNIT=SYSDA,DSNAME=HPU8.EXLIB(ELAPSE),
// SPACE=(TRK,(1,,1)),DISP=(NEW,CATLG)
//PLI.SYSIN DD ]
ELAPSE: PROC(TIME1,TIME2);
DCL (TIME1,TIME2) CHAR(9),
H1 PIC '99' DEF TIME1,
M1 PIC '99' DEF TIME1 POS(3),
MS1 PIC '99999' DEF TIME1 POS(5),
H2 PIC '99' DEF TIME2,
M2 PIC '99' DEF TIME2 POS(3),
MS2 PIC '99999' DEF TIME2 POS(5),
ETIME FIXED DEC(7);
IF H2<H1 THEN H2=H2+24;
ETIME=((H2]6K+M2)]6KKKK+MS2)-((H1]6K+M1)]6KKKK+MS1);
RETURN(ETIME);
END ELAPSE;
/]
Figure 20. Creating new libraries for compiled object modules
//OPT1K#2 JOB
//TRLE EXEC IBMZCL
//PLI.SYSIN DD ]
MNAME: PROC OPTIONS(MAIN);
.
.
.
program
.
.
.
END MNAME;
/]
//LKED.SYSLMOD DD DSNAME=HPU8.CCLM(DIRLIST),DISP=OLD
Figure 21. Placing a load module in an existing library
To use a PL/I program to add or delete one or more records within a member of a
library, you must rewrite the entire member in another part of the library. This is
rarely an economic proposition, since the space originally occupied by the member
cannot be used again. You must use two files in your PL/I program, but both can
be associated with the same DD statement. The program shown in Figure 23 on
page 160 updates the member created by the program in Figure 22 on page 160.
It copies all the records of the original member except those that contain only
blanks.

//OPT1K#3 JOB
//TREX EXEC IBMZCBG
//PLI.SYSIN DD ]
NMEM: PROC OPTIONS(MAIN);
DCL IN FILE RECORD SEQUENTIAL INPUT,
OUT FILE RECORD SEQUENTIAL OUTPUT,
P POINTER,
IOFIELD CHAR(8K) BASED(P),
EOF BIT(1) INIT('K'B);
OPEN FILE(IN),FILE (OUT);
ON ENDFILE(IN) EOF='1'B;
READ FILE(IN) SET(P);
DO WHILE (¬EOF);
PUT FILE(SYSPRINT) SKIP EDIT (IOFIELD) (A);
WRITE FILE(OUT) FROM(IOFIELD);
READ FILE(IN) SET(P);
END;
CLOSE FILE(IN),FILE(OUT);
END NMEM;
/]
//GO.OUT DD UNIT=SYSDA,DSNAME=HPU8.ALIB(NMEM),
// DISP=(NEW,CATLG),SPACE=(TRK,(1,1,1)),
// DCB=(RECFM=FB,BLKSIZE=36KK,LRECL=8K)
//GO.IN DD ]
MEM: PROC OPTIONS(MAIN);
/] this is an incomplete dummy library member ]/
Figure 22. Creating a library member in a PL/I program
//OPT1K#4 JOB
//TREX EXEC IBMZCBG
//PLI.SYSIN DD ]
UPDTM: PROC OPTIONS(MAIN);
DCL (OLD,NEW) FILE RECORD SEQUENTIAL,
EOF BIT(1) INIT('K'B),
DATA CHAR(8K);
ON ENDFILE(OLD) EOF = '1'B;
OPEN FILE(OLD) INPUT,FILE(NEW) OUTPUT TITLE('OLD');
READ FILE(OLD) INTO(DATA);
DO WHILE (¬EOF);
PUT FILE(SYSPRINT) SKIP EDIT (DATA) (A);
IF DATA=' ' THEN ;
ELSE WRITE FILE(NEW) FROM(DATA);
READ FILE(OLD) INTO(DATA);
END;
CLOSE FILE(OLD),FILE(NEW);
END UPDTM;
/]
//GO.OLD DD DSNAME=HPU8.ALIB(NMEM),DISP=(OLD,KEEP)
Figure 23. Updating a library member
Extracting information from a library directory

The directory of a library is a series of records (entries) at the beginning of the data
set. There is at least one directory entry for each member. Each entry contains a
member name, the relative address of the member within the library, and a variable
amount of user data.
User data is information inserted by the program that created the member. An
entry that refers to a member (load module) written by the linkage editor includes
user data in a standard format, described in the systems manuals.

If you use a PL/I program to create a member, the operating system creates the
directory entry for you and you cannot write any user data. However, you can use
assembler language macro instructions to create a member and write your own
user data. The method for using macro instructions to do this is described in the
data management manuals.

Chapter 8. Defining and using consecutive data sets
This chapter covers consecutive data set organization and the ENVIRONMENT
options that define consecutive data sets for stream and record-oriented data
transmission. It then covers how to create, access, and update consecutive data
sets for each type of transmission.
In a data set with consecutive 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. You can retrieve
the records only in the order in which they were written. See Table 13 on
page 147 for valid file attributes and ENVIRONMENT options for consecutive data
sets.
Using stream-oriented data transmission

This section covers how to define data sets for use with PL/I files that have the
STREAM attribute. It covers the ENVIRONMENT options you can use and how to
create and access data sets. The essential parameters of the DD statements you
use in creating and accessing these data sets are summarized in tables, and
several examples of PL/I programs are included to illustrate the text.
Data sets with the STREAM attribute are processed by stream-oriented data
transmission, which allows your PL/I program to ignore block and record
boundaries and treat a data set as a continuous stream of data values in character
or graphic form.
You create and access data sets for stream-oriented data transmission using the
list-, data-, and edit-directed input and output statements described in the PL/I
Language Reference.
For output, PL/I converts the data items from program variables into character form
if necessary, and builds the stream of characters or graphics into records for
transmission to the data set.
For input, PL/I takes records from the data set and separates them into the data
items requested by your program, converting them into the appropriate form for
assignment to program variables.
You can use stream-oriented data transmission to read or write graphic data.
There are terminals, printers, and data-entry devices that, with the appropriate
programming support, can display, print, and enter graphics. You must be sure
that your data is in a format acceptable for the intended device, or for a print utility
program.
Defining files using stream I/O

You define files for stream-oriented data transmission by a file declaration with the
following attributes:
DCL filename FILE STREAM
INPUT | {OUTPUT [PRINT]}
ENVIRONMENT(options);

Default file attributes are shown in Table 13 on page 147; the FILE attribute is
described in the PL/I Language Reference. The PRINT attribute is described
further in “Using PRINT files with stream I/O” on page 169. Options of the
ENVIRONMENT attribute are discussed below.
Specifying ENVIRONMENT options

Table 13 on page 147 summarizes the ENVIRONMENT options. The options
applicable to stream-oriented data transmission are:
CONSECUTIVE or ORGANIZATION(CONSECUTIVE)
F|FB|FS|FBS|V|VB|VS|VBS|U
RECSIZE(record-length)
BLKSIZE(block-size)
GRAPHIC
BLKSIZE is described in Chapter 6, “Using data sets and files,” beginning on page
149. Descriptions of the rest of these options follow immediately below.
CONSECUTIVE
STREAM files must have CONSECUTIVE data set organization; however, it is not
necessary to specify this in the ENVIRONMENT options since CONSECUTIVE is
the default data set organization. The CONSECUTIVE option for STREAM files is
the same as that described in “Data set organization” on page 142.
──CONSECUTIVE──────────────────────────────────────────────────────────────────

Record format options

Although record boundaries are ignored in stream-oriented data transmission,
record format is important when creating a data set. This is not only because
record format affects the amount of storage space occupied by the data set and the
efficiency of the program that processes the data, but also because the data set
can later be processed by record-oriented data transmission.
Having specified the record format, you need not concern yourself with records and
blocks as long as you use stream-oriented data transmission. You can consider
your data set a series of characters or graphics arranged in lines, and you can use
the SKIP option or format item (and, for a PRINT file, the PAGE and LINE options
and format items) to select a new line.
──┬─F───┬──────────────────────────────────────────────────────────────────────

├─FS──┤
├─FB──┤
├─FBS─┤
├─V───┤
├─VS──┤
├─VB──┤
├─VBS─┤
└─U───┘
Records can have one of the following formats, which are described in “Record
formats” on page 140.
Chapter 8. Defining and using consecutive data sets 163

Fixed-length F unblocked
FB blocked
FS unblocked, standard
FBS blocked, standard
Variable-length V unblocked
VB blocked
VS
VBS
Undefined-length U (cannot be blocked)
Blocking and deblocking of records are performed automatically.
RECSIZE
RECSIZE for stream-oriented data transmission is the same as that described in
“Specifying characteristics in the ENVIRONMENT attribute” on page 146.
Additionally, a value specified by the LINESIZE option of the OPEN statement
overrides a value specified in the RECSIZE option. LINESIZE is discussed in the
PL/I Language Reference.
Additional record-size considerations for list- and data-directed transmission of

graphics are given in the PL/I Language Reference.
Defaults for record format, BLKSIZE, and RECSIZE

If you do not specify the record format, BLKSIZE, or RECSIZE option in the
ENVIRONMENT attribute, or in the associated DD statement or data set label, the
following action is taken:
Input files:
Defaults are applied as for record-oriented data transmission, described in
“Record format, BLKSIZE, and RECSIZE defaults” on page 151.
Output files:
Record format
Set to VB-format
Record length
The specified or default LINESIZE value is used:
PRINT files:
F, FB, FBS, or U: line size + 1
V or VB: line size + 5
Non-PRINT files:
F, FB, FBS, or U: linesize
V or VB: linesize + 4
Block size:
F, FB, or FBS: record length
V or VB: record length + 4

GRAPHIC option
Specify the GRAPHIC option for edit-directed I/O.
──GRAPHIC──────────────────────────────────────────────────────────────────────

The ERROR condition is raised for list- and data-directed I/O if you have graphics
in input or output data and do not specify the GRAPHIC option.
For edit-directed I/O, the GRAPHIC option specifies that left and right delimiters are
added to DBCS variables and constants on output, and that input graphics will have
left and right delimiters. If you do not specify the GRAPHIC option, left and right
delimiters are not added to output data, and input graphics do not require left and
right delimiters. When you do specify the GRAPHIC option, the ERROR condition
is raised if left and right delimiters are missing from the input data.
For information on the graphic data type, and on the G-format item for edit-directed
I/O, see the PL/I Language Reference.
Creating a data set with stream I/O

To create a data set, you must give the operating system certain information either
in your PL/I program or in the DD statement that defines the data set. For OS/390
UNIX, use one of the following to provide the additional information:
TITLE option of the OPEN statement
DD_DDNAME environment variable
ENVIRONMENT attribute
The following paragraphs indicate the essential information, and discuss some of
the optional information you can supply.
Essential information
When your application creates a STREAM file, it must supply a line-size value for
that file from one of the following sources:
LINESIZE option of the OPEN statement
If you choose the LINESIZE option, it overrides all other sources.
RECSIZE option of the ENVIRONMENT attribute
The RECSIZE option of the ENVIRONMENT attribute overrides the other
RECSIZE options.
RECSIZE option of the TITLE option of the OPEN statement
RECSIZE specified in the TITLE option of the OPEN statement has precedence
over the RECSIZE option of the DD_DDNAME environment variable.
RECSIZE option of the DD_DDNAME environment variable
PL/I-supplied default value
the PL/I default is used when you do not supply any value.
If LINESIZE is not supplied, but a RECSIZE value is, PL/I derives the line-size
value from RECSIZE as follows:
A PRINT file with the ASA(N) option applied has a RECSIZE value of 4
A PRINT file with the ASA(Y) option applied has a RECSIZE value of 1
In all other cases, the value of RECSIZE is assigned to the line-size value.

PL/I determines a default line-size value based on attributes of the file and the type
of associated data set. In cases where PL/I cannot supply an appropriate default
line size, the UNDEFINEDFILE condition is raised.
A default line-size value is supplied for an OUTPUT file when:

The file has the PRINT attribute. In this case, the value is obtained from the
tab control table.
The associated data set is the terminal (stdout: or stderr:). In this case the
value is 120.
PL/I always derives the record length of the data set from the line-size value. A
record-length value is derived from the line-size value as follows:
For a PRINT file with the ASA(N) option applied, the value is line size + 4
For a PRINT file with the ASA(Y) option applied, the value is line size + 1
In all other cases, the line-size value is assigned to the record-length value
Examples
The use of edit-directed stream-oriented data transmission to create a data set on a
direct access storage device is shown in Figure 24. The data read from the input
stream by the file SYSIN includes a field VREC that contains five unnamed
7-character subfields; the field NUM defines the number of these subfields that
contain information. The output file WORK transmits to the data set the whole of
the field FREC and only those subfields of VREC that contain information.
//EX7#2 JOB
//STEP1 EXEC IBMZCBG
//PLI.SYSIN DD ]
PEOPLE: PROC OPTIONS(MAIN);
DCL WORK FILE STREAM OUTPUT,
1 REC,
2 FREC,
3 NAME CHAR(19),
3 NUM CHAR(1),
3 PAD CHAR(25),
2 VREC CHAR(35),
EOF BIT(1) INIT('K'B),
IN CHAR(8K) DEF REC;
ON ENDFILE(SYSIN) EOF='1'B;
OPEN FILE(WORK) LINESIZE(4KK);
GET FILE(SYSIN) EDIT(IN)(A(8K));
DO WHILE (¬EOF);
PUT FILE(WORK) EDIT(IN)(A(45+7]NUM));
GET FILE(SYSIN) EDIT(IN)(A(8K));
END;
CLOSE FILE(WORK);
END PEOPLE;
/]
//GO.WORK DD DSN=HPU8.PEOPLE,DISP=(NEW,CATLG),UNIT=SYSDA,
// SPACE=(TRK,(1,1))
//GO.SYSIN DD ]
R.C.ANDERSON K 2K2848 DOCTOR
B.F.BENNETT 2 771239 PLUMBER VICTOR HAZEL
R.E.COLE 5 698635 COOK ELLEN VICTOR JOAN ANN OTTO
J.F.COOPER 5 418915 LAWYER FRANK CAROL DONALD NORMAN BRENDA
A.J.CORNELL 3 237837 BARBER ALBERT ERIC JANET
E.F.FERRIS 4 158636 CARPENTER GERALD ANNA MARY HAROLD
/]
Figure 24. Creating a data set with stream-oriented data transmission

Figure 25 on page 167 shows an example of a program using list-directed output
to write graphics to a stream file. It assumes that you have an output device that
can print graphic data. The program reads employee records and selects persons
living in a certain area. It then edits the address field, inserting one graphic blank
between each address item, and prints the employee number, name, and address.
//EX7#3 JOB
//PLI.SYSIN DD ]
% PROCESS GRAPHIC;
XAMPLE1: PROC OPTIONS(MAIN);
DCL INFILE FILE INPUT RECORD,
OUTFILE FILE OUTPUT STREAM ENV(GRAPHIC);
/] GRAPHIC OPTION MEANS DELIMITERS WILL BE INSERTED ON OUTPUT FILES. ]/
DCL
1 IN,
3 EMPNO CHAR(6),
3 SHIFT1 CHAR(1),
3 NAME,
5 LAST G(7),
5 FIRST G(7),
3 SHIFT2 CHAR(1),
3 ADDRESS,
5 ZIP CHAR(6),
5 SHIFT3 CHAR(1),
5 DISTRICT G(5),
5 CITY G(5),
5 OTHER G(8),
5 SHIFT4 CHAR(1);
DCL EOF BIT(1) INIT('K'B);
DCL ADDRWK G(2K);
ON ENDFILE (INFILE) EOF = '1'B;
READ FILE(INFILE) INTO(IN);
DO WHILE(¬EOF);
DO;
IF SUBSTR(ZIP,1,3)¬='3KK'
THEN LEAVE;
L=K;
ADDRWK=DISTRICT;
DO I=1 TO 5;
IF SUBSTR(DISTRICT,I,1)= < >
THEN LEAVE; /] SUBSTR BIF PICKS 3P ]/
END; /] THE ITH GRAPHIC CHAR ]/
L=L+I+1; /] IN DISTRICT ]/
SUBSTR(ADDRWK,L,5)=CITY;
DO I=1 TO 5;
IF SUBSTR(CITY,I,1)= < >
THEN LEAVE;
END;
L=L+I;
SUBSTR(ADDRWK,L,8)=OTHER;
PUT FILE(OUTFILE) SKIP /] THIS DATA SET ]/
EDIT(EMPNO,IN.LAST,FIRST,ADDRWK) /] REQUIRES UTILITY ]/
(A(8),G(7),G(7),X(4),G(2K)); /] TO PRINT GRAPHIC ]/
/] DATA ]/
END; /] END OF NON-ITERATIVE DO ]/
READ FILE(INFILE) INTO (IN);
END; /] END OF DO WHILE(¬EOF) ]/
END XAMPLE1;
/]
//GO.OUTFILE DD SYSOUT=A,DCB=(RECFM=VB,LRECL=121,BLKSIZE=129)
//GO.INFILE DD ]
ABCDEF< >3KKK99< 3 3 3 3 3 3 3 >
ABCD < >3KKK11< 3 3 3 3 >
/]
Figure 25. Writing graphic data to a stream file

Accessing a data set with stream I/O
A data set accessed using stream-oriented data transmission need not have been
created by stream-oriented data transmission, but it must have CONSECUTIVE
organization, and all the data in it must be in character or graphic form. You can
open the associated file for input, and read the records the data set contains; or
you can open the file for output, and extend the data set by adding records at the
end.
To access a data set, you must use one of the following to identify it:
ENVIRONMENT attribute
DD_DDNAME environment variable
TITLE option of the OPEN statement
The following paragraphs describe the essential information you must include in the
DD statement, and discuss some of the optional information you can supply. The
discussions do not apply to data sets in the input stream.
When your application accesses an existing STREAM file, PL/I must obtain a
record-length value for that file. The value can come from one of the following
sources:
The LINESIZE option of the OPEN statement
The RECSIZE option of the ENVIRONMENT attribute
The RECSIZE option of the DD_DDNAME environment variable
The RECSIZE option of the TITLE option of the OPEN statement
PL/I-supplied default value
If you are using an existing OUTPUT file, or if you supply a RECSIZE value, PL/I
determines the record-length value as described in “Creating a data set with stream
I/O” on page 165.
PL/I uses a default record-length value for an INPUT file when:

The file is SYSIN, value = 80
The file is associated with the terminal (stdout: or stderr:), value = 120
Record format
When using stream-oriented data transmission to access a data set, you do not
need to know the record format of the data set (except when you must specify a
block size); each GET statement transfers a discrete number of characters or
graphics to your program from the data stream.
If you do give record-format information, it must be compatible with the actual

structure of the data set. For example, if a data set is created with F-format
records, a record size of 600 bytes, and a block size of 3600 bytes, you can access
the records as if they are U-format with a maximum block size of 3600 bytes; but if
you specify a block size of 3500 bytes, your data will be truncated.

Example
The program in Figure 26 reads the data set created by the program in Figure 24
on page 166 and uses the file SYSPRINT to list the data it contains. (For details
on SYSPRINT, see “Using SYSIN and SYSPRINT files” on page 173.) Each set of
data is read, by the GET statement, into two variables: FREC, which always
contains 45 characters; and VREC, which always contains 35 characters. At each
execution of the GET statement, VREC consists of the number of characters
generated by the expression 7*NUM, together with sufficient blanks to bring the
total number of characters to 35. The DISP parameter of the DD statement could
read simply DISP=OLD; if DELETE is omitted, an existing data set will not be
deleted.
//EX7#5 JOB
//PLI.SYSIN DD ]
PEOPLE: PROC OPTIONS(MAIN);
DCL WORK FILE STREAM INPUT,
1 REC,
2 FREC,
3 NAME CHAR(19),
3 NUM CHAR(1),
3 SERNO CHAR(7),
3 PROF CHAR(18),
2 VREC CHAR(35),
IN CHAR(8K) DEF REC,
ON ENDFILE(WORK) EOF='1'B;
OPEN FILE(WORK);
GET FILE(WORK) EDIT(IN,VREC)(A(45),A(7]NUM));
DO WHILE (¬EOF);
PUT FILE(SYSPRINT) SKIP EDIT(IN)(A);
GET FILE(WORK) EDIT(IN,VREC)(A(45),A(7]NUM));
END;
CLOSE FILE(WORK);
END PEOPLE;
/]
//GO.WORK DD DSN=HPU8.PEOPLE,DISP=(OLD,DELETE)
Figure 26. Accessing a data set with stream-oriented data transmission
Using PRINT files with stream I/O

Both the operating system and the PL/I language include features that facilitate the
formatting of printed output. The operating system allows you to use the first byte
of each record for a print control character. The control characters, which are not
printed, cause the printer to skip to a new line or page. (Tables of print control
characters are given in Figure 29 on page 180 and Figure 30 on page 180.)
In a PL/I program, the use of a PRINT file provides a convenient means of

controlling the layout of printed output from stream-oriented data transmission. The
compiler automatically inserts print control characters in response to the PAGE,
SKIP, and LINE options and format items.
You can apply the PRINT attribute to any STREAM OUTPUT file, even if you do
not intend to print the associated data set directly. When a PRINT file is
associated with a direct-access data set, the print control characters have no effect
on the layout of the data set, but appear as part of the data in the records.

The compiler reserves the first byte of each record transmitted by a PRINT file for
an American National Standard print control character, and inserts the appropriate
characters automatically.
A PRINT file uses only the following five print control characters:
Character Action
Space 1 line before printing (blank character)
0 Space 2 lines before printing
− Space 3 lines before printing
+ No space before printing
1 Start new page
The compiler handles the PAGE, SKIP, and LINE options or format items by
padding the remainder of the current record with blanks and inserting the
appropriate control character in the next record. If SKIP or LINE specifies more
than a 3-line space, the compiler inserts sufficient blank records with appropriate
control characters to accomplish the required spacing. In the absence of a print
control option or format item, when a record is full the compiler inserts a blank
character (single line space) in the first byte of the next record.
If a PRINT file is being transmitted to a terminal, the PAGE, SKIP, and LINE
options will never cause more than 3 lines to be skipped, unless formatted output is
specified.
Controlling printed line length

You can limit the length of the printed line produced by a PRINT file either by
specifying a record length in your PL/I program (ENVIRONMENT attribute) or in a
DD statement, or by giving a line size in an OPEN statement (LINESIZE option).
The record length must include the extra byte for the print control character, that is,
it must be 1 byte larger than the length of the printed line (5 bytes larger for
V-format records). The value you specify in the LINESIZE option refers to the
number of characters in the printed line; the compiler adds the print control
character.
The blocking of records has no effect on the appearance of the output produced by
a PRINT file, but it does result in more efficient use of auxiliary storage when the
file is associated with a data set on a direct-access device. If you use the
LINESIZE option, ensure that your line size is compatible with your block size. For
F-format records, block size must be an exact multiple of (line size+1); for V-format
records, block size must be at least 9 bytes greater than line size.
Although you can vary the line size for a PRINT file during execution by closing the
file and opening it again with a new line size, you must do so with caution if you
are using the PRINT file to create a data set on a direct-access device. You
cannot change the record format that is established for the data set when the file is
first opened. If the line size you specify in an OPEN statement conflicts with the
record format already established, the UNDEFINEDFILE condition is raised. To
prevent this, either specify V-format records with a block size at least 9 bytes
greater than the maximum line size you intend to use, or ensure that the first OPEN
statement specifies the maximum line size. (Output destined for the printer can be
stored temporarily on a direct-access device, unless you specify a printer by using
UNIT=, even if you intend it to be fed directly to the printer.)

Since PRINT files have a default line size of 120 characters, you need not give any
record format information for them. In the absence of other information, the
compiler assumes V-format records. The complete default information is:
BLKSIZE=129
LRECL=125
RECFM=VBA.
Example: Figure 27 on page 172 illustrates the use of a PRINT file and the
printing options of stream-oriented data transmission statements to format a table
and write it onto a direct-access device for printing on a later occasion. The table
comprises the natural sines of the angles from 0° to 359° 54' in steps of 6'.
The statements in the ENDPAGE ON-unit insert a page number at the bottom of
each page, and set up the headings for the following page.
The DD statement defining the data set created by this program includes no
record-format information. The compiler infers the following from the file declaration
and the line size specified in the statement that opens the file TABLE:
Record format = V
(the default for a PRINT file).
Record size = 98
(line size + 1 byte for print control character + 4 bytes for
record control field).
Block size = 102
(record length + 4 bytes for block control field).
The program in Figure 32 on page 185 uses record-oriented data transmission to

print the table created by the program in Figure 27 on page 172.

%PROCESS LIST;
SINE: PROC OPTIONS(MAIN);

DCL TABLE FILE STREAM OUTPUT PRINT;
DCL DEG FIXED DEC(5,1) INIT(K); /] INIT(K) FOR ENDPAGE ]/
DCL MIN FIXED DEC(3,1);
DCL PGNO FIXED DEC(2) INIT(K);
DCL ONCODE BUILTIN;
ON ERROR
BEGIN;
ON ERROR SYSTEM;
DISPLAY ('ONCODE = '|| ONCODE);
END;
ON ENDPAGE(TABLE)
BEGIN;
DCL I;
IF PGNO ¬= K THEN
PUT FILE(TABLE) EDIT ('PAGE',PGNO)
(LINE(55),COL(8K),A,F(3));
IF DEG ¬= 36K THEN
DO;
PUT FILE(TABLE) PAGE EDIT ('NATURAL SINES') (A);
IF PGNO ¬= K THEN
PUT FILE(TABLE) EDIT ((I DO I = K TO 54 BY 6))
(SKIP(3),1K F(9));
PGNO = PGNO + 1;
END;
ELSE
PUT FILE(TABLE) PAGE;
END;
OPEN FILE(TABLE) PAGESIZE(52) LINESIZE(93);

SIGNAL ENDPAGE(TABLE);
PUT FILE(TABLE) EDIT

((DEG,(SIND(DEG+MIN) DO MIN = K TO .9 BY .1) DO DEG = K TO 359))
(SKIP(2), 5 (COL(1), F(3), 1K F(9,4) ));
PUT FILE(TABLE) SKIP(52);
END SINE;
Figure 27. Creating a print file via stream data transmission. The example in Figure 32 on
page 185 will print the resultant file.
Overriding the tab control table

Data-directed and list-directed output to a PRINT file are aligned on preset tabulator
positions. See Figure 14 on page 111 and Figure 28 on page 173 for examples
of declaring a tab table. The definitions of the fields in the table are as follows:
OFFSET OF TAB COUNT:
Halfword binary integer that gives the offset of “Tab count,” the field
that indicates the number of tabs to be used.
PAGESIZE:
Halfword binary integer that defines the default page size. This page
size is used for dump output to the PLIDUMP data set as well as for
stream output.
LINESIZE: Halfword binary integer that defines the default line size.
PAGELENGTH:
Halfword binary integer that defines the default page length for printing
at a terminal.

FILLERS: Three halfword binary integers; reserved for future use.
TAB COUNT:
Halfword binary integer that defines the number of tab position entries
in the table (maximum 255). If tab count = 0, any specified tab
positions are ignored.
Tab1–Tabn:
n halfword binary integers that define the tab positions within the print
line. The first position is numbered 1, and the highest position is
numbered 255. The value of each tab should be greater than that of
the tab preceding it in the table; otherwise, it is ignored. The first data
field in the printed output begins at the next available tab position.
You can override the default PL/I tab settings for your program by causing the
linkage editor to resolve an external reference to PLITABS. To cause the reference
to be resolved, supply a table with the name PLITABS, in the format described
above.
To supply this tab table, include a PL/I structure in your source program with the
name PLITABS, which you must declare to be STATIC EXTERNAL in your MAIN
proc. An example of the PL/I structure is shown in Figure 28. This example
creates three tab settings, in positions 30, 60, and 90, and uses the defaults for
page size and line size. Note that TAB1 identifies the position of the second item
printed on a line; the first item on a line always starts at the left margin. The first
item in the structure is the offset to the NO_OF_TABS field; FILL1, FILL2, and
FILL3 can be omitted by adjusting the offset value by –6.
DCL 1 PLITABS STATIC EXT,

2 (OFFSET INIT(14),
PAGESIZE INIT(6K),
LINESIZE INIT(12K),
PAGELENGTH INIT(K),
FILL1 INIT(K),
FILL2 INIT(K),
FILL3 INIT(K),
NO_OF_TABS INIT(3),
TAB1 INIT(3K),
TAB2 INIT(6K),
TAB3 INIT(9K)) FIXED BIN(15,K);
Figure 28. PL/I structure PLITABS for modifying the preset tab settings
Using SYSIN and SYSPRINT files

If you code a GET statement without the FILE option in your program, the compiler
inserts the file name SYSIN. If you code a PUT statement without the FILE option,
the compiler inserts the name SYSPRINT.
If you do not declare SYSPRINT, the compiler gives the file the attribute PRINT in
addition to the normal default attributes; the complete set of attributes will be:
FILE STREAM OUTPUT PRINT EXTERNAL
Since SYSPRINT is a PRINT file, the compiler also supplies a default line size of
120 characters and a V-format record. You need give only a minimum of
information in the corresponding DD statement; if your installation uses the usual

convention that the system output device of class A is a printer, the following is
sufficient:
Note: SYSIN and SYSPRINT are established in the User Exit during initialization.
IBM-supplied defaults for SYSIN and SYSPRINT are directed to the
terminal.
You can override the attributes given to SYSPRINT by the compiler by explicitly
declaring or opening the file. For more information about the interaction between
SYSPRINT and the Language Environment for OS/390 & VM message file option,
see the OS/390 Language Environment Programming Guide.
The compiler does not supply any special attributes for the input file SYSIN; if you
do not declare it, it receives only the default attributes. The data set associated
with SYSIN is usually in the input stream; if it is not in the input stream, you must
supply full DD information.
For more information about SYSPRINT, see “SYSPRINT considerations” on

page 113.
Controlling input from the terminal

You can enter data at the terminal for an input file in your PL/I program if you do
the following:
1. Declare the input file explicitly or implicitly with the CONSECUTIVE
environment option (all stream files meet this condition)
2. Allocate the input file to the terminal.
You can usually use the standard default input file SYSIN because it is a stream
file and can be allocated to the terminal.
You are prompted for input to stream files by a colon (:). You will see the colon
each time a GET statement is executed in the program. The GET statement
causes the system to go to the next line. You can then enter the required data. If
you enter a line that does not contain enough data to complete execution of the
GET statement, a further prompt, which is a plus sign followed by a colon (+:), is
displayed.
By adding a hyphen to the end of any line that is to continue, you can delay
transmission of the data to your program until you enter two or more lines.
If you include output statements that prompt you for input in your program, you can
inhibit the initial system prompt by ending your own prompt with a colon. For
example, the GET statement could be preceded by a PUT statement such as:
PUT SKIP LIST('ENTER NEXT ITEM:');
To inhibit the system prompt for the next GET statement, your own prompt must
meet the following conditions:
1. It must be either list-directed or edit-directed, and if list-directed, must be to a
PRINT file.
2. The file transmitting the prompt must be allocated to the terminal. If you are
merely copying the file at the terminal, the system prompt is not inhibited.

Format of data
The data you enter at the terminal should have exactly the same format as stream
input data in batch mode, except for the following variations:
Simplified punctuation for input: If you enter separate items of input on
separate lines, there is no need to enter intervening blanks or commas; the
compiler will insert a comma at the end of each line.
For instance, in response to the statement:
GET LIST(I,J,K);
your terminal interaction could be as follows:
:
1
+:2
+:3
with a carriage return following each item. It would be equivalent to:
:
1,2,3
If you wish to continue an item onto another line, you must end the first line
with a continuation character. Otherwise, for a GET LIST or GET DATA
statement, a comma will be inserted, and for a GET EDIT statement, the item
will be padded (see next paragraph).
Automatic padding for GET EDIT: There is no need to enter blanks at the end
of a line of input for a GET EDIT statement. The item you enter will be padded
to the correct length.
For instance, for the PL/I statement:
GET EDIT(NAME)(A(15));
you could enter the five characters:
SMITH
followed immediately by a carriage return. The item will be padded with 10
blanks, so that the program receives a string 15 characters long. If you wish to
continue an item on a second or subsequent line, you must add a continuation
character to the end of every line except the last; the first line transmitted would
otherwise be padded and treated as the complete data item.
SKIP option or format item: A SKIP in a GET statement asks the program to
ignore data not yet entered. All uses of SKIP(n) where n is greater than one
are taken to mean SKIP(1). SKIP(1) is taken to mean that all unused data on
the current line is ignored.
Stream and record files

You can allocate both stream and record files to the terminal. However, no
prompting is provided for record files. If you allocate more than one file to the
terminal, and one or more of them is a record file, the output of the files will not
necessarily be synchronized. The order in which data is transmitted to and from
the terminal is not guaranteed to be the same order in which the corresponding
PL/I I/O statements are executed.

Also, record file input from the terminal is received in upper case letters because of
a TCAM restriction. To avoid problems you should use stream files wherever
possible.
Capital and lowercase letters

For stream files, character strings are transmitted to the program as entered in
lowercase or uppercase. For record files, all characters become uppercase.
End-of-file
The characters /* in positions one and two of a line that contains no other
characters are treated as an end-of-file mark, that is, they raise the ENDFILE
condition.
COPY option of GET statement

The GET statement can specify the COPY option; but if the COPY file, as well as
the input file, is allocated to the terminal, no copy of the data will be printed.
Controlling output to the terminal

At your terminal you can obtain data from a PL/I file that has been both:
1. Declared explicitly or implicitly with the CONSECUTIVE environment option. All
stream files meet this condition.
2. Allocated to the terminal.
The standard print file SYSPRINT generally meets both these conditions.
Format of PRINT files

Data from SYSPRINT or other PRINT files is not normally formatted into pages at
the terminal. Three lines are always skipped for PAGE and LINE options and
format items. The ENDPAGE condition is normally never raised. SKIP(n), where n
is greater than three, causes only three lines to be skipped. SKIP(0) is
implemented by backspacing, and should therefore not be used with terminals that
do not have a backspace feature.
You can cause a PRINT file to be formatted into pages by inserting a tab control
table in your program. The table must be called PLITABS, and its contents are
explained in “Overriding the tab control table” on page 172. You must initialize the
element PAGELENGTH to the length of page you require—that is, the length of the
sheet of paper on which each page is to be printed, expressed as the maximum
number of lines that could be printed on it. You must initialize the element
PAGESIZE to the actual number of lines to be printed on each page. After the
number of lines in PAGESIZE has been printed on a page, ENDPAGE is raised, for
which standard system action is to skip the number of lines equal to
PAGELENGTH minus PAGESIZE, and then start printing the next page. For other
than standard layout, you must initialize the other elements in PLITABS to the
values shown in Figure 14 on page 111. You can also use PLITABS to alter the
tabulating positions of list-directed and data-directed output. You can use PLITABS
for SYSPRINT when you need to format page breaks in ILC applications. Set
PAGESIZE to 32767 and use the PUT PAGE statement to control page breaks.

Although some types of terminals have a tabulating facility, tabulating of
list-directed and data-directed output is always achieved by transmission of blank
characters.
Stream and record files

You can allocate both stream and record files to the terminal. However, if you
allocate more than one file to the terminal and one or more is a record file, the files'
output will not necessarily be synchronized. There is no guarantee that the order in
which data is transmitted between the program and the terminal will be the same
as the order in which the corresponding PL/I input and output statements are
executed. In addition, because of a TCAM restriction, any output to record files at
the terminal is printed in uppercase (capital) letters. It is therefore advisable to use
stream files wherever possible.
Capital and lowercase characters

For stream files, characters are displayed at the terminal as they are held in the
program, provided the terminal can display them. For instance, with an IBM 327x
terminal, capital and lowercase letters are displayed as such, without translation.
For record files, all characters are translated to uppercase. A variable or constant
in the program can contain lowercase letters if the program was created under the
EDIT command with the ASIS operand, or if the program has read lowercase
letters from the terminal.
Output from the PUT EDIT command

The format of the output from a PUT EDIT command to a terminal is line mode
TPUTs with “Start of field” and “end of field” characters appearing as blanks on the
screen.
Using record-oriented data transmission

PL/I supports various types of data sets with the RECORD attribute (see Table 17
on page 181). This section covers how to use consecutive data sets.
Table 16 lists the statements and options that you can use to create and access a
consecutive data set using record-oriented data transmission.
Table 16 (Page 1 of 2). Statements and options allowed for creating and accessing
consecutive data sets
File declaration1 Valid statements,2 with Other options you
Options you must specify can specify
SEQUENTIAL OUTPUT WRITE FILE(file-reference)
BUFFERED FROM(reference);
LOCATE based-variable SET(pointer-reference)

FILE(file-reference);
FROM(reference);

File declaration1 Valid statements,2 with Other options you
Options you must specify can specify
SEQUENTIAL INPUT READ FILE(file-reference)
BUFFERED INTO(reference);
READ FILE(file-reference)
SET(pointer-reference);
IGNORE(expression);
SEQUENTIAL INPUT READ FILE(file-reference)
INTO(reference);
IGNORE(expression);
SEQUENTIAL UPDATE READ FILE(file-reference)
IGNORE(expression);
REWRITE FILE(file-reference); FROM(reference)

SEQUENTIAL UPDATE READ FILE(file-reference)
INTO(reference);
IGNORE(expression);
REWRITE FILE(file-reference)
FROM(reference);
Notes:
1. The complete file declaration would include the attributes FILE, RECORD and ENVIRONMENT.
2. The statement READ FILE (file-reference); is a valid statement and is equivalent to READ
FILE(file-reference) IGNORE (1);
Specifying record format

If you give record-format information, it must be compatible with the actual structure
of the data set. For example, if you create a data set with FB-format records, with
a record size of 600 bytes and a block size of 3600 bytes, you can access the
records as if they are U-format with a maximum block size of 3600 bytes. If you
specify a block size of 3500 bytes, your data is truncated.
Defining files using record I/O

You define files for record-oriented data transmission by using a file declaration
with the following attributes:
DCL filename FILE RECORD
INPUT | OUTPUT | UPDATE
SEQUENTIAL
BUFFERED

Default file attributes are shown in Table 13 on page 147. The file attributes are
described in the PL/I Language Reference. Options of the ENVIRONMENT
attribute are discussed below.

The ENVIRONMENT options applicable to consecutive data sets are:
F|FB|FS|FBS|V|VB|U
BLKSIZE(block-size)
SCALARVARYING
CONSECUTIVE or ORGANIZATION(CONSECUTIVE)
DEBLOCK
CTLASA|CTL36K
The options above the blank line are described in “Specifying characteristics in the
ENVIRONMENT attribute” on page 146, and those below the blank line are
described below.
See Table 13 on page 147 to find which options you must specify, which are
optional, and which are defaults.
CONSECUTIVE
The CONSECUTIVE option defines a file with consecutive data set organization,
which is described in this chapter and in “Data set organization” on page 142.
──CONSECUTIVE──────────────────────────────────────────────────────────────────

CONSECUTIVE is the default.
ORGANIZATION(CONSECUTIVE)
Specifies that the file is associated with a consecutive data set. The
ORGANIZATION option is described in “ORGANIZATION option” on page 153.
The file can be either a native data set or a VSAM data set.
DEBLOCK
The DEBLOCK option indicates that a program will do its own deblocking of
records.
This option is valid only for record input files that are not spanned or concatenated
and is valid only under batch mode.
If DEBLOCK is not specified, the PL/I library will perform deblocking of the dataset
as necessary.
CTLASA|CTL360
The printer control options CTLASA and CTL360 apply only to OUTPUT files
associated with consecutive data sets. They specify that the first character of a
record is to be interpreted as a control character.

──┬─CTLASA─┬───────────────────────────────────────────────────────────────────

└─CTL36K─┘
The CTLASA option specifies American National Standard Vertical Carriage

Positioning Characters or American National Standard Pocket Select Characters
(Level 1). The CTL360 option specifies IBM machine-code control characters.
The American National Standard control characters, listed in Figure 29, cause the
specified action to occur before the associated record is printed or punched.
The machine code control characters differ according to the type of device. The
IBM machine code control characters for printers are listed in Figure 30.
Code Action
Space 1 line before printing (blank code)
0 Space 2 lines before printing
− Space 3 lines before printing
+ Suppress space before printing
1 Skip to channel 1
2 Skip to channel 2
3 Skip to channel 3
4 Skip to channel 4
5 Skip to channel 5
6 Skip to channel 6
7 Skip to channel 7
8 Skip to channel 8
9 Skip to channel 9
A Skip to channel 10
B Skip to channel 11
C Skip to channel 12
V Select stacker 1
W Select stacker 2
Figure 29. American National Standard print and card punch control characters (CTLASA)
Print and Act immediately

Then Act Action (no printing)
Code byte Code byte

00000001 Print only (no space) —
00001001 Space 1 line 00001011
00010001 Space 2 lines 00010011
00011001 Space 3 lines 00011011
10001001 Skip to channel 1 10001011
10010001 Skip to channel 2 10010011
10011001 Skip to channel 3 10011011
10100001 Skip to channel 4 10100011
10101001 Skip to channel 5 10101011
10110001 Skip to channel 6 10110011
10111001 Skip to channel 7 10111011
11000001 Skip to channel 8 11000011
11001001 Skip to channel 9 11001011
11010001 Skip to channel 10 11010011
11011001 Skip to channel 11 11011011
11100001 Skip to channel 12 11100011
Figure 30. IBM machine code print control characters (CTL360)

Creating a data set with record I/O
When you create a consecutive data set, you must open the associated file for
SEQUENTIAL OUTPUT. You can use either the WRITE or LOCATE statement to
write records. Table 16 on page 177 shows the statements and options for
creating a consecutive data set.
When creating a data set, you must identify it to the operating system in a DD
statement. The following paragraphs, summarized in Table 17, tell what essential
information you must include in the DD statement and discuss some of the optional
information you can supply.
Table 17. Creating a consecutive data set with record I/O: essential parameters of the DD statement
When required
Storage device What you must state Parameters
All Always Output device UNIT= or SYSOUT= or
VOLUME=REF=
Block size1 DCB=(BLKSIZE=...

Direct access only Always Storage space required SPACE=
Direct access Data set to be used by another job step but not Disposition DISP=
required at end of job
Data set to be kept after end of job Disposition DISP=
Name of data set DSNAME=
Data set to be on particular device Volume serial number VOLUME=SER= or

VOLUME=REF=
1Or you could specify the block size in your PL/I program by using the ENVIRONMENT attribute.
When you create a consecutive data set you must specify:
The name of data set to be associated with your PL/I file. A data set with
consecutive organization can exist on any type of device.
The record length. You can specify the record length using the RECSIZE
option of the ENVIRONMENT attribute, of the DD_DDNAME environment
variable, or of the TITLE option of the OPEN statement.
For files associated with the terminal device (stdout: or stderr:), PL/I uses a
default record length of 120 when the RECSIZE option is not specified.
Accessing and updating a data set with record I/O

Once you create a consecutive data set, you can open the file that accesses it for
sequential input, for sequential output, or, for data sets on direct-access devices,
for updating. See Figure 31 on page 183 for an example of a program that
accesses and updates a consecutive data set. If you open the file for output, and
extend the data set by adding records at the end, you must specify DISP=MOD in
the DD statement. If you do not, the data set will be overwritten. If you open a file
for updating, you can update only records in their existing sequence, and if you
want to insert records, you must create a new data set. Table 16 on page 177
shows the statements and options for accessing and updating a consecutive data
set.

When you access a consecutive data set by a SEQUENTIAL UPDATE file, you
must retrieve a record with a READ statement before you can update it with a
REWRITE statement; however, every record that is retrieved need not be rewritten.
A REWRITE statement will always update the last record read.
Consider the following:

READ FILE(F) INTO(A);
.
.
.
READ FILE(F) INTO(B);
.
.
.
REWRITE FILE(F) FROM(A);
The REWRITE statement updates the record that was read by the second READ
statement. The record that was read by the first statement cannot be rewritten
after the second READ statement has been executed.
To access a data set, you must identify it to the operating system in a DD

statement. Table 18 summarizes the DD statement parameters needed to access
a consecutive data set.
Table 18. Accessing a consecutive data set with record I/O: essential parameters of the DD
statement
Parameters What you must state When required
DSNAME= Name of data set Always
DISP= Disposition of data set

UNIT= or Input device If data set not cataloged (all devices)
VOLUME=REF=
VOLUME=SER= Volume serial number If data set not cataloged (direct access)
DCB=(BLKSIZE= Block size1 If data set does not have standard labels
1Or you could specify the block size in your PL/I program by using the ENVIRONMENT attribute.
The following paragraphs indicate the essential information you must include in the
DD statement, and discuss some of the optional information you can supply. The
discussions do not apply to data sets in the input stream.
If the data set is cataloged, you need to supply only the following information in the
DD statement:
The name of the data set (DSNAME parameter). The operating system will
locate the information describing the data set in the system catalog, and, if
necessary, will request the operator to mount the volume containing it.
Confirmation that the data set exists (DISP parameter). If you open the data
set for output with the intention of extending it by adding records at the end,
code DISP=MOD; otherwise, opening the data set for output will result in it
being overwritten.

If the data set is not cataloged, you must additionally specify the device that will
read the data set and, direct-access devices, give the serial number of the volume
that contains the data set (UNIT and VOLUME parameters).
Example of consecutive data sets

Creating and accessing consecutive data sets are illustrated in the program in
Figure 31. The program merges the contents of two data sets, in the input stream,
and writes them onto a new data set, &&TEMP; each of the original data sets
contains 15-byte fixed-length records arranged in EBCDIC collating sequence. The
two input files, INPUT1 and INPUT2, have the default attribute BUFFERED, and
locate mode is used to read records from the associated data sets into the
respective buffers. Access of based variables in the buffers should not be
attempted after the file has been closed.
//EXAMPLE JOB
//PLI.SYSIN DD ]
%PROCESS LIST;
MERGE: PROC OPTIONS(MAIN);

DCL (INPUT1, /] FIRST INPUT FILE ]/
INPUT2, /] SECOND INPUT FILE ]/
OUT ) FILE RECORD SEQUENTIAL; /] RESULTING MERGED FILE]/
DCL SYSPRINT FILE PRINT; /] NORMAL PRINT FILE ]/
DCL INPUT1_EOF BIT(1) INIT('K'B); /] EOF FLAG FOR INPUT1 ]/

DCL INPUT2_EOF BIT(1) INIT('K'B); /] EOF FLAG FOR INPUT2 ]/
DCL OUT_EOF BIT(1) INIT('K'B); /] EOF FLAG FOR OUT ]/
DCL TRUE BIT(1) INIT('1'B); /] CONSTANT TRUE ]/
DCL FALSE BIT(1) INIT('K'B); /] CONSTANT FALSE ]/
DCL ITEM1 CHAR(15) BASED(A); /] ITEM FROM INPUT1 ]/

DCL ITEM2 CHAR(15) BASED(B); /] ITEM FROM INPUT2 ]/
DCL INPUT_LINE CHAR(15); /] INPUT FOR READ INTO ]/
DCL A POINTER; /] POINTER VAR ]/
DCL B POINTER; /] POINTER VAR ]/
ON ENDFILE(INPUT1) INPUT1_EOF = TRUE;

ON ENDFILE(INPUT2) INPUT2_EOF = TRUE;
ON ENDFILE(OUT) OUT_EOF = TRUE;
OPEN FILE(INPUT1) INPUT,

FILE(INPUT2) INPUT,
FILE(OUT) OUTPUT;
READ FILE(INPUT1) SET(A); /] PRIMING READ ]/

READ FILE(INPUT2) SET(B);
DO WHILE ((INPUT1_EOF = FALSE) & (INPUT2_EOF = FALSE));

IF ITEM1 > ITEM2 THEN
DO;
WRITE FILE(OUT) FROM(ITEM2);
PUT FILE(SYSPRINT) SKIP EDIT('1>2', ITEM1, ITEM2)
(A(5),A,A);
END;
ELSE
DO;
PUT FILE(SYSPRINT) SKIP EDIT('1<2', ITEM1, ITEM2)
(A(5),A,A);
READ FILE(INPUT1) SET(A);
END;
END;
Figure 31 (Part 1 of 2). Merge Sort—creating and accessing a consecutive data set

DO WHILE (INPUT1_EOF = FALSE); /] INPUT2 IS EXHAUSTED ]/
PUT FILE(SYSPRINT) SKIP EDIT('1', ITEM1) (A(2),A);
READ FILE(INPUT1) SET(A);
END;
DO WHILE (INPUT2_EOF = FALSE); /] INPUT1 IS EXHAUSTED ]/

PUT FILE(SYSPRINT) SKIP EDIT('2', ITEM2) (A(2),A);
END;
CLOSE FILE(INPUT1), FILE(INPUT2), FILE(OUT);

PUT FILE(SYSPRINT) PAGE;
OPEN FILE(OUT) SEQUENTIAL INPUT;
READ FILE(OUT) INTO(INPUT_LINE); /] DISPLAY OUT FILE ]/

DO WHILE (OUT_EOF = FALSE);
PUT FILE(SYSPRINT) SKIP EDIT(INPUT_LINE) (A);
READ FILE(OUT) INTO(INPUT_LINE);
END;
CLOSE FILE(OUT);
END MERGE;
/]
//GO.INPUT1 DD ]
AAAAAA
CCCCCC
EEEEEE
GGGGGG
IIIIII
/]
//GO.INPUT2 DD ]
BBBBBB
DDDDDD
FFFFFF
HHHHHH
JJJJJJ
KKKKKK
/]
//GO.OUT DD DSN=&&TEMP,DISP=(NEW,DELETE),UNIT=SYSDA,
// DCB=(RECFM=FB,BLKSIZE=15K,LRECL=15),SPACE=(TRK,(1,1))
Figure 31 (Part 2 of 2). Merge Sort—creating and accessing a consecutive data set
The program in Figure 32 on page 185 uses record-oriented data transmission to

print the table created by the program in Figure 27 on page 172.

%PROCESS LIST;
PRT: PROC OPTIONS(MAIN);

DCL TABLE FILE RECORD INPUT SEQUENTIAL;
DCL PRINTER FILE RECORD OUTPUT SEQL
ENV(V BLKSIZE(1K2) CTLASA);
DCL LINE CHAR(94) VAR;
DCL TABLE_EOF BIT(1) INIT('K'B); /] EOF FLAG FOR TABLE ]/

DCL TRUE BIT(1) INIT('1'B); /] CONSTANT TRUE ]/
DCL FALSE BIT(1) INIT('K'B); /] CONSTANT FALSE ]/
ON ENDFILE(TABLE) TABLE_EOF = TRUE;
OPEN FILE(TABLE),
FILE(PRINTER);
READ FILE(TABLE) INTO(LINE); /] PRIMING READ ]/
DO WHILE (TABLE_EOF = FALSE);

WRITE FILE(PRINTER) FROM(LINE);
READ FILE(TABLE) INTO(LINE);
END;
CLOSE FILE(TABLE),
FILE(PRINTER);
END PRT;
Figure 32. Printing record-oriented data transmission

Chapter 9. Defining and using regional data sets
This chapter covers regional data set organization, data transmission statements,
and ENVIRONMENT options that define regional data sets. How to create and
access regional data sets for each type of regional organization is then discussed.
A data set with regional organization is divided into regions, each of which is
identified by a region number, and each of which can contain one record or more
than one record, depending on the type of regional organization. The regions are
numbered in succession, beginning with zero, and a record can be accessed by
specifying its region number, and perhaps a key, in a data transmission statement.
Regional data sets are confined to direct-access devices.
Regional organization of a data set allows you to control the physical placement of
records in the data set, and to optimize the access time for a particular application.
Such optimization is not available with consecutive or indexed organization, in
which successive records are written either in strict physical sequence or in logical
sequence depending on ascending key values; neither of these methods takes full
advantage of the characteristics of direct-access storage devices.
You can create a regional data set in a manner similar to a consecutive or indexed
data set, presenting records in the order of ascending region numbers; alternatively,
you can use direct-access, in which you present records in random sequence and
insert them directly into preformatted regions. Once you create a regional data set,
you can access it by using a file with the attributes SEQUENTIAL or DIRECT as
well as INPUT or UPDATE. You do not need to specify either a region number or
a key if the data set is associated with a SEQUENTIAL INPUT or SEQUENTIAL
UPDATE file. When the file has the DIRECT attribute, you can retrieve, add,
delete, and replace records at random.
Records within a regional data set are either actual records containing valid data or
dummy records.
The major advantage of regional organization over other types of data set
organization is that it allows you to control the relative placement of records; by
judicious programming, you can optimize record access in terms of device
capabilities and the requirements of particular applications.
Direct access of regional data sets is quicker than that of indexed data sets, but
regional data sets have the disadvantage that sequential processing can present
records in random sequence; the order of sequential retrieval is not necessarily that
in which the records were presented, nor need it be related to the relative key
values.
Table 19 on page 187 lists the data transmission statements and options that you
can use to create and access a regional data set.

regional data sets
File Valid statements,2 with Other options you
declaration1 options you must include can also include
BUFFERED FROM(reference)
KEYFROM(expression);

FROM(file-reference)
FROM(reference)
SEQUENTIAL INPUT READ FILE(file-reference) KEYTO(reference)
READ FILE(file-reference) KEYTO(reference)

IGNORE(expression);
SEQUENTIAL INPUT READ FILE(file-reference) KEYTO(reference)
INTO(reference);
IGNORE(expression);
SEQUENTIAL UPDATE3 READ FILE(file-reference) KEYTO(reference)
READ FILE(file-reference) KEYTO(reference)

IGNORE(expression);

SEQUENTIAL UPDATE READ FILE(file-reference) KEYTO(reference)
INTO(reference);
IGNORE(expression);
FROM(reference);
DIRECT OUTPUT WRITE FILE(file-reference)
FROM(reference)
DIRECT INPUT READ FILE(file-reference)
INTO(reference)
KEY(expression);
Chapter 9. Defining and using regional data sets 187

regional data sets
File Valid statements,2 with Other options you
declaration1 options you must include can also include
DIRECT UPDATE READ FILE(file-reference)
INTO(reference)
KEY(expression);
FROM(reference)
KEY(expression);
WRITE FILE(file-reference)
FROM(reference)
DELETE FILE(file-reference)
KEY(expression);
INTO(reference)
KEY(expression);
FROM(reference)
KEY(expression);
FROM(reference)
KEY(expression);
UNLOCK FILE(file-reference)
KEY(expression);
Notes:
1. The complete file declaration would include the attributes FILE, RECORD, and ENVIRONMENT; if
you use any of the options KEY, KEYFROM, or KEYTO, you must also include the attribute KEYED.
2. The statement READ FILE(file-reference); is equivalent to the statement READ FILE(file-reference)
IGNORE(1);
3. The file must not have the UPDATE attribute when creating new data sets.
Defining files for a regional data set

Use a file declaration with the following attributes to define a sequential regional
data set:
SEQUENTIAL
BUFFERED
[KEYED]
To define a direct regional data set, use a file declaration with the following
attributes:

DIRECT
Default file attributes are shown in Table 13 on page 147. The file attributes are

The ENVIRONMENT options applicable to regional data sets are:
REGIONAL({1})
F|V|VS|U
BLKSIZE(block-size)
SCALARVARYING
KEYLENGTH(n)
REGIONAL option
Use the REGIONAL option to define a file with regional organization.
──REGIONAL──(──1──)────────────────────────────────────────────────────────────

1 specifies REGIONAL(1)
REGIONAL(1)
specifies that the data set contains F-format records that do not have recorded
keys. Each region in the data set contains only one record; therefore, each
region number corresponds to a relative record within the data set (that is,
region numbers start with 0 at the beginning of the data set).
Although REGIONAL(1) data sets have no recorded keys, you can use
REGIONAL(1) DIRECT INPUT or UPDATE files to process data sets that do
have recorded keys.
REGIONAL(1) organization is most suited to applications where there are no

duplicate region numbers, and where most of the regions will be filled (reducing
wasted space in the data set).
Using keys with REGIONAL data sets

There are two kinds of keys, recorded keys and source keys. A recorded key is a
character string that immediately precedes each record in the data set to identify
that record; its length cannot exceed 255 characters. A source key is the character
value of the expression that appears in the KEY or KEYFROM option of a data
transmission statement to identify the record to which the statement refers. When
you access a record in a regional data set, the source key gives a region number,
and can also give a recorded key.
You specify the length of the recorded keys in a regional data set with the
KEYLENGTH option of the ENVIRONMENT attribute, or the KEYLEN subparameter
on the DD statement. Unlike the keys for indexed data sets, recorded keys in a
regional data set are never embedded within the record.

Using REGIONAL(1) data sets
In a REGIONAL(1) data set, since there are no recorded keys, the region number
serves as the sole identification of a particular record. The character value of the
source key should represent an unsigned decimal integer that should not exceed
16777215 (although the actual number of records allowed can be smaller,
depending on a combination of record size, device capacity, and limits of your
access method. For direct regional(1) files with fixed format records, the maximum
number of tracks which can be addressed by relative track addressing is 65,536.)
If the region number exceeds this figure, it is treated as modulo 16777216; for
instance, 16777226 is treated as 10. Only the characters 0 through 9 and the
blank character are valid in the source key; leading blanks are interpreted as zeros.
Embedded blanks are not allowed in the number; the first embedded blank, if any,
terminates the region number. If more than 8 characters appear in the source key,
only the rightmost 8 are used as the region number; if there are fewer than 8
characters, blanks (interpreted as zeros) are inserted on the left.
Dummy Records
Records in a REGIONAL(1) data set are either actual records containing valid data
or dummy records. A dummy record in a REGIONAL(1) data set is identified by
the constant (8)'1'B in its first byte. Although such dummy records are inserted in
the data set either when it is created or when a record is deleted, they are not
ignored when the data set is read; your PL/I program must be prepared to
recognize them. You can replace dummy records with valid data. Note that if you
insert (8)'1'B in the first byte, the record can be lost if you copy the file onto a data
set that has dummy records that are not retrieved.
Creating a REGIONAL(1) data set

You can create a REGIONAL(1) data set either sequentially or by direct-access.
Table 19 on page 187 shows the statements and options for creating a regional
data set.
When you use a SEQUENTIAL OUTPUT file to create the data set, the opening of
the file causes all tracks on the data set to be cleared, and a capacity record to be
written at the beginning of each track to record the amount of space available on
that track. You must present records in ascending order of region numbers; any
region you omit from the sequence is filled with a dummy record. If there is an
error in the sequence, or if you present a duplicate key, the KEY condition is
raised. When the file is closed, any space remaining at the end of the current
extent is filled with dummy records.
If you create a data set using a buffered file, and the last WRITE or LOCATE
statement before the file is closed attempts to transmit a record beyond the limits of
the data set, the CLOSE statement might raise the ERROR condition.
If you use a DIRECT OUTPUT file to create the data set, the whole primary extent
allocated to the data set is filled with dummy records when the file is opened. You
can present records in random order; if you present a duplicate, the existing record
will be overwritten.
For sequential creation, the data set can have up to 15 extents, which can be on
more than one volume. For direct creation, the data set can have only one extent,
and can therefore reside on only one volume.

Example
Creating a REGIONAL(1) data set is illustrated in Figure 33. The data set is a list
of telephone numbers with the names of the subscribers to whom they are
allocated. The telephone numbers correspond with the region numbers in the data
set, the data in each occupied region being a subscriber's name.
//EX9 JOB
//STEP1 EXEC IBMZCBG,PARM.PLI='NOP,MAR(1,72)',PARM.BIND='LIST'
//PLI.SYSIN DD ]
CRR1: PROC OPTIONS(MAIN);
/] CREATING A REGIONAL(1) DATA SET - PHONE DIRECTORY ]/
DCL NOS FILE RECORD OUTPUT DIRECT KEYED ENV(REGIONAL(1));

DCL SYSIN FILE INPUT RECORD;
DCL SYSIN_REC BIT(1) INIT('1'B);
DCL 1 CARD,
2 NAME CHAR(2K),
2 NUMBER CHAR( 2),
2 CARD_1 CHAR(58);
DCL IOFIELD CHAR(2K);
ON ENDFILE (SYSIN) SYSIN_REC = 'K'B;

OPEN FILE(NOS);
READ FILE(SYSIN) INTO(CARD);
DO WHILE(SYSIN_REC);
IOFIELD = NAME;
WRITE FILE(NOS) FROM(IOFIELD) KEYFROM(NUMBER);
PUT FILE(SYSPRINT) SKIP EDIT (CARD) (A);
END;
CLOSE FILE(NOS);
END CRR1;
/]
//GO.SYSLMOD DD DSN=&&GOSET,DISP=(OLD,DELETE)
//GO.NOS DD DSN=NOS,UNIT=SYSDA,SPACE=(2K,1KK),
// DCB=(RECFM=F,BLKSIZE=2K,DSORG=DA),DISP=(NEW,KEEP)
//GO.SYSIN DD ]
ACTION,G. 12
BAKER,R. 13
BRAMLEY,O.H. 28
CHEESNAME,L. 11
CORY,G. 36
ELLIOTT,D. 85
FIGGINS,E.S. 43
HARVEY,C.D.W. 25
HASTINGS,G.M. 31
KENDALL,J.G. 24
LANCASTER,W.R. 64
MILES,R. 23
NEWMAN,M.W. 4K
PITT,W.H. 55
ROLF,D.E. 14
SHEERS,C.D. 21
SURCLIFFE,M. 42
TAYLOR,G.C. 47
WILTON,L.W. 44
WINSTONE,E.M. 37
/]
Figure 33. Creating a REGIONAL(1) data set

Accessing and updating a REGIONAL(1) data set
Once you create a REGIONAL(1) data set, you can open the file that accesses it
for SEQUENTIAL INPUT or UPDATE, or for DIRECT INPUT or UPDATE. You can
open it for OUTPUT only if the existing data set is to be overwritten. Table 19 on
page 187 shows the statements and options for accessing a regional data set.
Sequential access
To open a SEQUENTIAL file that is used to process a REGIONAL(1) data set, use
either the INPUT or UPDATE attribute. You must not include the KEY option in
data transmission statements, but the file can have the KEYED attribute, since you
can use the KEYTO option. If the target character string referenced in the KEYTO
option has more than 8 characters, the value returned (the 8-character region
number) is padded on the left with blanks. If the target string has fewer than 8
characters, the value returned is truncated on the left.
Sequential access is in the order of ascending region numbers. All records are
retrieved, whether dummy or actual, and you must ensure that your PL/I program
recognizes dummy records.
Using sequential input with a REGIONAL(1) data set, you can read all the records
in ascending region-number sequence, and in sequential update you can read and
rewrite each record in turn.
The rules governing the relationship between READ and REWRITE statements for
a SEQUENTIAL UPDATE file that accesses a REGIONAL(1) data set are identical
to those for a consecutive data set. Consecutive data sets are discussed in detail
in Chapter 8, “Defining and using consecutive data sets” on page 162.
Direct access
To open a DIRECT file that is used to process a REGIONAL(1) data set you can
use either the INPUT or the UPDATE attribute. All data transmission statements
must include source keys; the DIRECT attribute implies the KEYED attribute.
Use DIRECT UPDATE files to retrieve, add, delete, or replace records in a

REGIONAL(1) data set according to the following conventions:
Retrieval All records, whether dummy or actual, are retrieved. Your program
must recognize dummy records.
Addition A WRITE statement substitutes a new record for the existing
record (actual or dummy) in the region specified by the source key.
Deletion The record you specify by the source key in a DELETE statement
is converted to a dummy record.
Replacement The record you specify by the source key in a REWRITE
statement, whether dummy or actual, is replaced.
Example
Updating a REGIONAL(1) data set is illustrated in Figure 34 on page 194. This
program updates the data set and lists its contents. Before each new or updated
record is written, the existing record in the region is tested to ensure that it is a
dummy; this is necessary because a WRITE statement can overwrite an existing
record in a REGIONAL(1) data set even if it is not a dummy. Similarly, during the

sequential reading and printing of the contents of the data set, each record is
tested and dummy records are not printed.

//EX1K JOB
//STEP2 EXEC IBMZCBG,PARM.PLI='NOP,MAR(1,72)',PARM.BIND='LIST'
//PLI.SYSIN DD ]
ACR1: PROC OPTIONS(MAIN);
/] UPDATING A REGIONAL(1) DATA SET - PHONE DIRECTORY ]/
DCL NOS FILE RECORD KEYED ENV(REGIONAL(1));
DCL SYSIN FILE INPUT RECORD;
DCL (SYSIN_REC,NOS_REC) BIT(1) INIT('1'B);
DCL 1 CARD,
2 NAME CHAR(2K),
2 (NEWNO,OLDNO) CHAR( 2),
2 CARD_1 CHAR( 1),
2 CODE CHAR( 1),
2 CARD_2 CHAR(54);
DCL IOFIELD CHAR(2K);
DCL BYTE CHAR(1) DEF IOFIELD;
ON ENDFILE(SYSIN) SYSIN_REC = 'K'B;

OPEN FILE (NOS) DIRECT UPDATE;
DO WHILE(SYSIN_REC);
SELECT(CODE);
WHEN('A','C') DO;
IF CODE = 'C' THEN
DELETE FILE(NOS) KEY(OLDNO);
READ FILE(NOS) KEY(NEWNO) INTO(IOFIELD);
IF UNSPEC(BYTE) = (8)'1'B
THEN WRITE FILE(NOS) KEYFROM(NEWNO) FROM(NAME);
ELSE PUT FILE(SYSPRINT) SKIP LIST ('DUPLICATE:',NAME);
END;
WHEN('D') DELETE FILE(NOS) KEY(OLDNO);
OTHERWISE PUT FILE(SYSPRINT) SKIP LIST ('INVALID CODE:',NAME);
END;
END;
CLOSE FILE(SYSIN),FILE(NOS);
OPEN FILE(NOS) SEQUENTIAL INPUT;
ON ENDFILE(NOS) NOS_REC = 'K'B;
READ FILE(NOS) INTO(IOFIELD) KEYTO(NEWNO);
DO WHILE(NOS_REC);
IF UNSPEC(BYTE) ¬= (8)'1'B
THEN PUT FILE(SYSPRINT) SKIP EDIT (NEWNO,IOFIELD)(A(2),X(3),A);
PUT FILE(SYSPRINT) SKIP EDIT (IOFIELD) (A);
END;
CLOSE FILE(NOS);
END ACR1;
/]
//GO.NOS DD DSN=J44PLI.NOS,DISP=(OLD,DELETE),UNIT=SYSDA,VOL=SER=nnnnnn
//GO.SYSIN DD ]
NEWMAN,M.W. 564K C
GOODFELLOW,D.T. 89 A
MILES,R. 23 D
HARVEY,C.D.W. 29 A
BARTLETT,S.G. 13 A
CORY,G. 36 D
READ,K.M. K1 A
PITT,W.H. 55
ROLF,D.F. 14 D
ELLIOTT,D. 4285 C
HASTINGS,G.M. 31 D
BRAMLEY,O.H. 4928 C
/]
Figure 34. Updating a REGIONAL(1) data set

Essential information for creating and accessing regional data sets
To create a regional data set, you must give the operating system certain
information, either in your PL/I program or in the DD statement that defines the
data set. The following paragraphs indicate the essential information, and discuss
some of the optional information you can supply.
You must supply the following information when creating a regional data set:
Device that will write your data set (UNIT or VOLUME parameter of DD
statement).
Block size: You can specify the block size either in your PL/I program (in the
BLKSIZE option of the ENVIRONMENT attribute) or in the DD statement
(BLKSIZE subparameter). If you do not specify a record length, unblocked
records are the default and the record length is determined from the block size.
If you want to keep a data set (that is, you do not want the operating system to
delete it at the end of your job), the DD statement must name the data set and
indicate how it is to be disposed of (DSNAME and DISP parameters). The DISP
parameter alone will suffice if you want to use the data set in a later step but do not
need it after the end of your job.
If you want your data set stored on a particular direct-access device, you must
indicate the volume serial number in the DD statement (SER or REF subparameter
of VOLUME parameter). If you do not supply a serial number for a data set that
you want to keep, the operating system allocates one, informs the operator, and
prints the number on your program listing. All the essential parameters required in
a DD statement for the creation of a regional data set are summarized in Table 20;
and Table 21 on page 196 lists the DCB subparameters needed. See your
OS/390 JCL User's Guide for a description of the DCB subparameters.
You cannot place a regional data set on a system output (SYSOUT) device.
In the DCB parameter, you must always specify the data set organization as direct
by coding DSORG=DA. You cannot specify the DUMMY or DSN=NULLFILE
parameters in a DD statement for a regional data set.
Table 20 (Page 1 of 2). Creating a regional data set: essential parameters of the DD
statement
UNIT= or Output device1 Always
VOLUME=REF=
SPACE= Storage space required2
DCB= Data control block information:

see Table 21 on page 196
DISP= Disposition Data set to be used in another job step but not
required in another job
DISP= Disposition Data set to be kept after end of job
DSNAME= Name of data set

Table 20 (Page 2 of 2). Creating a regional data set: essential parameters of the DD
statement
VOLUME=SER= or Volume serial number Data set to be on particular volume
VOLUME=REF=
1Regional data sets are confined to direct-access devices.
2For sequential access, the data set can have up to 15 extents, which can be on more than one volume.
For creation with DIRECT access, the data set can have only one extent.
To access a regional data set, you must identify it to the operating system in a DD
statement. The following paragraphs indicate the minimum information you must
include in the DD statement; this information is summarized in Table 22.
If the data set is cataloged, you need to supply only the following information in
your DD statement:
The name of the data set (DSNAME parameter). The operating system locates
the information that describes the data set in the system catalog and, if
necessary, requests the operator to mount the volume that contains it.
Confirmation that the data set exists (DISP parameter).
If the data set is not cataloged, you must, in addition, specify the device that will
read the data set and give the serial number of the volume that contains the data
set (UNIT and VOLUME parameters).
Regional data sets do not require the subparameter OPTCD=L in the DD

statement.
When opening a multiple-volume regional data set for sequential update, the
ENDFILE condition is raised at the end of the first volume.
Table 21. DCB subparameters for a regional data set

Subparameters To specify When required
RECFM=F Record format1 These are always required
BLKSIZE= Block size1
DSORG=DA Data set organization

1Or you can specify the block size in the ENVIRONMENT attribute.
Table 22. Accessing a regional data set: essential parameters of the DD statement
DSNAME= Name of data set Always
DISP= Disposition of data set

UNIT= or Input device If data set not cataloged
VOLUME=REF=
VOLUME=SER= Volume serial number

Chapter 10. Defining and using VSAM data sets
This chapter covers VSAM (the Virtual Storage Access Method) organization for
record-oriented data transmission, VSAM ENVIRONMENT options, compatibility
with other PL/I data set organizations, and the statements you use to load and
access the three types of VSAM data sets that PL/I supports—entry-sequenced,
key-sequenced, and relative record. The chapter is concluded by a series of
examples showing the PL/I statements, Access Method Services commands, and
JCL statements necessary to create and access VSAM data sets.
For additional information about the facilities of VSAM, the structure of VSAM data
sets and indexes, the way in which they are defined by Access Method Services,
and the required JCL statements, see the VSAM publications for your system.
Using VSAM data sets
How to run a program with VSAM data sets

Before you execute a program that accesses a VSAM data set, you need to know:
The name of the VSAM data set
The name of the PL/I file
Whether you intend to share the data set with other users
Then you can write the required DD statement to access the data set:
//filename DD DSNAME=dsname,DISP=OLD|SHR
For example, if your file is named PL1FILE, your data set named VSAMDS, and
you want exclusive control of the data set, enter:
//PL1FILE DD DSNAME=VSAMDS,DISP=OLD
To share your data set, use DISP=SHR.
To optimize VSAM's performance by controlling the number of VSAM buffers used

for your data set, see the VSAM publications.
Pairing an Alternate Index Path with a File

When using an alternate index, you simply specify the name of the path in the
DSNAME parameter of the DD statement associating the base data set/alternate
index pair with your PL/I file. Before using an alternate index, you should be aware
of the restrictions on processing; these are summarized in Table 24 on page 202.
Given a PL/I file called PL1FILE and the alternate index path called PERSALPH,
the DD statement required would be:
//PL1FILE DD DSNAME=PERSALPH,DISP=OLD

VSAM organization
PL/I provides support for three types of VSAM data sets:
Key-sequenced data sets (KSDS)
Entry-sequenced data sets (ESDS)
Relative record data sets (RRDS).
These correspond roughly to PL/I indexed, consecutive, and regional data set
organizations, respectively. They are all ordered, and they can all have keys
associated with their records. Both sequential and keyed access are possible with
all three types.
Although only key-sequenced data sets have keys as part of their logical records,
keyed access is also possible for entry-sequenced data sets (using relative-byte
addresses) and relative record data sets (using relative record numbers).
All VSAM data sets are held on direct-access storage devices, and a virtual storage
operating system is required to use them.
The physical organization of VSAM data sets differs from those used by other
access methods. VSAM does not use the concept of blocking, and, except for
relative record data sets, records need not be of a fixed length. In data sets with
VSAM organization, the data items are arranged in control intervals, which are in
turn arranged in control areas. For processing purposes, the data items within a
control interval are arranged in logical records. A control interval can contain one
or more logical records, and a logical record can span two or more control intervals.
Concern about blocking factors and record length is largely removed by VSAM,
although records cannot exceed the maximum specified size. VSAM allows access
to the control intervals, but this type of access is not supported by PL/I.
VSAM data sets can have two types of indexes—prime and alternate. A prime
index is the index to a KSDS that is established when you define a data set; it
always exists and can be the only index for a KSDS. You can have one or more
alternate indexes on a KSDS or an ESDS. Defining an alternate index for an ESDS
enables you to treat the ESDS, in general, as a KSDS. An alternate index on a
KSDS enables a field in the logical record different from that in the prime index to
be used as the key field. Alternate indexes can be either nonunique, in which
duplicate keys are allowed, or unique, in which they are not. The prime index can
never have duplicate keys.
Any change in a data set that has alternate indexes must be reflected in all the
indexes if they are to remain useful. This activity is known as index upgrade, and is
done by VSAM for any index in the index upgrade set of the data set. (For a KSDS,
the prime index is always a member of the index upgrade set.) However, you must
avoid making changes in the data set that would cause duplicate keys in the prime
index or in a unique alternate index.
Before using a VSAM data set for the first time, you need to define it to the system
with the DEFINE command of Access Method Services, which you can use to
completely define the type, structure, and required space of the data set. This
command also defines the data set's indexes (together with their key lengths and
locations) and the index upgrade set if the data set is a KSDS or has one or more
alternate indexes. A VSAM data set is thus “created” by Access Method Services.

The operation of writing the initial data into a newly created VSAM data set is
referred to as loading in this publication.
Use the three different types of data sets according to the following purposes:
Use entry-sequenced data sets for data that you primarily access in the order
in which it was created (or the reverse order).
Use key-sequenced data sets when you normally access records through keys
within the records (for example, a stock-control file where the part number is
used to access a record).
Use relative record data sets for data in which each item has a particular
number, and you normally access the relevant record by that number (for
example, a telephone system with a record associated with each number).
You can access records in all types of VSAM data sets either directly by means of
a key, or sequentially (backward or forward). You can also use a combination of
the two ways: Select a starting point with a key and then read forward or backward
from that point.
You can create alternate indexes for key-sequenced and entry-sequenced data
sets. You can then access your data in many sequences or by one of many keys.
For example, you could take a data set held or indexed in order of employee
number and index it by name in an alternate index. Then you could access it in
alphabetic order, in reverse alphabetic order, or directly using the name as a key.
You could also access it in the same kind of combinations by employee number.
Table 23 shows how the same data could be held in the three different types of
VSAM data sets and illustrates their respective advantages and disadvantages.
Table 23 (Page 1 of 2). Types and advantages of VSAM data sets

Data set type Method of loading Method of reading Method of updating Pros and cons
Key-Sequenced Sequentially in order KEYED by specifying KEYED specifying a Advantages: Complete
or prime index which key of record in prime unique key in any access and updating
must be unique index index
Disadvantages:
SEQUENTIAL SEQUENTIAL Records must be in
backward or forward following positioning order of prime index
in order of any index by unique key before loading
Positioning by key Record deletion Uses: For uses where
followed by allowed access will be related to
sequential reading key
Record insertion
either backward or
allowed
forward
Entry-Sequenced Sequentially (forward SEQUENTIAL New records at end Advantages: Simple
only) backward or forward only fast creation
The RBA of each KEYED using RBA Existing records No requirement for a
record can be cannot have length unique index
Positioning by key
obtained and used as changed
followed by Disadvantages:
a key
sequential either Record deletion not Limited updating
backward or forward allowed facilities
Uses: For uses where
data will primarily be
accessed sequentially
Chapter 10. Defining and using VSAM data sets 199

Table 23 (Page 2 of 2). Types and advantages of VSAM data sets
Data set type Method of loading Method of reading Method of updating Pros and cons
Relative Record Sequentially starting KEYED specifying Sequentially starting Advantages: Speedy
from slot 1 numbers as key at a specified slot and access to record by
continuing with next number
KEYED specifying Sequential forward or
slot
number of slot backward omitting Disadvantages:
empty records Keyed specifying Structure tied to
Positioning by key
numbers as key numbering sequences
followed by
sequential writes Record deletion Fixed length records
allowed
Uses: For use where
Record insertion into records will be
empty slots allowed accessed by number
Keys for VSAM data sets

All VSAM data sets can have keys associated with their records. For
key-sequenced data sets, and for entry-sequenced data sets accessed via an
alternate index, the key is a defined field within the logical record. For
entry-sequenced data sets, the key is the relative byte address (RBA) of the record.
For relative-record data sets, the key is a relative record number.
Keys for indexed VSAM data sets

Keys for key-sequenced data sets and for entry-sequenced data sets accessed via
an alternate index are part of the logical records recorded on the data set. You
define the length and location of the keys when you create the data set.
The ways you can reference the keys in the KEY, KEYFROM, and KEYTO options
are as described under “KEY(expression) Option,” “KEYFROM(expression) Option,”
and “KEYTO(reference) Option” in Chapter 12 of the PL/I Language Reference.
Relative byte addresses (RBA)

Relative byte addresses allow you to use keyed access on an ESDS associated
with a KEYED SEQUENTIAL file. The RBAs, or keys, are character strings of
length 4, and their values are defined by VSAM. You cannot construct or
manipulate RBAs in PL/I; you can, however, compare their values in order to
determine the relative positions of records within the data set. RBAs are not
normally printable.
You can obtain the RBA for a record by using the KEYTO option, either on a
WRITE statement when you are loading or extending the data set, or on a READ
statement when the data set is being read. You can subsequently use an RBA
obtained in either of these ways in the KEY option of a READ or REWRITE
statement.
Do not use an RBA in the KEYFROM option of a WRITE statement.
VSAM allows use of the relative byte address as a key to a KSDS, but this use is
not supported by PL/I.

Relative record numbers
Records in an RRDS are identified by a relative record number that starts at 1 and
is incremented by 1 for each succeeding record. You can use these relative record
numbers as keys for keyed access to the data set.
Keys used as relative record numbers are character strings of length 8. The
character value of a source key you use in the KEY or KEYFROM option must
represent an unsigned integer. If the source key is not 8 characters long, it is
truncated or padded with blanks (interpreted as zeros) on the left. The value
returned by the KEYTO option is a character string of length 8, with leading zeros
suppressed.
Choosing a data set type

When planning your program, the first decision to be made is which type of data
set to use. There are three types of VSAM data sets and five types of non-VSAM
data sets available to you. VSAM data sets can provide all the function of the other
types of data sets, plus additional function available only in VSAM. VSAM can
usually match other data set types in performance, and often improve upon it.
However, VSAM is more subject to performance degradation through misuse of
function.
The comparison of all eight types of data sets given in Table 14 on page 154 is
helpful; however, many factors in the choice of data set type for a large installation
are beyond the scope of this book.
When choosing between the VSAM data set types, you should base your choice on
the most common sequence in which you will require your data. The following is a
suggested procedure that you can use to help ensure a combination of data sets
and indexes that provide the function you require.
1. Determine the type of data and how it will be accessed.
a. Primarily sequentially — favors ESDS.
b. Primarily by key — favors KSDS.
c. Primarily by number — favors RRDS.
2. Determine how you will load the data set. Note that you must load a KSDS in
key sequence; thus an ESDS with an alternate index path can be a more
practical alternative for some applications.
3. Determine whether you require access through an alternate index path. These
are only supported on KSDS and ESDS. If you require an alternate index path,
determine whether the alternate index will have unique or nonunique keys. Use
of nonunique keys can limit key processing. However, it might also be
impractical to assume that you will use unique keys for all future records; if you
attempt to insert a record with a nonunique key in an index that you have
created for unique keys, it will cause an error.
4. When you have determined the data sets and paths that you require, ensure
that the operations you have in mind are supported. Figure 35 on page 202
might be helpful.
Do not try to access a dummy VSAM data set, because you will receive an error
message indicating that you have an undefined file.

Table 25 on page 206, Table 26 on page 209, and Table 27 on page 222 show
the statements allowed for entry-sequenced data sets, indexed data sets, and
relative record data sets, respectively.
SEQUENTIAL KEYED SEQUENTIAL DIRECT
INPUT ESDS ESDS KSDS

KSDS KSDS RRDS
RRDS RRDS Path(U)
Path(N) Path(N)
Path(U) Path(U)
OUTPUT ESDS ESDS KSDS

RRDS KSDS RRDS
RRDS Path(U)
UPDATE ESDS ESDS KSDS

KSDS KSDS RRDS
RRDS RRDS Path(U)
Path(N) Path(N)
Path(U) Path(U)
Key: ESDS Entry-sequenced data set

KSDS Key-sequenced data set
RRDS Relative record data set
Path(N) Alternate index path with nonunique keys
Path(U) Alternate index path with unique keys
You can combine the attributes on the left with those at

the top of the figure for the data sets and paths shown.
For example, only an ESDS and an RRDS can be SEQUENTIAL OUTPUT.
PL/I does not support dummy VSAM data sets.
Figure 35. VSAM data sets and allowed file attributes
Table 24. Processing Allowed on Alternate Index Paths

Base Cluster Type Alternate Index Key Type Processing Restrictions
KSDS Unique key As normal KSDS May not modify key of access.
Nonunique key Limited keyed access May not modify key of access.
ESDS Unique key As KSDS No deletion.
Nonunique key Limited keyed access May not modify key of access.
No deletion.
May not modify key of access.
Defining files for VSAM data sets

You define a sequential VSAM data set by using a file declaration with the following
attributes:
SEQUENTIAL
BUFFERED
[KEYED]

You define a direct VSAM data set by using a file declaration with the following
attributes:
DIRECT
[KEYED]
Table 13 on page 147 shows the default attributes. The file attributes are
Some combinations of the file attributes INPUT or OUTPUT or UPDATE and

DIRECT or SEQUENTIAL or KEYED SEQUENTIAL are allowed only for certain
types of VSAM data sets. Figure 35 on page 202 shows the compatible
combinations.

Many of the options of the ENVIRONMENT attribute affecting data set structure are
not needed for VSAM data sets. If you specify them, they are either ignored or are
used for checking purposes. If those that are checked conflict with the values
defined for the data set, the UNDEFINEDFILE condition is raised when an attempt
is made to open the file.
The ENVIRONMENT options applicable to VSAM data sets are:

BKWD
GENKEY
REUSE
SCALARVARYING
VSAM
GENKEY and SCALARVARYING options have the same effect as they do when
you use them for non-VSAM data sets.
The options that are checked for a VSAM data set are RECSIZE and, for a
key-sequenced data set, KEYLENGTH and KEYLOC. Table 13 on page 147
shows which options are ignored for VSAM. Table 13 on page 147 also shows the
required and default options.
For VSAM data sets, you specify the maximum and average lengths of the records
to the Access Method Services utility when you define the data set. If you include
the RECSIZE option in the file declaration for checking purposes, specify the
maximum record size. If you specify RECSIZE and it conflicts with the values
defined for the data set, the UNDEFINEDFILE condition is raised.
BKWD option
Use the BKWD option to specify backward processing for a SEQUENTIAL INPUT
or SEQUENTIAL UPDATE file associated with a VSAM data set.
──BKWD─────────────────────────────────────────────────────────────────────────

Sequential reads (that is, reads without the KEY option) retrieve the previous record
in sequence. For indexed data sets, the previous record is, in general, the record

with the next lower key. However, if you are accessing the data set via a
nonunique alternate index, records with the same key are recovered in their normal
sequence. For example, if the records are:
A B C1 C2 C3 D E
where C1, C2, and C3 have the same key, they are recovered in the sequence:
E D C1 C2 C3 B A
When a file with the BKWD option is opened, the data set is positioned at the last
record. ENDFILE is raised in the normal way when the start of the data set is
reached.
Do not specify the BKWD option with either the REUSE option or the GENKEY
option. Also, the WRITE statement is not allowed for files declared with the BKWD
option.
GENKEY option
For the description of this option, see “GENKEY option — key classification” on
page 151.
REUSE option
Use the REUSE option to specify that an OUTPUT file associated with a VSAM
data set is to be used as a work file.
──REUSE────────────────────────────────────────────────────────────────────────

The data set is treated as an empty data set each time the file is opened. Any
secondary allocations for the data set are released, and the data set is treated
exactly as if it were being opened for the first time.
Do not associate a file that has the REUSE option with a data set that has alternate
indexes or the BKWD option, and do not open it for INPUT or UPDATE.
The REUSE option takes effect only if you specify REUSE in the Access Method
Services DEFINE CLUSTER command.
VSAM option
Specify the VSAM option for VSAM data sets.
──VSAM─────────────────────────────────────────────────────────────────────────

Performance options
You can specify the buffer options in the AMP parameter of the DD statement; they
are explained in your Access Method Services manual.

Defining Files for Alternate Index Paths
VSAM allows you to define alternate indexes on key sequenced and entry
sequenced data sets. This enables you to access key sequenced data sets in a
number of ways other than from the prime index. This also allows you to index and
access entry sequenced data sets by key or sequentially in order of the keys.
Consequently, data created in one form can be accessed in a large number of
different ways. For example, an employee file might be indexed by personnel
number, by name, and also by department number.
When an alternate index has been built, you actually access the data set through a
third object known as an alternate index path that acts as a connection between the
alternate index and the data set.
Two types of alternate indexes are allowed—unique key and nonunique key. For a
unique key alternate index, each record must have a different alternate key. For a
nonunique key alternate index, any number of records can have the same alternate
key. In the example suggested above, the alternate index using the names could
be a unique key alternate index (provided each person had a different name). The
alternate index using the department number would be a nonunique key alternate
index because more than one person would be in each department.
In most respects, you can treat a data set accessed through a unique key alternate
index path like a KSDS accessed through its prime index. You can access the
records by key or sequentially, you can update records, and you can add new
records. If the data set is a KSDS, you can delete records, and alter the length of
updated records. Restrictions and allowed processing are shown in Table 24 on
page 202. When you add or delete records, all indexes associated with the data
set are by default altered to reflect the new situation.
In data sets accessed through a nonunique key alternate index path, the record
accessed is determined by the key and the sequence. The key can be used to
establish positioning so that sequential access can follow. The use of the key
accesses the first record with that key. When the data set is read backwards, only
the order of the keys is reversed. The order of the records with the same key
remains the same whichever way the data set is read.
Defining VSAM data sets

Use the DEFINE CLUSTER command of Access Method Services to define and
catalog VSAM data sets. To use the DEFINE command, you need to know:
The name and password of the master catalog if the master catalog is
password protected
The name and password of the VSAM private catalog you are using if you are
not using the master catalog
Whether VSAM space for your data set is available
The type of VSAM data set you are going to create
The volume on which your data set is to be placed
The average and maximum record size in your data set
The position and length of the key for an indexed data set

The space to be allocated for your data set
How to code the DEFINE command
How to use the Access Method Services program.
When you have the information, you are in a position to code the DEFINE
command and then define and catalog the data set using Access Method Services.
Entry-sequenced data sets

The statements and options allowed for files associated with an ESDS are shown in
Table 25.
Table 25. Statements and options allowed for loading and accessing VSAM
entry-sequenced data sets
File Valid statements, with options Other options you can
declaration1 you must include also include
SEQUENTIAL OUTPUT WRITE FILE(file-reference) KEYTO(reference)
BUFFERED FROM(reference);
LOCATE based-variable
SET(pointer-reference)
SEQUENTIAL INPUT READ FILE(file-reference) KEYTO(reference) or
BUFFERED INTO(reference); KEY(expression)3
READ FILE(file-reference) KEYTO(reference) or
SET(pointer-reference); KEY(expression)3
READ FILE(file-reference); IGNORE(expression)
SEQUENTIAL UPDATE READ FILE(file-reference) KEYTO(reference) or
BUFFERED INTO(reference); KEY(expression)3
READ FILE(file-reference) KEYTO(reference) or
SET(pointer-reference); KEY(expression)3
READ FILE(file-reference)2 IGNORE(expression)
WRITE FILE(file-reference) KEYTO(reference)
FROM(reference);
REWRITE FILE(file-reference);
FROM(reference)
and/or
KEY(expression)3
Notes:
1. The complete file declaration would include the attributes FILE, RECORD, and ENVIRONMENT; if
you use either of the options KEY or KEYTO, it must also include the attribute KEYED.
2. The statement “READ FILE(file-reference);” is equivalent to the statement “READ
FILE(file-reference) IGNORE (1);.”
3. The expression used in the KEY option must be a relative byte address, previously obtained by
means of the KEYTO option.
Loading an ESDS
When an ESDS is being loaded, the associated file must be opened for
SEQUENTIAL OUTPUT. The records are retained in the order in which they are
presented.
You can use the KEYTO option to obtain the relative byte address of each record
as it is written. You can subsequently use these keys to achieve keyed access to
the data set.

Using a SEQUENTIAL file to access an ESDS
You can open a SEQUENTIAL file that is used to access an ESDS with either the
INPUT or the UPDATE attribute. If you use either of the options KEY or KEYTO,
the file must also have the KEYED attribute.
Sequential access is in the order that the records were originally loaded into the
data set. You can use the KEYTO option on the READ statements to recover the
RBAs of the records that are read. If you use the KEY option, the record that is
recovered is the one with the RBA you specify. Subsequent sequential access
continues from the new position in the data set.
For an UPDATE file, the WRITE statement adds a new record at the end of the
data set. With a REWRITE statement, the record rewritten is the one with the
specified RBA if you use the KEY option; otherwise, it is the record accessed on
the previous READ. You must not attempt to change the length of the record that
is being replaced with a REWRITE statement.
The DELETE statement is not allowed for entry-sequenced data sets.
Defining and loading an ESDS

In Figure 36 on page 208, the data set is defined with the DEFINE CLUSTER
command and given the name PLIVSAM.AJC1.BASE. The NONINDEXED
keyword causes an ESDS to be defined.
The PL/I program writes the data set using a SEQUENTIAL OUTPUT file and a
WRITE FROM statement. The DD statement for the file contains the DSNAME of
the data set given in the NAME parameter of the DEFINE CLUSTER command.
The RBA of the records could have been obtained during the writing for subsequent
use as keys in a KEYED file. To do this, a suitable variable would have to be
declared to hold the key and the WRITE...KEYTO statement used. For example:
DCL CHARS CHAR(4);
WRITE FILE(FAMFILE) FROM (STRING)
KEYTO(CHARS);
Note that the keys would not normally be printable, but could be retained for
subsequent use.
The cataloged procedure IBMZCBG is used. Because the same program (in
Figure 36 on page 208) can be used for adding records to the data set, it is
retained in a library. This procedure is shown in the next example.

//OPT9#7 JOB
//STEP1 EXEC PGM=IDCAMS,REGION=512K
//SYSIN DD ]
DEFINE CLUSTER -
(NAME(PLIVSAM.AJC1.BASE) -
VOLUMES(nnnnnn) -
NONINDEXED -
RECORDSIZE(8K 8K) -
TRACKS(2 2))
/]
//STEP2 EXEC IBMZCLG
//PLI.SYSIN DD ]
CREATE: PROC OPTIONS(MAIN);
DCL
FAMFILE FILE SEQUENTIAL OUTPUT ENV(VSAM),
IN FILE RECORD INPUT,
STRING CHAR(8K),
READ FILE(IN) INTO (STRING);

DO I=1 BY 1 WHILE (¬EOF);
PUT FILE(SYSPRINT) SKIP EDIT (STRING) (A);
WRITE FILE(FAMFILE) FROM (STRING);
END;
PUT SKIP EDIT(I-1,' RECORDS PROCESSED')(A);

END;
/]
//LKED.SYSLMOD DD DSN=HPU8.MYDS(PGMA),DISP=(NEW,CATLG),
// UNIT=SYSDA,SPACE=(CYL,(1,1,1))
//GO.FAMFILE DD DSNAME=PLIVSAM.AJC1.BASE,DISP=OLD
//GO.IN DD ]
FRED 69 M
ANDY 7K M
SUZAN 72 F
/]
Figure 36. Defining and loading an entry-sequenced data set (ESDS)
Updating an ESDS
Figure 37 shows the addition of a new record on the end of an ESDS. This is
done by executing again the program shown in Figure 36. A SEQUENTIAL
OUTPUT file is used and the data set associated with it by use of the DSNAME
parameter specifying the name PLIVSAM.AJC1.BASE specified in the DEFINE
command shown in Figure 36.
//OPT9#8 JOB
//STEP1 EXEC PGM=PGMA
//STEPLIB DD DSN=HPU8.MYDS(PGMA),DISP=(OLD,KEEP)
// DD DSN=CEE.SCEERUN,DISP=SHR
//FAMFILE DD DSN=PLIVSAM.AJC1.BASE,DISP=SHR
//IN DD ]
JANE 75 F
//
Figure 37. Updating an ESDS
You can rewrite existing records in an ESDS, provided that the length of the record
is not changed. You can use a SEQUENTIAL or KEYED SEQUENTIAL update file

to do this. If you use keys, they can be the RBAs or keys of an alternate index
path.
Delete is not allowed for ESDS.
Key-sequenced and indexed entry-sequenced data sets

The statements and options allowed for indexed VSAM data sets are shown in
Table 26. An indexed data set can be a KSDS with its prime index, or either a
KSDS or an ESDS with an alternate index Except where otherwise stated, the
following description applies to all indexed VSAM data sets.
Table 26 (Page 1 of 2). Statements and options allowed for loading and accessing VSAM
indexed data sets

FILE(file-reference)
SEQUENTIAL INPUT READ FILE(file-reference) KEY(expression) or
BUFFERED INTO(reference); KEYTO(reference)
READ FILE(file-reference) KEY(expression) or

SET(pointer-reference); KEYTO(reference)
READ FILE(file-reference);2 IGNORE(expression)

SEQUENTIAL UPDATE READ FILE(file-reference) KEY(expression) or

FROM(reference)
REWRITE FILE(file-reference); FROM(reference) and/or

KEY(expression)
DELETE FILE(file-reference) KEY(expression)

DIRECT READ FILE(file-reference)
BUFFERED INTO(reference)
KEY(expression);
KEY(expression);

indexed data sets
DIRECT READ FILE(file-reference)
KEY(expression);
KEY(expression);
FROM(reference)
KEY(expression);
KEY(expression);
FROM(reference)
Notes:
1. The complete file declaration would include the attributes FILE and RECORD. If you use any of the
options KEY, KEYFROM, or KEYTO, you must also include the attribute KEYED in the declaration.
IGNORE(1);
3. Do not associate a SEQUENTIAL OUTPUT file with a data set accessed via an alternate index.
4. Do not associate a DIRECT file with a data set accessed via a nonunique alternate index.
5. DELETE statements are not allowed for a file associated with an ESDS accessed via an alternate
index.
Loading a KSDS or indexed ESDS

When a KSDS is being loaded, you must open the associated file for KEYED
SEQUENTIAL OUTPUT. You must present the records in ascending key order,
and you must use the KEYFROM option. Note that you must use the prime index
for loading the data set; you cannot load a VSAM data set via an alternate index.
If a KSDS already contains some records, and you open the associated file with the
SEQUENTIAL and OUTPUT attributes, you can add only records at the end of the
data set. The rules given in the previous paragraph apply; in particular, the first
record you present must have a key greater than the highest key present on the
data set.
Figure 38 on page 211 shows the DEFINE command used to define a KSDS. The
data set is given the name PLIVSAM.AJC2.BASE and defined as a KSDS because
of the use of the INDEXED operand. The position of the keys within the record is
defined in the KEYS operand.
Within the PL/I program, a KEYED SEQUENTIAL OUTPUT file is used with a
WRITE...FROM...KEYFROM statement. The data is presented in ascending key
order. A KSDS must be loaded in this manner.
The file is associated with the data set by a DD statement which uses the name
given in the DEFINE command as the DSNAME parameter.

//OPT9#12 JOB
// EXEC PGM=IDCAMS,REGION=512K
//SYSIN DD ]
DEFINE CLUSTER -
VOLUMES(nnnnnn) -
INDEXED -
TRACKS(3 1) -
KEYS(2K K) -
RECORDSIZE(23 8K))
/]
// EXEC IBMZCBG
//PLI.SYSIN DD ]
TELNOS: PROC OPTIONS(MAIN);
DCL DIREC FILE RECORD SEQUENTIAL OUTPUT KEYED ENV(VSAM),

CARD CHAR(8K),
NAME CHAR(2K) DEF CARD POS(1),
NUMBER CHAR(3) DEF CARD POS(21),
OUTREC CHAR(23) DEF CARD POS(1),
OPEN FILE(DIREC) OUTPUT;
GET FILE(SYSIN) EDIT(CARD)(A(8K));

DO WHILE (¬EOF);
WRITE FILE(DIREC) FROM(OUTREC) KEYFROM(NAME);
END;
CLOSE FILE(DIREC);
END TELNOS;
/]
//GO.DIREC DD DSNAME=PLIVSAM.AJC2.BASE,DISP=OLD
//GO.SYSIN DD ]
ACTION,G. 162
BAKER,R. 152
BRAMLEY,O.H. 248
CHEESEMAN,D. 141
CORY,G. 336
ELLIOTT,D. 875
FIGGINS,S. 413
HARVEY,C.D.W. 2K5
HASTINGS,G.M. 391
KENDALL,J.G. 294
LANCASTER,W.R. 624
MILES,R. 233
NEWMAN,M.W. 45K
PITT,W.H. 515
ROLF,D.E. 114
SHEERS,C.D. 241
SUTCLIFFE,M. 472
TAYLOR,G.C. 4K7
WILTON,L.W. 4K4
WINSTONE,E.M. 3K7
//
Figure 38. Defining and loading a key-sequenced data set (KSDS)

Using a SEQUENTIAL file to access a KSDS or indexed ESDS
You can open a SEQUENTIAL file that is used to access a KSDS with either the
INPUT or the UPDATE attribute.
For READ statements without the KEY option, the records are recovered in
ascending key order (or in descending key order if the BKWD option is used). You
can obtain the key of a record recovered in this way by means of the KEYTO
option.
If you use the KEY option, the record recovered by a READ statement is the one
with the specified key. Such a READ statement positions the data set at the
specified record; subsequent sequential reads will recover the following records in
sequence.
WRITE statements with the KEYFROM option are allowed for KEYED
SEQUENTIAL UPDATE files. You can make insertions anywhere in the data set,
without respect to the position of any previous access. If you are accessing the
data set via a unique index, the KEY condition is raised if an attempt is made to
insert a record with the same key as a record that already exists on the data set.
For a nonunique index, subsequent retrieval of records with the same key is in the
order that they were added to the data set.
REWRITE statements with or without the KEY option are allowed for UPDATE files.
If you use the KEY option, the record that is rewritten is the first record with the
specified key; otherwise, it is the record that was accessed by the previous READ
statement. When you rewrite a record using an alternate index, do not change the
prime key of the record.
Using a DIRECT file to access a KSDS or indexed ESDS

You can open a DIRECT file that is used to access an indexed VSAM data set with
the INPUT, OUTPUT, or UPDATE attribute. Do not use a DIRECT file to access
the data set via a nonunique index.
If you use a DIRECT OUTPUT file to add records to the data set, and if an attempt
is made to insert a record with the same key as a record that already exists, the
KEY condition is raised.
If you use a DIRECT INPUT or DIRECT UPDATE file, you can read, write, rewrite,
or delete records in the same way as for a KEYED SEQUENTIAL file.
Figure 39 on page 213 shows one method by which a KSDS can be updated
using the prime index.

//OPT9#13 JOB
//PLI.SYSIN DD ]
DIRUPDT: PROC OPTIONS(MAIN);
DCL DIREC FILE RECORD KEYED ENV(VSAM),

ONCODE BUILTIN,
OUTREC CHAR(23),
NUMBER CHAR(3) DEF OUTREC POS(21),
NAME CHAR(2K) DEF OUTREC,
CODE CHAR(1),
ON KEY(DIREC) BEGIN;
IF ONCODE=51 THEN PUT FILE(SYSPRINT) SKIP EDIT
('NOT FOUND: ',NAME)(A(15),A);
('DUPLICATE: ',NAME)(A(15),A);
END;
OPEN FILE(DIREC) DIRECT UPDATE;
GET FILE(SYSIN) EDIT (NAME,NUMBER,CODE)

(COLUMN(1),A(2K),A(3),A(1));
DO WHILE (¬EOF);
PUT FILE(SYSPRINT) SKIP EDIT (' ',NAME,'#',NUMBER,' ',CODE)
(A(1),A(2K),A(1),A(3),A(1),A(1));
SELECT (CODE);
WHEN('A') WRITE FILE(DIREC) FROM(OUTREC) KEYFROM(NAME);
WHEN('C') REWRITE FILE(DIREC) FROM(OUTREC) KEY(NAME);
WHEN('D') DELETE FILE(DIREC) KEY(NAME);
OTHERWISE PUT FILE(SYSPRINT) SKIP EDIT
('INVALID CODE: ',NAME) (A(15),A);
END;
GET FILE(SYSIN) EDIT (NAME,NUMBER,CODE)
(COLUMN(1),A(2K),A(3),A(1));
END;
Figure 39 (Part 1 of 2). Updating a KSDS

CLOSE FILE(DIREC);
OPEN FILE(DIREC) SEQUENTIAL INPUT;
EOF='K'B;
ON ENDFILE(DIREC) EOF='1'B;
READ FILE(DIREC) INTO(OUTREC);

DO WHILE(¬EOF);
PUT FILE(SYSPRINT) SKIP EDIT(OUTREC)(A);
READ FILE(DIREC) INTO(OUTREC);
END;
CLOSE FILE(DIREC);
END DIRUPDT;
/]
//GO.DIREC DD DSNAME=PLIVSAM.AJC2.BASE,DISP=OLD
//GO.SYSIN DD ]
NEWMAN,M.W. 516C
GOODFELLOW,D.T. 889A
MILES,R. D
HARVEY,C.D.W. 2K9A
BARTLETT,S.G. 183A
CORY,G. D
READ,K.M. KK1A
PITT,W.H.
ROLF,D.F. D
ELLIOTT,D. 291C
HASTINGS,G.M. D
BRAMLEY,O.H. 439C
/]
Figure 39 (Part 2 of 2). Updating a KSDS
A DIRECT update file is used and the data is altered according to a code that is
passed in the records in the file SYSIN:
A Add a new record
C Change the number of an existing name
D Delete a record
At the label NEXT, the name, number, and code are read in and action taken
according to the value of the code. A KEY ON-unit is used to handle any incorrect
keys. When the updating is finished (at the label PRINT), the file DIREC is closed
and reopened with the attributes SEQUENTIAL INPUT. The file is then read
sequentially and printed.
The file is associated with the data set by a DD statement that uses the DSNAME
PLIVSAM.AJC2.BASE defined in the Access Method Services DEFINE CLUSTER
command in Figure 38 on page 211.
Methods of updating a KSDS: There are a number of methods of updating a

KSDS. The method shown using a DIRECT file is suitable for the data as it is
shown in the example. For mass sequential insertion, use a KEYED SEQUENTIAL
UPDATE file. This gives faster performance because the data is written onto the
data set only when strictly necessary and not after every write statement, and
because the balance of free space within the data set is retained.
Statements to achieve effective mass sequential insertion are:

DCL DIREC KEYED SEQUENTIAL UPDATE
ENV(VSAM);
WRITE FILE(DIREC) FROM(OUTREC)
KEYFROM(NAME);
The PL/I input/output routines detect that the keys are in sequence and make the
correct requests to VSAM. If the keys are not in sequence, this too is detected and
no error occurs, although the performance advantage is lost.
Alternate Indexes for KSDSs or Indexed ESDSs

Alternate indexes allow you to access KSDSs or indexed ESDSs in various ways,
using either unique or nonunique keys.
Unique Key Alternate Index Path

Figure 40 shows the creation of a unique key alternate index path for the ESDS
defined and loaded in Figure 36 on page 208. Using this path, the data set is
indexed by the name of the child in the first 15 bytes of the record.
Three Access Method Services commands are used. These are:
DEFINE ALTERNATEINDEX: defines the alternate index as a data set to VSAM.
BLDINDEX: places the pointers to the relevant records in the alternate index.
DEFINE PATH: defines an entity that can be associated with a PL/I file in a DD
statement.
DD statements are required for the INFILE and OUTFILE operands of BLDINDEX
and for the sort files. Care should be taken that the correct names are specified at
the various points.
//OPT9#9 JOB
//SYSIN DD ]
DEFINE ALTERNATEINDEX -
(NAME(PLIVSAM.AJC1.ALPHIND) -
VOLUMES(nnnnnn) -
TRACKS(4 1) -
KEYS(15 K) -
RECORDSIZE(2K 4K) -
UNIQUEKEY -
RELATE(PLIVSAM.AJC1.BASE))
/]
//DD1 DD DSNAME=PLIVSAM.AJC1.BASE,DISP=SHR
//DD2 DD DSNAME=PLIVSAM.AJC1.ALPHIND,DISP=SHR
//SYSIN DD ]
BLDINDEX INFILE(DD1) OUTFILE(DD2)
DEFINE PATH -
(NAME(PLIVSAM.AJC1.ALPHPATH) -
PATHENTRY(PLIVSAM.AJC1.ALPHIND))
//
Figure 40. Creating a Unique Key Alternate Index Path for an ESDS

Nonunique Key Alternate Index Path
Figure 41 shows the creation of a nonunique key alternate index path for an ESDS.
The alternate index enables the data to be slected by the sex of the children. This
enables he girls or the boys to be accessed separately and every member of each
group to be accessed by use of the key.
The three Access Method Services commands used are:
DEFINE ALTERNATEINDEX: defines the alternate index as a data set to VSAM.
BLDINDEX: places the pointers to the relevant records in the alternate index.
DEFINE PATH: defines an entity that can be associated with a PL/I file in a DD
statement.
DD statements are required for the INFILE and OUTFILE operands of BLDINDEX
and for the sort files. Care should be taken that the correct names are specified at
the various points.
The fact that the index has nonunique keys is specified by the use of the
NONUNIQUEKEY operand. When creating an index with nonunique keys, be
careful to ensure that the RECORDSIZE you specify is large enough. In a
nonunique alternate index, each alternate index record contains pointers to all the
records that have the associated index key. The pointer takes the form of an RBA
for an ESDS and the prime key for a KSDS. When a large number of records might
have the same key, a large record is required.
//OPT9#1K JOB
//SYSIN DD ]
/] care must be taken with recordsize ]/
(NAME(PLIVSAM.AJC1.SEXIND) -
VOLUMES(nnnnnn) -
TRACKS(4 1) -
KEYS(1 37) -
RECORDSIZE(2K 4KK) -
NONUNIQUEKEY -
/]
//DD2 DD DSNAME=PLIVSAM.AJC1.SEXIND,DISP=SHR
//SYSIN DD ]
DEFINE PATH -
(NAME(PLIVSAM.AJC1.SEXPATH) -
PATHENTRY(PLIVSAM.AJC1.SEXIND))
//
Figure 41. Creating a Nonunique Key Alternate Index Path for an ESDS
Figure 42 on page 217 shows the creation of a unique key alternate index path for
a KSDS. The data set is indexed by the telephone number, enabling the number to
be used as a key to discover the name of the person on that extension. The fact
that keys are to be unique is specified by UNIQUEKEY. Also, the data set will be
able to be listed in numerical order to show which numbers are not used. The three
Access Method Services commands used are:

DEFINE ALTERNATEINDEX: defines the data set that will hold the alternate
index data.
BLDINDEX: places the pointer to the relevant records in the alternate index.
DEFINE PATH: defines the entity that can be associated with a PL/I file in a DD
statement.
DD statements are required for the INFILE and OUTFILE of BLDINDEX and for the
sort files. Be careful not to confuse the names involved.
//OPT9#14 JOB
//SYSIN DD ]
(NAME(PLIVSAM.AJC2.NUMIND) -
VOLUMES(nnnnnn) -
TRACKS(4 4) -
KEYS(3 2K) -
RECORDSIZE(24 48) -
UNIQUEKEY -
/]
//DD2 DD DSNAME=PLIVSAM.AJC2.NUMIND,DISP=SHR
//SYSIN DD ]
DEFINE PATH -
(NAME(PLIVSAM.AJC2.NUMPATH) -
PATHENTRY(PLIVSAM.AJC2.NUMIND))
//
Figure 42. Creating a unique Key Alternate Index Path for a KSDS
When creating an alternate index with a unique key, you should ensure that no
further records could be included with the same alternate key. In practice, a unique
key alternate index would not be entirely satisfactory for a telephone directory as it
would not allow two people to have the same number. Similarly, the prime key
would prevent one person having two numbers. A solution would be to have an
ESDS with two nonunique key alternate indexes, or to restructure the data format
to allow more than one number per person and to have a nonunique key alternate
index for the numbers.
Detecting Nonunique Alternate Index Keys

If you are accessing a VSAM data set by means of an alternate index path, the
presence of nonunique keys can be detected by means of the SAMEKEY built-in
function. After each retrieval, SAMEKEY indicates whether any further records exist
with the same alternate index key as the record just retrieved. Hence, it is possible
to stop at the last of a series of records with nonunique keys without having to read
beyond the last record. SAMEKEY (file-reference) returns '1'B if the input/output
statement has completed successfully and the accessed record is followed by
another with the same key; otherwise, it returns '0'B.

Using Alternate Indexes with ESDSs
Figure 43 on page 219 shows the use of alternate indexes and backward reading
on an ESDS. The program has four files:
BASEFLE
reads the base data set forward.
BACKFLE
reads the base data set backward.
ALPHFLE
is the alphabetic alternate index path indexing the children by name.
SEXFILE
is the alternate index path that corresponds to the sex of the children.
There are DD statements for all the files. They connect BASEFLE and BACKFLE to
the base data set by specifying the name of the base data set in the DSNAME
parameter, and connect ALPHFLE and SEXFLE by specifying the names of the
paths given in Figure 40 on page 215 and Figure 41 on page 216.
The program uses SEQUENTIAL files to access the data and print it first in the
normal order, then in the reverse order. At the label AGEQUERY, a DIRECT file is
used to read the data associated with an alternate index key in the unique alternate
index.
Finally, at the label SPRINT, a KEYED SEQUENTIAL file is used to print a list of
the females in the family, using the nonunique key alternate index path. The
SAMEKEY built-in function is used to read all the records with the same key. The
names of the females will be accessed in the order in which they were originally
entered. This will happen whether the file is read forward or backward. For a
nonunique key path, the BKWD option only affects the order in which the keys are
read; the order of items with the same key remains the same as it is when the file
is read forward.
Deletion: At the end of the example, the Access Method Services DELETE
command is used to delete the base data set. When this is done, the associated
alternate indexes and paths will also be deleted.
Using Alternate Indexes with KSDSs

Figure 44 on page 221 shows the use of a path with a unique alternate index key
to update a a KSDS and then to access and print it in the order of the alternate
index.
The alternate index path is associated with the PL/I file by a DD statement that
specifies the name of the path (PLIVSAM.AJC2.NUMPATH, given in the DEFINE
PATH command in Figure 42 on page 217) as the DSNAME.
In the first section of the program, a DIRECT OUTPUT file is used to insert a new
record using the alternate index key. Note that any alteration made with an

alternate index must not alter the prime key or the alternate index key of access of
an existing record. Also, the alternation must not add a duplicate key in the prime
index or any unique key alternate index.
In the second section of the program (at the label PRINTIT), the data set is read in
the order of the alternate index keys using a SEQUENTIAL INPUT file. It is then
printed onto SYSPRINT.
//OPT9#15 JOB
//STEP1 EXEC IBMZCLG
//PLI.SYSIN DD ]
READIT: PROC OPTIONS(MAIN);
DCL BASEFLE FILE SEQUENTIAL INPUT ENV(VSAM),
/]File to read base data set forward ]/
BACKFLE FILE SEQUENTIAL INPUT ENV(VSAM BKWD),
/]File to read base data set backward ]/
ALPHFLE FILE DIRECT INPUT ENV(VSAM),
/]File to access via unique alternate index path ]/
SEXFILE FILE KEYED SEQUENTIAL INPUT ENV(VSAM),
/]File to access via nonunique alternate index path ]/
STRING CHAR(8K), /]String to be read into ]/
1 STRUC DEF (STRING),
2 NAME CHAR(25),
2 DATE_OF_BIRTH CHAR(2),
2 FILL CHAR(1K),
2 SEX CHAR(1);
DCL NAMEHOLD CHAR(25),SAMEKEY BUILTIN;
DCL EOF BIT(1) INIT('K'B);
/]Print out the family eldest first]/
ON ENDFILE(BASEFLE) EOF='1'B;
PUT EDIT('FAMILY ELDEST FIRST')(A);
READ FILE(BASEFLE) INTO (STRING);
DO WHILE(¬EOF);
PUT SKIP EDIT(STRING)(A);
READ FILE(BASEFLE) INTO (STRING);
END;
CLOSE FILE(BASEFLE);
PUT SKIP(2);
/]Close before using data set from other file not
necessary but good practice to prevent potential
problems]/
EOF='K'B;
ON ENDFILE(BACKFLE) EOF='1'B;
PUT SKIP(3) EDIT('FAMILY YOUNGEST FIRST')(A);
READ FILE(BACKFLE) INTO(STRING);
DO WHILE(¬EOF);
READ FILE(BACKFLE) INTO (STRING);
END;
CLOSE FILE(BACKFLE);
PUT SKIP(2);
/]Print date of birth of child specified in the file

SYSIN]/
ON KEY(ALPHFLE) BEGIN;
PUT SKIP EDIT
(NAMEHOLD,' NOT A MEMBER OF THE SMITH FAMILY') (A);
GO TO SPRINT;
END;
Figure 43 (Part 1 of 2). Alternate Index Paths and Backward Reading with an ESDS

AGEQUERY:
EOF='K'B;
GET SKIP EDIT(NAMEHOLD)(A(25));
DO WHILE(¬EOF);
READ FILE(ALPHFLE) INTO (STRING) KEY(NAMEHOLD);
PUT SKIP (2) EDIT(NAMEHOLD,' WAS BORN IN ',
DATE_OF_BIRTH)(A,X(1),A,X(1),A);
GET SKIP EDIT(NAMEHOLD)(A(25));
END;
SPRINT:
CLOSE FILE(ALPHFLE);
PUT SKIP(1);
/]Use the alternate index to print out all the females in the
family]/
ON ENDFILE(SEXFILE) GOTO FINITO;
PUT SKIP(2) EDIT('ALL THE FEMALES')(A);
READ FILE(SEXFILE) INTO (STRING) KEY('F');
DO WHILE(SAMEKEY(SEXFILE));
READ FILE(SEXFILE) INTO (STRING);
END;
FINITO:
END;
/]
//GO.BASEFLE DD DSN=PLIVSAM.AJC1.BASE,DISP=SHR
//GO.BACKFLE DD DSN=PLIVSAM.AJC1.BASE,DISP=SHR
//GO.ALPHFLE DD DSN=PLIVSAM.AJC1.ALPHPATH,DISP=SHR
//GO.SEXFILE DD DSN=PLIVSAM.AJC1.SEXPATH,DISP=SHR
//GO.SYSIN DD ]
ANDY
/]
//SYSIN DD ]
DELETE -
PLIVSAM.AJC1.BASE
//
Figure 43 (Part 2 of 2). Alternate Index Paths and Backward Reading with an ESDS

//OPT9#16 JOB
//STEP1 EXEC IBMZCLG,REGION.GO=256K
//PLI.SYSIN DD ]
ALTER: PROC OPTIONS(MAIN);
DCL NUMFLE1 FILE RECORD DIRECT OUTPUT ENV(VSAM),
NUMFLE2 FILE RECORD SEQUENTIAL INPUT ENV(VSAM),
IN FILE RECORD,
STRING CHAR(8K),
NAME CHAR(2K) DEF STRING,
NUMBER CHAR(3) DEF STRING POS(21),
DATA CHAR(23) DEF STRING,
ON KEY (NUMFLE1) BEGIN;

PUT SKIP EDIT('DUPLICATE NUMBER')(A);
END;

DO WHILE(¬EOF);
PUT FILE(SYSPRINT) SKIP EDIT (STRING) (A);
WRITE FILE(NUMFLE1) FROM (STRING) KEYFROM(NUMBER);
END;
CLOSE FILE(NUMFLE1);
EOF='K'B;
ON ENDFILE(NUMFLE2) EOF='1'B;
READ FILE(NUMFLE2) INTO (STRING);

DO WHILE(¬EOF);
PUT SKIP EDIT(DATA)(A);
READ FILE(NUMFLE2) INTO (STRING);
END;
PUT SKIP(3) EDIT(']]]]SO ENDS THE PHONE DIRECTORY]]]]')(A);

END;
/]
//GO.IN DD ]
RIERA L 123
/]
//NUMFLE1 DD DSN=PLIVSAM.AJC2.NUMPATH,DISP=OLD
//NUMFLE2 DD DSN=PLIVSAM.AJC2.NUMPATH,DISP=OLD
//STEP2 EXEC PGM=IDCAMS,COND=EVEN
//SYSIN DD ]
DELETE -
PLIVSAM.AJC2.BASE
//
Figure 44. Using a Unique Alternate Index Path to Access a KSDS
Relative-record data sets

The statements and options allowed for VSAM relative-record data sets (RRDS) are
shown in Table 27 on page 222.

relative-record data sets
SEQUENTIAL OUTPUT WRITE FILE(file-reference) KEYFROM(expression) or
BUFFERED FROM(reference); KEYTO(reference)

SEQUENTIAL INPUT READ FILE(file-reference) KEY(expression) or


SEQUENTIAL UPDATE READ FILE(file-reference) KEY(expression) or

WRITE FILE(file-reference) KEYFROM(expression) or

FROM(reference); KEYTO(reference)

and/or
KEY(expression)
DELETE FILE(file-reference); KEY(expression)

DIRECT INPUT READ FILE(file-reference)
KEY(expression);
KEY(expression);

relative-record data sets
KEY(expression);
KEY(expression);
FROM(reference)
KEY(expression);
KEY(expression);
FROM(reference)
Notes:
1. The complete file declaration would include the attributes FILE and RECORD. If you use any of the
options KEY, KEYFROM, or KEYTO, your declaration must also include the attribute KEYED.
The UNLOCK statement for DIRECT UPDATE files is ignored if you use it for files associated with a
VSAM RRDS.
IGNORE(1);
Loading an RRDS
When an RRDS is being loaded, you must open the associated file for OUTPUT.
Use either a DIRECT or a SEQUENTIAL file.
For a DIRECT OUTPUT file, each record is placed in the position specified by the
relative record number (or key) in the KEYFROM option of the WRITE statement
(see “Keys for VSAM data sets” on page 200).
For a SEQUENTIAL OUTPUT file, use WRITE statements with or without the
KEYFROM option. If you specify the KEYFROM option, the record is placed in the
specified slot; if you omit it, the record is placed in the slot following the current
position. There is no requirement for the records to be presented in ascending
relative record number order. If you omit the KEYFROM option, you can obtain the
relative record number of the written record by means of the KEYTO option.
If you want to load an RRDS sequentially, without use of the KEYFROM or KEYTO
options, your file is not required to have the KEYED attribute.
It is an error to attempt to load a record into a position that already contains a

record: if you use the KEYFROM option, the KEY condition is raised; if you omit it,
the ERROR condition is raised.
In Figure 45 on page 224, the data set is defined with a DEFINE CLUSTER
command and given the name PLIVSAM.AJC3.BASE. The fact that it is an RRDS
is determined by the NUMBERED keyword. In the PL/I program, it is loaded with a
DIRECT OUTPUT file and a WRITE...FROM...KEYFROM statement is used.

If the data had been in order and the keys in sequence, it would have been
possible to use a SEQUENTIAL file and write into the data set from the start. The
records would then have been placed in the next available slot and given the
appropriate number. The number of the key for each record could have been
returned using the KEYTO option.
The PL/I file is associated with the data set by the DD statement, which uses as
the DSNAME the name given in the DEFINE CLUSTER command.
//OPT9#17 JOB
//SYSIN DD ]
DEFINE CLUSTER -
VOLUMES(nnnnnn) -
NUMBERED -
TRACKS(2 2) -
RECORDSIZE(2K 2K))
/]
//PLI.SYSIN DD ]
CRR1: PROC OPTIONS(MAIN);
DCL NOS FILE RECORD OUTPUT DIRECT KEYED ENV(VSAM),
CARD CHAR(8K),
NAME CHAR(2K) DEF CARD,
NUMBER CHAR(2) DEF CARD POS(21),
IOFIELD CHAR(2K),
ON ENDFILE (SYSIN) EOF='1'B;
OPEN FILE(NOS);
DO WHILE (¬EOF);
PUT FILE(SYSPRINT) SKIP EDIT (CARD) (A);
IOFIELD=NAME;
WRITE FILE(NOS) FROM(IOFIELD) KEYFROM(NUMBER);
END;
CLOSE FILE(NOS);
END CRR1;
Figure 45 (Part 1 of 2). Defining and loading a relative-record data set (RRDS)

/]
//GO.NOS DD DSN=PLIVSAM.AJC3.BASE,DISP=OLD
//GO.SYSIN DD ]
ACTION,G. 12
BAKER,R. 13
BRAMLEY,O.H. 28
CHEESNAME,L. 11
CORY,G. 36
ELLIOTT,D. 85
FIGGINS.E.S. 43
HARVEY,C.D.W. 25
HASTINGS,G.M. 31
KENDALL,J.G. 24
LANCASTER,W.R. 64
MILES,R. 23
NEWMAN,M.W. 4K
PITT,W.H. 55
ROLF,D.E. 14
SHEERS,C.D. 21
SURCLIFFE,M. 42
TAYLOR,G.C. 47
WILTON,L.W. 44
WINSTONE,E.M. 37
//
Figure 45 (Part 2 of 2). Defining and loading a relative-record data set (RRDS)
Using a SEQUENTIAL file to access an RRDS

You can open a SEQUENTIAL file that is used to access an RRDS with either the
INPUT or the UPDATE attribute. If you use any of the options KEY, KEYTO, or
KEYFROM, your file must also have the KEYED attribute.
For READ statements without the KEY option, the records are recovered in
ascending relative record number order. Any empty slots in the data set are
skipped.
If you use the KEY option, the record recovered by a READ statement is the one
with the relative record number you specify. Such a READ statement positions the
data set at the specified record; subsequent sequential reads will recover the
following records in sequence.
WRITE statements with or without the KEYFROM option are allowed for KEYED
SEQUENTIAL UPDATE files. You can make insertions anywhere in the data set,
regardless of the position of any previous access. For WRITE with the KEYFROM
option, the KEY condition is raised if an attempt is made to insert a record with the
same relative record number as a record that already exists on the data set. If you
omit the KEYFROM option, an attempt is made to write the record in the next slot,
relative to the current position. The ERROR condition is raised if this slot is not
empty.
You can use the KEYTO option to recover the key of a record that is added by
means of a WRITE statement without the KEYFROM option.
REWRITE statements, with or without the KEY option, are allowed for UPDATE
files. If you use the KEY option, the record that is rewritten is the record with the

relative record number you specify; otherwise, it is the record that was accessed by
the previous READ statement.
DELETE statements, with or without the KEY option, can be used to delete records
from the dataset.
Using a DIRECT file to access an RRDS

A DIRECT file used to access an RRDS can have the OUTPUT, INPUT, or
UPDATE attribute. You can read, write, rewrite, or delete records exactly as
though a KEYED SEQUENTIAL file were used.
Figure 46 on page 227 shows an RRDS being updated. A DIRECT UPDATE file
is used and new records are written by key. There is no need to check for the
records being empty, because the empty records are not available under VSAM.
In the second half of the program, starting at the label PRINT, the updated file is
printed out. Again there is no need to check for the empty records as there is in
REGIONAL(1).
The PL/I file is associated with the data sets by a DD statement that specifies the
DSNAME PLIVSAM.AJC3.BASE, the name given in the DEFINE CLUSTER
command in Figure 46 on page 227.
At the end of the example, the DELETE command is used to delete the data set.

//] NOTE: WITH A WRITE STATEMENT AFTER THE DELETE FILE STATEMENT,
//] A “DUPLICATE” MESSAGE IS EXPECTED FOR CODE 'C' ITEMS
//] WHOSE NEWNO CORRESPONDS TO AN EXISTING NUMBER IN THE LIST,
//] FOR EXAMPLE, ELLIOT.
//] WITH A REWRITE STATEMENT AFTER THE DELETE FILE STATEMENT,
//] A “NOT FOUND” MESSAGE IS EXPECTED FOR CODE 'C' ITEMS
//] WHOSE NEWNO DOES NOT CORRESPOND TO AN EXISTING NUMBER IN
//] THE LIST, FOR EXAMPLE, NEWMAN AND BRAMLEY.
//OPT9#18 JOB
//PLI.SYSIN DD ]
ACR1: PROC OPTIONS(MAIN);
DCL NOS FILE RECORD KEYED ENV(VSAM),NAME CHAR(2K),
(NEWNO,OLDNO) CHAR(2),CODE CHAR(1),IOFIELD CHAR(2K),
BYTE CHAR(1) DEF IOFIELD, EOF BIT(1) INIT('K'B),
ONCODE BUILTIN;
OPEN FILE(NOS) DIRECT UPDATE;
ON KEY(NOS) BEGIN;
('NOT FOUND:',NAME)(A(15),A);
('DUPLICATE:',NAME)(A(15),A);
END;
GET FILE(SYSIN) EDIT(NAME,NEWNO,OLDNO,CODE)
(COLUMN(1),A(2K),A(2),A(2),A(1));
DO WHILE (¬EOF);
PUT FILE(SYSPRINT) SKIP EDIT (' ',NAME,'#',NEWNO,OLDNO,' ',CODE)
(A(1),A(2K),A(1),2(A(2)),X(5),2(A(1)));
SELECT(CODE);
WHEN('A') WRITE FILE(NOS) KEYFROM(NEWNO) FROM(NAME);
WHEN('C') DO;
DELETE FILE(NOS) KEY(OLDNO);
WRITE FILE(NOS) KEYFROM(NEWNO) FROM(NAME);
END;
WHEN('D') DELETE FILE(NOS) KEY(OLDNO);
OTHERWISE PUT FILE(SYSPRINT) SKIP EDIT
('INVALID CODE: ',NAME)(A(15),A);
END;
Figure 46 (Part 1 of 2). Updating an RRDS

GET FILE(SYSIN) EDIT(NAME,NEWNO,OLDNO,CODE)
(COLUMN(1),A(2K),A(2),A(2),A(1));
END;
CLOSE FILE(NOS);
PRINT:
OPEN FILE(NOS) SEQUENTIAL INPUT;
EOF='K'B;
ON ENDFILE(NOS) EOF='1'B;
DO WHILE (¬EOF);
PUT FILE(SYSPRINT) SKIP EDIT(NEWNO,IOFIELD)(A(5),A);
END;
CLOSE FILE(NOS);
END ACR1;
/]
//GO.NOS DD DSN=PLIVSAM.AJC3.BASE,DISP=OLD
//GO.SYSIN DD ]
NEWMAN,M.W. 564KC
GOODFELLOW,D.T. 89 A
MILES,R. 23D
HARVEY,C.D.W. 29 A
BARTLETT,S.G. 13 A
CORY,G. 36D
READ,K.M. K1 A
PITT,W.H. 55
ROLF,D.F. 14D
ELLIOTT,D. 4285C
HASTINGS,G.M. 31D
BRAMLEY,O.H. 4928C
//STEP3 EXEC PGM=IDCAMS,REGION=512K,COND=EVEN
//SYSIN DD ]
DELETE -
PLIVSAM.AJC3.BASE
//
Figure 46 (Part 2 of 2). Updating an RRDS

Part 4. Improving your program
Chapter 11. Improving performance . . . . . . . . . . . . . . . . . . . . . . . 230
Selecting compiler options for optimal performance . . . . . . . . . . . . . . . . 230
OPTIMIZE . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 230
GONUMBER . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 230
ARCH . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 230
REDUCE . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 231
RULES . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 231
IBM/ANS . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 231
(NO)LAXCTL . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 232
PREFIX . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 232
CONVERSION . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 233
FIXEDOVERFLOW . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 233
DEFAULT . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 233
BYADDR or BYVALUE . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 233
(NON)CONNECTED . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 234
(NO)DESCRIPTOR . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 234
(NO)INLINE . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 235
LINKAGE . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 235
(RE)ORDER . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 235
NOOVERLAP . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 236
RETURNS(BYVALUE) or RETURNS(BYADDR) . . . . . . . . . . . . . . . 236
Summary of compiler options that improve performance . . . . . . . . . . . . 236
Coding for better performance . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 236
DATA-directed input and output . . . . . . . . . . . . . . . . . . . . . . . . . . 236
Input-only parameters . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 237
GOTO statements . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 237
String assignments . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 237
Loop control variables . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 238
PACKAGEs versus nested PROCEDUREs . . . . . . . . . . . . . . . . . . . . 238
REDUCIBLE Functions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 239
DESCLOCATOR or DESCLIST . . . . . . . . . . . . . . . . . . . . . . . . . . 240
DEFINED versus UNION . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 240
Named constants versus static variables . . . . . . . . . . . . . . . . . . . . . 241
Avoiding calls to library routines . . . . . . . . . . . . . . . . . . . . . . . . . . 242

Improving performance
Chapter 11. Improving performance

Many considerations for improving the speed of your program are independent of
the compiler that you use and the platform on which it runs. This chapter, however,
identifies those considerations that are unique to the PL/I compiler and the code it
generates.
Selecting compiler options for optimal performance

The compiler options you choose can greatly improve the performance of the code
generated by the compiler; however, like most performance considerations, there
are trade-offs associated with these choices. Fortunately, you can weigh the
trade-offs associated with compiler options without editing your source code
because these options can be specified on the command line or in the configuration
file.
If you want to avoid details, the least complex way to improve the performance of
generated code is to specify the following (nondefault) compiler options:
OPT(2)
DFT(REORDER)
The following sections describe, in more detail, performance improvements and

trade-offs associated with specific compiler options.
OPTIMIZE
You can specify the OPTIMIZE option to improve the speed of your program;
otherwise, the compiler makes only basic optimization efforts.
Choosing OPTIMIZE(2) directs the compiler to generate code for better

performance. Usually, the resultant code is shorter than when the program is
compiled under NOOPTIMIZE. Sometimes, however, a longer sequence of
instructions runs faster than a shorter sequence. This occurs, for instance, when a
branch table is created for a SELECT statement where the values in the WHEN
clauses contain gaps. The increased number of instructions generated is usually
offset by the execution of fewer instructions in other places.
GONUMBER
Using this option results in a statement number table used for debugging. This
added information can be extremely helpful when debugging, but including
statement number tables increases the size of your executable file. Larger
executable files can take longer to load.
ARCH
Using ARCH(4) allows the compiler to select from the largest set of instructions
available under z/OS and OS/390 and thus permits it to generate the most optimal
code.

REDUCE
The REDUCE option specifies that the compiler is permitted to reduce an
assignment of a null string to a structure into a simple copy operation - even if that
means padding bytes might be overwritten.
The REDUCE option will cause less executable code to be generated for an
assignment of a null string to a structure, and that will usually mean your code will
run much faster. However, under the REDUCE option, any assignment of a null
string to a structure that is reduced to a simple copy will also cause any padding
bytes in that structure to be filled with '00'x.
For instance, in the following structure, there is one byte of padding between
field11 and field12. Under the NOREDUCE option, the assignment struc = ''; will
cause four assignments to be generated, but the padding byte will be unchanged.
However, under the REDUCE option, the assignment would be reduced to one
simple copy (a MVC), but the padding byte will be set to a '00'x.
dcl
1 struc,
5 field1K bin fixed(31),
5 field11 dec fixed(13)
5 field12 bin fixed(15),
5 field13 char(2);
RULES
Most of the RULES suboptions affect only the severity with which certain coding
practices, such as not declaring variables, are flagged and have no impact on
performance. However, these suboptions do have an impact on performance.
IBM/ANS
When you use the RULES(IBM) option, the compiler supports scaled FIXED
BINARY and, what is more important for performance, generates scaled FIXED
BINARY results in some operations. Under RULES(ANS), scaled FIXED BINARY
is not supported and scaled FIXED BINARY results are never generated. This
means that the code generated under RULES(ANS) always runs at least as fast as
the code generated under RULES(IBM), and sometimes runs faster.
For example, consider the following code fragment:

dcl (i,j,k) fixed bin(15);
..
.
i = j / k;
Under RULES(IBM), the result of the division has the attributes FIXED BIN(31,16).
This means that a shift instruction is required before the division and several more
instructions are needed to perform the assignment.
Under RULES(ANS), the result of the division has the attributes FIXED BIN(15,0).
This means that a shift is not needed before the division, and no extra instructions
are needed to perform the assignment.
Chapter 11. Improving performance 231

(NO)LAXCTL
Under RULES(LAXCTL), a CONTROLLED variable may be declared with constant
extents and yet allocated with different extents.
For instance, under RULES(LAXCTL), you may declare a structure as follows:

dcl
1 a controlled,
2 b char(17),
2 c char(29);
However, you could then allocate it as follows:

allocate
1 a,
2 b char(17K),
2 c char(29K);
This has disastrous consequences for performance because it means that

whenever the compiler sees a reference to the structure A or to any member of that
structure, the compiler is forced to assume that it knows nothing about the lengths,
dimensions or offsets of the fields in it.
However, the RULES(NOLAXCTL) option disallows this coding practice: under

RULES(NOLAXCTL), if you then want to allocate a CONTROLLED variable with a
variable extent, then that extents must be declared either with an asterisk or with a
non-constant expression. Consequently, under RULES(NOLAXCTL), when a
CONTROLLED variable is declared with constant extents, then the compiler can
generate much better code for any reference to that variable.
PREFIX
This option determines if selected PL/I conditions are enabled by default. The
default suboptions for PREFIX are set to conform to the PL/I language definition;
however, overriding the defaults can have a significant effect on the performance of
your program. The default suboptions are:
CONVERSION
INVALIDOP
FIXEDOVERFLOW
OVERFLOW
INVALIDOP
NOSIZE
NOSTRINGRANGE
NOSTRINGSIZE
NOSUBSCRIPTRANGE
UNDERFLOW
ZERODIVIDE
By specifying the SIZE, STRINGRANGE, STRINGSIZE, or SUBSCRIPTRANGE

suboptions, the compiler generates extra code that helps you pinpoint various
problem areas in your source that would otherwise be hard to find. This extra
code, however, can slow program performance significantly.

CONVERSION
When you disable the CONVERSION condition, some character-to-numeric
conversions are done inline and without checking the validity of the source;
therefore, specifying NOCONVERSION also affects program performance.
FIXEDOVERFLOW
On some platforms, the FIXEDOVERFLOW condition is raised by the hardware and
the compiler does not need to generate any extra code to detect it.
DEFAULT
Using the DEFAULT option, you can select attribute defaults. As is true with the
PREFIX option, the suboptions for DEFAULT are set to conform to the PL/I
language definition. Changing the defaults in some instances can affect
performance.
Some of the suboptions, such IBM/ANS and ASSIGNABLE/NONASSIGNABLE,

have no effect on program performance. But other suboptions can affect
performance to varying degrees and, if applied inappropriately, can make your
program invalid. The more important of these suboptions are:
BYADDR or BYVALUE
When the DEFAULT(BYADDR) option is in effect, arguments are passed by
reference (as required by PL/I) unless an attribute in an entry declaration indicates
otherwise. As arguments are passed by reference, the address of the argument is
passed from one routine (calling routine) to another (called routine) as the variable
itself is passed. Any change made to the argument while in the called routine is
reflected in the calling routine when it resumes execution.
Program logic often depends on passing variables by reference. Passing a variable

by reference, however, can hinder performance in two ways:
1. Every reference to that parameter requires an extra instruction.
2. Since the address of the variable is passed to another routine, the compiler is
forced to make assumptions about when that variable might change and
generate very conservative code for any reference to that variable.
Consequently, you should pass parameters by value using the BYVALUE suboption
whenever your program logic allows. Even if you use the BYADDR attribute to
indicate that one parameter should be passed by reference, you can use the
DEFAULT(BYVALUE) option to ensure that all other parameters are passed by
value.
If a procedure receives and modifies only one parameter that is passed by

BYADDR, consider converting the procedure to a function that receives that
parameter by value. The function would then end with a RETURN statement
containing the updated value of the parameter.
Procedure with BYADDR parameter

a: proc( parm1, parm2, ..., parmN );
dcl parm1 byaddr ...;

dcl parm2 byvalue ...;
..
.
dcl parmN byvalue ...;
/] program logic ]/
end;
Faster, equivalent function with BYVALUE parameter

a: proc( parm1, parm2, ..., parmN )
returns( ... /] attributes of parm1 ]/ );

..
.
dcl parmN byvalue ...;
/] program logic ]/
return( parm1 );
end;
(NON)CONNECTED
The DEFAULT(NONCONNECTED) option indicates that the compiler assumes that
any aggregate parameters are NONCONNECTED. References to elements of
NONCONNECTED aggregate parameters require the compiler to generate code to
access the parameter's descriptor, even if the aggregate is declared with constant
extents.
The compiler does not generate these instructions if the aggregate parameter has
constant extents and is CONNECTED. Consequently, if your application never
passes nonconnected parameters, your code is more optimal if you use the
DEFAULT(CONNECTED) option.
(NO)DESCRIPTOR
The DEFAULT(DESCRIPTOR) option indicates that, by default, a descriptor is
passed for any string, area, or aggregate parameter; however, the descriptor is
used only if the parameter has nonconstant extents or if the parameter is an array
with the NONCONNECTED attribute. In this case, the instructions and space
required to pass the descriptor provide no benefit and incur substantial cost (the
size of a structure descriptor is often greater than size of the structure itself).
Consequently, by specifying DEFAULT(NODESCRIPTOR) and using
OPTIONS(DESCRIPTOR) only as needed on PROCEDURE statements and
ENTRY declarations, your code runs more optimally.

(NO)INLINE
The suboption NOINLINE indicates that procedures and begin blocks should not be
inlined.
Inlining occurs only when you specify optimization.
Inlining user code eliminates the overhead of the function call and linkage, and also
exposes the function's code to the optimizer, resulting in faster code performance.
Inlining produces the best results when the overhead for the function is nontrivial,
for example, when functions are called within nested loops. Inlining is also
beneficial when the inlined function provides additional opportunities for
optimization, such as when constant arguments are used.
For programs containing many procedures that are not nested:

If the procedures are small and only called from a few places, you can increase
performance by specifying INLINE.
If the procedures are large and called from several places, inlining duplicates
code throughout the program. This increase in the size of the program might
offset any increase of speed. In this case, you might prefer to leave NOINLINE
as the default and specify OPTIONS(INLINE) only on individually selected
procedures.
When you use inlining, you need more stack space. When a function is called, its
local storage is allocated at the time of the call and freed when it returns to the
calling function. If that same function is inlined, its storage is allocated when the
function that calls it is entered, and is not freed until that calling function ends.
Ensure that you have enough stack space for the local storage of the inlined
functions.
LINKAGE
This suboption tells the compiler the default linkage to use when the LINKAGE
suboption of the OPTIONS attribute or option for an entry has not been specified.
The compiler supports various linkages, each with its unique performance
characteristics. When you invoke an ENTRY provided by an external entity (such
as an operating system), you must use the linkage previously defined for that
ENTRY.
As you create your own applications, however, you can choose the linkage
convention. The OPTLINK linkage is strongly recommended because it provides
significantly better performance than other linkage conventions.
(RE)ORDER
The DEFAULT(ORDER) option indicates that the ORDER option is applied to every
block, meaning that variables in that block referenced in ON-units (or blocks
dynamically descendant from ON-units) have their latest values. This effectively
prohibits almost all optimization on such variables. Consequently, if your program
logic allows, use DEFAULT(REORDER) to generate superior code.

Coding for better performance
NOOVERLAP
The DEFAULT(NOOVERALP) option lets the compiler assume that the source and
target in an assignment do not overlap, and it can therefore generate smaller and
faster code.
However, if you this option, you must insure that the source and target in
assignment do not overlap. For example, under the DEFAULT( NOOVERLAP )
option, the assignment in this example would be invalid:
dcl c char(2K);
substr(c,2,5) = substr(c,1,5);
RETURNS(BYVALUE) or RETURNS(BYADDR)
When the DEFAULT(RETURNS(BYVALUE)) option is in effect, the BYVALUE
attribute is applied to all RETURNS description lists that do not specify BYADDR.
This means that these functions return values in registers, when possible, in order
to produce the most optimal code.
Summary of compiler options that improve performance

In summary, the following options (if appropriate for your application) can improve
performance:
OPTIMIZE(2)
ARCH(4)
REDUCE
RULES(ANS NOLAXCTL)
DEFAULT with the following suboptions
BYVALUE
CONNECTED
NODESCRIPTOR
INLINE
LINKAGE(OPTLINK)
REORDER
NOOVERLAP
RETURNS(BYVALUE)

As you write code, there is generally more than one correct way to accomplish a
given task. Many important factors influence the coding style you choose, including
readability and maintainability. The following sections discuss choices that you can
make while coding that potentially affect the performance of your program.
DATA-directed input and output

Using GET DATA and PUT DATA statements for debugging can prove very helpful.
When you use these statements, however, you generally pay the price of
decreased performance. This cost to performance is usually very high when you
use either GET DATA or PUT DATA without a variable list.
Many programmers use PUT DATA statements in their ON ERROR code as

illustrated in the following example:

on error
begin;
on error system;
..
.
put data;
..
.
end;
In this case, the program would perform more optimally by including a list of
selected variables with the PUT DATA statement.
The ON ERROR block in the previous example contained an ON ERROR system

statement before the PUT DATA statement. This prevents the program from
getting caught in an infinite loop if an error occurs in the PUT DATA statement
(which could occur if any variables to be listed contained invalid FIXED DECIMAL
values) or elsewhere in the ON ERROR block.
Input-only parameters
If a procedure has a BYADDR parameter which it uses as input only, it is best to
declare that parameter as NONASSIGNABLE (rather than letting it get the default
attribute of ASSIGNABLE). If that procedure is later called with a constant for that
parameter, the compiler can put that constant in static storage and pass the
address of that static area.
This practice is particularly useful for strings and other parameters that cannot be
passed in registers (input-only parameters that can be passed in registers are best
declared as BYVALUE).
In the following declaration, for instance, the first parameter to getenv is an

input-only CHAR VARYINGZ string:
dcl getenv entry( char(]) varyingz nonasgn byaddr,
pointer byaddr )
returns( native fixed bin(31) optional )
options( nodescriptor );
If this function is invoked with the string 'IBM_OPTIONS', the compiler can pass the
address of that string rather than assigning it to a compiler-generated temporary
storage area and passing the address of that area.
GOTO statements
A GOTO statement that uses either a label in another block or a label variable
severely limits optimizations that the compiler might perform. If a label array is
initialized and declared AUTOMATIC, either implicitly or explicitly, any GOTO to an
element of that array will hinder optimization. However, if the array is declared as
STATIC, the compiler assumes the CONSTANT attribute for it and no optimization
is hindered.
String assignments
When one string is assigned to another, the compiler ensures that:
The target has the correct value even if the source and target overlap.
The source string is truncated if it is longer than the target.

This assurance comes at the price of some extra instructions. The compiler
attempts to generate these extra instructions only when necessary, but often you,
as the programmer, know they are not necessary when the compiler cannot be
sure. For instance, if the source and target are based character strings and you
know they cannot overlap, you could use the PLIMOVE built-in function to eliminate
the extra code the compiler would otherwise be forced to generate.
In the example which follows, faster code is generated for the second assignment
statement:
dcl based_Str char(64) based( null() );
dcl target_Addr pointer;
dcl source_Addr pointer;
target_Addr->based_Str = source_Addr->based_Str;
call plimove( target_Addr, source_Addr, stg(based_Str) );
If you have any doubts about whether the source and target might overlap or
whether the target is big enough to hold the source, you should not use the
PLIMOVE built-in.
Loop control variables

Program performance improves if your loop control variables are one of the types in
the following list. You should rarely, if ever, use other types of variables.
FIXED BINARY with zero scale factor
FLOAT
ORDINAL
HANDLE
POINTER
OFFSET
Performance also improves if loop control variables are not members of arrays,
structures, or unions. The compiler issues a warning message when they are.
Loop control variables that are AUTOMATIC and not used for any other purpose
give you the optimal code generation.
If a loop control variable is a FIXED BIN, performance is best if it has precision 31

and is SIGNED.
Performance is decreased if your program depends not only on the value of a loop
control variable, but also on its address. For example, if the ADDR built-in function
is applied to the variable or if the variable is passed BYADDR to another routine.
PACKAGEs versus nested PROCEDUREs

Calling nested procedures requires that an extra hidden parameter (the backchain
pointer) is passed. As a result, the fewer nested procedures that your application
contains, the faster it runs.
To improve the performance of your application, you can convert a mother-daughter

pair of nested procedures into level-1 sister procedures inside of a package. This
conversion is possible if your nested procedure does not rely on any of the
automatic and internal static variables declared in its parent procedures.

If procedure b in “Example with nested procedures” does not use any of the
variables declared in a, you can improve the performance of both procedures by
reorganizing them into the package illustrated in “Example with packaged
procedures.”
Example with nested procedures

a: proc;
dcl (i,j,k) fixed bin;

dcl ib based fixed bin;
..
.
call b( addr(i) );
..
.
b: proc( px );
dcl px pointer;
display( px->ib );
end;
end;
Example with packaged procedures

p: package exports( a );
dcl ib based fixed bin;
a: proc;
dcl (i,j,k) fixed bin;

..
.
call b( addr(i) );
..
.
end;
b: proc( px );
dcl px pointer;
display( px->ib );
end;
end p;
REDUCIBLE Functions
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.
In the following example, f is invoked only once since REDUCIBLE is part of the
declaration. If IRREDUCIBLE had been used in the declaration, f would be invoked
twice.

dcl (f) entry options( reducible ) returns( fixed bin );
select;
when( f(x) < K )
..
.
when( f(x) > K )
..
.
otherwise
..
.
end;
DESCLOCATOR or DESCLIST
When the DEFAULT(DESCLOCATOR) option is in effect, the compiler passes
arguments requiring descriptors (such as strings and structures) via a descriptor
locator in much the same way that the old compiler did. More information on
descriptors and how they are passed is available in Chapter 20, “PL/I - Language
Environment descriptors” on page 357.
This option allows you to invoke an entry point that is not always passed all of the
arguments that it declares.
This option also allows you to continue the somewhat unwise programming practice
of passing a structure and receiving it as a pointer.
However, the code generated by the compiler for DEFAULT(DESCLOCATOR) may,

in some situations, perform less well than that for DEFAULT(DESCLIST).
DEFINED versus UNION

The UNION attribute is more powerful than the DEFINED attribute and provides
more function. In addition, the compiler generates better code for union references.
In the following example, the pair of variables b3 and b4 perform the same function
as b1 and b2, but the compiler generates more optimal code for the pair in the
union.
dcl b1 bit(31);
dcl b2 bit(16) def b1;
dcl
1 ] union,
2 b3 bit(32),
2 b4 bit(16);
Code that uses UNIONs instead of the DEFINED attribute is subject to less
misinterpretation. Variable declarations in unions are in a single location making it
easy to realize that when one member of the union changes, all of the others
change also. This dynamic change is less obvious in declarations that use
DEFINED variables since the declare statements can be several lines apart.

Named constants versus static variables

You can define named constants by declaring a variable with the VALUE attribute.
If you use static variables with the INITIAL attribute and you do not alter the
variable, you should declare the variable a named constant using the VALUE
attribute. The compiler does not treat NONASSIGNABLE scalar STATIC variables
as true named constants.
The compiler generates better code whenever expressions are evaluated during
compilation, so you can use named constants to produce efficient code with no loss
in readability. For example, identical object code is produced for the two usages of
the VERIFY built-in function in the following example:
dcl numeric char value('K123456789');
jx = verify( string, numeric );
jx = verify( string, 'K123456789' );
The following examples illustrate how you can use the VALUE attribute to get
optimal code without sacrificing readability.
Example with optimal code but no meaningful names

dcl x bit(8) aligned;
select( x );
when( 'K1'b4 )
..
.
when( 'K2'b4 )
..
.
when( 'K3'b4 )
..
.
end;
Example with meaningful names but not optimal code

dcl ( a1 init( 'K1'b4)
,a2 init( 'K2'b4)
,a3 init( 'K3'b4)
,a4 init( 'K4'b4)
,a5 init( 'K5'b4)
) bit(8) aligned static nonassignable;
select( x );
when( a1 )
..
.
when( a2 )
..
.
when( a3 )
..
.
end;
Example with optimal code AND meaningful names

dcl ( a1 value( 'K1'b4)

,a2 value( 'K2'b4)
,a3 value( 'K3'b4)
,a4 value( 'K4'b4)
,a5 value( 'K5'b4)
) bit(8);
select( x );
when( a1 )
..
.
when( a2 )
..
.
when( a3 )
..
.
end;
Avoiding calls to library routines

The bitwise operations (prefix NOT, infix AND, infix OR, and infix EXCLUSIVE OR)
are often evaluated by calls to library routines. These operations are, however,
handled without a library call if either of the following conditions is true:
Both operands are bit(1)
Both operands are aligned and have the same constant length.
For certain assignments, expressions, and built-in function references, the compiler
generates calls to library routines. If you avoid these calls, your code generally
runs faster.
To help you determine when the compiler generates such calls, the compiler
generates a message whenever a conversion is done using a library routine.

Part 5. Using interfaces to other products
Chapter 12. Using the Sort program . . . . . . . . . . . . . . . . . . . . . . . 245
Preparing to use Sort . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 245
Choosing the type of Sort . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 246
Specifying the sorting field . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 248
Specifying the records to be sorted . . . . . . . . . . . . . . . . . . . . . . . . 250
Maximum record lengths . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 250
Determining storage needed for Sort . . . . . . . . . . . . . . . . . . . . . . . 251
Main storage . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 251
Auxiliary storage . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 251
Calling the Sort program . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 251
Example 1 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 253
Example 2 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 253
Example 3 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 253
Example 4 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 253
Example 5 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 253
Determining whether the Sort was successful . . . . . . . . . . . . . . . . . . 254
Establishing data sets for Sort . . . . . . . . . . . . . . . . . . . . . . . . . . . 254
Sort work data sets . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 254
Input data set . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 255
Output data set . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 255
Checkpoint data set . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 255
Sort data input and output . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 256
Data input and output handling routines . . . . . . . . . . . . . . . . . . . . . . . 256
E15—Input handling routine (Sort Exit E15) . . . . . . . . . . . . . . . . . . . 256
E35—Output handling routine (Sort Exit E35) . . . . . . . . . . . . . . . . . . 259
Calling PLISRTA example . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 260
Calling PLISRTB example . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 260
Calling PLISRTC example . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 262
Calling PLISRTD example . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 263
Sorting variable-length records example . . . . . . . . . . . . . . . . . . . . . 264
Chapter 13. ILC with C . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 266

Equivalent data types . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 266
Simple type equivalence . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 266
Struct type equivalence . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 267
Enum type equivalence . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 267
File type equivalence . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 268
Using C functions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 268
Matching simple parameter types . . . . . . . . . . . . . . . . . . . . . . . . . 269
Matching string parameter types . . . . . . . . . . . . . . . . . . . . . . . . . . 271
Functions returning ENTRYs . . . . . . . . . . . . . . . . . . . . . . . . . . . . 272
Linkages . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 273
Summary . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 275
Chapter 14. Interfacing with Java . . . . . . . . . . . . . . . . . . . . . . . . . 276

What is the Java Native Interface (JNI)? . . . . . . . . . . . . . . . . . . . . . . . 276
JNI Sample Program #1 - "Hello World" . . . . . . . . . . . . . . . . . . . . . . . 277
Declare the Native Method . . . . . . . . . . . . . . . . . . . . . . . . . . . 277

Load the Native Library . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 277
Write the Java Main Method . . . . . . . . . . . . . . . . . . . . . . . . . . . 278
Useful PL/I Compiler Options . . . . . . . . . . . . . . . . . . . . . . . . . . 278
Correct Form of PL/I Procedure Name and Procedure Statement . . . . . 279
JNI Include File . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 279
The Complete PL/I Procedure . . . . . . . . . . . . . . . . . . . . . . . . . . 280
Compiling the PL/I Program . . . . . . . . . . . . . . . . . . . . . . . . . . . 280
Linking the Shared Library . . . . . . . . . . . . . . . . . . . . . . . . . . . . 280
JNI Sample Program #2 - Passing a String . . . . . . . . . . . . . . . . . . . . . 281
JNI Include File . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 283
JNI Sample Program #3 - Passing an Integer . . . . . . . . . . . . . . . . . . . . 285
JNI Include File . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 288
Determining equivalent Java and PL/I data types . . . . . . . . . . . . . . . . 290
Full contents of jni_md.inc include file . . . . . . . . . . . . . . . . . . . . . . . . 291
Full contents of jni.inc include file . . . . . . . . . . . . . . . . . . . . . . . . . . . 292

Chapter 12. Using the Sort program
The compiler provides an interface called PLISRTx (x = A, B, C, or D) that allows
you to make use of the IBM-supplied Sort programs.
To use the Sort program with PLISRTx, you must:

1. Include a call to one of the entry points of PLISRTx, passing it the information
on the fields to be sorted. This information includes the length of the records,
the maximum amount of storage to use, the name of a variable to be used as a
return code, and other information required to carry out the sort.
2. Specify the data sets required by the Sort program in JCL DD statements.
When used from PL/I, the Sort program sorts records of all normal lengths on a
large number of sorting fields. Data of most types can be sorted into ascending or
descending order. The source of the data to be sorted can be either a data set or
a user-written PL/I procedure that the Sort program will call each time a record is
required for the sort. Similarly, the destination of the sort can be a data set or a
PL/I procedure that handles the sorted records.
Using PL/I procedures allows processing to be done before or after the sort itself,
thus allowing a complete sorting operation to be handled completely by a call to the
sort interface. It is important to understand that the PL/I procedures handling input
or output are called from the Sort program itself and will effectively become part of
it.
PL/I can operate with DFSORT or a program with the same interface. DFSORT
is a release of the program product 5740-SM1. DFSORT has many built-in
features you can use to eliminate the need for writing program logic (for example,
INCLUDE, OMIT, OUTREC and SUM statement plus the many ICETOOL
operators). See DFSORT Application Programming Guide for details and Getting
Started with DFSORT for a tutorial.
The following material applies to DFSORT. Because you can use programs other
than DFSORT, the actual capabilities and restrictions vary. For these capabilities
and restrictions, see DFSORT Application Programming Guide, or the equivalent
publication for your sort product.
To use the Sort program you must include the correct PL/I statements in your
source program and specify the correct data sets in your JCL.
Preparing to use Sort

Before using Sort, you must determine the type of sort you require, the length and
format of the sorting fields in the data, the length of your data records, and the
amount of auxiliary and main storage you will allow for sorting.
To determine the PLISRTx entry point that you will use, you must decide the
source of your unsorted data, and the destination of your sorted data. You must
choose between data sets and PL/I subroutines. Using data sets is simpler to
understand and gives faster performance. Using PL/I subroutines gives you more
flexibility and more function, enabling you to manipulate or print the data before it is
sorted, and to make immediate use of it in its sorted form. If you decide to use an

input or output handling subroutine, you will need to read “Data input and output
handling routines” on page 256.
The entry points and the source and destination of data are as follows:
Entry point Source Destination

PLISRTA Data set Data set
PLISRTB Subroutine Data set
PLISRTC Data set Subroutine
PLISRTD Subroutine Subroutine
Having determined the entry point you are using, you must now determine the
following things about your data set:
The position of the sorting fields; these can be either the complete record or
any part or parts of it
The type of data these fields represent, for example, character or binary
Whether you want the sort on each field to be in ascending or descending
order
Whether you want equal records to be retained in the order of the input, or
whether their order can be altered during sorting
Specify these options on the SORT statement, which is the first argument to
PLISRTx. After you have determined these, you must determine two things about
the records to be sorted:
Whether the record format is fixed or varying
The length of the record, which is the maximum length for varying
Specify these on the RECORD statement, which is the second argument to

PLISRTx.
Finally, you must decide on the amount of main and auxiliary storage you will allow
for the Sort program. For further details, see “Determining storage needed for Sort”
on page 251.
Choosing the type of Sort

If you want to make the best use of the Sort program, you must understand
something of how it works. In your PL/I program you specify a sort by using a
CALL statement to the sort interface subroutine PLISRTx. This subroutine has four
entry points: x=A, B, C, and D. Each specifies a different source for the unsorted
data and destination for the data when it has been sorted. For example, a call to
PLISRTA specifies that the unsorted data (the input to sort) is on a data set, and
that the sorted data (the output from sort) is to be placed on another data set. The
CALL PLISRTx statement must contain an argument list giving the Sort program
information about the data set to be sorted, the fields on which it is to be sorted,
the amount of space available, the name of a variable into which Sort will place a
return code indicating the success or failure of the sort, and the name of any output
or input handling procedure that can be used.
The sort interface routine builds an argument list for the Sort program from the
information supplied by the PLISRTx argument list and the choice of PLISRTx entry

point. Control is then transferred to the Sort program. If you have specified an
output- or input-handling routine, this will be called by the Sort program as many
times as is necessary to handle each of the unsorted or sorted records. When the
sort operation is complete, the Sort program returns to the PL/I calling procedure
communicating its success or failure in a return code, which is placed in one of the
arguments passed to the interface routine. The return code can then be tested in
the PL/I routine to discover whether processing should continue. Figure 47 is a
simplified flowchart showing this operation.
┌──────────────┐
│ │
│ CALL PLISRTx │
│ │
└──┬──┬──┬──┬──┘
│ │ │ │
┌────────────────────────────┘ │ │ └────────────────────────────┐
│ ┌─────────┘ └─────────┐ │

PLISRTA PLISRTB PLISRTC PLISRTD
│ │ │ │

┌───────────┴─────────────────────┴──────────────────────┴─────────────────────┴───────────┐
│ SORT PROGRAM │
├───────────┬─────────────────────┬──────────────────────┬─────────────────────┬───────────┤
│ │
│ ┌─────────┴────────┐ ┌─────────┴─────────┐ ┌─────────┴────────┐ ┌─────────┴─────────┐ │
│ │ Get records from │ │ Call PL/I sub─ │ │ Get records from │ │ Call PL/I sub─ │ │
│ │ data set till │ │ routine receiving │ │ data set till │ │ routine receiving
│ │ end of file │ │ one record on │ │ end of file │ │ one record on │ │
│ │ │ │ each call │ │ │ │ each call │ │
│ └─────────┬────────┘ └─────────┬─────────┘ └─────────┬────────┘ └─────────┬─────────┘ │
│ │ │ │ │ │
│ │ └─────────┐ ┌─────────┘ │ │
│ └────────────────────────────┐ │ │ ┌────────────────────────────┘ │
│ │ │ │ │ │
│ │
│ ┌──┴──┴──┴──┴──┐ │
│ │ │ │
│ │ Sort records │ │
│ │ │ │
│ └──┬──┬──┬──┬──┘ │
│ │ │ │ │ │
│ ┌────────────────────────────┘ │ │ └────────────────────────────┐ │
│ │ ┌─────────┘ └─────────┐ │ │
│ │ │ │ │ │
│ │
│ ┌─────────┴────────┐ ┌─────────┴─────────┐ ┌─────────┴────────┐ ┌─────────┴─────────┐ │
│ │ Place sorted │ │ Place sorted │ │ Call PL/I sub─ │ │ Call PL/I sub─ │ │
│ │ records on │ │ records on │ │ routine passing │ │ routine passing │ │
│ │ data set │ │ data set │ │ one record on │ │ one record on │ │
│ │ │ │ │ │ each call │ │ each call │ │
│ └─────────┬────────┘ └─────────┬─────────┘ └─────────┬────────┘ └─────────┬─────────┘ │
│ │ │ │ │ │
│ │ └─────────┐ ┌─────────┘ │ │
│ └────────────────────────────┐ │ │ ┌────────────────────────────┘ │
│ │ │ │ │ │
│ │
│ ┌──────┴──┴──┴──┴──────┐ │
│ │ Set up return code │ │
│ │ to indicate success │ │
│ │ or failure of sort │ │
│ └──────────┬───────────┘ │
│ │ │
└────────────────────────────────────────────┼─────────────────────────────────────────────┘
│

┌───────┴───────┐
│ Continue with │
│ PL/I program │
└───────────────┘
Figure 47. Flow of control for Sort program
Chapter 12. Using the Sort program 247

Within the Sort program itself, the flow of control between the Sort program and
input- and output-handling routines is controlled by return codes. The Sort program
calls these routines at the appropriate point in its processing. (Within the Sort
program, and its associated documentation, these routines are known as user exits.
The routine that passes input to be sorted is the E15 sort user exit. The routine
that processes sorted output is the E35 sort user exit.) From the routines, Sort
expects a return code indicating either that it should call the routine again, or that it
should continue with the next stage of processing.
The important points to remember about Sort are: (1) it is a self-contained program
that handles the complete sort operation, and (2) it communicates with the caller,
and with the user exits that it calls, by means of return codes.
The remainder of this chapter gives detailed information on how to use Sort from
PL/I. First the required PL/I statements are described, and then the data set
requirements. The chapter finishes with a series of examples showing the use of
the four entry points of the sort interface routine.
Specifying the sorting field

The SORT statement is the first argument to PLISRTx. The syntax of the SORT
statement must be a character string expression that takes the form:
'bSORTbFIELDS=(start1,length1,form1,seq1,
...startn,lengthn,formn,seqn)[,other options]b'
For example:
' SORT FIELDS=(1,1K,CH,A) '
b represents one or more blanks. Blanks shown are mandatory. No other blanks
are allowed.
start,length,form,seq
defines a sorting field. You can specify any number of sorting fields, but there
is a limit on the total length of the fields. If more than one field is to be sorted
on, the records are sorted first according to the first field, and then those that
are of equal value are sorted according to the second field, and so on. If all
the sorting values are equal, the order of equal records will be arbitrary unless
you use the EQUALS option. (See later in this definition list.) Fields can
overlay each other.
For DFSORT (5740-SM1), the maximum total length of the sorting fields is
restricted to 4092 bytes and all sorting fields must be within 4092 bytes of the
start of the record. Other sort products might have different restrictions.
start is the starting position within the record. Give the value in bytes except
for binary data where you can use a “byte.bit” notation. The first byte in
a string is considered to be byte 1, the first bit is bit 0. (Thus the
second bit in byte 2 is referred to as 2.1.) For varying length records
you must include the 4-byte length prefix, making 5 the first byte of
data.
length is the length of the sorting field. Give the value in bytes except for
binary where you can use “byte.bit” notation. The length of sorting
fields is restricted according to their data type.

form is the format of the data. This is the format assumed for the purpose of
sorting. All data passed between PL/I routines and Sort must be in the
form of character strings. The main data types and the restrictions on
their length are shown below. Additional data types are available for
special-purpose sorts. See the DFSORT Application Programming
Guide, or the equivalent publication for your sort product.
Code Data type and length
CH character 1–4096
ZD zoned decimal, signed 1–32
PD packed decimal, signed 1–32
FI fixed point, signed 1–256
BI binary, unsigned 1 bit to 4092 bytes
FL floating-point, signed 1–256
The sum of the lengths of all fields must not exceed 4092 bytes.
seq is the sequence in which the data will be sorted as follows:
A ascending (that is, 1,2,3,...)
D descending (that is, ...,3,2,1)
Note: You cannot specify E, because PL/I does not provide a method
of passing a user-supplied sequence.
other options
You can specify a number of other options, depending on your Sort program.
You must separate them from the FIELDS operand and from each other by
commas. Do not place blanks between operands.
FILSZ=y
specifies the number of records in the sort and allows for optimization by
Sort. If y is only approximate, E should precede y.
SKIPREC=y
specifies that y records at the start of the input file are to be ignored before
sorting the remaining records.
CKPT or CHKPT
specifies that checkpoints are to be taken. If you use this option, you must
provide a SORTCKPT data set and DFSORT's 16NCKPT=NO installation
option must be specified.
EQUALS|NOEQUALS
specifies whether the order of equal records will be preserved as it was in
the input (EQUALS) or will be arbitrary (NOEQUALS). You could improve
sort performance by using the NOEQUALS. The default option is chosen
when Sort is installed. The IBM-supplied default is NOEQUALS.
DYNALLOC=(d,n)
(OS/VS Sort only) specifies that the program dynamically allocates
intermediate storage.
d is the device type (3380, etc.).

n is the number of work areas.

Specifying the records to be sorted
Use the RECORD statement as the second argument to PLISRTx. The syntax of
the RECORD statement must be a character string expression which, when
evaluated, takes the syntax shown below:
'bRECORDbTYPE=rectype[,LENGTH=(L1,[,,L4,L5])]b'
For example:
' RECORD TYPE=F,LENGTH=(8K) '
b represents one or more blanks. Blanks shown are mandatory. No other blanks
are allowed.
TYPE
specifies the type of record as follows:
F fixed length
V varying length EBCDIC
D varying length ASCII
Even when you use input and output routines to handle the unsorted and
sorted data, you must specify the record type as it applies to the work data sets
used by Sort.
If varying length strings are passed to Sort from an input routine (E15 exit), you
should normally specify V as a record format. However, if you specify F, the
records are padded to the maximum length with blanks.
LENGTH
specifies the length of the record to be sorted. You can omit LENGTH if you
use PLISRTA or PLISRTC, because the length will be taken from the input data
set. Note that there is a restriction on the maximum and minimum length of the
record that can be sorted (see below). For varying length records, you must
include the four-byte prefix.
11 is the length of the record to be sorted. For VSAM data sets sorted as
varying records it is the maximum record size+4.
,, represent two arguments that are not applicable to Sort when called from
PL/I. You must include the commas if the arguments that follow are
used.
14 specifies the minimum length of record when varying length records are
used. If supplied, it is used by Sort for optimization purposes.
15 specifies the modal (most common) length of record when varying length
records are used. If supplied, it is used by Sort for optimization
purposes.
Maximum record lengths

The length of a record can never exceed the maximum length specified by the
user. The maximum record length for variable length records is 32756 bytes and
for fixed length records it is 32760 bytes.

Determining storage needed for Sort
Main storage
Sort requires both main and auxiliary storage. The minimum main storage for
DFSORT is 88K bytes, but for best performance, more storage (on the order of 1
megabyte or more) is recommended. DFSORT can take advantage of storage
above 16M virtual or extended architecture processors. Under OS/390, DFSORT
can also take advantage of expanded storage. You can specify that Sort use the
maximum amount of storage available by passing a storage parameter in the
following manner:
DCL MAXSTOR FIXED BINARY (31,K);
UNSPEC(MAXSTOR)='KKKKKKKK'B||UNSPEC('MAX');
CALL PLISRTA
(' SORT FIELDS=(1,8K,CH,A) ',
' RECORD TYPE=F,LENGTH=(8K) ',
MAXSTOR,
RETCODE,
'TASK');
If files are opened in E15 or E35 exit routines, enough residual storage should be
allowed for the files to open successfully.
Auxiliary storage
Calculating the minimum auxiliary storage for a particular sorting operation is a
complicated task. To achieve maximum efficiency with auxiliary storage, use direct
access storage devices (DASDs) whenever possible. For more information on
improving program efficiency, see the DFSORT Application Programming Guide,
particularly the information about dynamic allocation of workspace which allows
DFSORT to determine the auxiliary storage needed and allocate it for you.
If you are interested only in providing enough storage to ensure that the sort will
work, make the total size of the SORTWK data sets large enough to hold three sets
of the records being sorted. (You will not gain any advantage by specifying more
than three if you have enough space in three data sets.)
However, because this suggestion is an approximation, it might not work, so you

should check the sort manuals. If this suggestion does work, you will probably
have wasted space.
Calling the Sort program

When you have determined the points described above, you are in a position to
write the CALL PLISRTx statement. You should do this with some care; for the
entry points and arguments to use, see Table 28.
Table 28 (Page 1 of 2). The entry points and arguments to PLISRTx (x = A, B, C, or D)

Entry points Arguments
PLISRTA (sort statement,record statement,storage,return code
Sort input: data set [,data set prefix,message level, sort technique])
Sort output: data set
PLISRTB (sort statement,record statement,storage,return code,input routine
Sort input: PL/I subroutine [,data set prefix,message level,sort technique])
Sort output: data set

Table 28 (Page 2 of 2). The entry points and arguments to PLISRTx (x = A, B, C, or D)
Entry points Arguments
PLISRTC (sort statement,record statement,storage,return code,output routine
Sort input: data set [,data set prefix,message level,sort technique])
Sort output: PL/I subroutine
PLISRTD (sort statement,record statement,storage,return code,input routine,output routine[,data set
Sort input: PL/I subroutine prefix,message level,sort technique])
Sort output: PL/I subroutine
Sort statement Character string expression containing the Sort program SORT statement. Describes
sorting fields and format. See “Specifying the sorting field” on page 248.
Record statement Character string expression containing the Sort program RECORD statement. Describes
the length and record format of data. See “Specifying the records to be sorted” on
page 250.
Storage Fixed binary expression giving maximum amount of main storage to be used by the Sort
program. Must be >88K bytes for DFSORT. See also “Determining storage needed for
Sort.”
Return code Fixed binary variable of precision (31,0) in which Sort places a return code when it has
completed. The meaning of the return code is:
0=Sort successful
16=Sort failed
20=Sort message data set missing
Input routine (PLISRTB and PLISRTD only.) Name of the PL/I external or internal procedure used to
supply the records for the Sort program at sort exit E15.
Output routine (PLISRTC and PLISRTD only.) Name of the PL/I external or internal procedure to which
Sort passes the sorted records at sort exit E35.
Data set prefix Character string expression of four characters that replaces the default prefix of 'SORT' in
the names of the sort data sets SORTIN, SORTOUT, SORTWKnn and SORTCNTL, if
used. Thus if the argument is “TASK”, the data sets TASKIN, TASKOUT, TASKWKnn, and
TASKCNTL can be used. This facility enables multiple invocations of Sort to be made in
the same job step. The four characters must start with an alphabetic character and must
not be one of the reserved names PEER, BALN, CRCX, OSCL, POLY, DIAG, SYSC, or
LIST. You must code a null string for this argument if you require either of the following
arguments but do not require this argument.
Message level Character string expression of two characters indicating how Sort's diagnostic messages
are to be handled, as follows:
NO No messages to SYSOUT
AP All messages to SYSOUT
CP Critical messages to SYSOUT
SYSOUT will normally be allocated to the printer, hence the use of the mnemonic letter “P”.
Other codes are also allowed for certain of the Sort programs. For further details on these
codes, see DFSORT Application Programming Guide. You must code a null string for this
argument if you require the following argument but you do not require this argument.
Sort technique (This is not used by DFSORT; it appears for compatibility reasons only.) Character string
of length 4 that indicates the type of sort to be carried out, as follows:
PEER Peerage sort
BALN Balanced
CRCX Criss-cross sort
OSCL Oscillating
POLY Polyphase sort
Normally the Sort program will analyze the amount of space available and choose the most
effective technique without any action from you. You should use this argument only as a
bypass for sorting problems or when you are certain that performance could be improved
by another technique. See DFSORT Application Programming Guide for further
information.
The examples below indicate the form that the CALL PLISRTx statement normally
takes.

Example 1
A call to PLISRTA sorting 80-byte records from SORTIN to SORTOUT using
1048576 (1 megabyte) of storage, and a return code, RETCODE, declared as
FIXED BINARY (31,0).
CALL PLISRTA (' SORT FIELDS=(1,8K,CH,A) ',
1K48576,
RETCODE);
Example 2
This example is the same as example 1 except that the input, output, and work
data sets are called TASKIN, TASKOUT, TASKWK01, and so forth. This might
occur if Sort was being called twice in one job step.
CALL PLISRTA (' SORT FIELDS=(1,8K,CH,A) ',
1K48576,
RETCODE,
'TASK');
Example 3
This example is the same as example 1 except that the sort is to be undertaken on
two fields. First, bytes 1 to 10 which are characters, and then, if these are equal,
bytes 11 and 12 which contain a binary field, both fields are to be sorted in
ascending order.
CALL PLISRTA (' SORT FIELDS=(1,1K,CH,A,11,2,BI,A) ',
1K48576,
RETCODE);
Example 4
This example shows a call to PLISRTB. The input is to be passed to Sort by the
PL/I routine PUTIN, the sort is to be carried out on characters 1 to 10 of an 80 byte
fixed length record. Other information as above.
CALL PLISRTB (' SORT FIELDS=(1,1K,CH,A) ',
1K48576,
RETCODE,
PUTIN);
Example 5
This example shows a call to PLISRTD. The input is to be supplied by the PL/I
routine PUTIN and the output is to be passed to the PL/I routine PUTOUT. The
record to be sorted is 84 bytes varying (including the length prefix). It is to be
sorted on bytes 1 through 5 of the data in ascending order, then if these fields are
equal, on bytes 6 through 10 in descending order. (Note that the 4-byte length
prefix is included so that the actual values used are 5 and 10 for the starting
points.) If both these fields are the same, the order of the input is to be retained.
(The EQUALS option does this.)

CALL PLISRTD (' SORT FIELDS=(5,5,CH,A,1K,5,CH,D),EQUALS ',
' RECORD TYPE=V,LENGTH=(84) ',
1K48576,
RETCODE,
PUTIN, /]input routine (sort exit E15)]/
PUTOUT); /]output routine (sort exit E35)]/
Determining whether the Sort was successful

When the sort is completed, Sort sets a return code in the variable named in the
fourth argument of the call to PLISRTx. It then returns control to the statement that
follows the CALL PLISRTx statement. The value returned indicates the success or
failure of the sort as follows:
0 Sort successful
16 Sort failed
20 Sort message data set missing
You must declare the variable to which the return code is passed as FIXED
BINARY (31,0). It is standard practice to test the value of the return code after the
CALL PLISRTx statement and take appropriate action according to the success or
failure of the operation.
For example (assuming the return code was called RETCODE):

IF RETCODE¬=K THEN DO;
PUT DATA(RETCODE);
SIGNAL ERROR;
END;
If the job step that follows the sort depends on the success or failure of the sort,
you should set the value returned in the Sort program as the return code from the
PL/I program. This return code is then available for the following job step. The
PL/I return code is set by a call to PLIRETC. You can call PLIRETC with the value
returned from Sort thus:
CALL PLIRETC(RETCODE);
You should not confuse this call to PLIRETC with the calls made in the input and
output routines, where a return code is used for passing control information to Sort.
Establishing data sets for Sort

If DFSORT was installed in a library not know to the system, you must specify the
DFSORT library in a JOBLIB or STEPLIB DD statement.
When you call Sort, certain sort data sets must not be open. These are:
SYSOUT
A data set (normally the printer) on which messages from the Sort program will
be written.
Sort work data sets

SORTWK01–SORTWK32
Note: If you specify more than 32 sort work data sets, DFSORT will only use
the first 32.
****WK01–****WK32
From 1 to 32 working data sets used in the sorting process. These must be
direct-access. For a discussion of space required and number of data sets,
see “Determining storage needed for Sort” on page 251.
**** represents the four characters that you can specify as the data set prefix
argument in calls to PLISRTx. This allows you to use data sets with prefixes
other than SORT. They must start with an alphabetic character and must not
be the names PEER, BALN, CRCX, OSCL, POLY, SYSC, LIST, or DIAG.
Input data set
SORTIN
****IN
The input data set used when PLISRTA and PLISRTC are called.
See ****WK01–****WK32 above for a detailed description.
Output data set
SORTOUT
****OUT
The output data set used when PLISRTA and PLISRTB are called.
Checkpoint data set
SORTCKPT
Data set used to hold checkpoint data, if CKPT or CHKPT option was used in
the SORT statement argument and DFSORT's 16NCKPT=NO installation
option was specified. For information on this program DD statement, see
DFSORT Application Programming Guide.
DFSPARM
SORTCNTL
Data set from which additional or changed control statements can be read
(optional). For additional information on this program DD statement, see
DFSORT Application Programming Guide.

Sort data input and output

The source of the data to be sorted is provided either directly from a data set or
indirectly by a routine (Sort Exit E15) written by the user. Similarly, the destination
of the sorted output is either a data set or a routine (Sort Exit E35) provided by the
user.
PLISRTA is the simplest of all of the interfaces because it sorts from data set to
data set. An example of a PLISRTA program is in Figure 51 on page 260. Other
interfaces require either the input handling routine or the output handling routine, or
both.
Data input and output handling routines

The input handling and output handling routines are called by Sort when PLISRTB,
PLISRTC, or PLISRTD is used. They must be written in PL/I, and can be either
internal or external procedures. If they are internal to the routine that calls
PLISRTx, they behave in the same way as ordinary internal procedures in respect
of scope of names. The input and output procedure names must themselves be
known in the procedure that makes the call to PLISRTx.
The routines are called individually for each record required by Sort or passed from
Sort. Therefore, each routine must be written to handle one record at a time.
Variables declared as AUTOMATIC within the procedures will not retain their values
between calls. Consequently, items such as counters, which need to be retained
from one call to the next, should either be declared as STATIC or be declared in
the containing block.
E15—Input handling routine (Sort Exit E15)

Input routines are normally used to process the data in some way before it is
sorted. You can use input routines to print the data, as shown in the Figure 52 on
page 261 and Figure 54 on page 263, or to generate or manipulate the sorting
fields to achieve the correct results.
The input handling routine is used by Sort when a call is made to either PLISRTB
or PLISRTD. When Sort requires a record, it calls the input routine which should
return a record in character string format, with a return code of 12. This return
code means that the record passed is to be included in the sort. Sort continues to
call the routine until a return code of 8 is passed. A return code of 8 means that all
records have already been passed, and that Sort is not to call the routine again. If
a record is returned when the return code is 8, it is ignored by Sort.
The data returned by the routine must be a character string. It can be fixed or
varying. If it is varying, you should normally specify V as the record format in the
RECORD statement which is the second argument in the call to PLISRTx.
However, you can specify F, in which case the string will be padded to its
maximum length with blanks. The record is returned with a RETURN statement,
and you must specify the RETURNS attribute in the PROCEDURE statement. The
return code is set in a call to PLIRETC. A flowchart for a typical input routine is
shown in Figure 48 on page 257.

Input Handling Subroutine Output Handling Subroutine
START START
LAST RECEIVE
RECORD YES CALL
PLIRETC(8) RECORD
ALREADY
SENT PARAMETER
NO
Your code to Your code to

process record process record
CALL CALL
PLIRETC(12) PLIRETC(4)
RETURN END
RECORD
END
Figure 48. Flowcharts for input and output handling subroutines
Skeletal code for a typical input routine is shown in Figure 49 on page 258.

E15: PROC RETURNS (CHAR(8K));
/]---------------------------------------------------------------]/
/]RETURNS attribute must be used specifying length of data to be ]/
/] sorted, maximum length if varying strings are passed to Sort. ]/
/]---------------------------------------------------------------]/
DCL STRING CHAR(8K); /]--------------------------------------------]/
/]A character string variable will normally be]/
/] required to return the data to Sort ]/
/]--------------------------------------------]/
IF LAST_RECORD_SENT THEN
DO;
/]---------------------------------------------------------------]/
/]A test must be made to see if all the records have been sent, ]/
/]if they have, a return code of 8 is set up and control returned]/
/]to Sort ]/
/]---------------------------------------------------------------]/
CALL PLIRETC(8); /]-------------------------------------------]/

/] Set return code of 8, meaning last record ]/
/] already sent. ]/
/]-------------------------------------------]/
GOTO FINAL;
END;
ELSE
DO;
/]------------------------------------------------]/
/] If another record is to be sent to Sort, do the]/
/] necessary processing, set a return code of 12 ]/
/] by calling PLIRETC, and return the data as a ]/
/] character string to Sort ]/
/]------------------------------------------------]/
]]]](The code to do your processing goes here)
CALL PLIRETC (12); /]--------------------------------------]/

/] Set return code of 12, meaning this ]/
/] record is to be included in the sort ]/
/]--------------------------------------]/
RETURN (STRING); /]Return data with RETURN statement]/
END;
FINAL:
END; /]End of the input procedure]/
Figure 49. Skeletal code for an input procedure
Examples of an input routine are given in Figure 52 on page 261 and Figure 54 on
page 263.
In addition to the return codes of 12 (include current record in sort) and 8 (all
records sent), Sort allows the use of a return code of 16. This ends the sort and
causes Sort to return to your PL/I program with a return code of 16–Sort failed.
Note: A call to PLIRETC sets a return code that will be passed by your PL/I
program, and will be available to any job steps that follow it. When an output
handling routine has been used, it is good practice to reset the return code with a
call to PLIRETC after the call to PLISRTx to avoid receiving a nonzero completion
code. By calling PLIRETC with the return code from Sort as the argument, you can
make the PL/I return code reflect the success or failure of the sort. This practice is
shown in Figure 53 on page 262.

E35—Output handling routine (Sort Exit E35)
Output handling routines are normally used for any processing that is necessary
after the sort. This could be to print the sorted data, as shown in Figure 53 on
page 262 and Figure 54 on page 263, or to use the sorted data to generate
further information. The output handling routine is used by Sort when a call is
made to PLISRTC or PLISRTD. When the records have been sorted, Sort passes
them, one at a time, to the output handling routine. The output routine then
processes them as required. When all the records have been passed, Sort sets up
its return code and returns to the statement after the CALL PLISRTx statement.
There is no indication from Sort to the output handling routine that the last record
has been reached. Any end-of-data handling must therefore be done in the
procedure that calls PLISRTx.
The record is passed from Sort to the output routine as a character string, and you
must declare a character string parameter in the output handling subroutine to
receive the data. The output handling subroutine must also pass a return code of 4
to Sort to indicate that it is ready for another record. You set the return code by a
call to PLIRETC.
The sort can be stopped by passing a return code of 16 to Sort. This will result in
Sort returning to the calling program with a return code of 16–Sort failed.
The record passed to the routine by Sort is a character string parameter. If you
specified the record type as F in the second argument in the call to PLISRTx, you
should declare the parameter with the length of the record. If you specified the
record type as V, you should declare the parameter as adjustable, as in the
following example:
DCL STRING CHAR(]);
Figure 55 on page 264 shows a program that sorts varying length records.
A flowchart for a typical output handling routine is given in Figure 48 on page 257.
Skeletal code for a typical output handling routine is shown in Figure 50.
E35: PROC(STRING); /]The procedure must have a character string

parameter to receive the record from Sort]/
DCL STRING CHAR(8K); /]Declaration of parameter]/
(Your code goes here)
CALL PLIRETC(4); /]Pass return code to Sort indicating that the next
sorted record is to be passed to this procedure.]/
END E35; /]End of procedure returns control to Sort]/
Figure 50. Skeletal code for an output handling procedure
You should note that a call to PLIRETC sets a return code that will be passed by
your PL/I program, and will be available to any job steps that follow it. When you
have used an output handling routine, it is good practice to reset the return code
with a call to PLIRETC after the call to PLISRTx to avoid receiving a nonzero
completion code. By calling PLIRETC with the return code from Sort as the
argument, you can make the PL/I return code reflect the success or failure of the
sort. This practice is shown in the examples at the end of this chapter.

Calling PLISRTA example
After each time that the PL/I input- and output-handling routines communicate the
return-code information to the Sort program, the return-code field is reset to zero;
therefore, it is not used as a regular return code other than its specific use for the
Sort program.
For details on handling conditions, especially those that occur during the input- and
output-handling routines, see OS/390 Language Environment Programming Guide.
//OPT14#7 JOB ...

//PLI.SYSIN DD ]
EX1K6: PROC OPTIONS(MAIN);
DCL RETURN_CODE FIXED BIN(31,K);
CALL PLISRTA (' SORT FIELDS=(7,74,CH,A) ',

1K48576
RETURN_CODE);
SELECT (RETURN_CODE);
WHEN(K) PUT SKIP EDIT
('SORT COMPLETE RETURN_CODE K') (A);
WHEN(16) PUT SKIP EDIT
('SORT FAILED, RETURN_CODE 16') (A);
WHEN(2K) PUT SKIP EDIT
('SORT MESSAGE DATASET MISSING ') (A);
OTHER PUT SKIP EDIT (
'INVALID SORT RETURN_CODE = ', RETURN_CODE) (A,F(2));
END /] select ]/;
CALL PLIRETC(RETURN_CODE);
/]set PL/I return code to reflect success of sort]/
END EX1K6;
//GO.SORTIN DD ]
KK3329HOOKER S.W. RIVERDALE, SATCHWELL LANE, BACONSFIELD
KK2886BOOKER R.R. ROTORUA, LINKEDGE LANE, TOBLEY
KK3K77ROOKER & SON, LITTLETON NURSERIES, SHOLTSPAR
K59334HOOK E.H. 1K9 ELMTREE ROAD, GANNET PARK, NORTHAMPTON
K73872HOME TAVERN, WESTLEIGH
KKK931FOREST, IVER, BUCKS
/]
//GO.SYSPRINT DD SYSOUT=A
//GO.SORTOUT DD SYSOUT=A
//GO.SYSOUT DD SYSOUT=A
//GO.SORTWKK1 DD UNIT=SYSDA,SPACE=(CYL,2)
/]
Figure 51. PLISRTA—sorting from input data set to output data set
Calling PLISRTB example

//OPT14#8 JOB ...
//PLI.SYSIN DD ]
CALL PLISRTB (' SORT FIELDS=(7,74,CH,A) ',

1K48576
RETURN_CODE,
E15X);
SELECT(RETURN_CODE);
OTHER PUT SKIP EDIT
('INVALID RETURN_CODE = ',RETURN_CODE)(A,F(2));
END /] select ]/;
E15X: /] INPUT HANDLING ROUTINE GETS RECORDS FROM THE INPUT

STREAM AND PUTS THEM BEFORE THEY ARE SORTED]/
PROC RETURNS (CHAR(8K));
DCL SYSIN FILE RECORD INPUT,
INFIELD CHAR(8K);
ON ENDFILE(SYSIN) BEGIN;
PUT SKIP(3) EDIT ('END OF SORT PROGRAM INPUT')(A);
CALL PLIRETC(8); /] signal that last record has
already been sent to sort]/
GOTO ENDE15;
END;
READ FILE (SYSIN) INTO (INFIELD);

PUT SKIP EDIT (INFIELD)(A(8K)); /]PRINT INPUT]/
CALL PLIRETC(12); /] request sort to include current
record and return for more]/
RETURN(INFIELD);
ENDE15:
END E15X;
END EX1K7;
/]
//GO.SYSIN DD ]
/]
//]
//GO.SORTCNTL DD ]
OPTION DYNALLOC=(338K,2),SKIPREC=2
/]
Figure 52. PLISRTB—sorting from input handling routine to output data set

Calling PLISRTC example
//OPT14#9 JOB ...

//PLI.SYSIN DD ]
CALL PLISRTC (' SORT FIELDS=(7,74,CH,A) ',

1K48576
RETURN_CODE,
E35X);
OTHER PUT SKIP EDIT
('INVALID RETURN_CODE = ', RETURN_CODE) (A,F(2));
END /] select ]/;
CALL PLIRETC (RETURN_CODE);
E35X: /] output handling routine prints sorted records]/

PROC (INREC);
DCL INREC CHAR(8K);
PUT SKIP EDIT (INREC) (A);
CALL PLIRETC(4); /]request next record from sort]/
END E35X;
END EX1K8;
/]
//GO.STEPLIB DD DSN=SYS1.SORTLINK,DISP=SHR
//GO.SORTIN DD ]
/]
//GO.SORTCNTL DD ]
OPTION DYNALLOC=(338K,2),SKIPREC=2
/]
Figure 53. PLISRTC—sorting from input data set to output handling routine

Calling PLISRTD example
//OPT14#1K JOB ...

//PLI.SYSIN DD ]
CALL PLISRTD (' SORT FIELDS=(7,74,CH,A) ',
1K48576
RETURN_CODE,
E15X,
E35X);
OTHER PUT SKIP EDIT
('INVALID RETURN_CODE = ', RETURN_CODE) (A,F(2));
END /] select ]/;
E15X: /] Input handling routine prints input before sorting]/

PROC RETURNS(CHAR(8K));
DCL INFIELD CHAR(8K);
PUT SKIP(3) EDIT ('END OF SORT PROGRAM INPUT. ',
'SORTED OUTPUT SHOULD FOLLOW')(A);
CALL PLIRETC(8); /] Signal end of input to sort]/
GOTO ENDE15;
END;
GET FILE (SYSIN) EDIT (INFIELD) (A(8K));

PUT SKIP EDIT (INFIELD)(A);
CALL PLIRETC(12); /]Input to sort continues]/
RETURN(INFIELD);
ENDE15:
END E15X;
E35X: /] Output handling routine prints the sorted records]/

PROC (INREC);
DCL INREC CHAR(8K);

PUT SKIP EDIT (INREC) (A);
NEXT: CALL PLIRETC(4); /] Request next record from sort]/
END E35X;
END EX1K9;
/]
//GO.SYSIN DD ]
/]
Figure 54. PLISRTD—sorting from input handling routine to output handling routine

Sorting variable-length records example
//OPT14#11 JOB ...

//PLI.SYSIN DD ]
/] PL/I EXAMPLE USING PLISRTD TO SORT VARIABLE-LENGTH
RECORDS ]/

CALL PLISRTD (' SORT FIELDS=(11,14,CH,A) ',
' RECORD TYPE=V,LENGTH=(84,,,24,44) ',
/]NOTE THAT LENGTH IS MAX AND INCLUDES
4 BYTE LENGTH PREFIX]/
1K48576
RETURN_CODE,
PUTIN,
PUTOUT);
WHEN(K) PUT SKIP EDIT (
'SORT COMPLETE RETURN_CODE K') (A);
WHEN(16) PUT SKIP EDIT (
'SORT FAILED, RETURN_CODE 16') (A);
WHEN(2K) PUT SKIP EDIT (
'SORT MESSAGE DATASET MISSING ') (A);
OTHER PUT SKIP EDIT (
'INVALID RETURN_CODE = ', RETURN_CODE)
(A,F(2));
END /] SELECT ]/;
/]SET PL/I RETURN CODE TO REFLECT SUCCESS OF SORT]/
PUTIN: PROC RETURNS (CHAR(8K) VARYING);
/]OUTPUT HANDLING ROUTINE]/
/]NOTE THAT VARYING MUST BE USED ON RETURNS ATTRIBUTE
WHEN USING VARYING LENGTH RECORDS]/
DCL STRING CHAR(8K) VAR;
PUT SKIP EDIT ('END OF INPUT')(A);
CALL PLIRETC(8);
GOTO ENDPUT;
END;
GET EDIT(STRING)(A(8K));
I=INDEX(STRING||' ',' ')-1;/]RESET LENGTH OF THE]/
STRING = SUBSTR(STRING,1,I); /] STRING FROM 8K TO ]/
/] LENGTH OF TEXT IN ]/
/] EACH INPUT RECORD.]/
Figure 55 (Part 1 of 2). Sorting varying-length records using input and output handling
routines

PUT SKIP EDIT(I,STRING) (F(2),X(3),A);
CALL PLIRETC(12);
RETURN(STRING);
ENDPUT: END;
PUTOUT:PROC(STRING);
/]OUTPUT HANDLING ROUTINE OUTPUT SORTED RECORDS]/
DCL STRING CHAR (]);
/]NOTE THAT FOR VARYING RECORDS THE STRING
PARAMETER FOR THE OUTPUT-HANDLING ROUTINE
SHOULD BE DECLARED ADJUSTABLE BUT CANNOT BE
DECLARED VARYING]/
PUT SKIP EDIT(STRING)(A); /]PRINT THE SORTED DATA]/
CALL PLIRETC(4);
END; /]ENDS PUTOUT]/
END;
/]
//GO.SYSIN DD ]
/]
//]
Figure 55 (Part 2 of 2). Sorting varying-length records using input and output handling
routines

Chapter 13. ILC with C
This chapter describes some aspects of InterLanguage Communication (ILC)
between PL/I and C. The examples illustrate how to use many of the data types
common to both languages and should enable you to write PL/I code that either
calls or is called by C.
Equivalent data types

The table Table 29 lists the common C and PL/I data type equivalents.
Table 29. C and PL/I Type Equivalenst

C type Matchly PL/I type
char ...“ char(...) varyingz
wchar ...“ wchar(...) varyingz
signed char fixed bin(7)
unsgned char unsigned fixed bin(8)
short fixed bin(15)
unsigned short unsigned fixed bin(16)
int fixed bin(31)
unsigned int unsigned fixed bin(32)
long long fixed bin(63)
unsigned long long unsigned fixed bin(64)
float float bin(21)
double float bin(53)
long double float bin(p) (p >= 54)
enum ordinal
typedef define alias
struct define struct
union define union
struct * handle
Simple type equivalence

So, for example, the following illustrates the translation of the simple typedef for
time_t from the C header file time.h:
typedef long time_t;
define alias time_t fixed bin(31);
Figure 56. Simple type equivalence

Struct type equivalence
The following example illustrates the translation of the simple struct for tm from the
C header file time.h:
struct tm {
int tm_sec;
int tm_min;
int tm_hour;
int tm_mday;
int tm_mon;
int tm_year;
int tm_wday;
int tm_yday;
int tm_isdst;
};
define structure
1 tm
,2 tm_sec fixed bin(31)
,2 tm_min fixed bin(31)
,2 tm_hour fixed bin(31)
,2 tm_mday fixed bin(31)
,2 tm_mon fixed bin(31)
,2 tm_year fixed bin(31)
,2 tm_wday fixed bin(31)
,2 tm_yday fixed bin(31)
,2 tm_isdst fixed bin(31)
;
Figure 57. Sample struct type equivalence
Enum type equivalence

The following example illustrates the translation of the simple enum __device_t
from the C header file stdio.h:
typedef enum {
__disk = K,
__terminal = 1,
__printer = 2,
__tape = 3,
__tdq = 5,
__dummy = 6,
__memory = 8,
__hfs = 9,
__hiperspace = 1K
} __device_t;
define ordinal __device_t (

__disk value(K)
, __terminal value(1)
, __printer value(2)
, __tape value(3)
, __tdq value(4)
, __dummy value(5)
, __memory value(8)
, __hfs value(9)
, __hiperspace value(1K)
);
Figure 58. Sample enum type equivalence
Chapter 13. ILC with C 267

File type equivalence
A C file declaration depends on the platform, but it often starts as follows:
struct __file {
unsigned char ]__bufPtr;
... } FILE;
Figure 59. Start of the C declaration for its FILE type
All we want is a pointer (or token) for a file, so we can finesse this translation with:
define struct 1 file;

define alias file_Handle handle file;
Figure 60. PL/I equivalent for a C file
Using C functions
Let's say we wanted to write a program to read a file and dump it as formatted hex
- using the C functions fopen and fread.
The code for this program is straightforward:
filedump:
proc(fn) options(noexecops main);
dcl fn char(]) var;
%include filedump;
file = fopen( fn, 'rb' );
if file = sysnull() then

do;
display( 'file could not be opened' );
return;
end;
do forever;
unspec(buffer) = ''b;
read_In = fread( addr(buffer), 1, stg(buffer), file );
if read_In = K then
leave;
display( heximage(addr(buffer),16,' ') || ' '

|| translate(buffer,(32)'.',unprintable) );
if read_In < stg(buffer) then

leave;
end;
end filedump;
Figure 61. Sample code to use fopen and fread to dump a file
Most of the declarations in the INCLUDE file filedump are obvious:

define struct 1 file;
define alias file_Handle handle file;
define alias size_t unsigned fixed bin(32);
dcl file type(file_Handle);

dcl read_In fixed bin(31);
dcl buffer char(16);
dcl unprintable char(32) value( substr(collate(),1,32) );
Figure 62. Declarations for filedump program
Matching simple parameter types

It would be easy to mistranslate the declarations for the C functions. For instance,
you could take the following declaration for the C function fread:
size_t fread( void ],

size_t,
size_t,
FILE ]);
Figure 63. C declaration of fread
and translate it to:
dcl fread ext

entry( pointer,
type size_t,
type size_t,
type file_Handle )
returns( type size_t );
Figure 64. First incorrect declaration of fread
On some platforms, this would not link successfully because C names are case
senstive. In order to prevent this kind of linker problem, it is best to specify the
name in mixed case using the extended form of the external attribute. So, for
instance, the declare for fread would be better as:
dcl fread ext('fread')

entry( pointer,
type size_t,
type size_t,
type file_Handle )
Figure 65. Second incorrect declaration of fread
But this wouldn't run right, because while PL/I parameters are byaddr by default, C
parameters are byvalue by default; so we fix that by adding the byvalue attribute to
the parameters:

entry( pointer byvalue,
type size_t byvalue,
type file_Handle byvalue )
Figure 66. Third incorrect declaration of fread
But note how the return value is set in Figure 67: a fourth parameter (the address
of the temporary _temp5) is passed to the function fread, which is then expected to
place the return code in the integer at that address. This is the convention for how
values are returned when the byaddr attribute applies to returns, and PL/I uses this
convention by default.
] read_In = fread( addr(buffer), 1, stg(buffer), file );

]
L r4,FILE(,r13,176)
L r1,fread(,r5,12)
LA r2,_temp5(,r13,42K)
LA r8,BUFFER(,r13,184)
L r15,&EPA_&WSA(,r1,8)
L rK,&EPA_&WSA(,r1,12)
ST rK,_CEECAA_(,r12,5KK)
LA r1,#MX_TEMP1(,r13,152)
ST r8,#MX_TEMP1(,r13,152)
LA r8,1
ST r7,#MX_TEMP1(,r13,16K)
BALR r14,r15
L rK,_temp5(,r13,42K)
ST rK,READ_IN(,r13,18K)
Figure 67. Code generated for RETURNS BYADDR
This wouldn't run right, because C return values are byvalue. So, we fix that with
one more byvalue attribute.

entry( pointer byvalue,
type file_Handle byvalue )
returns( type size_t byvalue );
Figure 68. Correct declaration of fread
Note how the return value is set now in Figure 69 on page 271: no extra address
is passed, and the return value is simply returned in register 15.

] read_In = fread( addr(buffer), 1, stg(buffer), file );
]
L r2,FILE(,r13,176)
L r1,fread(,r5,12)
LA r7,BUFFER(,r13,184)
L r15,&EPA_&WSA(,r1,8)
L rK,&EPA_&WSA(,r1,12)
ST rK,_CEECAA_(,r12,5KK)
LA r7,1
ST r4,#MX_TEMP1(,r13,16K)
BALR r14,r15
LR rK,r15
ST rK,READ_IN(,r13,18K)
Figure 69. Code generated for RETURNS BYADDR
Matching string parameter types

Now that we have translated fread correctly, we might try this translation for fopen:
dcl fopen ext('fopen')

entry( char(]) varyingz byvalue,
char(]) varyingz byvalue )
returns( byvalue type file_handle );
Figure 70. First incorrect declaration of fopen
But C really has no strings, only pointers, and these pointers would be passed
byvalue; so the strings should be byaddr:

entry( char(]) varyingz byaddr,
char(]) varyingz byaddr )
returns( byvalue type file_handle );
Figure 71. Second incorrect declaration of fopen
But PL/I passes descriptors with strings and C doesn't understand them, so they
must be suppressed. We can do this by adding options(nodescriptor) to the
declaration:

entry( char(]) varyingz byaddr,
char(]) varyingz byaddr )
returns( byvalue type file_handle )
options ( nodescriptor );
Figure 72. Correct declaration of fopen
This will work, but isn't optimal since the parameters are input-only; if the parameter
is a constant, the nonassignable attribute will prevent a copy being made and
passed. Hence, the best translation of the declaration of fopen is:

entry( char(]) varyz nonasgn byaddr,
char(]) varyz nonasgn byaddr )
returns( byvalue type file_handle )
options ( nodescriptor );
Figure 73. Optimal, correct declaration of fopen
Now, on USS, we can compile and run the programs with the commands:
pli -qdisplay=std filedump.pli
filedump filedump.pli
Figure 74. Commands to compile and run filedump
This would produce the following output:
154K8689 938584A4 94977A4K 97999683 . filedump: proc

4D86955D 4K9697A3 899695A2 4D959685 (fn) options(noe
A7858396 97A24K94 8189955D 5E15154K xecops main);..
Figure 75. Output of running filedump
Functions returning ENTRYs

The C quicksort function qsort takes a compare routine. For instance, to sort an
array of integers, the following function (which use the byvalue attribute twice - for
the reasons discussed above) could be used:
comp2:
proc( key, element )
returns( fixed bin(31) byvalue );
dcl (key, element) pointer byvalue;

dcl word based fixed bin(31);
select;
when( key->word < element->word )
return( -1 );
when( key->word = element->word )
return( K );
otherwise
return( +1 );
end;
end;
Figure 76. Sample compare routine for C qsort function
And the C qsort function could be used with this compare routine to sort an array of
integers, as in the following code fragment:

dcl a(1:4) fixed bin(31) init(19,17,13,11);
put skip data( a );
call qsort( addr(a), dim(a), stg(a(1)), comp2 );
put skip data( a );
Figure 77. Sample code to use C qsort function
But since C function pointers are not the same as PL/I ENTRY variables, the C
qsort function must not be declared as simply:
dcl qsort ext('qsort')

entry( pointer,
fixed bin(31),
fixed bin(31),
entry returns( byvalue fixed bin(31) )
)
options( byvalue nodescriptor );
Figure 78. Incorrect declaration of qsort
Recall that a PL/I ENTRY variable may point to a nested function (and thus
requires a backchain address as well as an entry point address). But a C function
pointer is limited in pointing to a non-nested function only and so, a PL/I ENTRY
variable and a C function pointer do not even use the amount of storage.
However, a C function pointer is equivalent to the new PL/I type: a LIMITED

ENTRY. and hence the C qsort function could be declared as:
dcl qsort ext('qsort')

entry( pointer,
fixed bin(31),
fixed bin(31),
limited entry
returns( byvalue fixed bin(31) )
)
Figure 79. Correct declaration of qsort
Linkages
On 390, there are two crucial facts about linkages:
IBM C, JAVA and Enterprise PL/I use the same linkage by default.
This linkage is not the system linkage.
For a traditional PL/I application where all parameters are byaddr, the differences
between the code generated when a function has the default linkage and when it
has the system linkage would usually not matter. But if the parameters are byvalue
(as they usually are in C and JAVA), the differences can break your code.
In fact, there is only a small difference if the parameters are byaddr. In Figure 80
on page 274, the only difference between the code generated for a function with

the default linkage and for one with the system linkage is that the high-order bit is
turned on for the last parameter of the system linkage call.
This difference would be transparent to most programs.
dcl dftv ext entry( fixed bin(31) byaddr

,fixed bin(31) byaddr );
dcl sysv ext entry( fixed bin(31) byaddr
,fixed bin(31) byaddr )
options( linkage(system) );
] call dfta( n, m );
]
LA rK,M(,r13,172)
LA r2,N(,r13,168)
L r15,=V(DFTV)(,r3,126)
ST rK,#MX_TEMP1(,r13,156)
BALR r14,r15
]
] call sysa( n, m );
]
LA rK,M(,r13,172)
LA r2,N(,r13,168)
O rK,=X'8KKKKKKK'
L r15,=V(SYSV)(,r3,13K)
BALR r14,r15
Figure 80. Code when parameters are BYADDR
But, there is a big difference if the parameters are byvalue rather than byaddr. In
Figure 81 on page 275, for the function with the default linkage, register 1 points to
the values of the integers passed, while for the function with the system linkage,
register 1 points to the addresses of those values.
This difference would not be transparent to most programs.

dcl dftv ext entry( fixed bin(31) byvalue
,fixed bin(31) byvalue );
dcl sysv ext entry( fixed bin(31) byvalue
,fixed bin(31) byvalue )
options( linkage(system) );
] call dftv( n, m );
]
L r2,N(,r13,168)
L rK,M(,r13,172)
L r15,=V(DFTV)(,r3,174)
BALR r14,r15
]
] call sysv( n, m );
]
L r1,N(,r13,168)
L rK,M(,r13,172)
ST rK,#wtemp_1(,r13,176)
LA rK,#wtemp_1(,r13,176)
ST r1,#wtemp_2(,r13,18K)
LA r2,#wtemp_2(,r13,18K)
O rK,=X'8KKKKKKK'
L r15,=V(SYSV)(,r3,178)
BALR r14,r15
Figure 81. Code when parameters are BYVALUE
Summary
What we have learned in this chapter:
C is case sensitive.
Parameters should be BYVALUE.
Return values should be BYVALUE.
Except string parameters should be BYADDR.
Arrays and structures should also be BYADDR.
No descriptors should be passed.
Input-only strings should be NONASSIGNABLE.
C function pointers map to LIMITED ENTRYs.
The IBM C compilers and the IBM PL/I compilers use the same default linkage
(and it matters).

Chapter 14. Interfacing with Java
This chapter gives a brief description of Java and the Java Native Interface (JNI)
and explains why you might be interested in using it with PL/I. A simple Java - PL/I
application will be described and information on compatibility between the two
languages will also be discussed. Instructions on how to build and run the Java -
PL/I sample applications assume the work is being done in the UNIX System
Services (USS) environment of S/390.
Before you can communicate with Java from PL/I you need to have Java installed
on your S/390 system. Contact your local System Administrator for more
information on how to set up your S/390 Java environment.
What is the Java Native Interface (JNI)?

Java is an object-oriented programming language invented by Sun Microsystems
and provides a powerful way to make Internet documents interactive.
The Java Native Interface (JNI) is the Java interface to native programming
languages and is part of the Java Development Kits. By writing programs that use
the JNI, you ensure that your code is portable across many platforms.
The JNI allows Java code that runs within a Java Virtual Machine (JVM) to operate
with applications and libraries written in other languages, such as PL/I. In addition,
the Invocation API allows you to embed a Java Virtual Machine into your native
PL/I applications.
Java is a fairly complete programming language; however, there are situations in

which you want to call a program written in another programming language. You
would do this from Java with a method call to a native language, known as a native
method.
Some reasons to use native methods may include the following:

The native language has a special capability that your application needs and
that the standard Java class libraries lack.
You already have many existing applications in your native language and you
wish to make them accessible to a Java application.
You wish to implement a intensive series of complicated calculations in your
native language and have your Java applications call these functions.
You or your programmers have a broader skill set in your native language and
you do not wish to loose this advantage.
Programming through the JNI lets you use native methods to do many different
operations. A native method can:
utilize Java objects in the same way that a Java method uses these objects.
create Java objects, including arrays and strings, and then inspect and use
these objects to perform its tasks.
inspect and use objects created by Java application code.

update Java objects that it created or were passed to it, and these updated
objects can then be made available to the Java application.
Finally, native methods can also easily call already existing Java methods,
capitalizing on the functionality already incorporated in the Java programming
framework. In these ways, both the native language side and the Java side of an
application can create, update, and access Java objects and then share these
objects between them.
JNI Sample Program #1 - "Hello World"
Writing Java Sample Program #1

The first sample program we will write is yet another variation of the "Hello World!"
program.
Our "Hello World!" program has one Java class, callingPLI.java. Our native
method, written in PL/I, is contained in hiFromPLI.pli. Here is a brief overview of
the steps for creating this sample program:
1. Write a Java program that defines a class containing a native method, loads
the native load library, and calls the native method.
2. Compile the Java program to create a Java class.
3. Write a PL/I program that implements the native method and displays the
"Hello!" text.
4. Compile and link the PL/I program.
5. Run the Java program which calls the native method in the PL/I program.
Step 1: Writing the Java Program
Declare the Native Method

All methods, whether Java methods or native methods, must be declared within a
Java class. The only difference in the declaration of a Java method and a native
method is the keyword native. The native keyword tells Java that the
implementation of this method will be found in a native library that will be loaded
during the execution of the program. The declaration of our native method looks
like this:
public native void callToPLI();
In the above statement, the void means that there is no return value expected from
this native method call. The empty parentheses in the method name callToPLI( ),
means that there are no parameters being passed on the call to the native method.
Load the Native Library

A step that loads the native library must be included so the native library will be
loaded at execution time. The Java statement that loads the native library looks
like this:
static {
System.loadLibrary("hiFromPLI");
}
Chapter 14. Interfacing with Java 277

In the above statement, the Java System method System.loadLibrary(...) is called to
find and load the native library. The PL/I shared library, libhiFromPLI.so, will
created during the step that compiles and links the PL/I program.
Write the Java Main Method

The callingPLI class also includes a main method to instantiate the class and call
the native method. The main method instantiates callingPLI and calls the
callToPLI() native method.
The complete definition of the callingPLI class, including all the points addressed
above in this section, looks like this:
public class callingPLI {
public native void callToPLI();
static {
System.loadLibrary("hiFromPLI");
}
public static void main(String[] argv) {
callingPLI callPLI = new callingPLI();
callPLI.callToPLI();
System.out.println("And Hello from Java, too!");
}
}
Step 2: Compiling the Java Program

Use the Java compiler to compile the callingPLI class into an executable form. The
command would look like this:
javac callingPLI.java
Step 3: Writing the PL/I Program

The PL/I implementation of the native method looks much like any other PL/I
subroutine.
Useful PL/I Compiler Options

The sample program contains a series of *PROCESS statements that define the
important compiler options.
]Process Limits( Extname( 31 ) ) Margins( 1, 1KK ) ;
]Process Display(Std) Dllinit;
]Process Default( ASCII IEEE );
Here is a brief description of them and why they are useful:
Extname(31)
Allows for longer, Java style, external names.
Margins(1,100)
Extending the margins gives you more room for Java style names and
identifiers.
Display(Std)
Writes the "Hello World" text to stdout, not via WTOs. In the USS environment
WTOs would not be seen by the user.

Dllinit
Includes the initilization coded needed for creating a DLL.
Default( ASCII IEEE );

ASCII specifies that CHARACTER and PICTURE data is held in ASCII - the
form in which it is held by JAVA
IEEE specifies that FLOAT data is held in IEEE format - the form in which it is
held by JAVA
The following default PL/I compiler option is also necessary. A Java - PL/I program
may not work correctly if this option is changed or overridden.
RENT
The RENT option insures that code is reentrant even if it writes on static
variables.
Correct Form of PL/I Procedure Name and Procedure Statement

The PL/I procedure name must conform to the Java naming convention in order to
be located by the Java Class Loader at execution time. The Java naming scheme
consists of three parts. The first part identifies the routine to the Java environment,
the second part is the name of the Java class that defines the native method, and
the third part is the name of the native method itself.
Here is a breakdown of PL/I procedure name Java_callingPLI_callToPLI in the

sample program:
Java
All native methods resident in dynamic libraries must begin with Java
_callingPLI
The name of the Java class that declares the native method
_callToPLI
The name of the native method itself.
Note: There is an important difference between coding a native method in PL/I

and in C. The javah tool, which is shipped with the JDK, generates the form of the
external references required for C programs. When you write your native methods
in PL/I and follow the rules above for naming your PL/I external references,
performing the javah step is not necessary for PL/I native methods.
The complete procedure statement for the sample program looks like this:
Java_callingPLI_callToPLI:
Proc( JNIEnv , MyJObject )
External( "Java_callingPLI_callToPLI" )
Options( NoDescriptor ByValue );
JNI Include File

The PL/I include file which contains the PL/I definition of the Java interfaces is
contained in two include files, jni.inc which in turn includes jni_md.inc. These
include files are included with this statement:
%include jni;
For a complete listing of the jni.inc file refer to Figure 87 on page 292.

The Complete PL/I Procedure
For completeness, here is the entire PL/I program that defines the native method:
PliJava_Demo: Package Exports(]);
Java_callingPLI_callToPLI:
Proc( JNIEnv , MyJObject )
External( "Java_callingPLI_callToPLI" )
Options( NoDescriptor ByValue );
%include jni;
Display('Hello from VisualAge PL/I!');
End;
Step 4: Compiling and Linking the PL/I Program
Compiling the PL/I Program

Compile the PL/I sample program with the following command:
pli -c hiFromPLI.pli
Linking the Shared Library

Link the resulting PL/I object deck into a shared library with this command:
c89 -o libhiFromPLI.so hiFromPLI.o
Be sure to include the lib prefix on the name of the PL/I shared library or the Java
class loader will not find it.
Step 5: Running the Sample Program

Run the Java - PL/I sample program with this command:
java callingPLI
The output of the sample program will look like this:

Hello from VisualAge PL/I!
And Hello from Java, too!
The first line written from the PL/I native method. The second line is from the
calling Java class after returning from the PL/I native method call.

JNI Sample Program #2 - Passing a String

This sample program passes a string back and forth between Java and PL/I. Refer
to Figure 82 on page 282 for the complete listing of the jPassString.java program.
The Java portion has one Java class, jPassString.java. Our native method, written
in PL/I, is contained in passString.pli. Much of the information from the first sample
program applies to this sample program as well. Only new or different aspects will
be discussed for this sample program.

The native method for this sample program looks like this:
public native void pliShowString();

The Java statement that loads the native library for this sample program looks like
this:
static {
System.loadLibrary("passString");
}

The jPassString class also includes a main method to instantiate the class and call
the native method. The main method instantiates jPassString and calls the
pliShowString() native method.
This sample program prompts the user for a string and reads that value in from the
command line. This is done within a try/catch statement as shown in Figure 82 on
page 282.

// Read a string, call PL/I, display new string upon return
import java.io.];
public class jPassString{
/] Field to hold Java string ]/

String myString;
/] Load the PL/I native library ]/

static {
System.loadLibrary("passString");
}
/] Declare the PL/I native method ]/

public native void pliShowString();
/] Main Java class ]/

public static void main(String[] arg) {
System.out.println(" ");
/] Instantiate Java class and initilize string ]/

jPassString myPassString = new jPassString();
myPassString.myString = " ";
/] Prompt user for a string ]/

try {
BufferedReader in = new BufferedReader(
new InputStreamReader(System.in));
/] Process until 'quit' received ]/

while (!myPassString.myString.equalsIgnoreCase("quit")) {
System.out.println(
"From Java: Enter a string or 'quit' to quit.");
System.out.print("Java Prompt > ");
/] Get string from command line ]/
myPassString.myString = in.readLine();
if (!myPassString.myString.equalsIgnoreCase("quit"))
{
/] Call PL/I native method ]/
myPassString.pliShowString();
/] Return from PL/I and display new string ]/
System.out.println(
"From Java: String set by PL/I is: "
+ myPassString.myString );
}
}
} catch (IOException e) {
}
}
}
Figure 82. Java Sample Program #2 - Passing a String

The command to compile the Java code would look like this:
javac jPassString.java

All of the information about writing the PL/I "Hello World" sample program applies
to this program as well.

The PL/I procedure name for this program would be
pv.Java_jPassString_pliShowString.
Java_jPassString_pliShowString:
Proc( JNIEnv , myjobject )
external( "Java_jPassString_pliShowString" )
JNI Include File

%include jni;

The complete PL/I program is shown in Figure 83 on page 284. This sample PL/I
program makes several calls through the JNI.
Upon entry, a reference to the calling Java Object, myObject is passed into the PL/I
procedure. The PL/I program will use this reference to get information from the
calling object. The first piece of information is the Class of the calling object which
is retrieved using the GetObjectClass JNI function. This Class value is then used
by the GetFieldID JNI function to get the identity of the Java string field in the Java
object that we are interested in. This Java field is further identified by providing the
name of the field, myString, and the JNI field descriptor, Ljava/lang/String;, which
identifies the field as a Java String field. The value of the Java string field is then
retrieved using the GetObjectField JNI function. Before PL/I can use the Java
string value, it must be unpacked into a form that PL/I can understand. The
GetStringUTFChars JNI function is used to convert the Java string into a PL/I
varyingz string which is then displayed by the PL/I program.
After displaying the retrieved Java string, the PL/I program prompts the user for a
PL/I string to be used to update the string field in the calling Java object. The PL/I
string value is converted to a Java string using the NewString JNI function. This
new Java string is then used to update the string field in the calling Java object
using the SetObjectField JNI function.
When the PL/I program ends control is returned to Java, where the newly updated
Java string is displayed by the Java program.

plijava_demo: package exports(]);
Java_passString_pliShowString:
Proc( JNIEnv , myJObject )
external( "Java_jPassString_pliShowString" )
%include jni;
Dcl myBool Type jBoolean;

Dcl myClazz Type jClass;
Dcl myFID Type jFieldID;
Dcl myJObject Type jObject;
Dcl myJString Type jString;
Dcl newJString Type jString;
Dcl myID Char(9) Varz static init( 'myString' );
Dcl mySig Char(18) Varz static
init( 'Ljava/lang/String;' );
Dcl pliStr Char(132) Varz Based(pliStrPtr);
Dcl pliReply Char(132) Varz;
Dcl pliStrPtr Pointer;
Dcl nullPtr Pointer;
Display(' ');
/] Get information about the calling Class ]/

myClazz = GetObjectClass(JNIEnv, myJObject);
/] Get Field ID for String field from Java ]/

myFID = GetFieldID(JNIEnv, myClazz, myID, mySig );
/] Get the Java String in the string field ]/

myJString = GetObjectField(JNIEnv, myJObject, myFID );
/] Convert the Java String to a PL/I string ]/

pliStrPtr = GetStringUTFChars(JNIEnv, myJString, myBool );
Display('From PLI: String retrieved from Java is: ' || pliStr );

Display('From PLI: Enter a string to be returned to Java:' )
reply(pliReply);
/] Convert the new PL/I string to a Java String ]/

newJString = NewString(JNIEnv, trim(pliReply), length(pliReply) );
/] Change the Java String field to the new string value ]/

nullPtr = SetObjectField(JNIEnv, myJObject, myFID, newJString);
End;
end;
Figure 83. PL/I Sample Program #2 - Passing a String

pli -c passString.pli

c89 -o libpassString.so passString.o
Be sure to include the lib prefix on the name or the PL/I shared library or the Java

java jPassString
The output of the sample program, complete with the prompts for user input from
both Java and PL/I, will look like this:
>java jPassString
From Java: Enter a string or 'quit' to quit.

Java Prompt > A string entered in Java
From PLI: String retrieved from Java is: A string entered in Java
From PLI: Enter a string to be returned to Java:
A string entered in PL/I
From Java: String set by PL/I is: A string entered in PL/I

From Java: Enter a string or 'quit' to quit.
Java Prompt > quit
>
JNI Sample Program #3 - Passing an Integer

This sample program passes an integer back and forth between Java and PL/I.
Refer to Figure 84 on page 287 for the complete listing of the jPassInt.java
program. The Java portion has one Java class, jPassInt.java. The native method,
written in PL/I, is contained in passInt.pli. Much of the information from the first
sample program applies to this sample program as well. Only new or different
aspects will be discussed for this sample program.

The native method for this sample program looks like this:
public native void pliShowInt();

The Java statement that loads the native library for this sample program looks like
this:
static {
System.loadLibrary("passInt");
}

The jPassInt class also includes a main method to instantiate the class and call the
native method. The main method instantiates jPassInt and calls the pliShowInt()
native method.
This sample program prompts the user for an integer and reads that value in from
the command line. This is done within a try/catch statement as shown in Figure 84
on page 287.

// Read an integer, call PL/I, display new integer upon return
import java.io.];
import java.lang.];
public class jPassInt{
/] Fields to hold Java string and int ]/

int myInt;
String myString;
/] Load the PL/I native library ]/

static {
System.loadLibrary("passInt");
}
/] Declare the PL/I native method ]/

public native void pliShowInt();
/] Main Java class ]/

public static void main(String[] arg) {
/] Instantiate Java class and initilize string ]/

jPassInt pInt = new jPassInt();
pInt.myInt = 1K24;
pInt.myString = " ";
/] Prompt user for an integer ]/

try {
BufferedReader in = new BufferedReader(
new InputStreamReader(System.in));
/] Process until 'quit' received ]/

while (!pInt.myString.equalsIgnoreCase("quit")) {
System.out.println("From Java: Enter an Integer or 'quit' to quit.");
System.out.print("Java Prompt > ");
/] Get string from command line ]/
pInt.myString = in.readLine();
if (!pInt.myString.equalsIgnoreCase("quit"))
{
/] Set int to integer value of String ]/
pInt.myInt = Integer.parseInt( pInt.myString );
/] Call PL/I native method ]/
pInt.pliShowInt();
/] Return from PL/I and display new string ]/
System.out.println("From Java: Integer set by PL/I is: " + pInt.myInt );
}
}
} catch (IOException e) {
}
}
Figure 84. Java Sample Program #3 - Passing an Integer

The command to compile the Java code would look like this:
javac jPassInt.java

All of the information about writing the PL/I "Hello World" sample program applies
to this program as well.

The PL/I procedure name for this program would be Java_jPassInt_pliShowInt.
Java_passNum_pliShowInt:
external( "Java_jPassInt_pliShowInt" )
JNI Include File

%include jni;

The complete PL/I program is shown in Figure 85 on page 289. This sample PL/I
program makes several calls through the JNI.
Upon entry, a reference to the calling Java Object, myObject, is passed into the
PL/I procedure. The PL/I program will use this reference to get information from
the calling object. The first piece of information is the Class of the calling object
which is retrieved using the GetObjectClass JNI function. This Class value is then
used by the GetFieldID JNI function to get the identity of the Java integer field in
the Java object that we are interested in. This Java field is further identified by
providing the name of the field, myInt, and the JNI field descriptor, I, which
identifies the field as an integer field. The value of the Java integer field is then
retrieved using the GetIntField JNI function which is then displayed by the PL/I
program.
After displaying the retrieved Java integer, the PL/I program prompts the user for a
PL/I integer to be used to update the integer field in the calling Java object. The
PL/I integer value is then used to update the integer field in the calling Java object
using the SetIntField JNI function.
When the PL/I program ends, control is returned to Java, where the newly updated
Java integer is displayed by the Java program.

plijava_demo: package exports(]);
Java_passNum_pliShowInt:
external( "Java_jPassInt_pliShowInt" )
%include jni;
Dcl myClazz Type jClass;

Dcl myFID Type jFieldID;
Dcl myJInt Type jInt;
dcl rtnJInt Type jInt;
Dcl myJObject Type jObject;
Dcl pliReply Char(132) Varz;
Dcl nullPtr Pointer;
Display(' ');
/] Get information about the calling Class ]/

myClazz = GetObjectClass(JNIEnv, myJObject);
/] Get Field ID for int field from Java ]/

myFID = GetFieldID(JNIEnv, myClazz, "myInt", "I");
/] Get Integer value from Java ]/

myJInt = GetIntField(JNIEnv, myJObject, myFID);
display('From PLI: Integer retrieved from Java is: ' || trim(myJInt) );

display('From PLI: Enter an integer to be returned to Java:' )
reply(pliReply);
rtnJInt = pliReply;
/] Set Integer value in Java from PL/I ]/

nullPtr = SetIntField(JNIEnv, myJObject, myFID, rtnJInt);
End;
end;
Figure 85. PL/I Sample Program #3 - Passing an Integer

pli -c passInt.pli

c89 -o libpassInt.so passInt.o
Be sure to include the lib prefix on the name or the PL/I shared library or the Java

java jPassInt
The output of the sample program, complete with the prompts for user input from
both Java and PL/I, will look like this:
>java jPassInt
From Java: Enter an Integer or 'quit' to quit.

Java Prompt > 12345
From PLI: Integer retrieved from Java is: 12345

From PLI: Enter an integer to be returned to Java:
54321
From Java: Integer set by PL/I is: 54321

From Java: Enter an Integer or 'quit' to quit.
Java Prompt > quit
>
Determining equivalent Java and PL/I data types

When you communicate with Java from PL/I you will need to match the data types
between the two programming languages. This table shows Java primitive types
and their PL/I equivalents:
Table 30. Java Primitive Types and PL/I Native

Equivalents
Java Type PL/I Type Size in Bits
boolean jboolean 8, unsigned
byte jbyte 8
char jchar 16, unsigned
short jshort 16
int jint 32
long jlong 64
float jfloat 21
double jdouble 53
void jvoid n/a

Full contents of jni_md.inc include file
/]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]/
/]] jni_md.inc - This is included by jni.inc. ]/
/]] - The source is jni_md.h in jdk1.1.8 ]/
/]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]/
/] ]/
/] 5639-A83, 5639-A24 (C) Copyright IBM Corp. 1999,2KK1 ]/
/] (C) Copyright IBM Corp. 1998. All Rights Reserved. ]/
/] IBM Corp. ]/
/] ]/
/] The following menclosedy code is sample code created by IBM ]/
/] IBM product and is provided to you solely for the purpose of]/
/] ]/
/]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]/
define alias jint fixed bin(31) byvalue;

define alias jlong real float bin(53) byvalue;
define alias jbyte signed fixed bin(7);
define alias float real float bin(53) byvalue;

define alias double real float bin(53) byvalue;
Figure 86. jni_md.inc Include File

Full contents of jni.inc include file
/]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]/
/]] jni.inc - This is the main include for PL/I Java support. ]/
/]] - The source is jni.h in jdk1.1.8 ]/
/]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]/
/] ]/
/] 5639-A83, 5639-A24 (C) Copyright IBM Corp. 1999,2KK1 ]/
/] (C) Copyright IBM Corp. 1998. All Rights Reserved. ]/
/] IBM Corp. ]/
/] ]/
/] The following menclosedy code is sample code created by IBM ]/
/] IBM product and is provided to you solely for the purpose of]/
/] ]/
/]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]/
%include jni_md;
define alias jboolean unsigned fixed bin(8);

define alias jchar unsigned fixed bin(16);
define alias jshort fixed bin(15);
define alias jfloat float bin(21);
define alias jdouble float bin(53);
define alias jsize type jint;
define alias jobject pointer byvalue;

define alias jclass type jobject;
define alias jthrowable type jobject;
define alias jstring type jobject;
define alias jvoid type jobject;
define alias jfieldID type jobject;
define alias jmethodID type jobject;
define alias jarray type jobject;
define alias jbooleanArray type jarray;
define alias jbyteArray type jarray;
define alias jcharArray type jarray;
define alias jshortArray type jarray;
define alias jintArray type jarray;
define alias jlongArray type jarray;
define alias jfloatArray type jarray;
define alias jdoubleArray type jarray;
define alias jobjectArray type jarray;
Figure 87 (Part 1 of 22). jni.inc Include File

define alias jref type jobject; /] For transition---not meant to ]/
/] be part of public API anymore.]/
define structure
1 jvalue union,
2 z type jboolean,
2 b type jbyte,
2 c type jchar,
2 s type jshort,
2 i type jint,
2 j type jlong,
2 f type jfloat,
2 d type jdouble,
2 l type jobject;
define alias @jvalue handle jvalue;
/] jboolean constants ]/
dcl JNI_FALSE fixed bin(31) value(K);

dcl JNI_TRUE fixed bin(31) value(1);
/] possible return values for JNI functions. ]/
dcl JNI_OK fixed bin(31) value(K);

dcl JNI_ERR fixed bin(31) value(-1);
/] used in ReleaseScalarArrayElements ]/
dcl JNI_COMMIT fixed bin(31) value(1);

dcl JNI_ABORT fixed bin(31) value(2);
/] Used in RegisterNatives to describe native method name, ]/
/] signature, and function pointer. ]/
define structure
1 dummy#1,
2 name pointer,
2 signature pointer,
2 fnPtr pointer;
define alias @dummy#1 handle dummy#1;

define alias JNINativeMethod type dummy#1;

/] JNI Native Method Interface. ]/
dcl JNIEnv pointer byvalue ;

dcl dJNIEnv pointer based(JNIEnv);
dcl 1 JNINativeInterface_ based(dJNIEnv),

2 ] pointer,
2 ] pointer,
2 ] pointer,
2 ] pointer,
2 GetVersion limited entry

( pointer byvalue )
options (byvalue nodescriptor )
returns ( byvalue type jint ),
2 DefineClass limited entry

( pointer byvalue, pointer byvalue, pointer byvalue,
fixed bin(31) )
returns ( byvalue type jclass ),
2 FindClass limited entry

( pointer byvalue, nonasgn byaddr char(]) varz)
2 ] pointer,
2 ] pointer,
2 ] pointer,
2 GetSuperClass limited entry

( pointer byvalue, type jclass )
returns ( byvalue type jclass),
2 IsAssignableFrom limited entry

( pointer byvalue, type jclass, type jclass )
returns ( byvalue type jboolean ),
2 ] pointer,
2 Throw limited entry

( pointer byvalue, type jthrowable )
2 ThrowNew limited entry

( pointer byvalue, type jclass,
nonasgn byaddr char(]) varz )
2 ExceptionOccurred limited entry

( pointer byvalue )
returns ( byvalue type jthrowable ),

2 ExceptionDescribe limited entry
( pointer byvalue )
returns ( byvalue pointer optional ),
2 ExceptionClear limited entry

( pointer byvalue )
2 FatalError limited entry

( pointer byvalue, pointer byvalue )
2 ] pointer,
2 ] pointer,
2 NewGlobalRef limited entry

( pointer byvalue, type jobject )
returns ( byvalue type jobject ),
2 DeleteGlobalRef limited entry

2 DeleteLocalRef limited entry

2 IsSameObject limited entry

( pointer byvalue, type jobject, type jobject )
2 ] pointer,
2 ] pointer,
2 AllocObject limited entry

2 NewObject limited entry

( pointer byvalue, type jclass, list type jmethodID )
2 NewObjectV limited entry

( pointer byvalue, type jclass, type jmethodID,
pointer byvalue )
2 NewObjectA limited entry

pointer byvalue )

2 GetObjectClass limited entry
( pointer byvalue, type jobject)
2 IsInstanceOf limited entry

( pointer byvalue, type jobject, type jclass)
2 GetMethodID limited entry

byaddr nonasgn char(]) varz,
byaddr nonasgn char(]) varz)
returns ( byvalue type jmethodID ),
2 CallObjectMethod limited entry

( pointer byvalue, type jobject, list type jmethodID)
2 CallObjectMethodV limited entry
2 CallObjectMethodA limited entry
( pointer byvalue, type jobject, type jmethodID,
pointer byvalue )
2 CallBooleanMethod limited entry

2 CallBooleanMethodV limited entry

2 CallBooleanMethodA limited entry

pointer byvalue )
2 CallByteMethod limited entry

returns ( byvalue type jbyte ),
2 CallByteMethodV limited entry

2 CallByteMethodA limited entry

pointer byvalue )

2 CallCharMethod limited entry
returns ( byvalue type jchar ),
2 CallCharMethodV limited entry

2 CallCharMethodA limited entry

pointer byvalue )
2 CallShortMethod limited entry

returns ( byvalue type jshort ),
2 CallShortMethodV limited entry

2 CallShortMethodA limited entry

pointer byvalue )
2 CallIntMethod limited entry

2 CallIntMethodV limited entry

2 CallIntMethodA limited entry

pointer byvalue )
2 CallLongMethod limited entry

returns ( byvalue type jlong ),
2 CallLongMethodV limited entry

2 CallLongMethodA limited entry

pointer byvalue )

2 CallFloatMethod limited entry
returns ( byvalue type jfloat ),
2 CallFloatMethodV limited entry

2 CallFloatMethodA limited entry

pointer byvalue )
2 CallDoubleMethod limited entry

returns ( byvalue type jdouble ),
2 CallDoubleMethodV limited entry

2 CallDoubleMethodA limited entry

pointer byvalue )
2 CallVoidMethod limited entry

returns ( byvalue type jvoid ),
2 CallVoidMethodV limited entry

2 CallVoidMethodA limited entry

pointer byvalue )
2 CallNonVirtualObjectMethod limited entry

( pointer byvalue, type jobject, type jclass,
list type jmethodID )
2 CallNonVirtualObjectMethodV limited entry

list type jmethodID)

2 CallNonVirtualObjectMethodA limited entry
type jmethodID, pointer byvalue )
2 CallNonVirtualBooleanMethod limited entry

2 CallNonVirtualBooleanMethodV limited entry

2 CallNonVirtualBooleanMethodA limited entry

2 CallNonVirtualByteMethod limited entry

2 CallNonVirtualByteMethodV limited entry

2 CallNonVirtualByteMethodA limited entry

2 CallNonVirtualCharMethod limited entry

2 CallNonVirtualCharMethodV limited entry

2 CallNonVirtualCharMethodA limited entry


2 CallNonVirtualShortMethod limited entry
2 CallNonVirtualShortMethodV limited entry

2 CallNonVirtualShortMethodA limited entry

2 CallNonVirtualIntMethod limited entry

2 CallNonVirtualIntMethodV limited entry

2 CallNonVirtualIntMethodA limited entry

2 CallNonVirtualLongMethod limited entry

2 CallNonVirtualLongMethodV limited entry

2 CallNonVirtualLongMethodA limited entry

2 CallNonVirtualFloatMethod limited entry


2 CallNonVirtualFloatMethodV limited entry
2 CallNonVirtualFloatMethodA limited entry

2 CallNonVirtualDoubleMethod limited entry

2 CallNonVirtualDoubleMethodV limited entry

2 CallNonVirtualDoubleMethodA limited entry

2 CallNonVirtualVoidMethod limited entry

2 CallNonVirtualVoidMethodV limited entry

2 CallNonVirtualVoidMethodA limited entry

2 GetFieldID limited entry

returns ( byvalue type jfieldID ),
2 GetObjectField limited entry

( pointer byvalue, type jobject, type jfieldID )

2 GetBooleanField limited entry
2 GetByteField limited entry

2 GetCharField limited entry

2 GetShortField limited entry

2 GetIntField limited entry

2 GetLongField limited entry

2 GetFloatField limited entry

2 GetDoubleField limited entry

2 SetObjectField limited entry

( pointer byvalue, type jobject, type jfieldID,
type jobject )
2 SetBooleanField limited entry

type jboolean )
2 SetByteField limited entry

type jbyte )

2 SetCharField limited entry
type jchar )
2 SetShortField limited entry

type jshort )
2 SetIntField limited entry

type jint )
2 SetLongField limited entry

type jlong )
2 SetFloatField limited entry

type jfloat )
2 SetDoubleField limited entry

type jdouble )
2 GetStaticMethodID limited entry

returns ( byvalue type jmethodID ),
2 CallStaticObjectMethod limited entry

2 CallStaticObjectMethodV limited entry

( pointer byvalue, type jclass, list type jmethodID)
2 CallStaticObjectMethodA limited entry

pointer byvalue )

2 CallStaticBooleanMethod limited entry
2 CallStaticBooleanMethodV limited entry

2 CallStaticBooleanMethodA limited entry
pointer byvalue )
2 CallStaticByteMethod limited entry

2 CallStaticByteMethodV limited entry

2 CallStaticByteMethodA limited entry

pointer byvalue )
2 CallStaticCharMethod limited entry

2 CallStaticCharMethodV limited entry

2 CallStaticCharMethodA limited entry

pointer byvalue )
2 CallStaticShortMethod limited entry

2 CallStaticShortMethodV limited entry


2 CallStaticShortMethodA limited entry
pointer byvalue )
2 CallStaticIntMethod limited entry

2 CallStaticIntMethodV limited entry

2 CallStaticIntMethodA limited entry

pointer byvalue )
2 CallStaticLongMethod limited entry

2 CallStaticLongMethodV limited entry

2 CallStaticLongMethodA limited entry

pointer byvalue )
2 CallStaticFloatMethod limited entry

2 CallStaticFloatMethodV limited entry

2 CallStaticFloatMethodA limited entry

pointer byvalue )
2 CallStaticDoubleMethod limited entry


2 CallStaticDoubleMethodV limited entry
2 CallStaticDoubleMethodA limited entry

pointer byvalue )
2 CallStaticVoidMethod limited entry

2 CallStaticVoidMethodV limited entry

2 CallStaticVoidMethodA limited entry

pointer byvalue )
2 GetStaticFieldID limited entry

returns ( byvalue type jfieldID ),
2 GetStaticObjectField limited entry

( pointer byvalue, type jclass, type jfieldID )
2 GetStaticBooleanField limited entry

2 GetStaticByteField limited entry

2 GetStaticCharField limited entry

2 GetStaticShortField limited entry


2 GetStaticIntField limited entry
2 GetStaticLongField limited entry

2 GetStaticFloatField limited entry

2 GetStaticDoubleField limited entry

2 SetStaticObjectField limited entry

( pointer byvalue, type jclass, type jfieldID,
type jobject )
2 SetStaticBooleanField limited entry

type jboolean )
2 SetStaticByteField limited entry

type jbyte )
2 SetStaticCharField limited entry

type jchar )
2 SetStaticShortField limited entry

type jshort )
2 SetStaticIntField limited entry

type jint )

2 SetStaticLongField limited entry
type jlong )
2 SetStaticFloatField limited entry

type jfloat )
2 SetStaticDoubleField limited entry

type jdouble )
2 NewString limited entry

( pointer byvalue,
byaddr nonasgn wchar(]) varz,
type jint )
returns ( byvalue type jstring ),
2 GetStringLength limited entry

( pointer byvalue, type jstring )
returns ( byvalue type jsize ),
2 GetStringChars limited entry

( pointer byvalue, type jstring, byaddr type jboolean )
returns ( byvalue pointer ),
2 ReleaseStringChars limited entry

( pointer byvalue, type jstring,
byaddr nonasgn wchar(]) varz )
2 NewStringUTF limited entry

( pointer byvalue,
returns ( byvalue type jstring ),
2 GetStringUTFLength limited entry

( pointer byvalue, type jstring )
2 GetStringUTFChars limited entry

( pointer byvalue, type jstring, byaddr type jboolean)

2 ReleaseStringUTFChars limited entry
( pointer byvalue, type jstring,
2 GetArrayLength limited entry

( pointer byvalue, type jarray )
2 NewObjectArray limited entry

( pointer byvalue, type jsize, type jclass,
type jobject )
returns ( byvalue type jobjectArray ),
2 GetObjectArrayElement limited entry

( pointer byvalue, type jobjectArray, type jsize )
2 SetObjectArrayElement limited entry

( pointer byvalue, type jobjectArray, type jsize,
type jobject )
2 NewBooleanArray limited entry

( pointer byvalue, type jsize )
returns ( byvalue type jbooleanArray ),
2 NewByteArray limited entry

returns ( byvalue type jbyteArray ),
2 NewCharArray limited entry

returns ( byvalue type jcharArray ),
2 NewShortArray limited entry

returns ( byvalue type jshortArray ),
2 NewIntArray limited entry

returns ( byvalue type jintArray ),
2 NewLongArray limited entry

returns ( byvalue type jlongArray ),

2 NewFloatArray limited entry
returns ( byvalue type jfloatArray ),
2 NewDoubleArray limited entry

returns ( byvalue type jdoubleArray ),
2 GetBooleanArrayElements limited entry

( pointer byvalue, type jbooleanArray,
byaddr type jboolean )
2 GetByteArrayElements limited entry

( pointer byvalue, type jbyteArray,
2 GetCharArrayElements limited entry

( pointer byvalue, type jcharArray,
2 GetShortArrayElements limited entry

( pointer byvalue, type jshortArray,
2 GetIntArrayElements limited entry

( pointer byvalue, type jintArray,
2 GetLongArrayElements limited entry

( pointer byvalue, type jlongArray,
2 GetFloatArrayElements limited entry

( pointer byvalue, type jfloatArray,
2 GetDoubleArrayElements limited entry

( pointer byvalue, type jdoubleArray,

2 ReleaseBooleanArrayElements limited entry
( pointer byvalue, type jbooleanArray, type jboolean,
type jint )
2 ReleaseByteArrayElements limited entry

( pointer byvalue, type jbyteArray, type jbyte,
type jint )
2 ReleaseCharArrayElements limited entry

( pointer byvalue, type jcharArray, type jchar,
type jint )
2 ReleaseShortArrayElements limited entry

( pointer byvalue, type jshortArray, type jshort,
type jint )
2 ReleaseIntArrayElements limited entry

( pointer byvalue, type jintArray, type jint,
type jint )
2 ReleaseLongArrayElements limited entry

( pointer byvalue, type jlongArray, type jlong,
type jint )
2 ReleaseFloatArrayElements limited entry

( pointer byvalue, type jfloatArray, type jfloat,
type jint )
2 ReleaseDoubleArrayElements limited entry

( pointer byvalue, type jdoubleArray, type jdouble,
type jint )
2 GetBooleanArrayRegion limited entry

( pointer byvalue, type jbooleanArray, type jsize,
type jsize, type jboolean )
2 GetByteArrayRegion limited entry

( pointer byvalue, type jbyteArray, type jsize,
type jsize, type jbyte )

2 GetCharArrayRegion limited entry
( pointer byvalue, type jcharArray, type jsize,
type jsize, type jchar )
2 GetShortArrayRegion limited entry

( pointer byvalue, type jshortArray, type jsize,
type jsize, type jshort )
2 GetIntArrayRegion limited entry

( pointer byvalue, type jintArray, type jsize,
type jsize, type jint )
2 GetLongArrayRegion limited entry

( pointer byvalue, type jlongArray, type jsize,
type jsize, type jlong )
2 GetFloatArrayRegion limited entry

( pointer byvalue, type jfloatArray, type jsize,
type jsize, type jfloat )
2 GetDoubleArrayRegion limited entry

( pointer byvalue, type jdoubleArray, type jsize,
type jsize, type jdouble )
2 SetBooleanArrayRegion limited entry

( pointer byvalue, type jbooleanArray, type jsize,
type jsize, type jboolean )
2 SetByteArrayRegion limited entry

( pointer byvalue, type jbyteArray, type jsize,
type jsize, type jbyte )
2 SetCharArrayRegion limited entry

( pointer byvalue, type jcharArray, type jsize,
type jsize, type jchar )
2 SetShortArrayRegion limited entry

( pointer byvalue, type jshortArray, type jsize,
type jsize, type jshort )

2 SetIntArrayRegion limited entry
( pointer byvalue, type jintArray, type jsize,
type jsize, type jint )
2 SetLongArrayRegion limited entry

( pointer byvalue, type jlongArray, type jsize,
type jsize, type jlong )
2 SetFloatArrayRegion limited entry

( pointer byvalue, type jfloatArray, type jsize,
type jsize, type jfloat )
2 SetDoubleArrayRegion limited entry

( pointer byvalue, type jdoubleArray, type jsize,
type jsize, type jdouble )
2 RegisterNatives limited entry

( pointer byvalue, type jclass, pointer byvalue,
type jint )
2 UnregisterNatives limited entry

2 MonitorEnter limited entry

2 MonitorExit limited entry

2 GetJavaVM limited entry

( pointer byvalue, pointer byvalue )
returns ( byvalue type jint )
;

Part 6. Specialized programming tasks
Chapter 15. Using the SAX parser . . . . . . . . . . . . . . . . . . . . . . . . . 317
Overview . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 317
The PLISAXA built-in subroutine . . . . . . . . . . . . . . . . . . . . . . . . . . . 318
The PLISAXB built-in subroutine . . . . . . . . . . . . . . . . . . . . . . . . . . . 318
The SAX event structure . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 318
start_of_document . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 319
version_information . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 319
encoding_declaration . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 319
standalone_declaration . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 319
document_type_declaration . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 319
end_of_document . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 320
start_of_element . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 320
attribute_name . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 320
attribute_characters . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 320
attribute_predefined_reference . . . . . . . . . . . . . . . . . . . . . . . . . . . 320
attribute_character_reference . . . . . . . . . . . . . . . . . . . . . . . . . . . . 320
end_of_element . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 320
start_of_CDATA_section . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 321
end_of_CDATA_section . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 321
content_characters . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 321
content_predefined_reference . . . . . . . . . . . . . . . . . . . . . . . . . . . 321
content_character_reference . . . . . . . . . . . . . . . . . . . . . . . . . . . . 321
processing_instruction . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 321
comment . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 322
unknown_attribute_reference . . . . . . . . . . . . . . . . . . . . . . . . . . . . 322
unknown_content_reference . . . . . . . . . . . . . . . . . . . . . . . . . . . . 322
start_of_prefix_mapping . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 322
end_of_prefix_mapping . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 322
exception . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 322
Parameters to the event functions . . . . . . . . . . . . . . . . . . . . . . . . . 322
Coded character sets for XML documents . . . . . . . . . . . . . . . . . . . . . . 323
Supported EBCDIC code pages . . . . . . . . . . . . . . . . . . . . . . . . . . 324
Supported ASCII code pages . . . . . . . . . . . . . . . . . . . . . . . . . . . . 324
Specifying the code page . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 324
Using a number: . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 325
Using an alias . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 325
Exceptions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 325
Example . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 326
Exception codes . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 336
Chapter 16. Using PLIDUMP . . . . . . . . . . . . . . . . . . . . . . . . . . . . 342

PLIDUMP usage notes . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 343
Chapter 17. Interrupts and attention processing . . . . . . . . . . . . . . . . 345

Using ATTENTION ON-units . . . . . . . . . . . . . . . . . . . . . . . . . . . . 346
Interaction with a debugging tool . . . . . . . . . . . . . . . . . . . . . . . . . . 346
Chapter 18. Using the Checkpoint/Restart facility . . . . . . . . . . . . . . . 347

Requesting a checkpoint record . . . . . . . . . . . . . . . . . . . . . . . . . . . . 347
Defining the checkpoint data set . . . . . . . . . . . . . . . . . . . . . . . . . . 348

Requesting a restart . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 349
Automatic restart after a system failure . . . . . . . . . . . . . . . . . . . . . . 349
Automatic restart within a program . . . . . . . . . . . . . . . . . . . . . . . . 349
Getting a deferred restart . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 349
Modifying checkpoint/restart activity . . . . . . . . . . . . . . . . . . . . . . . . 350
Chapter 19. Using user exits . . . . . . . . . . . . . . . . . . . . . . . . . . . . 351

Procedures performed by the compiler user exit . . . . . . . . . . . . . . . . . . 351
Activating the compiler user exit . . . . . . . . . . . . . . . . . . . . . . . . . . . . 352
The IBM-supplied compiler exit, IBMUEXIT . . . . . . . . . . . . . . . . . . . 352
Customizing the compiler user exit . . . . . . . . . . . . . . . . . . . . . . . . 352
Modifying SYSUEXIT . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 352
Writing your own compiler exit . . . . . . . . . . . . . . . . . . . . . . . . . . . 353
Structure of global control blocks . . . . . . . . . . . . . . . . . . . . . . . . . 353
Writing the initialization procedure . . . . . . . . . . . . . . . . . . . . . . . . . 355
Writing the message filtering procedure . . . . . . . . . . . . . . . . . . . . . . 355
Writing the termination procedure . . . . . . . . . . . . . . . . . . . . . . . . . 356
Chapter 20. PL/I - Language Environment descriptors . . . . . . . . . . . . 357

Passing an argument . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 357
Argument passing by descriptor list . . . . . . . . . . . . . . . . . . . . . . . . 357
Argument passing by descriptor-locator . . . . . . . . . . . . . . . . . . . . . . 358
Descriptor header . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 358
String descriptors . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 359
Array descriptors . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 360

Chapter 15. Using the SAX parser
The compiler provides an interface called PLISAXx (x = A or B) that provides you
basic XML capability to PL/I. The support includes a high-speed XML parser,
which allows programs to consume inbound XML messages, check them for
well-formedness, and transform their contents to PL/I data structures.
The XML support does not provide XML generation, which must be instead be
accomplished by PL/I program logic.
The XML support has no special environmental requirements. It executes in all the
principal run-time environments, including CICS, IMS, and MQ Series, as well as
z/OS and OS/390 batch and TSO.
Overview
There are two major types of interfaces for XML parsing: event-based and
tree-based.
For an event-based API, the parser reports events to the application through
callbacks. Such events include: the start of the document, the beginning of an
element, etc. The application provides handlers to deal with the events reported by
the parser. The Simple API for XML or SAX is an example of an industry-standard
event-based API.
For a tree-based API (such as the Document Object Model or DOM), the parser
translates the XML into an internal tree-based representation. Interfaces are
provided to navigate the tree.
IBM Enterprise PL/I for z/OS and OS/390 Version 3 Release 1 provides a SAX-like
event-based interface for parsing XML documents. The parser invokes an
application-supplied handler for parser events, passing references to the
corresponding document fragments.
The parser has the following characteristics:

It provides high-performance, but non-standard interfaces.
It supports XML files encoded in either Unicode UTF-16 or any of several
single-byte code pages listed below.
The parser is non-validating, but does partially check well-formedness. See
section 2.5.10,
XML documents have two levels of conformance: well-formedness and validity, both
of which are defined in the XML standard, which you can find at
http://www.w3c.org/XML/. Recapitulating these definitions, an XML document is
well-formed if it complies with the basic XML grammar, and with a few specific
rules, such as the requirement that the names on start and end element tags must
match. A well-formed XML document is also valid if it has an associated document
type declaration (DTD) and if it complies with the constraints expressed in the DTD.
The XML parser is non-validating, but does partially check for well-formedness
errors, and generates exception events if it discovers any.

The PLISAXA built-in subroutine
The PLISAXA built-in subroutine allows you to invoke the XML parser for 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 the parser will pass back to the event
functions
x The address of the buffer containing the input XML
n The number of bytes of data in that buffer
c 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.
The PLISAXB built-in subroutine

The PLISAXB built-in subroutine allows you to invoke the XML parser for an XML
document residing in a file.

──PLISAXB(e,p,x─┬────┬─)───────────────────────────────────────────────────────

└─,c─┘
e An event structure
p A pointer value or "token" that the parser will pass back to the event
functions
x A character string expression specifying the input file
c The purported codepage of that XML
The SAX event structure

The event structure is a structure consisting of 24 LIMITED ENTRY variables which
point to functions that the parser will invoke for various "events".
The descriptions below of each event refer to the example of an XML document in
Figure 88 on page 319. In these descriptions, the term "XML text" refers to the
string based on the pointer and length passed to the event.

xmlDocument =
'<?xml version="1.K" standalone="yes"?>'
|| ''
|| '<sandwich>'
|| '<bread type="baker's best"/>'
|| '<?spread please use real mayonnaise ?>'
|| '<meat>Ham & turkey</meat>'
|| '<filling>Cheese, lettuce, tomato, etc.</filling>'
|| '<![CDATA[We should add a <relish> element in future!]]'
|| '</sandwich>'
|| 'junk';
Figure 88. Sample XML document
In the order of their appearance in this structure, the parser may recognize the
following events:
start_of_document
This event occurs once, at the beginning of parsing the document. The parser
passes the address and length of the entire document, including any line-control
characters, such as LF (Line Feed) or NL (New Line). For the above example, the
document is 305 characters in length.
version_information
This event occurs within the optional XML declaration for the version information.
The parser passes the address and length of the text containing the version value,
"1.0" in the example above.
encoding_declaration
This event occurs within the XML declaration for the optional encoding declaration.
The parser passes the address and length of the text containing the encoding
value.
standalone_declaration
This event occurs within the XML declaration for the optional standalone
declaration. The parser passes the address and length of the text containing the
standalone value, "yes" in the example above.
document_type_declaration
This event occurs when the parser finds a document type declaration. Document
type declarations begin with the character sequence "<!DOCTYPE" and end with a
">" character, with some fairly complicated grammar rules describing the content in
between. The parser passes the address and length of the text containing the
entire declaration, including the opening and closing character sequences, and is
the only event where XML text includes the delimiters. The example above does
not have a document type declaration.
Chapter 15. Using the SAX parser 319

end_of_document
This event occurs once, when document parsing has completed.
start_of_element
This event occurs once for each element start tag or empty element tag. The
parser passes the address and length of the text containing the element name. For
the first start_of_element event during parsing of the example, this would be the
string "sandwich".
attribute_name
This event occurs for each attribute in an element start tag or empty element tag,
after recognizing a valid name. The parser passes the address and length of the
text containing the attribute name. The only attribute name in the example is
"type".
attribute_characters
This event occurs for each fragment of an attribute value. The parser passes the
address and length of the text containing the fragment. An attribute value normally
consists of a single string only, even if it is split across lines:
<element attribute="This attribute value is
split across two lines"/>
The attribute value might consist of multiple pieces, however. For instance, the
value of the "type" attribute in the "sandwich" example at the beginning of the
section consists of three fragments: the string "baker", the single character "'" and
the string "s best". The parser passes these fragments as three separate events.
It passes each string, "baker" and "s best" in the example, as attribute_characters
events, and the single character "'" as an attribute_predefined_reference event,
described next.
attribute_predefined_reference
This event occurs in attribute values for the five pre-defined entity references
"&", "'", ">", "<" and """. The parser passes a CHAR(1) or
WIDECHAR(1) value that contains one of "&", "'", ">", "<" or '"', respectively.
attribute_character_reference
This event occurs in attribute values for numeric character references (Unicode
code points or "scalar values") of the form "&#dd;" or "&#xhh;", where "d" and "h"
represent decimal and hexadecimal digits, respectively. The parser passes a
FIXED BIN(31) value that contains the corresponding integer value.
end_of_element
This event occurs once for each element end tag or empty element tag when the
parser recognizes the closing angle bracket of the tag. The parser passes the
address and length of the text containing the element name.

start_of_CDATA_section
This event occurs at the start of a CDATA section. CDATA sections begin with the
string “<![CDATA[” and end with the string “]]”, and are used to "escape" blocks of
text containing characters that would otherwise be recognized as XML markup.
The parser passes the address and length of the text containing the opening
characters “<![CDATA[”. The parser passes the content of a CDATA section
between these delimiters as a single content-characters event. For the example, in
the above example, the content-characters event is passed the text "We should
add a <relish> element in future!".
end_of_CDATA_section
This event occurs when the parser recognizes the end of a CDATA section. The
parser passes the address and length of the text containing the closing character
sequence, “]]”.
content_characters
This event represents the "heart" of an XML document: the character data between
element start and end tags. The parser passes the address and length of the text
containing the this data, which usually consists of a single string only, even if it is
split across lines:
<element1>This character content is
split across two lines</element1>
If the content of an element includes any references or other elements, the

complete content may comprise several segments. For instance, the content of the
"meat" element in the example consists of the string "Ham ", the character "&" and
the string " turkey". Notice the trailing and leading spaces, respectively, in these
two string fragments. The parser passes these three content fragments as
separate events. It passes the string content fragments, "Ham " and " turkey", as
content_characters events, and the single "&" character as a
content_predefined_reference event. The parser also uses the content_characters
event to pass the text of CDATA sections to the application.
content_predefined_reference
This event occurs in element content for the five pre-defined entity references
"&", "'", ">", "<" and """. The parser passes a CHAR(1) or
WIDECHAR(1) value that contains one of "&", "'", ">", "<" or '"', respectively.
content_character_reference
This event occurs in element content for numeric character references (Unicode
code points or "scalar values") of the form "&#dd;" or "&#xhh;", where "d" and "h"
represent decimal and hexadecimal digits, respectively. The parser passes a
FIXED BIN(31) value that contains the corresponding integer value.
processing_instruction
Processing instructions (PIs) allow XML documents to contain special instructions
for applications. This event occurs when the parser recognizes the name following
the PI opening character sequence, "<?". The event also covers the data following
the processing instruction (PI) target, up to but not including the PI closing
character sequence, "?>". Trailing, but not leading white space characters in the

data are included. The parser passes the address and length of the text containing
the target, "spread" in the example, and the address and length of the text
containing the data, "please use real mayonnaise " in the example.
comment
This event occurs for any comments in the XML document. The parser passes the
address and length of the text between the opening and closing comment
delimiters, "", respectively. In the example, the text of the only
comment is "This document is just an example".
unknown_attribute_reference
This event occurs within attribute values for entity references other than the five
pre-defined entity references, listed for the event attribute_predefined_character.
The parser passes the address and length of the text containing the entity name.
unknown_content_reference
This event occurs within element content for entity references other than the five
pre-defined entity references listed for the content_predefined_character event.
The parser passes the address and length of the text containing the entity name.
start_of_prefix_mapping
This event is currently not generated.
end_of_prefix_mapping
This event is currently not generated.
exception
The parser generates this event when it detects an error in processing the XML
document.
Parameters to the event functions

All of these functions must return a BYVALUE FIXED BIN(31) value that is a return
code to the parser. For the parser to continue normally, this value should be zero.
All of these functions will be passed as the first argument a BYVALUE POINTER
that is the token value passed originally as the second argument to the built-in
function.
With the following exceptions, all of the functions will also be passed a BYVALUE
POINTER and a BYVALUE FIXED BIN(31) that supply the address and length of
the text element for the event. The functions/events that are different are:
end_of_document
No argument other than the user token is passed.
attribute_predefined_reference
In addition to the user token, one additional argument is passed: a BYVALUE
CHAR(1) or, for a UTF-16 document, a BYVALUE WIDECHAR(1) that holds
the value of the predefined character.

content_predefined_reference
CHAR(1) or, for a UTF-16 document, a BYVALUE WIDECHAR(1) that holds
the value of the predefined character.
attribute_character_reference
FIXED BIN(31) that holds the value of the numeric reference.
content_character_reference
FIXED BIN(31) that holds the value of the numeric reference.
processing_instruction
In addition to the user token, four additional arguments are passed:
1. a BYVALUE POINTER that is the address of the target text

2. a BYVALUE FIXED BIN(31) that is the length of the target text
3. a BYVALUE POINTER that is the address of the data text
4. a BYVALUE FIXED BIN(31) that is the length of the data text
exception
In addition to the user token, three additional arguments are passed:
1. a BYVALUE POINTER that is the address of the offending text

2. a BYVALUE FIXED BIN(31) that is the byte offset of the offending text
within the document
3. a BYVALUE FIXED BIN(31) that is the value of the exception code
Coded character sets for XML documents

The PLISAX built-in subroutine supports only XML documents in WIDECHAR
encoded using Unicode UTF-16, or in CHARACTER encoded using one of the
explicitly supported single-byte character sets listed below. The parser uses up to
three sources of information about the encoding of your XML document, and
signals an exception XML event if it discovers any conflicts between these sources:
1. The parser determines the basic encoding of a document by inspecting its
initial characters.
2. If step 1 succeeds, the parser then looks for any encoding declaration.
3. Finally, it refers to the codepage value on the PLISAX built-in subroutine call. If
this parameter was omitted, it defaults to the value provided by the
CODEPAGE compiler option value that you specified explicitly or by default.
If the XML document begins with an XML declaration that includes an encoding
declaration specifying one of the supported code pages listed below, the parser
honors the encoding declaration if it does not conflict with either the basic
document encoding or the encoding information from the PLISAX built-in
subroutine. If the XML document does not have an XML declaration at all, or if the
XML declaration omits the encoding declaration, the parser uses the encoding
information from the PLISAX built-in subroutine to process the document, as long
as it does not conflict with the basic document encoding.

Supported EBCDIC code pages
In the following table, the first number is for the Euro Country Extended Code Page
(ECECP), and the second is for Country Extended Code Page (CECP).
CCSID Description
01047 Latin 1 / Open Systems
01140, 00037 USA, Canada, etc.
01141, 00273 Austria, Germany
01142, 00277 Denmark, Norway
01143, 00278 Finland, Sweden
01144, 00280 Italy
01145, 00284 Spain, Latin America (Spanish)
01146, 00285 UK
01147, 00297 France
01148, 00500 International
01149, 00871 Iceland
Supported ASCII code pages

CCSID Description
00813 ISO 8859-7 Greek / Latin
00819 ISO 8859-1 Latin 1 / Open Systems
00920 ISO 8859-9 Latin 5 (ECMA-128, Turkey TS-5881)
Specifying the code page

If your document does not include an encoding declaration in the XML declaration,
or does not have an XML declaration at all, the parser uses the encoding
information provided by the PLISAX built-in subroutine call in conjunction with the
basic encoding of the document.
You can also specify the encoding information for the document in the XML
declaration, with which most XML documents begin. An example of an XML
declaration that includes an encoding declaration is:
<?xml version="1.K" encoding="ibm-114K"?>
If your XML document includes an encoding declaration, ensure that it is consistent

with the encoding information provided by the PLISAX built-in subroutine and with
the basic encoding of the document. If there is any conflict between the encoding
declaration, the encoding information provided by the PLISAX built-in subroutine
and the basic encoding of the document, the parser signals an exception XML
event.
Specify the encoding declaration as follows:

Using a number:
You can specify the CCSID number (with or without any number of leading zeroes),
prefixed by any of the following (in any mixture of upper or lower case):
IBM_ CP CCSID_
IBM- CP_ CCSID-
CP-
Using an alias
You can use any of the following supported aliases (in any mixture of lower and
upper case):
Code page Supported aliases

037 EBCDIC-CP-US, EBCDIC-CP-CA, EBCDIC-CP-WT, EBCDIC-CP-NL
500 EBCDIC-CP-BE, EBCDIC-CP-CH
813 ISO-8859-7, ISO_8859-7
819 ISO-8859-1, ISO_8859-1
920 ISO-8859-9, ISO_8859-9
1200 UTF-16
Exceptions
For most exceptions, the XML text contains the part of the document that was
parsed up to and including the point where the exception was detected. For
encoding conflict exceptions, which are signaled before parsing begins, the length
of the XML text is either zero or the XML text contains just the encoding declaration
value from the document. The example above contains one item that causes an
exception event, the superfluous "junk" following the "sandwich" element end tag.
There are two kinds of exceptions:

1. Exceptions that allow you to continue parsing optionally. Continuable
exceptions have exception codes in the range 1 through 99, 100,001 through
165,535, or 200,001 to 265,535. The exception event in the example above
has an exception number of 1 and thus is continuable.
2. Fatal exceptions, which don't allow continuation. Fatal exceptions have
exception codes greater than 99 (but less than 100,000).
Returning from the exception event function with a non-zero return code normally
causes the parser to stop processing the document, and return control to the
program that invoked the PLISAXA or PLISAXB built-in subroutine.
For continuable exceptions, returning from the exception event function with a zero
return code requests the parser to continue processing the document, although
further exceptions might subsequently occur. See section 2.5.6.1, "Continuable
exceptions" for details of the actions that the parser takes when you request
continuation.
A special case applies to exceptions with exception numbers in the ranges 100,001
through 165,535 and 200,001 through 265,535. These ranges of exception codes
indicate that the document's CCSID (determined by examining the beginning of the
document, including any encoding declaration) is not identical to the CCSID value

provided (explicitly or implicitly) by the PLISAXA or PLISAXB built-in subroutine,
even if both CCSIDs are for the same basic encoding, EBCDIC or ASCII.
For these exceptions, the exception code passed to the exception event contains
the document's CCSID, plus 100,000 for EBCDIC CCSIDs, or 200,000 for ASCII
CCSIDs. For instance, if the exception code contains 101,140, the document s
CCSID is 01140. The CCSID value provided by the PLISAXA or PLISAXB built-in
subroutine is either set explicitly as the last argument on the call or implicitly when
the last argument is omitted and the value of the CODEPAGE compiler option is
used.
Depending on the value of the return code after returning from the exception event
function for these CCSID conflict exceptions, the parser takes one of three actions:
1. If the return code is zero, the parser proceeds using the CCSID provided by the
built-in subroutine.
2. If the return code contains the document's CCSID (that is, the original
exception code value minus 100,000 or 200,000), the parser proceeds using
the document s CCSID. This is the only case where the parser continues after
a non-zero value is returned from one of the parsing events.
3. Otherwise, the parser stops processing the document, and returns control to
the PLISAXA or PLISAXB built-in subroutine which will raise the ERROR
condition.
Example
The following example illustrates the use of the PLISAXA built-in subroutine and
uses the example XML document cited above:

saxtest: package exports(saxtest);
define alias event

limited entry( pointer, pointer, fixed bin(31) )
options( byvalue );
define alias event_end_of_document

limited entry( pointer )
options( byvalue );
define alias event_predefined_ref

limited entry( pointer, char(1) )
define alias event_character_ref

limited entry( pointer, fixed bin(31) )
options( byvalue );
define alias event_pi

limited entry( pointer, pointer, fixed bin(31),
pointer, fixed bin(31) )
options( byvalue );
define alias event_exception

limited entry( pointer, pointer, fixed bin(31),
fixed bin(31) )
options( byvalue );
Figure 89. PLISAXA coding example - type declarations

saxtest: proc options( main );
dcl
1 eventHandler static
,2 eK1 type event

init( start_of_document )
,2 eK2 type event
init( version_information )
,2 eK3 type event
init( encoding_declaration )
,2 eK4 type event
init( standalone_declaration )
,2 eK5 type event
init( document_type_declaration )
,2 eK6 type event_end_of_document
init( end_of_document )
,2 eK7 type event
init( start_of_element )
,2 eK8 type event
init( attribute_name )
,2 eK9 type event
init( attribute_characters )
,2 e1K type event_predefined_ref
init( attribute_predefined_reference )
,2 e11 type event_character_ref
init( attribute_character_reference )
,2 e12 type event
init( end_of_element )
,2 e13 type event
init( start_of_CDATA )
,2 e14 type event
init( end_of_CDATA )
,2 e15 type event
init( content_characters )
,2 e16 type event_predefined_ref
init( content_predefined_reference )
,2 e17 type event_character_ref
init( content_character_reference )
,2 e18 type event_pi
init( processing_instruction )
,2 e19 type event
init( comment )
,2 e2K type event
init( unknown_attribute_reference )
,2 e21 type event
init( unknown_content_reference )
,2 e22 type event
init( start_of_prefix_mapping )
,2 e23 type event
init( end_of_prefix_mapping )
,2 e24 type event_exception
init( exception )
;
Figure 90. PLISAXA coding example - event structure

dcl token char(8);
dcl xmlDocument char(4KKK) var;
xmlDocument =
'<?xml version="1.K" standalone="yes"?>'
|| ''
|| '<sandwich>'
|| '<bread type="baker's best"/>'
|| '<?spread please use real mayonnaise ?>'
|| '<meat>Ham & turkey</meat>'
|| '<filling>Cheese, lettuce, tomato, etc.</filling>'
|| '<![CDATA[We should add a <relish> element in future!]]'.
|| '</sandwich>'
|| 'junk';
call plisaxa( eventHandler,

addr(token),
addrdata(xmlDocument),
length(xmlDocument) );
end;
Figure 91. PLISAXA coding example - main routine

dcl chars char(32KKK) based;
start_of_document:
proc( userToken, xmlToken, TokenLength )
options( byvalue );
dcl userToken pointer;

dcl xmlToken pointer;
dcl tokenLength fixed bin(31);
put skip list( lowercase( procname() )

|| ' length=' || tokenlength );
return(K);
end;
version_information:
options( byvalue );


|| ' <' || substr(xmltoken->chars,1,tokenlength ) || '>' );
return(K);
end;
encoding_declaration:
options( byvalue );


return(K);
end;
standalone_declaration:
options( byvalue );


return(K);
end;
Figure 92 (Part 1 of 6). PLISAXA coding example - event routines

document_type_declaration:
options( byvalue );


return(K);
end;
end_of_document:
proc( userToken )
options( byvalue );
put skip list( lowercase( procname() ) );
return(K);
end;
start_of_element:
options( byvalue );


return(K);
end;
attribute_name:
options( byvalue );


return(K);
end;

attribute_characters:
options( byvalue );


return(K);
end;
attribute_predefined_reference:
proc( userToken, reference )

dcl reference char(1);

|| ' ' || hex(reference ) );
return(K);
end;
attribute_character_reference:
options( byvalue );

dcl reference fixed bin(31);

|| ' <' || hex(reference ) );
return(K);
end;
end_of_element:
options( byvalue );


return(K);
end;

start_of_CDATA:
options( byvalue );


return(K);
end;
end_of_CDATA:
options( byvalue );


return(K);
end;
content_characters:
options( byvalue );


return(K);
end;
content_predefined_reference:

dcl reference char(1);

|| ' ' || hex(reference ) );
return(K);
end;

content_character_reference:
options( byvalue );

dcl reference fixed bin(31);

|| ' <' || hex(reference ) );
return(K);
end;
processing_instruction:
proc( userToken, piTarget, piTargetLength,
piData, piDataLength )
options( byvalue );

dcl piTarget pointer;
dcl piTargetLength fixed bin(31);
dcl piData pointer;
dcl piDataLength fixed bin(31);

|| ' <' || substr(piTarget->chars,1,piTargetLength ) || '>' );
return(K);
end;
comment:
options( byvalue );


return(K);
end;
unknown_attribute_reference:
options( byvalue );


return(K);
end;

unknown_content_reference:
options( byvalue );


return(K);
end;
start_of_prefix_mapping:
options( byvalue );


return(K);
end;
end_of_prefix_mapping:
options( byvalue );


return(K);
end;
exception:
proc( userToken, xmlToken, currentOffset, errorID )
options( byvalue );

dcl currentOffset fixed bin(31);
dcl errorID fixed bin(31);

|| ' errorid =' || errorid );
return(K);
end;
The preceding program would produce the following output:

start_of_dcoument length= 3K5
version_information <1.K>
standalone_declaration <yes>
comment <This document is just an example>
start_of_element <sandwich>
start_of_element <bread>
attribute_name <type>
attribute_characters <baker>
attribute_predefined_reference 7D
attribute_characters <s best>
end_of_element <bread>
processing_instruction <spread>
start_of_element <meat>
content_characters <Ham >
content_predefined_reference 5K
content_characters < turkey>
end_of_element <meat>
start_of_element <filling>
content_characters <Cheese, lettuce, tomato, etc.>
end_of_element <filling>
start_of_cdata <<![CDATA[>
content_characters <We should add a <relish> element in future!>
end_of_cdata <]]>
end_of_element <sandwich>
exception errorid = 1
content_characters <j>
content_characters <u>
content_characters <n>
content_characters <k>
end_of_document
Figure 93. PLISAXA coding example - program output
Exception codes
For each value of the exception code parameter passed to the exception event
(listed under the heading "Number"), the following table describes the exception,
and the actions that the parser takes when you request it to continue after the
exception. In these descriptions, the term "XML text" refers to the string based on
the pointer and length passed to the event.
Table 31 (Page 1 of 4). Continuable Exceptions

Number Description Parser Action on Continuation
1 The parser found an invalid character while scanning The parser generates a content_characters event with
white space outside element content. XML text containing the (single) invalid character.
Parsing continues at the character after the invalid
character.
2 The parser found an invalid start of a processing The parser generates a content_characters event with
instruction, element, comment or document type the XML text containing the 2- or 3-character invalid
declaration outside element content. initial character sequence. Parsing continues at the
character after the invalid sequence.
3 The parser found a duplicate attribute name. The parser generates an attribute_name event with the
XML text containing the duplicate attribute name.

4 The parser found the markup character "<" in an Prior to generating the exception event, the parser
attribute value. generates an attribute_characters event for any part of
the attribute value prior to the "<" character. After the
exception event, the parser generates an
attribute_characters event with XML text containing "<".
Parsing then continues at the character after the "<".
5 The start and end tag names of an element did not The parser generates an end_of_element event with
match. XML text containing the mismatched end name.
6 The parser found an invalid character in element The parser includes the invalid character in XML text for
content. the subsequent content_characters event.
7 The parser found an invalid start of an element, Prior to generating the exception event, the parser
comment, processing instruction or CDATA section in generates a content_characters event for any part of the
element content. content prior to the "<" markup character. After the
exception event, the parser generates a
content_characters event with XML text containing 2
characters: the "<" followed by the invalid character.
Parsing continues at the character after the invalid
character.
8 The parser found in element content the CDATA Prior to generating the exception event, the parser
closing character sequence “]]” without the matching generates a content_characters event for any part of the
opening character sequence “<![CDATA[”. content prior to the “]]” character sequence. After the
exception event, the parser generates a
content_characters event with XML text containing the
3-character sequence “]]”. Parsing continues at the
character after this sequence.
9 The parser found an invalid character in a comment. The parser includes the invalid character in XML text for
the subsequent comment event.
10 The parser found in a comment the character The parser assumes that the "--" character sequence
sequence "--" not followed by ">". terminates the comment, and generates a comment
event. Parsing continues at the character after the "--"
sequence.
11 The parser found an invalid character in a processing The parser includes the invalid character in XML text for
instruction data segment. the subsequent processing_instruction event.
12 A processing instruction target name was "xml" in The parser generates a processing_instruction event
lower-case, upper-case or mixed-case. with XML text containing "xml" in the original case.
13 The parser found an invalid digit in a hexadecimal The parser generates an attribute_characters or
character reference (of the form &#xdddd;). content_characters event with XML text containing the
invalid digit. Parsing of the reference continues at the
character after this invalid digit.
14 The parser found an invalid digit in a decimal The parser generates an attribute_characters or
character reference (of the form &#dddd;). content_characters event with XML text containing the
invalid digit. Parsing of the reference continues at the
character after this invalid digit.
15 The encoding declaration value in the XML The parser generates the encoding event with XML text
declaration did not begin with lower- or upper-case A containing the encoding declaration value as it was
through Z specified.
16 A character reference did not refer to a legal XML The parser generates an attribute_character_reference
character. or content_character_reference event with XML-NTEXT
containing the single Unicode character specified by the
character reference.
17 The parser found an invalid character in an entity The parser includes the invalid character in the XML
reference name. text for the subsequent unknown_attribute_reference or
unknown_content_reference event.
18 The parser found an invalid character in an attribute The parser includes the invalid character in XML text for
value. the subsequent attribute_characters event.

50 The document was encoded in EBCDIC, and the The parser uses the encoding specified by the
CODEPAGE compiler option specified a supported CODEPAGE compiler option.
EBCDIC code page, but the document encoding
declaration did not specify a recognizable encoding.
document encoding declaration specified a supported document encoding declaration.
EBCDIC encoding, but the parser does not support
the code page specified by the CODEPAGE compiler
option.
declaration specified an ASCII encoding.
declaration specified a supported Unicode encoding.
declaration specified a Unicode encoding that the
parser does not support.
declaration specified an encoding that the parser does
not support.
56 The document was encoded in ASCII, and the The parser uses the encoding specified by the
ASCII code page, but the document encoding
declaration did not specify a recognizable encoding.
document encoding declaration specified a supported document encoding declaration.
ASCII encoding, but the parser does not support the
code page specified by the CODEPAGE compiler
option.
declaration specified a supported EBCDIC encoding.
declaration specified a supported Unicode encoding.
declaration specified a Unicode encoding that the
parser does not support.
declaration specified an encoding that the parser does
not support.

100,001 The document was encoded in EBCDIC, and the If you return zero from the exception event, the parser
through encodings specified by the CODEPAGE compiler uses the encoding specified by the CODEPAGE
165,535 option and the document encoding declaration are compiler option. If you return the CCSID from the
both supported EBCDIC code pages, but are not the document encoding declaration (by subtracting 100,000
same. The exception code contains the CCSID for from the exception code), the parser uses this encoding.
the encoding declaration plus 100,000.
200,001 The document was encoded in ASCII, and the If you return zero from the exception event, the parser
through encodings specified by the CODEPAGE compiler uses the encoding specified by the CODEPAGE
265,535 option and the document encoding declaration are compiler option. If you return the CCSID from the
both supported ASCII code pages, but are not the document encoding declaration (by subtracting 200,000
same. The exception code contains the CCSID for from the exception code), the parser uses this encoding.
the encoding declaration plus 200,000.
Table 32 (Page 1 of 3). Terminating Exceptions

Number Description
100 The parser reached the end of the document while scanning the start of the XML declaration.
101 The parser reached the end of the document while looking for the end of the XML declaration.
102 The parser reached the end of the document while looking for the root element.
103 The parser reached the end of the document while looking for the version information in the XML declaration.
104 The parser reached the end of the document while looking for the version information value in the XML declaration.
106 The parser reached the end of the document while looking for the encoding declaration value in the XML
declaration.
108 The parser reached the end of the document while looking for the standalone declaration value in the XML
declaration.
109 The parser reached the end of the document while scanning an attribute name.
110 The parser reached the end of the document while scanning an attribute value.
111 The parser reached the end of the document while scanning a character reference or entity reference in an
attribute value.
112 The parser reached the end of the document while scanning an empty element tag.
113 The parser reached the end of the document while scanning the root element name.
114 The parser reached the end of the document while scanning an element name.
115 The parser reached the end of the document while scanning character data in element content.
116 The parser reached the end of the document while scanning a processing instruction in element content.
117 The parser reached the end of the document while scanning a comment or CDATA section in element content.
118 The parser reached the end of the document while scanning a comment in element content.
119 The parser reached the end of the document while scanning a CDATA section in element content.
120 The parser reached the end of the document while scanning a character reference or entity reference in element
content.
121 The parser reached the end of the document while scanning after the close of the root element.
122 The parser found a possible invalid start of a document type declaration.
123 The parser found a second document type declaration.
124 The first character of the root element name was not a letter, '_' or ':'.
125 The first character of the first attribute name of an element was not a letter, '_' or ':'.
126 The parser found an invalid character either in or following an element name.
127 The parser found a character other than '=' following an attribute name.
128 The parser found an invalid attribute value delimiter.
130 The first character of an attribute name was not a letter, '_' or ':'.

Number Description
131 The parser found an invalid character either in or following an attribute name.
132 An empty element tag was not terminated by a '>' following the '/'.
133 The first character of an element end tag name was not a letter, '_' or ':'.
134 An element end tag name was not terminated by a '>'.
135 The first character of an element name was not a letter, '_' or ':'.
136 The parser found an invalid start of a comment or CDATA section in element content.
137 The parser found an invalid start of a comment.
138 The first character of a processing instruction target name was not a letter, '_' or ':'.
139 The parser found an invalid character in or following a processing instruction target name.
140 A processing instruction was not terminated by the closing character sequence '?>'.
141 The parser found an invalid character following '&' in a character reference or entity reference.
142 The version information was not present in the XML declaration.
143 'version' in the XML declaration was not followed by a '='.
144 The version declaration value in the XML declaration is either missing or improperly delimited.
145 The version information value in the XML declaration specified a bad character, or the start and end delimiters did
not match.
146 The parser found an invalid character following the version information value closing delimiter in the XML
declaration.
147 The parser found an invalid attribute instead of the optional encoding declaration in the XML declaration.
148 'encoding' in the XML declaration was not followed by a '='.
149 The encoding declaration value in the XML declaration is either missing or improperly delimited.
150 The encoding declaration value in the XML declaration specified a bad character, or the start and end delimiters
did not match.
151 The parser found an invalid character following the encoding declaration value closing delimiter in the XML
declaration.
152 The parser found an invalid attribute instead of the optional standalone declaration in the XML declaration.
153 'standalone' in the XML declaration was not followed by a '='.
154 The standalone declaration value in the XML declaration is either missing or improperly delimited.
155 The standalone declaration value was neither 'yes' nor 'no' only.
156 The standalone declaration value in the XML declaration specified a bad character, or the start and end delimiters
did not match.
157 The parser found an invalid character following the standalone declaration value closing delimiter in the XML
declaration.
158 The XML declaration was not terminated by the proper character sequence '?>', or contained an invalid attribute.
159 The parser found the start of a document type declaration after the end of the root element.
160 The parser found the start of an element after the end of the root element.
300 The document was encoded in EBCDIC, but the CODEPAGE compiler option specified a supported ASCII code
page.
301 The document was encoded in EBCDIC, but the CODEPAGE compiler option specified Unicode.
302 The document was encoded in EBCDIC, but the CODEPAGE compiler option specified an unsupported code page.
303 The document was encoded in EBCDIC, but the CODEPAGE compiler option is unsupported and the document
encoding declaration was either empty or contained an unsupported alphabetic encoding alias.
did not contain an encoding declaration.
encoding declaration did not specify a supported EBCDIC encoding.

Number Description
306 The document was encoded in ASCII, but the CODEPAGE compiler option specified a supported EBCDIC code
page.
307 The document was encoded in ASCII, but the CODEPAGE compiler option specified Unicode.
308 The document was encoded in ASCII, but the CODEPAGE compiler option did not specify a supported EBCDIC
code page, ASCII or Unicode.
309 The CODEPAGE compiler option specified a supported ASCII code page, but the document was encoded in
Unicode.
310 The CODEPAGE compiler option specified a supported EBCDIC code page, but the document was encoded in
Unicode.
311 The CODEPAGE compiler option specified an unsupported code page, but the document was encoded in Unicode.
312 The document was encoded in ASCII, but both the encodings provided externally and within the document
encoding declaration are unsupported.
313 The document was encoded in ASCII, but the CODEPAGE compiler option is unsupported and the document did
not contain an encoding declaration.
314 The document was encoded in ASCII, but the CODEPAGE compiler option is unsupported and the document
encoding declaration did not specify a supported ASCII encoding.
315 The document was encoded in UTF-16 Little Endian, which the parser does not support on this platform.
316 The document was encoded in UCS4, which the parser does not support.
317 The parser cannot determine the document encoding. The document may be damaged.
318 The document was encoded in UTF-8, which the parser does not support.
319 The document was encoded in UTF-16 Big Endian, which the parser does not support on this platform.
500 Internal error. Please report the error to your service representative.
to
99,999

Chapter 16. Using PLIDUMP
This section provides information about dump options and the syntax used to call
PLIDUMP, and describes PL/I-specific information included in the dump that can
help you debug your routine.
Note: PLIDUMP conforms to National Language Support standards.
Figure 94 shows an example of a PL/I routine calling PLIDUMP to produce an

Language Environment for OS/390 & VM dump. In this example, the main routine
PLIDMP calls PLIDMPA, which then calls PLIDMPB. The call to PLIDUMP is made
in routine PLIDMPB.
%PROCESS MAP GOSTMT SOURCE STG LIST OFFSET LC(1K1);

PLIDMP: PROC OPTIONS(MAIN) ;
Declare (H,I) Fixed bin(31) Auto;

Declare Names Char(17) Static init('Bob Teri Bo Jason');
H = 5; I = 9;
Put skip list('PLIDMP Starting');
Call PLIDMPA;
PLIDMPA: PROC;
Declare (a,b) Fixed bin(31) Auto;
a = 1; b = 3;
Put skip list('PLIDMPA Starting');
Call PLIDMPB;
PLIDMPB: PROC;
Declare 1 Name auto,
2 First Char(12) Varying,
2 Last Char(12) Varying;
First = 'Teri';
Last = 'Gillispy';
Put skip list('PLIDMPB Starting');
Call PLIDUMP('TBFC','PLIDUMP called from procedure PLIDMPB');
Put Data;
End PLIDMPB;
End PLIDMPA;
End PLIDMP;
Figure 94. Example PL/I routine calling PLIDUMP
The syntax and options for PLIDUMP are shown below.
──PLIDUMP──(──character-string-expression 1──,──character-string-expression 2───

──)─────────────────────────────────────────────────────────────────────────────

character-string-expression 1
is a dump options character string consisting of one or more of the following:
B BLOCKS (PL/I hexadecimal dump).

C Continue. The routine continues after the dump.
F FILES.

H STORAGE.
Note: A ddname of CEESNAP must be specified with the H option
to produce a SNAP dump of a PL/I routine.
K BLOCKS (when running under CICS). The Transaction Work Area
is included.
NB NOBLOCKS.
NF NOFILES.
NH NOSTORAGE.
NK NOBLOCKS (when running under CICS).
NT NOTRACEBACK.
S Stop. The enclave is terminated with a dump.
T TRACEBACK.
T, F, and C are the default options.
character-string-expression 2
is a user-identified character string up to 80 characters long that is printed as
the dump header.
PLIDUMP usage notes

If you use PLIDUMP, the following considerations apply:
If a routine calls PLIDUMP a number of times, use a unique user-identifier for
each PLIDUMP invocation. This simplifies identifying the beginning of each
dump.
A DD statement with the ddname PLIDUMP, PL1DUMP, or CEEDUMP can be
used to define the data set for the dump.
The data set defined by the PLIDUMP, PL1DUMP, or CEEDUMP DD statement
should specify a logical record length (LRECL) of at least 133 to prevent dump
records from wrapping. If SYSOUT is used as the target in any one of these
DDs, you must specify MSGFILE(SYSOUT,FBA,133,0) or
MSGFILE(SYSOUT,VBA,137,0) to ensure that the lines are not wrapped.
When you specify the H option in a call to PLIDUMP, the PL/I library issues an
OS SNAP macro to obtain a dump of virtual storage. The first invocation of
PLIDUMP results in a SNAP identifier of 0. For each successive invocation,
the ID is increased by one to a maximum of 256, after which the ID is reset to
0.
Support for SNAP dumps using PLIDUMP is provided only under OS/390.
SNAP dumps are not produced in a CICS environment.
– If the SNAP is not successful, the CEE3DMP DUMP file displays the
message:
Snap was unsuccessful
– If the SNAP is successful, CEE3DMP displays the message:
Snap was successful; snap ID = nnn
where nnn corresponds to the SNAP identifier described above. An
unsuccessful SNAP does not result in an incrementation of the identifier.
Chapter 16. Using PLIDUMP 343

If you want to ensure portability across system platforms, use PLIDUMP to
generate a dump of your PL/I routine.

Chapter 17. Interrupts and attention processing
To enable a PL/I program to recognize attention interrupts, two operations must be
possible:
You must be able to create an interrupt. This is done in different ways
depending upon both the terminal you use and the operating system.
Your program must be prepared to respond to the interrupt. You can write an
ON ATTENTION statement in your program so that the program receives
control when the ATTENTION condition is raised.
Note: If the program has an ATTENTION ON-unit that you want invoked, you
must compile the program with either of the following:
– The INTERRUPT option (supported only in TSO)
– A TEST option other than NOTEST or TEST(NONE,NOSYM).
Compiling this way causes INTERRUPT(ON) to be in effect, unless
you explicitly specify INTERRUPT(OFF) in PLIXOPT.
You can find the procedure used to create an interrupt in the IBM instruction
manual for the operating system and terminal that you are using.
There is a difference between the interrupt (the operating system recognized your
request) and the raising of the ATTENTION condition.
An interrupt is your request that the operating system notify the running program. If
a PL/I program was compiled with the INTERRUPT compile-time option,
instructions are included that test an internal interrupt switch at discrete points in
the program. The internal interrupt switch can be set if any program in the load
module was compiled with the INTERRUPT compile-time option.
The internal switch is set when the operating system recognizes that an interrupt
request was made. The execution of the special testing instructions (polling) raises
the ATTENTION condition. If a debugging tool hook (or a CALL PLITEST) is
encountered before the polling occurs, the debugging tool can be given control
before the ATTENTION condition processing starts.
Polling ensures that the ATTENTION condition is raised between PL/I statements,
rather than within the statements.
Figure 95 on page 346 shows a skeleton program, an ATTENTION ON-unit, and

several situations where polling instructions will be generated. In the program
polling will occur at:
LABEL1
Each iteration of the DO
The ELSE PUT SKIP ... statement
Block END statements

%PROCESS INTERRUPT;
.
.
.
ON ATTENTION
BEGIN;
DCL X FIXED BINARY(15);
PUT SKIP LIST ('Enter 1 to terminate, K to continue.');
GET SKIP LIST (X);
IF X = 1 THEN
STOP;
ELSE
PUT SKIP LIST ('Attention was ignored');
END;
.
.
.
LABEL1:
IF EMPNO ...
.
.
.
DO I = 1 TO 1K;
.
.
.
END;
.
.
.
Figure 95. Using an ATTENTION ON-unit
Using ATTENTION ON-units

You can use processing within the ATTENTION ON-unit to terminate potentially
endless looping in a program.
Control is given to an ATTENTION ON-unit when polling instructions recognize that

an interrupt has occurred. Normal return from the ON-unit is to the statement
following the polling code.
Interaction with a debugging tool

If the program has the TEST(ALL) or TEST(ERROR) run-time option in effect, an
interrupt causes the debugging tool to receive control the next time a hook is
encountered. This might be before the program's polling code recognizes that the
interrupt occurred.
Later, when the ATTENTION condition is raised, the debugging tool receives
control again for condition processing.

Chapter 18. Using the Checkpoint/Restart facility
This chapter describes the PL/I Checkpoint/Restart feature which provides a
convenient method of taking checkpoints during the execution of a long-running
program in a batch environment.
At points specified in the program, information about the current status of the
program is written as a record on a data set. If the program terminates due to a
system failure, you can use this information to restart the program close to the point
where the failure occurred, avoiding the need to rerun the program completely.
This restart can be either automatic or deferred. An automatic restart is one that
takes place immediately (provided the operator authorizes it when requested by a
system message). A deferred restart is one that is performed later as a new job.
You can request an automatic restart from within your program without a system
failure having occurred.
PL/I Checkpoint/Restart uses the Advanced Checkpoint/Restart Facility of the

operating system. This facility is described in the books listed in “Bibliography” on
page 363.
To use checkpoint/restart you must do the following:

Request, at suitable points in your program, that a checkpoint record is written.
This is done with the built-in subroutine PLICKPT.
Provide a data set on which the checkpoint record can be written.
Also, to ensure the desired restart activity, you might need to specify the RD
parameter in the EXEC or JOB statement (see OS/390 JCL Reference).
Note: You should be aware of the restrictions affecting data sets used by your
program. These are detailed in the “Bibliography” on page 363.
Requesting a checkpoint record

Each time you want a checkpoint record to be written, you must invoke, from your
PL/I program, the built-in subroutine PLICKPT.
──CALL──PLICKPT──┬────────────────────────────────────────────────────────┬────

└─(──ddname──┬──────────────────────────────────────┬──)─┘
└─,──check-id──┬─────────────────────┬─┘
└─,──org──┬─────────┬─┘
└─,──code─┘
The four arguments are all optional. If you do not use an argument, you need not
specify it unless you specify another argument that follows it in the given order. In
this case, you must specify the unused argument as a null string (''). The
following paragraphs describe the arguments.
ddname
is a character string constant or variable specifying the name of the DD
statement defining the data set that is to be used for checkpoint records. If you
omit this argument, the system will use the default ddname SYSCHK.

check-id
is a character string constant or variable specifying the name that you want to
assign to the checkpoint record so that you can identify it later. If you omit this
argument, the system will supply a unique identification and print it at the
operator's console.
org
is a character string constant or variable with the attributes CHARACTER(2)
whose value indicates, in operating system terms, the organization of the
checkpoint data set. PS indicates sequential (that is, CONSECUTIVE)
organization; PO represents partitioned organization. If you omit this argument,
PS is assumed.
code
is a variable with the attributes FIXED BINARY (31), which can receive a return
code from PLICKPT. The return code has the following values:
0 A checkpoint has been successfully taken.

4 A restart has been successfully made.
8 A checkpoint has not been taken. The PLICKPT statement should be
checked.
12 A checkpoint has not been taken. Check for a missing DD statement, a
hardware error, or insufficient space in the data set. A checkpoint will fail if
taken while a DISPLAY statement with the REPLY option is still
incomplete.
16 A checkpoint has been taken, but ENQ macro calls are outstanding and
will not be restored on restart. This situation will not normally arise for a
PL/I program.
Defining the checkpoint data set

You must include a DD statement in the job control procedure to define the data
set in which the checkpoint records are to be placed. This data set can have either
CONSECUTIVE or partitioned organization. You can use any valid ddname. If you
use the ddname SYSCHK, you do not need to specify the ddname when invoking
PLICKPT.
You must specify a data set name only if you want to keep the data set for a
deferred restart. The I/O device can be any direct-access device.
To obtain only the last checkpoint record, then specify status as NEW (or OLD if
the data set already exists). This will cause each checkpoint record to overwrite
the previous one.
To retain more than one checkpoint record, specify status as MOD. This will cause
each checkpoint record to be added after the previous one.
If the checkpoint data set is a library, “check-id” is used as the member-name.

Thus a checkpoint will delete any previously taken checkpoint with the same name.
For direct-access storage, you should allocate enough primary space to store as
many checkpoint records as you will retain. You can specify an incremental space
allocation, but it will not be used. A checkpoint record is approximately 5000 bytes
longer than the area of main storage allocated to the step.

No DCB information is required, but you can include any of the following, where
applicable:
OPTCD=W, OPTCD=C, RECFM=UT
These subparameters are described in the OS/390 JCL User's Guide.
Requesting a restart
A restart can be automatic or deferred. You can make automatic restarts after a
system failure or from within the program itself. The system operator must
authorize all automatic restarts when requested by the system.
Automatic restart after a system failure

If a system failure occurs after a checkpoint has been taken, the automatic restart
will occur at the last checkpoint if you have specified RD=R (or omitted the RD
parameter) in the EXEC or JOB statement.
If a system failure occurs before any checkpoint has been taken, an automatic
restart, from the beginning of the job step, can still occur if you have specified
RD=R in the EXEC or JOB statement.
After a system failure occurs, you can still force automatic restart from the
beginning of the job step by specifying RD=RNC in the EXEC or JOB statement.
By specifying RD=RNC, you are requesting an automatic step restart without
checkpoint processing if another system failure occurs.
Automatic restart within a program

You can request a restart at any point in your program. The rules for the restart
are the same as for a restart after a system failure. To request the restart, you
must execute the statement:
CALL PLIREST;
To effect the restart, the compiler terminates the program abnormally, with a
system completion code of 4092. Therefore, to use this facility, the system
completion code 4092 must not have been deleted from the table of eligible codes
at system generation.
Getting a deferred restart

To ensure that automatic restart activity is canceled, but that the checkpoints are
still available for a deferred restart, specify RD=NR in the EXEC or JOB statement
when the program is first executed.
──RESTART──═──(──stepname──┬──────────┬──)─────────────────────────────────────

├─,────────┤
└─check-id─┘
If you subsequently require a deferred restart, you must submit the program as a
new job, with the RESTART parameter in the JOB statement. Use the RESTART
parameter to specify the job step at which the restart is to be made and, if you
want to restart at a checkpoint, the name of the checkpoint record.
Chapter 18. Using the Checkpoint/Restart facility 349

For a restart from a checkpoint, you must also provide a DD statement that defines
the data set containing the checkpoint record. The DD statement must be named
SYSCHK. The DD statement must occur immediately before the EXEC statement
for the job step.
Modifying checkpoint/restart activity

You can cancel automatic restart activity from any checkpoints taken in your
program by executing the statement:
CALL PLICANC;
However, if you specified RD=R or RD=RNC in the JOB or EXEC statement,
automatic restart can still take place from the beginning of the job step.
Also, any checkpoints already taken are still available for a deferred restart.
You can cancel any automatic restart and the taking of checkpoints, even if they
were requested in your program, by specifying RD=NC in the JOB or EXEC
statement.

Chapter 19. Using user exits
PL/I provides a number of user exits that allow you to customize the PL/I product to
suit your needs. The PL/I products supply default exits and the associated source
files.
If you want the exits to perform functions that are different from those supplied by
the default exits, we recommend that you modify the supplied source files as
appropriate.
At times, it is useful to be able to tailor the compiler to meet the needs of your
organization. For example, you might want to suppress certain messages or alter
the severity of others. You might want to perform a specific function with each
compilation, such as logging statistical information about the compilation into a file.
A compiler user exit handles this type of function.
With PL/I, you can write your own user exit or use the exit provided with the
product, either 'as is' or modified, depending on what you want to do with it. The
purpose of this chapter is to describe:
Procedures that the compiler user exit supports
How to activate the compiler user exit
IBMUEXIT, the IBM-supplied compiler user exit
Requirements for writing your own compiler user exit.
Procedures performed by the compiler user exit

The compiler user exit performs three specific procedures:
Initialization
Interception and filtering of compiler messages
Termination
As illustrated in Figure 96, the compiler passes control to the initialization

procedure, the message filter procedure, and the termination procedure. Each of
these three procedures, in turn, passes control back to the compiler when the
requested procedure is completed.
┌────────┐
│ │
│ │ ┌───────────────┐
│ ├───────
│Initialization │
│ C │───────┤procedure │
│ O │ └───────────────┘
│ M │ ┌───────────────┐
│ P ├───────
│Message filter │
│ I │───────┤procedure │
│ L │ └───────────────┘
│ E │ ┌───────────────┐
│ R ├───────
│Termination │
│ │───────┤procedure │
│ │ └───────────────┘
│ │
└────────┘
Figure 96. PL/I compiler user exit procedures
Each of the three procedures is passed two different control blocks:

A global control block that contains information about the compilation. This is
passed as the first parameter. For specific information on the global control
block, see “Structure of global control blocks” on page 353.
A function-specific control block that is passed as the second parameter. The
content of this control block depends upon which procedure has been invoked.
For detailed information, see “Writing the initialization procedure” on page 355,
“Writing the message filtering procedure” on page 355, and “Writing the
termination procedure” on page 356.
Activating the compiler user exit

In order to activate the compiler user exit, you must specify the EXIT compile-time
option. For more information on the EXIT option, see “EXIT” on page 19.
The EXIT compile-time option allows you to specify a user-option-string which

specifies the DDname for the user exit input file. If you do not specify a string,
SYSUEXIT is used as the DDname for the user exit input file.
The user-option-string is passed to the user exit functions in the global control block
which is discussed in “Structure of global control blocks” on page 353. Please
refer to the field “Uex_UIB_User_char_str” in the section “Structure of global control
blocks” on page 353 for additional information.
The IBM-supplied compiler exit, IBMUEXIT

IBM supplies you with the sample compiler user exit, IBMUEXIT, which filters
messages for you. It monitors messages and, based on the message number that
you specify, suppresses the message or changes the severity of the message.
Customizing the compiler user exit

As was mentioned earlier, you can write your own compiler user exit or simply use
the one shipped with the compiler. In either case, the name of the fetchable file for
the compiler user exit must be IBMUEXIT.
This section describes how to:

Modify the user exit input file for customized message filtering
Create your own compiler user exit
Modifying SYSUEXIT
Rather than spending the time to write a completely new compiler user exit, you
can simplify modify the user exit input file.
Edit the file to indicate which message numbers you want to suppress, and which
message number severity levels you would like changed. A sample file is shown in
Figure 97.

Fac Id Msg No Severity Suppress Comment
+--------+--------+----------+----------+--------------------------------
'IBM' 1K42 -1 1 String spans multiple lines
'IBM' 1K44 -1 1 FIXED BIN 7 mapped to 1 byte
'IBM' 1K47 8 K Order inhibits optimization
'IBM' 1K52 -1 1 Nodescriptor with ] extent arg
'IBM' 1K59 K K Select without OTHERWISE
'IBM' 1169 K 1 Precision of result determined
Figure 97. Example of an user exit input file
The first two lines are header lines and are ignored by IBMUEXIT. The remaining
lines contain input separated by a variable number of blanks.
Each column of the file is relevant to the compiler user exit:

The first column should contain the letters 'IBM' in single quotes for all compiler
messages to which you want the exit to apply. For messages from the SQL
side of the SQL preprocessor, it should contain the SQL message prefix 'SQL'
(again in single quotes).
The second column contains the four digit message number.
The third column shows the new message severity. Severity -1 indicates that
the severity should be left as the default value.
The fourth column indicates whether or not the message is to be suppressed.
A '1' indicates the message is to be suppressed, and a '0' indicates that it
should be printed.
The comment field, found in the last column, is for your information, and is
ignored by IBMUEXIT.
Writing your own compiler exit

To write your own user exit, you can use IBMUEXIT (see the source in Figure 16.)
as a model. As you write the exit, make sure it covers the areas of initialization,
message filtering, and termination.
Structure of global control blocks

The global control block is passed to each of the three user exit procedures
(initialization, filtering, and termination) whenever they are invoked. The following
code and accompanying explanations describe the contents of each field in the
global control block.
Chapter 19. Using user exits 353

Dcl
1 Uex_UIB native based( null() ),
2 Uex_UIB_Length fixed bin(31),
2 Uex_UIB_Exit_token pointer, /] for user exit's use ]/
2 Uex_UIB_User_char_str pointer, /] to exit option str ]/

2 Uex_UIB_User_char_len fixed bin(31),
2 Uex_UIB_Filename_str pointer, /] to source filename ]/

2 Uex_UIB_Filename_len fixed bin(31),
2 Uex_UIB_return_code fixed bin(31), /] set by exit procs ]/

2 Uex_UIB_reason_code fixed bin(31), /] set by exit procs ]/
2 Uex_UIB_Exit_Routs, /] exit entries set at

initialization ]/
3 ( Uex_UIB_Termination,
Uex_UIB_Message_Filter, /] call for each msg ]/
], ], ], ] )
limited entry (
], /] to Uex_UIB ]/
], /] to a request area ]/
);
Data Entry Fields

Uex_UIB_ Length: Contains the length of the control block in bytes. The value
is storage (Uex_UIB).
Uex_UIB_Exit_token: Used by the user exit procedure. For example, the
initialization may set it to a data structure which is used by both the message
filter, and the termination procedures.
Uex_UIB_User_char_str: Points to an optional character string, if you specify
it. For example, in pli filename (EXIT ('string'))...fn can be a character
string up to thirty-one characters in length.
Uex_UIB_char_len: Contains the length of the string pointed to by the
User_char_str. The compiler sets this value.
Uex_UIB_Filename_str: Contains the name of the source file that you are
compiling, and includes the drive and subdirectories as well as the filename.
The compiler sets this value.
Uex_UIB_Filename_len: Contains the length of the name of the source file
pointed to by the Filename_str. The compiler sets this value.
Uex_UIB_return_code: Contains the return code from the user exit procedure.
The user sets this value.
Uex__UIB_reason_code: Contains the procedure reason code. The user sets
this value.
Uex_UIB_Exit_Routs: Contains the exit entries set up by the initialization
procedure.
Uex_UIB_Termination: Contains the entry that is to be called by the compiler
at termination time. The user sets this value.

Uex_UIB_Message_Filter: Contains the entry that is to be called by the
compiler whenever a message needs to be generated. The user sets this
value.
Writing the initialization procedure

Your initialization procedure should perform any initialization required by the exit,
such as opening files and allocating storage. The initialization procedure-specific
control block is coded as follows:
Dcl 1 Uex_ISA native based( null() ),
2 Uex_ISA_Length_fixed bin(31); /] storage(Uex_ISA) ] /
The global control block syntax for the initialization procedure is discussed in the
section “Structure of global control blocks” on page 353.
Upon completion of the initialization procedure, you should set the return/reason
codes to the following:
0/0 Continue compilation
4/n Reserved for future use
16/n Abort compilation
Writing the message filtering procedure

The message filtering procedure permits you to either suppress messages or alter
the severity of messages. You can increase the severity of any of the messages
but you can decrease the severity only of WARNING (severity code 4) messages
to INFORMATIONAL (severity code 0) messages.
The procedure-specific control block contains information about the messages. It is

used to pass information back to the compiler indicating how a particular message
should be handled.
The following is an example of a procedure-specific message filter control block:

Dcl 1 Uex_MFA native based( null() ),
2 Uex_MFA_Length fixed bin(31),
2 Uex_MFA_Facility_Id char(3), /] of component writing

message ]/
2 ] char(1),
2 Uex_MFA_Message_no fixed bin(31),
2 Uex_MFA_Severity fixed bin(15),
2 Uex_MFA_New_Severity fixed bin(15); /] set by exit proc ]/
Data Entry Fields

Uex_MFA_Length: Contains the length of the control block in bytes. The
value is storage (Uex_MFA).
Uex_MFA_Facility_Id: Contains the ID of the facility; for the compiler, the ID is
IBM. For the SQL side of the SQL preprocessor, the id is SQL. The compiler
sets this value.
Chapter 19. Using user exits 355

Uex_MFA_Message_no: Contains the message number that the compiler is
going to generate. The compiler sets this value.
Uex_MFA_Severity: Contains the severity level of the message; it can be from
one to fifteen characters in length. The compiler sets this value.
Uex_MFA_New_Severity: Contains the new severity level of the message; it
can be from one to fifteen characters in length. The user sets this value.
Upon completion of the message filtering procedure, set the return/reason codes to
one of the following:
0/0 Continue compilation, output message
0/1 Continue compilation, do not output message
Writing the termination procedure

You should use the termination procedure to perform any cleanup required, such as
closing files. You might also want to write out final statistical reports based on
information collected during the error message filter procedures and the initialization
procedures.
The termination procedure-specific control block is coded as follows:

Dcl 1 Uex_ISA native based,
2 Uex_ISA_Length_fixed bin(31); /] storage(Uex_ISA) ]/
The global control block syntax for the termination procedure is discussed in
“Structure of global control blocks” on page 353. Upon completion of the
termination procedure, set the return/reason codes to one of the following:
0/0 Continue compilation

Chapter 20. PL/I - Language Environment descriptors
This chapter describes PL/I parameter passing conventions between PL/I routines
at run time. For additional information about Language Environment run-time
environment considerations, other than descriptors, see OS/390 Language
Environment Programming Guide. This includes run-time environment conventions
and assembler macros supporting these conventions.
Passing an argument
When a string, an array, or a structure is passed as an argument, the compiler
passes a descriptor for that argument unless the called routine is declared with
OPTIONS(NODESCRIPTOR). There are two methods for passing such
descriptors:
By descriptor list
By descriptor locator
The following key features should be noted about each of these two methods:
When arguments are passed with a descriptor list
– The number of arguments passed is one greater than the number of
arguments specified if any of the arguments needs a descriptor.
– An argument passed with a descriptor can be received as a pointer passed
by value (BYVALUE).
– The compiler uses this method when the DEFAULT(DESCLOCATOR)
compiler option is in effect.
When arguments are passed by descriptor locator
– The number of arguments passed always matches the number of
arguments specified.
– An argument passed with a descriptor can be received as a pointer passed
by address (BYADDR).
– The compiler uses this method when the DEFAULT(DESCLIST) compiler
option is in effect.
Argument passing by descriptor list

When arguments and their descriptors are passed with a descriptor list, an extra
argument is passed whenever at least one argument needs a descriptor. This
extra argument is a pointer to a list of pointers. The number of entries in this list
equals the number of arguments passed. For arguments that don't require a
descriptor, the corresponding pointer in the descriptor list is set to SYSNULL. For
arguments that do require a descriptor, the corresponding pointer in the descriptor
list is set to the address of that argument's descriptor.
So, for example, suppose the routine sample is declared as

declare sample entry( fixed bin(31), varying char(]) )
options( byaddr descriptor );
Then, if sample is called as in the following statement:

call sample( 1, 'test' );
The following three arguments are passed to the routine:
Address of a fixed bin(31) temporary with the value 1
Address of a varying char(4) temporary with the value test
Address of a descriptor list consisting of the following:
– SYSNULL()
– Address of the descriptor for a varying char(4) string
Argument passing by descriptor-locator

When arguments and their descriptors are passed by descriptor-locator, whenever
an argument requires a descriptor, the address of a locator/descriptor for it is
passed instead.
The locator/descriptor is a pair of pointers. The first pointer is the address of the
data; the second pointer is the address of the descriptor.
So, for example, suppose the routine sample is declared again as

declare sample entry( fixed bin(31), varying char(]) )
options( byaddr descriptor );
Then, if sample is called as in the following statement
call sample( 1, 'test' );
The following two arguments are passed to the routine:
Address of a fixed bin(31) temporary with the value 1
Address of a descriptor-locator consisting of the following:
– Address of a varying char(4) temporary with the value test
– Address of the descriptor for a varying char(4) string
IMPORTANT
The rest of this chapter describes only the descriptors generated under the
compiler option CMPAT(LE). The descriptors generated under the compiler
options CMPAT(V1) and CMPAT(V2) are the same as those generated under
OS PL/I.
Descriptor header
Every descriptor starts with a 4-byte field. The first byte specifies the descriptor
type (scalar, array, structure or union). The remaining three bytes are zero unless
they are set by the particular descriptor type.
The declare for a descriptor header is:

declare
1 dsc_Header based( sysnull() ),
2 dsc_Type fixed bin(8) unsigned,
2 dsc_Datatype fixed bin(8) unsigned,
2 ] fixed bin(8) unsigned,
2 ] fixed bin(8) unsigned;
The possible values for the dsc_Type field are:

declare
dsc_Type_Unset fixed bin(8) value(K),
dsc_Type_Element fixed bin(8) value(2),
dsc_Type_Array fixed bin(8) value(3),
dsc_Type_Structure fixed bin(8) value(4),
dsc_Type_Union fixed bin(8) value(4);
String descriptors
In a string descriptor, the second byte of the header indicates the string type (bit,
character or graphic as well as nonvarying, varying or varyingz).
In a string descriptor for a nonvarying bit string, the third byte of the header gives
the bit offset.
In a string descriptor for a varying string, the fourth byte has a bit indicating if the
string length is held in nonnative format.
In a string descriptor for a character string, the fourth byte also has a bit indicating
if the string data is in EBCDIC.
The declare for a string descriptor is:

declare
1 dsc_String based( sysnull() ),
2 dsc_String_Header,
3 ] fixed bin(8) unsigned,
3 dsc_String_Type fixed bin(8) unsigned,
3 dsc_String_BitOfs fixed bin(8) unsigned,
3 ],
4 dsc_String_Has_Nonnative_Len bit(1),
4 dsc_String_Is_Ebcdic bit(1),
4 dsc_String_Has_Nonnative_Data bit(1),
4 ] bit(5),
2 dsc_String_Length fixed bin(31); /] max length of string ]/
The possible values for the dsc_String_Type field are:
Chapter 20. PL/I - Language Environment descriptors 359

declare
dsc_String_Type_Unset fixed bin(8) value(K),
dsc_String_Type_Char_Nonvarying fixed bin(8) value(2),
dsc_String_Type_Char_Varyingz fixed bin(8) value(3),
dsc_String_Type_Char_Varying2 fixed bin(8) value(4),
dsc_String_Type_Bit_Nonvarying fixed bin(8) value(6),
dsc_String_Type_Bit_Varying2 fixed bin(8) value(7),
dsc_String_Type_Graphic_Nonvarying fixed bin(8) value(9),
dsc_String_Type_Graphic_Varyingz fixed bin(8) value(1K),
dsc_String_Type_Graphic_Varying2 fixed bin(8) value(11),
dsc_String_Type_Widechar_Nonvarying fixed bin(8) value(13),
dsc_String_Type_Widechar_Varyingz fixed bin(8) value(14),
dsc_String_Type_Widechar_Varying2 fixed bin(8) value(15);
Array descriptors
The declare for an array descriptor is:
declare
1 dsc_Array based( sysnull() ),
2 dsc_Array_Header like dsc_Header,
2 dsc_Array_EltLen fixed bin(31), /] Length of array element ]/
2 dsc_Array_Rank fixed bin(31), /] Count of dimensions ]/
2 dsc_Array_RVO fixed bin(31), /] Relative virtual origin ]/
2 dsc_Array_Data( 1: 1 refer(dsc_Array_Rank) ),
3 dsc_Array_LBound fixed bin(31), /] LBound ]/
3 dsc_Array_Extent fixed bin(31), /] HBound - LBound + 1 ]/
3 dsc_Array_Stride fixed bin(31); /] Multiplier ]/

Notices
This information was developed for products and services offered in the U.S.A. IBM may not
offer the products, services, or features discussed in this document in other countries.
Consult your local IBM representative for information on the products and services currently
available in your area. Any reference to an IBM product, program, or service is not intended
to state or imply that only that IBM product, program, or service may be used. Any
functionally equivalent product, program, or service that does not infringe any IBM intellectual
property right may be used instead. However, it is the user s responsibility to evaluate and
verify the operation of any non-IBM product, program, or service.
IBM may have patents or pending patent applications covering subject matter described in
this document. The furnishing of this document does not give you any license to these
patents. You can send license inquiries, in writing, to:
IBM Corporation
J74/G4
555 Bailey Avenue
San Jose, CA 95141-1099
U.S.A.
For license inquiries regarding double-byte (DBCS) information, contact the IBM Intellectual
Property Department in your country or send inquiries, in writing, to:
IBM World Trade Asia Corporation

Licensing
2-31 Roppongi 3-chome, Minato-ku
Tokyo 106, Japan
The following paragraph does not apply to the United Kingdom or any other country where
such provisions are inconsistent with local law:
INTERNATIONAL BUSINESS MACHINES CORPORATION PROVIDES THIS

PUBLICATION "AS IS" WITHOUT WARRANTY OF ANY KIND, EITHER
EXPRESS OR IMPLIED, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED
WARRANTIES OF NON-INFRINGEMENT, MERCHANTABILITY OR FITNESS
FOR A PARTICULAR PURPOSE.
Some states do not allow disclaimer of express or implied warranties in certain transactions,
therefore, this statement may not apply to you.
This information could include technical inaccuracies or typographical errors.
Changes are periodically made to the information herein; these changes will be incorporated
in new editions of the publication. IBM may make improvements and/or changes in the
product(s) and/or the program(s) described in this publication at any time without notice.
Any references in this publication to non-IBM Web sites are provided for convenience only
and do not in any manner serve as an endorsement of those Web sites. The materials at
those Web sites are not part of the materials for this IBM product and use of those Web
sites is at your own risk.

Trademarks
The following terms are trademarks of International Business Machines Corporation in the
United States, or other countries, or both:
AIX Language Environment

CICS MVS
CICS/ESA OpenEdition
DB2 OS/390
DFSMS RACF
DFSORT System/390
IBM VisualAge
IMS z/OS
IMS/ESA
Intel is a registered trademark of Intel Corporation in the United States and other countries.
Java and all Java-based trademarks are trademarks of Sun Microsystems, Inc. in the United
States and other countries.
Microsoft, Windows, and Windows NT are trademarks of Microsoft Corporation in the United
States and other countries.
Pentium is a registered trademark of Intel Corporation in the United States and other
countries.
Unicode is a trademark of the Unicode Consortium.
UNIX is a registered trademark of The Open Group in the United States and other countries.
Other company, product or service names may be the trademarks or service marks of
others.
If you are viewing this information in softcopy, the photographs and color illustrations may
not appear.

Bibliography
Messages and Codes, GC26-9940
Enterprise PL/I publications
SQL Reference, SC26-9944
Programming Guide, SC27-1457
Language Reference, SC27-1460
Messages and Codes, SC27-1461
Diagnosis Guide, GC27-1459
DFSORT
Compiler and Run-Time Migration Guide, Application Programming Guide, SC33-4035
GC27-1458
Installation and Customization, SC33-4034
PL/I for MVS & VM IMS/ESA

Installation and Customization under MVS,
Application Programming: Database Manager,
SC26-3119
SC26-8015
Language Reference, SC26-3114
Compile-Time Messages and Codes, SC26-3229 Application Programming: Database Manager
Diagnosis Guide, SC26-3149 Summary, SC26-8037
Migration Guide, SC26-3118 Application Programming: Design Guide,
Programming Guide, SC26-3113 SC26-8016
Reference Summary, SX26-3821
Application Programming: Transaction Manager,
SC26-8017
z/OS Language Environment Application Programming: Transaction Manager
Summary, SC26-8038
Concepts Guide, SA22-7567
Application Programming: EXEC DL/I Commands
Debugging Guide, GA22-7560 for CICS and IMS, SC26-8018
Run-Time Messages, SA22-7566 Application Programming: EXEC DL/I Commands
Customization, SA22-7564 for CICS and IMS Summary, SC26-8036
Programming Guide, SA22-7561
Programming Reference, SA22-7562
z/OS MVS
Run-Time Migration Guide, GA22-7565
JCL Reference, SA22-7597
Writing Interlanguage Communication Applications,
JCL User's Guide, SA22-7598
SA22-7563
System Commands, SA22-7627
CICS Transaction Server

Application Programming Guide, SC33-1687
z/OS UNIX System Services
UNIX System Services Command Reference,
Application Programming Reference, SC33-1688
SA22-7802
Customization Guide, SC33-1683
UNIX System Services Programming: Assembler
External Interfaces Guide, SC33-1944 Callable Services Reference, SA22-7803
UNIX System Services User's Guide, SA22-7801
DB2 UDB for OS/390 and z/OS

Administration Guide, SC26-9931 z/OS TSO/E
An Introduction to DB2 for OS/390, SC26-9937 Command Reference, SA22-7782
Application Programming and SQL Guide, User's Guide, SA22-7794
SC26-9933
Command Reference, SC26-9934

z/Architecture Unicode and character
Principles of Operation, SA22-7832 representation
OS/390 Support for Unicode: Using Conversion
Services, SC33-7050

Glossary
This glossary defines terms for all platforms and releases of PL/I. It might contain terms that
this manual does not use. If you do not find the terms for which you are looking, see the
index in this manual or IBM Dictionary of Computing, SC20-1699.
aggregate. See data aggregate.

A
aggregate expression. An array, structure, or union
access. To reference or retrieve data. expression.
action specification. In an ON statement, the ON-unit aggregate type. For any item of data, the specification
or the single keyword SYSTEM, either of which whether it is structure, union, or array.
specifies the action to be taken whenever the
appropriate condition is raised. allocated variable. A variable with which main storage
is associated and not freed.
activate (a block). To initiate the execution of a block.
A procedure block is activated when it is invoked. A allocation. (1) The reservation of main storage for a
begin-block is activated when it is encountered in the variable. (2) A generation of an allocated variable.
normal flow of control, including a branch. A package (3) The association of a PL/I file with a system data set,
cannot be activated. device, or file.
activate (a preprocessor variable or preprocessor alignment. The storing of data items in relation to
entry point). To make a macro facility identifier eligible certain machine-dependent boundaries (for example, a
for replacement in subsequent source code. The fullword or halfword boundary).
%ACTIVATE statement activates preprocessor variables
or preprocessor entry points. alphabetic character. Any of the characters A through
Z of the English alphabet and the alphabetic extenders
active. (1) The state of a block after activation and #, $, and @ (which can have a different graphic
before termination. (2) The state in which a representation in different countries).
preprocessor variable or preprocessor entry name is
said to be when its value can replace the corresponding alphameric character. An alphabetic character or a
identifier in source program text. (3) The state in which digit.
an event variable is said to be during the time it is
associated with an asynchronous operation. (4) The alternative attribute. A file description attribute that is
state in which a task variable is said to be when its chosen from a group of attributes. If none is specified,
associated task is attached. (5) The state in which a a default is assumed. Contrast with additive attribute.
task is said to be before it has been terminated.
ambiguous reference. A reference that is not
actual origin (AO). The location of the first item in the sufficiently qualified to identify one and only one name
array or structure. known at the point of reference.
additive attribute. A file description attribute for which area. A portion of storage within which based variables
there are no defaults, and which, if required, must be can be allocated.
stated explicitly or implied by another explicitly stated
attribute. Contrast with alternative attribute. argument. An expression in an argument list as part
of an invocation of a subroutine or function.
adjustable extent. The bound (of an array), the length
(of a string), or the size (of an area) that might be argument list. A parenthesized list of zero or more
different for different generations of the associated arguments, separated by commas, following an entry
variable. Adjustable extents are specified as name constant, an entry name variable, a generic
expressions or asterisks (or by REFER options for name, or a built-in function name. The list becomes the
based variables), which are evaluated separately for parameter list of the entry point.
each generation. They cannot be used for static
variables. arithmetic comparison. A comparison of numeric
values. See also bit comparison, character comparison.

arithmetic constant. A fixed-point constant or a
floating-point constant. Although most arithmetic B
constants can be signed, the sign is not part of the
base. The number system in which an arithmetic value
constant.
is represented.
arithmetic conversion. The transformation of a value
base element. A member of a structure or a union
from one arithmetic representation to another.
that is itself not another structure or union.
arithmetic data. Data that has the characteristics of
base item. The automatic, controlled, or static variable
base, scale, mode, and precision. Coded arithmetic
or the parameter upon which a defined variable is
data and pictured numeric character data are included.
defined.
arithmetic operators. Either of the prefix operators +
based reference. A reference that has the based
and −, or any of the following infix operators: + − * / **
storage class.
array. A named, ordered collection of one or more
based storage allocation. The allocation of storage
data elements with identical attributes, grouped into one
for based variables.
or more dimensions.
based variable. A variable whose storage address is
array expression. An expression whose evaluation
provided by a locator. Multiple generations of the same
yields an array of values.
variable are accessible. It does not identify a fixed
array of structures. An ordered collection of identical location in storage.
structures specified by giving the dimension attribute to
begin-block. A collection of statements delimited by
a structure name.
BEGIN and END statements, forming a name scope. A
array variable. A variable that represents an begin-block is activated either by the raising of a
aggregate of data items that must have identical condition (if the begin-block is the action specification
attributes. Contrast with structure variable. for an ON-unit) or through the normal flow of control,
including any branch resulting from a GOTO statement.
ASCII. American National Standard Code for
Information Interchange. binary. A number system whose only numerals are 0
and 1.
assignment. The process of giving a value to a
variable. binary digit. See bit.
asynchronous operation. (1) The overlap of an binary fixed-point value. An integer consisting of
input/output operation with the execution of statements. binary digits and having an optional binary point and
(2) The concurrent execution of procedures using optional sign. Contrast with decimal fixed-point value.
multiple flows of control for different tasks.
binary floating-point value. An approximation of a
attachment of a task. The invocation of a procedure real number in the form of a significand, which can be
and the establishment of a separate flow of control to considered as a binary fraction, and an exponent, which
execute the invoked procedure (and procedures it can be considered as an integer exponent to the base
invokes) asynchronously, with execution of the invoking of 2. Contrast with decimal floating-point value.
procedure.
bit. (1) A 0 or a 1. (2) The smallest amount of space
attention. An occurrence, external to a task, that could of computer storage.
cause a task to be interrupted.
bit comparison. A left-to-right, bit-by-bit comparison of
attribute. (1) A descriptive property associated with a binary digits. See also arithmetic comparison, character
name to describe a characteristic represented. (2) A comparison.
descriptive property used to describe a characteristic of
bit string constant. (1) A series of binary digits
the result of evaluation of an expression.
enclosed in and followed immediately by the suffix B.
automatic storage allocation. The allocation of Contrast with character constant. (2) A series of
storage for automatic variables. hexadecimal digits enclosed in single quotes and
followed by the suffix B4.
automatic variable. A variable whose storage is
allocated automatically at the activation of a block and bit string. A string composed of zero or more bits.
released automatically at the termination of that block.

bit string operators. The logical operators not and coded arithmetic data. Data items that represent
exclusive-or (¬), and (&), and or (|). numeric values and are characterized by their base
(decimal or binary), scale (fixed-point or floating-point),
bit value. A value that represents a bit type. and precision (the number of digits each can have).
This data is stored in a form that is acceptable, without
block. A sequence of statements, processed as a unit, conversion, for arithmetic calculations.
that specifies the scope of names and the allocation of
storage for names declared within it. A block can be a combined nesting depth. The deepest level of
package, procedure, or a begin-block. nesting, determined by counting the levels of
PROCEDURE/BEGIN/ON, DO, SELECT, and
bounds. The upper and lower limits of an array IF...THEN...ELSE nestings in the program.
dimension.
comment. A string of zero or more characters used for
break character. The underscore symbol ( _ ). It can documentation that are delimited by /* and */.
be used to improve the readability of identifiers. For
instance, a variable could be called commercial character.
OLD_INVENTORY_TOTAL instead of
CR (credit) picture specification character
OLDINVENTORYTOTAL.
DB (debit) picture specification character
built-in function. A predefined function supplied by
comparison operator. An operator that can be used
the language, such as SQRT (square root).
in an arithmetic, string locator, or logical relation to
built-in function reference. A built-in function name, indicate the comparison to be done between the terms
which has an optional argument list. in the relation. The comparison operators are:
= (equal to)
built-in name. The entry name of a built-in subroutine. > (greater than)
< (less than)
built-in subroutine. Subroutine that has an entry >= (greater than or equal to)
name that is defined at compile-time and is invoked by <= (less than or equal to)
a CALL statement. ¬= (not equal to)
¬> (not greater than)
buffer. Intermediate storage, used in input/output
¬< (not less than)
operations, into which a record is read during input and
from which a record is written during output. compile time. In general, the time during which a
source program is translated into an object module. In
PL/I, it is the time during which a source program can
C be altered, if desired, and then translated into an object
call. To invoke a subroutine by using the CALL program.
statement or CALL option.
compiler options. Keywords that are specified to
character comparison. A left-to-right, control certain aspects of a compilation, such as: the
character-by-character comparison according to the nature of the object module generated, the types of
collating sequence. See also arithmetic comparison, bit printed output produced, and so forth.
comparison.
complex data. Arithmetic data, each item of which
character string constant. A sequence of characters consists of a real part and an imaginary part.
enclosed in single quotes; for example,
composite operator. An operator that consists of
'Shakespeare''s 'Hamlet:''.
more than one special character, such as <=, **, and /*.
character set. A defined collection of characters. See
compound statement. A statement that contains
language character set and data character set. See
other statements. In PL/I, IF, ON, OTHERWISE, and
also ASCII and EBCDIC.
WHEN are the only compound statements. See
character string picture data. Picture data that has statement body.
only a character value. This type of picture data must
concatenation. The operation that joins two strings in
have at least one A or X picture specification character.
the order specified, forming one string whose length is
Contrast with numeric picture data.
equal to the sum of the lengths of the two original
closing (of a file). The dissociation of a file from a strings. It is specified by the operator ||.
data set or device.
Glossary 367
condition. An exceptional situation, either an error control variable. A variable that is used to control the
(such as an overflow), or an expected situation (such as iterative execution of a DO statement.
the end of an input file). When a condition is raised
(detected), the action established for it is processed. controlled parameter. A parameter for which the
See also established action and implicit action. CONTROLLED attribute is specified in a DECLARE
statement. It can be associated only with arguments
condition name. Name of a PL/I-defined or that have the CONTROLLED attribute.
programmer-defined condition.
controlled storage allocation. The allocation of
condition prefix. A parenthesized list of one or more storage for controlled variables.
condition names prefixed to a statement. It specifies
whether the named conditions are to be enabled or controlled variable. A variable whose allocation and
disabled. release are controlled by the ALLOCATE and FREE
statements, with access to the current generation only.
connected aggregate. An array or structure whose
elements occupy contiguous storage without any control sections. Grouped machine instructions in an
intervening data items. Contrast with nonconnected object module.
aggregate.
conversion. The transformation of a value from one
connected reference. A reference to connected representation to another to conform to a given set of
storage. It must be apparent, prior to execution of the attributes. For example, converting a character string to
program, that the storage is connected. an arithmetic value such as FIXED BINARY (15,0).
connected storage. Main storage of an uninterrupted cross section of an array. The elements represented
linear sequence of items that can be referred to by a by the extent of at least one dimension of an array. An
single name. asterisk in the place of a subscript in an array reference
indicates the entire extent of that dimension.
constant. (1) An arithmetic or string data item that
does not have a name and whose value cannot change. current generation. The generation of an automatic or
(2) An identifier declared with the VALUE attribute. controlled variable that is currently available by referring
(3) An identifier declared with the FILE or the ENTRY to the name of the variable.
attribute but without the VARIABLE attribute.
constant reference. A value reference which has a D

constant as its object
data. Representation of information or of value in a
contained block, declaration, or source text. All form suitable for processing.
blocks, procedures, statements, declarations, or source
text inside a begin, procedure, or a package block. The data aggregate. A data item that is a collection of
entire package, procedure, and the BEGIN statement other data items.
and its corresponding END statements are not
data attribute. A keyword that specifies the type of
contained in the block.
data that the data item represents, such as FIXED
containing block. The package, procedure, or BINARY.
begin-block that contains the declaration, statement,
data-directed transmission. The type of
procedure, or other source text in question.
stream-oriented transmission in which data is
contextual declaration. The appearance of an transmitted. It resembles an assignment statement and
identifier that has not been explicitly declared in a is of the form name = constant.
DECLARE statement, but whose context of use allows
data item. A single named unit of data.
the association of specific attributes with the identifier.
data list. In stream-oriented transmission, a
control character. A character in a character set
parenthesized list of the data items used in GET and
whose occurrence in a particular context specifies a
PUT statements. Contrast with format list.
control function. One example is the end-of-file (EOF)
marker.
data set. (1) A collection of data external to the
program that can be accessed by reference to a single
control format item. A specification used in
file name. (2) A device that can be referenced.
edit-directed transmission to specify positioning of a
data item within the stream or printed page.

data specification. The portion of a stream-oriented defined variable. A variable that is associated with
transmission statement that specifies the mode of some or all of the storage of the designated base
transmission (DATA, LIST, or EDIT) and includes the variable.
data list(s) and, for edit-directed mode, the format list(s).
delimit. To enclose one or more items or statements
data stream. Data being transferred from or to a data with preceding and following characters or keywords.
set by stream-oriented transmission, as a continuous
stream of data elements in character form. delimiter. All comments and the following characters:
percent, parentheses, comma, period, semicolon, colon,
data transmission. The transfer of data from a data assignment symbol, blank, pointer, asterisk, and single
set to the program or vice versa. quote. They define the limits of identifiers, constants,
picture specifications, iSUBs, and keywords.
data type. A set of data attributes.
descriptor. A control block that holds information
DBCS. In the character set, each character is about a variable, such as area size, array bounds, or
represented by two consecutive bytes. string length.
deactivated. The state in which an identifier is said to digit. One of the characters 0 through 9.
be when its value cannot replace a preprocessor
identifier in source program text. Contrast with active. dimension attribute. An attribute that specifies the
number of dimensions of an array and indicates the
debugging. Process of removing bugs from a bounds of each dimension.
program.
disabled. The state of a condition in which no interrupt
decimal. The number system whose numerals are 0 occurs and no established action will take place.
through 9.
do-group. A sequence of statements delimited by a
decimal digit picture character. The picture DO statement and ended by its corresponding END
specification character 9. statement, used for control purposes. Contrast with
block.
decimal fixed-point constant. A constant consisting
of one or more decimal digits with an optional decimal do-loop. See iterative do-group.
point.
dummy argument. Temporary storage that is created
decimal fixed-point value. A rational number automatically to hold the value of an argument that
consisting of a sequence of decimal digits with an cannot be passed by reference.
assumed position of the decimal point. Contrast with
binary fixed-point value. dump. Printout of all or part of the storage used by a
program as well as other program information, such as
decimal floating-point constant. A value made up of a trace of an error's origin.
a significand that consists of a decimal fixed-point
constant, and an exponent that consists of the letter E
followed by an optionally signed integer constant not E
exceeding three digits.
EBCDIC. (Extended Binary-Coded Decimal
decimal floating-point value. An approximation of a Interchange Code). A coded character set consisting of
real number, in the form of a significand, which can be 8-bit coded characters.
considered as a decimal fraction, and an exponent,
which can be considered as an integer exponent to the edit-directed transmission. The type of
base 10. Contrast with binary floating-point value. stream-oriented transmission in which data appears as
a continuous stream of characters and for which a
decimal picture data. See numeric picture data. format list is required to specify the editing desired for
the associated data list.
declaration. (1) The establishment of an identifier as
a name and the specification of a set of attributes element. A single item of data as opposed to a
(partial or complete) for it. (2) A source of attributes of collection of data items such as an array; a scalar item.
a particular name.
element expression. An expression whose evaluation
default. Describes a value, attribute, or option that is yields an element value.
assumed when none has been specified.
Glossary 369
element variable. A variable that represents an established action. The action taken when a
element; a scalar variable. condition is raised. See also implicit action and
ON-statement action.
elementary name. See base element.
epilogue. Those processes that occur automatically at
enabled. The state of a condition in which the the termination of a block or task.
condition can cause an interrupt and then invocation of
the appropriate established ON-unit. evaluation. The reduction of an expression to a single
value, an array of values, or a structured set of values.
end-of-step message. message that follows the listng
of the job control statements and job scheduler event. An activity in a program whose status and
messages and contains return code indicating success completion can be determined from an associated event
or failure for each step. variable.
entry constant. (1) The label prefix of a event variable. A variable with the EVENT attribute
PROCEDURE statement (an entry name). (2) The that can be associated with an event. Its value
declaration of a name with the ENTRY attribute but indicates whether the action has been completed and
without the VARIABLE attribute. the status of the completion.
entry data. A data item that represents an entry point explicit declaration. The appearance of an identifier
to a procedure. (a name) in a DECLARE statement, as a label prefix, or
in a parameter list. Contrast with implicit declaration.
entry expression. An expression whose evaluation
yields an entry name. exponent characters. The following picture
specification characters:
entry name. (1) An identifier that is explicitly or
1. K and E, which are used in floating-point picture
contextually declared to have the ENTRY attribute
specifications to indicate the beginning of the
(unless the VARIABLE attribute is given) or (2) An
exponent field.
identifier that has the value of an entry variable with the
ENTRY attribute implied. 2. F, the scaling factor character, specified with an
integer constant that indicates the number of
entry point. A point in a procedure at which it can be decimal positions the decimal point is to be moved
invoked. primary entry point and secondary entry point. from its assumed position to the right (if the
constant is positive) or to the left (if the constant is
entry reference. An entry constant, an entry variable negative).
reference, or a function reference that returns an entry
value. expression. (1) A notation, within a program, that
represents a value, an array of values, or a structured
entry variable. A variable to which an entry value can set of values. (2) A constant or a reference appearing
be assigned. It must have both the ENTRY and alone, or a combination of constants and/or references
VARIABLE attributes. with operators.
entry value. The entry point represented by an entry extended alphabet. The uppercase and lowercase
constant or variable; the value includes the environment alphabetic characters A through Z, $, @ and #, or those
of the activation that is associated with the entry specified in the NAMES compiler option.
constant.
extent. (1) The range indicated by the bounds of an
environment (of an activation). Information array dimension, by the length of a string, or by the size
associated with and used in the invoked block regarding of an area. (2) The size of the target area if this area
data declared in containing blocks. were to be assigned to a target area.
environment (of a label constant). Identity of the external name. A name (with the EXTERNAL
particular activation of a block to which a reference to a attribute) whose scope is not necessarily confined only
statement-label constant applies. This information is to one block and its contained blocks.
determined at the time a statement-label constant is
passed as an argument or is assigned to a external procedure. (1) A procedure that is not
statement-label variable, and it is passed or assigned contained in any other procedure. (2) A level-2
along with the constant. procedure contained in a package that is also exported.
external symbol. Name that can be referred to in a

control section other than the one in which it is defined.

External Symbol Dictionary (ESD). Table containing format constant. The label prefix on a FORMAT
all the external symbols that appear in the object statement.
module.
format data. A variable with the FORMAT attribute.
extralingual character. Characters (such as $, @,
and #) that are not classified as alphanumeric or format label. The label prefix on a FORMAT
special. This group includes characters that are statement.
determined with the NAMES compiler option.
format list. In stream-oriented transmission, a list
specifying the format of the data item on the external
F medium. Contrast with data list.
factoring. The application of one or more attributes to fully qualified name. A name that includes all the
a parenthesized list of names in a DECLARE statement, names in the hierarchical sequence above the member
eliminating the repetition of identical attributes for to which the name refers, as well as the name of the
multiple names. member itself.
field (in the data stream). That portion of the data function (procedure). (1) A procedure that has a
stream whose width, in number of characters, is defined RETURNS option in the PROCEDURE statement.
by a single data or spacing format item. (2) A name declared with the RETURNS attribute. It is
invoked by the appearance of one of its entry names in
field (of a picture specification). Any character-string a function reference and it returns a scalar value to the
picture specification or that portion (or all) of a numeric point of reference. Contrast with subroutine.
character picture specification that describes a
fixed-point number. function reference. An entry constant or an entry
variable, either of which must represent a function,
file. A named representation, within a program, of a followed by a possibly empty argument list. Contrast
data set or data sets. A file is associated with the data with subroutine call.
set(s) for each opening.
file constant. A name declared with the FILE attribute G

but not the VARIABLE attribute.
generation (of a variable). The allocation of a static
file description attributes. Keywords that describe variable, a particular allocation of a controlled or
the individual characteristics of each file constant. See automatic variable, or the storage indicated by a
also alternative attribute and additive attribute. particular locator qualification of a based variable or by
a defined variable or parameter.
file expression. An expression whose evaluation
yields a value of the type file. generic descriptor. A descriptor used in a GENERIC
attribute.
file name. A name declared for a file.
generic key. A character string that identifies a class
file variable. A variable to which file constants can be of keys. All keys that begin with the string are
assigned. It has the attributes FILE and VARIABLE and members of that class. For example, the recorded keys
cannot have any of the file description attributes. 'ABCD', 'ABCE', and 'ABDF', are all members of the
classes identified by the generic keys 'A' and 'AB',
fixed-point constant. See arithmetic constant. and the first two are also members of the class 'ABC';
and the three recorded keys can be considered to be
fix-up. A solution, performed by the compiler after unique members of the classes 'ABCD', 'ABCE',
detecting an error during compilation, that allows the 'ABDF', respectively.
compiled program to run.
generic name. The name of a family of entry names.
floating-point constant. See arithmetic constant. A reference to the generic name is replaced by the
entry name whose parameter descriptors match the
flow of control. Sequence of execution.
attributes of the arguments in the argument list at the
point of invocation.
format. A specification used in edit-directed data
transmission to describe the representation of a data
group. A collection of statements contained within
item in the stream (data format item) or the specific
larger program units. A group is either a do-group or a
positioning of a data item within the stream (control
format item).
Glossary 371
select-group and it can be used wherever a single input/output. The transfer of data between auxiliary
statement can appear, except as an on-unit. medium and main storage.
insertion point character. A picture specification

H character that is, on assignment of the associated data
to a character string, inserted in the indicated position.
hex. See hexadecimal digit. When used in a P-format item for input, the insertion
character is used for checking purposes.
hexadecimal. Pertaining to a numbering system with a
base of sixteen; valid numbers use the digits 0 through integer. (1) An optionally signed sequence of digits or
9 and the characters A through F, where A represents a sequence of bits without a decimal or binary point.
10 and F represents 15. (2) An optionally signed whole number, commonly
described as FIXED BINARY (p,0) or FIXED DECIMAL
hexadecimal digit. One of the digits 0 through 9 and (p,0).
A through F. A through F represent the decimal values
10 through 15, respectively. integral boundary. A byte multiple address of any
8-bit unit on which data can be aligned. It usually is a
halfword, fullword, or doubleword (2-, 4-, or 8-byte
I multiple respectively) boundary.
identifier. A string of characters, not contained in a
interleaved array. An array that refers to
comment or constant, and preceded and followed by a
nonconnected storage.
delimiter. The first character of the identifier must be
one of the 26 alphabetic characters and extralingual interleaved subscripts. Subscripts that exist in levels
characters, if any. The other characters, if any, can other than the lowest level of a subscripted qualified
additionally include extended alphabetic, digit, or the reference.
break character.
internal block. A block that is contained in another
IEEE. Institute of Electrical and Electronics Engineers. block.
implicit. The action taken in the absence of an explicit internal name. A name that is known only within the
specification. block in which it is declared, and possibly within any
contained blocks.
implicit action. The action taken when an enabled
condition is raised and no ON-unit is currently internal procedure. A procedure that is contained in
established for the condition. Contrast with another block. Contrast with external procedure.
ON-statement action.
interrupt. The redirection of the program's flow of
implicit declaration. A name not explicitly declared in control as the result of raising a condition or attention.
a DECLARE statement or contextually declared.
invocation. The activation of a procedure.
implicit opening. The opening of a file as the result of
an input or output statement other than the OPEN invoke. To activate a procedure.
statement.
invoked procedure. A procedure that has been
infix operator. An operator that appears between two activated.
operands.
invoking block. A block that activates a procedure.
inherited dimensions. For a structure, union, or
element, those dimensions that are derived from the iteration factor. (1) In an INITIAL attribute
containing structures. If the name is an element that is specification, an expression that specifies the number of
not an array, the dimensions consist entirely of its consecutive elements of an array that are to be
inherited dimensions. If the name is an element that is initialized with the given value. (2) In a format list, an
an array, its dimensions consist of its inherited expression that specifies the number of times a given
dimensions plus its explicitly declared dimensions. A format item or list of format items is to be used in
structure with one or more inherited dimensions is succession.
called a nonconnected aggregate. Contrast with
connected aggregate. iterative do-group. A do-group whose DO statement
specifies a control variable and/or a WHILE or UNTIL
option.

locator. A control block that holds the address of a
K variable or its descriptor.
key. Data that identifies a record within a direct-access locator/descriptor. A locator followed by a descriptor.
data set. See source key and recorded key. The locator holds the address of the variable, not the
address of the descriptor.
keyword. An identifier that has a specific meaning in
PL/I when used in a defined context. locator qualification. In a reference to a based
variable, either a locator variable or function reference
keyword statement. A simple statement that begins
connected by an arrow to the left of a based variable to
with a keyword, indicating the function of the statement.
specify the generation of the based variable to which
the reference refers. It might be an implicit reference.
known (applied to a name). Recognized with its
declared meaning. A name is known throughout its
locator value. A value that identifies or can be used to
scope.
identify the storage address.
locator variable. A variable whose value identifies the

L location in main storage of a variable or a buffer. It has
label. (1) A name prefixed to a statement. A name on the POINTER or OFFSET attribute.
a PROCEDURE statement is called an entry constant; a
locked record. A record in an EXCLUSIVE DIRECT
name on a FORMAT statement is called a format
UPDATE file that has been made available to one task
constant; a name on other kinds of statements is called
only and cannot be accessed by other tasks until the
a label constant. (2) A data item that has the LABEL
task using it relinquishes it.
attribute.
logical level (of a structure or union member). The
label constant. A name written as the label prefix of a
depth indicated by a level number when all level
statement (other than PROCEDURE, ENTRY,
numbers are in direct sequence (when the increment
FORMAT, or PACKAGE) so that, during execution,
between successive level numbers is one).
program control can be transferred to that statement
through a reference to its label prefix.
logical operators. The bit-string operators not and
exclusive-or (¬), and (&), and or (|).
label data. A label constant or the value of a label
variable.
loop. A sequence of instructions that is executed
iteratively.
label prefix. A label prefixed to a statement.
lower bound. The lower limit of an array dimension.
label variable. A variable declared with the LABEL
attribute. Its value is a label constant in the program.
leading zeroes. Zeros that have no significance in an

M
arithmetic value. All zeros to the left of the first nonzero main procedure. An external procedure whose
in a number. PROCEDURE statement has the OPTIONS (MAIN)
attribute. This procedure is invoked automatically as
level number. A number that precedes a name in a
the first step in the execution of a program.
DECLARE statement and specifies its relative position
in the hierarchy of structure names. major structure. A structure whose name is declared
with level number 1.
level-one variable. (1) A major structure or union
name. (2) Any unsubscripted variable not contained member. (1) A structure, union, or element name in a
within a structure or union. structure or union. (2) Data sets in a library.
lexically. Relating to the left-to-right order of units. minor structure. A structure that is contained within
another structure or union. The name of a minor
library. An MVS partitioned data set or a CMS
structure is declared with a level number greater than
MACLIB that can be used to store other data sets
one and greater than its parent structure or union.
called members.
mode (of arithmetic data). An attribute of arithmetic
list-directed. The type of stream-oriented transmission
data. It is either real or complex.
in which data in the stream appears as constants
separated by blanks or commas and for which
formatting is provided automatically.
Glossary 373
multiple declaration. (1) Two or more declarations of numeric picture data. Picture data that has an
the same identifier internal to the same block without arithmetic value as well as a character value. This type
different qualifications. (2) Two or more external of picture data cannot contain the characters 'A' or
declarations of the same identifier. 'X.'
multiprocessing. The use of a computing system with

two or more processing units to execute two or more O
programs simultaneously.
object. A collection of data referred to by a single
multiprogramming. The use of a computing system to name.
execute more than one program concurrently, using a
single processing unit. offset variable. A locator variable with the OFFSET
attribute, whose value identifies a location in storage
multitasking. A facility that allows a program to relative to the beginning of an area.
execute more than one PL/I procedure simultaneously.
ON-condition. An occurrence, within a PL/I program,
that could cause a program interrupt. It can be the
N detection of an unexpected error or of an occurrence
that is expected, but at an unpredictable time.
name. Any identifier that the user gives to a variable
or to a constant. An identifier appearing in a context ON-statement action. The action explicitly established
where it is not a keyword. Sometimes called a for a condition that is executed when the condition is
user-defined name. raised. When the ON-statement is encountered in the
flow of control for the program, it executes, establishing
nesting. The occurrence of: the action for the condition. The action executes when
A block within another block the condition is raised if the ON-unit is still established
or a RESIGNAL statement reestablishes it. Contrast
A group within another group with implicit action.
An IF statement in a THEN clause or in an ELSE
clause ON-unit. The specified action to be executed when the
appropriate condition is raised.
A function reference as an argument of a function
reference opening (of a file). The association of a file with a
A remote format item in the format list of a data set.
FORMAT statement
operand. The value of an identifier, constant, or an
A parameter descriptor list in another parameter expression to which an operator is applied, possibly in
descriptor list conjunction with another operand.
An attribute specification within a parenthesized
operational expression. An expression that consists
name list for which one or more attributes are being
of one or more operators.
factored
operator. A symbol specifying an operation to be
nonconnected storage. Storage occupied by
performed.
nonconnected data items. For example, interleaved
arrays and structures with inherited dimensions are in
option. A specification in a statement that can be used
nonconnected storage.
to influence the execution or interpretation of the
statement.
null locator value. A special locator value that cannot
identify any location in internal storage. It gives a
positive indication that a locator variable does not
currently identify any generation of data.
P
package constant. The label prefix on a PACKAGE
null statement. A statement that contains only the statement.
semicolon symbol (;). It indicates that no action is to be
taken. packed decimal. The internal representation of a
fixed-point decimal data item.
null string. A character, graphic, or bit string with a
length of zero. padding. (1) One or more characters, graphics, or bits
concatenated to the right of a string to extend the string
numeric-character data. See decimal picture data. to a required length. (2) One or more bytes or bits

inserted in a structure or union so that the following prefix. A label or a parenthesized list of one or more
element within the structure or union is aligned on the condition names included at the beginning of a
appropriate integral boundary. statement.
parameter. A name in the parameter list following the prefix operator. An operator that precedes an
PROCEDURE statement, specifying an argument that operand and applies only to that operand. The prefix
will be passed when the procedure is invoked. operators are plus (+), minus (−), and not (¬).
parameter descriptor. The set of attributes specified preprocessor. A program that examines the source
for a parameter in an ENTRY attribute specification. program before the compilation takes place.
parameter descriptor list. The list of all parameter preprocessor statement. A special statement
descriptors in an ENTRY attribute specification. appearing in the source program that specifies the
actions to be performed by the preprocessor. It is
parameter list. A parenthesized list of one or more executed as it is encountered by the preprocessor.
parameters, separated by commas and following either
the keyword PROCEDURE in a procedure statement or primary entry point. The entry point identified by any
the keyword ENTRY in an ENTRY statement. The list of the names in the label list of the PROCEDURE
corresponds to a list of arguments passed at invocation. statement.
partially qualified name. A qualified name that is priority. A value associated with a task, that specifies
incomplete. It includes one or more, but not all, of the the precedence of the task relative to other tasks.
names in the hierarchical sequence above the structure
or union member to which the name refers, as well as problem data. Coded arithmetic, bit, character,
the name of the member itself. graphic, and picture data.
picture data. Numeric data, character data, or a mix problem-state program. A program that operates in
of both types, represented in character form. the problem state of the operating system. It does not
contain input/output instructions or other privileged
picture specification. A data item that is described instructions.
using the picture characters in a declaration with the
PICTURE attribute or in a P-format item. procedure. A collection of statements, delimited by
PROCEDURE and END statements. A procedure is a
picture specification character. Any of the program or a part of a program, delimits the scope of
characters that can be used in a picture specification. names, and is activated by a reference to the procedure
or one of its entry names. See also external procedure
PL/I character set. A set of characters that has been and internal procedure.
defined to represent program elements in PL/I.
procedure reference. An entry constant or variable. It
PL/I prompter. Command processor program for the can be followed by an argument list. It can appear in a
PLI command that checks the operands and allocates CALL statement or the CALL option, or as a function
the data sets required by the compiler. reference.
point of invocation. The point in the invoking block at program. A set of one or more external procedures or
which the reference to the invoked procedure appears. packages. One of the external procedures must have
the OPTIONS(MAIN) specification in its procedure
pointer. A type of variable that identifies a location in statement.
storage.
program control data. Area, locator, label, format,
pointer value. A value that identifies the pointer type. entry, and file data that is used to control the
processing of a PL/I program.
pointer variable. A locator variable with the POINTER
attribute that contains a pointer value. prologue. The processes that occur automatically on
block activation.
precision. The number of digits or bits contained in a
fixed-point data item, or the minimum number of pseudovariable. Any of the built-in function names
significant digits (excluding the exponent) maintained for that can be used to specify a target variable. It is
a floating-point data item. usually on the left-hand side of an assignment
statement.
Glossary 375
transmission statements to control the format of data
Q being transmitted.
qualified name. A hierarchical sequence of names of repetition factor. A parenthesized unsigned integer
structure or union members, connected by periods, constant that specifies:
used to identify a name within a structure. Any of the
names can be subscripted. 1. The number of times the string constant that follows
is to be repeated.
2. The number of times the picture character that
R follows is to be repeated.
range (of a default specification). A set of identifiers
repetitive specification. An element of a data list that
and/or parameter descriptors to which the attributes in a
specifies controlled iteration to transmit one or more
DEFAULT statement apply.
data items, generally used in conjunction with arrays.
record. (1) The logical unit of transmission in a
restricted expression. An expression that can be
record-oriented input or output operation. (2) A
evaluated by the compiler during compilation, resulting
collection of one or more related data items. The items
in a constant. Operands of such an expression are
usually have different data attributes and usually are
constants, named constants, and restricted expressions.
described by a structure or union declaration.
returned value. The value returned by a function
recorded key. A character string identifying a record
procedure.
in a direct-access data set where the character string
itself is also recorded as part of the data. RETURNS descriptor. A descriptor used in a
RETURNS attribute, and in the RETURNS option of the
record-oriented data transmission. The transmission
PROCEDURE and ENTRY statements.
of data in the form of separate records. Contrast with
stream data transmission.
recursive procedure. A procedure that can be called

S
from within itself or from within another active scalar variable. A variable that is not a structure,
procedure. union, or array.
reentrant procedure. A procedure that can be scale. A system of mathematical notation whose
activated by multiple tasks, threads, or processes representation of an arithmetic value is either fixed-point
simultaneously without causing any interference or floating-point.
between these tasks, threads, and processes.
scale factor. A specification of the number of
REFER expression. The expression preceding the fractional digits in a fixed-point number.
keyword REFER, which is used as the bound, length, or
size when the based variable containing a REFER scaling factor. See scale factor.
option is allocated, either by an ALLOCATE or LOCATE
statement. scope (of a condition prefix). The portion of a
program throughout which a particular condition prefix
REFER object. The variable in a REFER option that applies.
holds or will hold the current bound, length, or size for
the member. The REFER object must be a member of scope (of a declaration or name). The portion of a
the same structure or union. It must not be program throughout which a particular name is known.
locator-qualified or subscripted, and it must precede the
member with the REFER option. secondary entry point. An entry point identified by
any of the names in the label list of an entry statement.
reference. The appearance of a name, except in a
context that causes explicit declaration. select-group. A sequence of statements delimited by
SELECT and END statements.
relative virtual origin (RVO). The actual origin of an
array minus the virtual origin of an array. selection clause. A WHEN or OTHERWISE clause of
a select-group.
remote format item. The letter R followed by the label
(enclosed in parentheses) of a FORMAT statement. self-defining data. An aggregate that contains data
The format statement is used by edit-directed data items whose bounds, lengths, and sizes are determined

at program execution time and are stored in a member keyword statement, assignment statement, and null
of the aggregate. statement.
separator. See delimiter. statement body. A statement body can be either a

simple or a compound statement.
shift. Change of data in storage to the left or to the
right of original position. statement label. See label constant.
shift-in. Symbol used to signal the compiler at the end static storage allocation. The allocation of storage for
of a double-byte string. static variables.
shift-out. Symbol used to signal the compiler at the static variable. A variable that is allocated before
beginning of a double-byte string. execution of the program begins and that remains
allocated for the duration of execution.
sign and currency symbol characters. The picture
specification characters. S, +, −, and $ (or other national stream-oriented data transmission. The transmission
currency symbols enclosed in < and >). of data in which the data is treated as though it were a
continuous stream of individual data values in character
simple parameter. A parameter for which no storage form. Contrast with record-oriented data transmission.
class attribute is specified. It can represent an
argument of any storage class, but only the current string. A contiguous sequence of characters, graphics,
generation of a controlled argument. or bits that is treated as a single data item.
simple statement. A statement other than IF, ON, string variable. A variable declared with the BIT,
WHEN, and OTHERWISE. CHARACTER, or GRAPHIC attribute, whose values can
be either bit, character, or graphic strings.
source. Data item to be converted for problem data.
structure. A collection of data items that need not
source key. A key referred to in a record-oriented have identical attributes. Contrast with array.
transmission statement that identifies a particular record
within a direct-access data set. structure expression. An expression whose
evaluation yields a structure set of values.
source program. A program that serves as input to
the source program processors and the compiler. structure of arrays. A structure that has the
dimension attribute.
source variable. A variable whose value participates
in some other operation, but is not modified by the structure member. See member.
operation. Contrast with target variable.
structuring. The hierarchy of a structure, in terms of
spill file. Data set named SYSUT1 that is used as a the number of members, the order in which they
temporary workfile. appear, their attributes, and their logical level.
standard default. The alternative attribute or option subroutine. A procedure that has no RETURNS
assumed when none has been specified and there is no option in the PROCEDURE statement. Contrast with
applicable DEFAULT statement. function.
standard file. A file assumed by PL/I in the absence subroutine call. An entry reference that must
of a FILE or STRING option in a GET or PUT represent a subroutine, followed by an optional
statement. SYSIN is the standard input file and argument list that appears in a CALL statement.
SYSPRINT is the standard output file. Contrast with function reference.
standard system action. Action specified by the subscript. An element expression that specifies a
language to be taken for an enabled condition in the position within a dimension of an array. If the subscript
absence of an ON-unit for that condition. is an asterisk, it specifies all of the elements of the
dimension.
statement. A PL/I statement, composed of keywords,
delimiters, identifiers, operators, and constants, and subscript list. A parenthesized list of one or more
terminated by a semicolon (;). Optionally, it can have a subscripts, one for each dimension of the array, which
condition prefix list and a list of labels. See also together uniquely identify either a single element or
cross section of the array.
Glossary 377
subtask. A task that is attached by the given task or
any of the tasks in a direct line from the given task to U
the last attached task.
undefined. Indicates something that a user must not
synchronous. A single flow of control for serial do. Use of a undefined feature is likely to produce
execution of a program. different results on different implementations of a PL/I
product. In that case, the application program is in
error.
T
union. A collection of data elements that overlay each
target. Attributes to which a data item (source) is other, occupying the same storage. The members can
converted. be structures, unions, elementary variables, or arrays.
They need not have identical attributes.
target reference. A reference that designates a
receiving variable (or a portion of a receiving variable). union of arrays. A union that has the DIMENSION
attribute.
target variable. A variable to which a value is
assigned. upper bound. The upper limit of an array dimension.
task. The execution of one or more procedures by a

single flow of control. V
task name. An identifier used to refer to a task value reference. A reference used to obtain the value
variable. of an item of data.
task variable. A variable with the TASK attribute variable. A named entity used to refer to data and to
whose value gives the relative priority of a task. which values can be assigned. Its attributes remain
constant, but it can refer to different values at different
termination (of a block). Cessation of execution of a times.
block, and the return of control to the activating block by
means of a RETURN or END statement, or the transfer variable reference. A reference that designates all or
of control to the activating block or to some other active part of a variable.
block by means of a GO TO statement.
virtual origin (VO). The location where the element of
termination (of a task). Cessation of the flow of the array whose subscripts are all zero are held. If
control for a task. such an element does not appear in the array, the
virtual origin is where it would be held.
truncation. The removal of one or more digits,
characters, graphics, or bits from one end of an item of
data when a string length or precision of a target Z
variable has been exceeded.
zero-suppression characters. The picture
type. The set of data attributes and storage attributes specification characters Z and *, which are used to
that apply to a generation, a value, or an item of data. suppress zeros in the corresponding digit positions and
replace them with blanks or asterisks respectively.

Index
argument passing (continued)
Special Characters by descriptor-locator 358
/ (forward slash) 132 array descriptor 360
*PROCESS, specifying options in 52 ASA option under OS/390 UNIX 134
% statements 53 ASCII
%INCLUDE statement 22, 53 compiler suboption
%NOPRINT statement 53 description 13
%OPTION 53 assembler routines
%PAGE statement 53 FETCHing 122
%POP statement 53 ASSIGNABLE compiler suboption 13
%PRINT statement 53 ATTENTION ON-units 346
%PROCESS, specifying options in 52 attention processing
%PUSH statement 53 attention interrupt,effect of 23
%SKIP statement 53 ATTENTION ON-units 346
debugging tool 346
main description 345
A attribute table 56
access
ATTRIBUTES option 6
ESDS 208
automatic
REGIONAL(1) data set 193
padding 112
relative-record data set 226
prompting
access method services
overriding 111
regional data set 195
using 111
REGIONAL(1) data set
restart
direct access 192
after system failure 349
sequential access 192
checkpoint/restart facility 347
ACCT EXEC statement parameter 99
within a program 349
aggregate
auxiliary storage for sort 251
length table 57
avoiding calls to library routines 242
AGGREGATE compiler option 5
ALIGNED compiler suboption 17
ALL option B
hooks location suboption 46 batch compile
ALLOCATE statement 57 OS/390 101, 104
alternate ddname under OS/390 UNIX, in TITLE BKWD option 147, 203
option 132 BLANK compiler option 7
alternate index BLKSIZE
Indexed ESDS BUFFERS option
KSDS comparison with DCB subparameter 148
nonunique key consecutive data sets 181
unique key CTLASA and CTL360
using with ESDS comparison with DCB subparameter 148
using with KSDS ENVIRONMENT 147
AMP parameter 197 comparison with DCB subparameter 148
ANS for record I/O 149
compiler suboption 13 KEYLENGTH option
APPEND option under OS/390 UNIX 134 comparison with DCB subparameter 148
ARCH compiler option 5, 230 option of ENVIRONMENT
argument for stream I/O 163
sort program 251 subparameter 144
argument passing block
by descriptor list 357 and record 139

block (continued) checkpoint/restart facility
size CALL PLIREST statement 349
consecutive data sets 181 checkpoint data set 348
maximum 150 description of 347
object module 105 modify activity 350
PRINT files 170 PLICKPT built-in subroutine 347
record length 150 request checkpoint record 347
regional data sets 196 request restart 349
specifying 139 RESTART parameter 349
BUFFERS option return codes 347
for stream I/O 163 CHKPT sort option 249
BUFSIZE option under OS/390 UNIX 134 CICS
BYADDR preprocessor options 85
description 233 support 85
effect on performance 233 CICS, compiling transactions in PL/I 108
using with DEFAULT option 13 CKPT sort option 249
BYVALUE CMPAT compiler option 7
description 233 COBOL
effect on performance 234 map structure 57
using with DEFAULT option 13 CODE subparameter 144
CODEPAGE compiler option 8
coding
C CICS statements 85
C routines improving performance 236
FETCHing 122 SQL statements 72
capacity record communications area, SQL 72
REGIONAL(1) 190 COMPACT compiler option 9
carriage return-line feed (CR - LF) 138 compilation
cataloged procedure user exit
compile and bind 89 activating 352
compile only 88 customizing 352
compile, bind, and run 91 IBMUEXIT 352
compile, input data for 91, 94 procedures 351
compile, prelink and link-edit 92 compile and bind, input data for 89
compile, prelink, link-edit, and run 94 COMPILE compiler option 9
compile, prelink, load and run 95 compile-time options
description of 87 under OS/390 UNIX 102
invoking 97 compile, prelink, and link-edit, input data for 92
listing 97 compiler
modifying % statements 53
DD statement 99 DBCS identifier 21
EXEC statement 99 descriptions of options 3
multiple invocations 97 general description of 101
under OS/390 graphic string constant 21
IBM-supplied 87 invoking 101
to invoke 97 JCL statements, using 104
to modify 98 listing
character string attribute table 56 aggregate length table 57
CHECK compiler option 7 attribute table 56
checkpoint data block level 56
for sort 255 cross-reference table 57
checkpoint data, defining, PLICKPT built-in DO-level 56
suboption 348 file reference table 60
checkpoint/restart heading information 55
deferred restart 349 include source program 22
PLICANC statement 350 input to compiler 55
input to preprocessor 55

compiler (continued) compiler options (continued)
listing (continued) MAXMSG 28
messages 60 MAXSTMT 28
printing options 106 MDECK 28
return codes 60 NAME 29
SOURCE option program 56 NAMES 29
source program 42 NATLANG 30
stack storage used 43 NEST 30
statement offset addresses 57 NOT 30
SYSPRINT 106 NUMBER 31
using 55 OBJECT 31
mixed string constant 21 OFFSET 31
PROCESS statement 52 OPTIMIZE 31, 230
reduce storage requirement 31 OPTIONS 32
severity of error condition 9 OR 33
temporary workfile (SYSUT1) 106 PP 33
under OS/390 batch 104 PPTRACE 34
compiler options PREFIX 34, 232
abbreviations 3 PROCEED 34
AGGREGATE 5 REDUCE 35, 231
ARCH 5, 230 RENT 36
ATTRIBUTES 6 RESPECT 37
BLANK 7 RULES 37, 231
CHECK 7 SEMANTIC 41
CMPAT 7 SERVICE 42
CODEPAGE 8 SOURCE 42
COMPACT 9 SPILL 42
COMPILE 9 STDSYS 42
CSECT 10 STMT 43
CURRENCY 11 STORAGE 43
DBCS 11 SYNTAX 43
DD 11 SYSPARM 44
default 3, 12, 233 SYSTEM 44
description of 3 TERMINAL 45
DISPLAY 19 TEST 46
DLLINIT 19 TUNE 47
EXIT 19 USAGE 48
EXTRN 19 WIDECHAR 48
FLAG 20 WINDOW 49
FLOAT 20 WRITABLE 49
GONUMBER 20, 230 XINFO 50
GRAPHIC 21 XREF 51
INCAFTER 21 compiling
INCDIR 21 CICS transactions in PL/I 108
INCLUDE 22 under OS/390 UNIX 101
INSOURCE 22 Compiling Java code
INTERRUPT 23 Compiling PL/I code
LANGLVL 24 concatenating
LIMITS 24 data sets 131
LINECOUNT 25 external references 129
LIST 25 COND EXEC statement parameter 99
MACRO 25 conditional compilation 9
MAP 26 conditional subparameter 143
MARGINI 26 CONNECTED compiler suboption
MARGINS 26 description 13
MAXMEM 27 effect on performance 234
Index 381
CONSECUTIVE CYLOFL subparameter
option of ENVIRONMENT 163, 179 DCB parameter 144
controlling input from the terminal
capital and lowercase letters 176 D
condition format 174 data
COPY option of GET statement 176 conversion under OS/390 UNIX 132
end-of-file 176 files
format of data 175 creating under OS/390 UNIX 133
stream and record files 175 sort program 256
controlling output to the terminal PLISRT(x) command 260
capital and lowercase letters 177 sorting 245
conditions 176 description of 245
format of PRINT files 176 types
output from the PUT EDIT command 177 equivalent Java and PL/I 290
stream and record files 177 equivalent SQL and PL/I 77
defining and using 162 data definition (DD) information under OS/390
input from the terminal 174 UNIX 132
output to the terminal 176 data set
record-oriented data transmission associating PL/I files with
accessing and updating a data set 181 closing a file 146
creating a data set 181 opening a file 145
defining files 178 specifying characteristics in the ENVIRONMENT
specifying ENVIRONMENT options 179 attribute 146
statements and options allowed 177 associating several data sets with one file 130
record-oriented I/O 177 blocks and records 139
stream-oriented data transmission 162 checkpoint 348
accessing a data set 168 conditional subparameter characteristics 144
creating a data set 165 consecutive stream-oriented data 162
defining files 162 data set control block (DSCB) 143
specifying ENVIRONMENT options 163 ddnames 104
using PRINT files 169 defining for dump
using SYSIN and SYSPRINT files 173 DD statement 343
control logical record length 343
area 198 defining relative-record 223
characters 169 direct 142
CONTROL option dissociating from a file 146
EXEC statement 107 dissociating from PL/I file 131
interval 198 establishing characteristics 139
control blocks indexed
function-specific 351 sequential 142
global control 353 information interchange codes 140
COPY option 176 input in cataloged procedures 87
cross-reference table label modification 145
compiler listing 57 labels 143, 156
using XREF option 56 libraries
CSECT compiler option 10 extracting information 160
CTLASA and CTL360 options SPACE parameter 157
ENVIRONMENT option types of 156
for consecutive data sets 179 updating 158
SCALARVARYING 153 use 156
CURRENCY compiler option 11 organization
customizing conditional subparameters 143
user exit data definition (DD) statement 143
modifying SYSUEXIT 352 types of 142
structure of global control blocks 353 partitioned 156
writing your own compiler exit 353

data set (continued) data set under OS/390 UNIX (continued)
record format defaults 148 DD_DDNAME environment variable 132
record formats default identification 132
fixed-length 140 establishing a path 133
undefined-length 142 establishing characteristics
variable-length 141 DD_DDNAME environment variable 133
records 139 extending on output 134
regional 186 maximum number of regions 137
REGIONAL(1) 190 number of regions 137
accessing and updating 192 recreating output 134
creating 190 data sets
sequential 142 associating data sets with files 128
sort program closing 146
checkpoint data set 255 defining data sets under OS/390 128
input data set 255 data-directed I/O 237
output data set 255 coding for performance 236
sort work data set 254 DBCS compiler option 11
sorting 254 DBCS identifier compilation 21
SORTWK 251 DCB subparameter 146, 148
source statement library 106 equivalent ENVIRONMENT options 148
SPACE parameter 104 main discussion of 144
stream files 162 overriding in cataloged procedure 100
temporary 106 regional data set 196
to establish characteristics 139 DD (data definition) information under OS/390
types of UNIX 132
comparison 154 DD compiler option 11
organization 142 DD information under OS/390 UNIX
used by PL/I record I/O 154 TITLE statement 132
unlabeled 143 DD statement 143
using 128 %INCLUDE 53
VSAM add to cataloged procedure 99
blocking 198 cataloged procedure, modifying 99
data set type 201 checkpoint/restart 347
defining 205 create a library 157
defining files 202 input data set in cataloged procedure 87
dummy data set 201 modify cataloged procedure 99
file attribute 202 modifying cataloged procedure 98
indexed data set 209 OS/390 batch compile 104
keys 200 regional data set 195
mass sequential insert 214 standard data set 104
organization 198 input (SYSIN) 105
running a program 197 output (SYSLIN, SYSPUNCH) 105
specifying ENVIRONMENT options 203 DD_DDNAME environment variables
VSAM option 204 alternate ddname under OS/390 UNIX 132
VSAM. APPEND 134
performance options 204 ASA 134
data set under OS/390 DELAY 135
associating one data set with several files 130 DELIMIT 135
concatenating 131 LRECL 136
HFS 131 LRMSKIP 136
data set under OS/390 UNIX PROMPT 136
associating a PL/I file with a data set PUTPAGE 136
how PL/I finds data sets 133 RECCOUNT 137
using environment variables under 132 RECSIZE 137
using the TITLE option of the OPEN SAMELINE 137
statement 132 SKIP0 138
using unassociated files 133
Index 383
DD_DDNAME environment variables (continued) define file
specifying characteristics under OS/390 UNIX 133 associating several files with one data set 130
TYPE 138 closing a file 146
ddname concatenating several data sets 131
%INCLUDE 53 ENVIRONMENT attribute 146
standard data sets 104 opening a file 145
DEBLOCK regional data set 188
option of ENVIRONMENT 179 ENV options 189
deblocking of records 140 keys 189
declaration specifying characteristics 146
of files under OS/390 128 VSAM data set 202
DECLARE define file under OS/390
STATEMENT definition 84 associating several data sets with one file 130
TABLE statement 84 DEFINED
declaring versus UNION 240
host variables, SQL preprocessor 75 DELAY option under OS/390 UNIX
DEFAULT compiler option description 135
description and syntax 12 DELIMIT option under OS/390 UNIX
suboptions description 135
ALIGNED 17 DESCLIST compiler suboption 16
ASCII or EBCDIC 13 DESCLOCATOR compiler suboption 16
ASSIGNABLE or NONASSIGNABLE 13 descriptor 357
BYADDR or BYVALUE 13 descriptor area, SQL 73
CONNECTED or NONCONNECTED 13 DESCRIPTOR compiler option
DESCLIST or DESCLOCATOR 16 effect on performance 234
DESCRIPTOR or NODESCRIPTOR 14 DESCRIPTOR compiler suboption
DUMMY 16 description 14
E 18 descriptor header
EVENDEC or NOEVENDEC 15 descriptor list, argument passing 357
HEXADEC 18 descriptor-locator, argument passing 358
IBM or ANS 13 DFSORT 245
INITFILL or NOINITFILL 16 direct data sets 142
INLINE or NOINLINE 14 DIRECT file
LINKAGE 15 indexed ESDS with VSAM
LOWERINC | UPPERINC 17 accessing data set 212
NATIVE or NONNATIVE 14 updating data set 214
NATIVEADDR or NONNATIVEADDR 14 RRDS
NULLSYS or NULL370 15 access data set 226
ORDER or REORDER 15 DISP parameter
ORDINAL(MIN | MAX) 18 consecutive data sets 182
OVERLAP | NOOVERLAP 18 for consecutive data sets 181
RECURSVIE or NONRECURSIVE 15 to delete a data set 156
RETCODE 17 DISPLAY compiler option 19
RETURNS 16 DLLINIT compiler option 19
SHORT 16 DSCB (data set control block) 143, 158
deferred restart 349 DSNAME parameter
define data set for consecutive data sets 181, 182
associating several data sets with one file 130 DSORG subparameter 144
associating several files with one data set 130 DUMMY compiler suboption 16
closing a file 146 dummy records
concatenating several data sets 131 REGIONAL(1) data set 190
ENVIRONMENT attribute 146 VSAM 201
ESDS 207 dump
opening a file 145 calling PLIDUMP 342
specifying characteristics 146 defining data set for
DD statement 343
logical record length 343

dump (continued) environment variables
identifying beginning of 343 setting under OS/390 UNIX 154
PLIDUMP built-in subroutine 342 EQUALS sort option 249
producing Language Environment for OS/390 & VM error
dump 342 severity of error compilation 9
SNAP 343 error devices
DYNALLOC sort option 249 redirecting 155
ESDS
using alternate index
E ESDS (entry-sequenced data set)
E compiler message 60 defining 207
E compiler suboption 18 nonunique key alternate index path 216
E15 input handling routine 256 unique key alternate index path 215
E35 output handling routine 259 updating 208
EBCDIC VSAM 199
compiler suboption 13 loading 206
EBCDIC (Extended Binary Coded Decimal Interchange statements and options 206
Code) 140 EVENDEC compiler suboption 15
embedded examples
CICS statements 85 calling PLIDUMP 342
SQL statements 74 EXEC SQL statements 66
ENDFILE EXEC statement
under OS/390 113 cataloged procedure, modifying 99
Enterprise PL/I library xv compiler 104
entry point introduction 104
sort program 251 maximum length of option list 107
entry-sequenced data set minimum region size 104
defining 207 modify cataloged procedure 99
updating 208 OS/390 batch compile 101, 104
VSAM 199 PARM parameter 107
loading an ESDS 206 to specify options 107
SEQUENTIAL file 207 Exit (E15) input handling routine 256
statements and options 206 Exit (E35) output handling routine 259
ENVIRONMENT attribute EXIT compiler option 19
list 146 export command 133
specifying characteristics under OS/390 UNIX extended binary coded decimal interchange code
BUFSIZE 134 (EBCDIC) 140
ENVIRONMENT options EXTERNAL attribute 56
BUFFERS option external references
CONSECUTIVE 163, 179 concatenating names 129
CTLASA and CTL360 179 EXTRN compiler option 19
DEBLOCK 179
equivalent DCB subparameters 148
GRAPHIC option 165 F
KEYLENGTH option F option of ENVIRONMENT
organization options 147 for record I/O 148
record format options 163 for stream I/O 163
RECSIZE option F-format records 140
comparison with DCB subparameter 148 FB option of ENVIRONMENT
record format 164 for record I/O 148
usage 164 for stream I/O 163
regional data set 189 FB-format records 140
VSAM FBS option of ENVIRONMENT
BKWD option 203 for record I/O 148
GENKEY option 204 for stream I/O 163
REUSE option 204
VSAM option 204
Index 385
FETCH
assembler routines 122 H
Enterprise PL/I routines 114 handling routines
OS/390 C routines 122 data for sort
field for sorting 248 input (sort exit E15) 256
file output (sort exit E35) 259
associating data sets with files 128 PLISRTB 260
closing 146 PLISRTC 262
defining data sets under OS/390 128 PLISRTD 263
establishing characteristics 139 to determine success 254
FILE attribute 56 variable length records 264
filespec 133 header label 143
FILLERS, for tab control table 172 HEXADEC compiler suboption 18
FILSZ sort option 249 HFS files
filtering messages 352 hook
FIXED location suboptions 46
TYPE option under OS/390 UNIX 138 host
fixed-length records 140 structures 82
FLAG compiler option 20 variables, using in SQL statements 75
flags, specifying compile-time options 103
FLOAT option 20
flowchart for sort 256
I
I compiler message 60
format notation, rules for xvi
IBM compiler suboption 13
forward slash (/) 132
IBMUEXIT compiler exit 352
FS option of ENVIRONMENT
IBMZC cataloged procedure 88
for record I/O 148
IBMZCB cataloged procedure 89
for stream I/O 163
IBMZCBG cataloged procedure 91
FUNC subparameter
IBMZCPG cataloged procedure 95
usage 144
IBMZCPL cataloged procedure 92
IBMZCPLG cataloged procedure 94
G identifiers
not referenced 6
GENKEY option
key classification 151 source program 6
usage 147 improving application performance 230
VSAM 203 INCAFTER compiler option 21
GET DATA statement 112 INCDIR compiler option 21
GET EDIT statement 112 %INCLUDE statement 53, 106
GET LIST statement 112 control statement 53
global control blocks source statement library 106
data entry fields 354 INCLUDE option 22
writing the initialization procedure 355 include preprocessor
writing the message filtering procedure 355 syntax 64
writing the termination procedure 356 %INCLUDE statement 22
GONUMBER compiler option 230 compiler 53
definition 20 without full preprocessor 22
GOTO statements 237 INDEXAREA option 147
graphic data 162 indexed data sets
GRAPHIC option indexed sequential data set 142
compiler 21 indexed ESDS (entry-sequenced data set)
of ENVIRONMENT 147, 165 DIRECT file 212
stream I/O 163 loading 210
graphic string constant compilation 21 SEQUENTIAL file 212
indicator variables, SQL 82
information interchange codes 140

INITFILL compiler suboption 16 key-sequenced data sets
initial volume label 143 accessing with a DIRECT file 212
initialization procedure of compiler user exit 355 accessing with a SEQUENTIAL file 212
INLINE compiler suboption 14 loading 210
input statements and options for 209
data for PLISRTA 260 KEYLEN subparameter 144
data for sort 256 KEYLENGTH option 147, 153
defining data sets for stream files 162 KEYLOC option
redirecting 155 usage 147
routines for sort program 256 keys
SEQUENTIAL 181 alternate index
skeletal code for sort 259 nonunique 216
sort data set 255 unique 215
input/output REGIONAL(1) data set 189
compiler dummy records 190
data sets 105 VSAM
data for compile and bind 89 indexed data set 200
data for compile, prelink, and link-edit 92 relative byte address 200
in cataloged procedures 88 relative record number 201
OS/390, punctuating long lines 112 KEYTO option
skeletal code for sort 257 under VSAM 206
sort data set 255 KSDS (key-sequenced data set)
INSOURCE option 22 define and load 210
interactive program unique key alternate index path 217
attention interrupt 23 updating 212
interblock gap (IBG) 139 VSAM
interchange codes 140 DIRECT file 212
INTERNAL attribute 56 loading 210
INTERRUPT compiler option 23 SEQUENTIAL file 212
interrupts
attention interrupts under interactive system 23
ATTENTION ON-units 346 L
debugging tool 346 label
main description 345 for data sets 143
invoking LANGLVL compiler option 24
cataloged procedure 97 Language Environment library xv
link-editing multitasking programs 99 large object (LOB) support, SQL preprocessor 80
multiple invocations 97 length of record
specifying under OS/390 UNIX 137
library
J compiled object modules 159
JAVA 276, 277, 278, 280, 281, 282, 283, 284, 285, creating a data set library 157
287, 288, 289, 290 creating a member 160
Java code, compiling 278, 282, 287 creating and updating a library member 158
Java code, writing 277, 281, 285 creating, examples of 158
JCL (job control language) directory 157
improving efficiency 87 extracting information from a library directory 160
using during compilation 104 general description of 142
jni how to use 156
JNI sample program 277, 281, 285 information required to create 157
JNI sample program placing a load module 159
source statement 106
source statement library 101
K SPACE parameter 157
key indexed VSAM data set 200 structure 160
system procedure (SYS1.PROCLIB) 156
Index 387
library (continued)
types of 156 M
updating a library member 160 MACRO option 25
using 156 macro preprocessor
LIMCT subparameter 144, 196 macro definition 65
LIMITS compiler option 24 options 65
line main storage for sort 251
length 170 MAP compiler option 26
numbers in messages 20 MARGINI compiler option 26
line feed (LF) MARGINS compiler option 26
definition 138 mass sequential insert 214
LINE option 163, 170 MAXMEM compiler option 27
LINECOUNT compiler option 25 MAXMSG compiler option 28
LINESIZE option MAXSTMT compiler option 28
for tab control table 172 MDECK compiler option
OPEN statement 164 description 28
link-editing message
description of 109 compiler list 60
LINKAGE compiler suboption printed format 173
effect on performance 235 run-time message line numbers 20
syntax 15 messages
Linking PL/I code filter function 355
LIST compiler option 25 modifying in compiler user exit 352
listing mixed string constant compilation 21
cataloged procedure 97 MODE subparameter
compiler usage 144
aggregate length table 57 module
ATTRIBUTE and cross-reference table 56 create and store object module 31
ddname list 3 multiple
file reference table 60 invocations
heading information 55 cataloged procedure 97
messages 60
options 55
preprocessor input 55
N
NAME compiler option 29
return codes 60
named constants
SOURCE option program 56
defining 241
statement nesting level 56
versus static variables 241
statement offset addresses 57
NAMES compiler option 29
storage offset listing 59
NATIVE compiler suboption
OS/390 batch compile 101, 106
description 14
source program 42
NATIVEADDR compiler suboption 14
statement offset address 57
NATLANG compiler option 30
storage offset listing 59
negative value
SYSPRINT 106
block-size 150
loader program, using 95
record length 149
logical not 30
NEST option 30
logical or 33
NODESCRIPTOR compiler suboption 14
loops
NOEQUALS sort option 249
control variables 238
NOEVENDEC compiler suboption 15
LOWERINC compiler suboption 17
NOINITFILL compiler suboption 16
LRECL option under OS/390 UNIX 136
NOINLINE compiler suboption 14
LRECL subparameter 139, 144
NOINTERRUPT compiler option 23
LRMSKIP option under OS/390 UNIX 136
NOMAP option 57
NONASSIGNABLE compiler suboption 13

NONCONNECTED compiler suboption 13 options under OS/390 UNIX (continued)
NONE, hooks location suboption 46 DD_DDNAME environment variables (continued)
NONNATIVE compiler suboption 14 PUTPAGE 136
NONNATIVEADDR compiler suboption 14 RECCOUNT 137
NONRECURSIVE compiler suboption 15 RECSIZE 137
NOOVERLAP compiler suboption 18 SAMELINE 137
effect on performance 236 SKIP0 138
%NOPRINT 53 TYPE 138
control statement 53 PL/I ENVIRONMENT attribute
NOSYNTAX compiler option 43 BUFSIZE 134
NOT compiler option 30 using
note statement 60 DD information 132
NTM subparameter TITLE 132
usage 144 OR compiler option 33
NULL370 compiler suboption 15 ORDER compiler suboption
NULLSYS compiler suboption 15 description 15
NUMBER compiler option 31 effect on performance 235
ORDINAL compiler suboption 18
ORGANIZATION option 153
O usage 147
object OS/390
module batch compilation
create and store 31 DD statement 104
record size 105 EXEC statement 104, 107
OBJECT compiler option listing (SYSPRINT) 106
definition 31 source statement library (SYSLIB) 106
offset specifying options 107
of tab count 172 temporary workfile (SYSUT1) 106
table 57 general compilation 101
OFFSET compiler option 31 OS/390 UNIX
OPEN statement compile-time options
subroutines of PL/I library 145 specifying 102
TITLE option 144 compiling under 101
Operating system DD_DDNAME environment variable 133
data definition (DD) information under OS/390 export command 133
UNIX 132 setting environment variables 154
OPTCD subparameter 143, 144 specifying compile-time options
optimal coding command line 102
coding style 236 using flags 103
compiler options 230 output
OPTIMIZE compiler option 230 data for PLISRTA 260
OPTIMIZE option 31 data for sort 256
%OPTION statement 53 defining data sets for stream files 162
options limit preprocessor output 28
for compiling 55 redirecting 155
for creating regional data set 186 routines for sort program 256
to specify for compilation 107 SEQUENTIAL 181
OPTIONS option 32 skeletal code for sort 259
options under OS/390 UNIX sort data set 255
DD_DDNAME environment variables SYSLIN 105
APPEND 134 SYSPUNCH 105
ASA 134 OVERLAP compiler suboption 18
DELAY 135
DELIMIT 135
LRECL 136
LRMSKIP 136
PROMPT 136
Index 389
PLIRETC built-in subroutine
P return codes for sort 254
PACKAGEs versus nested PROCEDUREs 238 PLISRTA interface 260
%PAGE 53 PLISRTB interface 260
control statement 53 PLISRTC interface 262
PAGE option 163 PLISRTD interface 263
PAGELENGTH, for tab control table 172 PLITABS external structure
PAGESIZE, for tab control table 172 control section 173
parameter passing declaration 110
argument passing 357 PLIXOPT variable 110
descriptor header 358 %POP statement 53
PARM parameter PP compiler option 33
for cataloged procedure 99 PPTRACE compiler option 34
specify options 107 PREFIX compiler option 34, 232
passing an argument 357 using default suboptions 232
performance preprocessing
VSAM options 204 %INCLUDE statement 53
performance improvement input 55
coding for performance limit output to 80 bytes 28
avoiding calls to library routines 242 source program 25
DATA-directed input and output 236 with MACRO 25
DEFINED versus UNION 240 preprocessors
GOTO statements 237 available with PL/I 63
input-only parameters 237 CICS options 85
loop control variables 238 include 64
named constants versus static variables 241 macro preprocessor 65
PACKAGEs versus nested PROCEDUREs 238 SQL options 68
REDUCIBLE functions 239 SQL preprocessor 66
string assignments 237 %PRINT 53
selecting compiler options control statement 53
ARCH 230 PRINT file
DEFAULT 233 format 176
GONUMBER 230 line length 170
OPTIMIZE 230 stream I/O 169
PREFIX 232 PRINT file
REDUCE 231 formatting conventions 110
RULES 231 punctuating output 110
PL/I record I/O 183
compiler procedure
user exit procedures 351 cataloged, using under OS/390 87
files compile and bind (IBMZCB) 89
associating with a data set under OS/390 compile and link-edit (IBMZCPL) 92
UNIX 132 compile only (IBMZC) 88
PL/I code, compiling 280, 284, 289 compile, bind, and run (IBMZCBG) 91
PL/I code, linking 280, 284, 289 compile, prelink, link-edit, and run (IBMZCPLG) 94
PL/I code, writing 278, 283, 288 compile, prelink, load and run (IBMZCPG) 95
PLICANC statement, and checkpoint/request 350 PROCEED compiler option 34
PLICKPT built-in subroutine 347 PROCESS statement
PLIDUMP built-in subroutine description 52
calling to produce a Language Environment for override option defaults 107
OS/390 & VM dump 342 PROMPT option under OS/390 UNIX 136
H option 343 prompting
syntax of 342 automatic, overriding 111
user-identifier 343 automatic, using 111
PLIREST statement 349 PRTSP subparameter
usage 144

punctuation records
automatic prompting length under OS/390 UNIX 137
overriding 111 RECSIZE option
using 111 consecutive data set 164
OS/390 defaults 164
automatic padding for GET EDIT 112 definition 149
continuation character 112 description under OS/390 UNIX 137
entering ENDFILE at terminal 113 for stream I/O 163—164
GET DATA statement 112 RECURSIVE compiler suboption 15
GET LIST statement 112 REDUCE compiler option 35
long input lines 112 effect on performance 231
SKIP option 113 reduce storage requirement 31
output from PRINT files 110 REDUCIBLE functions 239
%PUSH statement 53 region
PUT EDIT command 177 REGION parameter 99
PUTPAGE option under OS/390 UNIX 136 size, EXEC statement 104
REGION size, minimum required 87
regional data sets
R DD statement
REAL attribute 56 accessing 196
RECCOUNT option under OS/390 UNIX 137 creating 195
RECFM subparameter 144 defining files for
in organization of data set 144 regional data set 188
usage 144 specifying ENVIRONMENT options 189
record using keys 189
checkpoint 347 operating system requirement 195
data set 348 REGIONAL(1) data set
deblocking 140 accessing and updating 192
maximum size for compiler input 105 creating 190
sort program 250 using 190
record format REGIONAL option of ENVIRONMENT 189
fixed-length records 140 regions under OS/390 UNIX 137
options 163 relative byte address (RBA) 200
stream I/O 168 relative record number 201
to specify 178 relative-record data sets
types 140 accessing with a DIRECT file 226
undefined-length records 142 accessing with a SEQUENTIAL file 225
variable-length records 141 loading 223
record I/O statements and options for 221
data set RENT compiler option 36
access 181 REORDER compiler suboption
consecutive data sets 183 description 15
create 181 effect on performance 235
types of 154 RESPECT compiler option 37
data transmission 177 restarting
ENVIRONMENT option 179 requesting 349
format 148 RESTART parameter 349
record format 178 to request
record length automatic after system failure 349
regional data sets 186 automatic within a program 349
specify 139 deferred restart 349
value of 149 to cancel 349
RECORD statement 250 to modify 350
recorded key RETCODE compiler suboption 17
regional data set 189 return code
checkpoint/restart routine 347
Index 391
return code (continued) SKIP0 option under OS/390 UNIX 138
PLIRETC 254 SKIPREC sort option 249
return codes sorting
in compiler listing 60 assessing results 254
RETURNS compiler suboption 16, 236 calling sort 251
REUSE option 147, 204 CHKPT option 249
RRDS (relative record data set) choosing type of sort 246
define 224 CKPT option 249
load statements and options 221 data 245
load with VSAM 223 data input and output 256
updating 226 description of 245
VSAM DYNALLOC option 249
DIRECT file 226 E15 input handling routine 256
loading 223 EQUALS option 249
SEQUENTIAL file 225 FILSZ option 249
RULES compiler option 37 maximum record length 250
effect on performance 231 PLISRT 245
run-time PLISRTA(x) command 260—265
message line numbers 20 preparation 245
OS/390 considerations RECORD statement 256
automatic prompting 111 RETURN statement 256
formatting conventions 110 SKIPREC option 249
GET EDIT statement 112 SORTCKPT 255
GET LIST and GET DATA statements 112 SORTCNTL 255
punctuating long lines 112 SORTIN 255
SKIP option 113 sorting field 248
using PLIXOPT 110 SORTLIB 254
Running Sample Program SORTOUT 255
SORTWK 251, 254
storage
S auxiliary 251
S compiler message 60 main 251
SAMELINE option under OS/390 UNIX 137 writing input/output routines 256
sample program, running 280, 285, 290 source
SCALARVARYING option 153 key
SEMANTIC compiler option 41 in REGIONAL(1) data sets 190
sequential access listing
REGIONAL(1) data set 192 location 26
sequential data set 142 program
SEQUENTIAL file compiler list 56
ESDS with VSAM data set 105
defining and loading 207 identifiers 6
updating 208 included in compiler list 22
indexed ESDS with VSAM list 42
access data set 212 preprocessor 25
RRDS, access data set 225 shifting outside text 26
serial number volume label 143 SOURCE compiler option 42
SERVICE compiler option 42 source statement library 106
shift code compilation 21 SPACE parameter
SHORT compiler suboption 16 library 157
%SKIP 53 standard data sets 104
control statement 53 specifying compile-time options
SKIP option using flags under 103
in stream I/O 163 SPILL compiler option 42
under OS/390 113 spill file 106

SQL preprocessor structure of global control blocks (continued)
communications area 72 writing the termination procedure 356
descriptor area 73 SUB control character 140
EXEC SQL statements 66 symbol table 46
large object support 80 SYNTAX option 43
options 68 syntax, diagrams, how to read xvi
using host structures 82 SYS1.PROCLIB (system procedure library) 156
using host variables 75 SYSCHK default 347, 348
using indicator variables 82 SYSIN 105, 155
SQLCA 72 SYSIN and SYSPRINT files 173
SQLDA 73 SYSLIB
STACK subparameter %INCLUDE 53
usage 144 preprocessing 106
standard data set 104 SYSLIN 105
standard files (SYSPRINT and SYSIN) 155 SYSOUT 254
statement SYSPARM compiler option 44
nesting level 56 SYSPRINT 155
offset addresses 57 run-time considerations
% statements 53 SYSPUNCH 105
STDSYS compiler option 42 system
step abend 143 failure 349
STMT compiler option 43 restart after failure 349
STMT suboption of test 46 SYSTEM compiler options
storage SYSTEM(CICS) 44
blocking print files 170 SYSTEM(IMS) 44
library data sets 157 SYSTEM(MVS) 44
report in listing 43 SYSTEM(OS) 44
sort program 251 SYSTEM(TSO) 44
auxiliary storage 251 type of parameter list 44
main storage 251 SYSUT1 compiler data set 106
standard data sets 104
to reduce requirement 31
STORAGE compiler option 43 T
stream and record files 175, 177 tab control table 172
STREAM attribute 162 temporary workfile
stream I/O SYSUT1 106
consecutive data sets 162 terminal
data set input 174
access 168 capital and lowercase letters 176
create 165 COPY option of GET statement 176
record format 168 end of file 176
DD statement 166, 169 format of data 175
ENVIRONMENT options 163 stream and record files 175
file output 176
define 162 capital and lowercase characters 177
PRINT file 169 format of PRINT file 176
SYSIN and SYSPRINT files 173 output from PUT EDIT command 177
record formats for data transmission 149 stream and record files 177
string TERMINAL compiler option 45
graphic string constant compilation 21 terminating
string assignments 237 compilation 9
string descriptors 359 termination procedure
refid desch.string descriptors 359 compiler user exit 356
structure of global control blocks example of procedure-specific control block 356
writing the initialization procedure 355 syntax
writing the message filtering procedure 355 global 353
specific 356
Index 393
TEST compiler option variable-length records
definition 46 format 141
TIME parameter 99 sort program 264
TITLE option VB option of ENVIRONMENT
associating standard SYSPRINT file 114 for record I/O 148
description under OS/390 UNIX 132 for stream I/O 163
using 144 VB-format records 141
TITLE option under OS/390 VBS option of ENVIRONMENT
specifying character string value 128 for stream I/O 163
TITLE option under OS/390 UNIX VOLUME parameter
using files not associated with data sets 133 consecutive data sets 181, 182
trailer label 143 volume serial number
TUNE compiler option 47 direct access volumes 143
TYPE option under OS/390 UNIX 138 regional data sets 195
VS option of ENVIRONMENT
for stream I/O 163
U VSAM (virtual storage access method)
U compiler message 60 alternate index paths
U option of ENVIRONMENT data sets
for record I/O 148 alternate index paths 205
for stream I/O 163 alternate indexes 215
U-format 142 blocking 198
undefined-length records 142 choosing a type 201
UNDEFINEDFILE condition defining 205
BLKSIZE error 150 defining files for 202
line size conflict in OPEN 170 dummy data set 201
raising when opening a file under OS/390 entry-sequenced 206
UNIX 139 file attribute 202
UNDEFINEDFILE condition under OS/390 key-sequenced and indexed
DD statement error 129 entry-sequenced 209
UNDEFINEDFILE condition under OS/390 UNIX keys for 200
using files not associated with data sets 139 organization 198
UNIT parameter performance options 204
consecutive data sets 182 relative record 221
unreferenced identifiers 6 running a program with 197
updating specifying ENVIRONMENT options 203
ESDS 208 using 197
REGIONAL(1) data set 193 defining files 202
relative-record data set 226 ENV option 203
UPPERINC compiler suboption 17 performance option 204
USAGE compiler option 48 indexed data set
user exit load statement and options 209
compiler 351 mass sequential insert 214
customizing relative-record data set 223
modifying SYSUEXIT 352 VSAM option 204
structure of global control blocks 353 VTOC 143
writing your own compiler exit 353
functions 351
sort 248 W
using host variables, SQL preprocessor 75 W compiler message 60
WIDECHAR compiler option 48
WINDOW compiler option 49
V work data sets for sort 254
V option of ENVIRONMENT WRITABLE compiler option 49
for record I/O 148 Writing Java code
for stream I/O 163

Writing PL/I code
X
XINFO compiler option 50
XREF compiler option 51
Z
zero value 149
Index 395
We'd Like to Hear from You
Enterprise PL/I for z/OS and OS/390
Programming Guide
Publication No. SC27-1457-02
Please use one of the following ways to send us your comments about this book:
Mail—Use the Readers' Comments form on the next page. If you are sending the form
from a country other than the United States, give it to your local IBM branch office or
IBM representative for mailing.
Fax—Use the Readers' Comments form on the next page and fax it to this U.S. number:
800-426-7773.
Electronic mail—Use one of the following network IDs:
Internet: COMMENTS@VNET.IBM.COM
Be sure to include the following with your comments:
– Title and publication number of this book
– Your name, address, and telephone number if you would like a reply
Your comments should pertain only to the information in this book and the way the
information is presented. To request additional publications, or to comment on other IBM
information or the function of IBM products, please give your comments to your IBM
representative or to your IBM authorized remarketer.
IBM may use or distribute your comments without obligation.

Readers' Comments
Enterprise PL/I for z/OS and OS/390
Programming Guide
Publication No. SC27-1457-02
How satisfied are you with the information in this book?
Very Very
Satisfied Satisfied Neutral Dissatisfied Dissatisfied
Technically accurate
Complete
Easy to find
Easy to understand
Well organized
Applicable to your tasks
Grammatically correct and consistent
Graphically well designed
Overall satisfaction
May we contact you to discuss your comments? Yes No
Would you like to receive our response by E-Mail?
Your E-mail address
Name Address
Company or Organization
Phone No.
Cut or Fold
Readers' Comments
IBM
Along Line
SC27-1457-02

Fold and Tape Please do not staple Fold and Tape
NO POSTAGE
NECESSARY
IF MAILED IN THE
UNITED STATES
BUSINESS REPLY MAIL

FIRST-CLASS MAIL PERMIT NO. 40 ARMONK, NEW YORK
POSTAGE WILL BE PAID BY ADDRESSEE
IBM Corporation
Department HHX/H3
555 Bailey Ave
San Jose, CA 95141-1099
Fold and Tape Please do not staple Fold and Tape
Cut or Fold
SC27-1457-02 Along Line
IBM 
Program Number: 5655-H31
Printed in the United States of America

on recycled paper containing 10%
recovered post-consumer fiber.
Enterprise PL/I for z/OS and OS/390 Library

SC27-1456 Licensed Program Specifications
SC27-1457 Programming Guide
GC27-1458 Compiler and Run-Time Migration Guide
GC27-1459 Diagnosis Guide
SC27-1460 Language Reference
SC27-1461 Compile-Time Messages and Codes
SC27-1457-K2
Spine information:
IBM Enterprise PL/I for z/OS and OS/390 Programming Guide Version 3 Release 2.0

PL1

Caricato da

Informazioni sul documento

Descrizione originale:

Copyright

Formati disponibili

Condividi questo documento

Condividi o incorpora il documento

Opzioni di condivisione

Hai trovato utile questo documento?

Questo contenuto è inappropriato?

Copyright:

Formati disponibili

PL1

Caricato da

Copyright:

Formati disponibili

Enterprise PL/I for z/OS and OS/390 IBM

Fourth Edition (September 2002)

 International Business Machines Corporation 1998,2002. All rights reserved.

Part 1. Introduction . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . xiii

About This Book . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . xiv

Part 2. Compiling your program . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1

Chapter 1. Using compiler options and facilities . . . . . . . . . . . . . . . . . 3

 Copyright IBM Corp. 1991, 2002 iii

iv Enterprise PL/I Programming Guide

Chapter 2. PL/I preprocessors . . . . . . . . . . . . . . . . . . . . . . . . . . . 62

Chapter 3. Using PL/I cataloged procedures . . . . . . . . . . . . . . . . . . 87

Chapter 4. Compiling your program . . . . . . . . . . . . . . . . . . . . . . . 101

Chapter 5. Link-editing and running . . . . . . . . . . . . . . . . . . . . . . . 109

vi Enterprise PL/I Programming Guide

Chapter 6. Using data sets and files . . . . . . . . . . . . . . . . . . . . . . . 128

Chapter 7. Using libraries . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 156

Chapter 8. Defining and using consecutive data sets . . . . . . . . . . . . . 162

Chapter 9. Defining and using regional data sets . . . . . . . . . . . . . . . 186

Chapter 10. Defining and using VSAM data sets . . . . . . . . . . . . . . . . 197

Part 4. Improving your program . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 229

Chapter 11. Improving performance . . . . . . . . . . . . . . . . . . . . . . . 230

viii Enterprise PL/I Programming Guide

Part 5. Using interfaces to other products . . . . . . . . . . . . . . . . . . . . . . . . . . . 243

Chapter 12. Using the Sort program . . . . . . . . . . . . . . . . . . . . . . . 245

Chapter 13. ILC with C . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 266

Chapter 14. Interfacing with Java . . . . . . . . . . . . . . . . . . . . . . . . . 276

Part 6. Specialized programming tasks . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 315

Chapter 15. Using the SAX parser . . . . . . . . . . . . . . . . . . . . . . . . . 317

x Enterprise PL/I Programming Guide

Chapter 16. Using PLIDUMP . . . . . . . . . . . . . . . . . . . . . . . . . . . . 342

Chapter 17. Interrupts and attention processing . . . . . . . . . . . . . . . . 345

Chapter 18. Using the Checkpoint/Restart facility . . . . . . . . . . . . . . . 347

Chapter 19. Using user exits . . . . . . . . . . . . . . . . . . . . . . . . . . . . 351

Chapter 20. PL/I - Language Environment descriptors . . . . . . . . . . . . 357

xii Enterprise PL/I Programming Guide

 Copyright IBM Corp. 1991, 2002 xiii

Enterprise PL/I uses Language Environment as its run-time environment. It

Language Environment provides a common set of run-time options and callable

Using your documentation

xiv  Copyright IBM Corp. 1991, 2002

Language Environment information

Notation conventions used in this book

About This Book xv

For an example of programming syntax that follows these conventions, see

How to read the syntax notation

xvi Enterprise PL/I Programming Guide

Multiple required or optional items

About This Book xvii

──STATEMENT──item 1──item 2──┤ A ├─────────────────────────────────

where <A> is:

How to read the notational symbols

xviii Enterprise PL/I Programming Guide

Interpret this example as follows:

Enhancements in this release

About This Book xix

xx Enterprise PL/I Programming Guide

About This Book xxi

xxii Enterprise PL/I Programming Guide

 Copyright IBM Corp. 1991, 2002 1

Chapter 2. PL/I preprocessors . . . . . . . . . . . . . . . . . . . . . . . . . . . 62

2 Enterprise PL/I Programming Guide

Compile-time option descriptions

Table 3 (Page 1 of 3). Compile-time options, abbreviations, and IBM-supplied defaults