Complex and Key-Sequenced VSAM Data Sources

Describing Positionally-Related Records in VSAM

Some VSAM data sources are structured so that descendant records relate to each other through concatenating key fields. That is, the key field(s) of a parent record serves as the first part of the key of a child record. In such cases, the segment's key fields must be described to FOCUS using a GROUP declaration. Each segment's GROUP key fields will consist of the renamed key fields from the parent segment plus the unique key field from the child record.

Consider the following VSAM data structure with three types of records. The ROOT records have a key consisting of the publisher's number, PUBNO. The BOOKINFO segment has a key consisting of that same publisher's number, plus a hard or soft-cover indicator, BINDING. The SERIANO segment key consists of the first two elements, plus a record type field, RECTYPE.

The Master File for this structure looks as follows:

FILENAME=LIBRARY6, SUFFIX=VSAM,$
SEGNAME=ROOT, SEGTYPE=S0,$
GROUP=PUBKEY            ,ALIAS=KEY     ,USAGE=A10     ,ACTUAL=A10    ,$
FIELDNAME=PUBNO         ,ALIAS=PN      ,USAGE=A10     ,ACTUAL=A10    ,$
FIELDNAME=FILLER        ,ALIAS=        ,USAGE=A1      ,ACTUAL=A1     ,$
FIELDNAME=RECTYPE       ,ALIAS=1       ,USAGE=A1      ,ACTUAL=A1     ,$
FIELDNAME=AUTHOR        ,ALIAS=AT      ,USAGE=A25     ,ACTUAL=A25    ,$
FIELDNAME=TITLE         ,ALIAS=TL      ,USAGE=A50     ,ACTUAL=A50    ,$
SEGNAME=BOOKINFO, PARENT=ROOT, SEGTYPE=S0,$
GROUP=BOINKEY           ,ALIAS=KEY     ,USAGE=A11     ,ACTUAL=A11    ,$
FIELDNAME=PUBNO1        ,ALIAS=P1      ,USAGE=A10     ,ACTUAL=A10    ,$
FIELDNAME=BINDING       ,ALIAS=BI      ,USAGE=A1      ,ACTUAL=A1     ,$
FIELDNAME=RECTYPE       ,ALIAS=2       ,USAGE=A1      ,ACTUAL=A1     ,$
FIELDNAME=PRICE         ,ALIAS=PR      ,USAGE=D8.2N   ,ACTUAL=D8     ,$
SEGNAME=SERIANO, PARENT=BOOKINFO, SEGTYPE=S0,$
GROUP=SERIKEY           ,ALIAS=KEY     ,USAGE=A12     ,ACTUAL=A12    ,$
FIELDNAME=PUBNO2        ,ALIAS=P2      ,USAGE=A10     ,ACTUAL=A10    ,$
FIELDNAME=BINDING1      ,ALIAS=B1      ,USAGE=A1      ,ACTUAL=A1     ,$
FIELDNAME=RECTYPE       ,ALIAS=3       ,USAGE=A1      ,ACTUAL=A1     ,$
FIELDNAME=SERIAL        ,ALIAS=SN      ,USAGE=A15     ,ACTUAL=A15    ,$
SEGNAME=SYNOPSIS, PARENT=ROOT, SEGTYPE=S0, OCCURS=VARIABLE,$
FIELDNAME=PLOTLINE      ,ALIAS=PLOTL   ,USAGE=A10     ,ACTUAL=A10    ,$

Note that the length of the key fields specified in the USAGE and ACTUAL attributes of a GROUP declaration is the length of the key fields from the parent segment(s) plus the length of the added field of the child segment. In the example above, the length of the GROUP key SERIKEY equals the length of PUBNO2 and BINDING1, the group key from the parent segment, plus the length of RECTYPE, the field added to the group key in the child segment.

In the sample file, the repetition of the publisher's number as PUBNO1 and PUBNO2 in the descendant segments relates the three types of records. The file can be diagrammed as the following FOCUS structure:

A typical inquiry might request information on price and call numbers by publisher number:

PRINT PRICE AND SERIAL BY PUBNO
IF PUBNO EQ 1234567890 OR 9876054321

Since PUBNO is part of the key, such a retrieval can be made quickly and processing continues. To further expedite retrieval you could add search criteria based on the BINDING field, which is also part of the key.

The RECTYPE Attribute in VSAM

