ADANUC (Starting The Database, Defining Nucleus Parameters)

This document describes the utility "ADANUC". ADANUC is the database nucleus task.

The following topics are covered:


Functional Overview

The nucleus parameters are used to define the Adabas nucleus runtime environment.

The nucleus parameters are set during nucleus startup.

The nucleus parameters provide the following information:

  • The database to be used;

  • The setting of various Adabas session parameters, such as the maximum Adabas buffer size and the transaction and user non-activity time limits;

  • The type and amount of command data to be logged during the Adabas session. These parameters apply to statistical information and not to the logging of database updates on the Adabas data protection log.

This utility is a single-function utility.

Notes

  1. If ADANUC terminates with a stop error during nucleus startup, e.g. STP055 or STP997, the reason is probably that there are not enough operating system resources (for example memory) available in order to start the nucleus with the specified parameters. You can prevent the stop error from occurring by reducing the values of some nucleus parameters (for example NT or LBP).

  2. At the start of the first nucleus session after a database has been created or restored, the Adabas nucleus initializes all of the blocks of the WORK container. For a large WORK container this may take a few minutes. The database will only be available after the initialization of the WORK container has finished.

  3. The default values for the nucleus parameters can be used if there are not more than 20 users who perform Adabas calls with relatively small Adabas buffers. The following hints describe conditions under which it may be necessary to use other nucleus parameter values:

    • If you temporarily have bad response times for Adabas commands (during an Adabas buffer flush), or if you get I/O errors during asynchronous I/Os even though your hardware is OK, consider setting BFIO_PARALLEL_LIMIT.

    • If Adabas commands with large adabas buffers are performed, e.g. for LOB processing, consider increasing the value for LAB and LBP.

    • If there are multi-threaded applications performing Adabas calls, consider increasing the NCL parameter.

    • If the number of parallel Adabas sessions is greater than 20, increase the NU parameter.

    • If it is important that the autorestart time after a nucleus crash is short, set WRITE_LIMIT to a small positive value, especially if you are using a large buffer pool.

  4. You can run a database in read-only mode by either removing the write permissions from the Adabas containers or by specifying OPTIONS=READ_ONLY. If you run the database in read-only mode, the temporary working space on disk is only created if you specify its location explicitly (environment variables TEMPLOCn or entries TEMPORARY_LOCATION in the DBnnn.INI file). For further information, see Adabas Basics, Temporary Working Space.

  5. If the previous Adabas session was not terminated normally with SHUTDOWN or CANCEL, Adabas performs an Autorestart: All transactions that were active when the nucleus crashed, are rolled back, and all missing database updates are written to ASSO and DATA. For this purpose, all update operations have been logged on the WORK container. Additionally, all update operations are logged in the NUCPLG file, which is required to recover the current state of the database, if one or more of the database containers has been corrupted, for example, because of a disk failure. In case of a nucleus crash, it is necessary that both logs contain the same information, otherwise the database could contain additional transactions, or transactions could be lost if you perform a restore/recover later. In order to check this, the PLOG file must still be available with the same name when an autorestart is performed. If you have renamed the PLOG file, or moved it to another location, you get the following warning:

    %ADANUC-W-PLNOF, Last plog not found, so consistency check is not possible. New backup required.

    If you get this warning, your database is still consistent, but if you perform a restore/recover later, it may be that your database then becomes inconsistent. If you create a new backup to be used as a base for restore/recover, the consistency of the restore/recover is guaranteed again.

  6. On UNIX platforms, the IPC resources allocated by the Adabas nucleus are not removed if the nucleus is not shut down normally with ADAOPR SHUTDOWN or ADAOPR CANCEL. The nucleus can only be restarted after these resources have been removed, and for this reason the nucleus executes the command showipc -k <dbid>. Important: if Adabas was not installed as recommended by user "sag", group "sag", it is necessary to set the environment variable SIPUSER and/or SIPGROUP. For further information, see Database Monitoring and Tuning, showipc. On Windows platforms, the operating system automatically removes IPC resources that are no longer used.

Procedure Flow

graphics/adanuc01_new2.png

The sequential files NUCPLG and NUCCLG can have multiple extents. For detailed information about sequential files with multiple extents, see Adabas Basics, Using Utilities.

Data Set Environment
Variable/
Logical Name
Storage Medium Additional Information
Associator ASSOx Disk  
Command log NUCCLG Disk, Tape Utilities Manual,
ADACLP
Data storage DATAx Disk  
DBnnn.INI   Disk Adabas Extended Operations Manual
Protection log NUCPLG Disk Utilities Manual,
ADAPLP
Control statements stdin/
SYS$INPUT
  Utilities Manual
ADANUC messages stdout/
SYS$OUTPUT
  Messages and Codes
Work WORK1 Disk  
CSA dump ADA_CSA_DUMP Disk Adabas CSA dump
(see ADAOPR RESPONSE_CHECK)
SMP dump SMP_DUMPFILE Disk SMP dump
Temporary working space
(NUCTMPx, NUCSRTx)
TEMPLOCx Disk Administration Manual (see Temporary Working Space)

