Master Files for IDMS/DB

In this section:

This section explains the rules for making an IDMS/DB data source accessible to the server using the Master File. The Access File is an extension of Master File syntax that provides information to map DML record types and LRF-based records, including record and area names and, where needed, set or field name information.

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

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


Top of page

x
File Attributes

How to:

Master Files begin with a file declaration that names the file and describes the type of data source; in this case, an IDMS/DB data source. The file declaration has two attributes, FILENAME and SUFFIX.



x
Syntax: How to Identify a Master File
FILE[NAME]=name, SUFFIX=IDMSR [,$]

where:

name

Is any 1- to 8-character name. On z/OS, the Master File is the member name within the PDS allocated to DDNAME MASTER.

IDMSR

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


Top of page

x
Segment Attributes

In this section:

Each IDMS/DB segment described in a Master File requires a segment declaration that consists of at least two attributes, SEGNAME and SEGTYPE.



x
SEGNAME

The SEGNAME value assigned to DML record types and LRF records are suggestive names -- not necessarily the IDMS/DB record names. The segment name may be a maximum of eight characters and must be unique within a given Master File. If the same IDMS/DB record type is viewed in two different contexts (for example, a loop structure), two segment declarations are required.



x
SEGTYPE

The SEGTYPE keyword indicates whether a segment occurs once (SEGTYPE=U) or many times (SEGTYPE=S). It is used as follows:



x
PARENT

The PARENT keyword is required for descendant segment declarations. The PARENT value names the descendant's parent segment. This keyword is not specified for the root declaration.



x
CRFILE (Cross-referenced File)

The CRFILE keyword is specified only for segments that are described remotely in another Master File. The field descriptions for these segments are, in effect, copied into the Master File at execution time. Remote descriptions are discussed in Remote Descriptions.



x
OCCURS and POSITION

The OCCURS and POSITION attributes are specified only when the segment corresponds to an intra-record structure, such as a COBOL OCCURS or OCCURS DEPENDING clause. These keywords are described in detail in Intra-record Structures: OCCURS Segment.


Top of page

x
Field Attributes

In this section:

Each segment consists of one or more fields. The Master File need not describe all fields from a segment. The attributes are:

To describe a field in the Master File, you must specify the primary attributes FIELDNAME, ALIAS, USAGE, and ACTUAL. These attributes are discussed in this section. Note that the adapter does not support the MISSING attribute.



x
FIELDNAME

The FIELDNAME keyword may contain any name, not necessarily an IDMS/DB field name. It can be a maximum of 48 characters. The name that you assign must be unique, because in the server, data is referenced through field names. If the same IDMS/DB record type viewed in different contexts underlies two or more segments, different field names must be specified in separate segment descriptions.

Due to the record-oriented nature of IDMS/DB, the fields are described for each segment in the same order as they appear in the subschema record area. Bytes skipped for field alignment or for fields you want to omit must be described as dummy fields of the appropriate length.

For example, a 1-byte alphanumeric field is followed by a double-precision floating point field:

SEGNAME=EMPSTATUS,$
  FIELD=STATUS_CODE,SCODE ,A1,A1,$
  FIELD=           ,      ,A7,A7,$
  FIELD=GROSS_SALES,GSALES,D12.2,D8,$

The same name can be used for all dummy fields; in the example above, blanks are used.

You do not need to describe all fields of the record type or LRF record; only an initial set, starting with the first field and continuing up to the last field of interest. For variable-length record types, treat the fixed-length portion as one segment and the variable portion as another segment, as described with the OCCURS attribute. For information about OCCURS segments, see Intra-record Structures: OCCURS Segment.



x
Syntax: How to Describe a Field in the Master File
FIELD[NAME]=field,[ALIAS=]alias,[USAGE=]display,[ACTUAL=]format ,$

where:

field

Is a 1- to 48-character field name.

alias

The ALIAS keyword is used for certain fields which require specific ALIAS values.

display

Is the display format for the field.

format

Is the definition of the IDMS/DB 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=, USAGE=A2, ACTUAL=A2,$ 
FIELD = YEAR, ,A2, A2,$


x
ALIAS

The ALIAS keyword is used for certain fields which require specific ALIAS values:

The following is an example of a filler field in a segment that describes an LRF record. Suppose a record called JOB-EMPOSITION is defined to the IDMS/DB subschema with seven fields: the first three fields are derived from a physical (DML) record type called JOB; the last four fields, from the EMPOSITION physical record type. The Master File syntax for this LRF record looks like this:

