The Master File

In this section:

Each Master File that provides access to an IMS database describes the segments and fields that are available through one IMS PCB.

You do not have to describe every segment from the PCB in the Master File. However, the portion of the hierarchy you describe must be a subtree starting from the root (see IMS Overview and Mapping Concepts). Any segment or field that you do not describe in the Master File remains invisible to FOCUS.

Reporting costs are largely a function of the volume of data transferred. Therefore, requests issued through the adapter are efficient and cost effective because only segments referenced in your request are retrieved.

In a Master File the cumulative length of all fields across all segments cannot exceed 12,000 bytes (an IMS restriction. Field Attributes contains additional information about this limit).

Each Master File is stored as a member of a Master File PDS. The member name for a Master File must be the name assigned to that Master File in the FOCPSB record for the corresponding PCB (see The PCB Record in Required FOCPSB Attributes). At run time, the Master File data set is allocated to ddname MASTER.

A Master File consists of file, segment, and field declarations. Rules for declarations follow:

The following sections summarize the syntax for each type of declaration and then describe each attribute.


Top of page

x
File Attributes

Each Master File begins with a file declaration that names the file and describes the type of data source—an IMS database in this case. The file declaration has two attributes, FILENAME and SUFFIX. The syntax is

FILE[NAME]=filename, SUFFIX=IMS [,$]

where:

filename

Is any 1- to 8-character file name.

SUFFIX=IMS

Indicates that the Adapter for IMS/DB is required for data retrieval.


Top of page

x
Segment Attributes

In this section:

Each IMS segment described in a Master File requires a segment declaration that consists of at least two attributes, SEGNAME and SEGTYPE. The SEGNAME value is the name of the corresponding IMS segment. The SEGTYPE value identifies the characteristics of the segment.

The syntax is

SEGNAME=segname ,SEGTYPE= segtype [, PARENT=parent] [,$]

where:

segname

Is the one- to eight-character IMS segment name from the NAME parameter of the SENSEG record in the IMS PCB (see IMS Overview and Mapping Concepts).

segtype

Identifies the characteristics of the segment. Possible values follow:

U indicates that the segment is data sensitive and unique. A unique segment has no twins (PTR=NOTWIN in the IMS DBD). While a parent segment can have many types of unique children, it can have at most one instance of each type.

S0 indicates that the segment is data sensitive and has no key.

S or S1 indicates that the segment is data sensitive and has a non-unique key.

S2 indicates that the segment is data sensitive and has a unique key.

SH or SH1 indicates that the segment is key sensitive and has a non-unique key.

SH2 indicates that the segment is key sensitive and has a unique key.

parent

Is the name of the parent segment from the IMS database. Its value comes from the PARENT parameter of the SENSEG record in the IMS PCB.



x
SEGNAME

The SEGNAME attribute identifies the IMS segments you can access. The SEGNAME value is the name of the IMS segment from the SENSEG record in the PCB.

FOCUS retrieves segments in top-to-bottom, left-to-right sequence as described by the Master File. Therefore, the order of segments in the Master File should be the same as their order in the PCB in order to maintain the correct hierarchical sequence. However, FOCUS retrieves unique segments (only one instance per parent—no twins) prior to any non-unique segments that have the same parent.



x
SEGTYPE

The SEGTYPE attribute does the following:

The following table lists the valid SEGTYPE values:

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

No

Not Applicable



x
PARENT

The PARENT attribute identifies the parent of the segment in the hierarchy. It appears in the PARENT parameter of the SENSEG record in the PCB. The only exception is in the root segment, where the PCB either omits the PARENT parameter or specifies PARENT=0. In the Master File, you can specify the PARENT attribute of the root segment as PARENT=, or you can omit it.


Top of page

x
Field Attributes

In this section:

Each segment consists of one or more fields. The IMS DBD contains FIELD declarations for all sequence (key) and search fields, but other fields are optional.

If the PCB you are describing contains SENFLD records for a segment, the Master File can view only fields explicitly specified 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.

The Master File must describe the entire IMS segment. If it does not need access to some of the fields from a segment, it can replace their definitions with filler fields that occupy the same amount of space.

To describe a field in the Master File, you must supply the primary attributes FIELDNAME, ALIAS, USAGE, and ACTUAL, discussed in this section.

The Describing Data manual explains additional attributes, such as TITLE and DESCRIPTION, as well as how to define temporary fields in the Master File.

Note: The adapter does not support the MISSING attribute.

The syntax for a field declaration is

FIELD[NAME]=fieldname,[ALIAS=alias],[USAGE=]display,[ACTUAL=]imsformat,$

where:

fieldname

Is a field name that complies with FOCUS field naming conventions. In requests, you can qualify the field name with the Master File and/or segment name.

alias

Is an alias for an IMS field. Possible values are:

imsname.KEY is the alias for an IMS key field (except for the root key of an HDAM database). Form the alias by appending the suffix KEY to the name of the IMS field.

