FOCUS permits a great deal of flexibility in its Master Files. For the ADABAS Interface, you need only describe 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, 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 FOCUS procedure.
FOCUS Master Files have three parts: file declaration, segment declaration, and field declaration, each of which is explained in this chapter. Concepts which are specific to ADABAS files, for which FOCUS requires unique syntax in the Master File, are also explained.
The following is an example of the Master File for VEHICLES.
$$$ CREATED BY AUTOADBS 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,$
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= 60Figure 5-1. Example of the VEHICLES Master File
FIELD= MAINT_COST ,ALIAS= AM ,P7 ,P4 ,$
FIELD= AM0101_OCC ,ALIAS= ORDER ,I4 ,I2 ,$
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:
ADBSINX
The FILENAME (or FILE) is any valid name, as defined in the FOCUS for IBM Mainframe User's Manual, from one to eight characters long.
In the MVS environment, it is a member of a partitioned dataset with the ddname MASTER; in the CMS environment, it is stored with the filetype MASTER.
The value for the SUFFIX attribute is always ADBSINX, which is the name of the ADABAS Interface program that FOCUS loads to read an ADABAS database.
The following example is a typical file declaration:
FILENAME=ADACAR, SUFFIX=ADBSINX,$
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:
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 FOCUS hierarchical design to take advantage of multi-value fields and periodic groups. You may have multiple ADABAS records described in the same FOCUS view. Each record is described as a segment with a unique SEGNAME.
See your FOCUS for IBM mainframe documentation for more information on the number of segments allowed in a Master File.
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. Refer to the FOCUS for IBM Mainframe User's Manual for more information on file and segment cross-referencing.
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.
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.
The following two examples are typical segment declarations:
SEGNAME=S01 ,SEGTYPE=S ,$
SEGNAME=AM0101 ,SEGTYPE=S ,PARENT=S01 ,OCCURS=AMC ,$
Field declarations describe the fields in each file. For the simplest file structures (single-segment, fixed-length files), you only need to describe the ADABAS fields you actually use for reporting purposes.
Put them 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:
Note: Field declarations are always terminated with ,$.
There are additional attributes that apply to superdescriptor, cross-referenced, repeating, and other types of fields. These attributes are discussed later in this chapter.
The fieldname 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.
Fieldnames are unique names of 1-66 characters. The Master File fieldname does not need to be the same as the ADABAS fieldname. Fieldnames can include any alphanumeric characters, but the first character must be a letter from A-Z. Avoid embedded blanks and special characters.
Since all references to data in FOCUS are through fieldnames or aliases, the fieldnames 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 fieldnames in the two segments or FOCUS uses the first one in the Master File unless you qualify which field you want, for example, file.field, segment.field.
The ALIAS for a single ADABAS field must contain the two-character internal ADABAS fieldname. The Interface 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 must be the same as the two-character internal ADABAS fieldname, your Master File may include duplicate ALIAS values. In that case, the fieldname is used to differentiate between the segments.
The FOCUS ALIAS field allows reformatting of the field for a different view of the field. Several ADABAS data formats have maximum lengths that exceed the supported maximum length of FOCUS data formats. You can use the FOCUS ALIAS to convert this data to an acceptable FOCUS ACTUAL format and length.
When a field is specified in a retrieval request, the value in the FOCUS ALIAS is passed to ADABAS in the Format buffer. ADABAS uses the ALIAS to process the field and return the data to FOCUS.
To use the reformatting option, define the ALIAS using length and format values that indicate the way you want to reformat the field.
The syntax is
ALIAS='xx,l,f'
where:
The entire value must be enclosed in single quotation marks.
For example, if you only want to use 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 ADABAS Interface 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 a FOCUS 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 the section on ACTUAL for the acceptable USAGE and ACTUAL values along with the corresponding ADABAS codes.
Note: Groups cannot be reformatted. This formatting is only valid for elementary fields.
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 edit options when the field values are printed.
The syntax is
{USAGE}=tllleeeee
where:
The value that you specify for field length is the number of alphanumeric characters or numeric digits that FOCUS allocates for the field in any display or report. The specified value excludes the editing characters, such as comma, $, and so on. Edit options control how a field value is printed.
For more information about the USAGE attribute, refer to the FOCUS for IBM Mainframe User's Manual.
The ACTUAL attribute describes the length and type of the ADABAS field in storage. It is used only to describe the format of fields from external data files, and must be included in the Master Files needed for the ADABAS Interface. The source of this information is your existing ADABAS Field Definition Table (FDT).
The syntax is
ACTUAL=tlll
where:
FOCUS permits the following conversions from ACTUAL format to USAGE (display) format:
ADABAS |
FOCUS |
FOCUS |
FOCUS |
FOCUS |
Description |
A |
A |
1-256 |
A |
1-256 |
Alphanumeric |
G |
D |
8 |
D |
1-15 |
Decimal, Double- Precision |
F |
F |
4 |
F |
1-9 |
Decimal, SinglePrecision- |
B** |
I |
1-4 |
I |
1-9 |
Integer Values |
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: FOCUS ACTUAL is in number of bytes. FOCUS USAGE allows space for all possible digits, a minus sign for negative numbers, and a decimal point in numbers with decimal digits. |
** |
The length for ADABAS format type B (integer values) is 1-126 bytes. This value converts to a FOCUS ACTUAL type of integer I with 1-4 bytes. For example, ADABAS format B126 is represented in FOCUS as I4. Refer to the table containing USAGE and ACTUAL conversion formulas in The AUTOADBS Facility.. |
The following table shows the codes for the types of data FOCUS reads:
ACTUAL Type |
Meaning |
An |
Alphanumeric characters A-Z, 0-9, and the special characters in the EBCDIC display mode, where n = 1-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-4. |
Pn |
Packed decimal data, where n = 1-15 bytes. |
Zn |
Zoned decimal data, where n = 1-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). |
The following is a typical field declaration:
FIELD=MODEL ,ALIAS=AE ,USAGE=A20 ,ACTUAL=A20 ,$
As stated in ADABAS Overview and Mapping Considerations, descriptors act as key values associated with a single field in an ADABAS record. They enable records to be retrieved more efficiently based on the selection of a value, a set of values, or a range of values.
Additionally, all descriptors, superdescriptors, and subdescriptors are used to establish logical relationships between files. In FOCUS there are two methods for establishing logical relationships:
ADABAS descriptor fields are identified in the Master File using the INDEX=I attribute. For example:
FIELD=MAKE ,ALIAS=AD ,USAGE=A20 ,ACTUAL=A20 ,INDEX=I, $
INDEX=I is optional in the Master File, but its use is recommended so that keys in your Master File are easily recognized without reference to the Access File.
A superdescriptor is a key value associated with all or part of two to five ADABAS fields. If the superdescriptor consists of a group of complete fields, it is declared differently than a superdescriptor which consists of one or more partial fields. For information on superdescriptors consisting of partial fields, see Describing Descriptors in the Access File.
Superdescriptors can be printed if they contain only alphabetic fields.
A superdescriptor composed of several complete fields is described with the GROUP attribute. All the fields that are part of the group must be specified immediately after the GROUP atttribute in the order in which they appear in the superdescriptor.
The following example shows a superdescriptor defined in FOCUS terminology:
Figure 5-2. Superdescriptor Defined With the GROUP Attribute
GROUP=TRANS ,ALIAS=S1 ,USAGE=A20 ,ACTUAL=A20 ,INDEX=I ,$
FIELD=ACCT_NO ,ALIAS=C2 ,USAGE=A9 ,ACTUAL=A9 ,$
FIELD=ITEM_NO ,ALIAS=GD ,USAGE=A5 ,ACTUAL=A5 ,$
FIELD=TRANS_DATE ,ALIAS=D7 ,USAGE=A6YMD ,ACTUAL=A6 ,$
The group fieldname, in this case, is TRANS. Since it is a superdescriptor, the INDEX=I attribute is included on the GROUP specification.
The ALIAS is the two-character ADABAS fieldname for the superdescriptor.
The USAGE and ACTUAL values must be specified in alphanumeric format. See the next section on calculating group length for more information.
If any of the components of the TRANS group field were descriptors, they could also contain the INDEX=I attribute.
Note: TYPE=SPR must be defined in the Access File. For more information, see Describing Descriptors in the Access File.
For a group field, you must supply both the USAGE and ACTUAL values in alphanumeric format.
If the component fields of the group are alphanumeric, the USAGE and ACTUAL lengths of the group field must be exactly the sum of the component field lengths. For example, in Figure 5-2, the lengths specified in the USAGE and ACTUAL attributes for the component fields ACCT_NO, ITEM_NO, and TRANS_DATE each total 20. The lengths specified in the USAGE and ACTUAL attributes of the TRANS group field are consequently both equal to 20.
If the component fields of the group are not alphanumeric:
You determine these internal storage lengths as follows:
USAGE |
Length |
A (alphanumeric) |
A value equal to the number of characters contained in the field |
D (decimal, double-precision) |
8 |
F (decimal, single precision) |
4 |
I (integer) |
4 |
P (packed decimal): Pn or Pn.d, where n is less than or equal to 15 P16 P16.d Pn or Pn.d, where n is greater than 16 or less than or equal to 31 |
8 8 16 16 |
Z (zoned) |
A value equal to the number of characters contained in the field |
For example, consider the following GROUP specification in the EMPLOYEES Master File:
GROUP= LEAVE_DATA ,ALIAS= A3 ,A16 ,A4 ,$
FIELD=LEAVE_DUE ,ALIAS= AU ,P2 ,Z2 ,$
FIELD=LEAVE_TAKEN ,ALIAS= AV ,P2 ,Z2 ,$
In this example:
Here is a GROUP specification:
GROUP= MODEL_YEAR_MAKE ,ALIAS= AO ,A28 ,A22 , INDEX=I,$
FIELD=YEAR ,ALIAS= AG ,P2 ,Z2 ,$
FIELD=MAKE ,ALIAS= AD ,A20 ,A20 , INDEX=I,$
In this example:
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 must equal the two-character internal ADABAS name appended with the letter C.
Records with repeating fields are defined to FOCUS 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:
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 count 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 Interface 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.
Note: For both counter (CNT) and ORDER fields, Release 7.0.8 and higher supports ACTUAL=I2. Prior releases required ACTUAL=I1.
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.
Refer to the FOCUS for IBM Mainframe User's Manual for more information on the OCCURS attribute.
This section 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 count 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 fieldnames 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 ,$
This explanation interprets the file shown in Figure 5-7:
This example includes the periodic group called INCOME, which contains the MU field, BONUS. AUTOADBS comments out the group field with $PEMU because its length is variable (depending on the number of occurrences of the MU field). FOCUS cannot report on a group with an unknown length. However, the component fields can be referenced for reporting purposes.
In Figure 5-7, the BONUS_CNT (ALIAS=ATC) field is the count 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 count 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.
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 FOCUS to determine the sequence number of fields in an OCCURS segment. FOCUS 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 an ALIAS value of ORDER tracks the order of occurrence of the preceding fields in the segment. Therefore, in Figure 5-7, AT0301_OCC maintains the sequence of BONUS occurrences.
An ORDER field may be decoded into a meaningful value in a DEFINE. Refer to the FOCUS for IBM Mainframe User's Manual for information on DEFINE.
| Information Builders |