Chapter 13. Defining and using workstation VSAM data sets. IBM Version 8.5

PDF

Документ

Chapter 13. Defining and using workstation VSAM data sets

This chapter describes how you use Virtual Storage Access Method (VSAM) data sets on your workstation—including Distributed Data Management (DDM), ISAM, and BTRIEVE data sets—for record-oriented data transmission.

Platform distinction

Three access methods are discussed in connection with the PL/I workstation products; however, not all three methods are supported on every platform. Use the following as a guideline: v

DDM—supported on AIX only v

ISAM—supported on AIX and Windows v

BTRIEVE—supported on Windows only

This chapter also describes the statements you use to access the three types of

VSAM data sets—sequential, keyed, and direct. In many ways, workstation VSAM is similar to the VSAM on the mainframe. On the workstation, the terms sequential, keyed and direct are similar to the VSAM entry-sequenced data set, key-sequenced data set, and relative record data set.

The chapter concludes with a series of examples showing the PL/I statements and

DD:ddname environment variables necessary to create and access workstation

VSAM data sets.

Moving data between the workstation and mainframe

To convert mainframe VSAM files to the corresponding DDM, ISAM, or BTRIEVE files, follow the procedure documented in the prolog for the LODVSAM utility.

Make sure you specify the appropriate access method

AMTHD(DDM|ISAM|BTRIEVE).

To convert DDM, ISAM, or BTRIEVE files to corresponding mainframe VSAM files, follow the procedure documented in the prolog for the RELOAD utility. These utilities are supported on PL/I for Windows, but are not currently available on

PL/I for AIX.

Workstation VSAM organization

PL/I supports workstation VSAM sequential, keyed, and direct data sets. These correspond to PL/I consecutive, indexed, and relative data set organizations, respectively.

Both sequential and keyed access are possible with all three types of data sets.

With keyed data sets, the key, which is part of the logical record, is used for keyed access; keyed access is possible for direct data sets using relative record numbers.

Keyed access is also possible for sequential data sets using the sequential record value as a key.

All workstation VSAM data sets are stored on direct-access storage devices. The physical organization of workstation VSAM data sets differs from those used by other access methods.

287

Workstation VSAM organization

Creating and accessing workstation VSAM data sets

Your PL/I application can create workstation VSAM data sets, or it can access

VSAM data sets created by other programs. When you open a file to be associated with a workstation VSAM data set, and that data set does not exist, PL/I creates it using the attributes and options you specify in the DECLARE statement or in a

DD:ddname environment variable.

When your application accesses an existing VSAM data set, PL/I determines its type—sequential, direct, or keyed.

The operation of writing the initial data into a newly-created VSAM data set is referred to as

loading

in this publication.

Are you using the right access method?

Use each of the access methods, DDM|ISAM|BTRIEVE, to access data sets that were created with that particular access method. For example, you cannot use the

ISAM access method to access data sets you created with the BTRIEVE access method.

Determining which type of workstation VSAM data set you need

Use the three different types of data sets according to the following purposes: v

Use

sequential data sets

for data that you access primarily in the order in which the records were created (or the reverse order).

Use

keyed 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

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

Accessing records in workstation VSAM data sets

You can access records in all types of workstation 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, in which you select a starting point with a key and then read forward or backward from that point.

Table 15 on page 289 shows how data could be stored in the three different types

of workstation VSAM data sets and illustrates their respective advantages and disadvantages.

288

PL/I for Windows Programming Guide

Workstation VSAM organization

Table 15. Types and advantages of workstation VSAM data sets

Data Set Type Method of

Loading

Method of

Reading

Method of

Updating

Sequential

Keyed

Direct

Pros and Cons

Sequentially

(forward only)

The sequential record value of each record can be obtained and used as a key

Either sequentially or randomly by key

SEQUENTIAL backward or forward

KEYED using the sequential record value

Positioning by key followed by sequential either backward or forward

KEYED by specifying key of record

SEQUENTIAL backward or forward in order of any index

Positioning by key followed by sequential reading either backward or forward

Sequentially starting from slot

KEYED specifying numbers as key

New records at end only

Access can be sequential or

KEYED

Record deletion allowed

KEYED specifying a key

SEQUENTIAL following positioning by key

Record deletion allowed

Record insertion allowed

KEYED specifying number of slot

Positioning by key followed by sequential writes

Sequential forward or backward omitting empty records

Advantages

Simple fast creation

Uses

For uses where data is primarily accessed sequentially

Advantages

Complete access and updating

Uses

For uses where access is related to key

Sequentially starting at a specified slot and continuing with next slot

Record deletion allowed

Record insertion into empty slots allowed

Advantages

Speedy access to record by number

Keyed specifying numbers as key

Disadvantages

Structure tied to numbering sequences

Uses

For use where records are accessed by number

Using keys for workstation VSAM data sets

All workstation VSAM data sets can have keys associated with their records. For keyed data sets, the key is a defined field within the logical record. For sequential data sets, the key is the sequential record value of the record. For relative record data sets, the key is a

relative record number

Using keys for workstation VSAM keyed data sets

Keys for keyed data sets 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.

