Managing Supra Metadata

This topic explains how the Adapter for Supra enables you to describe and report from Supra database views. You should become familiar with these topics because most of the concepts affect the way Supra files are described to the server.

When the server accesses a data source, it needs information on how to interpret the data stored there. For each data source the server will access, you create a synonym that describes the structure of the data source and the server mapping of the Supra data types.

Creating a Supra Master File

A Master File is a set of comma-delimited records. Each record is terminated with a comma and dollar sign (,$). The syntax for describing a Supra database in a Master File is similar to that of any other Master File and uses the same attributes (keyword=value pairs). A Master File can contain a File record, Segment records, and Field records. The attributes are described in the following sections.

File Keywords

FILENAME

Is an arbitrary name up to eight characters in length.

SUFFIX

Is SUPRA when accessing RDM or PDM data using the Supra RDM and identifies the adapter.

Segment Keywords

SEGNAME

Is a name for the segment, up to 64 characters in length.

SEGTYPE

Is the segment type. Sn means that the first n fields are components of the key, in the order listed. This information is used only if the Access file is missing, or if no value is specified for the KEYNAME attribute of the Access File. If the two values disagree, the value specified in the Access File is retained. A message is displayed only if FSTRACE is allocated to the screen or to a file.

PARENT

Is the segment name of the parent. If you describe several Supra views or user views as a hierarchical structure in one Master File, you must define one view as the root segment and all other views as descendant segments. Each descendant segment must include the PARENT attribute to identify its parent in the hierarchy. You must also identify the shared fields for each pair of segments by specifying the KEYFLD and IXFLD attributes in the Access File.

Field Keywords

FIELDNAME

Is an arbitrary name, up to 66 characters in length.

ALIAS

Is the name of the view column, as defined to Supra. The total length must not exceed 66 characters.

USAGE

Is the display format for the field in report output. USAGE format values are A (Alpha), I (Integer), F (Floating point), D (Decimal), and P (Packed). Each format must have an associated length. F, D, and P formats can also have a specification for the number of decimal places to display, for example, D12.2 specifies a total length of 12, with a period and two decimal places.

ACTUAL

Specifies the actual Supra format (that is, the format defined by the DBA in the view definition that an application program would use for accessing the data).

The following are examples of Supra formats and their corresponding ACTUAL formats.

  • Supra B 1, 2, 4, and 8 (with decimal) fields can be defined as F or D.
  • Supra C 1-32,767 fields can be defined as A (the maximum length of an alphanumeric field is 256 characters).
  • Supra F 4, 8, and 16 fields can be defined as I.
  • Supra P 1-16 (with decimal) fields can be defined as P.
  • Supra Z 1-18 (with decimal) fields can be defined as Z.

The ACTUAL format does not specify the number of decimal places in the number. The USAGE format defines the number of decimal places. It must be large enough to accommodate all of the digits in the number, the decimal point, and a possible minus sign. For example, if the Supra format is P5 with 2 decimal places, you can use the following USAGE and ACTUAL specifications in the Master File:

ACTUAL=P5, USAGE=P8.2
Note: You can describe multiple views in one Master File. If they have shared fields (fields with the same value in both views), one view is described as the parent segment, and the other views are described as the child segments.

Creating a Supra Access File

The Access File provides the information necessary for selecting the appropriate Supra database, view, and access strategy (that is, the linking of items between different tables).

A logical record in the Access File consists of a list of attributes (keyword = value pairs) separated by commas and terminated by a comma and dollar sign (,$). The list is freeform and can span several lines. The keywords can be specified in any order.

The Access File contains two types of logical records, HEADER and SEGMENT.

HEADER Logical Record

USER

Is the Supra user name. If omitted, it defaults to FOCUS.

PASSWORD

Is the password associated with the Supra user. If omitted, it defaults to FOCUS.

SEGMENT Logical Record

SEGNAME

Is the segment name from the Master File.

VIEW

Is the name of the Supra view. If omitted, it defaults to SEGNAME.

USERVIEW

Is the Supra user view corresponding to the segment identified by SEGNAME. If omitted, it defaults to VIEW.

KEYNAME

Is a composite of at most nine field names that constitute the key of the view. The field names are concatenated with the slash symbol (/), without intervening blanks. The keyword value can span more than one line. If omitted, the first n fields, as specified by the SEGTYPE keyword in the Master File, are assumed.

KEYFLD