Notes:

  1. In the environment variable/logical name ADA_CSA_DUMP, the directory in which the Adabas CSA dump is to be created must be specified.
  2. The default directory for the Adabas CSA dump file is the database directory. For the layout of the file names for Adabas CSA dumps, see ADAOPR, parameter CSA.
  3. For further information about the Adabas CSA dumps, see also the ADAOPR parameters ABORT and RESPONSE_CHECK.
  4. In the environment variable/logical name SMP_DUMPFILE, the name of the SMP_DUMPFILE itself (not a directory) must be specified. An existing file is overwritten.
  5. If the SMP_DUMPFILE is not specified, the SMP dump is written into the Adabas CSA dump directory with the file name SAGSMP.xxx.hh:mm:ss (UNIX), SAGSMP.xxx.hh-mm-ss (Windows) and SAGSMP-xxx-hh-mm-ss (OpenVMS) where xxx is the database ID and hh:mm:ss/hh-mm-ss is the nucleus start-time.

Checkpoints

The following table shows the checkpoints written by the nucleus:

Function Checkpoint written
Nucleus startup SYNC
Nucleus termination SYNC

Control Parameters

The following control parameters are available:

D    [NO]AB32BIT

D    [NO]ADATCP

D    ADABAS_ACCESS = {ALL | GROUP}

     APU = (n1,n2,n3)

D    AR_CONFLICT = keyword

     BFIO_PARALLEL_LIMIT = number

D    [NO]BI

D    CLOGBMAX = number [K | M]

D    CLOGLAYOUT =  [5 | 6]

M    DBID = number

D    LAB = number [K | M]

D    LABX = number [K | M]

D    LBP = number [K | M]

D    LOGGING = (keyword [,keyword]...) 

D    LPXA = number

D    LWP = number [K | M]

D    NCL = number 

D    NISNHQ = number

D    NT = number 

D    NU = number 

D    OPTIONS = (keyword[,keyword]...) 

D    [NO]PLOG

D    PORTNUMBER = number

D    READ_PARALLEL_LIMITS = (records,blocks,total) 

D    TCPATB = number

D    TCPCONNECTIONS = number

D    TCPRECEIVER = number

D    TNAA = number

D    TNAE = number

D    TNAX = number

D    TT = number

D    UNBUFFERED = ALL | CLEAR | (keyword [, keyword [, keyword]]) 

     USEREXITS = (number[,number]...)

     WCHARSET = <ICU encoding>

D    WRITE_LIMIT = number

[NO]AB32BIT

Note:
This parameter is relevant only for HP-UX.

On HP-UX, you must create a 32-bit shared memory segment if you want access to shared memory from a 32-bit application. For this reason, it is necessary to create the shared memory for the attached buffers required for the communication between client programs and ADANUC as 32-bit shared memory, if you want to perform Adabas calls in 32-bit applications. However, the total size of 32-bit shared memory segments is limited. If you have several databases on a machine, it can happen that starting ADANUC fails with the message LABTB - LAB too big, because no more 32-bit shared memory space is available. If you don’t have 32-bit applications, you can avoid this error by specifying the parameter NOAB32BIT. Then the shared memory for the attached buffers is created as 64-bit shared memory.

The default is AB32BIT, which means that the shared memory is created as 32-bit shared memory segment.

Note:
If you started the nucleus with the parameter NOAB32BIT, and you nevertheless start a 32-bit application that performs Adabas calls , the application will get the Adabas response code 148 - Adabas not active.

[NO]ADATCP

This parameter enables/disables the TCP/IP receiver.

Note:
A valid Entire Net-Work (WCP) license is required, otherwise the TCP parameter settings will be ignored and only restricted settings such as TCPCONNECTIONS=3 will be used (see the Adabas Nucleus log file after startup).

The default is NOADATCP.

ADABAS_ACCESS

ADABAS_ACCESS = {ALL | GROUP}

If ADABAS_ACCESS = ALL is specified, all users may perform Adabas calls.

If ADABAS_ACCESS = GROUP is specified, only those users that belong to the group of the user starting Adabas, for example sag, may perform Adabas calls.

The default is ALL.

Please refer to Adabas Security Features, Using the UNIX Group Concept for further information about using the ADABAS_ACCESS parameter.

Note:
This parameter only applies to local Adabas calls in UNIX environments.

APU

APU = (n1,n2,n3)

This parameter specifies the number and layout of the Adabas Processing Units to be established for an Adabas session.

Adabas Processing Units optimize the parallel execution of Adabas commands, especially in the context of NUMA architectures. An Adabas Processing Unit consists of a logical collection of receiver and worker threads together with a dedicated command queue. The receiver threads pick up incoming user requests and place them into the command queue, while the worker threads process the commands in the command queue.

Each Adabas Processing Unit has exactly one command queue and must have at least one receiver and one worker thread.

Note:
If control parameters NT and APU are both specified, the settings of parameter NT are ignored. The Adabas nucleus is setup with the settings defined for APU.

n1

Specifies the number of Adabas Processing Units that are defined for the Adabas nucleus. The minimum value is 1, the maximum value is 8.

n2

Specifies the number of worker threads per Adabas Processing Unit. The minimum value is 1, the maximum value is 100/n1. The overall count of worker threads must not exceed 100.

n3

Specifies the number of receiver threads per Adabas Processing Unit. The minimum value is 1, the maximum value is 100/n1.

Examples

APU=(4,4,2)

This defines an Adabas nucleus with 4 Adabas Processing Units, each with 4 worker and 2 receiver threads. This value implies a total of 16 worker threads and 8 receiver threads.

