Each Master File corresponds to one PCB and each PCB accesses one DBD. The FILENAME value in the Master File can be any one- to eight-character name. However, for consistency and documentation purposes, the examples in this manual use the DBD name as the FILENAME value in the Master File:

1. Is an IMS PSB containing a PCB for DBD1.
2. Is the FILE record of the Master File for that PCB. The FILENAME attribute has the value DBD1.

A Master File contains segment records to describe the hierarchy of segments. These correspond to the SENSEG records in the PCB.

The Segment record in the Master File contains the following information:

• The SEGNAME attribute. Its value is the segment name from the SENSEG record in the corresponding PCB.
• The SEGTYPE attribute. Its value indicates whether the segment is a unique segment (there can be at most one segment instance for each parent), whether a segment is key sensitive, and whether the key (if there is one) is unique or non-unique. Recall that a key sensitive segment is used only for access to lower level segments and is specified by the parameter PROCOPT=K in the PCB. The information about the key for a segment comes from the DBD. The FIELD record in the DBD specifies NAME=(name,SEQ,M) for a non-unique key field, and NAME=(name,SEQ,U) or (name,SEQ) for a unique key.

  The following table lists permissible SEGTYPEs:

  SEGTYPE	Definition	PROCOPT=KIn PCB?	NAME=From DBD
  U	Data sensitive, unique segment	No	Not Applicable
  S0	Data sensitive, no key	No	(name)
  S or S1	Data sensitive, non-unique key	No	(name,SEQ,M)
  S2	Data sensitive, unique key	No	(name,SEQ,U) or (name,SEQ)
  SH or SH1	Key sensitive, non-unique key	Yes	(name,SEQ,M)
  SH2	Key sensitive, unique key	Yes	(name,SEQ,U) or (name,SEQ)

To describe data fields in the Master File, you must also consider information from both the PCB and the DBD.

If the PCB you are describing contains SENFLD records for a segment, the Master File can view only the fields explicitly named in those SENFLD records.

However, if the PCB does not contain any SENFLD records for a segment, you can describe the entire segment in the Master File. You can get information about sequence and search fields from the DBD. To describe other fields you may have to refer to the COBOL FD description for the segment.

For each field you describe in the Master File you must include the following:

• The FOCUS FIELDNAME. This can be any name that complies with FOCUS field naming conventions, as described in Creating FOCUS Descriptions.
• The ALIAS. The adapter uses the alias to distinguish between IMS sequence fields, IMS search fields, key fields from the root of an HDAM database, and other fields. These designations help the adapter produce optimized SSAs, as described in Reporting Efficiencies.

  If the field is not listed in the DBD, the alias can be any name that complies with FOCUS naming conventions.

  If the field is listed in the DBD (it is a sequence or search field), the alias value takes the form IMSname.suffix. IMSname is the field name specified in the DBD. The following table lists suffix values:

  Suffix	Description
  KEY	IMS key field
  IMS	IMS search field
  HKY	Key of root of an HDAM database

• The USAGE format. The USAGE format is the FOCUS display format for the field, as described in the Describing Data manual.
• The ACTUAL format. The ACTUAL format describes how the data is stored in the IMS database. The DBD specifies this information with the TYPE and BYTES parameters in each FIELD record. See Creating FOCUS Descriptions, for a discussion of ACTUAL formats.

The DBD indicates the length of each segment and the length and starting position of each listed field within a segment. The Master File need not describe all fields from a segment, but it must include filler fields that occupy the same space as any field it omits. You can use the BYTES and START parameters from the DBD to determine how the fields in the segment are arranged. If you want to describe two fields that are separated by data that you do not need, you must include a field in the Master File occupying the unneeded space in order to avoid a gap.

The following diagram illustrates FIELDNAME and ALIAS values in a Master File for a HIDAM database:

1. Is an IMS PSB. SEG1 has a SENFLD record for FLD1 limiting the view to that field alone. SEG2 has no SENFLD records. Therefore, the entire segment is available.
2. Is the IMS DBD that the PCB is viewing. SEG1 has two fields listed, but the PCB is sensitive only to the first. SEG2 has two fields listed, but they do not describe the entire segment.
3. Is the corresponding Master File. In SEG1, only FLD1 is available because of the SENFLD record in the PCB. The FIELDNAME can be any convenient name. Since this field is the key for the segment, the alias value is the name from the IMS DBD with the suffix value KEY appended: ALIAS=FLD1.KEY.

   In SEG2, the whole segment is available since the PCB has no SENFLD records for the segment. FLD3 is the key field. Therefore its alias value is FLD3.KEY. FLD4 is a non-key search field; its alias value is FLD4.IMS. No other fields are described in the PCB, but the Master File defines two more fields from the segment. Their alias values are arbitrary names with no suffix values. Notice the filler field between FLD3 and FLD4.