imsname.IMS is the alias for an IMS search field. Form the alias by appending the suffix IMS to the name of the IMS field.

imsname.HKY is the alias for the key of the root segment in an HDAM database. Form the alias by appending the suffix HKY to the name of the IMS field.

anyname is the alias for a field not listed in the DBD. The alias is any name that complies with FOCUS field naming conventions. The alias value can also be blank.

display

Is the FOCUS display format for the field.

imsformat

Is the FOCUS definition of the IMS field format and length (n).

You can omit the ALIAS, USAGE, and ACTUAL keywords from the field declaration if the values are specified in the standard order (FIELD, ALIAS, USAGE, ACTUAL). For example, the following declarations are equivalent:

FIELD = YEAR, ALIAS=YR, USAGE=A2, ACTUAL=A2,$
FIELD = YEAR, YR, A2, A2,$


x
FIELDNAME

IMS field names are acceptable values if they meet the following naming conventions:

Since field names appear as default column titles for reports, select names that are representative of the data.

You can use field names, aliases, or a unique truncation of either in requests. For example, consider the following Master File:

FILENAME=MFD1
  SEGNAME=SEG1
   FIELDNAME=S1, ALIAS=K1.KEY, USAGE=A4, ACTUAL=A4,$

The following commands are all equivalent in a FOCUS request:

PRINT S1
PRINT S
PRINT K1.KEY
PRINT K1
PRINT K

Duplicate field names (the same field names and aliases) within a segment are not permitted. Report requests can qualify duplicate field names from different segments with the name of the Master File and/or segment. That is, using the Master File from the previous example, the following are equivalent:

PRINT SEG1.S1
PRINT MFD1.S1
PRINT MFD1.SEG1.S1

You need this type of qualification if two segments in the Master File or in a join have a field defined with the same field name and alias. For more information about field qualifiers, see your FOCUS documentation.

Note: Field names in OCCURS segments may not be qualified.



x
ALIAS

The ALIAS value in the Master File distinguishes between fields that are defined in the IMS DBD and fields that are not defined to IMS. The adapter uses this information in constructing DL/I calls to IMS.

If a field used in a screening test (IF or WHERE) is a sequence or search field, the adapter may be able to create an SSA that instructs IMS to apply the screening test and return the appropriate records to FOCUS. If the field is not defined in the DBD, the adapter must retrieve all records sequentially from IMS so that FOCUS can screen them.

In certain cases, the adapter can instruct IMS to screen values based on a secondary index. Using a Secondary Index describes the technique for taking advantage of a secondary index.

The ALIAS value for a field defined in the DBD is composed of the following:

You can assign fields not defined in the DBD any name that complies with FOCUS field naming conventions. Do not include periods or suffix values for such alias names.

In requests, you can reference a field by its field name, its alias, or by a unique truncation of either. Note that the IMS field name is a unique truncation of the alias value. For example, if the IMS key field is named IMSNAME, then the alias for that field in the Master File is IMSNAME.KEY. A FOCUS request can reference the field by the name IMSNAME (without .KEY) because this name is a unique truncation of the alias.



x
USAGE

The USAGE attribute indicates the display format of the field. An acceptable value must include the field type and length and may contain diaplay options. USAGE formats (A, D, F, I, P) are available. For additional information about USAGE formats for non-FOCUS data sources, see the Describing Data manual.



x
ACTUAL

The ACTUAL attribute indicates the FOCUS representation of IMS field formats.

For fields defined in the DBD (sequence and search fields), use the format specified in the DBD.

Use the following chart as a guide for describing ACTUAL formats of those fields not defined in the DBD:

COBOL FORMAT

COBOL PICTURE

BYTES OF STORAGE

ACTUAL FORMAT

USAGE FORMAT

DISPLAY

X(4)

4

A4

A4

DISPLAY

S99

2

Z2

P3

DISPLAY

9(5)V9

6

Z6.1

P8.1

DISPLAY

99

2

A2

A2

COMP

S9

4

I2

I1

COMP

S9(4)

4

I2

I4

COMP

S9(5)

4

I4

I5

COMP

S9(9)

4

I4

I9

COMP-1

-

4

F4

F6

COMP-2

-

8

D8

D15

COMP-3

9

1

P1

P1

COMP-3

S9V99

2

P2

P5.2

COMP-3

9(4)V9(3)

4

P4

P8.3

FIXED BINARY(7) (COMP-4)

B or XL1

4

I4

I7

The USAGE lengths shown are minimum values. You can make them larger and add display options. You must allow space for all possible digits, a minus sign for negative numbers, and a decimal point in numbers with decimal digits. For more information, see the Describing Data manual.

The cumulative length of all fields, across all segments, cannot exceed 12K bytes. To determine whether the database you are defining falls within these constraints, issue the following report request:

CHECK FILE filename HOLD
TABLE FILE HOLD
WRITE MAX.LWORD
END

The resulting value must be less than or equal to 3,000.

