The RE command reads ET (user) data for the current user, another user, or all users.
This document covers the following topics:
The RE command reads user data that was previously stored in an Adabas system checkpoint file by a C3, CL, or ET command. The user data is returned in the record buffer. This user data may be needed for a user restart following abnormal termination of a user or Adabas session.
User data is read for the issuing user if no value is specified in the Command Option 1 field. The RE command reads user data stored during a previous session for the issuing user if the previous and current sessions both began with OP commands specifying the user ID.
Depending on the specified Command Option, the RE command reads user data for either another specific user (if that user ID is specified) or for all users.
If "I" is specified in the Command Option 1 field, user data stored by another user may be read if the ID of the user who stored the data is specified in the Additions 1 field.
If "A" is specified in the Command Option 1 field, the current and the following RE commands read all user data for all user IDs in ascending logical sequence. The corresponding user ID is returned in the Additions 1 field as each RE command is completed. The RE command with option "A" reads only the user data written to the checkpoint file whose transactions ended with an ET command; user data is not read for users' transactions that are not yet closed with an ET command.
This section describes ACB interface direct calls for the RE command. It covers the following topics:
We recommend that you set unused ACB fields to binary zeros before the direct call is initiated.
| 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 |
| ISN | 13-16 | binary | F | A |
| 17-26 | -- | -- | -- | |
| Record Buffer Length | 27-28 | binary | F | U |
| 29-34 | -- | -- | -- | |
| Command Option 1 | 35 | alphanumeric | F | U |
| 36 | -- | -- | -- | |
| Additions 1 | 37-44 | alphanumeric | F * | U/A ** |
| Additions 2 | 45-48 | alphanumeric | -- | A |
| 49-72 | -- | -- | -- | |
| Command Time | 73-76 | binary | -- | A |
| User Area | 77-80 | -- | -- | U |
| Buffer | Before Adabas Call | After Adabas Call |
|---|---|---|
| Format | *** | -- |
| Record | -- | A |
where:
| F | Supplied by user before Adabas call |
| A | Supplied by Adabas |
| U | Unchanged after Adabas call |
| * | Supplied ET data user ID when Command Option 1 equals "I" |
| ** | User ID for ET data in record buffer if Command Option 1 equals "A" |
| *** | Not used but must be included in parameter list of call statement |
| **** | A database ID is only necessary if you are accessing a database other than the application's default database (read in by ADARUN DBID parameter, provided in the loaded link globals table, or linked with the link routine). |
| -- | Not used |
We recommend that you set unused ACB fields to binary zeros before the direct call is initiated.
- Command Code (ACBCMD)
RE
- Command ID (ACBCID)
Adabas will return a transaction sequence number or binary zeros in this field.
Adabas returns binary zeros in this field if the user whose user data is to be read is not active and either no previous session exists for this user or the previous session for this user was terminated successfully with a CL command. Non-ET-logic users receive binary zeros in this field.
If the user is currently active or the previous session for the user was not terminated successfully with a CL command, Adabas returns the transaction sequence number of the last successfully completed user transaction.
- File Number (ACBFNR)
A database ID is only necessary if you are accessing a database other than the application's default database (read in by ADARUN DBID parameter, provided in the loaded link globals table, or linked with the link routine).
- Response Code (ACBRSP)
Adabas returns the response code for the command in this field. Response code 0 (ADARSP000) indicates that the command was executed successfully. If Command Option 1 specified "A", a response code 3 (ADARSP003) indicates end-of-file for the user data. Nonzero 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)
If Command Option 1 specifies "A", user data is returned in logical sequence starting with this ISN. If this field specifies zero, all user data is returned.
- Record Buffer Length (ACBRBL)
The length of the record buffer. The length specified determines the number of bytes of user data to be returned.
If the length specified is less than the number of bytes of user data available, only the specified number of bytes are inserted in the record buffer and the rightmost bytes are truncated.
- Command Option 1 (ACBCOP1)
If no value is specified in the Command Option 1 field, user data is read for the issuing user. The RE command reads user data stored during a previous session for the issuing user if the previous and current sessions both began with OP commands specifying the user ID.
If a Command Option 1 value is specified, the RE command reads user data for either another specific user or for all users as follows:
Option Description I (ID of user) Reads user data stored by another user if the ID of the user who stored the data is specified in the Additions 1 field. A (all users) The current and following RE commands read all user data in the
record buffer for all user IDs in ascending logical (ISN) sequence. A starting ISN can be specified in the ISN field. If the ISN field specifies zero, all user data is returned. The user ID for the user data contained in the record buffer at the end of the current and each following RE operation is returned in the Additions 1 field as each RE command is completed. RE reads only the user data written to the checkpoint file for users whose transactions ended with an ET command; user data is not read for users' transactions that are not yet closed with an ET command. For this option, a response code 3 (ADARSP003) returned in the response code field indicates end-of-file for the user data.- Additions 1: User ID (ACBADD1)
If user data stored by another user is to be read, this field must be set to the ID of the user who stored the data. If Command Option 1 specifies "A", this field returns the user ID for the user data contained in the record buffer at the end of this and each following RE operation.
- Additions 2: Transaction Sequence Number (ACBADD2)
If an ET logic user stored the data being read, Adabas will return, in this field, the transaction sequence number of the user's last successfully completed transaction in which user data was stored with an ET or CL command.
If the RE command returns a non-zero response code, the rightmost two bytes of the 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.
The user wishes to read the user's own data previously stored with an ET command.
| Command Code | RE | |
|---|---|---|
| Record Buffer Length | 100 | 100 bytes of user data is to be read |
| Command Option 1 | blank | the user data to be read was stored by this user |
| ISN | 0 |
The user wishes to read user data stored by another user (user ID = USER0002).
| Command Code | RE | |
|---|---|---|
| Record Buffer Length | 150 | 150 bytes of user data is to be read |
| Command Option 1 | I | the user data to be read was stored by another user |
| Additions 1 | USER0002 | ID of the user who stored the user data |
| ISN | 0 |
In the following example, the user wishes to read all user data and the corresponding user ID.
| Command Code | RE | |
|---|---|---|
| Record Buffer Length | 250 | 250 bytes of user data is to be read, per user |
| Command Option 1 | A | |
| ISN | 0 | read all user data |
This section describes ACBX interface direct calls for the RE command. It covers the following topics:
We recommend that you set unused ACBX fields to binary zeros before the direct call is initiated.
| 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 |
| Command ID | 13-16 | alphanumeric/ binary | --- | A |
| Database ID**** | 17-20 | numeric | F | U |
| File Number | 21-24 | numeric | F | U |
| 25-28 | --- | --- | --- | |
| ISN | 29-32 | binary | F | A |
| 33-48 | --- | --- | --- | |
| Command Option 1 | 49 | alphanumeric | F | U |
| 50-56 | --- | --- | --- | |
| Additions 1 | 57-64 | alphanumeric/ binary | F* | U/A** |
| Additions 2 | 65-68 | binary | --- | A |
| 69-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 | --- | --- |
| ABD and Buffer | Before Adabas Call | After Adabas Call |
|---|---|---|
| Format | *** | -- |
| Record | -- | A |
where:
| F | Supplied by user before Adabas call |
| A | Supplied by Adabas |
| U | Unchanged after Adabas call |
| * | Supplied ET data user ID when Command Option 1 equals "I" |
| ** | User ID for ET data in record buffer if Command Option 1 equals "A" |
| *** | Not used but should be included in Adabas call or one will be automatically generated. |
| **** | A database ID is only necessary if you are accessing a database other than the application's default database (read in by ADARUN DBID parameter, provided in the loaded link globals table, or linked with the link routine). |
| --- | 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)
RE
- 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.
If Command Option 1 specified "A", a response code 3 (ADARSP003) indicates end-of-file for the user data.
- Command ID (ACBXCID)
Adabas will return a transaction sequence number or binary zeros in this field.
Adabas returns binary zeros in this field if the user whose user data is to be read is not active and either no previous session exists for this user or the previous session for this user was terminated successfully with a CL command. Non-ET-logic users receive binary zeros in this field.
If the user is currently active or the previous session for the user was not terminated successfully with a CL command, Adabas returns the transaction sequence number of the last successfully completed user transaction.
- Database ID (ACBXDBID)
Use this field to specify the database ID only if you are accessing a database other than the application's default database (read in by ADARUN DBID parameter, provided in the loaded link globals table, or linked with the link routine). 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 DDDDCARD 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)
If Command Option 1 specifies "A", user data is returned in logical sequence starting with this ISN. If this field specifies zero, all user data is returned.
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 (ACBXCOP1)
If no value is specified in the Command Option 1 field, user data is read for the issuing user. The RE command reads user data stored during a previous session for the issuing user if the previous and current sessions both began with OP commands specifying the user ID.
If a Command Option 1 value is specified, the RE command reads user data for either another specific user or for all users as follows:
Option Description I (ID of user) Reads user data stored by another user if the ID of the user who stored the data is specified in the Additions 1 field. A (all users) The current and following RE commands read all user data in the
record buffer for all user IDs in ascending logical (ISN) sequence. A starting ISN can be specified in the ISN field. If the ISN field specifies zero, all user data is returned. The user ID for the user data contained in the record buffer at the end of the current and each following RE operation is returned in the Additions 1 field as each RE command is completed. RE reads only the user data written to the checkpoint file for users whose transactions ended with an ET command; user data is not read for users' transactions that are not yet closed with an ET command. For this option, a response code 3 (ADARSP003) returned in the response code field indicates end-of-file for the user data.- Additions 1: User ID (ACBXADD1)
If Command Option 1 specifies an "I", this field must be set to the user ID of the user who stored the data.
If Command Option 1 specifies "A", this field returns the user ID for the user data contained in the record buffer at the end of this and each following RE operation.
- Additions 2: Transaction Sequence Number (ACBXADD2)
If an ET logic user stored the data being read, Adabas will return, in this field, the transaction sequence number of the user's last successfully completed transaction in which user data was stored with an ET or CL command.
- 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.
The following buffers apply to the RE command:
A format buffer is not used by the RE command, but should be included in the Adabas call. If this is an ACB interface direct call and a format buffer is not specified, a processing error will occur; ACB interface direct calls expect buffers to be specified in a set sequence. If this is an ACBX interface direct call and a format buffer is not specified, one will be automatically generated.
Adabas returns the user data in the record buffer. If no user data was found, this contains blanks at the end of RE operation.