IMS key fields, secondary index fields, and search fields can consist of multiple elementary fields. In the Master File, you can break the IMS field into component parts (field redefinition) using a GROUP field.

The following diagram illustrates a group key:

1. Is a DBD. The field G is 8 bytes long and is type character.
2. Is the Master File. It defines the group as an 8-byte alphanumeric field. It then breaks this field down into two 4-byte alphanumeric fields.
3. Is a FOCUS session or FOCEXEC that uses the group field and its high-order component in screening tests. A slash must separate components of the group (see Creating FOCUS Descriptions).

An IMS segment can have multiple definitions. For example, a segment may contain either shipment or order information, depending on the value of one of its fields. If the field that identifies the type of segment is at the same position in each redefinition, you can use the RECTYPE attribute to define the different segment types in the Master File:

1. First define the non-changing portion of the segment as usual. Include a filler field for the part that will be redefined. The field that identifies the different types must be in the redefined portion.
2. Next, describe each redefined portion as a segment whose parent is the non-changing segment. Do not define a SEGTYPE for these children. Describe the field that identifies the segment type as FIELDNAME=RECTYPE in the Master File. The alias for the RECTYPE field is the value that identifies the type of data in the segment (in this example, either ALIAS=S, for a shipment, or ALIAS=O, for an order).

   Include a filler field in each redefinition to occupy the fields that are in the non-changing segment.

The following diagram illustrates segment redefinition in the Master File:

1. Is a segment named INFO that has two definitions, one for shipment information and one for order information. Field INFOTYPE contains the value S in those segment instances that contain shipment data. It contains the value O in those segment instances that represent order information.
2. Is the portion of the Master File that represents the IMS segment. It uses three segments to describe the one IMS segment.

   The parent segment, named INFO to match the IMS segment name, contains the key field since the key is not in the redefined portion. There is also a filler field to account for the redefined portion of the segment.

   Each child segment has INFO as its parent and a null SEGTYPE value. In each child, the field that corresponds to INFOTYPE from the DBD has FIELDNAME=RECTYPE. The ALIAS value for the RECTYPE field in each child segment is the INFOTYPE value that identifies that type of segment, S for the SHIP segment type and O for the ORDER segment type. (Each segment type also has a filler to occupy the positions of the fields that are described in the parent segment, and each segment type describes additional fields that it needs for either order or shipment data.)

   Creating FOCUS Descriptions, explains how to describe a segment type that allows multiple RECTYPE values.

A segment defined as type RECTYPE is considered a logical segment type since it is possible that it will not exist for all records in a file.

The Adapter for IMS allows logical segment types to have child segments. In the following example, the RECTYPE B segment has a real segment described as a child. This child segment only exists when the RECTYPE field of the record specifies a B:

The previous example illustrates a child segment that only exists when there is an instance of RECTYPE B. The following example shows a child segment that exists for all record types. The child segment will be accompanied by data that depends on the record type:

Through the use of the record type, the adapter activates only the necessary paths. This eliminates unnecessary, independent paths from the hierarchy traversal. This efficient data access results in improved adapter performance.

In an IMS database, segments can have repeating fields or repeating groups of fields. The number of repetitions may be fixed, may depend on the value of a field from the parent segment or from the non-repeating portion of the variable segment, or may have to be calculated from the segment length.

In the Master File, you describe a segment with repeating fields by defining each repeating field (or group) as a separate segment whose parent is the non-repeating portion of the segment. The child segment definition has no SEGTYPE, but it includes the OCCURS attribute to specify how many times the field repeats. The following table lists permissible values:

n

fieldname

VARIABLE

If the repeating field is not at the end of the segment, you must also identify its position within the segment (see Creating FOCUS Descriptions).

The following diagram illustrates an OCCURS segment in the Master File. Creating FOCUS Descriptions includes examples for each value of the OCCURS attribute.