Key-sequenced VSAM data sources also use the RECTYPE attribute field to distinguish record types within them. A record type (RECTYPE) field appears in the same position of all records in the file. A parent does not always share its RECTYPE with its descendants. It shares some other identifying piece of information, such as the PUBNO in our example. This field should be included in the parent key, as well as in all of its descendant keys, to relate them.

When using the RECTYPE attribute in VSAM data sources with group keys, the RECTYPE field can only be part of the segment's group key when it belongs to a segment with no descendants, or to a segment whose descendants are described with an OCCURS attribute. In the previous example, the RECTYPE field is added to the group key in the SERIANO segment, the lowest descendant segment in the chain.

If you place the RECTYPE field in the parent segment's portion of the key, the file will be sorted first by record type when FOCUS processes it, destroying the VSAM positional relationship with records in the child segments. In the previous example, if the RECTYPE of the BOOKINFO segment were made part of the group key, all BOOKINFO records would be sorted together and their relationship to the records in SERIANO would be lost.

Describing Data Sources With Unrelated Records in VSAM

Some VSAM data sources do not have related records. That is, the VSAM key of one record type is independent of the keys of other record types.

For example, consider another VSAM file containing information on our library. This file has three types of records: book information, magazine information, and newspaper information.

There are two possible structures:

• The RECTYPE is the beginning of the key. The key structure is:

RECTYPE B	Book Code
RECTYPE M	Magazine Code
RECTYPE N	Newspaper Code

The sequence of records is:

Book

Book

 

Magazine

Magazine

 

Newspaper

Newspaper

Note the difference between the use of the RECTYPE here and its use in Describing Positionally-Related Records. In this case, you do want to sort your records by type first (all book information together, all magazine information together, and all newspaper information together), so it is appropriate to include the RECTYPE as part of the key.

• The RECTYPE is not in the beginning of the key or is outside of the key. The key structure is:

Book Code

Magazine Code

Newspaper Code

The sequence of record types can be arbitrary.

Both types of file structure can be represented by the following structure:

Describing a Key and Record Type for a Data Structure With Unrelated Records in VSAM

To describe either type of file with unrelated records, make the record types descendants of a dummy root segment. The following rules apply:

• The segment name must be DUMMY.

• It must have only one field with an empty name and alias.

• It should not have any keys or record types described.

• The USAGE and ACTUAL formats must be A1.

All other non-OCCURS segments must point to the dummy root as their parent. Except for the dummy segment, all non-OCCURS segments must describe the full VSAM key. If the file does not have a key, the group should not be described. RECTYPEs may be anywhere in the record.

The following Master File describes a second, more complex file with unrelated records:

FILE=LIBRARY7, SUFFIX=VSAM,$
SEGMENT=DUMMY,$
FIELDNAME=         ,ALIAS=       ,USAGE=A1      ,ACTUAL=A1     ,$
SEGMENT=BOOK, PARENT=DUMMY, SEGTYPE=S0,$
GROUP=BOOKKEY      ,ALIAS=KEY    ,USAGE=A11     ,ACTUAL=A11    ,$
FIELDNAME=PUBNO    ,ALIAS=PN     ,USAGE=A3      ,ACTUAL=A3     ,$
FIELDNAME=AUTHNO   ,ALIAS=AN     ,USAGE=A3      ,ACTUAL=A3     ,$
FIELDNAME=TITLNO   ,ALIAS=TN     ,USAGE=A4      ,ACTUAL=A4     ,$
FIELDNAME=RECTYPE  ,ALIAS=B      ,USAGE=A1      ,ACTUAL=A1     ,$
FIELDNAME=AUTHOR   ,ALIAS=AT     ,USAGE=A25     ,ACTUAL=A25    ,$
FIELDNAME=TITLE    ,ALIAS=TL     ,USAGE=A50     ,ACTUAL=A50    ,$
FIELDNAME=BINDING  ,ALIAS=BI     ,USAGE=A1      ,ACTUAL=A1     ,$
FIELDNAME=PRICE    ,ALIAS=PR     ,USAGE=D8.2N   ,ACTUAL=D8     ,$
FIELDNAME=SERIAL   ,ALIAS=SN     ,USAGE=A15     ,ACTUAL=A15    ,$
FIELDNAME=SYNOPSIS,,ALIAS=SY     ,USAGE=A150    ,ACTUAL=A150   ,$
SEGMENT=MAGAZINE, PARENT=DUMMY, SEGTYPE=S0,$
GROUP=MAGKEY       ,ALIAS=KEY    ,USAGE=A11     ,ACTUAL=A11    ,$
FIELDNAME=VOLNO    ,ALIAS=VN     ,USAGE=A2      ,ACTUAL=A2     ,$
FIELDNAME=ISSUNO   ,ALIAS=IN     ,USAGE=A2      ,ACTUAL=A2     ,$
FIELDNAME=PERDAT   ,ALIAS=DT     ,USAGE=A6      ,ACTUAL=A6     ,$
FIELDNAME=RECTYPE  ,ALIAS=M      ,USAGE=A1      ,ACTUAL=A1     ,$
FIELDNAME=PERNAME  ,ALIAS=PRN    ,USAGE=A50     ,ACTUAL=A50    ,$
SEGMENT=NEWSPAP, PARENT=DUMMY, SEGTYPE=S0,$
GROUP=NEWSKEY     ,ALIAS=KEY     ,USAGE=A11     ,ACTUAL=A11    ,$
FIELDNAME=NEWDAT  ,ALIAS=ND      ,USAGE=A6      ,ACTUAL=A6     ,$
FIELDNAME=NVOLNO  ,ALIAS=NV      ,USAGE=A2      ,ACTUAL=A2     ,$
FIELDNAME=NISSUE  ,ALIAS=NI      ,USAGE=A2      ,ACTUAL=A2     ,$
FIELDNAME=RECTYPE ,ALIAS=N       ,USAGE=A1      ,ACTUAL=A1     ,$
FIELDNAME=NEWNAME ,ALIAS=NN      ,USAGE=A50     ,ACTUAL=A50    ,$

