This document covers the following topics:
The OP command is used to indicate the beginning of a user session. If the user is not yet known to Adabas, a new user queue element will be allocated, which will exist until the user issues a CL command, or is stopped by Adabas or by an operator.
An OP command is mandatory if any of the following applies:
The user is an exclusive control user (see the description in Concepts and Facilities);
User data stored in an Adabas system file with an ET command is to be read;
The user is to be an access-only user (no update commands permitted);
An OP command is optional for all other users if OPTIONS=OPEN_REQUIRED is not enabled for the current nucleus session. An implicit OP command will be issued by Adabas when the first Adabas command is issued by a user who is not currently identified to Adabas.
Users who use files which are security protected are not required to issue an OP command, but such users must provide a password with each command that involves a file which is security protected.
If an OP command is issued by an active ET logic user, and the user is not at ET status (currently has a record in hold), Adabas will issue a BT command for the user and will return response code 9 for the OP command. If an OP command is issued by any other type of active user, Adabas issues a CL command for the user prior to processing the OP command.
Adabas recognizes various user types, depending on the type of access/update performed by the user. See Concepts and Facilities, User Types for further details.
| Field | Format | |
|---|---|---|
| Call Type | B | F/U |
| Reserved (internal use) | -/- | |
| Command Code | A | F/U |
| Command ID | B | -/A |
| File Number | B | F/U (1) |
| Response Code | B | F/A (1) |
| ISN Lower Limit | B | F/A |
| ISN Quantity | B | F/A |
| Record Buffer Length (ACB only) | B | F/U |
| Command Option 1 | A | F/U |
| Command Option 2 | A | F/U |
| Additions 1 | A | F/U |
| Additions 2 | A,B | -/A |
| Additions 5 | A | -/A |
| Command Time | B | -/A |
| User Area | F/U |
| Buffer | |
|---|---|
| Format Buffer | */– |
| Record Buffer | F/U |
| Search Buffer | –/– |
| Value Buffer | –/– |
| 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 |
| * | Not used but must be included in parameter list of CALL statement |
(1) The meaning of this field depends on the value specified for "Call Type". See Calling Adabas, The Control Block for details.
OP
For an access only user, Adabas always returns 0 in this field.
For an ET logic user, Adabas will return binary zeros in this field if the previous session for this user was successfully terminated with a CL command, or no previous session existed for this user. If this user is an ID user (Additions 1 is not blank) and the previous session of the current user ID was not successfully terminated with a CL command, Adabas will return the transaction sequence number of the last successfully-completed user transaction in this field. Additionally, response code 9 is returned.
This field may be used to provide a user-specific non-activity time limit.
If this field contains binary zeros, the non-activity time limit specified by the appropriate ADANUC parameter (TNAA, TNAE, or TNAX) for the Adabas session is in effect. Following successful OP completion, Adabas returns system release information in this field; the timeout information previously held here is instead returned in the Additions 5 field.
The following platform information is returned in the ISN Lower Limit field, considered as a 4-byte binary value:
| Byte | Contents |
|---|---|
| high order byte | architecture byte (as defined in ENTIRE NET-WORK) |
| product line: 2 = Open Systems |
|
| 0 | |
| low order byte | local/remote indicator (local nucleus = 0, remote nucleus = 1) |
This field may be used to provide a user-specific transaction time limit.
If this field contains binary zeros, the non-activity time limit specified by the ADANUC parameter TT for the Adabas session is in effect. Following successful OP completion, Adabas returns system release information in this field; the timeout information previously held here is instead returned in the Additions 5 field.
The following version information is returned in the ISN Quantity field, considered as a 4-byte binary value:
| Byte | Contents |
|---|---|
| high order byte | major version |
| minor version | |
| SM level | |
| low order byte | patch level |
Adabas returns the response code for the command in this field. Response code 0 indicates that the command was executed successfully.
The length of the record buffer must be specified in this field. The length specified must be large enough to accommodate all required record buffer entries. The record buffer length should be set to zero if an empty record buffer is to be supplied.
If user data which is stored in an Adabas system file is to be returned, the length specified must be large enough to permit the user data to be inserted in the record buffer; otherwise, the user data will be truncated.
An `R' in this field indicates that the user is to be restricted to only those files specified in the file list provided in the record buffer. Response code 17 will be returned if the user attempts to access/update a file that is not contained in the file list. If an R is not specified in this field, a request to access/update a file that is not in the file list is processed as described under User Queue Element in this section.
An `S' in this field enables the user section for subtransactions; this option implies the `R' option if a file list has been specified.
An `E' in this field indicates that user data stored in an Adabas system file by a CL or ET command is to be returned in the record buffer.
The data stored with the last successful CL or ET command issued by the user in which user data was provided is returned.
This option may only be used if the user has provided the same USERID for both this user session and the session during which the user data was stored.
This field must be set to blank in all other cases.
This field may be used to provide a USERID for the user session.
A USERID must be provided if the user intends to store and/or read user data, and the user wants this data to be available during a subsequent user– or Adabas session.
The user intends to store and/or read user data, and the user wants this data to be available during a subsequent user- or Adabas session;
The user is to be assigned a special processing priority;
The value provided for the USERID must be unique for this user (not used by any other user), and must begin with a digit or an uppercase letter.
Users for whom none of the above conditions are true should set this field to blanks.
If the command is successful, the value returned in this field by Adabas depends on the user type:
| Access only user: | The input value is unchanged. |
| ET logic user: | The value returned is the ISN of the user's last successfully completed transaction for which user data was stored. If this is the first session or a non–ID user session, the value 0 is returned. |
For some response codes, Adabas returns detailed information in this field. See Adabas Messages And Codes for further information.
User-specific timeout values as specified in the fields ISN lower limit and ISN quantity are returned in the last 4 bytes of this field. The two high-order bytes contain the user-specific non-activity time limit in binary format, the two low-order bytes contain the user-specific transaction time limit in binary format.
The default encoding for W fields, the local time zone, and the files to be accessed and/or updated and the type of updating to be performed are specified in this buffer.
The syntax of this buffer is:
[OP_expression,...].
OP_expression may be one of the following:
| OP_expression | Explanation |
|---|---|
| TZ=’timezone’ | You must specify as timezone the name of
a time zone that is contained in the tz database that is also known as the
Olson database (see http://www.twinsun.com/tz/tz-link.htm).
You must specify the full name of a location, for example: America/New_York |
| WCHARSET=’char_set’ | You must specify as char_set an encoding
name that is listed in
http://www.iana.org/assignments/character-sets
- most of the character sets listed there,are supported by ICU, which is used
by Adabas for internationalization support. This character set is the default
character set used for W fields in record and value buffers in the Adabas user
session when no other character set has been specified in the format or search
buffer. Some character sets are platform-dependent, for example UTF-16. It is strongly recommended that you use the corresponding platform-independent character set, i.e. UTF-16BE or UTF-16LE instead of UTF-16. Otherwise Adabas cannot guarantee which variant is used. |
| usage=file_list | Here usage is one of the following:
filenumber [,filenumber] ...where filenumber is a number (leading zeros permitted) which indicates the Adabas file for which the preceding keyword is applicable. |
TZ and WCHARSET may be specified only once.
Duplicate file numbers for a given usage keyword are permitted. Duplicate file numbers across usage keywords are permitted. Each usage keyword may appear only once.
UPD, EXF and EXU also imply access to the file. If ACC or UPD are the only keywords specified, a file list is not required.
The following keyword combinations are permitted:
ACC + EXF
ACC + EXU
ACC + UPD
EXF + UPD
EXU + UPD
ACC + EXF + UPD
ACC + EXU + UPD
A user may or may not be permitted to use a file currently in use by another user or by an Adabas utility (denoted by UTI) as shown below:
| USER 2 Requested Usage | USER 1 Current Usage | ||||
|---|---|---|---|---|---|
| ACC | EXF | EXU | UPD | UTI | |
| ACC | yes | no | yes | yes | no |
| EXF | no | no | no | no | no |
| EXU | yes | no | no | no | no |
| UPD | yes | no | no | yes | no |
| UTI* | no | no | no | no | no |
*Some utilities permit access to a file by other users during utility execution. In this case, the utility issues an OP command with the EXU parameter specified.
If no keyword is supplied (in other words, if the record buffer is set to '.'), the user automatically becomes an ET logic user. In this case, the record buffer length can be set to zero in the Adabas control block and the record buffer need not be supplied.
During the time that a user is active, Adabas maintains a user queue element (UQE) for the user. The UQE contains a list of file numbers for the files the user is currently using. The file list is generated when the user issues an OP command and may be modified during the user session. If no OP command is issued, the file list will initially contain no files.
Each file in the file list is marked as one of the following:
ACC (access only)
EXF (read- and write-protected against all other users)
EXU (access and update and under exclusive control)
UPD (access and update)
UTI (access and update and in use by an Adabas utility)
If a subsequent attempt is made to access a file that is not currently in the user's file list, a test will be made to determine whether the file is currently in use by an Adabas utility. If not, the file will be added to the user's file list and marked as ACC.
If a subsequent attempt is made to update a file that is not currently in the user's file list, the following tests are applied:
Does the request conflict with the user type? For example, an access-only user may not issue update commands;
Is the user's file list restricted because command option 1 in the OP command specifies the value `R'?;
Is the file to be updated under exclusive control of another user or Adabas utility?
If the file is determined to be available for the user, the file is added to the user's file list and marked as UPD.
The following special feature is activated only if the nucleus has been started with OPTIONS= OPEN_REQUIRED.
If a user session is terminated without a CL (close) command, e.g. by switching off and re–booting a PC, the Adabas nucleus still considers the connection to be active. If the user wants to start a new session with the same user ID, the nucleus handles this OP command as if it was issued by a different user because of the new process ID, and so returns a response code to the user.
However, if this user keeps trying to start the new session and the first session remains inactive for a defined time frame (about 60 seconds) then the first session will be terminated. This termination may result in a backout transaction command (BT) for the first session. The second session for the user will then be able to start. If the first session in the meantime issues another command, the error response code 9 will be returned to the first session, and additional information indicating "open required" is returned in the field ADDITIONS_2 of the Control Block. See the Messages and Codes manual, response code 9, value "open required" in field ADDITIONS_2 for further details.
An access-only user session is to be opened with the character set UTF-16BE for W fields.
Command Code OP
Record Buffer Length 24 (or larger)
Record Buffer WCHARSET='UTF-16BE',ACC.
A user session is to be opened, in which the user intends to access files 8 and 9, and update files 8 and 16. The user intends to store user data in an Adabas system file during the session. The user data which was stored during the previous session is to be read. The USERID for the user is USER0001.
Command Code OP
Record Buffer Length 15 (or larger)
Command Option 2 E (user data is to be read)
Additions 1 USER0001 (USERID is required if user data
is to be stored and/or read)
Record Buffer ACC=9,UPD=8,16.
A user session is to be opened, in which the user wishes to have exclusive control of files 10, 11 and 12. The user does not intend to use ET commands and does not intend to store and/or read user data in/from an Adabas system file.
Command Code OP
Record Buffer Length 13 (or larger)
Command Option 2 b (user data is not to be stored or read)
Additions 1 bbbbbbbb (USERID is not required)
Record Buffer EXU=10,11,12.
A user session is to be opened, in which the user wishes to have exclusive control of files 10,11 and 12. The user intends to use ET commands.
Command Code OP
Record Buffer Length 26 (or larger)
Command Option 2 b (user data is not to be stored or read)
Additions 1 bbbbbbbb (USERID is not required)
Record Buffer EXU=10,11,12,UPD=10,11,12.
A user session is to be opened, in which the user intends to update files 5 and 7. The user ID of the user is USER0002. The user session will run with timeout values TNAE=30 minutes and TT=10 minutes.
Command Code OP
Record Buffer Length 8
ISN Lower Limit 1800 (1800 seconds = 30 minutes)
ISN Quantity 600 (600 seconds = 10 minutes)
Additions 1 USER0002
Record Buffer UPD=5,7.