Tuesday, June 20, 2006

Adabas Security

ADABAS provides the following facilities to prevent unauthorized access to and/or updating of ADABAS database files:
ADABAS Data Encryption (ciphering) which provides data security;
ADABAS Multiclient Files to control access to records in a file;
ADABAS SECURITY and the related security utility ADASCR, a selectable unit, which provides selective user access/update protection at a file, field, and field value level; and
provides control of ADABAS resources at a database/utility, command, or file level through the widely used non-Software AG security packages RACF, CA–ACF2 and CA–TOP–SECRET.
ADAESI is available for MVS/ESA and OS IV/F4 (FACOM) only.
Security is accomplished by comparing passwords and authorization levels.
Data Encryption
Data encryption is an integral feature of ADABAS and requires no options or extra modules.
Data may be enciphered before being placed in the database. The user must provide the cipher key at the time records are stored. This key is not stored and must be available to request or decipher the data. This minimizes the chances that data encryption can be compromised if unauthorized access to the system occurs.
To retain maximum control over cipher codes, an ADABAS user exit program can be created to insert the currently valid cipher code into user applications; this removes the need to make the codes known to users, and protects the file from corruption that can occur by adding data that is encrypted with the wrong cipher code.
Multiclient Files
Also available as an integral feature of ADABAS that requires no options or special modules is the multiclient file.
A single ADABAS physical file defined as “multiclient” can store records for multiple users or groups of users. The multiclient feature divides the physical file into multiple logical files by attaching an internal owner ID to each record.
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. Each user can access only the subset of records that is associated with the user’s owner ID.
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.
All database requests to multiclient files are handled by the ADABAS nucleus.
Access/update control is available only with ADABAS SECURITY and the related security utility ADASCR that defines and controls ADABAS SECURITY functions.
ADABAS SECURITY provides two types of access/update protection:
􀀀 “Access-/update-level” protection applies a basic level of security on a file-by-file basis.
Access/update protection can be defined for some files and not for others. It restricts use of a file or field within the file to those having an appropriate access/update profile definition and a password specified by the user of the file.
Access/update permission values ranging from 0 to 14 are defined for each user and attached to that user’s password, and each protected file (and selected field or fields, if desired) has equivalent access/update “threshold” protection values of the same range. Only a user whose permission value equals or is greater than the protection level of the specified file (and, when applicable, field) is permitted to perform that operation type (access or update) on the file or field. An access/update permission level of 0 only allows access/update of unprotected files or fields with protection level 0 or no defined protection password.
ADABAS Security
􀀀 “Value-level” protection applies restrictions on the type and range of values that can be accessed or updated in specific fields. The restrictions are applied according to user password (files with fields using value-level protection must be password-protected), can be for specific values or for value ranges, and can be either “accept” or “reject” criteria.
ADAESI allows the definition and protection of ADABAS resources using standard external (i.e., non-Software AG) security packages such as CA-ACF2, CA-TOP SECRET, and RACF installed on ADABAS systems running under MVS/ESA and OS IV/F4 (FACOM).
Generally, a security package allows the system administrator to authorize a user’s access to system resources. The security package then monitors all users and their resource usage to ensure that no unauthorized access or change occurs. Attempts by unauthorized users to use either the system or specific system resources are recorded and reported.
A user profile, which can be for a single user or a group of users, defines which system hardware and software resources a user is allowed to use. A resource profile defines access/update privileges for one or more devices, volumes, and/or programs (resources that must be used together to perform certain functions can be defined together in the same profile). When a user logs on to the system, the security package uses the user’s logon ID to identify that user’s profile. Each time the user attempts to perform a task or access information, the security package uses information in its resource profiles to allow or deny access. Using the profile
concept, the security package expands the single point of authorization—the logon ID—to provide extensive control over all system resources. ADAESI extends the ability of the related security packages to include the ADABAS database and users. Using ADAESI, the security packages can define and control access to the following
ADABAS resources: database nucleus; database files; database commands; utilities
(MODE=MULTI only); and ADABAS operator commands issued from an MVS console.

Related Security Options
ADABAS ONLINE SYSTEM/Basic Services Security
The DBA facility ADABAS ONLINE SYSTEM/Basic Services also provides a security facility for restricting access to the ADABAS online facilities. Basic Services Security requires NATURAL SECURITY as a prerequisite.
The NATURAL SECURITY system provides extensive security for ADABAS/NATURAL
users. See the NATURAL SECURITY Manual for additional information.