The following example illustrates the DI21PART Master File that provides access to the DI21PART database.

FILE=DI21PART    ,SUFFIX=IMS,$
SEGNAME=PARTROOT ,PARENT=,SEGTYPE=S2,$
  FIELD=PARTKEY  ,ALIAS=PARTKEY.HKY  ,USAGE=A17  ,ACTUAL=A17  ,$
  FIELD=SKIP1    ,ALIAS=SKIP1        ,USAGE=A33  ,ACTUAL=A33  ,$
SEGNAME=STANINFO ,PARENT=PARTROOT,SEGTYPE=S2,$
  FIELD=STANKEY  ,ALIAS=STANKEY.KEY  ,USAGE=A2   ,ACTUAL=A2   ,$
  FIELD=SKIP2    ,ALIAS=SKIP2        ,USAGE=A83  ,ACTUAL=A83  ,$
SEGNAME=STOKSTAT ,PARENT=PARTROOT,SEGTYPE=S2,$
  FIELD=STOCKEY  ,ALIAS=STOCKEY.KEY  ,USAGE=A16  ,ACTUAL=A16  ,$
  FIELD=SKIP3    ,ALIAS=,SKIP3       ,USAGE=A124 ,ACTUAL=A124 ,$
SEGNAME=CYCCOUNT ,PARENT=STOKSTAT,SEGTYPE=S2,$
  FIELD=CYCCKEY  ,ALIAS=CYCCKEY.KEY  ,USAGE=A2   ,ACTUAL=A2   ,$
  FIELD=SKIP4    ,ALIAS=SKIP4        ,USAGE=A23  ,ACTUAL=A23  ,$
SEGNAME=BACKORDR ,PARENT=STOKSTAT,SEGTYPE=S2,$
  FIELD=BACKEY   ,ALIAS=BACKEY.KEY   ,USAGE=A10  ,ACTUAL=A10  ,$
  FIELD=SKIP5    ,ALIAS=SKIP5        ,USAGE=A65  ,ACTUAL=A65  ,$


x
Group Fields

In this section:

IMS fields can consist of multiple elementary fields. In the Master File, you can break the IMS field into component parts using a GROUP field.

The GROUP record in the Master File describes the combined elementary fields. FIELD records immediately following the GROUP record describe the individual elementary fields.

You can describe a GROUP field in two ways. The first way is by listing its elements but not assigning USAGE and ACTUAL formats to the group field. The second option is to calculate the formats of the group based on the individual formats of its component fields. This method is included for compatibility with prior releases of the adapter.



x
Describing a Group Field as a Set of Elements

Each element of the group can have a different format. However, retrieval is more efficient if each USAGE format is of the same type (for example, alphanumeric or packed) as its ACTUAL format. The lengths may differ.

GROUP=gname, ALIAS=alias, ELEMENTS=n,$
 FIELD=fld1,,usage1,actual1,$
 .
 .
 .
 FIELD=fldn,,usagen,actualn,$

where:

gname

Is the group name. It can be any name that complies with field naming conventions.

alias

Is the IMS field name from the DBD if the group field is a sequence or search field. Possible values are:

imsfield.KEY is the alias for a field that is an IMS key field. Form the alias by appending the suffix KEY to the name of the IMS field.

imsfield.IMS is the alias for a field that is an IMS search field. Form the alias by appending the suffix IMS to the name of the IMS field.

imsfield.HKY is the alias for a field that is the key of the root segment in an HDAM data source. Form the alias by appending the suffix HKY to the name of the IMS field.

Note: The keyword ALIAS is required.

n

Is the number fields in the group.

fld1,...,fldn

Are field names for the individual elements that compose the group.

usage1,...,usagen

Are USAGE formats for the individual elements. For efficient retrieval, each individual USAGE format must be of the same data type as its corresponding ACTUAL format, but their lengths can differ.

actual1,...,actualn

Are ACTUAL formats for the individual elements. For efficient retrieval, each individual USAGE format must be of the same data type as its corresponding ACTUAL format, but their lengths can differ.



Example: Defining a Group Key

The following is an example of a group key definition in the Master File:

GROUP=G1, ALIAS=FILEKEY.KEY, ELEMENTS=3 ,$
  FIELD=F1,,A4,A4,$
  FIELD=F2,,P6,P3,$
  FIELD=F3,,I9,I4,$

The GROUP in the example describes an IMS key named FILEKEY that is 11 bytes long and consists of a 4-byte alphanumeric field, a 3-byte packed number, and a 4-byte integer.

The ACTUAL length of the GROUP is 11 (4+3+4).

The USAGE length of the GROUP is 16 (4+8+4) because it counts the packed field as 8.

Since the group components are of mixed data types, you must use individual fields in the WHERE expression of a query.

WHERE F1 = ABCD
WHERE F1 BETWEEN A AND B
WHERE F2 = 245

