Version 8.1.4
 —  Command Reference  —

OP Command: Open User Session

The OP command indicates the beginning of a user session.

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

This document covers the following topics:


Function and Use

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:

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

Top of page

User Types

Adabas identifies each user session by the type of access and updates performed by the user.

Access-Only Users

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

Exclusive Control Users

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.

ET Logic Users

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.

Top of page

ACB Interface Direct Call: OP Command

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

Control Block and Buffer Information

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 -- 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 Areas

Buffer Before Adabas Call After Adabas Call
Format *  
Record F A

where:

F Supplied by user before Adabas call
A Supplied 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 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

Control Block Field Descriptions

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

Command Code (ACBCMD)

OP

Command ID (ACBCID)

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.

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

Adabas sets this field to binary zero on return.

ISN Lower Limit: Non-activity Time Limit (ACBISL)

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.

ISN Quantity: Transaction Time Limit (ACBISQ)

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.

Record Buffer Length (ACBRBL)

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

Command Option 1: Restrict Files Option (ACBCOP1)
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.
Command Option 2: Read User Data (ACBCOP2)
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.
Additions 1: User ID (ACBADD1)

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:

Users for whom none of the above conditions are true may set this field to blanks.

Additions 2: Transaction Sequence Number (ACBADD2)

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 Manual documentation.

Additions 4: Maximum Settings (ACBADD4)

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

Additions 5: Returned Time-Out Values (ACBADD5)

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.

ACB Examples

Example 1: Access-Only User

An access-only user session is to be opened.

Control Block

Command Code OP  
Record Buffer Length 4 or larger

Buffer Areas

Record Buffer ACC. (or ACC= . or ACC=file-list.)

Allows all selected files to be accessed.

Example 2: ET Logic User

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 is to be read. The ID for the user is "USER0001".

Control Block

Command Code OP  
Record Buffer Length 15 or larger
Command Option 2 E user data is to be read
Additions 1 USER0001 user ID is required if user data is to be stored and/or read

Buffer Areas

Record Buffer ACC=9,UPD=8,16.

Example 3: Exclusive Control User Without ET Logic

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 or read user data in an Adabas system file.

Control Block

Command Code OP  
Record Buffer Length 13 or larger
Command Option 2 b (blank) user data is not to be stored or read
Additions 1 bbbbbbbb (blanks) user ID is not required

Buffer Areas

Record Buffer EXU=10,11,12.

Example 4: Exclusive Control User with ET Logic

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.

Control Block

Command Code OP  
Record Buffer Length 26 or larger
Command Option 2 b (blank) user data is not to be stored or read
Additions 1 bbbbbbbb (blanks) user ID is not required

Buffer Areas

Record Buffer EXU=10,11,12,UPD=10,11,12.

Example 5: Special Encoding for Wide-Character Fields

A user session is to be opened with shift-JIS special encoding for wide-character fields. The user intends to update file number 1.

Control Block

Command Code OP  
Record Buffer Length 16 or larger

Buffer Areas

Record Buffer UPD=1,WCODE=932.

Top of page

ACBX Interface Direct Call: OP Command

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

Control Block and Buffer Information

Control Block

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
  21-28 --- --- ---
ISN 29-32 binary --- A
  33-36 --- --- ---
ISN Lower Limit 37-40 binary F A
  41-44 --- --- ---
ISN Quantity 45-48 binary F A
Command Option 1 49 alphanumeric F U
Command Option 2 50 alphanumeric F U
  51-56 --- --- ---
Additions 1 57-64 alphanumeric/ binary F U
Additions 2 65-68 binary --- A
  69-76 --- --- ---
Additions 4 77-84 alphanumeric F A
Additions 5 85-92 alphanumeric/ binary --- A
  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 do not touch --- ---

ABDs and Buffers

ABD and Buffer Before Adabas Call After Adabas Call
Format *  
Record F A

where:

F Supplied by user before Adabas call
A Supplied by Adabas
U Unchanged after Adabas call
* 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

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)

OP

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)

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.

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 DDCARD input data or the default database ID value provided in the LNKGBLS module linked with or loaded by the link routine.

ISN (ACBXISN)

Adabas sets this field to binary zero on return.

ISN Lower Limit: Non-activity Time Limit (ACBXISL)

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.

The ACBXISL field is a four-byte binary field embedded in the eight-byte ACBXISLG field, which is not yet used. Set the high-order part of the ACBXISLG field to binary zeros.

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.

ISN Quantity: Transaction Time Limit (ACBXISQ)

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.

The ACBXISQ field is a four-byte binary field embedded in the eight-byte ACBXISQG field, which is not yet used. Set the high-order part of the ACBXISQG field to binary zeros.

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.

Command Option 1: Restrict Files Option (ACBXCOP1)
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.
Command Option 2: Read User Data (ACBXCOP2)
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.
Additions 1: User ID (ACBXADD1)

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:

Users for whom none of the above conditions are true may set this field to blanks.

Additions 2: Transaction Sequence Number (ACBXADD2)

Adabas returns in this field the transaction sequence number of the last transaction for which an ET command with ET data was executed successfully.

Additions 4: Maximum Settings (ACBXADD4)

This field may be used to set the following user-specific maximum binary values:

Bytes Usage
77-78 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.
79-80 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.
81-82 maximum number of command IDs that may be active for a user at the same time. This value cannot be greater than 1/240 X LQ (where LQ is the ADARUN sequential command table length parameter value, which has a default of 10000).
83-84 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.

Additions 5: Returned Time-Out Values (ACBXADD5)

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.

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 apply to OP commands:

Format Buffer

A format buffer is not used by the OP 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.

Record Buffer

The record buffer specifies:

The syntax of the record buffer is

graphics/4op_rec_buf_syntax.png

where:

The record buffer syntax must end with a period (".").

If no parameters are specified for the record buffer, it contains only a period ("."). 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.

Top of page

User Queue Element

During the time that a user is active, Adabas maintains a user queue element (UQE) for the user.

User Type and File Lists

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:

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:

If the file is determined to be available for the user, the file is added to the user's UQE and marked as UPD.

Special Encoding Information

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.

Top of page

Exceeding Time Limits

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.

Top of page

Values Returned in Control Block Fields

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:

OP Command, Binary Values Returned after OP Execution

Binary Values Returned after OP Execution

This returned information provides compatibility with VMS/UNIX.

The ISN lower limit (ISL) field now returns the following binary information:

OP Command, Binary Information Returned from ISL

Binary Information Returned from ISL

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:

OP Command, Timeout Values

Timeout Values

and correspondingly, in the Additions 5 command log entry.

Top of page