Database services such as loading or deleting files are handled by an integrated set of online and
batch-mode “utilities”. Most utilities can be run in parallel with normal database activity to
preclude interruption of daily production. See the ADABAS Utilities Manual for more
ADABAS utilities address initial design and load operations, backup/restore/recovery routines,
database modification routines, and audit/control/tuning procedures.
See the Optional Extensions chapter starting on page 71 for information about ADABAS
ONLINE SYSTEM/Basic Services, a menu-driven, interactive DBA tool.
Initial Design and Load Operations
ADACMP : Compress / Decompress
ADACMP COMPRESS is used to edit and compress data records to be loaded into the database
using ADALOD; ADACMP DECOMPRESS is used to decompress individual files for data
structure or field definition changes, or for use as input to non-ADABAS programs.
ADACMP input data must be in a sequential dataset/file. Indexed sequential and VSAM input
cannot be used. The records may be fixed, variable, or of undefined length. The maximum input
record length permitted depends on the operating system. The maximum compressed record
length is restricted by the Data Storage block size in use and the maximum compressed record
length set for the file (see the MAXRECL parameter, ADALOD utility). The input records can
be in either blocked or unblocked format.
It is possible to omit the input dataset if the parameter NUMREC=0 is supplied.
ADABAS Concepts and Facilities
The logical structure and characteristics of the data for input to COMPRESS are described with
field definitions statements (FNDEF to define fields or groups of fields; SUBFN and SUPFN
to define sub- or superfields, respectively; HYPDE, PHONDE, SUBDE, and SUPDE to define
various types of descriptors). Field definitions are used to create the ADABAS Field Definition
Table (FDT).
By default, input data records are processed in the order of the field definition statements. The
FORMAT parameter allows you to change the order of field processing or skip fields.
ADACMP COMPRESS edits and compresses the data records.
Editing includes checking each field defined with a “packed” (P) or “unpacked” (U) format to
ensure that the field value is numeric and in the correct format. Any record that contains invalid
data is written to the ADACMP error dataset and is not written to the compressed dataset.
ADABAS user exit 6 can be used to specify additional editing to be performed during ADACMP
COMPRESS processing. See the ADABAS DBA Reference Manual for information about user
Compression includes removing trailing blanks from alphanumeric fields; removing leading
zeros from numeric fields; removing trailing zeros in floating-point format fields; and packing
numeric unpacked fields. Fields with the fixed (FI) option are not compressed, and empty fields
located at the end of the record are neither stored nor compressed. Null value fields are processed
differently depending on options being used. SQL null value processing is supported.
Processed data records are written out together with the file definition information to a
sequential dataset with the “variable blocked” record format. This dataset, or several such
datasets from multiple ADACMP executions, can be used as input to the ADALOD utility. The
dataset can be used as input to ADALOD even if it contains no records, meaning that no records
were provided on the input dataset or all records were rejected during editing.
The ADACMP processing report indicates the approximate amount of space required in Data
Storage for the compressed records by device type (specified with the DEVICE parameter) and
for Data Storage padding factors between 5 and 30 percent. The compression rate is computed
based on the real amount of data used as input to the compression routine.
Utilities 4
ADACMP DECOMPRESS accepts as input data records from existing ADABAS files, either
directly without separate file unloading, or already unloaded with the ADAULD utility. If a file
is directly decompressed, it is unloaded without FDT information as part of the decomperssion
process, which can save time when decompressing larger files.
Direct decompression of multiclient files can be limited to records for a specific user only when
a valid owner ID (ETID parameter) is specified.
The FORMAT parameter may be used to decompress the record to a format other than that
specified by the FDT. This is particularly useful when the FDT of an existing file is to be
Processed data records are written to a sequential dataset with the “variable blocked” record
format. Rejected data records are written to the error dataset.
ADALOD : Loader
The ADALOD LOAD function loads a file into the database. Compressed records produced by
the ADACMP or ADAULD utility may be used as input.
ADALOD loads each compressed record into Data Storage, builds the Address Converter for
the file, and enters the field definitions for the file into the Field Definition Table (FDT).
ADALOD also extracts the values for all descriptors in the file together with the ISNs of all
records in which the value is present, to an intermediate dataset. This dataset is then sorted into
value/ISN sequence and entered into the Associator inverted lists.
The ADALOD UPDATE function is used to add or delete a large number of records to/from an
ADABAS file. The UPDATE function requires considerably less processing time than the
repetitive execution of the ADABAS add/delete record commands. Records to be added may
be the compressed records produced by the ADACMP or ADAULD utility. The ISNs of records
to be deleted can be provided either in an input dataset or by using control statements.
Records may be added and other records deleted during a single execution of ADALOD.
ADABAS Concepts and Facilities
ADAULD : Unload
The ADAULD utility unloads an ADABAS file. ADABAS files are unloaded to
􀀀 permit the data to be processed by a non-ADABAS program. In this case, the file must also be
decompressed after unloading using the DECOMPRESS function of the ADACMP utility.
􀀀 create one or more test files, all of which contain the same data. This procedure requires that
a file be unloaded, and then reloaded as a test file with a different file number.
􀀀 change the Field Definition Table (FDT). This requires that the file be unloaded, decompressed,
compressed using the modified field definitions, and reloaded. If the ADADBS utility is used
to add field definitions to a file, the file does not need to be unloaded first.
The sequence in which the records are unloaded may be
physical the order in which they are physically positioned within Data Storage.
logical a sequence controlled by the values of a user-specified descriptor.
ISN ascending ISN sequence.
The unloaded record output is in compressed format. The output records have the same format
as the records produced by the ADACMP utility.
Backup / Restore / Recovery Routines
ADAPLP : Protection Log / Work Print
The ADAPLP utility prints data protection records contained on the ADABAS Work dataset or
the ADABAS data protection log. You can specify whether to print
ALL all protection records—the default
ASSO just Associator protection records
DATA just Data Storage protection records
C1 records resulting from ADABAS C1 commands
C5 records resulting from ADABAS C5 commands
EEKZ records written at completion of a nucleus buffer flush
ET records resulting from ADABAS ET commands
REPR Work dataset records used by Autorestart to repair the index
SAVO records resulting from online SAVE database/file operations
VEKZ records written at completion of update commands
The number of protection records printed can be reduced even more by specifying a file, ISN,
or RABN.
ADARAI : Recovery Aid
The ADABAS Recovery Aid utility ADARAI can be used to automate and optimize database
recovery. See also the restart/recovery information in the ADABAS Operations Manual.
ADARAI supports all ADABAS-compatible tape management systems.
The ADARAI utility prepares the recovery log files (RLOGs), lists the information contained
in the RLOGs, creates the job control statements to recover the database, and disables ADARAI
The RLOGs record the information about datasets, utility parameters, and protection logs
needed to build the recovery job control statements. There are two RLOGs: the primary file
(DDRLOGR1 or RLOGR1) and a mirror file (DDRLOGM1 or RLOGM1). The mirror file must
always exist; it can be used to recover the database if the primary file is not accessible.
ADABAS Concepts and Facilities 4
Information is stored on the RLOG by generations. A “generation” includes all activity between
consecutive ADASAV SAVE/RESTORE (database) and/or RESTORE GCB operations. The
first generation includes the first ADASAV SAVE/RESTORE (database) or RESTORE GCB
operation and extends to (but excludes) the second.
Minimally, the RLOG retains the number of generations specified by the MINGENS parameter
during the ADARAI PREPARE step. However, a maximum of 32 generations will be stored on
the RLOG if there is enough space available.
Systems using the Recovery Aid feature require a formatted recovery log (RLOG) dataset pair
(normal and mirrored), which must first be formatted with the ADAFRM utility and then
defined using the ADARAI utility.
ADARES : Restart
The ADARES utility performs functions related to database recovery:
􀀀 BACKOUT removes all the updates applied between two checkpoints. The checkpoints used
are normally the result of a non-synchronized checkpoint command (C1) but may also be
synchronized checkpoints. The complete database may be included in the backout process, or
backout may be limited to selected files.
􀀀 CLCOPY copies a command log dataset from disk to a sequential dataset. This function is
necessary only if dual command logging is in effect for an ADABAS session.
􀀀 COPY copies a sequential ADABAS protection log dataset. This function should be executed
if the ADABAS session in which the sequential protection log dataset was created was
terminated abnormally.
􀀀 PLCOPY copies a protection log dataset from disk to a sequential dataset. This function is
necessary only if dual protection logging is in effect for an ADABAS session.
􀀀 REGENERATE reapplies all the updates performed between two user-specified checkpoints.
The checkpoints specified may be the result of a non-synchronized checkpoint command (C1)
but may also be synchronized checkpoints. The REGENERATE function may process all files
or be limited to one or more files. It is most often used after the database (or one or more files)
has been restored to a previous status with the RESTORE or RESTONL function of the
ADASAV utility.
􀀀 REPAIR repairs one or more blocks in Data Storage that, for any reason, have become unusable.
The most recent save tape of the database and any protection log tapes created thereafter are used
as input to this function.
ADASAV : Save / Restore Database or Files
The ADASAV utility saves and restores the contents of the database, or one or more files, to or
from a sequential dataset. ADASAV should be run as often as required for the number and size
of the files contained in the database, and the amount and type of updating. For large databases,
ADASAV functions may be run in parallel for the various disk packs on which the database is
Special ADASAV functions are available for use with the ADABAS DELTA SAVE FACILITY.
For more information, see the ADABAS DELTA SAVE FACILITY Manual.
RESTONL functions restore from a SAVE dataset created while the ADABAS nucleus was
active (that is, online); RESTORE functions restore from a SAVE dataset created while the
ADABAS nucleus was inactive (that is, offline).
RESTONL and RESTORE have the subfunctions GCB, FILES, and FMOVE:
􀀀 Without a subfunction, RESTONL and RESTORE restore entire databases.
􀀀 With the GCB subfunction, they restore the General Control Block, Associator RABNs 2–30
of the database, and specified files.
􀀀 With the FILES subfunction, they restore one or more files into an existing database to their
original RABNs.
􀀀 With the FMOVE subfunction, they restore one or more files into an existing database to any
free space, allowing changes to extent sizes.
If changes occurred during the online SAVE, the RESTONL function is followed automatically
by the RESTPLOG function. RESTPLOG applies the updates that occurred during, and
therefore were not included in, the online SAVE.
RESTPLOG is also executed following a RESTONL or RESTONL FILES function that ended
before the protection log (PLOG) updates were completely restored. RESTPLOG applies the
database updates not applied by the unsuccessful RESTONL function.
The SAVE function to save a database or one or more files may be executed while the ADABAS
nucleus is active (online) or inactive (offline). If the Recovery Aid option is active, a SAVE
database operation begins a new RLOG generation.
ADABAS Concepts and Facilities
ADASEL : Select Protection Data
The ADASEL utility selects information in the ADABAS sequential (SIBA) or dual (PLOG)
protection log. ADASEL decompresses the information and writes it to a print dataset
(DDDRUCK or DRUCK) or to a user-specified output dataset.
The protection log contains information on all updates applied to the database during a given
ADABAS session. Information selected by ADASEL can be used for auditing or as input to a
NATURAL or non-ADABAS program.
You can select before-images, after-images, or both for new, updated, and deleted records. You
can also select data written to the protection log by an ADABAS C5 command.
Database Modification Routines
ADADBS : Database Services
All ADADBS functions can also be performed using ADABAS ONLINE SYSTEM/Basic
Services. When the ADABAS Recovery Aid is active, using Basic Services is preferable for file
change operations because it writes checkpoints that are necessary for recovery operation.
ADADBS offers a variety of functions, any number of which may be performed during a single
execution of the utility.
Database Functions
The ADD function adds a new dataset to the Associator or Data Storage. The dataset to be added
may be on a device type that is the same as that currently being used or different. A maximum
of five datasets each may be assigned to the Associator and Data Storage.
The DECREASE function decreases the size of the last dataset currently being used for
Associator or Data Storage. The space to be released must be available in the Free Space Table
The DECREASE function does not deallocate any of the specified physical extent space. To
deallocate space, you must decrease the database with the DECREASE function; save it with
ADASAV SAVE; reformat the datasets with ADAFRM; and restore the database with ADASAV.
The INCREASE function increases the size of the last dataset currently being used for the
Associator or Data Storage. This function may be executed any number of times for the
Associator. The maximum of five Data Storage Space Tables (DSSTs) limits Data Storage
increases to four before all five Data Storage extents must be combined into a single extent with
either the REORASSO or REORDB function of the ADAORD utility.
The NEWALTS function assigns additional alternate RABN blocks for the Associator or Data
Storage. Existing alternate RABN definitions cannot be changed with NEWALTS.
Alternate RABN blocks can be used in place of RABN blocks that are physically damaged. If
ADABAS detects that a write operation is not successful, ADABAS selects an alternate block
of the same type, and the data is written to it. This alternate RABN is then used in place of the
original block for all subsequent read and write operations.
The RENAME function changes the name assigned to a (file or) database. If a file is not
specified or is specified with file number zero, the database is renamed.
File Functions
The ALLOCATE function is used to allocate a logical extent (an Address Converter, Data
Storage, Normal or Upper Index) of a specific size. The DEALLOCATE function is used to
deallocate a logical extent. Only one extent may be allocated or deallocated per ADADBS
The CHANGE function changes the standard length of an ADABAS field. No modifications to
records in Data Storage are made by this function. The user is, therefore, responsible for
preventing references to the field that would cause invalid results because of an inconsistency
between the new standard length as defined to ADABAS and the actual number of bytes
contained in the record.
The DELETE function deletes an ADABAS file from the database. The file may not be coupled.
If an ADABAS expanded file is specified, the complete expanded file (the anchor and all
component files) is deleted. This function results in the deallocation of all logical extents
assigned to the file. The released space may be used for a new file or for a new extent of an
existing file.
The DSREUSE function determines, for a specified file, whether Data Storage blocks that
become free as a result of record deletion are reused. Block reuse is originally determined when
a file is loaded into the database with the ADALOD FILE function, or when the system file is
defined with the ADADEF DEFINE function. In both cases, block reuse defaults to “YES” if
not specified.
ADABAS Concepts and Facilities
The ISNREUSE function determines, for a specified file, whether ADABAS reuses the ISN of
a deleted record for a new record. If not, each new record is assigned the next higher unused ISN.
For a specified ADABAS file that is not a system file, the MODFCB function modifies
parameters such as file padding factors for the Associator or Data Storage; maximum size of
secondary logical extent allocations for Data Storage, Normal Index, and Upper Index;
maximum compressed record length permitted; and whether a user program is allowed to
perform a file refresh operation by issuing a special E1 command.
The NEWFIELD function adds one or more fields to a specified ADABAS file that is not a
system file. The new field definition is added to the end of the Field Description Table (FDT).
NEWFIELD cannot be used to specify actual Data Storage data for the new field; the data can
be specified later using ADABAS add or update commands, or NATURAL commands.
The REFRESH function sets the file to “0” records loaded; sets the first extent for the Address
Converter, Data Storage, Normal Index, and Upper Index to “empty” status; and deallocates
other extents.
The RELEASE function releases a descriptor from descriptor status. All space currently
occupied in the Associator inverted list for this descriptor is released. The space can then be
reused for this file by reordering or by ADALOD UPDATE. No changes are made to Data
The RENAME function changes the name assigned to a file or database. If a file is not specified
or is specified with file number zero, the database is renamed.
The RENUMBER function changes the number of an ADABAS file that is not a system file.
If the new number specified is already assigned to another file, the RENUMBER function will
not execute.
The UNCOUPLE function eliminates the coupling relationship between two files.
Other Functions
The CVOLSER function prints the ADABAS file extents that are contained on a disk volume
specified by its volume serial number.
The DELCP function deletes checkpoint information recorded up to and including a specified
date; checkpoint information recorded after the date specified is not deleted. After running
ADADBS DELCP, the remaining records are reassigned ISNs to include those ISNs made
available when the checkpoint records were deleted. The lower ISNs are assigned but the
chronological order of checkpoints is maintained.
The OPERCOM function issues operator commands to the ADABAS nucleus. ADABAS issues
a message to the operator, confirming command execution. Only the update ADABAS nucleus
(NUC01) running in an ADASMP multiprocessing or an ADAPLEX+ nucleus cluster is allowed
to run ADABAS utilities such as ADADBS. The optional SMPID or PLXID parameter,
respectively, allows you to redirect the OPERCOM commands to another (read-only) nucleus
in the cluster for execution, just as though the command had been issued by a locally run
The PRIORITY function sets or changes the ADABAS priority of a user. A user’s priority can
range from 0 (the lowest) to 255 (the highest, and the default). The priority value is added to
the operating system priority by the interregion communications mechanism. The user for
which a priority is to be set or changed is identified by the same user ID provided in the
ADABAS Control Block (OP command, Additions 1 field).
The RECOVER function recovers space allocated by rebuilding the Free Space Table (FST).
RECOVER subtracts file, DSST, and alternate RABN extents from the total available space.
The REFRESHSTATS function resets statistical values maintained by the ADABAS nucleus for
its current session. Parameters may be used to restrict the function to particular groups of
statistical values:
􀀀 ALL (the default) resets values for the combination of CMDUSAGE, COUNTERS,
􀀀 CMDUSAGE resets the counters for ADABAS direct call commands such as Lx, Sx, or A1.
􀀀 COUNTERS resets the counter fields for local or remote, physical or logical calls, ADABAS
STAR calls, format translations, format overwrites, autorestarts, protection log switches, buffer
flushes, and command throw-backs.
􀀀 FILEUSAGE resets the count of commands for each file.
􀀀 POOLUSAGE resets the high-water marks for the nucleus pools such as the Work pool, the
Command Queue, or the User Queue.
􀀀 THREADUSAGE resets the count of commands for each ADABAS thread.
ADABAS maintains a list of the files used by each ADABAS utility in the Data Integrity Block
(DIB). The DDIB operator command (or ADABAS ONLINE SYSTEM/Basic Services)
displays this block to determine which jobs are using which files. A utility removes its entry
from the DIB when it terminates normally. If a utility terminates abnormally (for example, the
job is cancelled by the operator), the files used by that utility remain “in use”. The RESETDIB
function releases any such files and resets the DIB entries for a specified job and/or a particular
utility execution.
ADABAS Concepts and Facilities
ADADEF : Define a Database
The ADADEF utility is used to define a new database, including the Checkpoint file, or to define
a new Work file (NEWWORK function) for an existing database.
Databases are defined with name, ID, components (Associator, Data Storage, and Work) with
device type and size.
ADABAS uses certain files to store system information. The Checkpoint file is used to store
checkpoint data as well as user data provided with the ADABAS CL and ET commands. It is
required and must be specified in the ADADEF DEFINE (database) function.
Before database components (Associator, Data Storage, and Work) can be defined with
ADADEF, each must be formatted by the ADAFRM utility.
ADAFRM : Format Datasets
The ADAFRM utility formats the ADABAS direct access (DASD) datasets; that is, the
Associator, Data Storage, and Work datasets as well as the intermediate storage (Temp, Sort,
and command/dual protection/recovery logging) datasets.
Formatting with ADAFRM comprises two basic operations: creating blocks (that is, RABNs)
on the specified tracks/cylinders; and filling the created blocks with binary zeros (nulls).
Any new dataset must be formatted before it can be used by the ADABAS nucleus or an
ADABAS utility. After increasing a dataset with the ADADBS INCREASE or ADD function,
new RABNs must also be formatted.
ADAFRM also provides functions to “reset” existing Associator, Data Storage, or Work blocks
to binary zeros (nulls).
More than one ADAFRM function (ASSOFRM, DATAFRM, RLOGFRM, and so on) can be
performed in the same job. However, each function must be specified on separate statements.
ADAINV : Invert
The ADAINV utility is used to
􀀀 create a descriptor (INVERT function); or
􀀀 couple two files (COUPLE function).
The INVERT function
􀀀 modifies the Field Definition Table (FDT) to indicate that the specified field is a descriptor; and
􀀀 adds all values and corresponding ISN lists for the field to the inverted list.
The newly defined descriptor may then be used in the same manner as any other descriptor. This
function may also be used to create a subdescriptor, superdescriptor, phonetic descriptor, or
The COUPLE function adds a common descriptor to two files (updates their inverted lists). Any
two files may be coupled provided that a common descriptor with identical format and length
definitions is present in both files. A single file may be coupled with up to 18 other files, but
only one coupling relationship may exist between any two files at any one time. A file may not
be coupled to itself.
Only files with numbers 255 or lower can be coupled.
Changes affecting a coupled file’s inverted lists are automatically made to the other file. The
DBA should consider the additional overhead required to update the coupling lists when the
descriptor used as the basis for coupling is updated, or when records are added to or deleted from
either file. For example, if a field used as the basis for coupling contains a large number of null
values and is not defined with the NU (null suppression) option, the result may be a significant
increase in execution time and required disk space to store the coupling lists.
An interrupted ADAINV operation can be restarted without first having to restore the file.
ADABAS Concepts and Facilities
ADAORD : Reorder
Three types of functions are available within the ADAORD utility; only one function may be
executed during a given execution of ADAORD.
Reorder Functions
The REORASSO function physically reorders all Associator blocks for all files; REORFASSO
reorders the Associator for a single file. This eliminates Associator space fragmentation, and
combines multiple Address Converter, Normal and Upper Index, and Data Storage Space Table
(DSST) component extents into a single logical extent for each component.
The REORDATA function reorders Data Storage for all files in the database; REORFDATA
reorders Data Storage for a single file. This condenses extents containing only empty blocks,
and also eliminates any Data Storage fragmentation caused by file deletion.
The REORDB function performs both the REORASSO and REORDATA functions in a single
ADAORD execution; the REORFILE function performs both the REORFASSO and
REORFDATA functions in a single ADAORD execution. The records may be reordered in the
logical sequence by a descriptor, by ISN, or in the current sequence.
Restructure Functions
The RESTURCTURE functions are used to relocate a database or specified files to a different
physical device.The RESTRUCTUREDB function unloads an entire database to a sequential dataset;
RESTRUCTUREF unloads one or more files to a sequential dataset. This dataset can be used
as input to the STORE function.
Store Function
The STORE function loads one or more files into an existing database using the output produced
by the RESTRUCTURE functions or the REORDB function.
Audit / Control / Tuning Procedures
ADAACK : Check Address Converter
ADAACK should only be used for diagnostic purposes. It checks
􀀀 the Address Converter for a specified file(s) and ISN range. It is used in conjunction with
􀀀 each Address Converter element to determine whether the Data Storage RABN is within the
used portion of the Data Storage extents specified in the File Control Block.
􀀀 the ISN for each record in each Data Storage block within the specified ISN range to ensure that
the Address Converter element for that ISN contains the correct Data Storage RABN.
ADADCK : Check Data Storage
ADADCK should only be used for diagnostic purposes. It checks the Data Storage and the Data
Storage Space Table (DSST) of a specific file (or files) in the database.
ADADCK reads each used Data Storage block (according to the Data Storage extents in the File
Control Block) and checks whether:
􀀀 the block length is within the permitted range (4 􀀀􀀀block length 􀀀􀀀physical block size).
􀀀 the sum of the lengths of all records in the Data Storage block plus 4 equals the block length.
􀀀 any record exists with a record length greater than the maximum compressed record length for
the file or with a length 􀀀􀀀0.
􀀀 any duplicate ISNs exist within one block.
􀀀 the associated DSST element contains the correct value. If not, the DSST must be repaired (see
REPAIR parameter).
ADABAS Concepts and Facilities
ADAICK : Check Index and Address Converter
ADAICK should only be used for diagnostic purposes. It checks the physical structure of the
Associator. This includes validating the index based upon the descriptor value structures and
the Associator extents defined by the General Control Block (GCB) and File Control Block
􀀀 check index and Address Converter for specific files;
􀀀 print/dump the contents of any Associator or Data Storage block in the database; or
􀀀 produce a formatted print/dump of the contents of the GCB, FCBs, and FDTs.
ADAMER : ADAM Estimation
The ADAMER utility produces statistics that indicate the number of Data Storage accesses
required to find and read a record when using an ADAM descriptor. This information is used
to determine
whether the number of accesses required to retrieve a record using an ADAM descriptor would
be less than the standard ADABAS accessing method;
􀀀 the amount of Data Storage space required to produce an optimum distribution of records based
on the randomization of the ADAM descriptor.
The input data for ADAMER is a dataset containing the compressed records of a file produced
by the ADACMP or ADAULD utility.
The field to be used as the ADAM descriptor is specified with the ADAMDE parameter. A
multiple value field or a field contained within a periodic group may not be used. The ISN
assigned to the record may be used instead of a descriptor as the basis for randomization
The ADAM descriptor must contain a different value in each record, since the file cannot be
successfully loaded with the ADAM option of the ADALOD utility if duplicate values are
present for the ADAM descriptor. The ADAMER utility requires a descriptor field defined as
unique (UQ), but does not check for unique values; checking for unique descriptor values is done
by the ADALOD utility when loading the file as an ADAM file.
The BITRANGE parameter may be used to specify that a given number of bits are to be
truncated from each ADAM descriptor value before the value is used as input to the
randomization algorithm. This permits records containing ADAM descriptor values beginning
with the same value (for example, 40643210, 40643220, 40643344) to be loaded into the same
physical block in Data Storage. This technique can be used to optimize sequential reading of
the file when using the ADAM descriptor to control the read sequence, or to remove
insignificant information such as a check digit.
ADAREP : Report
The ADAREP utility produces the database status report, which provides information
concerning the current physical layout and logical contents of the database.
The information provided in this report includes
􀀀 a database overview: the database name, number, creation date/time, file status, and current log
􀀀 current space resources for Associator, Data Storage, and Work: amount and locations of
currently used space, allocated but unused space, and alternate RABN blocks.
􀀀 summary and detailed file information: summary by file of ISN, extent, padding factor,
used/unused Associator and Data Storage space, and file options; and detailed, optionally by
file, that includes all summary information plus MINISN/MAXISN settings, detailed space
information, creation and last use date/time, Field Definition Table (FDT) contents, and general
or extended Checkpoint file information.
􀀀 checkpoint information: general and extended Checkpoint file information.
􀀀 physical structure: Associator/Data Storage RABN information including device type,
VOLSER number, file number (if appropriate), and usage (AC, NI/UI, Data Storage, DSST,
alternate, or unused).
ADABAS Concepts and Facilities
ADAVAL : Validate the Database
The ADAVAL utility validates any or all files within an ADABAS database except the
Checkpoint and Security files.
ADAVAL compares the actual descriptor values contained in the records in Data Storage with
the corresponding values stored in the Associator to ensure that the Associator and Data Storage
are synchronized, and that there are no values missing from the Associator.
Before running ADAVAL, the consistency of the inverted lists should be checked with the
ADAICK utility.
ADAPRI : Print Selected ADABAS Blocks
The ADAPRI utility prints the contents of a block (or range of blocks) contained in the
Associator, Data Storage, Work, Temp, Sort, dual command log (CLOG), dual data protection
log (PLOG), the recovery log (RLOG), or the DELTA SAVE images (DSIM) dataset.

