Mapping Adabas Files With Variable-Length Records and Repeating Fields

In this section:

The OCCURS segment attribute is used by the server to describe MU and PE field types in a Master File.

Consider the sample Adabas file VEHICLES. The FDT for the VEHICLES file is shown below.

*********************************
* FILE     2 (VEHICLES        ) *
*********************************
FIELD DESCRIPTION TABLE
      I      I        I        I              I                   I
LEVEL I NAME I LENGTH I FORMAT I  OPTIONS     I  PARENT OF        I
      I      I        I        I              I                   I
------I------I--------I--------I--------------I-------------------I
      I      I        I        I              I                   I
  1   I  AA  I   15   I    A   I DE,UQ,NU     I                   I
  1   I  AB  I    4   I    F   I FI           I                   I
  1   I  AC  I    8   I    A   I DE           I                   I
  1   I  CD  I        I        I              I                   I
  2   I  AD  I   20   I    A   I DE,NU        I SUPERDE           I
  2   I  AE  I   20   I    A   I NU           I                   I
  2   I  AF  I   10   I    A   I DE,NU        I                   I
  1   I  AG  I    2   I    U   I NU           I SUPERDE           I
  1   I  AH  I    1   I    A   I DE,FI        I                   I
  1   I  AI  I    1   I    A   I FI           I                   I
  1   I  AJ  I    6   I    U   I NU           I SUPERDE           I
  1   I  AK  I        I        I              I                   I
  2   I  AL  I    3   I    A   I NU           I                   I
  2   I  AM  I    4   I    P   I MU,NU        I                   I
      I      I        I        I              I                   I
-------------------------------------------------------------------
SPECIAL DESCRIPTOR TABLE
       I      I        I        I                I                I
 TYPE  I NAME I LENGTH I FORMAT I    OPTIONS     I   STRUCTURE    I
       I      I        I        I                I                I
-------I------I--------I--------I----------------I----------------I
       I      I        I                         I                I
 SUPER I  AN  I    4   I    B   I DE,NU          I AJ (  5 -   6) I
       I      I        I        I                I AJ (  3 -   4) I
 SUPER I  AO  I   22   I    A   I DE,NU          I AG (  1 -   2) I
       I      I        I        I                I AD (  1 -  20) I
       I      I        I        I                I                I
-------------------------------------------------------------------

The MU field, MAINT_COST, is a field in VEHICLES. It is allocated to a new segment, AM0101, required by the adapter, as shown in the Master File for a partial view of the VEHICLES file, illustrating the use of OCCURS=occursname:

$$$ CREATED ON 12/10/97 AT 10.17.27 BY PMSMJB
FILENAME=ADACAR,SUFFIX=ADBSINX,$
 
$ ADABAS FILE = VEHICLES-FILE                     DICTIONARY = 6
SEGNAME=S01     ,SEGTYPE=S,$
 
 FIELD=REG_NUM                    ,ALIAS=AA      ,A15 ,A15  ,INDEX=I,$
 FIELD=CHASSIS_NUM                ,ALIAS=AB      ,I9  ,I4   ,$
 FIELD=PERSONNEL_ID               ,ALIAS=AC      ,A8  ,A8   ,INDEX=I,$
 FIELD=CLASS                      ,ALIAS=AH      ,A1  ,A1   ,INDEX=I,$
 FIELD=LEASE_PUR                  ,ALIAS=AI      ,A1  ,A1   ,$
 FIELD=DATE_ACQ                   ,ALIAS=AJ      ,P6  ,Z6   ,$
$GRMU=CAR_MAINTENANCE             ,ALIAS=AK      ,A11 ,A7   ,$
  FIELD=CURR_CODE                 ,ALIAS=AL      ,A3  ,A3   ,$
  FIELD=MAINT_COST_CNT            ,ALIAS=AMC     ,I4  ,I2   ,$
 FIELD=DAT_ACQ_DESC               ,ALIAS=AN      ,A4  ,A4   ,INDEX=I,$
 GROUP=MODEL_YEAR_MAKE            ,ALIAS=AO      ,A28 ,A22  ,INDEX=I,$
  FIELD=YEAR_S02                  ,ALIAS=AG      ,P2  ,Z2   ,$
  FIELD=MAKE_S02                  ,ALIAS=AD      ,A20 ,A20  ,INDEX=I,$
  
