The hyperdescriptor exits 1 through 31 (HEX01...HEX31) are required to define the algorithm for user-supplied descriptor values (see the Adabas Utilities Manual documentation ). A hyperdescriptor exit is called by the ADACMP utility, ADACHK utility or the Adabas nucleus whenever a hyperdescriptor value is to be generated. ADACMP and ADACHK always use the hyperdescriptor exit specified in its own HEXnn ADARUN statement. When the ADAINV utility specifies a hyperdescriptor exit, the exit used is the one specified in the Adabas nucleus' ADARUN statement.

Hyperdescriptor Exit Parameters

Notes:

1. Hyperdescriptor exits must return the same AMODE value to the calling program that was active when the hyperdescriptor exit was called.
2. If Adabas 8 (or later) is installed and your hyperdescriptor exit has not been updated to use the new parameter list, the Hyperdescriptor Exit Stub can be linked to your hyperdescriptor exit to provide the necessary parameter list changes and input parameter conversion. The Hyperdescriptor Exit Stub does not provide extended MU or PE support. For more information, read Hyperdescriptor Exit Stub.
3. An initialization call is made to each loaded hyperdescriptor exit during Adabas nucleus or ADACMP startup. For more details, read Hyperdescriptor Exit Initialization Call.

This document covers the following topics:

• Main Parameter Area

• Input Parameter Area (Pointed to by Third Parameter Address)

• Output Parameter Area

• Null Value Option

• Hyperdescriptor Exit Initialization Call

• Hyperdescriptor Exit Sample

• Hyperdescriptor Exit Stub

---

Main Parameter Area

Parameter	Content
0 (R1)	Reserved (must not be changed)
4 (R1)	Fullword of zeros (must not be changed)
8 (R1)	Address of the beginning of the input parameter area.
12 (R1)	Address of the beginning of the output parameter area. This address must be inserted by the user-written program. An output parameter area must always be returned by the user hyperdescriptor exit. If no values are to be returned, the address will point to a Header Element with a total length that indicates no Value Elements exist.

Input Parameter Area (Pointed to by Third Parameter Address)

Header Element Fields

LL	Total length of the input parameter area, including this length field
FNR	File number
ISN	ISN assigned to the record
HN	Name of the hyperdescriptor
F	Flag byte: X'02' indicates file with extended MU or PE fields X'80' indicates initialization call

Parent Element Fields

FN	Name of the parent field
L	Length of the value pointed to by VALADDR if the parent field is defined with the FI option.
I	Four-byte periodic group index of the parent field. If the parent field is not part of a PE group, these bytes contain zeros.
VALADDR	Address of the value of the parent field. The format of the value depends on the options of the fields. If the parent field is defined with the NU (null value suppression) option and the value for this field is suppressed, no input parameter element is created.

The following examples show formats for the value pointed to by VALADDR for parent fields with combinations of the FI (fixed storage) and MU (multiple-value) options:

where:

C	A one-byte value representing the MU count. If the MY value is for a file defined with extended MU or PE fields, an extended count may be present. For more details on the extended count, read Identifying MU and PE Occurrences Greater Than 191 in Compressed Records , found in the ADACMP documentation.
*L	A hexadecimal value length, including this one- or two-byte length value. For lengths from 1 through 127, only a single byte is required. For lengths ranging 128 to 255, two bytes are needed: the first byte is set to X`80', and the second byte is set to the actual length value (see the following example table):

Length	Byte 1	Byte 2
L=127:	x`7F'	(x`80')
L=128:	x`80'	x`80'
L=255:	x`80'	x`FF'

Output Parameter Area

This area must be allocated and filled within the hyperdescriptor user exit. The address of this area must be placed into the second position of the main parameter area.

This area consists of a 8-byte header followed by the generated hyperdescriptor values in compressed format.

Header Element

LL	Total length of the output parameter area, including this length field. If no values are returned, the total length is set to the length of the Header Element.
00	Reserved space. This must be set to zeros.
RC	Return code. The hyperdescriptor exit may set a non-zero value here to indicate the call is rejected; a value of "16" is recommended. If this field is non-zero, the call will fail with response code 79 (ADARSP079).
ISN	The ISN to be assigned to the descriptor values. If the original ISN is to be changed, the new ISN must be inserted here. If these four bytes contain zero on return to the Adabas nucleus, the original ISN is used. This is a four-byte binary value.

Value Elements

L

Length of the following value, including this length byte. The maximum length depends on the format in use for the hyperdescriptor.

Value

The descriptor value to be inserted into the index. The value must follow the rules in effect for the format assigned to this hyperdescriptor. If the hyperdescriptor is defined with the PE option, one byte containing the one-byte PE index must immediately follow the value and be included in length L. If the hyperdescriptor defined with the PE option is for a file defined with extended MU or PE fields, two bytes containing the two-byte PE index must immediately follow the value and be included in length L. The nucleus checks values of packed or numeric format for validity. Valid signs for packed fields are A,C,E,F (positive) and B,D (negative). The nucleus changes all signs to F or D.

Examples:

L	Value	Notes
04	R E D
06	B L U E02	where X'02' is a PE index
03	123F	packed 123
04	123F01	packed 123 in PE group with index 1
07	B L U E0002	where X'0002' is a PE index for a file defined with extended MU or PE fields
05	123F010A	packed 123 in extended PE group with index 266

Null Value Option

The NU (null value) option is possible for the hyperdescriptor or parent fields. The possible combinations are as follows:

• The hyperdescriptor is not NU:

  • The parent field is not NU and the value is null, the hyperdescriptor exit is called and the null value is passed.

  • The parent field is NU and the value is null, the hyperdescriptor exit is called and no input parameter element is created for this parent field.

  • All parent fields are NU and all values are null, the hyperdescriptor exit is called and no input parameter element is created for any parent field.

• The hyperdescriptor is NU:

  • The parent field is not NU and the value is null, the hyperdescriptor exit is called and the null value is passed.

  • The parent field is NU and its value is null, the hyperdescriptor exit is called and no input parameter element is created for this parent field.

  • All parent fields are NU and all values are null, the hyperdescriptor exit is not called.

Hyperdescriptor Exit Initialization Call

During Adabas nucleus or ADACMP startup, each loaded hyperdescriptor exit is called with an initialization call. The main parameter area must be used as documented. The third parameter address will point to an input parameter area with a header length indicating that no values follow. The flag byte will be set to x'80' to indicate the initialization call. Upon return, the hyperdescriptor exit must set the fourth parameter address to an output parameter area with a header length indicating that no values are returned.

Hyperdescriptor Exit Sample

Sample hyperdescriptor exit source is supplied in the Adabas source library in member USERHX03. A sample job to assemble and link the hyperdescriptor exit is supplied in member ASMUHX03 of the sample job library in z/OS environments.

Hyperdescriptor Exit Stub

The Hyperdescriptor Exit Stub is provided to allow earlier hyperdescriptor exits to use the Adabas 8 parameter list without change. The Hyperdescriptor Exit Stub is intended as a temporary solution for those customers who do not wish to immediately update their hyperdescriptor exits to use the new parameter areas. The Hyperdescriptor Exit Stub will not function for files that are defined with extended MU or PE fields; a response code will be given when the Hyperdescriptor Exit Stub is called for such files. Hyperdescriptor exits linked with the Hyperdescriptor Exit Stub may be used with earlier versions of Adabas, however, the Hyperdescriptor Exit Stub must not be used with hyperdescriptor exits that use the Adabas 8 parameters.

Sample job LNKHEX8 in the JOBS data set provides an example for linking the Hyperdescriptor Exit Stub to your hyperdescriptor exit.