Mapping Adabas Descriptors

In this section:

 

Adabas descriptors, superdescriptors, and subdescriptors must be declared in Master and Access Files in certain ways:


Top of page

x
Specifying INDEX=I

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. 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 using it is recommended so that keys in your Master File are easily recognized without reference to the Access File.


Top of page

x
Describing Superdescriptors

A superdescriptor is a key value associated with all or part of two to twenty 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 Customizing the Adabas Environment.

Superdescriptors can be printed if they contain only alphabetic fields.


Top of page

x
Specifying Superdescriptors Using the GROUP Attribute

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 server terminology:

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 field name, 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 field name for the superdescriptor.

The USAGE and ACTUAL values must be specified in alphanumeric format. See the next topic 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 Customizing the Adabas Environment.


Top of page

x
Calculating GROUP Length

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 the Specifying Superdescriptors Using the GROUP Attribute, 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)

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

8

P16

16

P16.d

8

Pn or Pn.d, where n is greater than 16 or less than or equal to 31

16

Z (zoned)

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:


Top of page

x
Describing Descriptors in the Access File

Field suffixes are specified in the Access File to identify descriptors, superdescriptors, and subdescriptors.

The syntax is

FIELD[NAME]=fieldname, TYPE=fieldsuffix, [NU={YES|NO}] ,$

where:

fieldname

Is the field name or group in the Access File.

fieldsuffix

Indicates the field suffix. Possible values are:

DSC which indicates a descriptor.

SPR which indicates a superdescriptor made up of whole fields.

NOP which indicates a subdescriptor or superdescriptor made up of partial fields.

PDS which indicates a phonetic descriptor.

HDS which indicates a hyperdescriptor.

blank which indicates non-descriptor fields.

NU

Specifies whether null-suppression is in use. Possible values are:

YES which indicates that the field is described in the adapter with null-suppression.

Note: Descriptors with null values are not stored in inverted lists.

NO which indicates null-suppression is not used. NO is the default value.


Top of page

x
Specifying Superdescriptors Containing Partial Fields

If a superdescriptor consists of one or more partial fields, that superdescriptor (field) is defined with TYPE=NOP (non-printable) in the Access File. This type of descriptor can be used in selection tests, but neither it nor any part of it can be printed or displayed unless the field is alphanumeric.

The partial fields that comprise such superdescriptors are stored in Adabas. There is no facility or necessity for identifying them to the server or the adapter. If you look at an Access File that contains a superdescriptor composed of partial fields, you would recognize it by TYPE=NOP, but you cannot list the partial fields that are its components. To use the adapter, identify such a superdescriptor in the Access File with TYPE=NOP.

Any superdescriptor defined to the server with TYPE=NOP has the following limitation: CALLTYPE=RL is not supported when this field is the IXFLD in an embedded cross-reference or JOIN.

See your Software AG documentation for more information about using superdescriptors containing partial fields.


Top of page

x
Specifying Subdescriptors

A subdescriptor consists of a partial field value for which an index has been created in Adabas. It is described at the field level in the Access File as TYPE=NOP. It can be used in selection tests, but it cannot be printed.

Any subdescriptor defined to the server in the Access File with TYPE=NOP has the following limitation: CALLTYPE=RL is not supported when this field is the IXFLD in an embedded cross-reference or JOIN.


Top of page

x
Specifying Phonetic Descriptors

A phonetic descriptor consists of similar phonetic values for which an index has been created in Adabas. It is described at the field level in the Access File as TYPE=PDS. It can be used in selection tests, but it cannot be printed.


Top of page

x
Specifying Hyperdescriptors

A hyperdescriptor consists of values generated, based on a user-supplied algorithm, for which an index has been created in Adabas. It is described at the field level in the Access File as TYPE=HDS. It can be used in selection tests, but it cannot be printed.

Any phonetic descriptor or hyperdescriptor defined to the server in the Access File with TYPE=PDS/HDS has the following limitation: CALLTYPE=RL is not supported when this field is the IXFLD in an embedded cross-reference or JOIN.

If you have selected a field defined with TYPE=NOP (for example, subdescriptors), TYPE=PDS or TYPE=HDS, a FIND call is issued even if RL has been specified.


Top of page

x
Specifying Null-Suppression

To allow the Adapter for Adabas to create the most efficient calls, while still maintaining integrity of the answer set, any null-suppressed fields that are components of a superdescriptor must be defined in the Access File. The NU attribute is used to define a null-suppressed field.

An NU field defined as a descriptor is not stored in inverted lists when it contains a null value. Any qualifying descriptor records containing a null value are not recognized by a FIND command that refers to that descriptor.

The same is true for subdescriptors and superdescriptors derived from fields described in the adapter with null-suppression. No entry is made for a subdescriptor if the bytes of the field from which it is derived contain a null value and that field is defined with null-suppression (NU). No entry is made for a superdescriptor if any of the fields from which it is derived is an NU field with a null value.