FILENAME=JOBMAST, SUFFIX=IDMSR,$
  SEGNAME=JOBEMP, SEGTYPE=S,$
    FIELDNAME=JOBID       ,ALIAS=         ,USAGE=A4   ,ACTUAL=A4  ,$
    FIELDNAME=TITLE       ,ALIAS=         ,USAGE=A20  ,ACTUAL=A20 ,$
    FIELDNAME=DESCRIPTN   ,ALIAS=CMTS.END ,USAGE=A120 ,ACTUAL=A120,$
    FIELDNAME=START_DTE   ,ALIAS=         ,USAGE=A6YMD,ACTUAL=A6  ,$
    FIELDNAME=FINISH_DTE  ,ALIAS=         ,USAGE=A6YMD,ACTUAL=A6  ,$
    FIELDNAME=SALARY_GRADE,ALIAS=         ,USAGE=P4   ,ACTUAL=Z2  ,$
    FIELDNAME=SALARY      ,ALIAS=         ,USAGE=P10.2,ACTUAL=P5  ,$
    FIELDNAME=            ,ALIAS=FILL.END ,USAGE=A1   ,ACTUAL=A8  ,$

In this example, the filler field corresponds to the last field of the EMPOSITION record type, because LRF records must lie on a double-word boundary. The IDMS/DB filler field is stored to make the record length a multiple of 8. IDMS/DB filler fields on physical record types underlying LRF views must become filler fields. These filler fields can have any field name or contain a blank; its ALIAS must include the .END suffix. Since the JOB record type is 144 bytes (total of ACTUAL formats), it does not need a filler; the last field DESCRIPTN only requires an alias with an .END suffix.



x
USAGE

Master Files require you to specify field formats and lengths for USAGE and ACTUAL parameters.

The USAGE and ACTUAL keywords describe the data format of the field. The USAGE parameter defines the field length for the fields. Allow for the maximum possible number of characters or digits including decimal points. You may include valid edit options without increasing the length size.

Note: For network record types, the USAGE and ACTUAL formats of zoned CALC and zoned index fields must be described as alphanumeric (A).



x
ACTUAL

The ACTUAL parameter defines the field length for COBOL fields found in the IDMS/DB file. The number of internal storage bytes used by COBOL determines the actual length of the field for these formats:

Alphanumeric (A)

Equals the number of characters described in the PICTURE clause.

Zoned decimal (Z)

Equals the number of characters described in the PICTURE clause.

Integer (I)

Equals 2 or 4, corresponding to decimal lengths of 1-4 or 5-9 in the PICTURE clause.

Floating-point (F)

Equals 4 bytes.

Double-precision (D)

Equals 8 bytes.

Packed decimal (P)

Equals (number of PICTURE digits / 2) + 1; excluding sign (S) or implied decimal (V).

Use the following chart as a guide for describing ACTUAL formats:

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

Note:

  • For COMP-1 and COMP-2, allow for the maximum possible digits.
  • For COBOL DISPLAY fields with zoned decimal, server formats must be packed (P).
  • For COMP-1 and COMP-2, PICTURE clauses are not permitted for internal floating-point formats (F and D).



x
GROUP Fields

The GROUP keyword identifies a set of fields following it with a single name. This GROUP name is any unique name up to 48 characters in length. Its usage is similar to that of a COBOL group name. Generally, this attribute is used for IDMS/DB indexed or CALC fields.

Note:

For example, a GROUP field called EMP_NAME is composed of two fields, FIRST_NAME and LAST_NAME. Notice the USAGE and ACTUAL formats:

GROUP=EMP_NAME    ,ALIAS=  ,USAGE=A25  ,ACTUAL=A25 ,$
  FIELD=FIRST_NAME,ALIAS=  ,USAGE=A10  ,ACTUAL=A10 ,$
  FIELD=LAST_NAME ,ALIAS=  ,USAGE=A15  ,ACTUAL=A15 ,$

The FIELDTYPE keyword identifies indexed fields, both SPF and Integrated, on network record types. Omit it for LRF records.



x
IDMS/DB Database Key

The database key of a network record type corresponding to a segment can optionally be described as the last field in the segment. To specify a database key, use the following values:

Keyword

Description

FIELDNAME

Is any unique key. It can be a maximum of 48 characters.

ALIAS

Value is DBKEY.

USAGE

Value is I10.

ACTUAL

Value is I4.

The database key is used to select records from entry segments when screening on particular IDMS/DB values in the user request.



x
Remote Descriptions