Chapter 13. Defining and using workstation VSAM data sets

289

Workstation VSAM organization

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 the

PL/I Language Reference

Using sequential record values

Sequential record values allow you to use keyed access on a sequential data set associated with a KEYED SEQUENTIAL file.

BTRIEVE and ISAM

The sequential record values, or keys, are character strings of length 7, and their values are defined by workstation VSAM.

You cannot construct or manipulate sequential record values in PL/I; you can, however, compare their values in order to determine the relative positions of records within the data set. Sequential record values are not normally printable.

You can obtain the sequential record value 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 a sequential record value obtained in either of these ways in the KEY option of a READ or REWRITE statement.

Using relative record numbers

Records in a direct data set 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 10. 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 10 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 10, with leading zeros suppressed.

Choosing a data set type

When planning your application, you must first decide which type of data set to use. There are three types of workstation VSAM data sets and five types of non-VSAM data sets available to you. Workstation VSAM data sets can provide all the functions of the other types of data sets, plus additional functions available only with workstation VSAM. Workstation VSAM can usually match, or even improve upon, the performance of other data set types. However, workstation

VSAM is more subject to performance degradation through misuse of functions.

Table 15 on page 289 shows you the possibilities available with each type of

workstation VSAM data set. When choosing between the workstation VSAM data set types, you should base your decision on the most common sequence in which your program accesses your data. You can use the following procedure to ensure a combination of data sets and indexes that provide the function you require:

Determine the type of data and how it is accessed.

Primarily sequentially — favors ESDS.

Primarily by key — favors KSDS.

Primarily by number — favors RRDS.

Determine how you 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

290

PL/I for Windows Programming Guide

Choosing a data set type

alternative for some applications. Table 16 on page 292 shows types of

processing that you can use on alternate index paths

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

has unique or nonunique keys. The use of nonunique keys can limit key processing. However, it might also be impractical to assume that you 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.

When you have determined the data sets and paths that you require, ensure

that the operations you have in mind are supported. Figure 18 shows the

workstation VSAM data sets and the file attributes that you can specify.

Do not try to access a dummy workstation VSAM data set, because you will receive an error message indicating that you have an undefined file.

Table 17 on page 295, Table 18 on page 298, and Table 19 on page 305 show the

statements allowed for sequential data sets, keyed data sets, and direct data sets, respectively.

INPUT

SEQUENTIAL

ESDS

KSDS

RRDS

Path(N)

Path(U)

OUTPUT

ESDS

RRDS

UPDATE

ESDS

KSDS

RRDS

Path(N)

Path(U)

KEYED SEQUENTIAL

ESDS

KSDS

RRDS

Path(N)

Path(U)

ESDS

KSDS

RRDS

ESDS

KSDS

RRDS

Path(N)

Path(U)

DIRECT

KSDS

RRDS

Path(U)

KSDS

RRDS

Path(U)

KSDS

RRDS

Path(U)

Key: ESDS

KSDS

Entry-sequenced data set

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 18. VSAM data sets and allowed file attributes

Chapter 13. Defining and using workstation VSAM data sets

291

Choosing a data set type

Table 16. Processing allowed on alternate index paths

Base Cluster Type Alternate Index Key Type

KSDS Unique key

Processing

As normal KSDS

Nonunique key Limited keyed access

ESDS Unique key

Nonunique key

As KSDS

Limited keyed access

Restrictions

May not modify key of access.

No deletion.

May not modify key of access.

No deletion.

May not modify key of access.

Defining files for workstation VSAM data sets

You define a workstation VSAM sequential data set by using a file declaration with the following attributes: dcl Filename file record input | output | update sequential buffered

[keyed] environment(options);

You define a workstation VSAM keyed data set by using a file declaration with the following attributes: dcl Filename file record input | output | update sequential | direct buffered | unbuffered

[keyed] environment(options);

You define a workstation VSAM direct data set by using a file declaration with the following attributes: dcl Filename file record input | output | update direct | sequential unbuffered | buffered

[keyed] environment(options);

The file attributes are described in the

PL/I Language Reference

for this product.

Options of the ENVIRONMENT attribute are discussed below.

Specifying options of the PL/I ENVIRONMENT attribute

Many of the options of the PL/I ENVIRONMENT attribute affecting data set structure are not needed for workstation 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 workstation VSAM data sets are:

292

PL/I for Windows Programming Guide

Defining files for workstation VSAM data sets

CONSECUTIVE

CTLASA

GENKEY

GRAPHIC

KEYLENGTH

KEYLOC

ORGANIZATION(CONSECUTIVE|INDEXED|RELATIVE)

RECSIZE

SCALARVARYING

VSAM

For a complete explanation of these ENVIRONMENT options and how to use

them, see “Specifying characteristics using the PL/I ENVIRONMENT attribute” on page 233. In addition to this list of ENVIRONMENT options, there is a set of

options that can be used with a DD statement, see “Specifying characteristics using

DD:ddname environment variables” on page 239.

Adapting existing programs for workstation VSAM

This section is intended primarily for PL/I for z/OS users who are transferring programs to the workstation.

In most cases, if your PL/I program uses files declared with ENVIRONMENT

