Special SAS Options for VSAM

The special SAS options for VSAM data sets are specified in the INFILE statement except when you load a new VSAM data set with initial records. You must use the FILE statement when you load a new VSAM data set. For more information about FILE statement options for VSAM data sets, see Loading Records into a VSAM Data Set .

All the options except those described in the following table can be used with all three VSAM data set types. The special SAS options for VSAM are listed in the following table:

Special SAS Options for Selected VSAM Data Sets

Option	ESDS through AIX	ESDS	KSDS	RRDS
ERASE=			X	X
GENKEY	X		X
KEY=	X		X
KEYGE	X		X
KEYLEN=	X		X
KEYPOS=	X		X
RBA=	X	X	X
RRN=				X
SEQUENTIAL		X		X
SKIP	X		X	X

BACKWARD

BKWD

instructs SAS to read a VSAM data set backwards. You can use the BACKWARD option only when you are reading the VSAM data set sequentially.

BUFND=integer

specifies the number of data buffers for a VSAM input data set. If BUFND= is not specified, VSAM provides a default value. For sequential processing, two data buffers are usually sufficient. If your VSAM application's performance is slow, it might indicate that you should increase the number of data buffers that are specified by BUFND=. The systems programming staff at your installation can help you determine what values to assign to BUFND=.

BUFNI=integer

specifies the number of index buffers for a VSAM data set. If BUFNI= is not specified, VSAM provides a default value. For sequential processing, one index buffer is usually sufficient. If your VSAM application's performance is slow, it might indicate that you should increase the number of data buffers specified by BUFNI=. The systems programming staff at your installation can help you determine what value to assign to BUFNI=.

CONTROLINTERVAL

CTLINTV

CNV

specifies that you want to read VSAM control intervals rather than logical records. When you specify the CONTROLINTERVAL option for a password-protected VSAM data set, you must give a control-interval-access or higher-level password with the PASSWD= option.

Control intervals cannot be updated or erased. Control interval access is typically used only for diagnostic applications or for reading a VSAM catalog.

ERASE=variable

defines a numeric SAS variable that you must set when you want to erase a VSAM record. The ERASE= option must be specified to erase a VSAM record.

The record is erased when you set the ERASE= variable to a value of 1 before a PUT statement for the output data set executes. When you set the ERASE= variable to a value of 0, the record is updated (instead of erased) when the PUT statement executes. This is the default action if ERASE= is not specified.

After a record is erased, the ERASE= variable is automatically reset to 0. Therefore, you must reset the ERASE= variable to 1 in order to erase another record. This prevents the inadvertent deletion of a series of records.

This option is valid only for KSDS and RRDS records. There is a VSAM restriction that records cannot be erased from an ESDS.

FEEDBACK=variable

FDBK=variable

defines a numeric SAS variable that SAS sets to the VSAM logical error code when a logical error occurs. FEEDBACK= is similar to the _FDBK_ automatic variable, but it is more flexible and less likely to allow VSAM logical errors to go unnoticed. When SAS sets the FEEDBACK= variable, you must reset it to 0 to continue processing after a logical error. See Error-Handling Techniques and Error Messages for more information.

GENKEY

specifies generic-key processing for a KSDS. When GENKEY is specified, SAS programs treat the KEY= variable as the leading portion of a record's key. SAS retrieves the first record whose key matches the generic key, unless you also specify skip sequential processing. Use this option if you plan to retrieve a series of KSDS records that have the same leading key field, or if you know only the leading portion of a particular key. The GENKEY option applies to all records that are read from the data set in the DATA step. That is, you cannot turn GENKEY on and off. Changing the value of the KEY= variable indicates another generic-key retrieval request.

When you specify both the GENKEY and the SKIP options, SAS retrieves the first record containing the matching partial key and then reads the following records sequentially. Access is sequential after the first key until you change the value of the KEY= variable. Changing this variable indicates another direct-access, generic-key retrieval request. Assigning a new value that equals the previous value is not regarded as a change. To perform repeated direct-access, generic-key retrievals with the same KEY= value, you must clear and reassign the KEY= variable after each retrieval.

KEY=variable

KEY=(list of variables)

indicates that keyed direct access is to be used to retrieve records from a KSDS or an ESDS that was accessed through an alternate index. The KEY= option specifies either one variable or a list of variables that provides the key of the record to be read. You can construct a key up to 256 characters long by defining a list of up to 16 character variables. SAS builds the key by concatenating the variables; blanks are not trimmed. The key is extended with blanks on the right until it reaches the full key length set during creation of the VSAM data set with AMS/IDCAMS.

Unless used with the GENKEY option, the key value that is passed to VSAM is either padded with blanks or truncated, as necessary, to equal the key length that is defined when the KSDS is created.