Using Adabas

Generally, ADABAS uses between 10% and 50% of the data processing resources (disk storage,
CPU time, elapsed processing time) used by other database management systems. Since fewer
hardware facilities are used, more can be accomplished with less. Very large online applications
using several gigabytes of data have been successfully implemented, with thousands of terminal
workstations, and with the response times and the cost of much smaller systems.
Accessing a Database from Programs
ADABAS access is field-oriented: user programs access and retrieve only the fields they need.
User program statements invoke ADABAS search and retrieval operations automatically.
Direct Call Interface
ADABAS provides a powerful and flexible set of direct call commands for performing database
operations. ADABAS direct call commands provide a direct interface to the ADABAS database
when NATURAL or another fourth-generation database language is not being used.
The commands can be categorized by function:
􀀀 Database query
􀀀 Read (Data Storage or Associator)
􀀀 Database modification
􀀀 Logical transaction processing
􀀀 Special commands
ADABAS Concepts and Facilities 3
Database Query Commands (Sx)
Database query commands (S1/S4, S2, S5)) search for and return the ISNs of specified records
or record groups according to specified search criteria. Other commands in this category (S8,
S9) sort the resulting ISN lists in preparation for later operations.
The ISN lists resulting from any Sx command may be saved on the ADABAS Work dataset for
later retrieval during the user session.
In most cases, these commands do not actually read the database; ISNs are read directly from
the Associator’s inverted lists. Options allow the ISN’s record to be placed in hold status to
prevent it from being updated by other programs until the record is released; if desired,
additional field values contained in the first ISN’s record can be read from Data Storage.
Read Commands (Lx)
The L1 through L6 commands are used to read actual records from Data Storage. Depending
on the specified command and its options, records are read individually
􀀀 in the sequence in which they are stored;
􀀀 in the order of an ISN list created by one of the database query commands; or
􀀀 in logical sequence according to a user-specified descriptor.
See page 39 for more information about sequential access methods.
A hold option allows the database records to be locked until released by a separate command
or at transaction end.
The L9 and LF commands read information directly from the Associator inverted lists or File
Definition Tables (FDTs), returning either the inverted list values for a specified descriptor or
the field definitions for a specified file in the database.
Database Modification Commands (A1, E1, N1/N2)
Database modification commands (A1, E1, and N1/N2) change, delete, or add database records
and update the related Associator lists accordingly. ISNs can be assigned to new records either
by the user or by ADABAS.
The inverted lists and the Address Converter are automatically maintained by ADABAS. When
the user supplies a new value for a descriptor, either in a new record or as part of a record update,
ADABAS performs all necessary maintenance of the inverted lists. When a new record is added
or a record is deleted, the Address Converter is appropriately updated. These operations are
completely transparent to the user.
Using ADABAS 3
Logical Transaction Control Commands (ET/BT)
An ADABAS logical transaction defines the logical start (BT) and end (ET) of the database
operation being performed. If the user operation or ADABAS itself terminates abnormally,
these commands provide the capability for restarting a user, beginning with the last
unsuccessfully processed transaction. ET/BT commands
􀀀 define the transaction start and end;
􀀀 restore pretransaction conditions if a situation occurs that prevents successful completion of the
transaction; and
􀀀 read program-specified user data written during the transaction sequence.
Programs that use these commands are called ET logic programs. Although not required,
Software AG recommends that you use ET logic. See page 44 for more information about
transaction logic.
Special Commands
Special commands perform many of the “housekeeping” functions required for maintaining the
ADABAS database environment. Commands in this group
􀀀 open (OP) and close (CL) a user session (but do not control a transaction);
􀀀 write data protection information and checkpoints (C1, C5); and
􀀀 set (HI) and release (RI) record hold status.
In addition, the RC command releases one or more command IDs currently assigned to a user,
or deletes one or all global format IDs.
The RE command reads user data previously stored in an ADABAS system file by CL or ET
ADABAS Concepts and Facilities 3
Complex Searches
In many large database systems, the time required to process complex searches is often
excessive. ADABAS efficiently solves this problem. Many ADABAS applications are currently
in use with up to 150 complex selection criteria created dynamically. Data is retrieved
immediately from files with more than 50 million records.
Multifile Searching
It is often necessary to perform a multifile search in order to resolve an inquiry. Multifile
searching can be accomplished using multiple search commands, physically coupled files, or
soft file-coupling. See page 21 for information about coupled files.
Multiple search commands may be used in which a value retrieved in one command is used as
the search value for the next command. This process is not restricted to two files.
Multi-index Searching
“Fuzzy” matching (i.e., retrieving data based on similar rather than on exact search criteria)
can be implemented using hyperdescriptors. Hyperdescriptors allow multiple virtual indexes,
meaning that several different search index entries can be made for a single data field. See page
34 for information about hyperdescriptors.
Using ADABAS 3
Access Methods
ADABAS supports both sequential and random access methods. Different calls use different
ADABAS access paths and components; the most efficient method depends on the kind of
information you want and the number of records you need to retrieve.
Sequential Access
Physical sequence retrieves every record in a file in the order the records are stored in Data
Storage. You can limit the fields within each record for which values are to be returned. You can
also specify a “start” ISN: the sequential pass then begins at the first record physically located
after the record identified by the specified ISN.
ADABAS bypasses the Associator and goes directly to Data Storage, reading the first data block
(or the first record following a specified ISN) and continuing in consecutive sequence until the
last block is read. Physical sequence is the fastest way to process a large volume of records.
Program ADABAS
I/O Buffer
Work Area
Returns field values
1 Converter
Figure 2-9: Read in Physical Sequence (L2/L5)
ADABAS Concepts and Facilities 3
ISN sequence retrieves records in ISN order. ADABAS uses database query commands (Sx) to
build and sort ISN lists, which can then be read using L1/L4 commands with the GET NEXT
option. When reading, ADABAS uses the Address Converter to find the RABNs of each ISN
in the list and then reads and returns the records from Data Storage.
Program ADABAS
I/O Buffer
Work Area
(Sx ISN List)
Inverted List
Returns field values
Read by ISN
Sx, L1/L4
Figure 2-10: Read in ISN Sequence (L1/L4)
Logical sequence retrieves records by descriptor value. ADABAS finds the value(s) in the
inverted list, uses the Address Converter to find the RABNs of the ISNs related to the value, and
retrieves the records from Data Storage.
Program ADABAS
I/O Buffer
Work Area
Returns field values
Read Logical
1 Converter
Figure 2-11: Read in Logical Sequence (L3/L6)
Using ADABAS 3
Reading in logical sequence retrieves all the records related to a single value or a range of values
of the specified descriptor. It returns the records sorted in ascending/descending order by
descriptor value, and in ascending/descending ISN order within each value. You can specify a
starting and ending value. You can also specify the field(s) for which values are returned. Read
logical is useful when you want the returned records sorted on a particular field.
ADABAS provides a special read command (L9) to determine the range of values present for
a descriptor, and the number of records that contain each value. Such a retrieval is called a
“histogram”. The L9 command does not require any access to data records, only to the inverted
lists stored in the Associator.
Program ADABAS
I/O Buffer
Work Area
Returns count of ISNs for each value
Figure 2-12: Read Descriptor Values (L9)
Random Access
ADABAS uses the S1/S2/S4 commands to select records that satisfy a search criterion: the
count of the records found and a list of their ISNs is returned. The S1/S4 commands return the
ISNs in ascending sequence; the S2 command allows you to specify a sort sequence for the
returned ISNs.
The search criterion may comprise
􀀀 one or more fields in a single file;
􀀀 fields contained in two or more physically coupled files; or
􀀀 search, read, and internal list matching based on the soft coupling feature.
ADABAS Concepts and Facilities 3
A search criterion may contain one or more fields that are not defined as descriptors. If
nondescriptors are used, ADABAS performs read operations to determine which records to
return to the user. If only descriptors are used within the search criterion, ADABAS resolves the
query by using the Associator inverted lists; no read operation is required.
Random Access Using the ADABAS Direct Access Method (ADAM)
The ADAM feature is available on mainframe platforms only.
The ADABAS Direct Access Method (ADAM) improves random access performance on a
particular descriptor field in a file. ADAM uses the field value to compute the relative block
address (RABN) for record storage. The ADAM descriptor may also be used like any other
descriptor within a selection criterion, and for logical sequential processing as well. This option
may be selected for any given file when the file is loaded into the database.
Customer ID=17802
Data Block 1
Data Block 2
Data Block 3
Customer File
Data Storage
Figure 2-13: ADABAS Direct Access Method (ADAM)
Using ADABAS 3
Using Triggers and Stored Procedures
The ADABAS triggers and stored procedures facility is an integral part of ADABAS; however,
NATURAL (see page 102) and ADABAS ONLINE SYSTEM (see page 71) are required to use
the facility.
A procedure is a NATURAL subprogram that is written and tested using standard NATURAL
􀀀 A trigger is a procedure that is executed automatically by ADABAS when a specified set of
criteria is met. The set of criteria is determined for each command sent to ADABAS and is based
on the target file number and optionally the command type and/or field. The command type
refers to the commands FIND, READ, STORE, UPDATE, and DELETE. The field must be in
the corresponding Format Buffer of the command.
􀀀 A stored procedure is executed by ADABAS, but is invoked directly by a special user call from
any of a number of applications that use it. Storing programs that are used by multiple clients
in an ADABAS file on the server reduces the amount of data traffic to and from the server.
The same types of parameters are passed to the subprogram whether it is a trigger or a stored
The ADABAS facility for triggers and stored procedures allows you to implement and maintain
both types of procedures. It resides within ADABAS and provides an extension to an
application. It can be used to
􀀀 implement various security and auditing features for an application; and
􀀀 provide a consistent, central environment where data can be verified or manipulated, either
manually by the application or automatically by ADABAS when triggers are defined.
ADABAS Concepts and Facilities 3
Maintaining Database Integrity
ADABAS provides facilities to ensure the logical consistency of data in a competitive updating
environment and when a user or ADABAS session is interrupted.
Facilities are available for both online and traditional batch update. For online,
transaction-oriented processing, ADABAS ensures that the database is free of incomplete
transactions. For batch mode updating, ADABAS ensures restart in the event of failure by
providing checkpointing and backout/regeneration of updates.
Transaction Logic
ADABAS data protection, recovery, and user restart are based on the concept of a “logical
transaction”: the smallest unit of work (as defined by the user) that must be performed in its
entirety to ensure that the information contained in the database is logically consistent.
A logical transaction may comprise one or more ADABAS commands that together perform the
database read/update required to complete a logical unit of work. A logical transaction begins
with the first command that places a record in hold status and ends when an ET (end transaction),
BT (back out transaction), CL (close), or OP (open) command is issued for the same user.
The OP (open) or RE (read ET data) commands can be used to retrieve user restart data stored
by the ET or CL command. This data is also written to the ADABAS data protection log with
each checkpoint written by the transaction and can be read using the ADASEL utility.
The ET command must be issued at the end of each logical transaction. Successful execution
of an ET command ensures that all the updates performed during the transaction are physically
applied to the database, regardless of subsequent user or ADABAS session interruption.
Updates performed during transactions for which ET commands are not successfully executed
are backed out, either manually by issuing the BT command or automatically by the
Autobackout routine (see page 48).
Competitive Updating
Competitive updating is in effect when two or more users (in multiuser mode) are updating the
same ADABAS file(s). The ADABAS facilities used to ensure data integrity in a competitive
updating environment include record hold/release, avoidance of resource deadlock, and
exclusive control updating.
Using ADABAS 3
Record Hold and Release
The ADABAS Record Hold facility ensures that a record will not be updated by more than one
user at a time. A user can put the record in “hold” status (that is, the ISN of the record is put in
the Hold Queue) using the commands S4 (find with hold), L4/L5/L6 (read with hold), A1/E1
(update/delete) with the hold option specified, N1/N2 (add record with hold), or HI (hold
If a record requested for hold status is already being held by another user or utility, the user
issuing the record hold command is put in “wait” status until the record becomes available, at
which time ADABAS reactivates the command. You may request that a response code be
returned if you do not want to be put in “wait” status.
Records in “hold” status can be accessed (found and read) by users who do not seek to hold the
Records in “hold” status are released by issuing the ET or CL commands. Options are available
with ET and BT commands to release records selectively. The CL command releases all records
in “hold” status for the issuing user.
Avoiding Resource Deadlock
Resource deadlock occurs when two users are each waiting for a record held by the other user.
ADABAS protects against such a user deadlock situation by detecting the potential deadlock
and returning a response code to the second user after putting the first user in “wait” status.
Exclusive Control Updating
Users who use logical transaction commands (ET/BT) are called ET logic users.
Alternatively, a user can request exclusive control of one or more ADABAS files for the duration
of the user session. If the file or files for which exclusive control is requested are not already
opened for update by another user or utility, exclusive control is granted and the user becomes
an exclusive update (EXU) user. ADABAS treats EXU users as non-ET logic users.
ADABAS does not place an ISN in “hold” status for EXU users. ADABAS disables hold logic
processing for files being updated under exclusive file control.
Instead of using ET commands, EXU users can request checkpoints to act as reference points;
for example, updates applied after a checkpoint can be removed.
ADABAS Concepts and Facilities 3
Timeout Controls
ADABAS times out
􀀀 transactions that exceed a specified limit; and
􀀀 users who are inactive for a specified amount of time.
Transaction Time Limit
ADABAS provides a transaction duration time limit for ET logic users. The time limit is set with
the ADARUN TT parameter; an override for a specific user can be set using the OP command.
If a transaction exceeds the prescribed limit, ADABAS generates a BT (back out transaction)
command to remove all the updates performed during the transaction and release all held
records. The user can then either repeat the backed out transaction from the beginning or begin
another transaction.
Non-Activity Time Limit
All users are subject to a non-activity time limit; different limits can be set for different user
types and for specific users within each user type.
If a user exceeds the prescribed limit and the user is
􀀀 an ET logic user, ADABAS backs out the current transaction, releases all held records and
command IDs, and deletes the user’s file list.
􀀀 an EXU user, ADABAS deletes the user’s file list and releases all command IDs. The user loses
his EXU user status and becomes an access-only user.
􀀀 an access-only user, ADABAS deletes the user’s file list.
Using ADABAS 3
Backout, Recovery, and Restart
Backout, recovery, and restart may be required when a user or ADABAS session is interrupted
due to a timeout (see page 46); a program error when ADABAS determines that a transaction
cannot be completed successfully; an ADABAS, hardware, or operating system failure; or a
power failure.
A “user session” is a sequence of ADABAS calls optionally starting with an open (OP)
command and ending with a close (CL) command. A “user” is either a batch mode program or
a person using a terminal. The uniqueness of each user is assured by the user ID, a machine, an
address space, and a terminal ID.
An “ADABAS session” starts when ADABAS is activated and continues until ADABAS is
terminated. During this time, the ADABAS nucleus creates a sequence of protection entries in
exact historical sequence reflecting all modifications made in the database. The sequence of
protection entries is written to the Work dataset (part 1) and to a protection log in blocks. Each
block contains the nucleus session number, a unique block number, and a time stamp.
User Program Error
A user program that is in the middle of a transaction can detect that the transaction cannot be
completed successfully. In this case, a BT (back out transaction) command is used to remove
or “back out” the incomplete transaction.
If a user program error causes logical damage to the database, it may be necessary to recover
the affected files using the ADASAV and ADARES utilities.
ADABAS, Hardware, or Operating System Failure
After any failure that causes the ADABAS nucleus to terminate abnormally, an automatic
procedure is executed when ADABAS is reactivated to bring the database to a physically and
logically valid status. All partially executed update commands are reset; all incomplete
transactions are backed out.
The automatic procedure comprises three steps: repair the database, Autorestart, and
􀀀 Database repair modifies the database to the status it would have had if a buffer flush had just
been completed at the time of failure. That is, all blocks in the database are at a status that
enables the nucleus to perform normally.
ADABAS Concepts and Facilities 3
􀀀 Autorestart backs out updates of single update commands that were partially executed when the
system failed. It resolves internal inconsistencies in the database and ensures physical integrity.
􀀀 Autobackout, which is performed only for ET logic users, backs out updates of user transactions
that were partially executed when the system failed. ADABAS performs an internal BT (back
out transaction) followed by Autorestart, and then informs the user that the last transaction has
been backed out.
The Autobackout routine is executed at the end of an ET session that was terminated with HALT.
It is also executed automatically at the beginning of the next ADABAS session to remove any
updates performed within transactions that did not complete successfully.
After Autobackout execution, the database contains updates only from logically complete
ET users can manually back out an incomplete transaction at any time by issuing the BT (back
out transaction) command. See page 44.
If an ADABAS, hardware, or operating system failure results in physical damage to the
database, it may be necessary to recreate the database using the ADASAV and ADARES
Power Failure
Depending on the hardware, a power failure during an I/O operation may damage the ADABAS
blocks that were being processed. This damage cannot be detected during Autorestart and
therefore can result in problems later such as unexpected response codes or lost database
If the ADARUN IGNDIB=YES parameter is set, the Autorestart routine checks whether a buffer
flush was active when the session interruption occurred. If a buffer flush was in process, the
Autorestart shuts down and ADABAS alerts the user to the potential problem and includes a list
of the files being updated when the buffer flush was in process. The DBA must then determine
whether a power failure occurred.
If the cause of a session interruption
􀀀 is a power failure, Software AG strongly recommends recovering the affected files using the
ADASAV and ADARES utilities.
􀀀 is definitely not a power failure and the integrity of the information on the output hardware can
be guaranteed, the database can be reactivated immediately. Database recovery is not necessary.