SEGNAME=AM0101 ,SEGTYPE=S,PARENT=S01  ,OCCURS=AMC,$  MAX= 60
 FIELD=MAINT_COST                 ,ALIAS=AM      ,P7  ,P4  ,$
 FIELD=AM0101_OCC                 ,ALIAS=ORDER   ,I4  ,I2  ,$

In the original segment, the MAINT_COST_CNT (ALIAS=AMC) field contains the total number of occurrences of the MAINT_COST field. The new segment, AM0101, contains the MAINT_COST data field and the newly created AM0101_OCC field. The AM0101_OCC field contains the position of each occurrence.

This example includes the group field called CAR_MAINTENANCE, which contains the MU field, MAINT_COST. You cannot report on a group with an unknown length. However, the component fields can be referenced for reporting purposes.

Note: The Create Synonym facility creates the new segment, AM0101, for you. Otherwise, you must create the new segment using the OCCURS segment attribute.

The following is the Access File for the VEHICLES file:

$$$ CREATED ON 12/10/03 AT 10.17.27 BY PMSMJB
$$$ FILENAME=ADACAR,SUFFIX=ADBSINX,$
RELEASE=6,OPEN=YES,$
 
$ ADABAS FILE = VEHICLES-FILE                     DICTIONARY = 6
SEGNAM=S01   ,ACCESS=ADBS,FILENO=002,
              CALLTYPE=RL,SEQFIELD=PERSONNEL_ID,$
 FIELD=DAT_ACQ_DESC                         ,TYPE=NOP,$
 FIELD=MODEL_YEAR_MAKE                      ,TYPE=SPR,$
  FIELD=YEAR_S02                            ,TYPE=   ,NU=YES,$
  FIELD=MAKE_S02                            ,TYPE=DSC,NU=YES,$
SEGNAM=AM0101,ACCESS=MU  ,FILENO=002,$ MAINT_COST

A new segment is created for the MU field. Note that for this new segment, ACCESS=MU.

Here is an example of the counter fields. The AMC field contains the total count of occurrences, the AM field contains the actual data, and the ORDER field contains the position of each occurrence.

     (AMC)          (AM)        (ORDER)
MAINT_COST_CNT   MAINT_COST   AM0101_OCC
--------------   ----------   ----------
             1          520            1
----------------------------------------
             1          210            1
----------------------------------------
             4           44            1
             4          322            2
             4           66            3
             4          188            4
----------------------------------------
             6          324            1
             6         1103            2
             6          566            3
             6          755            4
             6          988            5
             6         1899            6
----------------------------------------
             2          344            1
             2          500            2

In some cases, the ORDER field may describe the months of the year (1 to 12). If all occurrences for the month of June are needed, for example, you would print data in which the ORDER field is equal to 6 (for June).

Using the preceding sample data, here is an example of how to use the ORDER field. This request always selects the sixth occurrence of maintenance costs:

TABLE FILE VEHICLES
PRINT MAINT_COST 
WHERE AM0101_OCC EQ 6 
END
 
MAINT_COST
----------
      1899

Using the same data, this request always selects the second occurrence of maintenance costs:

TABLE FILE VEHICLES
PRINT MAINT_COST 
WHERE AM0101_OCC EQ 2 
END
 
MAINT_COST
----------
       322
      1103
       500

Top of page

x
Describing Multi-Value Fields and Periodic Groups With the OCCURS Attribute

The OCCURS attribute is a segment attribute used to describe portions of records containing a multi-value field or a periodic group. When describing Adabas files, the OCCURS attribute may be equal to the field name or (another option) to the two-character internal Adabas name appended with the letter C.

Records with repeating fields are defined in the Master File by describing the singly occurring fields in the parent segment, and the multiply occurring fields or groups in their own subordinate segment. The OCCURS attribute appears in the declaration for the subordinate segments.

The syntax is

OCCURS=occursname ,$

where:

occursname

Indicates a data field in the parent segment that contains the number of occurrences of the descendant segment. Its value is derived from the two-character internal Adabas name (ALIAS attribute in the Master File) appended with the letter C.

The following is an example of the VEHICLES Master File, containing an MU segment with the counter field in the parent segment:

FILENAME=VEHICLES,SUFFIX=ADBSINX,$
  SEGNAME=S01     ,SEGTYPE=S,$
   FIELD=REG_NUM          ,ALIAS=AA         ,A15    ,A15  , INDEX=I,$
   FIELD=CHASSIS_NUM      ,ALIAS=AB         ,I9     ,I4   ,$
   FIELD=PERSONNEL_ID     ,ALIAS=AC         ,A8     ,A8   , INDEX=I,$
   FIELD=CLASS            ,ALIAS=AH         ,A1     ,A1   , INDEX=I,$
   FIELD=LEASE_PUR        ,ALIAS=AI         ,A1     ,A1   ,$
   FIELD=CURR_CODE        ,ALIAS=AL         ,A3     ,A3   ,$
   FIELD=MAINT_COST_CNT   ,ALIAS=AMC        ,I4     ,I2   ,$
   GROUP=MODEL_YEAR_MAKE  ,ALIAS=AO         ,A28    ,A22  , INDEX=I,$
    FIELD=YEAR            ,ALIAS=AG         ,P2     ,Z2   ,$
    FIELD=MAKE            ,ALIAS=AD         ,A20    ,A20  , INDEX=I,$ 
SEGNAME=AM0101  ,SEGTYPE=S ,PARENT=S01  ,OCCURS=AMC,$
   FIELD=MAINT_COST       ,ALIAS=AM         ,P7     ,P4   ,$
   FIELD=AM0101_OCC       ,ALIAS=ORDER      ,I4     ,I2   ,$

MAINT_COST is the MU field. It is allocated to the newly created segment, AM0101. The counter field, MAINT_COST_CNT, is located in the parent segment. The new segment, AM0101, uses this counter field to determine the number of occurrences of the MAINT_COST field (OCCURS=AMC).

Notice that the fields MAINT_COST_CNT and AM0101_OCC (ALIAS=ORDER) have USAGE=I4 and ACTUAL=I2. These are the required values for the USAGE and ACTUAL attributes of the counter field and the ORDER field.

The adapter builds the PE segment in the same way. However, the component fields within the PE group are defined in the new segment.

The following is a view of the EMPLOYEES Master File, containing a PE group:

FILENAME=EMPFILE1,SUFFIX=ADBSINX,$
 
SEGNAME=S01     ,SEGTYPE=S,$
 FIELD=PERSONNEL_ID               ,ALIAS=AA       ,A8    ,A8  ,INDEX=I,$
  FIELD=FIRST_NAME                ,ALIAS=AC       ,A20   ,A20 ,$
  FIELD=NAME                      ,ALIAS=AE       ,A20   ,A20 ,INDEX=I,$ 
FIELD= LEAVE_BOOKED_CNT           ,ALIAS=AWC      ,I4    ,I2  ,$ 
SEGNAME=AW0401   ,SEGTYPE=S,PARENT=S01   ,OCCURS=AWC,$
 GROUP=LEAVE_BOOKED               ,ALIAS=AW       ,A16   ,A12 ,$
  FIELD=LEAVE_START               ,ALIAS=AX       ,P6    ,Z6  ,$
  FIELD=LEAVE_END                 ,ALIAS=AY       ,P6    ,Z6  ,$
 FIELD=AW0401_OCC                 ,ALIAS=ORDER    ,I4    ,I2  ,$

LEAVE_BOOKED is the PE group. It is allocated to the newly created segment, AW0401. The counter field, LEAVE_BOOKED_CNT, is located in the parent segment. The new segment, AW0401, uses this counter field to determine the number of occurrences of the LEAVE_BOOKED group (OCCURS=AWC).

The counter field, LEAVE_BOOKED_CNT, and the ORDER field, AW0401_OCC, require values of I4 for the USAGE attribute and I2 for the ACTUAL attribute.

The number of occurrences is limited by the original definition of the file to Adabas.

To retrieve the appropriate occurrence of a repeating field in a report request, specify the ORDER field in your Master File. See Specifying OCCURS Segment Sequence: The ORDER Field for details.

For detailed information about defining MU fields and PE groups in the Access File, see Segment Attributes in Access Files.


Top of page

x
Describing Multi-Value Fields Within Periodic Groups

This topic describes how to specify multi-value fields within periodic groups in the Master File. Define each multi-value field contained in the periodic group segment as a separate descendant segment of the periodic group.