VSAM Repeating Groups With RECTYPEs

When data sources contain records that have repeating groups, the OCCURS attribute is used to describe a separate segment for the repeating fields.

Note: OCCURS segments are treated as MISSING if they are not activated through an INCLUDE in a FOCUS MODIFY. A period (.) is placed in the first byte of the first occurrence of OCCURS=n or OCCURS=fieldname to signify that the segment is missing.

In some data sources, however, the repeating fields themselves must be identified according to a RECTYPE indicator.

Suppose you want to describe a file that, schematically, looks like this:

A          RECTYPE    B C         RECTYPE      B C

A          RECTYPE    D           RECTYPE      D

You need to describe three segments in your Master File, with A as the root segment, and segments for B, C, and D as two descendant OCCURS segments for A:

Each of the two descendant OCCURS segments in this example depends on the RECTYPE indicator that appears for each occurrence.

All syntax rules for using RECTYPE fields and OCCURS segments also apply to RECTYPEs within OCCURS segments.

Since the OCCURS segments are evaluated depending on the contents of the RECTYPE indicator, the RECTYPE must appear at the start of each OCCURS segment. This enables you to describe very complex data sources, including ones with nested and parallel repeating groups that depend on RECTYPEs.

In the next example, B/C, and D represent a nested repeating group, and E represents a parallel repeating group.

A

RECTYPE B C 

RECTYPE D

RECTYPE E

RECTYPE E

The Master File would be coded as:

FILENAME=SAMPLE,SUFFIX=VSAM,$
SEGNAME=ROOT,SEGTYPE=S0,$
GROUP=GRPKEY        ,ALIAS=KEY       ,USAGE=A8      ,ACTUAL=A8     ,$
FIELD=FLD000        ,E00             ,A08           ,A08           ,$
FIELD=A_DATA        ,E01             ,A02           ,A02           ,$
SEGNAME=SEG001,PARENT=ROOT,OCCURS=VARIABLE,SEGTYPE=S0              ,$
FIELD=RECTYPE ,     ,A01             ,A01           ,ACCEPT=B OR C ,$
FIELD=B_OR_C_DATA   ,E02             ,A08           ,A08           ,$
SEGNAME=SEG002,PARENT=SEG001,OCCURS=VARIABLE,SEGTYPE=S0            ,$
FIELD=RECTYPE       ,D               ,A01           ,A01           ,$
FIELD=D_DATA        ,E03             ,A07           ,A07           ,$
SEGNAME=SEG003,PARENT=ROOT,OCCURS=VARIABLE,SEGTYPE=S0              ,$
FIELD=RECTYPE       ,E               ,A01           ,A01           ,$
FIELD=E_DATA        ,E04             ,A06           ,A06           ,$

Describing VSAM Repeating Groups Using MAPFIELD

The first record contains "header" information, values for A and B, followed by an OCCURS segment of C and D that was identified by its preceding record indicator. The second record has a different record indicator and contains a different repeating group, this time for E.

The following diagram illustrates this relationship.

