The OP command indicates the beginning of a user session.
This document covers the following topics:
Software AG recommends that all users start their Adabas sessions with an OP command.
An OP command is mandatory if any of the following is true for the user:
The nucleus is run with ADARUN parameter OPENRQ=YES.
Exclusive file control (EXF) is to be performed.
User data that was stored in an Adabas system file by a previous ET command is to be read.
User data is to be stored in an Adabas system file, using a C3, CL, or ET command.
The user is to be assigned a special processing priority.
The user is to be an access-only user (no update commands permitted).
A transaction time limit and/or a non-activity time limit is to be set for the user that differs from that specified by ADARUN parameters TT and/or TNAx, respectively. The setting for a user must conform to the maximum (2-byte) setting set by the ADARUN parameters MXTT and MXTNA, respectively.
Special data encoding and/or architecture is to be specified for the user session.
An OP command is otherwise optional. An implicit OP command is issued by Adabas when the first Adabas command is issued by a user who is not currently identified to Adabas.
Users accessing files that are protected by Adabas Security are not required to issue an OP command; such users must, however, provide a password with each command directed to a security-protected file. If the system is protected through the Adabas External Security Interface (ADAESI) and an attached security package, an OP command may be required. Ask your DBA or system security specialist for more information.
If an OP command is issued by an active ET logic user, and the user is not at ET status (an OP, ET, or BT command has not been previously issued with one or more records in hold status), Adabas issues a BT command for the user and returns 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 before processing the OP command.
A user operating in single-user mode cannot issue more than one OP command during a given session execution.
Adabas identifies each user session by the type of access/update performed by the user.
If an OP command is issued in which access-only (ACC parameter) is specified, the user is defined to be an access-only user. Such users may not issue hold, update, delete, add record, ET, or BT commands.
Note:
Access-/update-level security can also be controlled through Adabas
Security on a file and field level, and through Adabas SAF Security on a
database and file level. The security control "adds to" the user type control;
that is, an access-only user's access level can be further defined on a file,
field, or value level with Adabas Security, but cannot be changed to an update
level.
If an OP command is issued in which exclusive file control (EXF or EXU parameter) is specified, the user is defined to be an exclusive control user. Such a user is considered to be a non-ET logic user (unless the UPD parameter has also been specified in which case the user is defined to be an ET logic user). If such a user issues an ET command, the user is changed to an ET logic user when the first ET command is issued.
All other users (including users who do not issue an OP command) are defined as ET logic users. Transactions issued by such users are subject to the transaction duration time limit.
| Field | Position | Format | Before Adabas Call | After Adabas Call |
|---|---|---|---|---|
| 1-2 | -- | -- | -- | |
| COMMAND CODE | 3-4 | alphanumeric | F | U |
| COMMAND ID | 5-8 | alphanumeric | -- | A |
| FILE NUMBER** | 9-10 | binary | F | U |
| RESPONSE CODE | 11-12 | binary | -- | A |
| ISN | 13-16 | binary | -- | A |
| ISN LOWER LIMIT | 17-20 | binary | F | A |
| ISN QUANTITY | 21-24 | binary | F | A |
| 25-26 | -- | -- | -- | |
| RECORD BUFFER LENGTH | 27-28 | binary | F | U |
| 29-34 | -- | -- | -- | |
| COMMAND OPTION 1 | 35 | alphanumeric | F | U |
| COMMAND OPTION 2 | 36 | alphanumeric | F | U |
| ADDITIONS 1 | 37-44 | alphanumeric | F | U |
| ADDITIONS 2 | 45-48 | alphanumeric | -- | A |
| 49-56 | -- | -- | -- | |
| ADDITIONS 4 | 57-64 | binary | F | A |
| ADDITIONS 5 | 65-72 | binary | -- | A |
| COMMAND TIME | 73-76 | binary | -- | A |
| USER AREA | 77-80 | -- | -- | U |
| Buffer | Before Adabas Call | After Adabas Call |
|---|---|---|
| FORMAT BUFFER | * | |
| RECORD BUFFER | F | A |
where:
| F | Filled in by user before Adabas call |
| A | Filled in by Adabas |
| U | Unchanged after Adabas call |
| * | Not used but must be included in parameter list of the call statement |
| ** | A database ID is only necessary if you are accessing multiple databases and need to limit the command operation to a specific database. |
| -- | Not used |
OP
Adabas will return binary zeros in this field if the previous session for this user was terminated successfully with a CL command, or no previous session existed for this user.
If the previous session for this user was not terminated successfully with a CL command, Adabas will return in this field the transaction sequence number of the last successfully completed user transaction.
The above information is returned only if the user is an ET logic user. If the user is a non-ET logic user, this field is not modified by Adabas.
A database ID is only necessary if you are accessing multiple databases and need to limit the command operation to a specific database.
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 documentation.
Adabas sets this field to binary zero on return.
This field may be used to provide a user-specific non-activity time limit. This limit must conform to the maximum specified by the ADARUN parameter MXTNA. If this field contains binary zeros, the non-activity time limit specified by the appropriate ADARUN parameter (TNAA, TNAE, or TNAX) for the Adabas session is in effect.
Following successful OP completion, Adabas returns its system and call type information in this field; the timeout information previously held here is returned in the additions 5 field, bytes 4 and 5. See the section Values Returned in Control Block Fields for detailed information.
This field may be used to provide a user-specific transaction time limit. This limit must conform to the maximum specified by the ADARUN parameter MXTT. If this field contains binary zeros, the transaction time limit specified by the ADARUN TT parameter for the Adabas session is in effect.
Following successful OP completion, Adabas returns its system release information in this field; the timeout information previously held here is returned in the additions 5 field, bytes 6 and 7. See the section Values Returned in Control Block Fields for detailed information.
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 are stored in an Adabas system file are 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.
| Option | Description |
|---|---|
| R | (restrict files) the user is restricted to the files specified in the file list provided in the record buffer. The OP command returns a response code 48 if a specified file is not available. Later commands issue response code 17 if the user attempts to access/update a file not contained in the file list. If the "R" option is not specified and an attempt is made to access a file not currently in the specified file list, Adabas tests to determine whether the file is currently in use by an Adabas utility and if not, the file is added to the user's list. See the section User Queue Element for more information. |
| Option | Description |
|---|---|
| E | user (ET) data stored in an Adabas system file by the last successful C3, CL, or ET command issued by the user (in which user data was provided) is returned in the record buffer. This option may only be used if the user has provided the same user ID for this user session and the session during which the user data was stored. |
This field may be used to provide a user ID for the user session. To avoid later limitations, Software AG recommends that you always specify a user ID.
The value provided for the user ID should be unique for the user (that is, not used by any other user at the same time), and must begin with the value "A" through "9". If the value is not unique, a response code 48 occurs. If the other user has been inactive for 60 seconds, the nucleus schedules an internal autobackout for that user and returns response code 9 for the OP command. With another OP command, the user can take over the user ID (ETID) of the other user, who loses the user ID due to the internal backout transaction (BT) command and receives response code 9 on the next call.
A user ID must be provided if any of the following is true:
The user intends to first read (if any) and then store user data, and the user wishes the data to be available during a subsequent user or Adabas session.
A user that specifies a user ID (ETID) can store ET data that remains available in later sessions. ET data stored by a user having no user ID is available during the user's current session only. Data to be stored can be provided with the ET command or at the end of the session with a close (CL) command. ET data stored with a user ID in a previous session can be read with either the OP or RE command.
The user is to be assigned a special processing priority (priorities are assigned with Adabas Online System or the ADADBS utility's PRIORITY function);
The operation being started is on a multiclient file; see the Adabas DBA Reference documentation for more information about multiclient files. A user with a blank or missing owner ID receives response code 3 or 113 when trying to access a multiclient file.
Users for whom none of the above conditions are true may set this field to blanks.
Adabas returns in this field the transaction sequence number of the last transaction for which an ET command with ET data was executed successfully.
If the OP command returns a non-zero response code, the rightmost two bytes may contain a subcode defining the exact response code meaning. Response codes and their subcodes are defined in the Adabas Messages and Codes documentation.
This field may be used to set the following user-specific maximum binary values:
| Bytes | Usage |
|---|---|
| 57-58 | maximum number of ISNs that may be stored in the internal ISN element table resulting from the execution of a Sx command. Increasing the default setting will result in less access to the Adabas Work being necessary. The maximum allowed is 1000. |
| 59-60 | maximum number of records that a user may have in hold status at the same time. The default is the value set by the ADARUN NISNHQ parameter, and the maximum is 1/4 the value set by the ADARUN NH parameter minus 1, or 65535-whichever is smaller. |
| 61-62 | maximum number of command IDs that may be active for a user at the same time. This value cannot be greater than 1/240 � LQ (where LQ is the ADARUN sequential command table length parameter value, which has a default of 10000). |
| 63-64 | maximum amount of time permitted for the execution of an Sx command. |
If one or more of the values above are not specified, the system-wide specifications for the nucleus become the defaults. The user should consult with the DBA concerning the system defaults in effect for these values before entering any user-specific values in this field.
Values specified must be in binary. Specifying blanks or binary zero is equivalent to "no value".
Adabas sets the additions 4 field 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.
User-specific timeout values are returned in the left (high-order) and right (low-order) halves, respectively, of the rightmost fullword of the additions 5 field. For more information, see the section Values Returned in Control Block Fields.
The record buffer specifies
the files to be accessed and/or updated, and the type of updating to be performed
special encoding for alphanumeric and/or wide-character fields during the session
for fields in record and value buffers, special architecture that overrides the architecture for remote calls set by Entire Net-work.
The syntax of the record buffer is
-where:
"keyword" is one of the following:
| ACC ESS | file is to be accessed only |
| UPD ATE | file is to be updated (implies ET logic) |
| EXF | exclusive file control: no other users may access/update the file |
| EXU | file is to be updated under exclusive control of the user. No other user can update the specified file while this user session is active. Exclusive control is given only if no other active user has issued an OP command specifying the EXF/EXU or UPD parameter for the file. |
"file-list" is one or more 1-5-digit file numbers (leading zeros permitted) indicating the Adabas file(s) for which the preceding file-list keyword is applicable.
ACODE assigns special encoding for A fields during the user session.
"alpha-key" specifies the key of supplied encoding descriptor objects.
WCODE assigns special encoding for W fields during the user session.
"wchar-key" specifies the key of supplied encoding descriptor objects.
ARC defines special data architecture for fields in the record and value buffers. This definition overrides the architecture key defined for remote calls in Entire Net-work.
Note:
The ARC setting does not affect the data coversion performed by
ADALNK / LNKUES on the Adabas control block (ACB) and buffers with fixed layout
such as the search and format buffers.
"architecture-key" is an integer which is the sum of the following numbers:
| byte order | b=0 | high-order byte first |
|---|---|---|
| b=1 | low-order byte first | |
| encoding family | e=0 | ASCII encoding family |
| e=2 | EBCDIC encoding family (default for local calls) | |
| floating-point format | f=0 | IBM370 floating-point format |
| f=4 | VAX floating-point format | |
| f=8 | IEEE floating-point format |
The default is ARC = b + e + f = 2; that is, high-order byte first; EBCDIC encoding family; and IBM370 floating-point format (b=0; e=2; f=0).
User data from an Intel386 PC provides the example: b=1; e=0; f=8; or ARC=9.
The record buffer syntax must end with "."
If no parameters are specified for the record buffer, it contains only "." 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.
If a user-type "keyword" is to apply to a series of files, each file for which the keyword is applicable may be specified with a comma between each file number. Duplicate file numbers within a keyword are permitted. Duplicate file numbers across keywords are permitted. Each keyword may appear only once.
UPD and EXU also imply access to the file. If ACC is the only keyword specified, a file list is not required.
Note:
For Natural Lightstorm (NLS) version 3.1 users: it is necessary to
enter a file list in the record buffer of the OP command because NLS sets
option 'R' (restricted open) leading Adabas to expect a file there.
If no user-type keyword is specified, the user automatically becomes an ET logic user.
During the time that a user is active, Adabas maintains a user queue element (UQE) for the user.
The UQE lists the numbers of up to 5000 files the user is currently using. For a non-ET user, Adabas creates the file list when the user issues an OP command; no file list is created for an ET user. The file list 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 with one of the following use classes:
ACC, access only;
EXF/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 not currently in the specified file list, Adabas tests to determine whether the file is currently in use by an Adabas utility. If not, the file is added to the user's UQE and marked as ACC. However, if the OP command specifies the restrict files option in the command option 1 field with a file list in the record buffer, and then tries to access a file not in the file list, response code 17 occurs.
If a subsequent attempt is made to update a file 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 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 UQE and marked as UPD.
If the user specifies ACODE, WCODE, and/or ARC to determine the special encoding to be used, this information is communicated to the Adabas nucleus, which stores it in the UQE.
See the section on timeout characteristics in the Adabas Operations documentation for information on which action will be taken if a user exceeds the non-activity time limit.
In some cases, values are returned in the ISN lower limit and ISN quantity fields to allow compatibility with VMS/UNIX systems. As a result, any user-specific timeout values previously held in these fields in early Adabas releases are now returned in the additions 5 field. These changes also affect the corresponding command log fields.
The ISN quantity field returns the following binary values after OP execution:
This returned information provides compatibility with VMS/UNIX.
The ISN lower limit (ISL) field now returns the following binary information:
The rightmost two bytes indicate whether the user program is running in a noncluster (00) or cluster (nn) nucleus environment. The specific cluster nucleus type return code is for use by Software AG technical support.
Any timeout values specified in the ISL/ISQ fields at the start of OP processing are returned in the additions 5 field, as follows:
and correspondingly, in the additions 5 command log entry.
An access-only user session is to be opened.
| Command Code | OP | |
|---|---|---|
| Record Buffer Length | 4 | or larger |
| Record Buffer | ACC. (or ACC= . or ACC=file-list.) |
|---|
Allows all selected files to be accessed.
A user session is to be opened during 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 stored during the previous session are to be read. The ID for the user is "USER0001".
| Command Code | OP | |
|---|---|---|
| Record Buffer Length | 15 | or larger |
| Command Option 2 | E | user data are to be read |
| Additions 1 | USER0001 | user ID is required if user data are to be stored and/or read |
| Record Buffer | ACC=9,UPD=8,16. |
|---|
A user session is to be opened during 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 are not to be stored or read |
| Additions 1 | bbbbbbbb | user ID is not required |
| Record Buffer | EXU=10,11,12. |
|---|
A user session is to be opened during 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 are not to be stored or read |
| Additions 1 | bbbbbbbb | user ID is not required |
| Record Buffer | EXU=10,11,12,UPD=10,11,12. |
|---|
A user session is to be opened with shift-JIS special encoding for wide-character fields. The user intends to update file number 1.
| Command Code | OP | |
|---|---|---|
| Record Buffer Length | 16 | or larger |
| Record Buffer | UPD=1,WCODE=932. |
|---|