If you reference either the group or the first elementary field from the group in your request, the adapter generates qualified SSAs in its DL/I calls for retrieval. Thus, IMS does the screening and returns the segments that pass the screening test back to the adapter.

However, if you reference an elementary field that is not the first field in the group, the adapter constructs DL/I calls to retrieve the segments sequentially, and then FOCUS applies the screening test to the returned data.

Note: The adapter does not support a group field within a group field. You may be able to use DEFINE fields in the Master File instead.



x
Describing a Group Field With Formats

Each element of the group can have a different format. However, retrieval is more efficient if the USAGE format for each element is the same type as its ACTUAL format (for example, alphanumeric or packed); the lengths may differ.

The syntax for a GROUP record and its subordinate FIELD records is

GROUP=gname, ALIAS=alias, USAGE=An, ACTUAL=Am,$
FIELD=fld1,al1,use1,act1,$
 .
 .
 .
FIELD=fldn,aln,usen,actn,$

where:

gname

Is the group name. It can be any name that complies with FOCUS field naming conventions.

alias

Is an alias for an IMS field. Note that the keyword ALIAS is required. Possible values follow:

imsname.KEY is the alias for an IMS key field (except for the root key of an HDAM database). Append the suffix KEY to the name of the IMS field.

imsname.IMS is the alias for an IMS search field. Append the suffix IMS to the name of the IMS field.

imsname.HKY is the alias for the key of the root segment in an HDAM database. Append the suffix HKY to the name of the IMS field.

anyname is the alias for a field not listed in the DBD. The alias is any name that complies with FOCUS field naming conventions. The alias value can also be blank.

An

Is the USAGE format for the GROUP. It must be alphanumeric and its length must count all F fields as length 4, all D fields as length 8, and all integer fields as length 4, regardless of the length specified in the ACTUAL format. For alphanumeric fields, USAGE length must equal ACTUAL length. For P (packed) fields, the length depends on the USAGE of the packed field:

USAGE of Packed Field

Length for GROUP USAGE

Pn or Pn.d, n≤15, P16

8

P16

8

P16.d

16

Pn or Pn.d, 16<n≤31

16

Am

Is the ACTUAL format for the GROUP. Its length is the sum of the lengths of the IMS fields.

fld1,...,fldn

Are FOCUS field names for the individual elements in the group.

al1,...,aln

Are alias names for the individual elements. They can be any names that comply with FOCUS field naming conventions.

use1,...,usen

Are USAGE formats for the individual elements. For efficient retrieval, each individual USAGE format must be of the same data type as its corresponding ACTUAL format, but their lengths can differ.

act1,...,actn

Are ACTUAL formats for the individual elements. For efficient retrieval, each individual USAGE format must be of the same data type as its corresponding ACTUAL format, but their lengths can differ.

The following is an example of a group key definition in the Master File:

GROUP=G1, ALIAS=FILEKEY.KEY, USAGE=A16, ACTUAL=A11 ,$
  FIELD=F1,F1,A4,A4,$
  FIELD=F2,F2,P6,P3,$
  FIELD=F3,F3,I9,I4,$

Note:

You can use the group field or any individual field in a FOCUS query. For example:

WHERE G1 EQ 'ABCD'/245/-20 or
IF G1 GT ABCD/245/-20
IF G1 FROM ABCD/245/-20 TO ABCD/300/50
IF G1 IS ABCD/245F/-20  (field F2 has a non-standard sign, F) 
IF G1 IS A$*
IF F1 IS ABCD
IF F1 FROM A TO B
IF F2 IS 245

You must use a slash (/) to separate the individual fields when you reference the group name.

If you reference either the group or the first elementary field from the group in your request, the adapter generates qualified SSAs in its DL/I calls for retrieval. Thus, IMS does the screening and returns the segments that pass the screening test back to FOCUS.

However, if you reference an elementary field that is not the first field in the group, FOCUS constructs DL/I calls to retrieve the segments sequentially, and then FOCUS applies the screening test to the returned data.

Reporting Efficiencies contains a detailed explanation of screening conditions and SSA generation.

Note: The adapter does not support a group field within a group field. See the Describing Data manual for information on DEFINE fields in the Master File.


Top of page

x
Using a Secondary Index

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.

In prior FOCUS releases, each Master File could describe only one index and the application programmer had to decide which Master File provided the optimal access path for a request. This technique is still supported, and Release Dependent Adapter Features describes it.

Note: In the DBCTL environment, secondary indexes can be described in the Access File.

In current FOCUS releases, one Master File and FOCPSB can describe all primary and secondary indexes for a database. Then, given a report request, the adapter can examine all record selection tests to determine the best access path into the database. The adapter can take advantage of this Auto Index Selection feature for the following reasons:

In the Master File, prior to the secondary index definitions, you must describe the entire root segment of the database. Every field listed in the DBD is an IMS sequence field or search field, and each secondary index is based on one or more of these fields. You must assign each secondary index field its appropriate alias, as described in ALIAS in Field Attributes.