Since the OCCURS segments are identified by the record indicator rather than the parent A/B segment, you must use the keyword MAPFIELD. MAPFIELD identifies a field in the same way RECTYPE does, but since the OCCURS segments will each have their own values for MAPFIELD, the value of MAPFIELD is associated with each OCCURS segment by means of a complementary field named MAPVALUE.

The following diagram illustrates this relationship:

MAPFIELD is assigned as the ALIAS of the field that will be the record indicator. You can give this field any name.

Syntax: Naming and Defining MAPFIELD Values in VSAM

FIELD=name, ALIAS=MAPFIELD, USAGE=format, ACTUAL=format,$

where:

name

Is the name you provide for this field.

ALIAS

MAPFIELD is assigned as the alias of the field that will be the RECTYPE indicator.

USAGE

Follows the usual field format.

ACTUAL

Follows the usual field format.

Descendant segment values depend on the value of MAPFIELD. They are described as separate segments, one for each possible value of MAPFIELD, and all descend from the segment that has the MAPFIELD. A special field, MAPVALUE, is described as the last field in these descendant segments after the ORDER field, if one was used. The actual MAPFIELD value is supplied as the ALIAS of the MAPVALUE.

Syntax: Defining a MAPFIELD Value Using MAPVALUE in VSAM

FIELD=MAPVALUE, ALIAS=alias, USAGE=format, ACTUAL=format,ACCEPT=list/range ,$

where:

MAPVALUE

Indicates that the segment depends on a MAPFIELD in its parent segment.

alias

Is the primary MAPFIELD identifier. If there is an ACCEPT list, this value is any value in the ACCEPT list or range.

USAGE

Is the same format as the MAPFIELD format in the parent segment.

ACTUAL

Is the same format as the MAPFIELD format in the parent segment.

list

Is the list of one or more lines of specified MAPFIELD values for records that have the same segment layout. The maximum number of characters allowed in the list is 255. Each item in the list must be separated by either a blank or the keyword OR. If the list contains embedded blanks or commas, it must be enclosed within single quotation marks (''). The list may contain a single MAPFIELD value. For example:

FIELDNAME=MAPFIELD, ALIAS=A, USAGE=A1, ACTUAL=A1,
ACCEPT=A OR B OR C,$

range