KEYGE

specifies that retrieval requests with the KEY= option are for any record whose key is equal to or greater than the key that is specified by the KEY= option. This approximate key retrieval is useful when the exact record key is not known. The KEYGE option applies to all records that are read from the data set in that DATA step. That is, you cannot turn KEYGE on and off.

KEYLEN=variable

specifies a numeric SAS variable that, when used with GENKEY, specifies the length of the key to be compared to the keys in the data set. The variable's value is the number of generic key characters passed to VSAM. If you specify GENKEY without the KEYLEN= option, the generic-key length is the KEY= variable length (or the sum of the KEY= variable lengths, if a list is specified).

SAS sets the variable that is specified by the KEYLEN= option to the actual key length that is defined in the cluster before the DATA step executes. The KEYLEN= option can be used to read KSDS keys without any advance knowledge of the key length. Assign the value of the KEYLEN= variable to a different variable if you also intend to set the KEYLEN= variable for generic key processing. You might need to name the variable in a RETAIN statement if you need this initial value after the first execution of the DATA step.

KEYPOS=variable

specifies a numeric SAS variable that SAS sets to the position of the key field. This option enables KSDS keys to be read without advance knowledge of the key position. The variable is set to the column number, not the offset, which is one less than the column number.

When you use the KEYLEN= and the KEYPOS= options together, it is possible to read KSDS keys without knowing either the key position or length in advance. The SAS variables that you specify with the KEYLEN= and KEYPOS= options should not be present in any SAS data set that is used as input to the DATA step.

PASSWD=password

gives the appropriate password for a data set that has VSAM password protection. The password is replaced with Xs on the SAS log. Here are the guidelines for an appropriate password:

You need a read (or higher-level) password for a data set that you are reading only.
You need an update (or higher-level) password for a data set that you are updating or loading.
You need a control interval (or higher-level) password to read a data set's control intervals directly.

RBA=variable

defines a numeric variable that you set to the relative-byte address (RBA) of the data record (or control interval) to be read. The RBA= option indicates that addressed direct access is to be used for record retrieval from an ESDS or a KSDS. The RBA= option can also be used to access the control intervals in an RRDS if the CONTROLINTERVAL option is specified.

READPW=password

is a synonym for the PASSWD= option.

RECORDS=variable

defines a numeric variable that SAS sets to the number of logical records in the VSAM data set you are reading.

RESET

specifies that the VSAM data set is to be reset to empty (no records) when it is opened. The RESET option applies only to loading a VSAM data set that has been defined with the VSAM option REUSE. Specify this option to use a VSAM data set as a work data set by reloading it in the DATA step. This option cannot be used if the data set has an alternate index.

RRN=variable

defines a numeric variable that you set to the relative-record number (RRN) of the record to be read or written. This option indicates that keyed direct access is to be used for record storage and retrieval and is appropriate only for an RRDS.

SEQUENTIAL

SEQ

specifies sequential record retrieval when either the RBA= (for an ESDS) or the RRN= (for an RRDS) direct access option indicates direct record storage for the PUT statement or statements.

The SEQUENTIAL option is necessary only when adding new records after sequentially reading existing records in an ESDS or an RRDS.

SKIP

indicates that skip sequential access is to be used for record retrieval. Skip sequential access finds an initial record with keyed direct access and then retrieves records from then on with sequential access. An unchanged KEY= or RRN= value indicates that subsequent records are to be retrieved sequentially. The SKIP option can be used for a KSDS or an RRDS.

UPDATE=variable

defines a numeric variable that tells SAS that not every record that is read is to be updated when you are reading and writing records in a VSAM data set. When you have both an INFILE and a FILE statement referencing the same VSAM data set, records are retrieved for update by default.

In most cases, when a record is retrieved for update, no user, including you, can access that particular record or any other records in the same control interval until you free the record by executing a PUT or an INPUT statement for the data set. The UPDATE= option is used to avoid user lockout when only a few of many records that are read need to be updated. You can set the UPDATE= variable to one of the following values:

A value of 1 before an INPUT statement indicates that the record is retrieved for update. This is the default if UPDATE= is not specified.
A value of 0 before the INPUT statement indicates that the record is not retrieved for update.

VSAM

indicates that the fileref points to a VSAM nonstandard, external data set. It is optional for the VSAM option to immediately follow the fileref in the INFILE and FILE statements. However, the VSAM option must immediately follow the fileref if you bypass the VSAM catalog to determine the volume location of the VSAM component or cluster and you code the AMP=('AMORG') parameter in the JCL that defines the VSAM component or cluster.

WRITEPW=password

is a synonym for the PASSWD= option.