1. Is an IMS segment with one key field and one repeating field.
2. Are the equivalent segments in the Master File. Segment SEG2 contains the non-repeating portion of the IMS SEG2 segment. Segment SEG3 contains the repeating field. It specifies OCCURS=5. SEG3 has no SEGTYPE value.

Using IMS secondary indexes, you can retrieve records in order of a field other than the key field. (A secondary index is itself a database with its own DBD.) The DBD for a database that uses a secondary index includes an XDFLD statement that assigns a field name to the index.

If a PCB includes the parameter PROCSEQ=indexDBDname, the named index is used as the main entry point into the database.

One Master File can describe the primary index and multiple secondary indexes. You must also include a record for each secondary index in the FOCPSB. Then, when you issue a FOCUS report request, the adapter inspects all key fields and secondary indexes to select the optimal retrieval path based on the selection criteria in the request.

In prior releases, each secondary index required a separate Master File, and the application programmer had to decide which Master File to use with each request. Release Dependent Adapter Features, describes that technique.

In order to access a database through a secondary index, the IMS PSB must contain a PCB that defines the index as the main entry point into the database. The PCB does this by identifying the DBD for the index in the PROCSEQ parameter (recall that a secondary index is, itself, an IMS database). The adapter requires the IMS PSB to also include a PCB for the normal entry point into the database. This PCB does not include a PROCSEQ parameter.

The FOCPSB has a one-to-one correspondence with the PSB. The FOCPSB entry that corresponds to the normal entry point into the database supplies the name of the Master File. Each FOCPSB entry that corresponds to a secondary index PCB supplies the name of the index from the XDFLD record of the DBD.

The following diagram illustrates an IMS PSB and its corresponding FOCPSB:

1. Is the IMS DBD for the PATDB01 database. The LCHILD record for the secondary index gives the name of the index DBD. The corresponding XDFLD record names the index.
2. Is an IMS PSB with two PCBs for PATDB01. The first PCB does not include a PROCSEQ parameter. Therefore, it uses the normal entry point into the database. The second PCB includes the parameter PROCSEQ=PATDBIX1. Therefore, a secondary index is the main entry point into the database through this PCB, and the PATDBIX1 DBD describes it.
3. Is the FOCPSB that describes the IMS PSB. The entry corresponding to the first PCB supplies the Master File name, PCBNAME=PATINFO. The entry corresponding to the PCB for the secondary index provides the index name, PCBNAME=IXNAME.

To define the secondary index in the Master File, you must do the following:

• Describe each field that participates in a secondary index as a key or search field, with the suffix .KEY, .HKY, or .IMS.
• Describe the rest of the IMS segment with FOCUS field definitions or filler fields.
• At the end of the root segment, define each secondary index as a group field:
  • The ALIAS of the group field must have the suffix .SKY (Secondary index key) appended to the index name from the XDFLD record in the DBD. That is, ALIAS=XDFLDname.SKY, where XDFLDname is the value of the NAME parameter in the XDFLD record of the DBD.
  • The fields that comprise the secondary index must be subordinate fields in the group. You can find the names of these fields in the SRCH parameter of the XDFLD record in the DBD. You described these fields previously in the Master File as sequence or search fields. When you now describe them as subordinate fields, you must assign them a new FIELDNAME not already used in the Master File. Their ALIAS values must be the FIELDNAME values you previously gave them.

The following diagram illustrates how to describe a secondary index in the Master File:

1. Is the IMS DBD. It describes one secondary index. The XDFLD record assigns the name IXNAME to the index. The SRCH parameter indicates that the IXNAME index searches on the fields LNAME and FNAME.
2. Is the corresponding Master File. In the GROUP record at the end of the Master File, the ALIAS value is the name of the index from the DBD with the suffix SKY appended.

   The subordinate fields in the group were previously assigned field names in the Master File. The ALIAS value for each subordinate field in the group definition is the previously-assigned FIELDNAME. The FIELDNAME in the subordinate field entry is a new name.

The adapter now has the information necessary for determining the best access path for a particular request. Consider the following request:

TABLE FILE PATINFO
PRINT LAST_NAME FIRST_NAME SALARY ADMIT_DATE
IF LAST_NAME IS 'SMITH'
END

Since the field referenced in the IF condition is the high-order part of an index, the adapter generates a qualified SSA to retrieve data using the PCB that permits access through the index. Reporting Efficiencies, shows examples of such SSAs.

Sample File Descriptions illustrates three secondary index definitions for this database.