Version 8.1.4
 —  Command Reference  —

A1 Command: Update Record

The A1 command updates records with a hold option.

This document covers the following topics:


Function and Use

The A1 command is used to change the value of one or more fields in a record. The record containing the field (or fields) to be updated is identified by the file number in which it is contained and its ISN. Specify the fields to be updated in the format buffer and provide the updating values for these fields in the record buffer. Only the fields specified are modified. All other fields in the record remain unchanged.

All necessary updating to the Associator and Data Storage is performed by Adabas.

A hold option is available to place the record in hold status before it is updated.

If the user is operating in multiuser mode, the A1 command will be executed only if the record to be updated is in hold status for the user.

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

Note:
The A4 command from previous Adabas releases is executed as an A1 command.

Top of page

ACB Interface Direct Call: A1 Command

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

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
Command ID 5-8 alphanumeric / binary F U
File Number 9-10 binary F U
Response Code 11-12 binary -- A
ISN 13-16 binary F U
ISN Lower Limit 17-20 binary -- A1
ISN Quantity 21-24 binary -- A1
Format Buffer Length 25-26 binary F U
Record Buffer Length 27-28 binary F U
  29-34 -- -- --
Command Option 1 / 2 35-36 alphanumeric F U
  37-44 -- -- --
Additions 2 45-48 alphanumeric / binary   A
Additions 3 49-56 alphanumeric F A
Additions 4 57-64 alphanumeric F A
Additions 5 65-72 alphanumeric F U
Command Time 73-76 binary -- A
User Area 77-80 -- -- U

Notes

  1. These fields are used and not reset by Adabas if coupled files are used.

Buffer Areas

Buffer Before Adabas Call After Adabas Call
Format F U
Record F U

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)

A1

Command ID (ACBCID)

If a series of records is to be updated by using a series of A1 calls, and the same fields are specified in the format buffer for each call (such as when updating a set of records resulting from a find command), this field should be set to a non-blank, non-zero value. If the A1 command is used in conjunction with an L1/L4, L2/L5, or L3/L6 command, and the same fields within each record are read and updated, the same command ID used for the read command should be used for the A1 calls. In both cases, this reduces the time needed to process each successive A1 call.

If only a single record is to be updated with a single A1 call, or the format buffer is modified between A1 calls, this field should be set to blanks.

The leftmost byte of this field may not be set to hexadecimal 'FF'.

File Number (ACBFNR)

Specify the binary number of the file to be read in this field. For physical direct calls, specify the file number as follows:

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)

Adabas returns the response code for the command in this field. Response code 0 indicates that the command was executed successfully. Non-zero response codes, which can also have accompanying subcodes returned in the rightmost half of the Additions 2 field, are described in the Adabas Messages and Codes Manual documentation.

ISN (ACBISN)

The ISN of the record to be updated.

ISN Quantity/Lower Limit (ACBISQ and ACBISL)

These fields are set to nulls following completion of the A1 operation unless coupled files are used. If coupled files are used, these fields are used by A1 processing and are not reset.

Format Buffer Length (ACBFBL)

The format buffer length (in bytes). The format buffer area defined in the user program must be as large as (or larger than) the length specified.

Record Buffer Length (ACBRBL)

The record buffer length (in bytes). The record buffer area defined in the user program must be as large as (or larger than) the length specified.

Command Option 1 and Command Option 2: Hold Record Option (ACBCOP1 and ACBCOP2)
Option Description
H An "H" in either the Command Option 1 or Command Option 2 field places the record in hold status before it is updated. If the record is currently being held by another user, the command is placed in wait status until either the record becomes available or the transaction times out-unless option "R" is also specified.
R If this option is specified, it must be specified in the Command Option 1 field and option "H" must be specified in the Command Option 2 field. Option "R" causes Adabas to return response code 145 if the record to be held is not available. The command is not placed in wait status.
Additions 2 - Length of Compressed Record - (ACBADD2)

If the command is processed successfully, the following information is returned in this field:

Additions 3 - Password - (ACBADD3)

This field is used to provide an Adabas security password. If the database, file, or fields are security protected, the user must provide a valid security password. Adabas sets the Additions 3 field to blanks during command processing to enhance password integrity.

If the accessed file is password protected, Adabas sets this field to blanks during command processing to protect the integrity of the password.

Additions 4 - Cipher Code - (ACBADD4)

This field is used to provide a cipher code. If the file is ciphered, the user must provide a valid cipher code. If the file is not ciphered, this field should be set to blanks.

Adabas sets any cipher code to blanks during command processing, and returns a version code and database ID in the rightmost (low-order) three bytes of this field. For more information, see the section Control Block Fields.

Additions 5 - Format ID, Global Format ID - (ACBADD5)

This field may be used to provide a separate format ID to identify the internal format buffer used for this command, or to provide a global format ID.

As long as the high order bit of the first byte of the Additions 5 field is not set to 1, the value provided in the command ID field will be used as the format ID as well.

If, however, this bit is set to 1, the fifth through eighth bytes of the Additions 5 field are used as the format ID.