(CONSECUTIVE) or ENVIRONMENT(INDEXED) or with no PL/I

ENVIRONMENT attribute, it can access workstation VSAM data sets without alteration. PL/I detects that a workstation VSAM data set is being opened and can provide the correct access.

You can readily adapt existing programs with CONSECUTIVE, INDEXED,

REGIONAL(1) or VSAM files for use with workstation VSAM data sets. Programs with consecutive files might not need alteration, and there is never any necessity to alter programs with indexed files unless the logic depends on EXCLUSIVE files.

Programs with REGIONAL(1) data sets require only minor revision.

The following sections tell you what modifications you might need to make in order to adapt files for the workstation.

Adapting programs using CONSECUTIVE files

There is no concept of fixed-length records in DDM, but there is in ISAM and

BTRIEVE. If your program relies on the RECORD condition to detect incorrect length records, it does not function in the same way using workstation VSAM data sets as it does with non-workstation VSAM data sets.

If the logic of the program depends on raising the RECORD condition when a record of an incorrect length is found, you must write your own code to check for the record length and take the necessary action. This is because records of any length up to the maximum specified are allowed in workstation VSAM data sets.

Adapting programs using INDEXED files

Compatibility is provided for INDEXED files. For files that you declare with the

INDEXED ENVIRONMENT option, PL/I associates the file with a workstation

VSAM keyed data set. UNDEFINEDFILE is raised if the data set is any other type.

Because mainframe ISAM record handling differs in detail from workstation VSAM record handling, workstation VSAM processing might not always give the required result.

Chapter 13. Defining and using workstation VSAM data sets

293

Defining files for workstation VSAM data sets

You should remove dependence on the RECORD condition, and insert your own code to check for record length if this is necessary. You should also remove any checking for deleted records.

Adapting programs using REGIONAL(1) files

You can alter programs using REGIONAL(1) data sets to use workstation VSAM direct data sets. Remove REGIONAL(1) and any other implementation-dependent options from the file declaration and replace them with

ENV(ORGANIZATION(RELATIVE)). You should also remove any checking for deleted records, because workstation VSAM deleted records are not accessible to you.

Adapting programs using VSAM files

If you use the VSAM ENVIRONMENT option, the associated workstation VSAM data set must exist before the file is opened. You can create your data sets with a

simple program. Figure 19 is an example of creating a workstation VSAM keyed

data set.

/********************************************************************/

/* */

/* NAME - ISAM0.PLI

/* DESCRIPTION

/* Create an ISAM Keyed data set

/********************************************************************/

NewVSAM: proc options(main); declare

NewFile keyed record output file env(organization(indexed) recsize(80) keylength(8) keyloc(17)

); open file(NewFile) title(’/keynames.dat’); close file(NewFile);

End NewVSAM;

Figure 19. Creating a workstation VSAM keyed data set

If the data set named KEYNAMES.DAT does not already exist, PL/I creates it with that name when the OPEN statement is executed.

294

PL/I for Windows Programming Guide

Using workstation VSAM sequential data sets

Using workstation VSAM sequential data sets

The statements and options allowed for files associated with a workstation VSAM

sequential data set are shown in Table 17.

Table 17. Statements and options allowed for loading and accessing workstation VSAM sequential data sets

File declaration

Valid statements, with options you must include

Other options you can also include

SEQUENTIAL OUTPUT

BUFFERED

WRITE FILE(file-reference)

FROM(reference);

KEYTO(reference)

SEQUENTIAL OUTPUT

UNBUFFERED

SEQUENTIAL INPUT

BUFFERED

SEQUENTIAL INPUT

UNBUFFERED

SEQUENTIAL UPDATE

BUFFERED

SEQUENTIAL UPDATE

UNBUFFERED

LOCATE based-variable

FILE(file-reference);

WRITE FILE(file-reference)

FROM(reference);

READ FILE(file-reference)

INTO(reference);

READ FILE(file-reference)

SET(pointer-reference);

SET(pointer-reference)

KEYTO(reference)

KEYTO(reference) or

KEY(expression)

KEYTO(reference) or

KEY(expression)

READ FILE(file-reference);

READ FILE(file-reference)

INTO(reference);

READ FILE(file-reference);

READ FILE(file-reference)

INTO(reference);

IGNORE(expression)

KEY(expression)

KEYTO(reference) or

IGNORE(expression)

KEYTO(reference) or

KEY(expression)

KEYTO(reference) or

KEY(expression)

READ FILE(file-reference)

SET(pointer-reference);

READ FILE(file-reference)

WRITE FILE(file-reference)

FROM(reference);

REWRITE

FILE(file-reference)

FROM(reference);

IGNORE(expression)

KEYTO(reference) WRITE FILE(file-reference)

FROM(reference);

REWRITE

FILE(file-eference);

FROM(reference) and/or

KEY(expression)

DELETE FILE(file-reference);

READ FILE(file-reference)

INTO(reference);

KEY(expression)

KEYTO(reference) or

READ FILE(file-reference);

IGNORE(expression)

KEYTO(reference)

KEY(expression)