Note: IMS allows system-defined sub-sequence fields to make an index unique. The Master File can completely ignore the presence and length of such fields.

For each secondary index, in the Master File you must perform the following steps:

  1. Describe the secondary index as a group field at the end of the root segment. In the group definition, use the index name (provided by the XDFLD NAME parameter in the DBD) as the alias name and append the suffix SKY to it. The syntax is
    GROUP=anyname,ALIAS=XDFLDname.SKY

    where:

    anyname

    Is the field name for the group, unique within the Master File.

    XDFLDname

    Is the name assigned to the index by the XDFLD record in the DBD.

    For example, consider the following portion of the DBD for the PATDB01 database:

          .
          .
          .
        FIELD NAME=LNAME,BYTES=12,START=56,TYPE=C
        FIELD NAME=FNAME,BYTES=12,START=68,TYPE=C
          .
          .
          .
        LCHILD NAME=(SEGIX1,PATDBIX1),PTR=INDX
        XDFLD  NAME=IXNAME,SRCH=(LNAME,FNAME),                           X
                    SUBSEQ=/SX1,NULLVAL=BLANK

    In the example, the fields that comprise the secondary index are LNAME, FNAME, and an additional sub-sequence system field that makes the index unique and that the Master File can ignore. The GROUP definition for the index in the Master File follows:

    GROUP=NAMEIX   ,ALIAS=IXNAME.SKY   ,USAGE=A24  ,ACTUAL=A24,$

    The ALIAS is the index name from the DBD (XDFLD NAME=IXNAME) with the suffix SKY appended. Note that the index definition completely ignores the sub-sequence field.

  2. Describe the indexed fields as subordinate fields of the group. The XDFLD SRCH parameter in the DBD lists the names of the fields that participate in the index. You already described these fields once in the Master File as sequence or search fields.

    Assign each subordinate field a new field name not previously used in the Master File. Give each subordinate field an alias value identical to the fieldname you assigned it when you previously described it as a sequence or search field. The syntax is

    FIELDNAME=fieldname, ALIAS=alias 
         .
         .
         .
    GROUP=...
    FIELD[NAME] = newname, ALIAS = fieldname 

    where:

    alias

    Is an alias for an IMS field. Possible values are as follows:

    imsname.KEY

    Is the alias for an IMS key field (except for the root key of an HDAM database). Append the suffix KEY to the name of the IMS field.

    imsname.IMS

    Is the alias for an IMS search field. Append the suffix IMS to the name of the IMS field.

    imsname.HKY

    Is the alias for the key of the root segment in an HDAM database. Append the suffix HKY to the name of the IMS field.

    newname

    Is any name not previously used in the Master File.

    fieldname

    Is the field name previously assigned to this field.

The following portion of the PATINFO Master File illustrates the secondary index definition for the example in Step 1:

    .
    .
    .
FIELD=LAST_NAME      ,ALIAS=LNAME.IMS      ,USAGE=A12   ,ACTUAL=A12,$
FIELD=FIRST_NAME     ,ALIAS=FNAME.IMS      ,USAGE=A12   ,ACTUAL=A12,$
    .
    .
    .
GROUP=NAMEIX         ,ALIAS=IXNAME.SKY     ,USAGE=A24,  ,ACTUAL=A24,$
 FIELD=NAMEL         ,ALIAS=LAST_NAME      ,USAGE=A12   ,ACTUAL=A12,$
 FIELD=NAMEF         ,ALIAS=FIRST_NAME     ,USAGE=A12   ,ACTUAL=A12,$

The FOCPSB must also reflect the secondary indexes. The IMS PSB includes a PCB for the normal entry point into the database and an additional PCB for entry through each secondary index. Each PCB for a secondary index includes the parameter PROCSEQ=indexDBDname, where indexDBDname comes from the LCHILD NAME parameter in the database DBD.

The FOCPSB must have a one-to-one correspondence with the PSB.

When the Interface generates DL/I calls for retrieval, it examines the record selection tests in the request to determine which PCB offers the most efficient access path to the required data. See Reporting Efficiencies, for information.

Note: Since the PSB most likely includes only one PCB for each secondary index, each Master File that accesses the same index PCB must contain the same GROUP ALIAS value for the index.

Release Dependent Adapter Features, includes a sample DBD, PSB, FOCPSB, and Master File for the PATDB01 database and its three secondary indexes.


Top of page

x
Segment Redefinition: The RECTYPE Attribute

In this section:

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 and has the same format and length in each redefinition, you can use the RECTYPE attribute to define the different segment types in the Master File.

The record type (RECTYPE) field can be part of the key or of the body of the segment. When you issue a request, you do not have to know which segment definition is called for. FOCUS displays the appropriate fields and values based on the value in the RECTYPE field.