Is a field name in the parent segment or a defined field that establishes the embedded cross-reference between segments. It is mandatory in all but the root segment. Its value is a composite of a maximum of nine field names concatenated with the slash symbol (/), without blank spaces. The value can span more than one line.

IXFLD

Is a field name in the descendant segment that establishes the embedded cross-reference between segments. It is mandatory for all but the root segment. The IXFLD values should match the KEYFLD values of the parent segment. The keyword value consists of a maximum of nine field names concatenated with the slash symbol (/), without blanks. The value can span more than one line.

If your request references fields from two segments defined in the same Master File, the two views are automatically cross-referenced. The fields that implement the cross-reference are specified in the Access File with the KEYFLD and IXFLD attributes. The selection of the shared fields is transparent to you.

The following rules apply to KEYFLD and IXFLD.

  • As KEYFLD, you can specify a:
    • Simple field.
    • List of fields.
  • As IXFLD, you can specify a:
    • Simple field.
    • List of fields.

In all cases, the length and the format of KEYFLD and IXFLD must be consistent (a list of fields may be joined to a simple field and vice versa, as long as their formats are alphanumeric).

Sample Master and Access File

The following is a sample Master File that describes two Supra views.

FILE=DTCCORP1              ,SUFFIX=SUPRA,$
SEGNAME=CORPDESC,SEGTYPE=S,$
  FIELDNAME=DELETE_FLAG    ,ALIAS=DFLAG.1  , USAGE=A1   ,ACTUAL=A1  ,$
 GROUP=CONTRL_KEY          ,ALIAS=CNTRL.KEY,USAGE=A23  ,ACTUAL=A23 ,$
  FIELDNAME=CORP           ,ALIAS=CNTRL.1  ,USAGE=A3    ,ACTUAL=A3  ,$
  FIELDNAME=ACCOUNT        ,ALIAS=CNTRL.2  ,USAGE=A10   ,ACTUAL=A10 ,$
  FIELDNAME=COST_CENTR     ,ALIAS=CNTRL.3  ,USAGE=A10   ,ACTUAL=A10 ,$
 FIELDNAME=LRECL           ,ALIAS=LRECL.1  ,USAGE=P4    ,ACTUAL=P3  ,$
 FIELDNAME=ACCT_TYPE       ,ALIAS=ACDSC.1  ,USAGE=A1    ,ACTUAL=A1  ,$
 FIELDNAME=ACCT_DESC       ,ALIAS=ACDSC.2  ,USAGE=A20   ,ACTUAL=A20 ,$
 FIELDNAME=FILLER          ,ALIAS=ACDSC.3  ,USAGE=A32   ,ACTUAL=A32 ,$
SEGNAME=CORPOWNR,SEGTYPE=S,PARENT=CORPDESC,$
  FIELDNAME=DELETE_FLAG    ,ALIAS=EFLAG.1  ,USAGE=A1    ,ACTUAL=A1  ,$
 GROUP=DESC_KEY            ,ALIAS=DTKEY.KEY,USAGE=A23 ,ACTUAL=A23 ,$
  FIELDNAME=CORP           ,ALIAS=DTKEY.1  ,USAGE=A3    ,ACTUAL=A3  ,$
  FIELDNAME=ACCOUNT        ,ALIAS=DTKEY.2  ,USAGE=A10   ,ACTUAL=A10 ,$
  FIELDNAME=COST_CENTR     ,ALIAS=DTKEY.3  ,USAGE=A10   ,ACTUAL=A10 ,$
 FIELDNAME=LRECL           ,ALIAS=LRECL.1  ,USAGE=P4    ,ACTUAL=P3  ,$
 FIELDNAME=ACCT_TYPE       ,ALIAS=OWNER.1  ,USAGE=A1    ,ACTUAL=A1  ,$
 FIELDNAME=ACCT_OWNER      ,ALIAS=OWNER.2  ,USAGE=A20   ,ACTUAL=A20 ,$
 FIELDNAME=FILLER          ,ALIAS=OWNER.3  ,USAGE=A32   ,ACTUAL=A32 ,$

The following is the corresponding Access File. 

USER=CINCOM,PASSWORD=CINCOM,$
SEGNAME=CORPDESC,VIEW=V01,KEYNAME=CNTRL.KEY,$
SEGNAME=CORPOWNR,VIEW=V02,KEYNAME=DTKEY.KEY,
    KEYFLD=CNTRL.KEY,IXFLD=DTKEY.KEY,$