If the two high-order (leftmost) bits of the first byte of Additions 5 field are set to one (B'11'), all eight bytes of the Additions 5 field are used as a global format ID (that is, the format ID can be used by several users at the same time).

See the section Command ID, Format ID, Global Format ID for more information and examples.

ACB Examples

For the Adabas file definitions used in all the examples in this section, see File Definitions Used in Examples.

Example 1

ISN 4 of file 1 is to be updated with the following values:

Field AA 1234
Field AB 20

Control Block

Command Code A1  
Command ID bbbb (blanks) only 1 record is to be updated
File Number 1  
ISN 4  
Format Buffer Length 10 or larger
Record Buffer Length 10 or larger
Additions 3 bbbbbbbb (blanks) file is not security protected
Additions 4 bbbbbbbb (blanks) file is not ciphered

Buffer Areas

Format Buffer AA,AB,2,U.
Record Buffer X'F1F2F3F440404040F2F0'

Example 2

A set of records (previously identified with a FIND command) in file 2 are to be updated with the following values:

Field RA ABCD
Field XB 80
Field XC 0

Control Block

Command Code A1  
Command ID ABCD a non-blank, non-zero command ID is recommended because the same fields in a series of records are being updated
File Number 2  
ISN n each ISN resulting from the previous FIND command will be inserted in this field before each call
Format Buffer Length 9 or larger
Record Buffer Length 16 or larger
Additions 3 password file 2 is security protected
Additions 4 bbbbbbbb (blanks) file is not ciphered

Buffer Areas

Format Buffer RA,XB,XC.
Record Buffer X'C1C2C3C440404040080CF0F0F0F0F0F0'

The A1 call is repeated for each ISN which resulted from the previous find command.

Top of page

ACBX Interface Direct Call: A1 Command

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

Control Block and Buffer Overview

Control Block

Field Position Format Before Adabas Call After Adabas Call
  1-2 binary --- ---
Version Indicator 3-4 binary F U
  5-6 binary --- ---
Command Code 7-8 alphanumeric F U
  9-10 binary --- ---
Response Code 11-12 binary --- U
Command ID 13-16 alphanumeric/ binary F U
Database ID 17-20 numeric F U
File Number 21-24 numeric F U
  25-28 --- --- ---
ISN 29-32 binary F U
  33-36 --- --- ---
ISN Lower Limit 37-40 binary --- A1
  41-44 --- --- ---
ISN Quantity 45-48 binary --- A1
Command Option 1 49 alphanumeric F U
Command Option 2 50 alphanumeric F U
  51-64 --- --- ---
Additions 2 65-68 binary   A
Additions 3 69-76 alphanumeric/ binary F A
Additions 4 77-84 alphanumeric F A
Additions 5 85-92 alphanumeric/ binary F U
  93-114 --- --- ---
Error Subcode 115-116 binary --- A
  117-144 --- --- ---
Command Time 145-152 binary --- A
User Area 153-168 not applicable --- U
  169-193 --- --- ---

Notes

  1. These fields are used and not reset by Adabas if coupled files are used.

ABDs and Buffers

ABD and Buffer Before Adabas Call After Adabas Call
Format F U
Record F U

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)

A1

Response Code (ACBXRSP)

Adabas returns the response code for the command in this field. Response code 0 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)

If a series of records is to be updated by using a series of A1 calls, and the same fields are specified in the format buffer for each call (such as when updating a set of records resulting from a find command), this field should be set to a non-blank, non-zero value. If the A1 command is used in conjunction with an L1/L4, L2/L5, or L3/L6 command, and the same fields within each record are read and updated, the same command ID used for the read command should be used for the A1 calls. In both cases, this reduces the time needed to process each successive A1 call.

If only a single record is to be updated with a single A1 call, or the format buffer is modified between A1 calls, this field should be set to blanks.

The leftmost byte of this field may not be set to hexadecimal 'FF'.

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

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 (ACBXISL)

This field is set to nulls following completion of the A1 operation, unless hard-coupled files are used. If coupled files are used, this field is used during A1 operation and is not reset.

ISN Quantity (ACBXISQ)

This field is set to nulls following completion of the A1 operation, unless hard-coupled files are used. If coupled files are used, this field is used during A1 operation and is not reset.

Command Option 1 and Command Option 2: Hold Record Option (ACBXCOP1 and ACBXCOP2)
Option Description
H An "H" in either the Command Option 1 or Command Option 2 places the record in hold status before it is updated. If the record is currently being held by another user, the command is placed in wait status until either the record becomes available or the transaction times out-unless option "R" is also specified.
R If specified, this setting must be specified in the Command Option 1 field and option "H" must be specified in the Command Option 2 field. Option "R" causes Adabas to return response code 145 if the record to be held is not available. The command is not placed in wait status.
Additions 2 - Length of Compressed Record - (ACBXADD2)

If the command is processed successfully and if the record buffer contains at least one valid field value, the leftmost two bytes contain the length (in binary form) of the compressed record accessed.

Additions 3 - Password - (ACBXADD3)