In the Master File, you describe the one IMS segment with multiple FOCUS segments, a base segment describing the unchanging portion, and a child segment describing each redefinition:

  1. First define the constant portion of the segment as the base segment. Give it the same name as the IMS segment. Include a filler field for the portion that will be redefined. The field that identifies the different record types must be in the redefined portion.
  2. Describe each redefined portion as a child of the base segment. You can give these children any valid segment names, but do not assign them SEGTYPE values. Include a filler field in each child to occupy the positions of fields actually defined in the base segment.
  3. In each child segment, describe the field that identifies the segment type with FIELDNAME=RECTYPE. The value in the RECTYPE field is the value that identifies the type of segment. For example, the RECTYPE field could contain the value S for a shipment record, O for an order record. The format of the RECTYPE field can be alphanumeric, integer, or packed.
  4. Assign the identifying value (for example, S or O) as the ALIAS for the RECTYPE field. If more than one value can identify the same record type, use the ACCEPT attribute, discussed in Accepting Multiple RECTYPE Values, instead.
  5. Describe the remaining fields of each child segment based on its contents and function.

The following example illustrates an IMS DBD with a redefined segment. The CLIENT segment contains client ID, address, and other client information. The INFO segment contains either shipment information or order information, depending on the value in the INFOTYPE field. If INFOTYPE contains the value S, the segment is a shipment segment. If INFOTYPE contains the value O, the segment is an order segment. The relevant portions of the DBD are shown:

SEGM NAME=CLIENT,BYTES=(200),PTR=(TWIN),PARENT=0
  FIELD=(CLID,SEQ,U),BYTES=8,START=1,TYPE=C
   .
   .
   .
SEGM NAME=INFO,BYTES=(200),PTR=(TWIN),PARENT=CLIENT
  FIELD=(IKEY,SEQ,U),BYTES=8,START=1,TYPE=C
  FIELD=(INFOTYPE),BYTES=1,START=09,TYPE=C
   .
   .
   .

The corresponding Master File represents the IMS INFO segment with three segments:

   FILE=IMS1,SUFFIX=IMS
    SEGNAME=CLIENT,SEGTYPE=S2
      FIELD=F1,CLID.KEY,A8 ,A8 ,$
      FIELD=F2,CLNAME  ,A20,A20,$ 
1.  SEGNAME=INFO   ,SEGTYPE=S2,PARENT=CLIENT,$
      FIELD=F3,IKEY.KEY,A8 ,A8 ,$
      FIELD=,,          A20,A20,$ 
2.  SEGNAME=SHIP   ,SEGTYPE=, PARENT=INFO,$
      FIELD=,,          A8 ,A8 ,$
      FIELD=RECTYPE ,S, A1 ,A1 ,$
      FIELD=SHIPDATE,,  A6 ,A6 ,$
       .
       .
       .
      other shipment info 
3.  SEGNAME=ORDER,SEGTYPE=,PARENT=INFO,$
      FIELD=,,         A8 ,A8 ,$
      FIELD=RECTYPE,O, A1 ,A1 ,$
      FIELD=ORDERDATE,,A6 ,A6 ,$
       .
       .
       .
      other order info.
  1. The base segment, like the IMS segment, is named INFO. It contains the key field. The redefined portion is described as a filler field.
  2. The SHIP segment describes the shipment record type. The field that corresponds to the IMS INFOTYPE field has FIELDNAME=RECTYPE and ALIAS=S.
  3. The ORDER segment describes the order record type. The field that corresponds to the IMS INFOTYPE field has FIELDNAME=RECTYPE and ALIAS=O.

Notice that each child segment has a filler for the key field defined in the base segment.



x
Accepting Multiple RECTYPE Values

If multiple values identify the same record type (for example, S or T for a shipment record), use the ACCEPT attribute to enumerate the list or range of acceptable values. In this case, define the ALIAS value as blank.

The syntax is

FIELDNAME=RECTYPE, ALIAS= , USAGE=usage, ACTUAL=actual,
ACCEPT = val1 [OR] val2 [ [OR] ...valn] ,$
   ACCEPT = val1 TO val2,$

where:

usage

Is the FOCUS display format for the field.

actual

Is the FOCUS definition of the IMS field format and length (n).

val1,val2,valn

Defines a list or range of values that identifies the record type. A list can be continued on more than one line. Enclose values that contain embedded blanks or special characters in single quotation marks.

The following examples illustrate the ACCEPT attribute:

ACCEPT = AAA TO RRR
ACCEPT = 136 TO 1029
ACCEPT = RED OR WHITE OR BLUE
ACCEPT = RED WHITE BLUE
ACCEPT = 6 OR 11 OR 922 OR 1000
ACCEPT = RED WHITE 'GREEN GREY'

Refer to the Logical Parent Segment feature in IMS Overview and Mapping Concepts, for more information on RECTYPEs.


Top of page

x
Variable Length Segments: The OCCURS Segment

In this section:

In an IMS database, segments can have repeating fields or repeating groups of fields. The number of repetitions may have the following attributes:

In the Master File, you define multiple segments to describe one IMS variable length segment:

