Describing Complex RMS Keyed

Describing Multiple Record Types

Files may have records that must be deciphered according to a record type indicator in the record itself. Describing these files involves two things. First, each different record type will need its own segment. Second, the relationship between the different record types (that is, between the different segments) will need to be determined and expressed using the PARENT attribute for each segment.

Using RECTYPE

The syntax for defining a RECTYPE field is

FIELDNAME=RECTYPE,ALIAS=alias,USAGE=usage,ACTUAL= actual 
 [,ACCEPT=list/range],$

where:

RECTYPE

Is the required field name.

alias

Is the primary RECTYPE identifier. If there is an ACCEPT list or range, this value is any valid alias name.

list

Is a list of one or more lines of specific RECTYPE 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 an item in the list contains embedded blanks or commas, it must be enclosed within single quotation marks ('). The list may contain a single RECTYPE value.

For example:

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

range

Is a range of one or more lines of RECTYPE values for records that have the same segment layout. The maximum number of characters allowed in the range is 255. If either value 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.

For example:

FIELDNAME=RECTYPE,ALIAS=100,USAGE=P3,ACTUAL=P2,ACCEPT=70 TO 100,$

When using an ACCEPT list or range, also called generalized RECTYPE, the RECTYPE field name is not unique across segments, therefore it must not be used in a WHERE clause of an SQL request. It is the responsibility of the client application to determine if the row for the RECTYPE is required. If the client application cannot do this, you must code individual segments for each RECTYPE.

To illustrate the use of the generalized RECTYPE capability in RMS file descriptions, consider the following record layouts in the DOC file. Record type DN is the root segment and contains the document number and title. Record types M, I, and C contain information about manuals, installation guides, and course guides, respectively. Notice that record types M and I have the same layout.

Record Type DN:

---KEY---
+-----------------------------------------------------------------+
DOCID    FILLER   RECTYPE   TITLE
+-----------------------------------------------------------------+

Record Type M:

--------KEY------
+-----------------------------------------------------------------+
MDOCID   MDATE   RECTYPE   MRELEASE            MPAGES     FILLER
+-----------------------------------------------------------------+

Record Type I:

--------KEY------
+-----------------------------------------------------------------+
IDOCID   IDATE   RECTYPE   IRELEASE            IPAGES     FILLER
+-----------------------------------------------------------------+

Record Type C:

--------KEY------
+-----------------------------------------------------------------+
CRSEDOC  CDATE   RECTYPE   COURSENUM   LEVEL   CPAGES     FILLER
+-----------------------------------------------------------------+

Without the ACCEPT attribute, each of the four record types must be described as separate segments in the Master File. For example, a unique set of field names must be provided for record type M and for record type I, although they have the same layout.

The generalized RECTYPE capability enables you to code just one set of field names that apply to the record layout for both record type M and record type I. The ACCEPT attribute can be used for any RECTYPE specification, even when there is only one acceptable value.

FILENAME=DOC, SUFFIX=RMS,$
SEGNAME=ROOT, SEGTYPE=S0,$
 GROUP=DOCNUM,  ALIAS=KEY,          A5,  A5, $
  FIELD=DOCID,     ALIAS=,          A5,  A5, $
 FIELD=FILLER,     ALIAS=,          A5,  A5, $
 FIELD=RECTYPE,    ALIAS=,          A3,  A3, $
 FIELD=TITLE,      ALIAS=,          A18, A18,$
SEGNAME=MANUALS, PARENT=ROOT, SEGTYPE=S0,    $
 GROUP=MDOCNUM, ALIAS=KEY,          A10, A10,$
  FIELD=MDOCID,    ALIAS=,          A5,  A5, $
  FIELD=MDATE,     ALIAS=,          A5,  A5, $
 FIELD=RECTYPE,    ALIAS=M,         A3,  A3, ACCEPT = M OR I,$
 FIELD=MRELEASE,   ALIAS=,          A7,  A7, $
 FIELD=MPAGES,     ALIAS=,          I5,  A5, $
 FIELD=FILLER,     ALIAS=,          A6,  A6, $
SEGNAME=COURSES, PARENT=ROOT, SEGTYPE=S0,    $
 GROUP=CRSEDOC, ALIAS=KEY,          A10, A10,$
  FIELD=CDOCID,    ALIAS=,          A5,  A5, $
  FIELD=CDATE,     ALIAS=,          A5,  A5, $
 FIELD=RECTYPE,    ALIAS=C,         A3,  A3, $
 FIELD=COURSENUM,  ALIAS=,          A4,  A4, $
 FIELD=LEVEL,      ALIAS=,          A2,  A2, $
 FIELD=CPAGES,     ALIAS=,          I5,  A5, $
 FIELD=FILLER,     ALIAS=,          A7,  A7, $

Describing Related Record Types

Consider the LIBRARY file that contains three types of records, related by a combination of the key and the RECTYPE attribute. The ROOT records have a key that consists of the publisher's number. The BOOKINFO segment has a key that consists of that same publisher's number, plus a hard or soft-cover indicator. The SERIANO key consists of the first two elements, plus a record type.

In the sample file, the repetition of the publisher number interrelates the three types of records. The Master File for this file would look like the following:

FILENAME=LIBRARY6,SUFFIX=RMS,$
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,SEGTYPE=S0,PARENT=ROOT,$
 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,SEGTYPE=S0,PARENT=BOOKINFO,$
 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,SEGTYPE=S0,PARENT=ROOT,OCCURS=VARIABLE,$
  FIELDNAME=PLOTLINE   ,ALIAS=PLOTL ,USAGE=A10     ,ACTUAL=A10    ,$

A typical query might request information on price and call numbers for a specific publisher's number:

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

Since PUBNO is part of the key, the retrieval can be made and the processing continues. For greater speed retrieval, you could add search criteria based on the BINDING field, which is also part of the key.

Describing Unrelated Record Types

A file may contain records that are not related to each other. Records with varying RECTYPEs exist independently of each other in a file, and the sequence of records in the file may be random.

Consider our LIBRARY file. Suppose that the file has three types of records: book information, magazine information, and newspaper information.

Since book information, magazine information, and newspaper information have nothing in common, these record types cannot be described in a parent/child relationship.

The records simply look like the following:

BOOK    MAGAZINE    NEWSPAPER

To describe a file with unrelated records, you must make the record types descendants of a root segment named DUMMY.

The following rules apply to the DUMMY segment:

The root (top) segment name must be DUMMY.
It can have only one field, with an empty FIELDNAME and ALIAS.
Both its USAGE and ACTUAL attributes must be A1.

All of the other segments must be descendants of the DUMMY segment.

The Master File for this file would look like the following:

FILENAME=LIBRARY3, SUFFIX=FIX,$
SEGMENT=DUMMY,SEGTYPE=S0,$
   FIELDNAME=            ,ALIAS=       ,USAGE=A1      ,ACTUAL=A1      ,$

SEGMENT=BOOK,SEGTYPE=S0,PARENT=DUMMY,$
   FIELDNAME=RECTYPE     ,ALIAS=B      ,USAGE=A1      ,ACTUAL=A1      ,$
   GROUP=PUBNUM          ,ALIAS=KEY    ,USAGE=AI0     ,ACTUAL=A10     ,$
   FIELDNAME=PUBNO       ,ALIAS=PN     ,USAGE=A10     ,ACTUAL=A10     ,$
   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,SEGTYPE=S0,PARENT=DUMMY,$
   FIELDNAME=RECTYPE     ,ALIAS=M      ,USAGE=A1      ,ACTUAL=A1      ,$
   GROUP=PERNUM          ,ALIAS=KEY    ,USAGE=A10     ,ACTUAL=A10     ,$
   FIELDNAME=PER_NO      ,ALIAS=PN     ,USAGE=A10     ,ACTUAL=A10     ,$
   FIELDNAME=PER_NAME    ,ALIAS=NA     ,USAGE=A50     ,ACTUAL=A50     ,$
   FIELDNAME=VOL_NO      ,ALIAS=VN     ,USAGE=I2      ,ACTUAL=I2      ,$
   FIELDNAME=ISSUE_NO    ,ALIAS=IN     ,USAGE=I2      ,ACTUAL=I2      ,$
   FIELDNAME=PER_DATE    ,ALIAS=DT     ,USAGE=YYMD    ,ACTUAL=DATE    ,$
   FIELDNAME=            ,ALIAS=FILLER ,USAGE=A4      ,ACTUAL=A4      ,$

SEGMENT=NEWSPAP,SEGTYPE=S0,PARENT=DUMMY,$   
   FIELDNAME=RECTYPE     ,ALIAS=N      ,USAGE=A1      ,ACTUAL=A1      ,$
   FIELDNAME=NEW_NAME    ,ALIAS=NN     ,USAGE=A50     ,ACTUAL=A50     ,$
   FIELDNAME=NEW_DATE    ,ALIAS=ND     ,USAGE=I6MDY   ,ACTUAL=I4      ,$
   FIELDNAME=            ,ALIAS=FILLER ,USAGE=A4      ,ACTUAL=A4      ,$
   GROUP=PAPVI           ,ALIAS=KEY    ,USAGE=A4      ,ACTUAL=A4      ,$
   FIELDNAME=NVOL_NO     ,ALIAS=NV     ,USAGE=I2      ,ACTUAL=I2      ,$
   FIELDNAME=NISSUE      ,ALIAS=NI     ,USAGE=I2      ,ACTUAL=I2      ,$

Describing Embedded Repeating Data

In this section:

Some records may contain embedded repeating data. Consider the following record layout:

A   B   C1   C2   C1   C2

Fields C1 and C2 repeat within this data record. C1 has an initial value, as does C2. C1 then provides a second value for that field, as does C2. Thus, there are two values for fields C1 and C2 for every one value for fields A and B.

The number of times C1 and C2 occur does not have to be fixed, depending on the value of a counter field. Suppose field B is this counter field. In the case shown above, the value of field B is 2, since C1 and C2 occur twice. The value of field B in the next record may be different, and fields C1 and C2 will occur that number of times.

The number of times fields C1 and C2 occur can also be variable. In this case, everything after fields A and B is assumed to be a series of C1s and C2s, alternating to the end of the record.

You describe these multiply occurring fields by placing them in a separate segment. Fields A and B are placed in the first segment, called the root segment. Fields C1 and C2, which occur multiple times in relation to A and B, are placed in a descendant segment. You use an additional segment attribute, the OCCURS attribute, to specify that this segment is a multiply occurring segment.

Repeating fields or groups of fields described by the OCCURS attribute are not supported for free-format (comma-delimited) sequential files.

Top of page

OCCURS

The OCCURS attribute is an optional segment attribute used to describe records containing repeating fields or groups of fields. You define such records by describing the singly occurring fields in one segment and the multiply occurring fields in another, subordinate segment. The OCCURS attribute appears in the declaration for the subordinate segment.

The syntax is

OCCURS = {n|fieldname|VARIABLE},$

where:

n: Is an integer value showing the number of occurrences (1 to 4095).
fieldname: Names a data field in the parent segment, that is, a counter specifying the number of occurrences of the descendant segment.
VARIABLE: Indicates that the number of occurrences varies from record to record. The number of occurrences is computed from the record length (that is, if the field lengths for the segment add up to 40, and 120 characters are read in, it means there are three occurrences).

When different types of records are combined in one file, each record type can contain only one segment (defined as OCCURS=VARIABLE). It may have OCCURS descendants (if it contains a nested group), but it may not be followed by any other segment with the same parent, that is, there can be no other segments to its right in the structure. This restriction is necessary to ensure that data in the record is interpreted correctly.

Top of page

Example: Using the OCCURS Attribute

You place the OCCURS attribute in the segment declaration after the PARENT attribute. Consider the following record layout:

A   B   C1   C2   C1   C2

You have two occurrences of fields C1 and C2 for every one occurrence of fields A and B. Thus, to describe this file, you place fields A and B in the root segment, and fields C1 and C2 in the descendant segment.

You describe this file with the following Master File:

FILENAME=EXAMPLE1,SUFFIX=RMS,$
 GROUP=ONE   ,ALIAS=KEY   ,USAGE=A2   ,ACTUAL=A2   ,FIELDTYPE=I   ,$
  FIELDNAME=A    ,ALIAS=   ,USAGE=A2   ,ACTUAL=A2   ,$
  FIELDNAME=B    ,ALIAS=   ,USAGE=A1   ,ACTUAL=A1   ,$
 SEGNAME=TWO,PARENT=ONE,OCCURS=2,SEGTYPE=S0,$
  FIELDNAME=C1   ,ALIAS=   ,USAGE=I4   ,ACTUAL=I2   ,$
  FIELDNAME=C2   ,ALIAS=   ,USAGE=I4   ,ACTUAL=I2   ,$

Note: OCCURS is not supported for Write Access. However, if the fields occur a specific number of times, an alternate Master File can be built with the fields described that number of times (for example, PAYMENT_1, PAYMENT_2 if Payment occurs two times). Using the alternate Master, specific instances of the OCCURS can be referenced. If the OCCURS segments will not be referenced during the write, the alternate Master is not needed. However, the message (FOC1305) RMS Duplicate Record will display.

Top of page

Example: Describing Parallel and Nested Sets of OCCURS Segments

You can have several sets of repeating fields in your data structure. You describe each of these sets of fields as a separate segment in your Master File.

Sets of repeating fields can be divided into two basic types: parallel and nested. Parallel sets of repeating fields are unrelated (that is, they have no parent/child or logical relationship). Consider the following record layout:

A1   A2   B1   B2   B1   B2   C1   C2   C1   C2   C1   C2

In this example, fields B1 and B2 and fields C1 and C2 repeat within the record. The number of times that fields B1 and B2 occur is unrelated to the number of times fields C1 and C2 occur. Fields B1 and B2 and fields C1 and C2 are parallel sets of repeating fields. They should be described in the Master File as children of the same parent, the segment that contains fields A1 and A2. The following Master File illustrates this relationship:

FILENAME=EXAMPLE1, SUFFIX=RMS,$
 GROUP=ONE   ,ALIAS=KEY   ,USAGE=A2   ,ACTUAL=A2   ,FIELDTYPE=I   ,$
  FIELDNAME=A1,   ALIAS= ,   USAGE=A2,   ACTUAL=A2,   $
  FIELDNAME=A2,   ALIAS= ,   USAGE=A2,   ACTUAL=A2,   $
 SEGNAME=TWO, SEGTYPE=S0, PARENT=ONE,    OCCURS=2,    $
  FIELDNAME=B1,   ALIAS= ,   USAGE=A2,   ACTUAL=A2,   $
  FIELDNAME=B2,   ALIAS= ,   USAGE=A2,   ACTUAL=A2,   $
 SEGNAME=THREE, SEGTYPE=S0, PARENT=ONE,  OCCURS=3,    $
  FIELDNAME=C1,   ALIAS= ,   USAGE=A2,   ACTUAL=A2,   $
  FIELDNAME=C2,   ALIAS= ,   USAGE=A2,   ACTUAL=A2,   $

Nested sets of repeating fields are those whose occurrence in some way depends on one another. Consider the following data structure:

A1   A2   B1   B2   C1   C1   B1   B2   C1   C1   C1

In this example, field C1 occurs after fields B1 and B2 occur once. Field C1 occurs a varying number of times, as recorded by a counter field, B2. There will not be a set of occurrences of C1 unless C1 is preceded by an occurrence of fields B1 and B2. Fields B1, B2, and C1 are a nested set of repeating fields. The following Master File illustrates this relationship:

FILENAME=EXAMPLE2, SUFFIX=RMS,$
 GROUP=ONE   ,ALIAS=KEY   ,USAGE=A2   ,ACTUAL=A2   ,FIELDTYPE=I   ,$
  FIELDNAME=A1,   ALIAS= ,   USAGE=A2,   ACTUAL=A2,      $
  FIELDNAME=A2,   ALIAS= ,   USAGE=A2,   ACTUAL=A2,      $
 SEGNAME=TWO,      SEGTYPE=S0, PARENT=ONE, OCCURS=2,     $
  FIELDNAME=B1,   ALIAS= ,   USAGE=A2,   ACTUAL=A2,      $
  FIELDNAME=B2,   ALIAS= ,   USAGE=I6,   ACTUAL=I4,      $
 SEGNAME=THREE,    SEGTYPE=S0, PARENT=TWO, OCCURS=B2,    $
  FIELDNAME=C1,   ALIAS= ,   USAGE=A2,   ACTUAL=A2,      $

Since field C1 repeats with relation to fields B1 and B2, which repeat in relation to fields A1 and A2, field C1 is described as a separate, descendant segment of Segment TWO, which is in turn a descendant of Segment ONE.

The following data structure contains both nested and parallel sets of repeating fields:

A1 A2  B1  B2  C1  C1  C1  B1  B2  C1  C1  C1  C1  D1  D1  E1  E1  E1  E1

You describe this with the Master File that follows. The PARENT attribute is used to describe the logical relationship of the segments. Note that the assignment of the PARENT attribute shows you how the occurrences are nested:

FILENAME=EXAMPLE3,SUFFIX=RMS,$
 GROUP=ONE   ,ALIAS=KEY   ,USAGE=A2   ,ACTUAL=A2   ,FIELDTYPE=I   ,$
  FIELDNAME=A1   ,ALIAS=   ,USAGE=A2   ,ACTUAL=A2   ,   $
  FIELDNAME=A2   ,ALIAS=   ,USAGE=I4   ,ACTUAL=I1   ,   $
 SEGNAME=TWO,PARENT=ONE,OCCURS=2,SEGTYPE=S0,            $
  FIELDNAME=B1   ,ALIAS=   ,USAGE=A15  ,ACTUAL=A15  ,   $
  FIELDNAME=B2   ,ALIAS=   ,USAGE=I4   ,ACTUAL=I1   ,   $
 SEGNAME=THREE,PARENT=TWO,OCCURS=B2,SEGTYPE=S0,         $
  FIELDNAME=C1   ,ALIAS=   ,USAGE=A25  ,ACTUAL=A25  ,   $
 SEGNAME=FOUR,PARENT=ONE,OCCURS=A2,SEGTYPE=S0,          $
  FIELDNAME=D1   ,ALIAS=   ,USAGE=A15  ,ACTUAL=A15  ,   $
 SEGNAME=FIVE,PARENT=ONE,OCCURS=VARIABLE,SEGTYPE=S0,    $
  FIELDNAME=E1   ,ALIAS=   ,USAGE=A5   ,ACTUAL=A5   ,   $

Note:

Segments ONE, TWO, and THREE represent a nested group of repeating segments. Fields B1 and B2 occur a fixed number of times, so OCCURS equals 2. Field C1 occurs a certain number of times within each occurrence of fields B1 and B2. The number of times C1 occurs is determined by the value of B2, which is a counter. The value of B2 is 3 for the first occurrence of Segment TWO, and 4 for the second occurrence.
Segments FOUR and FIVE consist of fields that repeat independently within the parent segment. They have no relationship to each other or to Segment TWO except for the common parent, so they represent a parallel group of repeating segments.
As in the case of Segment THREE, the number of times Segment FOUR occurs is determined by a counter in its parent, A2. In this example, the value of A2 is 2.
The number of times Segment FIVE occurs is VARIABLE. The rest of the fields in the record (all those to the right of the first occurrence of E1) as occurrences of E1. To ensure that data in the record is interpreted correctly, a segment defined as OCCURS=VARIABLE must be at the end of the record. In a data structure diagram, it will be the right-most segment. There can only be one segment defined as OCCURS=VARIABLE for each parent.

Top of page

POSITION

The POSITION attribute is an optional attribute. It is used to describe a record in which non-repeating data follows embedded repeating data.

You describe the file as a multi-segment structure, made up of a parent segment and at least one child segment that contains the embedded repeating data. The parent segment is made up of whatever singly occurring fields are in the record, as well as an alphanumeric field (or fields) that indicates where the embedded repeating data appear in the record. The alphanumeric field is a placeholder that is the exact length of the combined embedded repeating data. For example, if you have four occurrences of an 8-character field, the length of the placeholder in the parent segment will be 32 characters.

The POSITION attribute is described in the child segment. It gives the name of the placeholder field in the parent segment.

The syntax is

POSITION = fieldname

where:

fieldname: Is the name of the field in the parent segment that defines the starting position of the multiply occurring fields.

Consider the following record layout:

A1   Q1   Q1   Q1   Q1   A2   A3   A4

In this example, field Q1 repeats four times in the middle of the record. When you describe this structure, you specify a field that occupies the position of the four Q1 fields in the record. You then assign the actual Q1 fields to a descendant, multiply occurring segment. The POSITION attribute, specified in the descendant segment, gives the name of the place holder field in the parent segment.

The Master File for this file would look like this:

FILENAME=EXAMPLE3,SUFFIX=RMS,$
 GROUP=ONE   ,ALIAS=KEY   ,USAGE=A2   ,ACTUAL=A2   ,FIELDTYPE=I   ,$
  FIELDNAME=A1     ,ALIAS=   ,USAGE=A2  ,ACTUAL=A2   ,$
  FIELDNAME=QFIL   ,ALIAS=   ,USAGE=A1   ,ACTUAL=A32   ,$
  FIELDNAME=A2     ,ALIAS=   ,USAGE=I2   ,ACTUAL=I2    ,$
  FIELDNAME=A3     ,ALIAS=   ,USAGE=A10  ,ACTUAL=A10   ,$
  FIELDNAME=A4     ,ALIAS=   ,USAGE=A15  ,ACTUAL=A15   ,$
 SEGNAME=TWO,SEGTYPE=S0,PARENT=ONE,POSITION=QFIL,OCCURS=4,$
  FIELDNAME=Q1     ,ALIAS=   ,USAGE=D8   ,ACTUAL=D8    ,$

If the total length of the multiple occurrences of the field(s) is greater than 256, you can use a filler field after the place holder field to make up the remaining length. This is because the format of a field cannot exceed 256 bytes.

This structure will only work if you have a fixed number of occurrences of the repeating field. This means that the OCCURS attribute of the descendant segment must be of the type OCCURS=n. The following will not work: OCCURS=fieldname or OCCURS=VARIABLE.

When a segment is coded with ...OCCURS=n, POSITION=fieldname, ..., all segments that follow using OCCURS=n or OCCURS=fieldname, must use the POSITION attribute to correctly map data.

Top of page

ORDER Field

In an OCCURS segment, the order of the data may be significant. For example, the numbers may represent monthly or quarterly data, but the record itself may not explicitly specify the month (or quarter) to which the data applies.

You can add a special ORDER field to your Master File to identify the individual occurrences of data uniquely within their parent segment. This is typically done to the screen by the occurrence number versus a field value (for example, the month is 12). The sequence number of each instance of the segment is automatically defined as a virtual field, and does not actually exist within the file.

The following syntax rules apply to the ORDER field:

It must be the last field described in an OCCURS segment. If you are using MAPVALUE, then MAPVALUE must be the last field preceded by the ORDER field.
The field name is arbitrary.
The ALIAS attribute must be ORDER.
The USAGE attribute must be In, with any appropriate edit options; "n" is a number from 1 to 9.
The ACTUAL attribute must be I4.

For example:

FIELD=ACT_MONTH, ALIAS=ORDER, USAGE=I2, ACTUAL=I4,$

Order values are assigned sequentially (1,2,3,...) and the order value is reset to 1 when a new instance of the parent segment is retrieved. The value is assigned prior to any selection tests that might accept or reject the record, and can be used in a screening condition. For example, to obtain data for the month of June, type:

SUM AMOUNT...
IF ORDER IS 6

Top of page

Example: Describing Repeating Embedded Data With Record Type Indicators

If a file contains records that have repeating embedded data, the OCCURS attribute is used to describe a separate segment for the repeating fields. In some files, however, the repeating fields themselves must be identified according to a record type indicator. Suppose you want to describe a file that, schematically, looks like the following:

A  Rectype B C     Rectype  B C
A  Rectype D       Rectype  D

You would 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.

This is its Master File:

FILE=ABCD, SUFFIX=RMS,$
 GROUP=ONE            ,ALIAS=KEY      ,ACTUAL=A2   ,USAGE=A2  ,$
  FIELDNAME=A            ,ALIAS=      ,USAGE=A2   ,ACTUAL=A2  ,$
 SEGNAME=BC_SEG, SEGTYPE=S0, PARENT=ONE, OCCURS=2,$
  FIELDNAME=RECTYPE      ,ALIAS=1     ,USAGE=I2    ,ACTUAL=I2   ,$
  FIELDNAME=B            ,ALIAS=      ,USAGE=A5    ,ACTUAL=A5   ,$
  FIELDNAME=C            ,ALIAS=      ,USAGE=A5    ,ACTUAL=A5   ,$
 SEGNAME=D_SEG, SEGTYPE=S0, PARENT=ONE, OCCURS=2,$
  FIELDNAME=RECTYPE      ,ALIAS=2     ,USAGE=I2    ,ACTUAL=I2   ,$
  FIELDNAME=D            ,ALIAS=      ,USAGE=A15   ,ACTUAL=A15  ,$

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

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

Since the OCCURS segment depends on the RECTYPE indicator for its evaluation, the RECTYPE must appear at the start of each OCCURS segment. This allows very complex files to be described, including those with nested and parallel repeating groups that depend on RECTYPEs. For example:

A   Rectype B C   Rectype D   Rectype D   Rectype E   Rectype E

In this case, B/C, and D represent a nested repeating group, and E represents a parallel repeating group.

Top of page

Syntax: How to Describe Repeating Groups Depending on a Preceding Record Type Indicator Using MAPFIELD/MAPVALUE

MAPFIELD is assigned as the ALIAS of the field that will be the record type indicator. You can give this field any name; it is otherwise described according to the usual syntax:

FIELD=name, ALIAS=MAPFIELD, USAGE=usage, ACTUAL=actual,$

The descendant segments, whose values depend on the value of the MAPFIELD, are described as separate segments, one for each possible value of MAPFIELD, and all descending from the segment that has the MAPFIELD. A special field, MAPVALUE, is described as the last field in these descendant segments. If an ORDER field is chosen, it must be used before the MAPVALUE. The actual MAPFIELD value is supplied as the MAPVALUE ALIAS.

The syntax is

FIELDNAME=MAPVALUE,ALIAS=alias,USAGE=usage{Pn},ACTUAL={Pn},
  ACCEPT=list/range],$