Chapter 13. Defining and using workstation VSAM data sets

295

Using workstation VSAM sequential data sets

Table 17. Statements and options allowed for loading and accessing workstation VSAM sequential data sets (continued)

File declaration

Valid statements, with options you must include

Other options you can also include

Notes:

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.

The statement “READ FILE(file-reference);” is equivalent to the statement “READ

FILE(file-reference) IGNORE (1);”

The expression used in the KEY option must be a sequential record value, previously obtained by means of the KEYTO option.

Using a sequential file to access a workstation VSAM sequential data set

When a sequential data set is being loaded, the associated file must be opened for

SEQUENTIAL OUTPUT. The records are stored in the order in which they are presented.

You can use the KEYTO option to obtain the sequential record value of each record as it is written. You can subsequently use these keys to achieve keyed access to the data set.

You can open a SEQUENTIAL file that is used to access a workstation VSAM sequential data set 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 occurs 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 sequential record value of the records that are read. If you use the KEY option, the record that is recovered is the one with the sequential record value 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 sequential record value if you use the KEY option; otherwise, it is the record accessed on the previous READ.

Defining and loading a workstation VSAM sequential data set

Figure 20 on page 297 is an example of a program that defines and loads a

workstation VSAM sequential data set. You can also use this program to process a

DDM or SFS file by modifying the AMTHD specification.

The PL/I program writes the data set using a SEQUENTIAL OUTPUT file and a

WRITE FROM statement.

The sequential record values 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:

296

PL/I for Windows Programming Guide

Using workstation VSAM sequential data sets

dcl Chars char(7); /*DDM uses 4; BTRIEVE and ISAM use 7 as shown */ write file(Famfile) from (String) keyto(Chars); dcl Chars char(4); /* DDM uses 4 */ write file(Famfile) from (String) keyto(Chars);

The keys would not normally be printable, but could be retained for subsequent use.

/********************************************************************/

/* */

/* DESCRIPTION

Define and load an ISAM sequential data set.

/* USAGE

The following commands are required to establish the environment variables to run this program:

SET DD:IN=ISAM1.INP,RECSIZE(38)

SET DD:FAMFILE=ISAM1.OUT,AMTHD(ISAM),RECSIZE(38)

/* REMARKS: Restrict test to ASCII format.

/********************************************************************/

CREATE: proc options(main); put skip list(’START ISAM1 TEST’); dcl

FamFile file sequential output env(organization(consecutive)),

In file record input,

Eof bit(1) init(’0’b), i fixed(15),

String char(38); on endfile(In) Eof = ’1’b; read file(In) into (String); do i=1 by 1 while (¬Eof); put file(sysprint) skip edit (String) (a); write file(FamFile) from (String); read file(In) into (String); end; put skip edit(i-1,’ records processed ’)(a); put skip list(’END ISAM1 TEST’); end CREATE;

The input data for this program might look like this:

Fred

Andy

Susan

Figure 20. Defining and loading a workstation VSAM sequential data set

Chapter 13. Defining and using workstation VSAM data sets

297

Using workstation VSAM sequential data sets

Updating a sequential data set

The program illustrated in Figure 20 on page 297 can be used to update a

workstation VSAM sequential data set. If it is run again, new records are added on the end of the data set.

You can rewrite existing records in a sequential data set, 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 must be sequential record values from a previous WRITE or READ statement.

Workstation VSAM keyed data sets

The statements and options allowed for workstation VSAM keyed data sets are

shown in Table 18.

Table 18. Statements and options allowed for loading and accessing workstation VSAM keyed data sets

File declaration

Valid statements, with options you must include

Other options you can also include

SEQUENTIAL OUTPUT

BUFFERED

WRITE FILE(file-reference)

FROM(reference)

KEYFROM(expression);

SET(pointer-reference)

SEQUENTIAL OUTPUT

UNBUFFERED

SEQUENTIAL INPUT

BUFFERED

LOCATE based-variable

FILE(file-reference)

KEYFROM(expression);

WRITE FILE(file-reference)

FROM(reference)

KEYFROM(expression);

READ FILE(file-reference)

INTO(reference);

KEY(expression) or

KEYTO(reference)

SEQUENTIAL INPUT

UNBUFFERED

SEQUENTIAL UPDATE

BUFFERED

READ FILE(file-reference)

SET(pointer-reference);

READ FILE(file-reference);

READ FILE(file-reference)

INTO(reference);

READ FILE(file-reference);

READ FILE(file-reference)

INTO(reference);

KEY(expression) or

KEYTO(reference)

IGNORE(expression)

KEY(expression) or

KEYTO(reference)

IGNORE(expression)

KEY(expression) or

KEYTO(reference)

READ FILE(file-reference)

SET(pointer-reference);

READ FILE(file-reference);

KEY(expression) or

KEYTO(reference)

IGNORE(expression)

WRITE FILE(file-reference)

FROM(reference)

KEYFROM(expression);

REWRITE

FILE(file-reference);

FROM(reference) and/or

KEY(expression)

DELETE FILE(file-reference) KEY(expression)

298

PL/I for Windows Programming Guide

Workstation VSAM keyed data sets