For more information about null-suppression and how it affects data retrieval, see your Software AG documentation.


Top of page

x
Specifying Support for SQL-Compatible Null Representation

Two additional data definition options are provided to enable specification of SQL-compatible null representation and handling by the Adapter for Adabas. The NC (not counted) and NN (not null) options can be placed in Access File field definitions to control evaluation and handling of null values. (Note that the NN option is only permitted when the NC option is also specified.)

See Server File Structure for an overview of these options, and Creating Synonyms When Adabas Fields Are Defined With the NC Option for a detailed explanation and examples of both the Master Files and Access Files following issuance of Create Synonym.


Top of page

x
Implementing Embedded JOINs: KEYFLD and IXFLD

The KEYFLD and IXFLD attributes identify the common fields for parent/descendant relationships in a multi-segment Master File. These relationships are referred to as embedded JOINs or server views.

For each descendant segment, the KEYFLD and IXFLD attributes specify the field names of the shared field that implements the embedded JOIN. The parent field supplies the value for cross-referencing; the descendant field contains the corresponding value. The adapter implements the relationship by matching values at run time.

The KEYFLD and IXFLD attributes are valid only for ACCESS=ADBS segments.

Attribute

Description

KEYFLD

Field name in the parent segment whose value is used to retrieve the child segment. This is also known as the primary key.

IXFLD

Field name in the child or cross-referenced segment containing the related data. This is also known as the foreign key.

The value for the KEYFLD attribute is a 1- to 66-character field name or alias from the parent segment. The value for the IXFLD attribute is a 1- to 66-character field name or alias from the descendant segment. This is an example of a Master File with an embedded JOIN using KEYFLD and IXFLD.

FILENAME=AMKTORDR     ,SUFFIX=ADBSINX ,$
SEGNAME=MKTORDER 
FIELDNAME=NMARKET_GRP     ,BA          ,I3      ,I2,   INDEX=I,$
FIELDNAME=QPRODUCT        ,BB          ,I3      ,I2       ,$
FIELDNAME=QNEEDITM        ,BC          ,A3      ,I2       ,$
FIELDNAME=FBUILD          ,BD          ,A1      ,A1       ,$
FIELDNAME=FK_NPRODUCT     ,BE          ,A4      ,A4       ,$
FIELDNAME=FK_NCUSTOMER    ,BF          ,I3      ,I2       ,$
FIELDNAME=DATEMKTO        ,BG          ,A8      ,A8       ,$
FIELDNAME=DATEFBLD        ,BH          ,A8      ,A8       ,$
 
SEGNAME=CUSTOMER, SEGTYPE=U,PARENT=MKTORDER,$
FIELDNAME=NCUSTMR_GRP     ,AA          ,I3      ,I2,   INDEX=I,$
FIELDNAME=NAMECUST        ,AB          ,A15     ,A15      ,$
FIELDNAME=DCUSROAD        ,AC          ,A20     ,A20      ,$
FIELDNAME=DCUSTOWN        ,AD          ,A20     ,A20      ,$

This is an example of an Access File with an embedded JOIN using KEYFLD and IXFLD.

RELEASE=6,    OPEN=YES,$
  SEGNAM=MKTORDER,   ACCESS=ADBS,FILENO=022,DBNO=001 ,$
  SEGNAM=CUSTOMER,   ACCESS=ADBS,FILENO=021,DBNO=001 ,CALLTYPE=FIND, 
IXFLD=NCUSTMR_GRP,KEYFLD=FK_NCUSTOMER,$				

Note: Include the pair of attributes in the Access File segment declaration for descendant segments. Do not specify them in the segment declaration for the root segment.

A JOIN can be based on more than one field in the host and cross-referenced logical record types. If the Adabas file uses multiple fields to establish a relationship or link between logical record types, you can specify concatenated fields in an embedded JOIN. You can also specify multiple fields with the dynamic JOIN command.

In the multi-field embedded JOIN, the KEYFLD and IXFLD values consist of a list of their component fields separated by slashes (/). Additional Access File attributes are not required. The syntax is

KEYFLD=field1/field2/...,
IXFLD=cfield1/cfield2/...,$

where:

field1/...

Is a composite of up to 16 key fields from the parent segment. Slashes are required.

cfield1/...

Is a composite of up to 16 key fields from the descendant segment.

The adapter compares each field pair for the data formats prior to format conversion. It evaluates each field pair with the following rules:

To implement JOINs, the Adabas DBMS converts the alphanumeric field formats on the server to equivalent Adabas field formats in order to perform the necessary search and match operations. When the Adabas DBMS returns the answer set of matched values, it also converts the values back to alphanumeric formats. The cross-referenced fields must be descriptor fields.


iWay Software