APU=(8,2,1)

This defines an Adabas nucleus with 8 Adabas Processing Units, each with 2 worker threads and 1 receiver thread. This value implies a total of 16 worker threads and 8 receiver threads.

APU=(1,6,2)

This defines an Adabas nucleus with 1 Adabas Processing Unit, each with 6 worker threads and 2 receiver threads. This value implies a total of 6 worker threads and 2 receiver threads. Defining only 1 Adabas Processing Unit results in a runtime environment that is similar to a runtime environment that is defined using the NT parameter only.

AR_CONFLICT

AR_CONFLICT = keyword

This parameter specifies the action to be taken if a restart detects that the last system crash was during a buffer flush. The following keywords can be used:

Keyword Meaning
ABORT no restart is performed
CONTINUE the system tries to perform a restart

It is recommended to keep the setting AR_CONFLICT=ABORT. Only if the nucleus does not come up due to an interrupted buffer flush, then temporarily AR_CONFLICT=CONTINUE should be set.

Note:
You should be aware of the possibility of inconsistencies in the case of a restart with AR_CONFLICT=CONTINUE. Consistency should be checked with the ADAINV VERIFY function in this case.

The default is ABORT.

BFIO_PARALLEL_LIMIT

BFIO_PARALLEL_LIMIT = number

This parameter is used to limit the number of parallel I/O requests by a buffer flush and to allow earlier processing of concurrent I/Os from other threads. A large buffer flush, for example, can cause the I/O queue to be very busy, and other I/Os (such as buffer pool read I/Os and WORK I/Os) can be enqueued for a long time, slowing down command throughput and possibly causing applications to stall if a buffer flush is active.

If BFIO_PARALLEL_LIMIT is specified, the buffer flush sets up the specified number of I/Os and waits until these have been processed before issuing the next packet. The maximum value for ´number´ is defined by the operating system, for example by the UNIX kernel parameter AIO_LISTIO_MAX. Specifying a value of 0 is equivalent to specifying the maximum value allowed. The default value is 50.

Note:
If the value of BFIO_PARALLEL_LIMIT is too high (or equal to 0), this can result in an I/O error during asynchronous IO (utility error message: ADRERR). The reason for this is that the memory available within the operating system for asynchronous I/O is exhausted. You can imagine that the required memory is at least the size of the blocks to be written to the database plus some additional space. The maximum value for BFIO_PARALLEL_LIMIT for which you can be sure that this ADRERR error will not occur, depends on the operating system configuration and on the other processes that are active on the same machine. 50 seems to be a useful value for BFIO_PARALLEL_LIMIT; if the ADRERR error occurs nevertheless, you should check your operating system configuration.

Examples

adanuc: bfio_parallel_limit = 20

Twenty parallel I/O requests are permitted for a buffer flush.

adanuc: bfio_parallel_limit = 0

The number of parallel buffer flush I/Os is unlimited.

[NO]BI

[NO]BI

This option is used to specify whether before images are written to the PLOG (BI) or not (NOBI).

The before images on the PLOG are used during a regenerate in order to verify the data consistency (for example, whether the appropriate PLOG is being used). If NOBI is set, the PLOG is smaller, but the consistency verifications cannot be performed.

The default is BI.

Note that if you specify NOBI, this will reduce the amount of consistency checking possible when using the ADAREC REGENERATE function. See ADAREC for more details.

CLOGBMAX

CLOGBMAX = number[K | M]

This parameter specifies the maximum Adabas buffer length that is logged in the command log. If an Adabas buffer is larger than the value specified, the buffer is truncated in the command log. 0 means that the complete buffers are always logged.

The default is 0 (the complete buffers are logged).

Example

adanuc: clogbmax = 4k

The logging of Adabas buffers is limited to the first 4 kilobytes of each buffer.

CLOGLAYOUT

CLOGLAYOUT = [5|6]

If you specify CLOGLAYOUT=5, the command log has the same layout as for Adabas Version 5 when command logging is enabled. Since this layout does not support the ACBX interface, only the subset of information that is also available in the old ACB interface is logged for ACBX calls. The command log can be evaluated with the ADACLP utility that already existed in old versions of Adabas.

If you specify CLOGLAYOUT=6, the command log is generated in the new layout that is supported by Adabas Version 6. For evaluating the command log, an example program prilogc is provided – for details see Appendix B.

The default value is 5.

DBID

DBID = number