Table 18. Statements and options allowed for loading and accessing workstation VSAM keyed data sets (continued)

File declaration

Valid statements, with options you must include

Other options you can also include

SEQUENTIAL UPDATE

UNBUFFERED

READ FILE(file-reference)

INTO(reference);

KEY(expression) or

KEYTO(reference)

READ FILE(file-reference);

WRITE FILE(file-reference)

FROM(reference)

KEYFROM(expression);

REWRITE

FILE(file-reference)

FROM(reference);

KEY(expression)

DIRECT

BUFFERED

DIRECT

UNBUFFERED

DIRECT OUTPUT

BUFFERED

DIRECT OUTPUT

UNBUFFERED

DIRECT

INPUT

UPDATE

BUFFERED

DELETE

FILE(file-reference);

READ FILE(file-reference)

INTO(reference)

KEY(expression);

READ FILE(file-reference)

SET(pointer-reference)

KEY(expression);

READ FILE(file-reference)

INTO(reference)

KEY(expression);

WRITE FILE(file-reference)

FROM(reference)

KEYFROM(expression);

WRITE FILE(file-reference)

FROM(reference)

KEYFROM(expression);

READ FILE(file-reference)

INTO(reference)

KEY(expression);

KEY(expression)

READ FILE(file-reference)

SET(pointer-reference)

KEY(expression);

REWRITE

FILE(file-reference)

FROM(reference)

KEY(expression);

DELETE FILE(file-reference)

KEY(expression);

WRITE FILE(file-reference)

FROM(reference)

KEYFROM(expression);

Chapter 13. Defining and using workstation VSAM data sets

299

Workstation VSAM keyed data sets

Table 18. Statements and options allowed for loading and accessing workstation VSAM keyed data sets (continued)

File declaration

Valid statements, with options you must include

Other options you can also include

DIRECT

UPDATE

UNBUFFERED

READ FILE(file-reference)

INTO(reference)

KEY(expression);

REWRITE

FILE(file-reference)

FROM(reference)

KEY(expression);

DELETE FILE(file-reference)

KEY(expression);

WRITE FILE(file-reference)

FROM(reference)

KEYFROM(expression);

Notes:

The complete file declaration could 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.

The statement READ FILE(file-reference); is equivalent to the statement READ

FILE(file-reference) IGNORE(1);

Do not associate a DIRECT file with a workstation VSAM data set that has duplicate key capability.

Loading a workstation VSAM keyed data set

When a keyed data set 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.

If a keyed data set already contains some records, and you open the associated file with the SEQUENTIAL and OUTPUT attributes, you can add records at the end of the data set only. Again, you must present the records in ascending key order, and you must use the KEYFROM option. In addition, the first record you present must have a key greater than the highest key present on the data set.

Figure 21 on page 301 is an example of a program that loads a workstation VSAM

keyed data set. 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 keyed data set must be loaded in this manner. You can also use this program to process a DDM or SFS file by modifying the AMTHD specification.

300

PL/I for Windows Programming Guide

Workstation VSAM keyed data sets

/********************************************************************/

/* */

/* DESCRIPTION

/* Load an ISAM keyed data set.

/* USAGE

/* The following commands are required to establish */

/* the environment variables to run this program:

SET DD:DIREC=ISAM2.OUT,AMTHD(ISAM)

SET DD:SYSIN=ISAM2.INP,RECSIZE(80)

/* */

/********************************************************************/

NAMELD: proc options(main); put skip list(’START ISAM2 TEST’); dcl Direc file record keyed sequential output env(organization(indexed) recsize(23) keyloc(1) keylength(20)

); dcl Eof bit(1) init(’0’b); dcl 1 IoArea,

5 Name char(20),

5 Number char(3); on endfile(sysin) Eof = ’1’b; open file(Direc); get file(sysin) edit(Name,Number) (a(20),a(3)); do while (¬Eof); write file(Direc) from(IoArea) keyfrom(Name); get file(sysin) edit(Name,Number) (a(20),a(3)); end; close file(Direc); put skip list(’END ISAM2 TEST’); end NAMELD;

Figure 21. Defining and loading a workstation VSAM keyed data set

Chapter 13. Defining and using workstation VSAM data sets

301

Workstation VSAM keyed data sets

The input file for this program could be:

ACTION,G.

BAKER,R.

BRAMLEY,O.H.

CHEESMAN,D.

CORY,G.

ELLIOTT,D.

FIGGINS,S.

HARVEY,C.D.W.

HASTINGS,G.M.

KENDALL,J.G.

LANCASTER,W.R.

MILES,R.

NEWMAN,M.W.

PITT,W.H.

ROLF,D.E.

SHEERS,C.D.

SURCLIFFE,M.

TAYLOR,G.C.

WONG, X-G.

WILTON,L.W.

WINSTONE,E.M.

VISWANATHAN, I.

162

152

248

141

336

875

413

205

391

294

624

233

450

515

114

241

472

407

509

404

307

411

Defining and loading a workstation VSAM keyed data set (continued)

Using a SEQUENTIAL file to access a workstation VSAM keyed data set

