The Adabas multiclient feature stores records for multiple users or groups of users in a single Adabas file. This feature is specified at the file level. It divides the physical file into multiple logical files by attaching an owner ID to each record. Each user can access only the subset of records that is associated with the user's owner ID. The file is still maintained as a single physical Adabas file.
The Adabas nucleus handles all database requests to multiclient files.
This document covers the following topics:
Each record in a multiclient file has a specific owner, which is identified by an internal owner ID attached to each record (for any installed external security package such as RACF or CA-Top Secret, a user is still identified by either Natural ETID or LOGON ID). The owner ID is assigned to a user ID. A user ID can have only one owner ID, but an owner ID can belong to more than one user.
The following table shows examples of the ETID/owner ID relationship.
| ETID | Owner ID | Description |
|---|---|---|
| USER1 | 1 | More than one user can use the same
owner ID.
Here, USER1, USER2 and USER3 share the same owner ID and therefore the same records. |
| USER2 | 1 | |
| USER3 | 1 | |
| ... | ||
| USER4 | 2 |
The relationship between the user ID and the owner ID is stored in the profile table in the Adabas checkpoint file. The DBA maintains the profile table using Adabas Online System/Basic Services (AOS), a prerequisite for the multiclient feature.
The relation between user ID and owner ID is 1:1 or n:1; either a single user or group of users can be assigned to one owner ID. Record isolation is always performed on the owner ID level.
The owner ID has a fixed length of up to 8 bytes (alphanumeric). The length is defined by the user during file creation; it can be changed only by unloading and reloading the multiclient file. Each owner ID must be less than or equal to the length assigned for the file; otherwise, a nonzero response code occurs. To avoid wasting space, make the owner ID no larger than necessary.
The following tables show an example of owner isolation for a group of eight file records.
| ISN | Owner ID | Record | Discussion |
|---|---|---|---|
| 1 | 1 | data | Example for a physical Adabas file with records owned by different users |
| 2 | 2 | data | |
| 3 | 1 | data | |
| 4 | 3 | data | |
| 5 | 2 | data | |
| 6 | 3 | data | |
| 7 | - no data - | ||
| 8 | 1 | data |
| ISN | Record | ISN | Record |
|---|---|---|---|
| 1 | data | 1 | - no data - |
| 2 | - no data - | 2 | data |
| 3 | data | 3 | - no data - |
| 4 | - no data - | 4 | - no data - |
| 5 | - no data - | 5 | data |
| 6 | - no data - | 6 | - no data - |
| 7 | - no data - | 7 | - no data - |
| 8 | data | 8 | - no data - |
| File as seen by a user with an owner ID=1 | File as seen by a user with an owner ID=2 | ||
A superuser owner ID provides access to all records in a multiclient file. A superuser owner ID begins with an asterisk (*). Adabas allows users with such an owner ID to match with any other owner ID, allowing the user to read all records in a file. More than one superuser owner IDs, each beginning with an asterisk and allowing identical privileges, can be defined for a multiclient file.
A superuser owner ID applies only to Lx read commands and nondescriptor search (Sx) commands. Descriptor search commands by a superuser return only the records having the superuser's owner ID. Data records or index values stored by a superuser are labeled with the superuser's owner ID.
Note:
If a superuser issues an L3 or L9 command, the value start option is
ignored; that is, Adabas always starts at the very beginning of the specific
descriptor.
No changes to an existing application program are needed to use it in a multiclient environment; however, a user ID must be supplied in the Additions 1 field of the Adabas control block of each open (OP) call made by a user who addresses a multiclient file. This allows Adabas to retrieve the owner ID from the checkpoint file. Otherwise, the application program neither knows nor cares whether a multiclient file or a standard Adabas file is being accessed.
Multiclient support is provided for soft coupling.
The data and index structures of a multiclient file differ from those of standard Adabas files.
A Data Storage (DATA) record in a standard file has the following structure:
A Data Storage record in a multiclient file has the following structure:
Every normal index and upper index value for a multiclient file is prefixed by the owner ID:
The tables below illustrate a multiclient index structure. If a single descriptor value points to more than one Data Storage record, Adabas stores this extended index value only once, followed by the list of ISNs. If the same descriptor value for different owner IDs is to be stored, then multiple entries are made in the index.
| ISN | Owner ID | NAME | |
|---|---|---|---|
| 1 | 1 | SMITH | The field NAME is a descriptor. |
| 2 | 2 | SMITH | |
| 3 | 1 | SMITH | |
| 4 | 3 | JONES | |
| 5 | 2 | JONES | |
| 6 | 3 | HARRIS | |
| 7 | - not stored - | ||
| 8 | 1 | HARRIS |
| Owner ID | DE value | ISN count | ISN list | |
|---|---|---|---|---|
| 1 | HARRIS | 1 | 8 | This is the index for the descriptor NAME. The sort sequence of values is: owner ID | (DE-value) |
| 1 | SMITH | 2 | 1,3 | |
| 2 | JONES | 1 | 5 | |
| 2 | SMITH | 1 | 2 | |
| 3 | HARRIS | 1 | 6 | |
| 3 | JONES | 1 | 4 |
Notes:
The multiclient feature causes no added processing overhead for find (S1,S2), read-logical (L3) and histogram (L9) commands. The index structure permits specific record selection, and there is no postselection procedure in the Data Storage.
If the selection is done on the Data Storage, Adabas must read the record and check the owner ID. If the record's owner ID does not match the current user's owner ID, the record is skipped. This might slow down a read-physical (L2) and a read-by-ISN (L1 with I option) command or a nondescriptor search command.
The owner ID is part of the user's profile record, which is stored in the Adabas profile table. The profile is maintained using the Adabas Online System. See the Adabas Online System documentation for more information.
Calls to multiclient files can result in the following non-zero Adabas response codes, which indicate that an error has occurred:
| Read and Update Operation | If a user tries to read or change a multiclient file's record using an owner ID that does not apply to the record, Adabas returns either response code 3 or 113, depending on the type of read or update operation. |
| Add Record Operation | If a user has an owner ID that is either blank or too long for the owner ID length assigned to the multiclient file, Adabas returns response code 68 if this owner tries to add a new record. |
| Blank or Missing Owner IDs | A user with a blank or missing owner ID receives response code 3 or 113 when trying to access a multiclient file. |
In general, multiclient files are transparent to Adabas utility processing. Special functions of the ADALOD and ADAULD utilities support the migration of an application from a standard to a multiclient environment.
Two ADALOD LOAD parameters LOWNERID and ETID support multiclient files. The parameters work together to define owner IDs and determine whether a file is a multiclient file.
LOWNERID specifies the length of the internal owner ID values assigned to each record for multiclient files.
Valid length values are 0-8. In combination with the ETID parameter, the LOWNERID parameter can be used to reload a standard file as a multiclient file, change the length of the owner ID for the file, or remove the owner ID from the records of a file.
If the LOWNERID parameter is not specified, the length of the owner ID for the input file (if any) remains the same.
ETID assigns a new owner ID to all records being loaded into a multiclient file, and must be specified if the input file contains no owner IDs; that is, the input file was not unloaded from a multiclient source file.
The following table illustrates the effects of LOWNERID and ETID settings.
| LOWNERID Parameter Setting: | Owner ID Length in Input File: | |
|---|---|---|
| 0 | 2 | |
| 0 | Keep as nonmulticlient file | Convert into a nonmulticlient file |
| 1 | Set up multiclient file (ETID) | Decrease owner ID length |
| 2 | Set up multiclient file (ETID) | Keep owner ID length |
| 3 | Set up multiclient file (ETID) | Increase owner ID length |
| (LOWNERID not specified) | Keep as nonmulticlient file | Keep as a multiclient file |
Where this table indicates (ETID) in the "Owner ID Length...0" column, the ETID parameter must specify the user ID identifying the owner of the records being loaded. The owner ID assigned to the records is taken from the user profile of the specified user ID. In the "Owner ID Length...2" column the ETID parameter is optional; if ETID is omitted, the loaded records keep their original owner IDs.
Note:
If the ETID parameter is used, the ADALOD utility requires an
active nucleus. The nucleus will translate the ETID value into the internal
owner ID value.
When executing the UPDATE function, ADALOD keeps the owner ID length previously defined for the file being updated. The owner IDs of the records being added are adjusted to the owner ID length defined for the file. The owner IDs of the loaded records or of any new records must fit into the existing owner ID space.
ADALOD LOAD FILE=20,LOWNERID=2,NUMREC=0
-creates file 20 as a multiclient file. The length of the internal owner ID is two bytes, but no actual owner ID is specified. No records are actually loaded in the file (NUMREC=0).
ADALOD LOAD FILE=20,LOWNERID=2,ETID=USER1
-creates file 20 as a multiclient file and loads all supplied records for user USER1. The length of the internal owner ID is two bytes.
ADALOD UPDATE FILE=20,ETID=USER2
-performs a mass update to add records to file 20, a multiclient file. Loads all the new records for USER2.
The ADAULD utility unloads records from an Adabas file to a sequential output file. This output file can then be used as input to a subsequent ADALOD operation.
If a multiclient file is unloaded, the output file contains all the unloaded records with their owner IDs. This information can either be retained by the subsequent ADALOD operation, or be overwritten with new information by the ADALOD ETID parameter. Any differences in LOWNERID parameter values for the unloaded and newly loaded file are automatically adjusted by ADALOD.
The ETID parameter of ADAULD can be used to restrict UNLOAD processing to only the records owned by the specified user. If the ETID parameter is omitted, all records are unloaded. If the SELCRIT/SELVAL parameters are specified for a multiclient file, the ETID parameter must also be specified.
ADAULD UNLOAD FILE=20,ETID=USER1
-unloads all records owned by USER1 in physical sequence.
The ADACMP utility either compresses user data from a sequential input file into the Adabas internal structure, or decompresses Adabas data to a sequential user file. The COMPRESS function makes no distinction between standard and multiclient files, processing both in exactly same way. The DECOMPRESS function can decompress records selectively if the INFILE parameter specifies a multiclient file and a valid ETID value is specified.
The DECOMPRESS function skips the owner ID, if present. The output of a DECOMPRESS operation on a multiclient file contains neither owner ID nor any ETID information.
If the INFILE parameter specifies a multiclient file for the DECOMPRESS function, decompression can be limited to records for a specific user using the ETID parameter. ADACMP then reads and decompresses records for the specified user. If the ETID parameter is not specified when decompressing a multiclient file, all records in the file are decompressed.
ADACMP DECOMPRESS INFILE=20,ETID=USER1
-decompresses records which are owned by USER1 from file 20 to a sequential output file.
