This chapter describes how to use consecutive, indexed, and regional data sets using the SAM, QSAM, ISAM and DAM access methods, and how to use teleprocessing data sets.
Figure 54 shows the facilities that are available with the various types of data sets that can be used with PL/I.
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.
CONSECUTIVE DATA SETS
VSAM KSDS SEQUENCE Key
Order DEVICES DASD ACCESS
1 By Key
2 Sequential 123 3 Backward
Alternate
index 123
Access as above
How With
Extended new keys SPANNED Yes RECORDS
DELETION
1 Space Yes, reusable
2 Space not reusable
This section describes consecutive data set organization and the ENVIRONMENT options that define consecutive data sets. It then describes how to create, access, and update consecutive data sets.
VSAM VSAM REGIONAL REGIONAL REGIONAL
ESDS RRDS INDEXED CONSECUTIVE (1) (2) (3)
Entry Num- Key Entry By By By
Order bered Order Order Region Region Region DASD DASD DASD DASD, tape, DASD DASD DASD
card, etc.
123 123 12 2 12 12 12
3 tape only
123 No No No No No No
At In With At In With With
end empty new end empty new new
slots keys slots keys keys
Yes No Yes Yes No No Yes
1 No Yes, 1 Yes, 2 No Yes, 2 Yes, 2 Yes, 2
Figure 54. A Comparison of Data Set Types Available to PL/I Record I/O
CONSECUTIVE ORGANIZATION
REWRITE FILECfile-reference); . FROMCreference) READ FILECfile-reference)
Figure 55. Statements and Options Permitted for Creating and Accessing Consecutive Data Sets
Notes to Figure 55:
1 The complete file declaration would include the attributes FILE, RECORD and ENVIRONMENT.
150 OS PL/I Optimizing Compiler: Programmer's Guide
2 The statement READ FILE (file-reference); is a valid
statement and is equivalent tOI READ FILE(file-reference) IGNORE (1);
3 The BACKWARDS attribute may be specified for files on magnetic tape.
DEFINING A CON.SECUTIVE DATA SET
A consecutive data set is defined by a file declaration with the following attributes:
DCL filename FILE RECORD
INPUT I OUTPUT I UPDATE SEQUENTIAL
BUFFERED I UNBUFFERED [BACKWARDS]
ENVIRONMENT(options);
Default file attributes are shown in Figure 45 on page 123. The file attributes are described in the OS and DOS PL/I Language Reference Manual. Options of the ENVIRONMENT attribute are discussed below.
ENVIRONMENT OPTIONS FOR CONSECUTIVE DATA SETS
CONSECUTIVE Option
The ENVIRONMENT options applicable to consecutive data sets are:
FIFBIFSIFBSIVIVBIVSIVBSIDIDBIU RECSIZECrecord-length)
BLKSIZE(block-size) SCALARVARYING
COBOL BUFFERSCn) NCPCn) TRKOFL CONSECUTIVE TOTAL
LEAVE or REREAD ASCII
BUFOFF[(n)]
CTLASA or CTL360
The options above the blank line are described in "Data Set Organization Options" on page 122, and those below the blank line are described below. D- and DB-format records are also described below.
See Figure 45 on page 123 to find which options must be specified, which are optional, and which are defaults.
The CONSECUTIVE option may be specified for a STREAM or RECORD file. It defines a file with consecutive data set organization, which is described above.
~ Syntax CONSECUTIVE
CONSECUTIVE is the default when the merged attributes from the DECLARE and OPEN statements do not include the TRANSIENT
attribute.
TOTAL Option -- In-Line Code Optimization
In general, I/O operations are performed by library subroutines called from compiled code. Under certain conditions, however, the Optimizing Compiler can, when requested, provide in-line code to carry out these operations, thus saving the overhead of library calls. This gives faster execution of the I/O
statements.
The TOTAL option aids the Optimizing Compiler in the production of efficient compiled code. In particular, it requests the compiler to use in-line code for certain I/O operations. It specifies that no attributes will be merged from the OPEN statement or the I/O statement or the DCB parameter; if a
complete set of attributes can be built up at compile time from explicitly declared and default attributes, then in-line code will be used for certain I/O operations.
~ Syntax TOTAL
The UNDEFINEDFIlE condition is raised if any attribute that was not explicitly declared appears on the OPEN statement, or if the I/O statement implies a file attribute that conflicts with a declared or default attribute.
The Checkout Compiler accepts and checks the TOTAL option but does not perform any optimization.
The TOTAL option cannot be specified for device-associated files or files reading Optical Mark Read data.
The use of in-line input/output code may result in reduced error-handling capability, In particular, if a program-check interrupt or an abend occurs during in-line input/output, the error message produced may contain incorrect offset and
statement number information. Also, execution of a GO TO
statement in an ERROR on-unit for such an interrupt may cause a further program check.
There are some differences in the optimized code that is generated under Release 5. The Release 5 implementation
generates code to call modules in the Pl/I Transient library so that mode-switching can be performed if necessary. This
implementation results in a longer instruction path than on prior releases, but is still faster than not using the TOTAL option.
Figure 56 on page 153 shows the conditions under which I/O statements are handled in-line.
When in-line code is employed to implement an I/O statement, the compiler gives an informational message.
152 OS Pl/I Optimizing Compiler: Programmer's Guide
statement1 READ SET READ INTO
WRITE FROM (fixed string) WRITE FROM
(varying string) WRITE FROM
Area2 LOCATE A
Record Variable Requirements None
Length known at compile time, maximum length for a varying string or area2
Length known at compile time
Length known at compile time, maximum length for a varying string or area2
File Attribute3 or ENVIRONMENT Option Requirements~
Not BACKWARDS for record types U, V, VB
RECSIZE known at compile time.5 SCALARVARYING option if varying string
RECSIZE known at compile time5 RECSIZE known at compile time.5 SCALARVARYING option used
RECSIZE known at compile time5 RECSIZE known at compile time.5 SCALARVARYING if varying string
Figure 56. Conditions Under Which I/O Statements Are Handled In-Line (TOTAL Option Used)
Notes to Figure 56:
1 All statements must be found to be valid during compilation.
File parameters or file variables are never handled by in-line code.
2 Including structures whose last element is an unsubscripted area.
3 4
5
File attributes are SEQUENTIAL BUFFERED, INPUT or OUTPUT.
Data set organization must be CONSECUTIVE; allowable record formats are F, FB, FS , FBS, U, V, or VB.
BLKSIZE may be specified instead of RECSIZE for unblocked record formats F, FS, V and U.
CTLASA and CTL360 Options - Printer and Punch Control
The printer/punch 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.
~ Syntax CTLASA I CTL360
The CTLASA option specifies American National Standard Vertical Carriage Positioning Characters or American National Standard Pocket Select Characters CLevel 1). The CTL360 option specifies IBM machine-code control characters.
The control characters that can be used with these options are listed with their actions in "Punching Cards and Printing" on page 163.
LEAVE and REREAD Options - Magnetic Tape Handling
The magnetic tape handling options allow you to specify the action to be taken when the end of a magnetic tape volume is reached, or when a data set on a magnetic tape volume is closed.
The LEAVE option prevents the tape from being rewound. The REREAD option rewinds the tape to permit reprocessing of the data set. If neither of these is specified, the action at end of volume or on closing of a data set is controlled by the DISP parameter of the associated DD statement.
r-::
SyntaxLEAVE I REREAD
If a data set is first read or written forward and then read backward in the same program, specify the LEAVE option to prevent rewind when the file is closed (or, with a multivolume data set, when volume switching occurs).
LEAVE and REREAD can also be specified on the CLOSE statement, as described in the OS and DOS PL/I Language Reference Manual.
The effects of the LEAVE and REREAD options are summarized in Figure 57 on page 155.
154 OS PL/I Optimizing Compiler: Programmer's Guide
ENVIRONMENT DISP
Option Parameter Action
REREAD
-
Positions the current volume to reprocess the data set. Repositioning for a BACKWARDS file is at the physical end of the data set.lEAVE
-
Positions the current volume at the logical end of the data set. Repositioning for a BACKWARDS file is at the physical beginning of the data set.Neither PASS Positions the volume at the end of the data set REREAD nor
lEAVE
DELETE Rewinds the current volume
KEEP, CATlG, Rewinds and unloads the current volume UNCATlG
Figure 57. Effect of lEAVE and REREAD options
ASCII Option
The ASCII option specifies that the code used to represent data on the data set is ASCII.
r-:=
Syntax~CII
Data sets on magnetic tape using ASCII may be created and
accessed in Pl/I. The implementation supports F, FB, U, D, and DB record formats. F, FB, and U formats are treated in the same way as with other data sets; D and DB formats, which correspond to V and VB formats with other data sets, are described below.
Only character data may be written onto an ASCII data set; when the data set is created, transmission must be from a character variable. This variable may have the attribute VARYING as well as CHARACTER, but the 2 length bytes of a varying-length
character string cannot be transmitted; in other words, varying-length character strings cannot be transmitted to an ASCII data set using a SCAlARVARYING file. Also, data
aggregates containing varying-length strings may not be transmitted.
Since an ASCII data set must be on magnetic tape, it must be of consecutive organization. The associated file must be BUFFERED.
The BUFOFF ENVIRONMENT option may be specified for ASCII data sets.
If ASCII is not specified in either the ENVIRONMENT option or the DD statement, but one of BUFOFF, D, or DB is specified, then ASCII is the default.
BUFOFF Option and Block Prefix Fields
At the beginning of each block in an ASCII data set, there may be a field known as the block prefix field. It may be from 1 to 99 bytes long. The buffer offset option, BUFOFF, specifies the length of this field to data management, so that the accessing or creation of data is started at this offset from the beginning of each physical block. Pl/I does not support access to this field, and in general it does not contain information that is used in these implementations. There is one situation in which
BUFOFF Defaults
data management does use information in the block prefix: with variable-length records (that is, D- or DB-format records), the block prefix field may be used to record the length of the block. In this case, it is 4 bytes long and contains a
right-aligned, decimal character value that gives the length of the block in bytes, including the block prefix field itself. It is then exactly equivalent to a block length field.
r-=
SyntaxLFOFF[(n)]
A numeric value equal to the length of the prefix may be
specified for Un". It may be specified as either an integer or as a variable with the attributes FIXED BINARY(31,O) STATIC.
Its minimum value is 0 and its maximum is 99. The absence of a prefix length specification indicates that the block prefix is to be used as a block length field; it implies that the field is
4 bytes long. The length of the block is inserted in the prefix by data management.
On input, any ASCII data set may be accessed if it has a block prefix field of length 1 to 99 bytes, or no block prefix field at all; and it may be accessed whether or not the block prefix field is used as a block length field.
On output, a data set using anyone of the valid record formats may be created without a block prefix, but the only situation in which the creation of a block prefix is supported by PL/I is when it is used as a block length field. The only permissible buffer offset specification on output is therefore BUFOFF, with no prefix length specification.
The BUFOFF option may be used with ASCII data sets only.
For output files, if you do not specify BUFOFF, the default is:
BUFFER offset:
F, FB, or U: 0 D, or DB: 4
With DB-format records on output files, the length of the block prefix (that is, the buffer offset) must always be either 0 or 4.
D-format and DB-format Records
The data contained in D- and DB-format records is recorded in ASCII. Each record may be of a different length. The two formats are:
D-format:
The records are unblocked; each record constitutes a single block. Each record consists of:
Four control bytes Data bytes
The 4 control bytes contain the length of the record; this value is inserted by data management and requires no action by you. In addition, there may be, at the start of the block, a block prefix field, which may contain the length of the block.
DB-format:
The records are blocked. All other information given for D-format applies to DB-format.
156 OS PL/I Optimizing Compiler: Programmer's Guide
storage Device using the ENVIRONMENT attribute.
Figure 58. Creating a Consecutive Data Set: Essential Parameters of DD Statement
CREATING A CONSECUTIVE DATA SET
When you create a consecutive data set, the associated file must
Essential Information
When you create a consecutive data set you must specify the:
• Device that will write or punch your data set (UNIT, SYSOUT, or VOLUME parameter of DD statement). A data set with consecutive organization can exist on any type of auxiliary storage device.
• Block size: you can specify the block size either in your PL/I program (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 do not specify a record format, U-format is the default.
If you want to keep a magnetic-tape or direct-access 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 will not need it after the end of your job.
When creating a data set on a direct-access device, you must specify the amount of space required for it (SPACE parameter of DD statement).
If you want your data set stored on a particular magnetic-tape or direct-access device, you must specify the volume serial number in the DD statement (SER or REF subparameter of VOLUME parameter). If you do not specify a serial number for a magnetic-tape data set that you want to keep, the operating system will allocate one, inform the operator, and print the number on your program listing.
If your data set is to follow another data set on a
magnetic-tape volume, you must use the LABEL parameter of the DD statement to indicate its sequence number on the tape.
The DCB subparameters of the DD statement that apply to
consecutive data sets are listed in Figure 59 on page 159; they are described in your JeL manual. Figure 45 on page 123 shows which options of the ENVIRONMENT attribute you can specify for consecutive data sets.
ACCESSING AND UPDATING A CONSECUTIVE DATA SET
Once a consecutive data set has been created, the file that accesses it can be opened for sequential input, for sequential output, or, for data sets on direct-access devices, for ypdate.
If you open the file for output, and extend the data set by adding records at the end, DISP=MOD must be specified in the DD statement. If DISP=MOD is not specified, the data set will be overwritten. If you open a file for update, records can be updated only in their existing sequence, and if records are to be inserted, a new data set must be created. Figure 55 on page 150 shows the statements and options for accessing and updating a consecutive data set.
158 OS PL/I Optimizing Compiler: Programmer's Guide
Subparameter Specifies
BLKSIZE Maximum number of bytes per block BUFNO Number of data 111anagement buffers
CODE Paper tape: code in which the tape is punched DEN Magnetic tape: tape recording density
FUNC Card reader or punch: function to be performed LRECL Maximum number of bytes per record
MODE Card reader or punch: mode or operation (column binary or EBCDIC and Read Column Eliminate or Optical Mark Read)
OPTCD Optional data-management services and data-set attributes
PRTSP Printer line spacing (0, 1, 2, or 3) RECFM Record format and characteristics
STACK Card reader or punch: stacker selection TRTCH Magnetic tape: tape recording technique for
7-track tape
Figure 59. DCB Subparameters for Consecutive Data Sets
When a consecutive data set is accessed by a SEQUENTIAL UPDATE file, a record must be retrieved with a READ statement before it can be updated by 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 FIlECF) INTOeB);
REWRITE FIlE(F) FROMCA);
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 s'tatement
has been executed.
The operating system does not permit updating a consecutive data set on magnetic tape except by adding records at the end. To
replace or insert records, you must read the data set and write the updated records into a new data set.
A consecutive data set on magnetic tape can be read forward or backward. If the data set is to be read backward, the
associated file must have the BACKWARDS attribute. The
BACKWARDS attribute cannot be specified when a data set has V-, VB-, VS-, VBS-, D-, or DB-format records.
When Required summarized in Figure 60, indicate the essential information you must include in the DD statement, and discuss some of the
160 OS PL/I Optimizing Compiler: Programmer's Guide
If the data set follows another data set on a magnetic-tape volume, you must use the LABEL parameter of the DD statement to indicate its sequence number on the tape.
Magnetic Tape Without IBM Standard Labels
Record Format
If a magnetic-tape data set has nonstandard labels or is
unlabeled, you must specify the block size either in your PL/I program (ENVIRONMENT attribute) or in the DD statement (BLKSIZE subparameter). The DSNAME parameter is not essential if the data set is not cataloged.
PL/I includes no facilities for processing nonstandard labels which to the operating system appear as data sets preceding or following your data set. You can either process the labels as
PL/I includes no facilities for processing nonstandard labels which to the operating system appear as data sets preceding or following your data set. You can either process the labels as