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.
Notes:
This document covers the following topics:
| 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. |
| 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:
|
| 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' |
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.
| 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. |
Note:
If the hyperdescriptor exit returns an ISN in the ISN field of
the header element, the file must be defined with USERISN=YES to prevent ISN
reassignment when the file is later reloaded.
| 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 |
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.
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.
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.
 |
Warning: Sample user exits and programs and are not supported under any maintenance contract agreement. |
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.