SEGTYPEs KLU and KL specify unique and non-unique segments for which the aggregate fields are remotely described in another Master File. In other words, a KLU or KL segment contains no field information; its fields are fully defined in another Master File. The CRFILE keyword specifies the source or remote Master File. At execution time, the remote field descriptions are, in effect, copied into the current Master File.

Generally, KLU and KL segment types are used when several Master Files are constructed for the same IDMS/DB subschema. They save typing and maintenance effort. Use KLU if the underlying segment is unique (U); KL if the underlying segment is non-unique (S). Remote descriptions have no logical implications regarding parent/descendant relationships, nor do they impact their implementation.

To specify a remote description, you must give the KLU or KL segment the same name as the source segment in the remote Master File to ensure the proper use of field descriptions. The source file is specified as the CRFILE value. For example:

SEGMENT=SALES,PARENT=DEPT,SEGTYPE=KL,CRFILE=RECORDS,$

This segment declaration indicates that the field descriptions for the SALES segment are obtained from the SALES segment in the RECORDS Master File. The SEGTYPE for the SALES segment in the RECORDS Master File cannot be KL or KLU; only U or S. Only field names and their attributes from the source file are used; original segment attributes are not. The source file does not have to be a file description as long as it describes the named segment.


Top of page

x
Intra-record Structures: OCCURS Segment

A common record structure is one where a field or group of adjacent fields is repeated in the same record type. In COBOL and PL/I syntax, repeating intra-record structures are defined through an OCCURS clause. The server equivalent of an OCCURS clause is an OCCURS segment.

For example, the OFFICE record type contains the field OFFICE-PHONE that occurs three times. The corresponding OFFICE segment can list three separate fields with different field names, or alternately OFFICE-PHONE can be described in a separate descendant OCCURS segment. Using the OCCURS method, each office phone is referenced by a single name (see the Master File for EMPSS01).

The diagram below depicts the non-OCCURS method and the OCCURS method.

OCCURS segments have two attributes or keywords: ORDER and POSITION. The POSITION keyword directs the server to OCCURS segments when non-repeating fields exist between repeating fields. The ORDER keyword creates a fictitious count field that may be decoded.


Top of page

x
Describing the Repeating Group to the Server

In this section:

Any fixed or variable-length record type described in COBOL can be mapped into a server hierarchy using OCCURS segments. A simple OCCURS segment is a descendant of the parent segment which contains non-repeating fields found in the IDMS/DB record type. You must specify the OCCURS keyword on the descendant segment declaration that describes the repeating group. Like the COBOL OCCURS clause, the value of this keyword may be a numeric constant or a field name. The numeric constant indicates a fixed number of repetitions; a field name indicates a count field in the parent segment that maintains a count of the number of occurrences.

OCCURS segments also describe parallel and nested intra-record hierarchical structures. Parallel sets of repeating groups are described as multiple descendant segments of the same parent. In a nested structure, where a repeating group contains another repeating group, one OCCURS segment is the parent of another. Fixed and variable OCCURS segments can be intermixed in any order.

The restrictions for OCCURS segments are as follows:

From the server standpoint, OCCURS segments are indistinguishable from other segments. The server processes them, if referenced, in the usual top-to-bottom, left-to-right retrieval order.

For example, consider this COBOL budget record type:

01  BUDGET-RCD.
02  ACCOUNT           PIC XXX.
02  ACTUAL-COUNT      PIC 99.
02  PLANNED-AMT       PIC 9(9) OCCURS 12 TIMES.
02  ACTUAL-AMT        PIC 9(9) OCCURS 12 TIMES
                      DEPENDING ON ACTUAL-COUNT.

The equivalent Master File is:

SEGMENT=BUDGET,SEGTYPE=S,$
   FIELD=ACCOUNT      ,ALIAS=   ,USAGE=A3  ,ACTUAL=A3       ,$
   FIELD=ACTUAL_COUNT ,ALIAS=   ,USAGE=P4  ,ACTUAL=Z2       ,$
SEGMENT=PLANNED ,PARENT=BUDGET,SEGTYPE=S,OCCURS=12          ,$
   FIELD=PLANNED_AMT  ,ALIAS=   ,USAGE=P12 ,ACTUAL=Z9       ,$
SEGMENT=REAL_AMT,PARENT=BUDGET,SEGTYPE=S,OCCURS=ACTUAL_COUNT,$
   FIELD=ACTUAL_AMT   ,ALIAS=   ,USAGE=P12 ,ACTUAL=Z9       ,$