The OCCURS segment is a virtual segment (it does not physically exist) that describes the repetitions to FOCUS. The following chart lists permissible values for the OCCURS attribute:

OCCURS=

Description

n

Is the number of times the field repeats in the segment.

fieldname

Is the name of a field that contains a value indicating the number of times the field repeats in the segment. The repeating field must be at the end of the segment.

VARIABLE

Indicates that the number of repetitions must be computed from the length of the segment. In this case, the segment must contain a counter field as its first field. The counter field alias in the Master File must be IMSname.CNT. The repeating field must be at the end of the segment.

When the number of occurrences is fixed, the repeating field can be located between two fields rather than at the end of the segment. In this case, you must define a place-holder field at the position of the repeating field in the base segment. Then, in the OCCURS segment, you must indicate the location of the repeating field by supplying the name of the place-holder field with the POSITION attribute.

The syntax for an OCCURS segment is

SEGNAME=occseg,PARENT=imsseg,OCCURS=occurs,$

where:

occseg

Is the name of the OCCURS segment. It can be any valid segment name.

imsseg

Is the name of the base segment. It must be the IMS segment name.

occurs

Indicates the number of repetitions. Possible values are:

n is the fixed number of times that the group repeats in the segment. It is an integer value from 1 to 4095.

n, POSITION=posfield signals that the repeating field is embedded within the base segment rather than occurring at the end and names a field in the base segment that marks the starting position of the repeating field.

nfield is the name of a field in the parent or non-repeating portion of the segment whose value is the number of times that the group repeats. You must define this field in the Master File whether or not it is a search field defined in the DBD.

VARIABLE indicates that the length of the repeating segment varies and that the number of occurrences can be computed from each segment. In this case, the (base) segment must contain a counter field as its first field. The alias value for the counter field must be IMSname.CNT (IMSname is the name of the field in the IMS DBD).

In the IMS DBD, a variable length segment differs from a fixed length segment only in the BYTES parameter. For variable length segments, the BYTES parameter consists of two values: the maximum and minimum number of bytes. IMS cannot search for values among the repetitions within a segment. Therefore, in any FOCUS retrieval request that references a field in a repeating group, FOCUS, and not IMS, searches and screens the OCCURS segments.



x
The ORDER Field

Sometimes the sequence of fields within an OCCURS segment is significant. For example, each instance of the repeating field may represent one quarter of the year, but the segment may not have a field that identifies the quarter to which it applies.

ORDER is an optional counter used to identify the sequence number within a group of repeating fields. You should include it when the order of data is important. The ORDER field does not represent an existing field in the database. It is used only for internal processing.

The ORDER field must be the last field described in the OCCURS segment. The syntax is

FIELDNAME=fieldname, ALIAS=ORDER, USAGE=In, ACTUAL=I4 ,$

where:

fieldname

Is a valid field name.

In

Is an integer format.

Note:

In report requests, you can use the value of the ORDER field. You can also use a DEFINE field in your session or in the Master File to translate it to more meaningful values. For example:

DEFINE ...
QTR/A3 = DECODE ORDER(1 '1ST' 2 '2ND' 3 '3RD' 4 '4TH')
 .
 .
 .

A subsequent request could include:

PRINT TOT.TAXES IF QTR IS 1ST

or

PRINT QTR BALANCE INTEREST


x
Example: OCCURS=n

In the following example, the IMS segment, IMS1, includes a group (consisting of the two fields MONTH and AMOUNT) that repeats 12 times. The COBOL FD for the segment follows:

01  IMS1
    05  ACCOUNT  PIC X(9)
    05  TYPE     PIC XXX
    05  PAYMENT OCCURS 12 TIMES
        10 MONTH PIC 99
        10 AMT   PIC S9(3)V(99)COMP-3

The Master File uses two segments to describe this IMS variable length segment:

1. SEGNAME=IMS1,PARENT=,SEGTYPE=S2 
    FIELD=ACT_NUM ,ALIAS=ACCOUNT.KEY ,A9  ,A9,$
    FIELD=TYPE    ,ALIAS=TYPE        ,A3  ,A3,$ 
2. SEGNAME=OCC1,PARENT=IMS1,OCCURS=12
    FIELD=MM      ,ALIAS=MONTH       ,A2  ,A2,$
    FIELD=AMT     ,ALIAS=AMT         ,P6.3,P3,$
  1. Segment IMS1 is the base segment. It has the same name as the IMS segment and describes the two non-repeating fields, ACT_NUM and TYPE.
  2. The OCCURS segment, OCC1, identifies IMS1 as its parent. It has no SEGTYPE, and it includes the OCCURS attribute. The two repeating fields are described in this segment.

In the following example, the repeating group is not at the end of the segment, but is embedded in the segment before the LNAME field. The COBOL FD for this situation is:

01  IMS1
    05  ACCOUNT PIC X(9)
    05  TYPE    PIC XXX
    05  PAYMENT OCCURS 12 TIMES
        10 MONTH PIC 99
        10 AMT   PIC S9(3)V(99)COMP-3
    05  LNAME    PIC X(20)

