This document covers the following topics:
The A1 command is used to modify the value of one or more fields within 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. The user specifies the fields to be updated in the format buffer, and provides the values to be used for updating these fields in the record buffer. Only those fields specified and system generated fields defined without the option CR will be modified. All other fields in the record remain unchanged.
All necessary updating to the Associator and Data Storage is performed by Adabas. If one or more descriptors are updated, Adabas will update the inverted lists to reflect the modifications. If a field which was used to derive a subdescriptor or a superdescriptor is updated, Adabas will update the corresponding subdescriptor or superdescriptor values to reflect the modification.
In case of an ET user, the A1 command will be executed only if the record to be updated is in hold status for the user or when command option 1 = H, L, U or R was specified.
The user can also position to a record via an ADAM (Adabas direct access method) key. In this case, the command option 2 must be set to V, and the search and value buffers must contain the ADAM descriptor name and the ADAM key respectively. If this method is used, the ISN field in the control block becomes an output field.
| Field | Format | |
|---|---|---|
| Call Type | B | F/U |
| Reserved (internal use) | -/- | |
| Command Code | A | F/U |
| Command ID | B | F/U |
| File Number | B | F/U (1) |
| Response Code | B | F/A (1) |
| ISN | B | F/U |
| ISN Lower Limit | B | F/A |
| Format Buffer Length (ACB only) | B | F/U |
| Record Buffer Length (ACB only) | B | F/U |
| Search Buffer Length (ACB only) | B | F/U |
| Value Buffer Length (ACB only) | B | F/U |
| Command Option 1 | A | F/U |
| Command Option 2 | A | F/U |
| Additions 2 | A,B | -/A |
| Additions 3 | A | F/A |
| Additions 5 | A | F/U |
| Command Time | B | -/A |
| User Area | F/U |
| Buffer | |
|---|---|
| Format Buffer | F/U |
| Record Buffer | F/A |
| Search Buffer | F/U (2) |
| Value Buffer | F/U (2) |
| ISN Buffer | –/– |
| A | alphanumeric |
| B | binary |
| A | Filled in by Adabas |
| F | To be filled in by User |
| U | Unchanged after Adabas call |
| - | Not used |
(1) The meaning of this field depends on the value
specified for "Call Type". See Calling Adabas, The Control
Block for details.
(2) Only required if the V
option is used
A1
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 is used in conjunction with the L1/L4, L2/L5, or L3/L6 command, and the same fields within each record are read and updated, the same Command ID which was used for the READ command should be used for the A1 calls. In both cases, this reduces the time required 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 or binary zero.
The high-order byte of this field may not be set to hexadecimal `FF', except when automatic command ID generation is used (see Programming Considerations, Using Command IDs for additional information).
The number of the file which contains the record to be updated.
Adabas returns the response code for the command in this field. Response code 0 indicates that the command was executed successfully.
The ISN of the record to be updated.
If the ADAM option is used, Adabas returns the ISN of the record found in this buffer.
If command option ‘L’ is used, the format buffer must contain a segment with *-position, the input value contains the current position of the segment. The value is increased by the length specified for the segment.
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.
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.
The search buffer length (in bytes). The search buffer area defined in the user program must be as large as (or larger than) the length specified.
The value buffer length (in bytes). The value buffer area defined in the user program must be as large as (or larger than) the length specified.
When the user supplies an `H', the record is placed into exclusive hold status before the update command is executed.
When the user supplies an `R', the record is placed into exclusive hold status before the update command is executed. If the ISN is held by another user, a response 145 is returned.
When the user supplies an `L', the current updated record is returned in the record buffer according to the current format buffer. This option implies the H option.
When the user supplies a `U', Adabas attempts to place the record is placed into exclusive hold status. The command will not wait if an ISN conflict is detected (ISN in hold for another user), and a response 145 is returned. The current updated record is returned in the record buffer.
The `L' and the `U' options are only useful when used in conjunction with the add option or system generated fields (without CR) in the format buffer.
When the user supplies an ‘X’, the A1 command is equivalent (but more efficient) to an E1 command for the ISN specified followed by an N2 command for the ISN specified with the format and record buffers specified, with the exception that fields with field options SY and CR remain unchanged.
Note:
The ‘X’ option is helpful for reducing the number of MU values or
PE groups in a record.
When the user supplies an `H', the ISN is placed into the hold queue before the update command is executed. The command waits if the ISN is held by another user unless the `R' option is specified in Command Option 1, in which case a response 145 is returned.
When the user supplies an ‘L’, the format buffer is only allowed if the format buffer contains a segment with *-position. Then the ISN Lower Limit field is used to determine the current position of the segment with *-position. Without the option ‘L’, the current position of a segment with *-position is the first (leftmost) byte of the field value.
When the user supplies a ‘T’, the record is handled according to the rules described in the section Programming Considerations, System Generated Fields.
A `V' in this field indicates that the ADAM option is being used. A value (ADAM key) can only be supplied for ADAM descriptor files. The value for the key is given in the value buffer, and the descriptor name is specified in the search buffer. If the ADAM option is used, the ISN field becomes an output field.
A response 52 is returned if no record with specified ADAM key is found.
The following table shows the possible combinations of the command options 1 and 2, together with the hold status required and conflict information:
| CO1 | CO2 | Hold Status | Conflict | Specials |
|---|---|---|---|---|
| ' ' | ' ' | Requires hold | ||
| 'H' | ' ' | Set hold | Wait for ISN | |
| ' ' | 'H' | Set hold | Wait for ISN | |
| 'L' | ' ' | Set hold | Wait for ISN | Read record |
| 'U' | ' ' | Set hold | Rsp 145 | Read record |
| 'R' | ' ' | Set hold | Rsp145 | |
| 'R' | 'H' | Set hold | Rsp 145 | |
| 'R' | 'V' | Set hold | Rsp 145 | ADAM |
| ' ' | 'V' | Requires hold | ADAM | |
| 'H' | 'V' | Set hold | Wait for ISN | ADAM, read record |
| 'L' | 'V' | Set hold | Wait for ISN | ADAM, read record |
| 'U' | 'V' | Set hold | Rsp 145 | ADAM, read record |
If the response code is 0, Adabas returns the compressed record length of the updated record in this field. The length is provided in the first two bytes in binary format. If the `L' or `U' option is used, the last two bytes will contain the length of the compressed fields selected by the format buffer in binary format.
This field is used to provide a security password.
If the file to be used is not security protected, this field should be set to blanks. If the file is security protected, the user must provide a valid password.
Adabas sets this field to blanks during command processing to protect the integrity of any password provided.
This field may be used to provide a separate format buffer ID that is used to identify the internal format buffer used for this command, or to provide a global format buffer ID.
As long as the first byte of the Additions 5 field is not alphanumeric, the value provided in the command ID field will also be used as the format buffer ID.
If the first byte is a lower case character, the bytes 5 to 8 of the Additions 5 field will be used as the separate local format buffer ID.
If the first byte is a digit or an upper case character, the Additions 5 field (8 bytes) will be used as a separate global format buffer ID, which means that the format buffer ID can be used by several users in parallel.
See Programming Considerations, Using Command IDs for additional information and examples.
The fields to be updated must be specified in this buffer.
The syntax and examples of format buffer construction are provided in Calling Adabas, Format and Record Buffers.
The values to be used for updating are provided in this buffer according to the length and format as specified in the format buffer.
Examples of record buffer construction are provided in Calling Adabas, Format and Record Buffers.
If the ADAM option (command option 2=V) is used, the search buffer contains the field specification of the ADAM descriptor. A response 61 is returned if the field name is not an ADAM key.
If the ADAM option (command option 2=V) is used, the value buffer contains the value of the ADAM key.
The following additional considerations are applicable for the A1 command:
Subdescriptors, superdescriptors, hyperdescriptors and phonetic descriptors may not be updated directly. In order to update any of the above, the field(s) used to derive the subdescriptor, superdescriptor, or phonetic descriptor must be updated. All corresponding subdescriptor, superdescriptor, or phonetic descriptor values will then be updated automatically by Adabas.
The maxiumum record length after compression (including record ISN) is the maximum available DATA storage block size - 4.
A descriptor value may not exceed 1144 bytes, unless the descriptor is defined with the TR option.
If a field is updated using a length override which 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 which was used. If a subsequent reference uses the standard length, value truncation for alphanumeric fields or response code 55 for numeric fields may occur.
Field names without index may be specified more than once only if they are multiple-value fields. Multiple-value fields and fields in periodic groups with the same index may not be specified more than once. It is also forbidden to specify a group and a field in the group at the same time.
Numeric edit masks must not be specified in the format buffer.
A multiple-value count field 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. The corresponding positions in the record buffer will also be ignored.
If a multiple-value field is updated, Adabas automatically updates the multiple value field count, if necessary, according to the following rules:
For a multiple-value field defined with the NU option, the count field is adjusted to reflect the current number of existing non-null values. Null values are completely suppressed.
Field Definition 01,MF,5,A,MU,NU
MF values before update XXXXX,YYYYY
Format Buffer MF4
Record Buffer ZZZZZ
Result after update XXXXX,YYYYY,ZZZZZ
MF count = 3
MF values before update XXXXX,YYYYY,ZZZZZ
Format Buffer MF2
Record Buffer bbbbb (blanks)
Result after update XXXXX,ZZZZZ
MF count = 2
MF values before update XXXXX,ZZZZZ
Format Buffer MF1-2
Record Buffer bbbbbbbbbb (blanks)
Result after update Values suppressed
MF count = 0
For a multiple-value field defined without the NU option, the count is adjusted to reflect the current number of existing values (including null values).
Field Definition 01,MF,5,A,MU
MF values before update XXXXX,YYYYY
Format Buffer MF4
Record Buffer DDDDD
Result after update XXXXX,YYYYY,b(blank),DDDDD
MF count = 4
MF values before update XXXXX,YYYYY,ZZZZZ
Format Buffer MF3
Record Buffer bbbbb (blanks)
Result after update XXXXX,YYYYY,b (blank)
MF count = 3
If you specify MU fields without index, only the values contained in the record buffer are stored in the database; all other MU values contained in the old record are removed. If the current record buffer contains null values and the MU field is defined with the NU option, the null values are suppressed. The count field is adjusted accordingly.
Field Definition 01,MF,5,A,MU,NU
MF values before update XXXXX,YYYYY
Format Buffer MF
Record Buffer AAAAA
Result after update AAAAA
MF count = 1
MF values before update XXXXX,YYYYY
Format Buffer MF1
Record Buffer AAAAA
Result after update AAAAA,YYYYY
MF count = 2
MF values before update XXXXX,YYYYY,ZZZZZ
Format Buffer MF
Record Buffer bbbbb (blanks)
Result after update value suppressed
MF count = 0
If one or more fields contained in a periodic group are updated, Adabas automatically 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 current 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 0x08000000500C
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 0x00000000000C
Result after update GB (1st occurrence)
BA = 0 BB = 0
GB (2nd occurrence)
BA = 6 BB = 25
GB count = 2
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 number which represents the length of the value (including the length byte).
Field Definitions 01,AA,3,A
01,AB,0,A
Format Buffer AA,AB.
Record Buffer "313233063132333435"
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.
Note:
The Adabas file definitions in Appendix A are used in the
examples in this section.
ISN 4 of file 1 is to be updated with the following values:
Field AA 1234 Field AB 20
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)
Format Buffer AA,AB,2,U.
Record Buffer 0x21323334202020203230