You can open a SEQUENTIAL file that is used to access a keyed data set with either the INPUT or the UPDATE attribute.

For READ statements without the KEY option, the records are recovered in ascending key order. You can obtain the key of a record recovered in this way by using the KEYTO option.

If you use the KEY option, the record recovered by a READ statement is the one with the specified key. This READ statement positions the data set at the specified record; subsequent sequential reads recover the following records in key 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. 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.

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 specified key; otherwise, it is the record that was accessed by the previous READ statement.

Using a DIRECT file to access a workstation VSAM keyed data set

You can open a DIRECT file that is used to access a workstation VSAM keyed data set with the INPUT, OUTPUT, or UPDATE attribute.

302

PL/I for Windows Programming Guide

Workstation VSAM keyed data sets

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 22 shows one method you can use to update a keyed data set. You can also

use this program to process a DDM or SFS file by modifying the AMTHD specification.

/********************************************************************/

/* */

/* DESCRIPTION

Update an ISAM keyed data set by key.

/* USAGE

The following commands are required to establish the environment variables to run this program:

SET DD:DIREC=ISAM2.OUT,AMTHD(ISAM)

SET DD:SYSIN=ISAM3.INP,RECSIZE(80)

Note: This program is using isam2.out file created by the previous sample program NAMELD.

/********************************************************************/

DIRUPDT: proc options(main); put skip list(’ISAM3 TEST START’); dcl Direc file record keyed update env(organization(indexed) recsize(23) keyloc(1) keylength(20)

); dcl 1 IoArea,

5 NewArea,

10 Name char(20),

10 Number char(3),

5 Code char(1); dcl oncode builtin; dcl Eof bit(1) init(’0’b); on endfile(sysin) Eof = ’1’b; on key(Direc) begin; if oncode=51 then put file(sysprint) skip edit

(’Not found: ’,Name)(a(15),a); if oncode=52 then put file(sysprint) skip edit

(’Duplicate: ’,Name)(a(15),a); end; open file(Direc) direct update;

Figure 22. Updating a workstation VSAM keyed data set

Chapter 13. Defining and using workstation VSAM data sets

303

Workstation VSAM keyed data sets

