Master Files for Adabas

In this section:

Standard Master File attributes are generally used to describe Adabas files, but there are concepts in Adabas file processing that require special terminology at the field and segment level. On z/OS, the Master File is a member of a PDS allocated to DDNAME MASTER.

The server permits a great deal of flexibility in its Master Files. For the Adapter for Adabas, you need to describe only the Adabas fields actually used in reporting applications, omitting any unnecessary Adabas fields. (Note the exception that if a PE group is included in the Master File, all fields of the PE group must be included. See Field Attributes in Master Files and Describing Multi-Value Fields Within Periodic Groups for additional information.) Additionally, describing the same Adabas file in multiple ways enables you to access that same file in its different configurations within one procedure.

Master Files have three parts: file declaration, segment declaration, and field declaration, each of which is explained in these topics. Concepts that are specific to Adabas files, for which the server requires unique syntax in the Master File, are also explained.

The following is an example of the Master File for VEHICLES.

$$$ CREATED ON 12/10/03 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,$
 GROUP=CAR_DETAILS                ,ALIAS=CD     ,A50   ,A50  ,$
  FIELD=MAKE                      ,ALIAS=AD     ,A20   ,A20  ,INDEX=I,$
  FIELD=MODEL                     ,ALIAS=AE     ,A20   ,A20  ,$
  FIELD=COLOR                     ,ALIAS=AF     ,A10   ,A10  ,INDEX=I,$
 FIELD=YEAR                       ,ALIAS=AG     ,P2    ,Z2   ,$
 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   ,$

Top of page

x
File Attributes in Master Files

In this section:

Master Files begin with a file declaration that names the file and describes the type of data source. The file declaration has two attributes, FILENAME and SUFFIX.

The syntax is

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

where:

filename

Is a one- to eight-character name that complies with server file naming conventions.

ADBSINX

Is the value that specifies the Adapter for Adabas.



x
FILENAME

The FILENAME (or FILE) is any valid name from one to eight characters long.

In the z/OS environment, it is a member of a partitioned data set allocated to the DDNAME MASTER.



x
SUFFIX

The value for the SUFFIX attribute is always ADBSINX, which is the name of the Adapter for Adabas program that the server loads to read an Adabas database.



Example: File Declaration

The following example is a typical file declaration:

FILENAME=ADACAR, SUFFIX=ADBSINX,$

Top of page

x
Segment Attributes in Master Files

In this section:

Each segment declaration describes one Adabas record or a subset of an Adabas record (called a logical record type). Each logical record type described in a Master File requires a segment declaration that consists of at least two attributes, SEGNAME and SEGTYPE.

The syntax is

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

where:

segname

Is a unique one- to eight-character name that identifies the segment.

segtype

Identifies the characteristics of the segment. Possible values are:

S which indicates multiple instances of a descendant segment are related to a given parent.

SO which indicates the Write Adapter for Adabas (for the Read Adapter for Adabas, SEGTYPE=S is sufficient).

U which indicates a single instance of data for a descendant segment is related to its parent.

KL which indicates multiple instances of a cross-referenced descendant segment are related to a given parent.

KLU which indicates a single instance of a cross-referenced descendant segment is related to its parent.

parent

Is the name of the parent segment in the Master File.

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 field on the server) appended with the letter C.



x
SEGNAME

The SEGNAME (or SEGMENT) attribute is the name of a group of data fields that have a one-to-one relationship to each other in the Adabas file.

You may describe an Adabas file in the server hierarchical design to take advantage of multi-value fields and periodic groups. You may have multiple Adabas records described in the same Master File view. Each record is described as a segment with a unique SEGNAME.



x
Syntax: How to Name a Root Segment in the Master File

For the root segment of the Adabas file, the segment name generated is

Snn 

where:

nn

Is a two-digit number indicating the order in which the file was selected.

The first file (selected as the root from the File Selection Menu) has SEGNAME=S01. Subsequent files used in the same description (selected as children from the File Selection Menu) have SEGNAME=S02, SEGNAME=S03, and so on.



x
Syntax: How to Name a Segment for a PE Group and MU Field

The segment names for PE (periodic element) groups and MU (multi-value) fields have the format