The mapping principle is very simple: the non-repeating field in the record type is described in one parent segment, and the parallel COBOL OCCURS structures are made into descendant OCCURS segments. The OCCURS keyword on the descendant segments specifies either a number (fixed occurrences) or a count field (variable occurrences). In this case, the count field ACTUAL_COUNT is located in the immediate parent segment called BUDGET and is specified on the REAL_AMT descendant segment.

The following is a diagram for this Master File example:

If the PLANNED or REAL_AMT segments had repeating structures, they would in turn be parents of OCCURS segments defined by the same principles. The BUDGET segment could have other non-OCCURS descendants. The PLANNED and REAL_AMT segments might have CALC-based or index-based descendants. However, set-based descendants of this record type would be tied to the BUDGET segment, not to the PLANNED or REAL_AMT segments.



x
POSITION

OCCURS segments are defined in the same order as they appear in the actual record type. In some cases, COBOL OCCURS clauses are separated by non-repeating fields. The POSITION keyword in a Master File indicates that the repeating fields are located in the middle of non-repeating fields.

The POSITION attribute can only be used for a repeating group with a fixed number of occurrences. This means that the OCCURS attribute of the descendant segment must equal a numeric constant and not a count field.

Suppose the previous COBOL record type looked like this:

01  BUDGET-RCD.
02  ACCOUNT         PIC XXX.
02  PLANNED-AMT     PIC 9(9) OCCURS 12 TIMES.
02  ACTUAL-COUNT    PIC 99.
02  ACTUAL-AMT      PIC 9(9) OCCURS 12 TIMES
                    DEPENDING ON ACTUAL-COUNT.

Here, the two repeating structures PLANNED-AMT and ACTUAL-AMT are separated by the non-repeating field ACTUAL-COUNT, which clearly belongs to the BUDGET segment. You must indicate in the Master File that the first occurrence of the PLANNED segment will not immediately follow the ACCOUNT field in the BUDGET segment (the PLANNED-AMT field is described in a separate descendant segment). The POSITION keyword accomplishes this task by directing the server to the descendant segment named PLANNED.

The corresponding Master File looks like this:

SEGMENT=BUDGET,SEGTYPE=S,$
  FIELD=ACCOUNT      ,ALIAS=   ,USAGE=A3   ,ACTUAL=A3        ,$
  FIELD=PLANNED_SEG1 ,ALIAS=   ,USAGE=A108 ,ACTUAL=A108      ,$
  FIELD=ACTUAL_COUNT ,ALIAS=   ,USAGE=P4   ,ACTUAL=Z2        ,$
SEGMENT=PLANNED ,PARENT=BUDGET,SEGTYPE=S,OCCURS=12,
        POSITION=PLANNED_SEG1                                ,$
  FIELD=PLANNED_AMT  ,ALIAS=   ,USAGE=P12  ,ACTUAL=Z9        ,$
SEGMENT=REAL_AMT,PARENT=BUDGET,SEGTYPE=S,OCCURS=ACTUAL_COUNT ,$
  FIELD=ACTUAL_AMT   ,ALIAS=   ,USAGE=P12  ,ACTUAL=Z9        ,$

The POSITION keyword in the PLANNED segment names a field called PLANNED_SEG1 in BUDGET, the immediate parent segment. PLANNED_SEG1 in the parent coincides with the first field of the first occurrence in PLANNED, the OCCURS segment. The REAL_AMT segment does not require a POSITION keyword, because the position of its first occurrence is correctly inferred as following the last described field in the BUDGET segment.

In the previous example, the PLANNED_SEG1 spans all occurrences of the PLANNED segment. As an alternative, 12 individual fields named PLANNED_SEG1 through PLANNED_SEG12 could be described instead in the BUDGET segment. Each individual field would need the appropriate numeric format. Then you could refer to any one of the 12 amount fields by its specific name, or generically through the PLANNED_AMT field. The POSITION attribute can always be used for this purpose, even when it is not required for positioning the first position of an OCCURS segment located in the middle of the record type.



x
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 specifies the quarter to which it applies.

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



x
Syntax: How to Identify an ORDER Field

The ORDER field must be the last field described in the OCCURS segment

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

where:

name

Is any valid field name.

In

Is an integer format.

Note:

  • The ALIAS value must be ORDER.
  • The ACTUAL format must be I4.
  • The ORDER field must be the last field defined in the OCCURS segment.



Example: Using the ORDER Field in Requests

In requests, you can use the value of the ORDER field. You can also specify a DEFINE statement 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:

SELECT TOT.TAXES FROM JOBMAST
WHERE QTR = 1

or

SELECT QTR,BALANCE,INTEREST

WebFOCUS