Two kinds of control blocks are now supported by Adabas:
The Adabas control block (ACB) is the classic control block, used for Adabas releases prior to Adabas version 8. If you have been using releases of Adabas prior to Adabas 8, the direct calls used by your applications use the ACB. It is important to note that Adabas 8 fully supports the ACB, so you are not required to update your existing applications once you install Adabas 8.
The extended Adabas control block (ACBX) can be used in Adabas releases starting with Adabas 8. The ACBX supports the increased buffer sizes and segmented buffers introduced in Adabas 8. If you have purchased and installed Adabas 8 (or later), you can use the ACBX in direct calls from your applications. Otherwise, you cannot.
The use of each applicable field in the control blocks is explained with each Adabas command in Commands. To ensure user program compatibility with later Adabas releases, all control block fields not used by a particular command should be set to zeros or blanks, depending on field type.
The position of each field in a control block is fixed. In addition, all values in the control block must be entered in the data type defined for the field. For example, the ISN field is defined as binary format; therefore, any entry made in this field must be in binary format.
Notes:
This document covers the following topics:
The Adabas control block (ACB) is 80 bytes long . This section covers the following topics:
The following table describes the format of the ACB. We recommend that you set unused ACB fields to binary zeros before the direct call is initiated.
| DSECT Name | Field | Control Block Position | Offset | Length (in Bytes) | Format |
|---|---|---|---|---|---|
| ACBTYPE | Call Type | 1 | 00 | 1 | binary |
| reserved | (reserved) | 2 | 01 | 1 | binary |
| ACBCMD | Command Code | 3-4 | 02 | 2 | alphanumeric |
| ACBCID | Command ID | 5-8 | 04 | 4 | alphanumeric / binary |
| ACBFNR | File Number | 9-10 | 08 | 2 | binary |
| ACBRSP | Response Code | 11-12 | 0A | 2 | binary |
| ACBISN | ISN | 13-16 | 0C | 4 | binary |
| ACBISL | ISN Lower Limit | 17-20 | 10 | 4 | binary |
| ACBISQ | ISN Quantity | 21-24 | 14 | 4 | binary |
| ACBFBL | Format Buffer Length | 25-26 | 18 | 2 | binary |
| ACBRBL | Record Buffer Length | 27-28 | 1A | 2 | binary |
| ACBSBL | Search Buffer Length | 29-30 | 1C | 2 | binary |
| ACBVBL | Value Buffer Length | 31-32 | 1E | 2 | binary |
| ACBIBL | ISN Buffer Length | 33-34 | 20 | 2 | binary |
| ACBCOP1 | Command Option 1 | 35 | 22 | 1 | alphanumeric |
| ACBCOP2 | Command Option 2 | 36 | 23 | 1 | alphanumeric |
| ACBADD1 | Additions 1 | 37-44 | 24 | 8 | alphanumeric / binary |
| ACBADD2 | Additions 2 | 45-48 | 2C | 4 | alphanumeric / binary |
| ACBADD3 | Additions 3 | 49-56 | 30 | 8 | alphanumeric |
| ACBADD4 | Additions 4 | 57-64 | 38 | 8 | alphanumeric |
| ACBADD5 | Additions 5 | 65-72 | 40 | 8 | alphanumeric / binary |
| ACBCMDT | Command Time | 73-76 | 48 | 4 | binary |
| ACBUSER | User Area | 77-80 | 4C | 4 | not applicable |
The content of the control block fields and buffers must be set before an Adabas command (call) is issued. Adabas also returns one or more values or codes in certain fields and buffers after each command is executed.
We recommend that you set unused ACB fields to binary zeros before the direct call is initiated.
Each of the fields in the ACB is described in this section, in the order they appear in the ACB format. The descriptions are valid for most Adabas commands; however, some Adabas commands use some control block fields for purposes other than those described here. For complete information about how these fields are used by each Adabas command, read Commands.
The first byte of the Adabas control block (ADACB) is used by the Adabas API to determine the processing to be performed. For more information, read Linking Applications to Adabas.
The values for logical requests are:
| Hex | Indicates ... |
|---|---|
| X'00' | a 1-byte file number (file numbers between 1 and 255) or DBID. |
| X'30' | a 2-byte file number (file numbers between 1 and 65535) or DBID. |
| X'40' | values greater than or equal to a blank. These are accepted as "logical application calls" to maintain compatibility with earlier releases of Adabas. |
Note:
The X'44', X'48', and X'4C' calls are reserved for use by
Software AG and are therefore not accepted.
All other values in the first byte of the ADACB are reserved for use by Software AG.
Because an application can reset the value in the first byte of the ADACB on each call, it is possible to mix both one- and two-byte file number (DBID) requests in a single application. In this case, you must ensure the proper construction of the file number (ACBFNR) and response code (ACBRSP) fields in the ADACB for each call type. See the discussions of these fields for more information.
Software AG recommends that an application written to use two-byte file numbers always place X'30' in the first byte of the ADACB, the logical database ID in the ACBRSP field, and the file number in the ACBFNR field. The application can then treat both the database ID and file number as 2-byte binary integers, regardless of the value for the file number in use.
Applications written in Software AG's Natural language need not include this first byte of the Adabas ACB because Natural supplies appropriate values.
The command code defines the command to be executed, and comprises two alphanumeric characters (for example, OP, A1, BT).
The command ID field is used by many Adabas commands to identify logical read sequences, search results, and (optionally) decoded formats for use by subsequent commands. You can specify alphanumeric or binary command IDs as you choose or you can request the generation of new binary command IDs by Adabas. See the section General Programming Considerations for more information about command IDs. For ET, CL, and some OP commands, Adabas returns a binary transaction sequence number in the command ID field.
Note:
For commands that operate on a coupled file pair, this
field specifies the primary file from which ISNs or data are returned.
The file number may be one or two bytes.
For an application program issuing Adabas commands for file numbers between 1 and 255 (single byte), build the control block as follows:
| Position | Action |
|---|---|
| 1 | Place X'00' in the first byte of the ADACB. |
| 9 | Place the file number in the second (rightmost) byte of the ACBFNR field of the ADACB. The first (leftmost) byte of the ACBFNR field is used to store the logical (database) ID or number. |
If the first byte in ACBFNR is set to zero (B'0000 0000'), the Adabas API uses either the database ID from the ADARUN cards provided in DDCARD input data, or the default database ID value assembled into the link routine at offset X'80'.
Adabas permits the use of file numbers greater than 255 on logical requests. For an application program issuing Adabas commands for file numbers between 256 and 5000 (two-byte), build the control block as follows:
| Position | Action |
|---|---|
| 1 | Place X'30' in the first byte of the ADACB. |
| 9 | Use both bytes in ACBFNR for the file number, and use the two bytes in ACBRSP for the database (logical) ID. |
If the ACBRSP field is zero, the Adabas API uses either the database ID from the ADARUN cards provided in DDCARD input data, or the default database ID value assembled into the link routine at offset X'80'.
The response code field is used for two-byte database IDs.
It is also always set to a value when the Adabas command is completed. Successful completion is normally indicated by a response code of zero. For repeatable commands that process sequences of records or ISNs, other response codes indicate end-of-file or end-of-ISN-list. Non-zero response codes are defined in the Adabas Messages and Codes.
The ISN field both specifies a required four-byte Adabas ISN value required by the command and, where appropriate, returns either the first ISN of a command-generated ISN list, or an ISN of the record read by the command.
ISN lower limit specifies the starting point in an ISN list or range where processing is to begin. When using the multifetch option, this field holds an optional maximum count of prefetched records to return; if zero, there is no limit.
Following successful OP command completion, Adabas returns its system, call type, and nucleus ID (nucid) information in this field; the timeout information previously held here is returned in the Additions 5 field, bytes 4 and 5. See the section Values Returned in Control Block Fields for detailed information.
The ISN quantity field is a count of ISNs returned by a command. The count can be a total of all ISNs in an ISN list, or the total ISNs entered into the ISN buffer from a larger pool of ISNs by this operation.
Following successful OP command completion, Adabas returns its system release information in this field; the timeout information previously held here is returned in the Additions 5 field, bytes 6 and 7. See the section Values Returned in Control Block Fields for detailed information.
In addition, Sx commands using security-by-value set this field to 1 when more than one ISN meet the search criteria.
The format, record, search, value, and ISN buffer length fields specify the size of the related buffers. A buffer's size usually remains the same throughout a transaction. In some ISN-related operations, the ISN buffer size value determines how a command processes ISNs; for example, specifying a zero ISN buffer length causes some commands to store a resulting ISN list in the Adabas work area. If a buffer is not needed for an Adabas command, the corresponding length value should be set to zero. In some cases (multifetch option, as an example), there is a limit on the length of the buffer; see the specific command descriptions for more information.
The Command Option 1 and 2 fields allow you to specify processing options (ISN hold, command-level prefetching control, returning of ISNs, and so on).
The Additions 1 field sometimes requires miscellaneous command-related parameters such as qualifying descriptors for creating ISN lists, or the second file number of a coupled file pair.
The Additions 2 field returns the compressed record length in the leftmost (high-order) two bytes and decompressed length of record buffer-selected fields in the rightmost (low-order) two bytes for all An, Ln, Nn, and S1/2/4 commands. The OP (open) and RE (read ET data) commands return transaction sequence numbers in this field. If Entire Net-work is installed, some response codes return the node ID of the "problem" node in the leftmost two bytes of the Additions 2 field.
If a command results in a nucleus response code, the Additions 2 field's low-order (rightmost) two bytes (47 and 48) can contain a hexadecimal subcode to identify the cause of the response code. For example, if no OP command began the session and the ADARUN statement specified OPENRQ=YES, a response code 9 (ADARSP009), subcode 66 is returned and these bytes are set to the hexadecimal value 0042 corresponding to the decimal 66. Response codes and their subcodes (as decimal equivalents) are described in the section Nucleus Response Codes in the Adabas Messages and Codes.
Note:
If you are running with Entire Net-Work, the leftmost two
bytes of the ACB Additions 2 field (ACBADD2) may contain the ID of the Entire
Net-Work node that issued this response code.
The Additions 3 field is for providing a user`s password for accessing password-protected files. If the file containing the field is actually password-protected, the password in this field is replaced with spaces (blanks) during command execution before Adabas returns control to the user program.
The Additions 4 field must be set to a cipher code for those instructions that read or write encrypted (ciphered) database data files. For commands requiring multiple command IDs but no cipher code, one of the command IDs is specified in this field.
When processed by the nucleus, an Adabas call returns the Adabas release (version and revision) level numbers and the database ID in the low-order (rightmost) three bytes of the Additions 4 field with the format vrnnnn where
| v | is the Adabas version number; |
| r | is the Adabas revision level number; and |
| nnnn | is the number (hexadecimal) of the Adabas database that processed the call. |
For example, "741111" indicates that an Adabas version 7.4 nucleus on database 4369 processed the call.
The high-order (leftmost) two bits of the first byte of the Additions 5 field control the unique or global format ID selection; the low-order (rightmost) four or eight bytes can contain either an optional unique or global format ID, respectively. Refer to the section Using a Global Format ID for a complete description of this feature. A global format ID to be deleted can be specified in this field for the RC (release command ID) command. When completed, the OP command returns any optionally specified non-activity and/or transaction timeout values in the Additions 5 field.
The command time field is used by Adabas to return the elapsed time which was needed by the nucleus to process the command. This does not include the times when the thread was waiting on Adabas I/O operations or other resources. The time, counted in 16-microsecond units, is called "Adabas thread time". The returned count is in binary format.
The user area field is reserved for use by the user program. When making logical user calls, the user area is neither written nor read by Adabas.
For compatibility with future Adabas releases, Software AG recommends that you set unused control block fields to null values corresponding to the field's data type.
The ACB DSECT can be found in member ADACB of the distributed Adabas SRCE library.
Programming examples that show control block construction in a variety of host languages are provided in section Programming Examples of this documentation.
The extended Adabas control block , the ACBX, supports the increase in the buffer sizes in Adabas commands. It is 192 bytes in length (versus the 80 bytes used by the ACB). The existing, non-extended Adabas Control Block (ACB) is still supported and your existing applications will still work, but if you want to take advantage of some of the extended features provided in Adabas 8, you must use the new ACBX. Specifically, you must use the ACBX if you are using the long buffer (buffers longer than 32K) or segmented buffer (multiple format/record buffer pairs or format/record/multifetch buffer triplets) features of Adabas 8.
Otherwise, your application programs may freely switch between Adabas calls using the existing direct call interface (ACB) and calls using the new interface (ACBX).
The following table describes the format of the ACBX. We recommend that you set unused ACBX fields to binary zeros before the direct call is initiated.
| DSECT Field Name | Field | Control Block Position | Offset | Length (in bytes) | Format |
|---|---|---|---|---|---|
| ACBXTYP | Call Type | 1 | 00 | 1 | binary |
| ACBXRSV1 | Reserved 1 | 2 | 01 | 1 | binary |
| ACBXVER | Version Indicator | 3-4 | 02 | 2 | binary |
| ACBXLEN | ACBX Length | 5-6 | 04 | 2 | binary |
| ACBXCMD | Command Code | 7-8 | 06 | 2 | alphanumeric |
| ACBXRSV2 | Reserved 2 | 9-10 | 08 | 2 | binary |
| ACBXRSP | Response Code | 11-12 | 0A | 2 | binary |
| ACBXCID | Command ID | 13-16 | 0C | 4 | alphanumeric/ binary |
| ACBXDBID | Database ID | 17-20 | 10 | 4 | numeric |
| ACBXFNR | File Number | 21-24 | 14 | 4 | numeric |
| ACBXISNG | 8-Byte ISN | 25-32 | 18 | 8 | do not use |
| ACBXISN | ISN | 29-32 | 1C | 4 | binary |
| ACBXISLG | 8-Byte ISN Lower Limit | 33-40 | 20 | 8 | do not use |
| ACBXISL | ISN Lower Limit | 37-40 | 24 | 4 | binary |
| ACBXISQG | 8-Byte ISN Quantity | 41-48 | 28 | 8 | do not use |
| ACBXISQ | ISN Quantity | 45-48 | 2C | 4 | binary |
| ACBXCOP1 | Command Option 1 | 49 | 30 | 1 | alphanumeric |
| ACBXCOP2 | Command Option 2 | 50 | 31 | 1 | alphanumeric |
| ACBXCOP3 | Command Option 3 | 51 | 32 | 1 | alphanumeric |
| ACBXCOP4 | Command Option 4 | 52 | 33 | 1 | alphanumeric |
| ACBXCOP5 | Command Option 5 | 53 | 34 | 1 | alphanumeric |
| ACBXCOP6 | Command Option 6 | 54 | 35 | 1 | alphanumeric |
| ACBXCOP7 | Command Option 7 | 55 | 36 | 1 | alphanumeric |
| ACBXCOP8 | Command Option 8 | 56 | 37 | 1 | alphanumeric |
| ACBXADD1 | Additions 1 | 57-64 | 38 | 8 | alphanumeric/ binary |
| ACBXADD2 | Additions 2 | 65-68 | 40 | 4 | binary |
| ACBXADD3 | Additions 3 | 69-76 | 44 | 8 | alphanumeric/ binary |
| ACBXADD4 | Additions 4 | 77-84 | 4C | 8 | alphanumeric |
| ACBXADD5 | Additions 5 | 85-92 | 54 | 8 | alphanumeric/ binary |
| ACBXADD6 | Additions 6 | 93-100 | 5C | 8 | alphanumeric/ binary |
| ACBXRSV3 | Reserved 3 | 101-104 | 64 | 4 | binary |
| ACBXERRG | Error Offset in Buffer (64-bit) | 105-112 | 68 | 8 | do not use |
| ACBXERRA | Error Offset in Buffer (32-bit) | 109-112 | 6C | 4 | binary |
| ACBXERRB | Error Character Field | 113-114 | 70 | 2 | alphanumeric |
| ACBXERRC | Error Subcode | 115-116 | 72 | 2 | binary |
| ACBXERRD | Error Buffer ID | 117 | 74 | 1 | alphanumeric |
| ACBXERRE | Reserved for future use | 118 | 75 | 1 | do not use |
| ACBXERRF | Error Buffer Sequence Number | 119-120 | 76 | 2 | numeric |
| ACBXSUBR | Subcomponent Response Code | 121-122 | 78 | 2 | binary |
| ACBXSUBS | Subcomponent Response Subcode | 123-124 | 7A | 2 | binary |
| ACBXSUBT | Subcomponent Error Text | 125-128 | 7C | 4 | alphanumeric |
| ACBXLCMP | Compressed Record Length | 129-136 | 80 | 8 | binary |
| ACBXLDEC | Decompressed Record Length | 137-144 | 88 | 8 | binary |
| ACBXCMDT | Command Time | 145-152 | 90 | 8 | binary |
| ACBXUSER | User Area | 153-168 | 98 | 16 | not applicable |
| ACBXRSV4 | Reserved 4 | 169-193 | A8 | 24 | do not touch |
The content of the control block fields and buffers must be set before an Adabas command (call) is issued. Adabas also returns one or more values or codes in certain fields and buffers after each command is executed.
We recommend that you set unused ACBX fields to binary zeros before the direct call is initiated.
Each of the fields in the ACBX is described in this section, in the order they appear in the ACBX format. The descriptions are valid for most Adabas commands; however, some Adabas commands use some control block fields for purposes other than those described here. For complete information about how these fields are used by each Adabas command, read Commands.
The first byte of the Adabas control block (ADACBX) is used by the Adabas API to determine the processing to be performed. See Linking Applications to Adabas in the Adabas Operations documentation for more information.
When issuing an Adabas command, set this field to binary zeros. This indicates that a logical user call is being made (ACBXTUSR equate).
The following values in ACBXTYPE are reserved for use by Software AG and are therefore not accepted by application programs: X'04', X'08', X'0c', X'10', X'14', X'18', X'1c', X'20', X'24', X'28', X'2c', X'34', X'38', X'3c', X'44', X'48', and X'4c'.
Applications written in Software AG's Natural language need not include this first byte of the Adabas ACBX because Natural supplies appropriate values.
This field is reserved. Set this field to zero.
The version indicator identifies whether the Adabas control block uses the new ACBX or the classic ACB format. If this field is set to a value starting with the letter "F" (for example "F2"), Adabas treats the Adabas control block as though it is specified in the ACBX format. If this field is set to any other value, Adabas treats the control block as though it is specified in the classic ACB format.
The ACBX length field should be set to the length of the ACBX structure passed to Adabas (the ACBXQLL equate, currently 192).
The command code defines the command to be executed, and comprises two alphanumeric characters (for example, OP, A1, BT).
This field is reserved. Set this field to zero.
This field gets set to a value when the Adabas command is completed. Successful completion is normally indicated by a response code of zero. For repeatable commands that process sequences of records or ISNs, other response codes indicate end-of-file or end-of-ISN-list. Non-zero response codes are defined in the Adabas Messages and Codes documentation.
The command ID field is used by many Adabas commands to identify logical read sequences, search results, and (optionally) decoded formats for use by subsequent commands. You can specify alphanumeric or binary command IDs as you choose or you can request the generation of new binary command IDs by Adabas. See the section General Programming Considerations for more information about command IDs. For ET, CL, and some OP commands, Adabas returns a binary transaction sequence number in the command ID field.
Use this field to specify the database ID. The Adabas call will be directed to this database.
This field is a four-byte binary field, but at this time only two-byte database IDs are supported. Therefore, the database ID should be specified in the low-order part (rightmost bytes) of the field, with leading binary zeros.
If this field is set to binary zeros, the Adabas API uses either the database ID from the ADARUN cards provided in DDCARD input data or the default database ID value provided in the LNKGBLS module linked with or loaded by the link routine.
Use this field to specify the number of the file to which the Adabas call should be directed.
This field is a four-byte binary field, but the file number should be specified in the low-order part (rightmost bytes) of the field, with leading binary zeros.
Note:
For commands that operate on a coupled file pair, this
field specifies the primary file from which ISNs or data are returned.
The ISN field specifies any required Adabas ISN value required by the command and, where appropriate, returns either the ISN of the record read by the command , or the first ISN of an ISN list generated by the command.
The ACBXISN field is a four-byte binary field embedded in the eight-byte ACBXISNG field, which is not yet used. Set the high-order part of the ACBXISNG field to binary zeros.
ISN lower limit specifies the starting point in an ISN list or range where processing is to begin. When using the multifetch option, this field holds an optional maximum count of prefetched records to return; if zero, there is no limit.
Following successful OP command completion, Adabas returns its system, call type, and nucleus ID (nucid) information in this field; the timeout information previously held here is returned in the Additions 5 field, bytes 4 and 5. See the section Values Returned in Control Block Fields for detailed information.
The ACBXISL field is a four-byte binary field embedded in the eight-byte ACBXISLG field, which is not yet used. Set the high-order part of the ACBXISLG field to binary zeros.
The ISN quantity field is a count of ISNs returned by a search (Sx) command. The count can be a total of all ISNs in an ISN list, or the total ISNs entered into the ISN buffer from a larger pool of ISNs by this operation.
Following successful OP command completion, Adabas returns its system release information in this field; the timeout information previously held here is returned in the Additions 5 field, bytes 6 and 7. See the section Values Returned in Control Block Fields for detailed information.
In addition, Sx commands using security-by-value set this field to 1 when more than one ISN meet the search criteria.
The ACBXISQ field is a four-byte binary field embedded in the eight-byte ACBXISQG field, which is not yet used. Set the high-order part of the ACBXISQG field to binary zeros.
The Command Option 1 - 8 fields allow you to specify processing options (ISN hold, command-level prefetching control, returning of ISNs, and so on). In Adabas 8.1, only the Command Option 1 and Command Option 2 field are supported. However, the other Command Option fields are provided for potential expansion in future Adabas releases.
The Additions 1 field sometimes requires miscellaneous command-related parameters such as qualifying descriptors for creating ISN lists, or the second file number of a coupled file pair.
OP (open) and RE (read ET data) commands return transaction sequence numbers in this field.
The Additions 3 field is for providing a user's password for accessing password-protected files. This field is always reset to blanks during command execution.
If a command reads or writes records of an encrypted (ciphered) Adabas file, the Additions 4 field must be set to the cipher code for that file. For commands requiring multiple command IDs but no cipher code, one of the command IDs is specified in this field.
Adabas always resets this field to blanks during command execution.
When processed by a nucleus that is not running single-user mode (ADARUN MODE=SINGLE is not specified), the Adabas call returns the Adabas release (version and revision) level numbers and the database ID in the low-order (rightmost) three bytes of the Additions 4 field with the format vrnnnn where
| v | is the Adabas version number; |
| r | is the Adabas revision level number; and |
| nnnn | is the number (hexadecimal) of the Adabas database that processed the call. |
For example, "811111" indicates that an Adabas version 8.1 nucleus on database 4369 processed the call.
The high-order (leftmost) two bits of the first byte of the Additions 5 field control the unique or global format ID selection; the low-order (rightmost) four or eight bytes can contain either an optional unique or global format ID, respectively. A global format ID to be deleted can be specified in this field for the RC (release command ID) command. When completed, the OP command returns any optionally specified non-activity or transaction timeout values in the Additions 5 field.
This field is not used at this time. It must be set to binary zeros.
This field is reserved. Set this field must be set to binary zeros.
The Error Offset in Buffer (64-bit) and the Error Offset in Buffer (32-bit) fields specify the offset in the buffer, if any, where the error is detected during the direct call.
The Error Offset in Buffer (64-bit) field, ACBXERRG, is not yet available, but may be used in some later release. For now, use the Error Offset in Buffer (32-bit) field, ACBXERRA.
The ACBXERRx fields are only set when a response code is returned from a direct call. The ACBXERRA, ACBXERRD, and ACBXEFFE fields are only set when the response code is related to buffer processing.
The Error Offset in Buffer (64-bit) and the Error Offset in Buffer (32-bit) fields specify the offset in the buffer, if any, where the error is detected during the direct call.
The Error Offset in Buffer (64-bit) field, ACBXERRG, is not yet available, but may be used in some later release. For now, use the Error Offset in Buffer (32-bit) field, ACBXERRA.
The ACBXERRx fields are only set when a response code is returned from a direct call. The ACBXERRA, ACBXERRD, and ACBXERRF fields are only set when the response code is related to buffer processing.
This field identifies the two-byte Adabas short name of the field, if any, that was being processed when the error was detected.
The ACBXERRx fields are only set when a response code is returned from a direct call.
This field stores the subcode of the error that occurred during direct call processing.
The ACBXERRx fields are only set when a response code is returned from a direct call. If Entire Net-work is installed, some response codes return the node ID of the problem node in the leftmost two bytes of this field.
This field contains the ID (from the ABDID field) of the buffer referred to by the ACBXERRA field, so that the buffer causing the error can be identified, when multiple buffers are involved.
The ACBXERRx fields are only set when a response code is returned from a direct call. The ACBXERRA, ACBXERRD, and ACBXERRF fields are only set when the response code is related to buffer processing.
This field is reserved for future use. Do not use this field at this time.
This field contains the two-byte sequence number of the buffer segment containing the error (if any) referred to by the ACBXERRA and ACBXERRD fields.
The ACBXERRx fields are only set when a response code is returned from a direct call. The ACBXERRA, ACBXERRD, and ACBXERRF fields are only set when the response code is related to buffer processing.
This field contains the response code from any error that occurred when an Adabas add-on product intercepts the Adabas command.
If the message was compressed using zEDC compression services and the attempt to decompress the message failed, subcode 1 is placed in the rightmost two bytes of this field.
This field contains the response subcode from any error that occurred when an Adabas add-on product intercepts the Adabas command.
This field contains the error text of any error that occurred when an Adabas add-on product intercepts the Adabas command.
This field returns the compressed record length when a record was read or written.
This is the length of the compressed data processed by the successful Adabas call. If the logical data storage record spans multiple physical data records, the combined length of all associated physical records may not be known. In this case, Adabas returns high values in the low-order word of this field.
This field returns the decompressed record length. This is the length of the decompressed data processed by the successful call. If multiple record buffer segments are specified, this reflects the total length across all buffer segments.
The command time (also called thread time) field is used by Adabas to return the elapsed time that was needed by the nucleus to process the command. This does not include the times when the Adabas thread executing the command was waiting on Adabas I/O operations or other resources; it does include the times when the thread was waiting for a processor so it could execute the code. The time is measured in 1/4096 microsecond units and the returned count is in binary format.
The user area field is reserved for use by the user program. When making logical user calls, the user area is neither written nor read by Adabas.
This field is reserved for use by Adabas. Your user program should set this field to binary zeros before the first Adabas call using this ACBX and then leave it unmodified thereafter.
The ACBX DSECT can be found in member ADACBX of the distributed Adabas SRCE library. For your convenience, an ACBX Format table is also provided, elsewhere in this section.
The ACBX differs in many ways from the ACB. The ACBX includes some fields that are not included in the ACB and the sizes of some ACBX fields are larger than their ACB equivalents. These expansions in the ACBX have been made to ensure that its structure can be flexible enough to handle potential future enhancements to Adabas, without altering its fundamental structure for many years.
This section describes the differences between the ACB and the ACBX:
The ACBX is 192 (or X’C0’) bytes in length; the ACB is 80 bytes long.
The buffer length fields are not included in the ACBX as they are in the ACB. When using the ACBX direct call interface, they are instead provided in the individual Adabas buffer descriptions (ABDs). So the ACBX contains no buffer fields corresponding to the ACBFBL, ACBIBL, ACBRBL, ACBSBL, and ACBVBL found in the ACB; the ABDs associated with the call are used instead. One ABD represents an individual Adabas buffer segment. They are described in Adabas Buffer Descriptions.
The number of command option, additions, and reserved control block fields are larger in the ACBX:
The ACBX contains eight command option fields, up from the two command option fields available in the ACB.
The ACBX contains six additions fields, up from the five additions fields available in the ACB.
The ACBX contains four reserved fields, up from one reserved field available in the ACB.
Reserved ACBX fields must be set to binary zeros; the reserved 4 field (ACBXRSV4) should be initialized to binary zeros and then left unchanged.
The units used to measure command time (thread time) differ between the ACB and the ACBX. The ACB measures command time (ACBCMDT) in 16 microsecond units; the ACBX measures command time (ACBXCMDT) in 1/4096 microsecond units.
The lengths of many control block fields are larger in the ACBX. The following table summarizes these changes:
| Field Title | Length | |
|---|---|---|
| ACB | ACBX | |
| File Number | 2 | 4 |
| Database ID | 2 | 4 |
| ISN | 4 | 4 |
| ISN Lower Limit | 4 | 4 |
| ISN Quantity | 4 | 4 |
| Compressed Record Length | 4 | 8 |
| Decompressed Record Length | 4 | 8 |
| Command Time | 4 | 8 |
| User Area | 4 | 16 |
| Format Buffer Length | 2 | 4 (in the ABD) |
| Record Buffer Length | 2 | 4 (in the ABD) |
| Search Buffer Length | 2 | 4 (in the ABD) |
| Value Buffer Length | 2 | 4 (in the ABD) |
The following additional fields are available in the ACBX:
| ACBX DSECT Name | Description |
|---|---|
| ACBXADD6 | Additions 6 |
| ACBXCOP3 | Command options 3 |
| ACBXCOP4 | Command options 4 |
| ACBXCOP5 | Command options 5 |
| ACBXCOP6 | Command options 6 |
| ACBXCOP7 | Command options 7 |
| ACBXCOP8 | Command options 8 |
| ACBXDBID | The database ID. In the ACB, the database ID is stored in the response code field (ACBRSP) for X’30’ calls and in the first byte of ACBFNR for other logical calls. |
| ACBXERRA | Error offset into the buffer (32-bit). |
| ACBXERRB | Error character field (field name). |
| ACBXERRC | Error subcode. In the ACB, the error subcode is stored in the Additions 2 field (ACBADD2). |
| ACBXERRD | Error buffer ID, if multiple buffers are involved. |
| ACBXERRE | Error buffer sequence number, if multiple buffers are involved. |
| ACBXERRG | Error offset into the buffer (64-bit) - this field is not yet supported. |
| ACBXLCMP | Compressed record length (or portion of record if the entire record is not read). In the ACB, the compressed record length is stored in the Additions 2 field (ACBADD2). |
| ACBXLDEC | Decompressed record length. In the ACB, the decompressed record length is stored in the Additions 2 field (ACBADD2). |
| ACBXLEN | The length of the ACBX, currently 192 |
| ACBXRSV2 | Reserved. The value of this field must be set to zero. |
| ACBXRSV3 | Reserved. The value of this field must be set to zero. |
| ACBXRSV4 | Reserved for use by Adabas. |
| ACBXSUBR | Subcomponent response code, used by Adabas add-on products. |
| ACBXSUBS | Subcomponent response subcode, used by Adabas add-on products. |
| ACBXSUBT | Subcomponent error text, used by Adabas add-on products. |
| ACBXVER | When set to C'F2', this field indicates to Adabas that the new extended ACB (ACBX) is used. |
There are a number of cases where an ACB field that has multiple purposes has been split out into additional fields in the ACBX:
In the ACB, the Response code field (ACBRSP) is used to store the database ID for X’30’ calls. For the other logical calls the one-byte database ID was stored in the first byte of the file number field, ACBFNR. The ACBX provides a Database ID field (ACBXDBID) for this purpose.
In the ACB, the ACBADD2 field is used to retain error information for certain Adabas response codes. In the ACBX, error information fields (ACBXERR* series) are provided for this purpose.
In the ACB, the ACBADD2 field is used to return, for a successful call, the compressed and decompressed record lengths of the processed data. In the ACBX, for a successful call, the Compressed Record field (ACBXLCMP) contains the length of the compressed data processed by Adabas and the Decompressed Record field (ACBXLDEC) contains the length of the decompressed data.
The offset and sequence of ACBX fields is generally different from the corresponding ACB fields, as depicted in the following table.
| Offset | ACB DSECT Field Name | ACBX DSECT Field Name |
|---|---|---|
| 00 | ACBTYPE (Call type) | ACBXTYPE (Call type) |
| 01 | reserved | ACBXRSV1 (reserved 1) |
| 02 | ACBCMD (Command code) | ACBXVER (ACBX version indicator) |
| 04 | ACBCID (Command ID) | ACBXLEN (ACBX length) |
| 06 | (ACBCID continued) | ACBXCMD (Command code) |
| 08 | ACBFNR (File number) | ACBXRSV2 (reserved 2) |
| 0A | ACBRSP (Response code -- used for the database ID with X’30’ calls) | ACBXRSP (Response code) |
| 0C | ACBISN (ISN) | ACBXCID (Command ID) |
| 10 | ACBISL (ISN lower limit) | ACBXDBID (Database ID) |
| 14 | ACBISQ (ISN quantity) | ACBXFNR (File number) |
| 18 | ACBFBL (Format buffer length) | ACBXISNG (8-Byte ISN) |
| 1A | ACBRBL (Record buffer length) | (ACBXISNG continued) |
| 1C | ACBSBL (Search buffer length) | ACBXISN (ISN -- included in ACBXISNG) |
| 1E | ACBVBL (Value buffer length) | (ACBXISN and ACBXISNG continued) |
| 20 | ACBIBL (ISN buffer length) | ACBXISLG (8-Byte ISN Lower Limit) |
| 22 | ACBCOP1 (Command option 1) | (ACBXISLG continued) |
| 23 | ACBCOP2 (Command option 2) | (ACBXISLG continued) |
| 24 | ACBADD1 (Additions 1) | ACBXISL (ISN lower limit -- included in ACBXISLG) |
| 28 | (ACBADD1 continued) | ACBXISQG (8-Byte ISN Quantity) |
| 2C | ACBADD2 (Additions 2) | ACBXISQ (ISN quantity -- included in ACBXISQG) |
| 30 | ACBADD3 (Additions 3) | ACBXCOP1 (Command option 1) |
| 31 | (ACBADD3 continued) | ACBXCOP2 (Command option 2) |
| 32 | (ACBADD3 continued) | ACBXCOP3 (Command option 3) |
| 33 | (ACBADD3 continued) | ACBXCOP4 (Command option 4) |
| 34 | (ACBADD3 continued) | ACBXCOP5 (Command option 5) |
| 35 | (ACBADD3 continued) | ACBXCOP6 (Command option 6) |
| 36 | (ACBADD3 continued) | ACBXCOP7 (Command option 7) |
| 37 | (ACBADD3 continued) | ACBXCOP8 (Command option 8) |
| 38 | ACBADD4 (Additions 4) | ACBXADD1 (Additions 1) |
| 40 | ACBADD5 (Additions 5) | ACBXADD2 (Additions 2) |
| 44 | (ACBADD5 continued) | ACBXADD3 (Additions 3) |
| 48 | ACBCMDT (Command time) | (ACBXADD3 continued) |
| 4C | ACBUSER (User area) | ACBXADD4 (Additions 4) |
| 54 | --- | ACBXADD5 (Additions 5) |
| 5C | --- | ACBXADD6 (Additions 6) |
| 64 | --- | ACBXRSV3 (reserved 3) |
| 68 | --- | ACBXERRG (Error offset in buffer, 64-bit -- this is not yet supported). |
| 6C | --- | ACBXERRA (Error offset in buffer, 32-bit) |
| 70 | --- | ACBXERRB (Error character field) |
| 72 | --- | ACBXERRC (Error subcode) |
| 74 | --- | ACBXERRD (Error buffer ID) |
| 75 | --- | ACBXERRE (Error buffer sequence number) |
| 78 | --- | ACBXSUBR (Subcomponent response code) |
| 7A | --- | ACBXSUBS (Subcomponent response subcode) |
| 7C | --- | ACBXSUBT (Subcomponent error text) |
| 80 | --- | ACBXLCMP (Compressed record length) |
| 88 | --- | ACBXLDEC (Decompressed record length) |
| 90 | --- | ACBXCMDT (Command time) |
| 98 | --- | ACBXUSER (User area) |
| A8 | --- | ACBXRSV4 (reserved 4) |
All command logs (CLOGs) are written in a format as described in Command Log Formats.
For the sake of compatibility, the ADARUN CLOGLAYOUT (see CLOGLAYOUT : Command Logging Format parameter still exists, but logs are only written in CLOGLAYOUT=8 format.