where:

MAPVALUE

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

alias

Is the primary MAPFIELD value that identifies the segment. 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 a list of one or more lines of specific 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 an item in 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=MAPVALUE, 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 either value in 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.

In some cases, the record type indicates what kind of repeating data will follow. Schematically, the records would look like the following:

A  B  Recordtype  (1)   C D   C D   C D
A  B  Recordtype  (2)   E E

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 type indicator. The second record has a different record type indicator and contains a different repeating group, this time for E.

Since the OCCURS segments are identified by the record type indicator, rather than the parent A/B segment, you can use the keyword MAPFIELD. MAPFIELD identifies a field like RECTYPE, but, since the OCCURS segments will each have specific values for MAPFIELD, its value is associated with each OCCURS segment by means of a complementary field named MAPVALUE.

The Master File for this file would look like the following:

FILENAME=EXAMPLE,SUFFIX=RMS,$
GROUP=ONE           ,ALIAS=KEY       ,ACTUAL=A2     ,USAGE=A2  ,$
FIELDNAME=A         ,ALIAS=          ,USAGE=A2      ,ACTUAL=A2,$
FIELDNAME=B         ,ALIAS=          ,USAGE=A10     ,ACTUAL=A10,$
FIELDNAME=FLAG      ,ALIAS= MAPFIELD ,USAGE=A1      ,ACTUAL=A1,$
SEGNAME=TWO,SEGTYPE=S0,PARENT=ONE,OCCURS=VARIABLE,$
FIELDNAME=C         ,ALIAS=          ,USAGE=A5      ,ACTUAL=A5,$
FIELDNAME=D         ,ALIAS=          ,USAGE=A7      ,ACTUAL=A7,$
FIELDNAME=MAPVALUE  ,ALIAS=1         ,USAGE=A1      ,ACTUAL=A1,$
SEGNAME=THREE,SEGTYPE=S0,PARENT=ONE,OCCURS=VARIABLE,$
FIELDNAME=E         ,ALIAS=          ,USAGE=D12.2   ,ACTUAL=D8,$
FIELDNAME=MAPVALUE  ,ALIAS=2         ,USAGE=A1      ,ACTUAL=A1,$