Accessing BSAM and VSAM files

Overview

The sequential and VSAM I/O processing facility allows SOUL requests to access BSAM and VSAM files through an image format defined in SOUL requests. Access to BSAM files is supported in all versions of Model 204. Access to VSAM files is supported in z/OS and z/VSE versions of Model 204.

Images allow reads and processing of sequential files, VSAM files, and terminal input (IFDIAL connections), writes to sequential files and terminals, and creation of formatted blocks of storage used to build print records or process data that is in a non-Model 204 format.

This topic discusses how Model 204 accesses basic sequential and VSAM files and the commands and system specifications that the I/O processing facility requires.

Sequential I/O processing

The sequential I/O facility has an external file I/O support feature that allows READ access to any sequential file whose organizational structure is in accordance with the BSAM data set structure (z/OS) or the SAM file structure (z/VSE):

• In z/OS operating systems, Model 204 can obtain BLKSIZE, LRECL, RECFM, BUFNO, and NCP information from the DCB parameter of the DD statement or from the disk file label at the time the data set is opened. A DEFINE DATASET command is not required.
• In z/VSE operating systems, you must issue a DEFINE DATASET command for each sequential file to be accessed and you must include the BLKSIZE, LRECL, and RECFM parameters.
• In z/VM, only one user at a time can access a particular sequential file. A CLOSE DATASET command must be issued between user opens.

  If a previous user has not closed the file, any subsequent attempt to open the file brings down the z/VM virtual machine.

Buffer requirements

Sequential I/O processing requires a number of buffers equal to the BUFNO parameter of the DEFINE DATASET command for each concurrent OPEN DATASET command issued.

The buffer size required for a file is equal to the block size of the file. Buffer space is released when the file is closed.

Determining sequential data set format

Model 204 determines the format of sequential data sets by determining the values of the record format, data length, logical record length, and block size of the data set when it is opened.

• The record format describes the way physical records are structured. Attributes recognized by Model 204 are:

  Attribute	Meaning
  F	Fixed length
  V	Variable length
  U	Undefined length
  B	Records are blocked
  A	Carriage control present

  The allowed value combinations are:

  F, FA, FB, FBA, V, VA, VBA, U, UA

• Data length is the maximum amount of data that can be placed into a logical record.

  Data length does not take into account carriage control characters, record descriptor words, or block descriptor words.

• Logical record length is the maximum length (in bytes) of each record in the data set.

  The record descriptor word and carriage control character are included if they are present. If the records are of variable or undefined length, the maximum logical record length must be specified.

• Block size is the maximum length (in bytes) of a block.

  If the record format is F, the block size must be an integral multiple of the logical record length. If the record format is V, the specified block size must be the maximum block size and at least four bytes larger than the logical record length.

Sequential data set algorithm

Model 204 determines the sequential data set characteristics by using an algorithm based upon values derived from:

• Operating-system-dependent information
• Data set definition (created by the DEFINE DATASET command)
• Information provided by Model 204 that is dependent upon the data set being opened

The steps of the algorithm are performed in order, with each successive value dependent upon the preceding values. Undetermined values are systematically defaulted. Erroneous values are flagged. Values (such as logical record length) are changed in order to make them consistent with previously examined values (such as record format and data length).

The following table summarizes the characteristics examined by the algorithm and the action taken:

Algorithm for determining sequential data set characteristics

If the characteristic examined is...	And the value found is...	Then the result is...
Record format (RECFM)	No value	Undefined record
	RECFM =	Undefined record
Data length (DATALEN)	DATALEN = 0, RECFM = U	DATALEN = BLKSIZE
	DATALEN=0, RECFM=U, carriage control	DATALEN = DATALEN - 1
	Negative DATALEN, RECFM = U	OPEN fails
	DATALEN = 0, LRECL not 0	DATALEN = BLKSIZE
	DATALEN = 0, LRECL not 0, zero, carriage control	DATALEN = DATALEN - 1
	DATALEN = 0, LRECL not 0, RECFM = V	DATALEN = DATALEN - 4 (if blocked) DATALEN = DATALEN - 8 (if unblocked)
	Negative DATALEN, LRECL not 0	OPEN fails
	DATALEN = 0	OPEN fails (no default)
Logical record length (LRECL)	LRECL < 32767	LRECL = DATALEN
	LRECL < 32767, carriage control	LRECL = LRECL + 4
	LRECL > 32767	OPEN fails
Block size (BLKSIZE)	BLKSIZE > LRECL	BLKSIZE = LRECL
	RECFM = F	BLKSIZE = multiple of LRECL (rounded down)
	RECFM = V	BLKSIZE = LRECL + 4
	BLKSIZE > 32767	OPEN fails
	Final processing
	BLKSIZE > LRECL, RECFM = F	RECFM altered to include blocking
	BLKSIZE > LRECL, RECFM = V	RECFM altered to include blocking
Number of buffers (BUFNO)	BUFNO ≤ 1	Multiple buffering disabled
Number of channel programs (NCP)	BUFNO ≥ 2, BUFNO > NCP	Multiple buffering enabled with BUFNO buffers
	BUFNO ≥ 2, BUFNO ≤ NCP	Multiple buffering enabled with NCP + 1 buffers
	NCP ≥ BUFNO, BUFNO ≥ 2	BUFNO = NCP + 1, multiple buffering enabled