This field is used to provide an Adabas security password. If the database, file, or fields are security protected, the user must provide a valid security password. Adabas sets the Additions 3 field to blanks during command processing to enhance password integrity.

If the accessed file is password protected, Adabas sets this field to blanks during command processing to protect the integrity of the password.

Additions 4 - Cipher Code - (ACBXADD4)

This field is used to provide a cipher code. If the file is ciphered, the user must provide a valid cipher code. If the file is not ciphered, this field should be set to blanks.

Adabas sets any cipher code to blanks during command processing, and returns a version code and database ID in the rightmost (low-order) three bytes of this field. For more information, see the section Control Block Fields.

Additions 5 - Format ID, Global Format ID - (ACBXADD5)

This field may be used to provide a separate format ID to identify the internal format buffer used for this command, or to provide a global format ID.

As long as the high order bit of the first byte of the Additions 5 field is not set to 1, the value provided in the command ID field will be used as the format ID as well.

If, however, this bit is set to 1, the fifth through eighth bytes of the Additions 5 field are used as the format ID.

If the two high-order (leftmost) bits of the first byte of Additions 5 field are set to one (B'11'), all eight bytes of the Additions 5 field are used as a global format ID (that is, the format ID can be used by several users at the same time).

See the section Command ID, Format ID, Global Format ID for more information and examples.

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.

Top of page

Buffers

The following buffers should be specified with an A1 command:

Format Buffer

The fields to be updated must be specified in this buffer. When performing an A1 command, the format buffer cannot contain any of the following:

Any of the above in the format buffer will cause a nucleus response of 44 for an A1 command.

Descriptions of the syntax and examples of format buffer construction are provided in Format Buffers.

Record Buffer

The values to be used for updating are provided in this buffer according to the length and format as specified in the format buffer. For more information, read Record Buffers

Top of page

Additional Considerations

The following additional considerations are applicable for the A1 command:

  1. Subdescriptors, superdescriptors, and phonetic descriptors may not be directly updated. To update any of these descriptors, the fields used to derive them must be updated. All corresponding subdescriptor, superdescriptor, or phonetic descriptor values will then be updated by Adabas.

  2. Theoretically, the maximum record length permitted is 32767 bytes before compression. The actual maximum is limited by block size restrictions. It is also smaller depending on the size of the LU parameter specified for the Adabas session; the maximum is (LU - format buffer length - 108). The maximum record length after compression is equal to the smaller of either the Data Storage block size - 4 bytes, or the Work block size - 110 bytes.

  3. A descriptor value cannot be larger than 253 bytes.

  4. If a field is updated using a length override that exceeds the standard length (not permitted if the field is defined with the Fixed Storage option), all subsequent references to this field should specify the length that was used. If a subsequent reference uses the standard length, value truncation of an alphanumeric fields, a response code 55 for a numeric field may occur.

  5. A multiple-value field or a field within a periodic group may be specified more than once in the format buffer. A multiple-value field may be specified without an index several times, or with different indices. A periodic field must always have different indices.

  6. A multiple-value or periodic group count field specified in the format buffer will be ignored by Adabas. The corresponding value in the record buffer will also be ignored. A literal in the format buffer will be ignored by Adabas, and the corresponding positions in the record buffer will also be ignored.

  7. If a multiple-value field is updated and the field count must be changed, Adabas updates the multiple-value field count according to the following rules:

  8. If one or more fields contained in a periodic group are updated, Adabas updates the periodic group count, if necessary, according to the following rule:

    The count is adjusted to reflect the highest occurrence number referenced in the format buffer (provided that this occurrence is higher than the existing highest occurrence number).

    Field Definitions 01,GB,PE
    02,BA,1,B,DE,NU
    02,BB,5,P,NU
    GB values before update GB (1st occurrence)
    BA = 5 BB = 20
    GB (2nd occurrence)
    BA = 6 BB = 25
    GB count = 2
    Format Buffer GB4
    Record Buffer X'08000000500F'
    Result after update GB (1st occurrence)
    BA = 5 BB = 20
    GB (2nd occurrence)
    BA = 6 BB = 25
    GB (3rd occurrence)
    BA = 0 BB = 0
    GB (4th occurrence)
    BA = 8 BB = 500
    GB count = 4
    GB values before update GB (1st occurrence)
    BA = 5 BB = 20
    GB (2nd occurrence)
    BA = 6 BB = 25
    GB count = 2
    Format Buffer GB1
    Record Buffer X'00000000000F'
    Result after update GB (1st occurrence)
    BA = 0 BB = 0
    GB (2nd occurrence)
    BA = 6 BB = 25
    GB count = 2

    A maximum of 191 occurrences is permitted for a periodic group.

  9. If a field defined with variable length (no standard length) is specified in the format buffer, the corresponding value in the record buffer must be preceded by a one-byte binary length value that includes the length byte itself.

    Field Definitions 01,AA,3,A
    01,AB,A
    Format Buffer AA,AB
    Record Buffer X'F1F2F306F1F2F3F4F5'

    Fields AA and AB are to be updated. The new value for AA is "123". The new value for AB (which is a variable-length field) is "12345".

Top of page