HI Command: Hold Record

#### Search Results

Search

# HI Command: Hold Record

The HI command prevents record update by other 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:

- Function and Use

- ACB Interface Direct Call: HI Command

- ACBX Interface Direct Call: HI Command

## Function and Use

The HI command is used to place a record in hold status. This command is used to hold a record for subsequent updating without allowing other users to update the record until it is released.

Specify the file number and ISN of the record to be held.

If the record to be held is currently being held by another user, the action taken by Adabas is controlled by the setting of the Command Option 1 field in the Adabas control block. If the Command Option 1 field:

- contains an "R", Adabas returns response code 145 (ADARSP145) if the record to be held is not available;

- does not contain an "R", Adabas places the user in wait status until the record becomes available, at which time the user is reactivated automatically.

## ACB Interface Direct Call: HI Command

This section describes ACB interface direct calls for the HI command. It covers the following topics:

- Control Block and Buffer Overview

- Control Block Field Descriptions

- ACB Example

### Control Block and Buffer Overview

#### Control Block

Field | Position | Format | Before Adabas Call | After Adabas Call
--- | --- | --- | --- | ---
| 1-2 | -- | -- | --
Command Code | 3-4 | alphanumeric | F | U
| 5-8 | -- | -- | --
File Number | 9-10 | binary | F | U
Response Code | 11-12 | binary | -- | A
ISN | 13-16 | binary | F | U
| 17-34 | -- | -- | --
Command Option 1 | 35 | alphanumeric | F | U
| 36-72 | -- | -- | --
Command Time | 73-76 | binary | -- | A
User Area | 77-80 | -- | -- | U

#### Buffer Areas

None used.

where:

F | Supplied by user before Adabas call
A | Supplied by Adabas
U | Unchanged after Adabas call
-- | Not used

### Control Block Field Descriptions

We recommend that you set unused ACB fields to binary zeros before the direct call is initiated.

> Command Code (ACBCMD)

>   HI

> File Number (ACBFNR)

>   The number of the file that contains the record to be held.

>   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 HI command returns a non-zero response code, the rightmost two bytes of 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 (ACBISN)

>   The ISN of the record to be placed in hold status.

> Command Option 1: Response Code 145 (ADARSP145) if Record Not Available (ACBCOP1)

>   If the record to be held is currently being held by another user, the action taken by Adabas is controlled by the setting of the Command Option 1 field:

>   Option | Description
>   --- | ---
>   R (return) | Causes Adabas to return response code 145 (ADARSP145) if the record to be held is not available. The command is not placed in wait status.

>   Otherwise, Adabas places the command in wait status until either the record becomes available, at which time command and user are reactivated automatically, or the transaction times out.

### ACB Example

The record identified by ISN 3 in file 2 is to be placed in hold status. Control is not to be returned until the record is available.

#### Control Block

Command Code | HI |
File Number | 2 | record to be held is in file 2
ISN | 3 | record with ISN 3 to be held
Command Option 1 | b | response code 145 (ADARSP145) option not used

## ACBX Interface Direct Call: HI Command

This section describes ACBX interface direct calls for the HI command. It covers the following topics:

- Control Block and Buffer Overview

- Control Block Field Descriptions

### Control Block and Buffer Overview

#### Control Block

Field | Position | Format | Before Adabas Call | After Adabas Call
--- | --- | --- | --- | ---
| 1-2 | --- | --- | ---
Version Indicator | 3-4 | binary | F | U
| 5-6 | --- | --- | ---
Command Code | 7-8 | alphanumeric | F | U
| 9-10 | --- | --- | ---
Response Code | 11-12 | binary | --- | A
--- | 13-16 | --- | --- | ---
Database ID | 17-20 | numeric | F | U
File Number | 21-24 | numeric | F | U
| 25-28 | --- | --- | ---
ISN | 29-32 | binary | F | U
| 33-48 | --- | --- | ---
Command Option 1 | 49 | alphanumeric | F | U
| 50 | --- | --- | ---
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 | do not touch | --- | ---

#### Buffer Areas

None used.

where:

F | Supplied by user before Adabas call
A | Supplied by Adabas
U | Unchanged after Adabas call
-- | Not used

### Control Block Field Descriptions

We recommend that you set unused ACBX fields to binary zeros before the direct call is initiated.

> Version Indicator (ACBXVER)

>   F2

> Command Code (ACBXCMD)

>   HI

> 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.

> Database ID (ACBXDBID)

>   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.

> File Number (ACBXFNR)

>   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.

> ISN (ACBXISN)

>   Use this field to specify the ISN of the record to be placed in hold status.

>   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.

> Command Option 1: Response Code 145 (ADARSP145) if Record Not Available (ACBXCOP1)

>   If the record to be held is currently being held by another user, the action taken by Adabas is controlled by the setting of the Command Option 1 field:

>   Option | Description
>   --- | ---
>   R (return) | Causes Adabas to return response code 145 (ADARSP145) if the record to be held is not available. The command is not placed in wait status.

>   Otherwise, Adabas places the command in wait status until either the record becomes available, at which time command and user are reactivated automatically, or the transaction times out.

> Command Option 3: Shared Hold Status (ACBXCOP3)

>   Option | Description
>   --- | ---
>   S | Puts the record in shared hold status until the end of the transaction. The record is placed in shared hold status only if the record is not already in hold status.

>   If the same record is placed in shared hold status more than once (using the C or S options or the Q option for different read sequences), it stays in shared hold status until all of the specified hold lifetimes have expired.

>   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.

### On this page

- Function and Use
- ACB Interface Direct Call: HI Command
- ACBX Interface Direct Call: HI Command