Examples of sequential data set processing

The following examples describe various ways that Model 204 opens sequential data sets:

• Model 204 opens a dump data set that has a block size of 13000. The Model 204 page size is 6184. Therefore, the record format is set to FB, the data length and logical record length are set to 6184, and block size is rounded down to 12368 (6184 * 2).
• Model 204 opens the password data set (CCASTAT). No information has been provided by the operating system. Therefore, the record format is forced to be undefined. The data length, logical record length, and block size are set to 6286.
• Model 204 opens a USE data set. The operating system provides the information that the record format is FA and the logical record length is 133. The data set definition block indicates that the data length is 72. Using this information and the algorithm, the record format is set to FA, the data length is set to 72, and the logical record length and block size are set to 73.

The following examples illustrate how, after values are obtained from the operating system and the data set definition, Model 204 might force some or all the characteristics to have values dependent upon the use of the data set being opened:

• The record format for a dump data set is forced to fixed. Data length is forced to be equal to the Model 204 page size currently in effect.
• The record format for the Model 204 password data set (CCASTAT) is forced to be undefined. Data length is set to 6286, if the logical record length and block size have not been provided by the operating system.
• The record format for a USE data set is set to the value of the UDDRFM parameter, if the record format has not been provided by the operating system or a data set definition. Data length is set to 132, if data length, logical record length, and block size have not been provided by the operating system or a data set definition.
• A USE data set can be a disk file with any organization. The printer data set with a length of 133 and a record format of FA is the default.

VSAM I/O processing

External file I/O support allows READ access to any VSAM KSDS cluster through its primary or alternate index key via a predefined PATH and an ALTERNATEINDEX cluster in the VSAM catalog.

The following sections explain system requirements, primary and alternate index key processing, and procedures for loading VSAM KSDS and ESDS files.

System requirements

VSAM I/O processing requires the following system specifications:

• Increased value of the STRINGS option if users reach (and cannot reduce) the maximum number of concurrent positioning requests for a keyed VSAM data set.

  When the maximum number of concurrent positioning requests is reached, a request for another positioning string is denied.

• Increased dynamically allocated storage (SPCORE).

  Access to VSAM data sets increases the requirements for dynamically allocated storage available at execution. SPCORE size requirements depend on:

  • Location where VSAM modules are loaded.

    Load VSAM modules in the LPA (z/OS) or SVA (z/VSE). If the modules are not loaded into the LPA, approximately 280K bytes are required within the region or partition.

  • The number of strings (STRNO) for each VSAM file and the BUFFER SPACE parameter defined in the VSAM cluster definition.

    The product of these parameters determines the amount of storage required for each opened VSAM file.

    For z/OS installations, in particular, if the STRNO parameter is specified in the DD statement, it must have the same value as the STRINGS parameter in the DEFINE DATASET statement. Preferably, do not specify the STRNO parameter in the DD statement.

Primary key processing

When processing VSAM files through the primary key, Model 204 requires:

• DD (DLBL for z/VSE) statement in the JCL for each VSAM file
• DEFINE DATASET command in Model 204 for each VSAM file

DEFINE DATASET must contain:

• File name
• File organization (VSAM)
• Other parameters, such as access method (keyed or sequential), password (if any), number of strings, and close option

Alternate index key processing

When processing VSAM files through the alternate index key, Model 204 requires:

• DD (DLBL for z/VSE) statement in the JCL for each predetermined PATH
• DEFINE DATASET command for each PATH

Record retrieval through the alternate index key is based on the cluster definition ALTERNATEINDEX.

• If NONUNIQUEKEY is specified, the record returned from VSAM depends on the retrieval method used in the SOUL procedure:
  • If a keyed retrieval (retrieval by a READ IMAGE statement with a KEY option) is requested, only the first record of the record set with the specified key is retrieved from the base cluster. Other records of the same set are ignored.
  • If sequential retrieval (a POSITION statement used to set the initial pointer, followed by READ IMAGE statement with the NEXT option) is requested, all records with the same alternate key are returned first. Records with the next highest alternate key follow.
• If UNIQUEKEY is specified in the definition of the ALTERNATEINDEX cluster, any retrieval request with the alternate key is identical to the retrieval through the primary key.

Loading a VSAM KSDS or ESDS file

A VSAM KSDS file (or a VSAM ESDS file accessed through an ALTERNATEINDEX cluster) can be loaded directly into any Model 204 file by using the File Load utility. The following specifications are required:

• Include a DD (or DLBL) statement for the VSAM file (or the PATH) in the JCL for File Load execution.
• Provide a DEFINE DATASET command for each VSAM file (or PATH definition if the alternate index is used):
  • Parameters that support VSAM file I/O are SEQUENTIAL and KEYED SEQUENTIAL file organization, to specify the VSAM access password assigned when the cluster was defined.

    The password is checked against the VSAM catalog for the data set and also checked each time an OPEN DATASET is issued for the data set.

  • CLOSE indicates physically closing the VSAM file.
  • CLOSE=EOJ indicates closing the VSAM file during Model 204 termination.
  • CLOSE=NOUSERS indicates closing the VSAM file when no users are accessing the file. NOUSERS is the default.
• In z/VSE, load VSAM modules in the SVA area to conserve space.