This mandatory parameter selects the database to be used. `number' is in the range from 1 to 255.

Example:

adanuc: dbid = 2

Database 2 is used.

LAB

LAB = number[K | M]

This parameter specifies the size of the attached buffer area to be used during the Adabas session. The attached buffer area is used for allocating the user buffers during command execution.

Adabas rounds up the given value to the next multiple of 32 kilobytes to allocate the attached buffer area.

The high water mark for this parameter can be displayed using the DISPLAY parameter in ADAOPR.

The minimum value is 1 megabyte, the default value is 1 megabyte, however, if the value specified is less than the value of the NCL parameter in kilobytes, the value for LAB is automatically increased to that value.

Notes:

  1. The attached buffers must be large enough to contain, for each local client thread, the maximum total size of user buffers for an Adabas call performed by this thread. Additional space may be required for the administration of the user buffers and for waste resulting from the different sizes required for different threads.
  2. Attached buffers > 64 KB are allocated in the separate attached buffer extension area (see parameter LABX).

LABX

LABX = number[K | M]

This parameter specifies the size of the attached buffer extension area to be used for LOB processing or for other Adabas calls that use large Adabas buffer areas. While the regular attached buffers remain allocated during the whole Adabas session of the users, the attached buffer extensions are allocated before each Adabas call that requires more than 64 KB of attached buffer space, and they are released again at the end of the call.

The attached buffer extension area was introduced because storing large buffers in the regular attached buffer area requires much more space because of fragmentation.

Adabas rounds up the given value to the next multiple of 32 kilobytes to allocate the attached buffer area.

The high water mark for this parameter can be displayed using the DISPLAY parameter in ADAOPR.

The minimum value is 1 megabyte, the default value is 20 megabytes.

LBP

LBP = number[K | M]

This parameter specifies the size in bytes of the Adabas buffer pool during the session.

The high water mark for this parameter can be displayed using the DISPLAY parameter in ADAOPR.

The minimum value is 32 megabytes, the default value is 100 megabytes.

Note:
The actual size of the buffer pool also depends on the NT parameter: if the size specified for LBP is less than NT * 2M, it is automatically increased to NT * 2M.

There are the following reasons for using a buffer pool in Adabas:

  • If the same database block is accessed more than once, physical I/Os for rereading the block can be avoided;

  • Commands that update the database can be finished before all of the corresponding database blocks have been written to the disk.

If the buffer pool is too small, you have a larger number of I/Os than you would when performing the same database operations with a sufficient buffer pool size. In some cases, it may even occur that Adabas cannot successfully process an Adabas command, in which case the command will get a response code 162 (buffer pool too small).

In particular, if you process LOBs, it is recommended that you increase the size of the buffer pool; it should be possible to put the LOBs into the buffer pool without removing too many other database blocks. On the other hand, the buffer pool should not be too large, since there is no advantage in having buffer pool I/Os replaced by operating system paging I/Os.

You can use the ADAOPR parameter DISPLAY=BP_STATISTICS in order to help you find the optimum size for the buffer pool.

Example:

adanuc: lbp=32m

32 megabytes are allocated to the Adabas buffer pool.

LOGGING

LOGGING = (keyword [,keyword]...)

This parameter specifies logging of the buffers as defined in the keyword list.

The following keywords may be specified in the keyword list:

Keyword Meaning
CB log Adabas control block
FB log format buffers
RB log record buffers
SB log search buffer
VB log value buffer
IB log ISN buffer
ABD log Adabas buffer descriptions
IO log I/O activity
NAT log Natural information
OFF perform no logging

Logging parameters may also be specified while a session is executing by using operator commands as described in the section on the utility ADAOPR.

Example

adanuc: logging=(cb)

Command logging is performed for the current Adabas session; all of the Adabas control blocks will be logged.

LPXA

LPXA = number

This parameter specifies the number of blocks reserved for data protection information on the Adabas WORK in the XA context if OPTIONS=XA is specified. These blocks are used to save protection information for transactions which run in the XA context and are in the pending state (prepared but not yet committed) at nucleus shutdown or for a long time. Each such transaction uses at least one of these blocks. If there are no free blocks in this area, Adabas will heuristically commit such transactions.

The minimum value is 1, and the default value is 10.

LWP

LWP = number[K | M]

This parameter specifies the size of the Adabas work pool, which is a work area in memory to be used for the Adabas nucleus session.

The Adabas work pool area is used to store the following:

  • Descriptor value table (DVT);

  • WORK I/O areas during command execution.

The high water mark for this parameter can be displayed using the DISPLAY parameter in ADAOPR.

The default value is 16 M, the minimum value is 500 K, the maximum value is 4000 M.

Example:

adanuc: lwp=750k

The size of the Adabas work pool is 750 Kbytes.

NCL

NCL = number

This parameter specifies the number of client threads locally accessing the database. Normally, the number of client threads is identical to the number of Adabas user sessions = the number of user queue elements, which is limited by the NU parameter.However, in the case of multi-threaded applications, the number of client threads may be larger, since the same Adabas sessions may be accessed by more than one thread. But on the other hand, in the case of application servers where the same process uses different Adabas user sessions for different users, it can happen that the number of client threads is smaller than the number of Adabas user sessions.

The minimum value is 2. The default value is the value for the NU parameter but at least 50. There is no fixed maximum value for this parameter, it is only limited by the IPC resources that are available for the operating system (see Increasing System V Resources (does not apply to AIX) for further information).

Note that Net-Work Version 7 also uses several threads to access the database; please refer to the Net-Work documentation for further details.

Notes:

  1. The value specified for the NCL parameter should not be too high. When Adabas sessions are terminated correctly with a close command, the associated message queues are removed, but if the sessions are terminated abnormally without a close command, the message queues are not removed. A cleanup of the message queues is only performed when the number of client message queues is equal to the value specified for the NCL parameter - therefore, it may happen that Adabas attempts to create more message queues than it is allowed to do by the system, if the value for the NCL parameter is too high, even though the actual number of active Adabas users is very small. If this happens, the Adabas commands receive a response 255 (see Messages and Codes for further information).
  2. A cleanup of the message queues can be initiated manually with the ADAOPR FREE_CLQ command.

NISNHQ

NISNHQ = number

This parameter specifies the maximum number of records that can be placed into hold at any time by a single user.

If a user attempts to place more records in the hold status than permitted, he will receive a non-zero response code, even though there may still be space in the hold queue.

The high water mark for this parameter can be displayed using the DISPLAY parameter in ADAOPR.

The minimum value is 0 - where 0 means unlimited, the default value is 0 (unlimited).

Example

adanuc: nisnhq=50

The maximum number of records which can be in the hold status for a single user is 50.

NT

NT = number

This parameter specifies the number of threads to be established for the Adabas session.

Each Adabas command is assigned to a thread. A thread is released when the command has been processed.

The high water mark for this parameter can be displayed using the DISPLAY parameter in ADAOPR.

The minimum value is 1, the maximum value 100 and the default value is 6.

Notes:

  1. It is strongly recommended to use an NT parameter value greater than 1, because some internal commands can only be executed if NT > 1. If NT is 1, some utilities or applications, such as SQL Gateway, which use these internal commands, may fail.
  2. NT = 1 only makes sense in some special situations, for example, if support requests an ADANUC trace and you want to have the trace of all Adabas commands in one file.
  3. Increasing the NT parameter usually implies an overhead, which may reduce the performance. Therefore, it usually doesn't make sense to use an NT parameter value that is significantly higher than the number of hardware threads; if you have a large number of hardware threads, the performance may even be better if NT is less than the number of hardware threads, because the Adabas nucleus is not the only program running on the machine and using CPU time.
  4. One reason to increase the value of the NT parameter is if there are several complex commands in parallel that require a long time to complete. If all nucleus threads are blocked by such commands, it can happen that short running commands cannot be scheduled for a long time, and as a result the overall performance of Adabas becomes very low.
  5. With previous versions of Adabas, it was possible that short running commands could no longer be scheduled because complex, long-running commands blocked all threads, which resulted in very poor overall performance. In order to avoid this situation, now only NT/2 threads can be used to process such long-running commands in parallel. As a consequence of this, it may be that you can see several free threads even though there are sufficient commands in the command queue waiting to be scheduled.
  6. If control parameters NT and APU are both specified, the settings of parameter NT are ignored. The Adabas nucleus is setup with the settings defined for APU.

Example:

adanuc: nt=8

Eight threads are established for the session.

NU

NU = number

This parameter specifies the number of user queue elements to be established for the Adabas session.

A user queue element is assigned to each active Adabas user. A user queue element is assigned when the user issues an OP command or when the first Adabas command is issued. A user queue element is released when the user issues a CL command or when the user queue element is deleted on a timeout.

The high water mark for this parameter can be displayed using the DISPLAY parameter in ADAOPR.

The minimum value is 2, the default value is 20, the maximum value is 99999.

Example:

adanuc: nu=100

The Adabas user queue consists of 100 elements.

Note:
The NU parameter is used for two different purposes:

  • the number of user queue entries

  • the number of communication blocks

For single-threaded applications, the number of required communication blocks is not larger than the number of user queue elements, but for multi-threaded applications you need one communication block for each thread of an application that performs Adabas calls. Therefore the required value of the NU parameter may be much higher than the number of Adabas users.

OPTIONS

OPTIONS = (keyword[,keyword]...)

This parameter is used to define the mode(s) in which the nucleus is started.

The following keywords are permitted:

Keyword Meaning
AUTO_EXPAND

If AUTO_EXPAND is selected, the database will increase the existing container extents or create a new container extent if there is no free space available for increasing an existing Adabas file or for adding a new Adabas file. See the section Container Files in the Adabas Basics section for further information.

AUTORESTART_ONLY

The AUTORESTART_ONLY keyword shuts down the nucleus immediately after its startup sequence has completed. If an autorestart is pending, the autorestart will be performed. No user commands or utility calls will be accepted by the nucleus.

FAULT_TOLERANT_AR

When FAULT_TOLERANT_AR is selected, the nucleus behaviour in the event of an Adabas error during autorestart can be controlled. If an error occurs for a given file, a detailed entry is made in the nucleus log, but the autorestart continues. When the autorestart completes, the DBA can restore and regenerate the file by using ADABCK RESTORE and ADAREC REGENERATE for the affected file. If however the error occurred for the index of a file, it is sufficient to rebuild the file's index by using the REINVERT function of ADAINV. If FAULT_TOLERANT_AR is not selected, Adabas aborts an autorestart if an error is detected, and this can cause the database to be in an inconsistent state.

LOCAL_UTILITIES

If LOCAL_UTILITIES is selected, ADANUC rejects all remote utility calls, i.e. the Adabas utilities cannot be run from a remote node across a network. This setting is recommended if security is important in your operating environment.

LOCAL_UTILITIES and UTILITIES_ONLY can be dynamically enabled or disabled without having to shut the database down (see ADAOPR for further information).

NOPLOG_FOR_REPLICATION

If this option is selected, all changes in data of the replication system files will not be written to the protection log.

OPEN_REQUIRED

If OPEN_REQUIRED is selected, an open (OP) command must be issued as the first command of a user session.

This option should be set if lnk_set_adabas_id is used when calling Adabas from application servers, and also when using Net-Work, otherwise in these cases Adabas cannot guarantee transaction integrity following an ADANUC restart.

READONLY

The READONLY option causes ADANUC to run in read-only mode. Refer to the Administration Manual for more details.

TRUNCATION

The TRUNCATION keyword controls the truncation of alphanumeric fields. If TRUNCATION is set, alphanumeric fields are truncated if necessary and response code 0 is returned. If TRUNCATION is not set, response code 55 is returned if truncation occurred.

UTILITIES_ONLY

If UTILITIES_ONLY is selected, all calls other than for utilities will be rejected, giving the DBA exclusive control over all of the files in the database. Note, however, that this restriction only applies to new users; users who were already active when OPTIONS=UTILITIES_ONLY was specified can continue processing normally. If you want exclusive utility control over files or the entire database, use the LOCK function of ADAOPR instead.

LOCAL_UTILITIES and UTILITIES_ONLY can be dynamically enabled or disabled without having to shut the database down (see ADAOPR in this manual for further information).

XA

The keyword XA indicates that the server will support distributed transaction processing according to the X/Open XA specification. If the Adabas XA interface is to be used by an application, OPTION=XA must be used. See XA Support for further information.

The default is that no option is set.

Example:

adanuc: options = utilities_only

All non-utility calls are rejected and the DBA has exclusive control over all database files.

[NO]PLOG

[NO]PLOG

PLOG specifies which protection log is to be switched on.

The database cannot be regenerated if the disk is physically damaged and if there is no protection log. In this case, the database has to be restored using the last database dump. All updates made since this last dump was taken are then lost.

PLOG is the default.

PORTNUMBER

PORTNUMBER = number

This parameter specifies the TCP/IP port number if ADATCP is enabled.

The minimum value is 1024, the maximum value is 65535, and the default value is 49152.

Example:

adanuc: portnumber=63111

Adabas listens on port 63111 for ADATCP connections.

READ_PARALLEL_LIMITS

READ_PARALLEL_LIMITS = (records,blocks,total)

For sequential commands, Adabas tries to increase the performance by reading the database blocks required for the following records in advance and in parallel. This lets you take advantage of disk striping, and the sequence of I/Os can be optimized. Significant performance improvements can only be expected when the physical I/O rate is high. A typical case where the READ_PARALLEL_LIMITS parameter can improve the performance is the execution of a batch program in which a complete large file is read, and this file contains a large number of database blocks that are not in the buffer pool when the program is started. However, this prefetching of database blocks can also have a negative impact on the performance:

  • Checking which blocks are required for the next records requires a certain amount of CPU time, and this is superfluous if all blocks are already in the buffer pool.

  • If you don’t read the next records of the command sequence, the overhead for reading blocks for this command sequence is superfluous.

  • If I/Os for too many blocks have been initiated, an I/O required for another command performed in parallel may be delayed significantly.

The READ_PARALLEL_LIMITS parameter lets you control the read-ahead behaviour. You can specify 3 numbers with the following meanings:

records

The maximum number of records to be processed next in a command sequence, that are checked for blocks that are not yet in the buffer pool. The maximum value that can be specified is 65,535.

blocks

The maximum number of blocks read in advance for one command sequence. The number specified for blocks must be <= the number specified for records, the maximum value is operating-system dependent.

total

The maximum total number of blocks read in advance at the same time for the whole database. The number specified for total must be >= the number specified for blocks, the maximum value is operating-system dependent.

The default is (0,0,0), i.e. no read-ahead is performed.

Note:
If the value of the number specified for total is too high, this can result in an I/O error during asynchronous IO (utility error message: ADRERR). The reason for this is that the memory available within the operating system for asynchronous I/O is exhausted. You can imagine that the required memory is at least the size of the blocks to be written to the database plus some additional space. The maximum value for total for which you can be sure that this ADRERR error will not occur, depends on the operating system configuration and on the other processes that are active on the same machine.

Example

adanuc: read_parallel_limits = (100,20,50)

When sequential commands are processed, the next up to 100 records of a command sequence are checked for required blocks that are not yet in buffer pool. The search for blocks to be read is stopped when 20 blocks are found, or when the number of blocks found plus the number of blocks currently read by other commands is 50. Then a read I/O for these blocks is initiated.

TCPATB

TCPATB = number[K | M]

This parameter specifies the attached buffer size for the ADATCP receivers (similar to LAB/LABX), but they have their own attached buffer handling that is not based on IPC.

The minimum value is 1 megabyte, the default value is 20 megabytes.

Example:

adanuc: tcpatb=50m

The ADATCP-based attached buffer size is set to 50 megabytes

TCPCONNECTIONS

TCPCONNECTIONS = number

This parameter specifies the maximum possible number of parallel ADATCP connections per receiver thread.

The minimum value is 1, and the default value is 4294967295.

Example:

adanuc: tcpconnections=1000

Up to 1000 parallel ADATCP connections are accepted.

TCPRECEIVER

TCPRECEIVER = number

This parameter specifies the number of ADATCP receiver threads to be established during Adabas startup.

The minimum value is 1, the maximum value is 20, and the default value is 4.

Example:

adanuc: tcpreceiver=8

The number of receiver threads is set to 8.

TNAA

TNAA = number

This parameter specifies the maximum elapsed time (in seconds) that an access-only user may be active without issuing an Adabas command. This value can be changed dynamically with the ADAOPR utility.

The OP command allows you to override this value. See Command Reference, OP command for details.

See Command Reference, Time Limits for a table with timeout conditions.

Note that the figure you specify for this parameter is only approximate. In any particular instance, the actual amount of time can vary from this value by up to 10 seconds.

The minimum value is 20, the default value is 900 and the maximum value is 2592000.

Example:

adanuc: tnaa=180

The non-activity time limit for access-only users is 180 seconds.

TNAE

TNAE = number

This parameter specifies the maximum elapsed time (in seconds) that an ET logic user may be active without issuing an Adabas command. This value can be changed dynamically with the ADAOPR utility.

The OP command allows you to override this value. See Command Reference, OP command for details.

See Command Reference, Time Limits for a table with timeout conditions.

Note that the figure you specify for this parameter is only approximate. In any particular instance, the actual amount of time can vary from this value by up to 10 seconds.

The minimum value is 20, the default value is 900 and the maximum value is 2592000.

Example:

adanuc: tnae=180

The non-activity time limit for ET logic users is 180 seconds.

TNAX

TNAX = number

This parameter specifies the maximum elapsed time (in seconds) that an exclusive update user who does not use ET logic may be active without issuing an Adabas command. This value can be changed dynamically with the ADAOPR utility.

The OP command allows you to override this value. See Command Reference, OP command for details.

See Command Reference, Time Limits for a table with timeout conditions.

Note that the figure you specify for this parameter is only approximate. In any particular instance, the actual amount of time can vary from this value by up to 10 seconds.

The minimum value is 20, the default value is 900 and the maximum value is 2592000.

Example:

adanuc: tnax=180

The non-activity time limit for exclusive update users is 180 seconds.

TT

TT = number

This parameter specifies the maximum elapsed time (in seconds) permitted for a logical transaction issued by an ET logic user. This value can be changed dynamically with the ADAOPR utility.

The OP command allows you to override this value. See Command Reference, OP command for details.

The time measurement for a logical transaction starts when the first command that places a record in hold status is issued, and terminates when an ET, BT, or CL command is issued. Adabas takes the following action when this time limit is exceeded:

  1. All database updates made during the transaction are backed out;

  2. All records held during the transaction are released;

  3. All Command IDs for the user are released;

  4. Response code 9 is returned on the next call issued by the user.

This time limit does not apply to non-ET logic users. The value specified for TT directly influences the required size of the Adabas Work data set.

The high water mark for this parameter can be displayed using the DISPLAY parameter in ADAOPR.

Note that the figure you specify for this parameter is only approximate. In any particular instance, the actual amount of time can vary from this value by up to 10 seconds.

The minimum value is 20, the default value is 300 and the maximum value is 2592000.

Example:

adanuc: tt=50

The transaction time limit for ET logic users is 50 seconds.

UNBUFFERED

UNBUFFERED = ALL | CLEAR | (keyword [, keyword [, keyword]]) 

This parameter is relevant only for UNIX platforms, and if database containers or the protection log are stored in a file system. Usually, write I/Os are buffered by the file system. However, if you specify the O_DSYNC option for the corresponding open call, write I/O operations are performed unbuffered. This may improve the performance, in particular, if specified for WORK and PLOG, as it is required that the corresponding log information is really on disk at the end of a transaction. With the parameter UNBUFFERED, the usage of the O_DSYNC operation may be defined.

Note:
Usage of this parameter only has impact on the performance of Adabas; which actual setting of the UNBUFFERED parameter results in the best performance depends on the operating system and the storage system used - the integrity of the database is guaranteed for all values of the UNBUFFERED parameter.

The following keywords may be specified in the keyword list:

Keyword Meaning
DATABASE ASSO and DATA containers in a file system are opened with the option O_DSYNC.
NODATABASE ASSO and DATA containers in a file system are not opened with the option O_DSYNC.
WORK A WORK container in a file system is opened with the option O_DSYNC.
NOWORK A WORK container in a file system is not opened with the option O_DSYNC.
PLOG A protection log in a file system is opened with the option O_DSYNC.
NOPLOG A protection log in a file system is not opened with the option O_DSYNC.

The keyword ALL is equivalent to (DATABASE, WORK, PLOG).

The keyword CLEAR is equivalent to (NODATABASE, NOWORK, NOPLOG).

The default is (NODATABASE, WORK, PLOG).

Example:

adanuc: unbuffered=(nowork)

O_DSYNC is not used for ASSO and DATA containers because NODATABASE is the default.

O_DSYNC is not used for WORK container because NOWORK has been specified.

O_DSYNC is used for protection logs because PLOG is the default.

USEREXITS

USEREXITS = (keyword [,keyword]...)

This parameter, used in conjunction with the user exit facility, specifies one or more user exits. The specified user exit(s) must be loadable at execution time.

The keyword can take the values 1, 2, 4, 11 and 14.

Notes:

  1. User exit 1 and 11 are mutually exclusive.
  2. User exit 4 is only activated if CLOGLAYOUT=5 is specified. User exit 14 is only activated if CLOGLAYOUT=6 is specified.

See Adabas Basics, User Exits and Hyperexits for further information about the user exits available.

WCHARSET

WCHARSET = <ICU encoding>

This parameter specifies the default encoding for W fields for user sessions. This encoding is used if no other encoding is specified in the record buffer of the OP call, or in the format buffer of L or A/N calls.

Example

adanuc: wcharset=utf-16be

WRITE_LIMIT

WRITE_LIMIT = number

This parameter specifies the percentage of modified database blocks in the buffer pool before an implicit buffer flush is taken. For more information on buffer flushes, refer to Administration, Database Monitoring and Tuning, Buffer Pool Mangement.

Supported values are 1-50; the default value is 50. For compatibility reasons, values of 0 and 51-70 are also allowed - they are equivalent to 50.

Notes:

  1. Starting with Adabas version 6.4, different flush lists and buffer flushes for temporary blocks (NUCTMP, NUCSRT) and for database blocks (ASSO, DATA) are introduced to reduce the number of write I/Os for temporary blocks, when a small value for WRITE_LIMIT is specified. Temporary blocks should only be written to disk in order to avoid a buffer flush; therefore independent of the value of WRITE_LIMIT, an implicit buffer flush is taken when the percentage of modified blocks (temporary blocks and database blocks together) is 50. Such a buffer flush writes either temporary blocks or database blocks, depending on which kind of modified blocks constitutes the most data.
  2. If you have a large buffer pool, it is useful to specify a small value for WRITE_LIMIT in order to reduce the time required for an auto restart of the nucleus: during an auto restart, ADANUC must read the update log in the WORK container and reapply all changes in the database that had not yet been written to disk. A smaller value for WRITE_LIMIT means a smaller amount of data not yet written to disk, and therefore less updates to be made during the auto restart.

Example:

adanuc: write_limit=10

An implicit buffer flush is taken when the size of modified database blocks is 10% of the buffer pool size.

Summary of ADANUC Parameters

Parameter Use Min. Value Max. Value (see note 1) Default Dynamic (see note 3)
[NO]AB32BIT Attached buffers defined as 32-bit shared memory to enable Adabas access from 32-bit applications (only relevant for HP-UX)     AB32BIT No
[NO]ADATCP Enable/disable ADATCP     NOADATCP No
ADABAS_ACCESS Restrict user access for making Adabas calls     ALL No
APU Adabas processing units     None No
AR_
CONFLICT
Restart after crash during buffer flush     ABORT No
BFIO_PARALLEL_LIMIT Limit of parallel buffer flush IOs 0 (see note 4) None 50 Yes
[NO]BI Write before image to PLOG     BI No
CLOGBMAX Length of Adabas buffers logged (only for CLOGLAYOUT=6) 0 (complete buffers are logged) 4GB 4096 No
CLOGLAYOUT Select layout of CLOG 5 6 5 No
DBID Database 1 255 None No
LAB Attached buffer area 1MB 2GB Maximum (1MB, NCL value * 1024) No
LABX Attached buffer extension area 1MB None 20MB No
LBP Adabas
Buffer Pool Size (see note 2)
32MB None 100MB No
LOGGING Command Logging     OFF Yes
LPXA XA data protection area size 1 block 65535 blocks 10 blocks if the XA option is set No
LWP Length of Adabas
Work Pool
500 KB 4000 MB 16 MB No
NCL Number of local client threads 2 None =NU, but at least 50 No
NISNHQ Maximum Number of ISNs in Hold per User 0 (see note 4) None 0 Yes
NT Number of Threads 1 100 6 No
NU User Queue Size 2 users 99999 users 20 users No
OPTIONS Various Options     No option Some
[NO]PLOG Protection Logging     PLOG No
PORTNUMBER The number of the TCP/IP port 1 65535 49152 No
READ_PARALLEL_LIMITS Optimize read-ahead I/O performance     (0,0,0) Yes
TCPATB Attached buffer size for the TCP/IP receivers 1M None 20M No
TCPCONNECTIONS Number of TCP/IP connections 1 None 4294967295 No
TCPRECEIVER Number of TCP/IP receiver threads 1 20 4 No
TNAA Non-Activity
Time Limit
(ACC Only Users)
20 2592000 900
seconds
Yes
TNAE Non-Activity
Time Limit
(ET Logic Users)
20 2592000 900
seconds
Yes
TNAX Non-Activity
Time Limit
(EXU,EXF Users)
20 2592000 900
seconds
Yes
TT Transaction
Time Limit
20 2592000 300
seconds
Yes
UNBUFFERED Setting of the O_DSYNC option (UNIX platforms only)     NODATABASE, WORK, PLOG No
USEREXITS User Exit(s)
to be used
    None No
WCHARSET Default encoding for W fields     None (UTF-8) No
WRITE_
LIMIT
Buffer Pool
Modification Limit
1 (see note 5) 50 50 (see note 5) Yes

Notes:

  1. "None" means that there is no explicit maximum value, but there may be a limit given by the available operating system resources, for example via the maximum size of a shared memory segment.
  2. The actual buffer pool size is increased to NT value * 2 MB if the specified value is less. If you have specified a large buffer pool size that is is not available as shared memory, Adabas tries to allocate a smaller buffer pool.
  3. If the value of a dynamic parameter is changed using ADAOPR, the new value takes effect immediately, without the nucleus having to be restarted. In the case of non-dynamic parameters, the nucleus must first be stopped and restarted for the new value to take effect.
  4. A value of 0 means there is no limit.
  5. For compatibility reasons values 0 and 51-70 can also be specified: They are equivalent to 50.