get file(sysin) edit (Name,Number,Code) (a(20),a(3),a(1)); do while (¬Eof); put file(sysprint) skip edit (’ ’,Name,’#’,Number,’ ’,Code)

(a(1),a(20),a(1),a(3),a(1),a(1)); select (Code); when(’A’) write file(Direc) from(NewArea) keyfrom(Name); when(’C’) rewrite file(Direc) from(NewArea) key(Name); when(’D’) delete file(Direc) key(Name); end; otherwise put file(sysprint) skip edit

(’Invalid code: ’,Name) (a(15),a); end; get file(sysin) edit (Name,Number,Code) (a(20),a(3),a(1)); close file(Direc); put file(sysprint) page;

*/ /* Display the updated file open file(Direc) sequential input;

Eof = ’0’b; on endfile(Direc) Eof = ’1’b; read file(Direc) into(NewArea); do while(¬Eof); put file(sysprint) skip edit(Name,Number)(a,a); read file(Direc) into(NewArea); end; close file(Direc); put skip list(’ISAM3 TEST END’); end DIRUPDT;

An input file for this program might look like this one:

NEWMAN,M.W.

GOODFELLOW,D.T.

MILES,R.

HARVEY,C.D.W.

BARTLETT,S.G.

CORY,G.

READ,K.M.

PITT,W.H.

ROLF,D.E.

ELLIOTT,D.

HASTINGS,G.M.

BRAMLEY,O.H.

GABRIELLI, M.

516C

889A

209A

183A

001A

291C

439C

Updating a workstation VSAM keyed data set (continued)

The program uses a DIRECT update file and alters the data according to a code that is passed into the records in the file SYSIN:

Add a new record

Change the number of an existing name

Delete a record

The program reads the name, number, and code and takes action according to the value of the code. A KEY ON-unit is used to handle any incorrect keys. When the updating is finished the file DIREC is closed and reopened with the attributes

SEQUENTIAL INPUT. The file is then read sequentially and printed.

304

PL/I for Windows Programming Guide

Workstation VSAM direct data sets

Workstation VSAM direct data sets

The statements and options allowed for workstation VSAM direct data sets are:

Table 19. Statements and options allowed for loading and accessing workstation VSAM direct data sets

File declaration

Valid statements, with options you must include

Other options you can also include

SEQUENTIAL OUTPUT

BUFFERED

WRITE FILE(file-reference)

FROM(reference);

KEYFROM(expression) or

KEYTO(reference)

SEQUENTIAL OUTPUT

UNBUFFERED

SEQUENTIAL INPUT

BUFFERED

LOCATE based-variable

FILE(file-reference);

WRITE FILE(file-reference)

FROM(reference);

READ FILE(file-reference)

INTO(reference);

SET(pointer-reference)

KEYFROM(expression) or

KEYTO(reference)

KEY(expression) or

KEYTO(reference)

SEQUENTIAL INPUT

UNBUFFERED

SEQUENTIAL UPDATE

BUFFERED

SEQUENTIAL UPDATE

UNBUFFERED

READ FILE(file-reference)

SET(pointer-reference);

READ FILE(file-reference);

READ FILE(file-reference)

INTO(reference);

READ FILE(file-reference);

READ FILE(file-reference)

INTO(reference);

READ FILE(file-reference)

SET(pointer-reference);

READ FILE(file-reference);

WRITE FILE(file-reference)

FROM(reference);

REWRITE

FILE(file-reference);

DELETE FILE(file-reference);

READ FILE(file-reference)

INTO(reference);

READ FILE(file-expression);

WRITE FILE(file-reference)

FROM(reference);

REWRITE

FILE(file-reference)

FROM(reference);

DELETE

FILE(file-reference);

KEY(expression) or

KEYTO(reference)

IGNORE(expression)

KEY(expression) or

KEYTO(reference)

IGNORE(expression)

KEY(expression) or

KEYTO(reference)

KEY(expression) or

KEYTO(reference)

IGNORE(expression)

KEYFROM(expression) or

KEYTO(reference)

FROM(reference) and/or

KEY(expression)

KEY(expression) or

KEYTO(reference)

IGNORE(expression)

KEYFROM(expression) or

KEYTO(reference)

KEY(expression)

Chapter 13. Defining and using workstation VSAM data sets

305

Workstation VSAM direct data sets

Table 19. Statements and options allowed for loading and accessing workstation VSAM direct data sets (continued)

File declaration

Valid statements, with options you must include

Other options you can also include

DIRECT OUTPUT

BUFFERED

DIRECT OUTPUT

UNBUFFERED

DIRECT INPUT

BUFFERED

WRITE FILE(file-reference)

FROM(reference)

KEYFROM(expression);

WRITE FILE(file-reference)

FROM(reference)

KEYFROM(expression);

READ FILE(file-reference)

INTO(reference)

KEY(expression);

DIRECT INPUT

UNBUFFERED

DIRECT UPDATE

BUFFERED

READ FILE(file-reference)

SET(pointer-reference)

KEY(expression);

READ FILE(file-reference)

KEY(expression);

READ FILE(file-reference)

INTO(reference)

KEY(expression);

DIRECT UPDATE

UNBUFFERED

READ FILE(file-reference)

SET(pointer-reference)

KEY(expression);

REWRITE

FILE(file-reference)

FROM(reference)

KEY(expression);

DELETE FILE(file-reference)

KEY(expression);

WRITE FILE(file-reference)

FROM(reference)

KEYFROM(expression);

READ FILE(file-reference)

INTO(reference)

KEY(expression);

REWRITE

FILE(file-reference)

FROM(reference)

KEY(expression);

DELETE FILE(file-reference)

KEY(expression);

WRITE FILE(file-reference)

FROM(reference)

KEYFROM(expression);

306

PL/I for Windows Programming Guide

Workstation VSAM direct data sets

Table 19. Statements and options allowed for loading and accessing workstation VSAM direct data sets (continued)

File declaration

Valid statements, with options you must include

Other options you can also include

Notes:

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 statement READ FILE(file-reference); is equivalent to the statement READ

FILE(file-reference) IGNORE(1);

Loading a workstation VSAM direct data set

When a direct data set 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 “Using keys for workstation VSAM data sets” on page 289).

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 using the KEYTO option.

If you want to load a direct data set sequentially, without use of the KEYFROM or

KEYTO options, you are not required to use 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.

Figure 23 on page 308 is an example of a program that defines and loads a

workstation VSAM direct data set. In the PL/I program, the data set is loaded with a DIRECT OUTPUT file and a WRITE...FROM...KEYFROM statement is used.

You can also use this program to process a DDM or SFS file by modifying the

AMTHD specification.

If the data were in order and the keys in sequence, it would be possible to use a

SEQUENTIAL file and write into the data set from the start. The records would then be placed in the next available slot and given the appropriate number. The number of the key for each record could be returned using the KEYTO option.

Chapter 13. Defining and using workstation VSAM data sets

307

Workstation VSAM direct data sets

/**********************************************************************/

/* DESCRIPTION */

Load an ISAM direct data set.

/* USAGE

/* The following commands are required to establish

/* the environment variables to run this program:

SET DD:SYSIN=ISAM4.INP,RECSIZE(80)

SET DD:NOS=ISAM4.OUT,AMTHD(ISAM),RECCOUNT(100)

/*********************************************************************/

CREATD: proc options(main);

*/ put skip list(’ISAM4 TEST START’); dcl Nos file record output direct keyed env(organization(relative) recsize(20) ); dcl Sysin file input record; dcl 1 In_Area,

2 Name char(20),

2 Number char( 2); dcl Sysin_Eof bit (1) init(’0’b); dcl Ntemp fixed(15); on endfile (Sysin) Sysin_Eof = ’1’b; open file(Nos); read file(Sysin) into(In_Area); do while(¬Sysin_Eof);

Ntemp = Number; write file(Nos) from(Name) keyfrom(Ntemp); put file(sysprint) skip edit (In_Area) (a); read file(Sysin) into(In_Area); end; close file(Nos); put skip list(’ISAM4 TEST END’); end CREATD;

This could be the input file for this program:

ACTION,G.

BAKER,R.

BRAMLEY,O.H.

CHEESNAME,L.

CORY,G.

ELLIOTT,D.

FIGGINS,E.S.

HARVEY,C.D.W.

HASTINGS,G.M.

KENDALL,J.G.

LANCASTER,W.R.

MILES,R.

NEWMAN,M.W.

PITT,W.H.

ROLF,D.E.

SHEERS,C.D.

SURCLIFFE,M.

TAYLOR,G.C.

WILTON,L.W.

WINSTONE,E.M.

Figure 23. Loading a workstation VSAM direct data set

308

PL/I for Windows Programming Guide

Workstation VSAM direct data sets

Using a SEQUENTIAL file to access a workstation VSAM direct data set

You can open a SEQUENTIAL file that is used to access a direct data set with either the INPUT or the UPDATE attribute. If you use any of the options KEY,

KEYTO, or KEYFROM, your file must also use the KEYED attribute.

Using READ statements

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 recover the following records in sequence.

Using WRITE statements

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.

Using the REWRITE or DELETE statements

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.

You can also use DELETE statements, with or without the KEY option, to delete records from the data set.

Using a DIRECT file to access a workstation VSAM direct data set

A DIRECT file used to access a direct data set can have the OUTPUT, INPUT, or

UPDATE attribute. You can read, write, rewrite, or delete records exactly as though you were using a KEYED SEQUENTIAL file.

Figure 24 on page 310 shows a direct data set being updated. A DIRECT UPDATE

file is used and new records are written by key. You do not need to check for the records being empty, because the empty records are not available under workstation VSAM. You can also use this program to process a DDM or SFS file by modifying the AMTHD specification.

In the second half of the program, the updated file is printed. Again, you do not need to check for the empty records as there is in REGIONAL(1).

Chapter 13. Defining and using workstation VSAM data sets

309

Workstation VSAM direct data sets

/********************************************************************/

/* */

/* DESCRIPTION

Update an ISAM direct data set by key.

/* USAGE

/* Note: This sample program is using the direct ISAM data set

The following commands are required to establish the environment variables to run this program.

SET DD:SYSIN=ISAM5.INP,RECSIZE(80)

SET DD:NOS=ISAM4.OUT,AMTHD(ISAM),APPEND(Y)

*/ isam4.out created by the previous sample program CREATD.

/* */

/********************************************************************/

UPDATD: proc options(main); put skip list(’ISAM5 TEST START’); dcl Nos file record keyed env(organization(relative)); dcl Sysin file input record; dcl Sysin_Eof bit (1) init(’0’b); dcl Nos_Eof bit (1) init(’0’b); dcl 1 In_Area,

2 Name char(20),

2 (CNewNo,COldNo) char( 2),

2 In_Area_1 char( 1),

2 Code char( 1); dcl IoField char(20); dcl NewNo fixed(15); dcl OldNo fixed(15); dcl oncode builtin; on endfile (Sysin) sysin_Eof = ’1’b; open file (Nos) direct update;

Figure 24. Updating a workstation VSAM direct data set by key

310

PL/I for Windows Programming Guide

Workstation VSAM direct data sets

/* trap errors */ on key(Nos) begin; if oncode=51 then put file(sysprint) skip edit

(’Not found:’, Name) (a(15), a); if oncode=52 then put file(sysprint) skip edit

(’Duplicate:’, Name) (a(15), a); end;

/* update the direct data set */ read file(Sysin) into(In_Area); do while(¬Sysin_Eof); if CNewNo¬=’ ’ then

NewNo = CNewNo; else

NewNo = 0; if COldNo¬=’ ’ then

OldNo = COldNo; else

OldNo = 0; 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; end; read file(Sysin) into(In_Area); end; when(’D’) delete file(Nos) key(OldNo); otherwise put file(sysprint) skip list (’Invalid code:’,Name); close file(Sysin),file(Nos);

/* open and print updated file */ open file(Nos) sequential input; on endfile (Nos) Nos_Eof = ’1’b;

Updating a workstation VSAM direct data set by key (continued)

Chapter 13. Defining and using workstation VSAM data sets

311

Workstation VSAM direct data sets

read file(Nos) into(IoField) keyto(CNewNo); do while(¬Nos_Eof); put file (sysprint) skip edit (CNewNo,IoField)(a(5),a); read file(Nos) into(IoField) keyto(CNewNo); end; close file(Nos); put skip list(’ISAM5 TEST END’); end UPDATD;

An input file for this program might look like this:

NEWMAN,M.W.

GOODFELLOW,D.T.

MILES,R.

HARVEY,C.D.W.

BARTLETT,S.G.

CORY,G.

READ,K.M.

WONG,X-G.

PITT,W.H.

ROLF,D.F.

ELLIOTT,D.

HASTINGS,G.M.

BRAMLEY,O.H.

VISWANATHAN, I.

5640 C

23 D

36 D

55 X

14 D

4285 C

31 D

4928 C

4115 D

Updating a workstation VSAM direct data set by key (continued)

312

PL/I for Windows Programming Guide