Is a range of one or more lines of MAPFIELD values for records that have the same segment layout. The maximum number of characters allowed in the range is 255. If the range contains embedded blanks or commas, it must be enclosed in single quotation marks ('). To specify a range of values, include the lowest value, the keyword TO, and the highest value, in that order.

Using the sample file at the beginning of this section, the Master File would look like this:

FILENAME=EXAMPLE,SUFFIX=FIX,$
SEGNAME=ROOT,SEGTYPE=S0,$
FIELD =A         ,             ,A14   ,A14    ,$
FIELD =B         ,             ,A10   ,A10    ,$
FIELD =FLAG      ,MAPFIELD     ,A01   ,A01    ,$
SEGNAME=SEG001,PARENT=ROOT,OCCURS=VARIABLE,SEGTYPE=S0,$
FIELD =C         ,             ,A05   ,A05    ,$
FIELD =D         ,             ,A07   ,A07    ,$
FIELD =MAPVALUE  ,1            ,A01   ,A01    ,$
SEGNAME=SEG002,PARENT=ROOT,OCCURS=VARIABLE,SEGTYPE=S0,$
FIELD =E         ,             ,D12.2 ,D8     ,$
FIELD =MAPVALUE  ,2            ,A01   ,A01    ,$

Note: MAPFIELD can only exist on an OCCURS segment that has not been positionally re-mapped. The segment definition cannot contain POSITION=fieldname.

VSAM Data and Index Buffers

The AMP sub-parameters BUFND and BUFNI allow MVS BATCH users to enhance the I/O efficiency of their TABLE, TABLEF, MODIFY, and JOIN operations against VSAM data sources by retaining frequently accessed VSAM Control Intervals in memory, rather than on physical DASD. Job throughput is improved by reducing the number of physical I/O operations. These SET commands allow FOCUS users to improve performance in their interactive sessions. In general, BUFND (data buffers) increase the efficiency of physical sequential reads, while BUFNI (index buffers) most benefit JOIN or KEYED access operations.

Syntax: How to Establish Data and Index Buffers in VSAM

SET BUFND and BUFNI

{MVS|CMS} VSAM SET BUFND {n1|8}
{MVS|CMS} VSAM SET BUFNI {n2|1}

where:

n1

Is the number of data buffers. The default is BUFND=8.

n2

Is the number of index buffers. The default is BUFNI=1.

To determine how many buffers are in effect at any time, issue a VSAM SET query:

Syntax: Querying buffers currently in effect in VSAM

{MVS/CMS} VSAM SET ?

Alternate Indexes in VSAM

Alternate indexes are separate, additional index structures that allow you to view the data records in a different sequence. For instance, you might usually access a personnel file by Social Security number, but occasionally need to retrieve records by job description. In this case, you could describe the job description field as an alternate index. Alternate indexes must be related to the base clusters they describe by a "path," which is stored in a separate file.

Alternate indexes are VSAM structures that are created and maintained in the VSAM environment. You can describe them to FOCUS in the Master File, however, so that you can exploit them in the FOCUS environment.

These indexes offer improved efficiency. You can use one as an alternate, more efficient, retrieval path or you can take advantage of them indirectly, applying screening tests (IF...LT, IF...LE, IF...GT, IF...GE, IF...EQ, IF...FROM...TO, IF...IS) that translate into direct reads using the alternate index. You can also join data sources through an alternate index with the JOIN command.

It is not necessary to explicitly identify the indexed view in order to exploit the alternate index. FOCUS automatically selects the alternate index when one is described to FOCUS in the Master File.

To use an alternate index in a TABLE request, simply provide an IF or WHERE test on the alternate index field that meets the above criteria. For example:

TABLE FILE CUST
PRINT SSN
WHERE LNAME EQ 'SMITH'
END

Note that if we define the LNAME field as an alternate index field, records in this file will be retrieved by last name and certain IF tests on the field LNAME will result in direct reads. If the alternate index fieldname were omitted, the primary key (if there was one) would be used for sequential or direct reads, and the alternate indexes would simply be treated as regular fields.

Describing Alternate Indexes in VSAM

Alternate indexes must be described in Master Files with FIELDTYPE=I. The ALIAS of the alternate index field must be the filename allocated to the corresponding path name. Alternate indexes can be described as GROUPs if they consist of portions with dissimilar formats. Remember that the ALIAS=KEY must be used to describe the primary key.

Consider the following example:

FILENAME=CUST, SUFFIX=VSAM,$
SEGNAME=ROOT, SEGTYPE=S0,$
GROUP=G, ALIAS=KEY, A10, A10,$
FIELD=SSN, SSN, A10, A10,$
FIELD=FNAME, DD1, A10, A10, FIELDTYPE=I,$
FIELD=LNAME, DD2, A10, A10, FIELDTYPE=I,$

In this example, SSN is a primary key and FNAME and LNAME are alternate keys (indexes). DD1 and DD2 are file names (ddnames) allocated to corresponding paths. CUST must be allocated to the base cluster.

Only one record type can be referenced in the request when alternate indexes are used, but the number of OCCURS segments is unrestricted.

The file name or ddname specified in the alias must be allocated to the path corresponding to the index. Note that the path name is different from both the cluster name and the alternate index name.

If you are uncertain of the path names and alternate indexes associated with a given base cluster, use the IDCAMS utility. (See the IBM manual entitled Using VSAM Commands and Macros for details.)

The following example demonstrates how to find the alternate index and path names associated with a base cluster named CUST.DATA:

Syntax: How to Find Alternate Index Names for a Cluster in VSAM

First, find the alternate index names (AIX) associated with the given cluster.

IDCAMS input

LISTCAT CLUSTER ENTRIES(CUST.DATA) ALL

IDCAMS output (fragments)
  CLUSTER --------- CUST.DATA
    ASSOCIATIONS
      AIX ---------- CUST.INDEX1
      AIX ---------- CUST.INDEX2

This provides the names of the alternate indexes (AIX): CUST.INDEX1 and CUST.INDEX2.

Syntax: How to Find Path Names Associated With a Given AIX Name in VSAM

Next, find path names associated with the given AIX name.

IDCAMS input:
  LISTCAT AIX ENTRIES (CUST.INDEX1 CUST.INDEX2) ALL

IDCAMS output (fragments):
  AIX ---------CUST.INDEX1
    ASSOCIATIONS
      CLUSTER -- CUST.DATA
      PATH ------CUST.PATH1
  AIX ---------CUST.INDEX2
    ASSOCIATIONS
      CLUSTER -- CUST.DATA
      PATH ------CUST.PATH2

This provides the path names: CUST.PATH1 and CUST.PATH2.