aammnn 

where:

aa

Is the Adabas field name.

mm

Is a two-digit number that indicates the order in which the PE group or MU field appears in the PREDICT description of the file.

nn

Is the order number used for the root segment.



Example: Naming a Segment for a PE Group and MU Field

Using the syntax aammnn, SEGNAME=BE0201 describes the segment for the field BE, which is the second (02) PE group or MU field described in the first segment (01).



x
SEGTYPE

The SEGTYPE attribute identifies the basic characteristics of related or cross-referenced segments. Cross-referencing is a method of accessing information from two or more different files or segments to use in a single report request.

SEGTYPE

Is the root segment and cross-reference segment type. The SEGTYPE is S0 for the root file and children with a non-unique IXFLD. The SEGTYPE is U for a child with a unique IXFLD. The SEGTYPE for all PE and MU fields is S0.



x
PARENT

Any segment except the root is a descendant, or child, of another segment. The PARENT attribute supplies the name of the segment which is the logical parent or owner of the current segment. If no PARENT attribute appears, the default is the immediately preceding segment. However, it is highly recommended to include the parent. The PARENT name is the one- to eight-character SEGNAME of a previous segment.

PARENT

Is the value of SEGNAME of the parent record.



x
OCCURS

For more information on the segment attribute OCCURS, which applies to repeating fields and groups, see Describing Multi-Value Fields and Periodic Groups With the OCCURS Attribute.

OCCURS

Indicates the number of occurrences of a PE group or MU field. This attribute contains the Adabas field name of the PE group or MU field with the suffix C, which is the ALIAS of the counter field in the parent segment.



Example: Segment Declaration

The following two examples are typical segment declarations:

SEGNAME=S01        ,SEGTYPE=S     ,$
SEGNAME=AM0101     ,SEGTYPE=S     ,PARENT=S01    ,OCCURS=AMC   ,$

Top of page

x
Field Attributes in Master Files

In this section:

Field declarations describe the fields in each file. For the simplest file structures (single-segment, fixed-length files), you need to describe only the Adabas fields you actually use for reporting purposes.

Put the fields in any order within their segment, except in the case of fields within periodic groups (PE). The PE group must have all fields defined and in the proper order.

The syntax is

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

where:

fieldname

Is the 1- to 66-character name that is unique to the Master File.

alias

Is the two-character internal Adabas field name.

display

Is the server display format for the field.

format

Is the server definition of the Adabas field format and length.

Note: Field declarations are always terminated with ,$.

There are additional attributes that apply to superdescriptor, cross-referenced, repeating, and other types of fields.



x
FIELDNAME

The field name appears as a column heading when you include the field in a report request. You can change the default by using AS or NOPRINT in the report or by using TITLE in the Master File.

Field names are unique names of up to 66 characters. The Master File field name does not need to be the same as the Adabas field name. Field names can include any alphanumeric characters, but the first character must be a letter from A to Z. Avoid embedded blanks and special characters.

Since all references to data on the server are through field names or aliases, the field names should be unique within a Master File. This requirement is true even when the same Adabas record is included as two differently structured segments in the same Master File. You must specify different field names in the two segments or the server uses the first one in the Master File unless you qualify which field you want, for example, file.field, segment.field.



x
ALIAS

The ALIAS for a single Adabas field must contain the two-character internal Adabas field name. The adapter uses it to generate direct calls to the Adabas DBMS. The format rules are as follows:

Note: Because of the requirement that the ALIAS in a Master File be the same as the two-character internal Adabas field name, your Master File may include duplicate ALIAS values. In that case, the field name is used to differentiate between the segments.



x
Using the ALIAS to Reformat Adabas Fields

The ALIAS field allows reformatting of the field for a different view. Several Adabas data formats have lengths that exceed the supported maximum length of data formats on the server. You can use the ALIAS to convert this data to an acceptable ACTUAL format and length.

When a field is specified in a retrieval request, the value in the ALIAS is passed to Adabas in the Format buffer. Adabas uses the ALIAS to process the field and return the data to the server.

To use the reformatting option, define the ALIAS using length and format values that indicate how you want to reformat the field.

The syntax is

ALIAS='xx,l,f'

where:

xx

Is the two-character internal Adabas field name.

l

Is the new length of the field value in number of bytes.

f

Is the new Adabas format of the field value.

The entire value must be enclosed in single quotation marks.

For example, if you want to use only the first three characters in a six-byte field, use the following syntax in your Master File:

FIELD=L_DBNR, ALIAS='AU,3,P', USAGE=P3, ACTUAL=P3  ,$

In this case, the Adapter for Adabas will read only the first three bytes (L_DBNR is a six-byte field with the Adabas description: 01, AU, 6, U).

In the next example, to convert an Adabas binary field format of ten bytes (Adabas description: 01, BB, 10, B) to an alphanumeric format large enough to accommodate the Adabas value, you could use the following syntax in your Master File:

FIELD=TESTFLD, ALIAS='BB,10,A', USAGE=A20, ACTUAL=A10  ,$

Notice that you must also change the USAGE and ACTUAL values to reflect the changes in the format. Refer to the chart in ACTUAL for the acceptable USAGE and ACTUAL values along with the corresponding Adabas codes.

Note: Groups cannot be reformatted. This formatting is valid only for elementary fields.



x
USAGE

The USAGE attribute enables you to describe how you want fields displayed on the screen, printed in reports, or used in calculations. This attribute includes the data field type, length, and any applicable display options when the field values are printed. FORMAT is a synonym for USAGE.

The syntax is

USAGE=tllleeeee 

where:

t

Is the field type.

lll

Is the number of positions needed to display the field.

eeeee

Are the display options.

The value that you specify for field length is the number of alphanumeric characters or numeric digits that the server allocates for the field in any display or report. The specified value excludes the editing characters, such as comma, $, and so on. Display options control how a field value is printed.



x
ACTUAL

The ACTUAL attribute describes the length and type of the Adabas field in storage. It is used to describe the format of fields from external data files only, and must be included in the Master Files needed for the Adapter for Adabas. The source of this information is your existing Adabas Field Definition Table (FDT).

The syntax is

ACTUAL=tlll 

where:

t

Is the server field type of the Adabas field.

lll

Is the storage length of the Adabas field.

The server permits the following conversions from ACTUAL format to USAGE (display) format:

Adabas Format Type

Server ACTUAL Type

Server ACTUAL Length*

Server USAGE Type

Server USAGE Length*

 
 
Description

A

A

1-256

A

1-256

Alphanumeric

G

F
D

4
8

F
D

1-9
1-15

Float Single-Precision
Float Double-Precision

F

I

2, 4

I

1-9

Integer

B
1-4
5-6
7-126

 
I
P
A

 
1-4
7-8
9-126

 
I
P
A

 
1-9
12-15
14-252

 
Integer Values
Packed Decimal
Alpha

P

P

1-15

P

1-33.n

Packed Decimal

U

Z

1-29

A or P

1-33.n

Zoned

* Lengths are measured as follows:

  • ACTUAL is in number of bytes.
  • USAGE allows space for all possible digits, a minus sign for negative numbers, and a decimal point in numbers with decimal digits.

The following table shows the codes for the types of data the server reads:

ACTUAL Type

Description

An

Alphanumeric characters A to Z, 0 to 9, and the special characters in the EBCDIC display mode, where n = 1 to 256 bytes.

D8

Double-precision, floating-point numbers, stored internally in eight bytes.

F4

Single-precision, floating-point numbers, stored internally in four bytes.

In

Binary integers, where n = 1 to 4.

Pn

Packed decimal data, where n = 1 to 15 bytes.

Zn

Zoned decimal data, where n = 1 to 30 bytes. Represent the field as Zm.n, where m is the total number of digits, and n is the number of decimal places (for example, Z6.1 means a six-digit number with one decimal place).



x
INDEX

For more information on the field attribute INDEX, which applies to descriptors, see Specifying INDEX=I.



x
GROUP

For more information on the field attribute GROUP, which applies to superdescriptors, see Specifying Superdescriptors Using the GROUP Attribute.



Example: Field Declaration

The following is a typical field declaration:

FIELD=MODEL ,ALIAS=AE ,USAGE=A20 ,ACTUAL=A20 ,$

iWay Software