The BT command removes database updates for ET logic users.
We recommend that you set unused ACB and ACBX fields to binary zeros before the direct call is initiated.
This document covers the following topics:
The BT command is used to remove all database modifications (adds, deletes, updates) performed during the user's current logical transaction. This may be necessary because of a program error or the determination that the entire transaction cannot be completed successfully. BT commands may only be issued by ET logic users.
Adabas issues an implicit ET command as the last step in the processing of a BT command. This causes the current data protection block to be physically written to the Adabas Work and the data protection log, and the release of all records which were held during the transaction.
The Command Option 1 field provides the "P" option to place all records listed in the ISN buffer in hold status. The "M" (multifetch) option releases a subset of the records held by the current transaction. The records to be released from hold status are specified in the ISN buffer. The first fullword in the buffer specifies the number of 8-byte elements following.
The Command Option 2 field provides the "F" (exclude file) option to exclude a single file from backout processing. The updates performed to the file specified will not be backed out. Any records in the file that are in hold status for the user will, however, be released.
This section describes ACB interface direct calls for the BT command. It covers the following topics:
| Field | Position | Format | Before Adabas Call | After Adabas Call |
|---|---|---|---|---|
| 1-2 | -- | -- | -- | |
| Command Code | 3-4 | alphanumeric | F | U |
| Command ID | 5-8 | binary | -- | A |
| File Number * | 9-10 | binary | F * | U |
| Response Code | 11-12 | binary | -- | A |
| 13-16 | -- | -- | -- | |
| ISN Lower Limit | 17-20 | binary | F | U |
| 21-32 | -- | -- | -- | |
| ISN Buffer Length ** | 33-34 | binary | F ** | U |
| Command Option 1 | 35 | alphanumeric | F | U |
| Command Option 2 | 36 | alphanumeric | F | U |
| 37-72 | -- | -- | -- | |
| Command Time | 73-76 | binary | -- | A |
| User Area | 77-80 | -- | -- | U |
| Buffer | Before Adabas Call | After Adabas Call |
|---|---|---|
| ISN ** | F | U |
where:
| F | Supplied by user before Adabas call |
| A | Supplied by Adabas |
| U | Unchanged after Adabas call |
| * | Required only if Command Option 2 is specified |
| ** | Required only if Command Option 1 is specified |
| -- | Not used |
We recommend that you set unused ACB fields to binary zeros before the direct call is initiated.
- Command Code (ACBCMD)
BT
- Command ID (ACBCID)
In this field, Adabas returns the transaction sequence number of the transaction that has been backed out. The number is returned in binary format.
- File Number (ACBFNR)
If a file is to be excluded from backout processing, the number of the file to be excluded must be specified in this field, and option F must be specified in the Command Option 2 field.
If no file is to be excluded (option F is not specified), any value specified in the file number field is disregarded.
Note:
When using two-byte file numbers and database IDs, a X'30' must be coded in the first byte of the control block.- Response Code (ACBRSP)
In this field, Adabas returns the response code for the command. Response code 0 (ADARSP000) indicates that the command was executed successfully. If the BT command returns a non-zero response code, the rightmost two bytes of the Adabas control block, bytes 45 - 48 (Additions 2 field) may contain a subcode defining the exact response code meaning. Response codes and their subcodes are defined in the Adabas Messages and Codes Manual documentation.
- ISN Lower Limit (ACBISL)
If the hold ISNs option is specified, this field must contain the count of six-byte ISN buffer entries.
- ISN Buffer Length (ACBIBL)
The ISN buffer length (in bytes). This length is required only if the hold ISNs or multifetch option is used (see the Command Option 1 field description). If the multifetch feature is specified, this value must be less than 32 KB.
- Command Option 1: Hold ISNs Option (ACBCOP1)
Note:
If multifetch is set with ADARUN PREFETCH=YES, the "P" option is automatically used for ET/BT commands (the "M" option is automatically used for all other commands). You cannot override this option setting by using this field.By default as part of BT command execution, Adabas releases all ISNs currently held by the user.
Option Description P Places all or a portion of these ISNs back into hold status. The ISNs to be returned to hold status must be provided in the ISN buffer, and the ISN count must be specified in the ISN lower limit field. M (command-level multifetch) Releases only a subset instead of all of the ISNs held by the current transaction. The records to be released from hold status are specified in the ISN buffer.The first fullword in the buffer specifies the number of 8-byte elements following. - Command Option 2: Exclude File Option (ACBCOP2)
Option Description F (exclude file) Excludes the single file specified in the file number field from backout processing. The updates performed to the specified file are not backed out but committed. Any records in the file that are in hold status for the user are released. blanks All files are to be included in backout processing.
The current user transaction is to be backed out. All files are to be included in the backout process.
| Command Code | BT | |
|---|---|---|
| Command Option 1 | blank | no ISNs are held |
| Command Option 2 | b | file exclude option not used |
The current user transaction is to be backed out. Updates made to file 4 are not to be included in the backout process.
| Command Code | BT | |
|---|---|---|
| File Number | 4 | file 4 to be excluded from backout |
| Command Option 2 | F | file exclude option used |
The current user transaction is to be backed out. ISNs 1, 2, and 3 which are contained in file 6 are to be placed into hold status.
| Command Code | BT | |
|---|---|---|
| Command Option 1 | P | place ISNs into hold status option |
| Command Option 2 | b | file exclude option not used |
| ISN Buffer | |
|---|---|
| 000600000001 | ISN 1 |
| 000600000002 | ISN 2 |
| 000600000003 | ISN 2 |
This section describes ACBX interface direct calls for the BT command. It covers the following topics:
| Field | Position | Format | Before Adabas Call | After Adabas Call |
|---|---|---|---|---|
| 1-2 | --- | --- | --- | |
| Version Indicator | 3-4 | binary | F | U |
| 5-6 | binary | --- | --- | |
| Command Code | 7-8 | alphanumeric | F | U |
| 9-10 | --- | --- | --- | |
| Response Code | 11-12 | binary | --- | A |
| Command ID | 13-16 | alphanumeric/ binary | --- | A |
| Database ID* | 17-20 | numeric | F* | U |
| File Number* | 21-24 | numeric | F* | U |
| 25-36 | --- | --- | --- | |
| ISN Lower Limit | 37-40 | binary | F | U |
| 45-48 | --- | --- | --- | |
| Command Option 1 | 49 | alphanumeric | F | U |
| Command Option 2 | 50 | alphanumeric | F | U |
| Command Option 3 | 51 | alphanumeric | F | U |
| 52-114 | --- | --- | --- | |
| Error Subcode | 115-116 | binary | --- | A |
| 117-144 | --- | --- | --- | |
| Command Time | 145-152 | binary | --- | A |
| User Area | 153-168 | not applicable | --- | U |
| 169-193 | --- | --- | --- |
| ABD and Buffer | Before Adabas Call | After Adabas Call |
|---|---|---|
| ISN ** | F | U |
where:
| F | Supplied by user before Adabas call |
| A | Supplied by Adabas |
| U | Unchanged after Adabas call |
| * | Required only if Command Option 2 is specified |
| ** | Required only if Command Option 1 is specified |
| --- | Not used |
We recommend that you set unused ACBX fields to binary zeros before the direct call is initiated.
- Version Indicator (ACBXVER)
F2
- Command Code (ACBXCMD)
BT
- Response Code (ACBXRSP)
Adabas returns the response code for the command in this field. Response code 0 (ADARSP000) indicates that the command was executed successfully. Non-zero response codes, which can also have accompanying subcodes returned in the Error Subcode (ACBXERRC) field, are described in the Adabas Messages and Codes Manual documentation.
- Command ID (ACBXCID)
In this field, Adabas returns the transaction sequence number of the transaction that has been backed out. The number is returned in binary format.
- Database ID (ACBXDBID)
Use this field to specify the database ID of the file to be excluded from backout processing. 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.
- File Number (ACBXFNR)
Use this field to specify the number of the file to be excluded from backout processing (option F must be specified in the Command Option 2 field).
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.
If no file is to be excluded (option F is not specified in Command Option 2), any value specified in the file number field is disregarded.
- ISN Lower Limit (ACBXISL)
If the hold ISNs option is specified, this field must contain the count of six-byte ISN buffer entries.
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.
- Command Option 1: Hold ISNs Option (ACBXCOP1)
By default as part of BT command execution, Adabas releases all ISNs currently held by the user.
Option Description P Places all or a portion of these ISNs back into hold status. The ISNs to be returned to hold status must be provided in the ISN buffer, and the ISN count must be specified in the ISN lower limit field. M (command-level multifetch) Releases only a subset instead of all of the ISNs held by the current transaction. The records to be released from hold status are specified in the ISN buffer. The first fullword in the buffer specifies the number of 8-byte elements following. - Command Option 2: Exclude File Option (ACBXCOP2)
Option Description F (exclude file) Excludes the single file specified in the file number field from backout processing. The updates performed to the specified file are not backed out but committed. Any records in the file that are in hold status for the user are released. blanks All files are to be included in backout processing. - Command Option 3: Shared Hold Status (ACBXCOP3)
Option Description H Keeps the record in shared hold status indefinitely. Records in shared hold status at the time of the BT command are kept in shared hold status beyond the end of the transaction until another ET or BT command is issued (without this H option or the prefetch or multifetch options). Any records in exclusive hold status are also changed to shared hold status beyond the end of the transaction. You cannot use option H if the multifetch or prefetch options are used (or, in Adabas on open systems, if all resources owned by the user are to be released via a command option 1 "T" setting).
For complete information about shared hold updating, read Shared Hold Status.
- Error Subcode (ACBXERRC)
If the command returns a nonzero response code, this field contains a subcode defining the exact response code meaning. Response codes and their subcodes are defined in the Adabas Messages and Codes Manual documentation.
If the Command Option 1 field is set to "P", each ISN whose record is to be returned to hold status must be provided as a six-byte binary entry in which:
the first two bytes specify the number of the file containing the record; and
the next four bytes contain the ISN of the record to be held.
If the Command Option 1 field is set to "M", only a subset of the records held by the current transaction are to be released. The first fullword in the ISN buffer specifies the number of eight-byte elements, and each following eight-byte group is interpreted as one file number/ISN identifier of records to be released from hold status (read BT/ET Multifetch Processing).