The Master File must include LNAME in the base segment. It must also describe where the repeating fields fit into the base segment by defining a place-holder field before LNAME, equal to the length of the 12 occurrences and by pointing to the place-holder field with the POSITION attribute:

   SEGNAME=IMS1,PARENT=,SEGTYPE=S2 
    FIELD=ACT_NUM   ,ALIAS=ACCOUNT.KEY  ,A9 ,A9 ,$
    FIELD=TYPE      ,ALIAS=TYPE         ,A3 ,A3 ,$ 
1.  FIELD=HOLDIT    ,ALIAS=             ,A60,A60,$
    FIELD=LNAME     ,ALIAS=LAST_NAME    ,A20,A20,$ 
2. SEGNAME=OCC1,PARENT=IMS1,OCCURS=12, POSITION=HOLDIT
    FIELD=MM        ,ALIAS=MONTH        ,A2  ,A2,$
    FIELD=AMT       ,ALIAS=AMT          ,P6.3,P3,$
  1. The HOLDIT field is the place holder for the repeating group in the base segment (IMS1). Since the repeating group consists of 12 occurrences, each of which is 5 bytes long (A2 and P3, described in segment OCC1), the HOLDIT field is defined as A60.
  2. The attribute POSITION=HOLDIT in the OCCURS segment declaration describes where the repeating group is located in the actual (base) segment.


x
Example: OCCURS=fieldname

In this example, the value of the TIMES field is the number of occurrences. The following COBOL FD describes this situation:

01  IMS1
    05  ACCOUNT PIC X(9)
    05  TYPE    PIC XXX
    05  TIMES   PIC S999  COMP-3 
    05  PAYMENT OCCURS DEPENDING ON TIMES
        10 MONTH PIC 99
        10 AMT   PIC S9(3)V(99)COMP-3

The Master File attribute, OCCURS=TIMES, identifies the TIMES field as containing the number of repetitions. The Master File also defines the optional ORDER field as the last field in the OCCURS segment:

   SEGNAME=IMS1,SEGTYPE=S2 
    FIELD=ACT_NUM ,ALIAS=ACCOUNT.KEY ,A9   ,A9,$
    FIELD=TYPE    ,ALIAS=TYPE        ,A3   ,A3,$
    FIELD=TIMES   ,ALIAS=TIMES       ,P4   ,P2,$ 
1. SEGNAME=OCC1,PARENT=IMS1, OCCURS=TIMES
    FIELD=MM     ,ALIAS=MONTH        ,A2   ,A2,$
    FIELD=AMT    ,ALIAS=AMT          ,P6.3 ,P3,$ 
2.  FIELD=WHICH  ,ALIAS=ORDER        ,I4   ,I4,$ 
  1. The attribute OCCURS=TIMES identifies the value in the TIMES field as the number of instances of the repeating group.
  2. The field named WHICH is the optional ORDER field (ALIAS=ORDER). It is an internal counter defined as the last field in the OCCURS segment. It associates a sequence number with each occurrence of the repeating group. With the ORDER field defined, a request can include a test that selects a specific occurrence, for example:
    WHERE WHICH EQ 3


x
Example: OCCURS=VARIABLE

This example describes a segment in which the number of occurrences must be calculated from the length of the segment. The first field in the segment must be a 2-byte counter field that contains the true length of the segment and is defined to IMS in the DBD. The COBOL FD for this variable length segment follows:

01  IMS1
    05  COUNTER PIC 99 COMP
    05  ACCOUNT PIC X(9)
    05  TYPE    PIC XXX
    05  PAYMSCHED OCCURS 1 TO 12 TIMES
        10 MONTH PIC 99
        10 AMT   PIC S9(3)V(99)COMP-3

The Master File must specify OCCURS=VARIABLE and must describe the counter field with the attribute ALIAS=IMSname.CNT:

   SEGNAME=IMS1,SEGTYPE=S2  
1.  FIELD=COUNTFLD  ,ALIAS=COUNTER.CNT ,I2   ,I2,$
    FIELD=ACT_NUM   ,ALIAS=ACCOUNT.KEY ,A9   ,A9,$
    FIELD=TYPE      ,ALIAS=TYPE        ,A3   ,A3,$ 
2. SEGNAME=OCC1,PARENT=IMS1, OCCURS=VARIABLE
    FIELD=MM        ,ALIAS=MONTH       ,A2   ,A2,$
    FIELD=AMT       ,ALIAS=AMT         ,P6.3 ,P3,$
  1. The two-byte counter field must be the first field in the base segment. Its alias is formed by appending the suffix CNT to the field name defined in the IMS DBD, ALIAS=COUNTER.CNT.
  2. In the OCCURS segment definition, the attribute OCCURS=VARIABLE indicates that the first field defined in the Master File contains the segment length and that the number of repetitions must be calculated from this length.

Information Builders