A periodic group containing a multi-value field is defined as two separate segments.

All fields must be defined in the order in which they appear in the FDT.

Consider the EMPLOYEES file. It has a periodic group called INCOME, which contains one multi-value field, BONUS. Each counter field (for example, AQC) must be in its appropriate parent segment. The INCOME_CNT field is in the parent segment for the periodic group, INCOME. The BONUS_CNT field is in the parent segment for the MU field, BONUS. Any repeating fields within the periodic group are defined in the AQ0201 segment. Their corresponding Adabas two-character field names are the values for ALIAS with the appropriate values for USAGE and ACTUAL.

Here is the view of the Master File for this structure:

 FILENAME=EMPFILE1,SUFFIX=ADBSINX,$
   SEGNAME=S01     ,SEGTYPE=S,$
    FIELD=PERSONNEL_ID      ,ALIAS=AA        ,A8    ,A8  ,INDEX=I,$
     FIELD=FIRST_NAME       ,ALIAS=AC        ,A20   ,A20 ,$
     FIELD=NAME             ,ALIAS=AE        ,A20   ,A20 ,INDEX=I,$ 
1. FIELD=INCOME_CNT        ,ALIAS=AQC       ,I4    ,I2  ,$  
1. SEGNAME=AQ0201  ,SEGTYPE=S,PARENT=S01   ,OCCURS=AQC,$ 
1. $PEMU=INCOME             ,ALIAS=AQ        ,A19   ,A13 ,$  
1.    FIELD=CURR_CODE        ,ALIAS=AR        ,A3    ,A3  ,$ 
1.    FIELD=SALARY           ,ALIAS=AS        ,P9    ,P5  ,$ 
2.   FIELD=BONUS_CNT        ,ALIAS=ATC       ,I4    ,I2  ,$ 
1. FIELD=AQ0201_OCC        ,ALIAS=ORDER     ,I4    ,I2  ,$
2. SEGNAME=AT0301  ,SEGTYPE=S,PARENT=AQ0201,OCCURS=ATC,$ 
2.  FIELD=BONUS             ,ALIAS=AT        ,P9    ,P5  ,$ 
2.  FIELD=AT0301_OCC        ,ALIAS=ORDER     ,I4    ,I2  ,$
  1. PE fields.

    This example includes the periodic group called INCOME, which contains the MU field, BONUS. Create Synonym comments out the group field with $PEMU because its length is variable (depending on the number of occurrences of the MU field). The server cannot report on a group with an unknown length. However, the component fields can be referenced for reporting purposes.

  2. MU fields.

    BONUS_CNT (ALIAS=ATC) is the counter field. It is defined in the PE segment and tells us the number of occurrences for that field. Used in the MU segment, it indicates how many times this repeating field occurs, for example, OCCURS=ATC. Defined in the parent segment, the counter field is used by the child segment to tell us how many occurrences to expect.

    Any periodic group segment must be described in its entirety. This description has two requirements: each field of the periodic group must have a field declaration in the periodic group segment, and each field in the group must be described in the order in which it appears in the Adabas FDT.


Top of page

x
Specifying OCCURS Segment Sequence: The ORDER Field

There may be occasions with OCCURS segment processing when the order of the data is significant. For example, the field values may represent monthly or quarterly data, but the record itself may not explicitly specify the month (or quarter) to which the data applies. The ORDER field maintains the sequence number for each multiply occurring instance.

The order of the occurrences of a multi-value field or periodic group also has some significance in your application. For example, if a periodic group contains 12 occurrences, each occurrence could correspond to one month of the year. The first occurrence represents January, the second February, and so on through to December.

To use the ORDER option, you must include an additional field in your Master File with an ALIAS of ORDER. This option instructs the server to determine the sequence number of fields in an OCCURS segment. The server automatically supplies a value for the new field that defines the sequence number of each repeating group. The ORDER field does not represent an existing Adabas field; it is used only for internal processing.

The syntax rules for the ORDER field are:

Each field with the ALIAS value ORDER tracks the order of occurrence of the preceding fields in the segment. Therefore, in the sample Master File in Describing Multi-Value Fields Within Periodic Groups, AT0301_OCC maintains the sequence of BONUS occurrences.

An ORDER field may be decoded into a meaningful value in a DEFINE.


WebFOCUS