Parameters Specification

The parameters specification is used to control compile-time and run-time features of the Accessroutines.

The following diagram illustrates the syntax for specifying your database parameters:

<parameters specification>

── PARAMETERS ( ───────────────────────────────────────────────────────►
  ┌◄──────────────────────────── , ────────────────────────────┐
 ►┴─┬ /1\─ ALLOWEDCORE = <unsigned integer> ─────────────────┬─┴─ ) ───┤
    ├─/1\─ CONTROLPOINT = <unsigned integer> ─┬──────────────┤
    │                                         └─ SYNCPOINTS ─┤
    ├─/1\─ DATAENCRYPTTYPE ─────┬──────────────────┬─────────┤
    │                           └─ = ─┬─ AESHMAC ──┤         │
    │                                 └─ AESGCM ───┘         │ 
    ├─/1\─ DUMPENCRYPTTYPE ─────┬──────────────────┬─────────┤
    │                           └─ = ─┬─ TDES ─────┤         │
    │                                 └─ AES256 ───┘         │ 
    ├─/1\─ MAXUPDATEPERTR = <unsigned integer> ──────────────┤ 
    ├─/1\─ OVERLAYGOAL = <unsigned number> ──────────────────┤ 
    ├─/1\─ RESIDENT LIMIT = <unsigned integer> ──────────────┤
    ├─/1\─ SYNCPOINT = <unsigned integer> ──┬────────────────┤
    │                                       └─ TRANSACTIONS ─┤
    └─/1\─ SYNCWAIT = <unsigned integer> ─┬──────────────────┤
                                          └─ SECONDS ────────┘

The following table describes the elements of the syntax diagram:

Option

Description

ALLOWEDCORE

The ALLOWEDCORE parameter controls how many words of main memory the Accessroutines can utilize for database buffers. When the memory allocated for buffers reaches the size stipulated, deallocation of buffers commences. Deallocation of buffers continues until the value specified by the ALLOWEDCORE parameter is reached. The maximum value that can be specified is 549,755,813,887 words. The default value is 50,000 words.

The value of the ALLOWEDCORE parameter can be changed while the database is active by directing a message to the database stack.

For instructions on changing the ALLOWEDCORE parameter by using Visible DBS commands, refer to the Enterprise Database Server Utilities Operations Guide.

For databases using XE features, a new default of 200,000 words applies only if the ALLOWEDCORE parameter is not specified in the DASDL source.

The change to the default value requires a control file update in addition to a DASDL update on existing databases.

CONTROLPOINT

The CONTROLPOINT parameter specifies the number of syncpoints that occur before a new controlpoint occurs. Immediately after every syncpoint, the value of the CONTROLPOINT parameter is compared with the current number of syncpoints. If the current number of syncpoints is equal to the value of the CONTROLPOINT parameter, the last syncpoint is changed to a controlpoint and the current number of syncpoints becomes 0 (zero). Therefore, the maximum number of syncpoints that can occur between controlpoints is always one less than the value of the CONTROLPOINT parameter. For example, if the CONTROLPOINT parameter is set to 5, then the maximum number of syncpoints is 4.

The parameter applies only to audited databases. The maximum value is 4095. The default value is 2. All modified data and audit buffers are flushed to disk during the creation of two contiguous control audit points.

The value of the CONTROLPOINT parameter can be changed while the database is active by directing a message to the database stack. For instructions on how to change this parameter by using Visible DBS commands, refer to the Enterprise Database Server Utilities Operations Guide.

DATAENCRYPTTYPE

The DATAENCRYPTTYPE parameter establishes the default encryption algorithm that is used to encrypt the items of the database. The algorithms that are supported depend on the type of encryption being used:

  • Structure Level Encryption (SLE) supports only the AESGCM algorithm.

  • Field Level Encryption (FLE) supports both the AESGCM and AESHMAC algorithms.

Both of these algorithms are specified for use in IEEE P1619.1 (IEEE Standard for Authenticated Encryption with Length Expansion for Storage Devices). If the DATAENCRYPTTYPE parameter is not specified, the AESGCM algorithm is the default algorithm and is expected to be faster.

Changing the encryption algorithm requires a reorganization of the structures containing the encrypted data items. And, the applications must be recompiled. Since each encryption algorithm requires a different amount of padding, the record size will be changed and a “record format conversion” type of reorganization must be performed.

Note: Only OFFLINE and USEREORGDB reorganizations are supported if an index sequential set contains any encrypted key items. ONLINE reorganization and online garbage collection are not supported if an index sequential set contains any encrypted key items. There is still a restriction of up to 300 structures per reorganization at a time.

DUMPENCRYPTTYPE

The DUMPENCRYPTTYPE parameter was previously called the ENCRYPTTYPE parameter.

The DUMPENCRYPTTYPE parameter establishes the default encryption algorithm that the DMUTILITY and COPYAUDIT software use when copying files to tape. Setting this option allows nonmodified backup scripts to encrypt files to tape.

The DUMPENCRYPTTYPE parameter can also be requested with the DMUTILITY DUMP syntax, and the COPYAUDIT QUICKCOPY syntax. When you specify an ENCRYPTTYPE value in a DMUTILITY DUMP or COPYAUDIT QUICKCOPY statement, it overrides the DUMENCRYPTTYPE value specified in DASDL.

If an DUMPENCRYPTTYPE value is not defined by DASDL and is not specified by a DMUTILITY DUMP or COPYAUDIT QUICKCOPY statement, the TDES algorithm is used.

Refer to the Enterprise Database Server Utilities Operations Guide for examples and additional information about the DUMPENCRYPTTYPE parameter.

MAXUPDATEPERTR

The MAXUPDATEPERTR parameter controls the maximum number of updates per transaction. The maximum number of MAXUPDATEPERTR that can be specified is 50,000 and must be greater than 0.When the limit is exceeded, all of the previous updates from the current transaction are backed-out and the program receives a LIMITERROR 8.

The value for the MAXUPDATEPERTR parameter can also be changed by using the DMCONTROL statement or a Visible DBS command. However, this feature can only be turned off by performing a DASDL update. For more information about the DMCONTROL statement or Visible DBS commands, refer to the Enterprise Database Server Utilities Operations Guide .

OVERLAY-GOAL

The OVERLAYGOAL parameter controls the rate at which buffers are overlaid to the disk. The value for OVERLAYGOAL must be an integer or decimal number in the range 0 through 100. For databases using XE features, the default value is 1 percent of the allowed core for each minute. For databases using non- XE features, the default value is 5 percent of the allowed core for each minute.

OVERLAYGOAL is a dynamic database parameter that can be changed by a DASDL update without recompilation of the Enterprise Database Server software.

The value for the OVERLAYGOAL option can also be changed by using a Visible DBS command. For instructions on using Visible DBS commands, refer to the Enterprise Database Server Utilities Operations Guide.

A change to the default value requires a DASDL update operation.

OVERLAYGOAL algorithms are activated when the total in-use buffer space exceeds the ALLOWEDCORE value.

Structure BUFFER specifications are ignored when the OVERLAYGOAL parameter is not the number 0, except when any of the following conditions occur:

  • A structure is being accessed randomly and there are no buffer specifications, in which case a maximum of 512 buffers are used.

  • A structure is being accessed randomly and there are buffer specifications, in which case:

  • If the calculated value of SYSTEM BUFFERS + RANDOM BUFFERS PER USER is less than 512, a maximum of 512 buffers are used.

  • If the calculated value of SYSTEM BUFFERS + RANDOM BUFFERS PER USER is greater than 512, the calculated value is used for the maximum number of buffers.

  • An EXTENDED structure is being accessed serially and readahead is activated, in which case the serial buffer specification is used.

  • A non-EXTENDED structure is being accessed serially and readahead is activated, in which case 2 serial buffers are used.

ALLOWEDCORE is the ultimate limiting factor for any or all structures. Regardless of the 512 value or calculated value for SYSTEM BUFFERS + RANDOM BUFFERS PER USER for any individual structure, when ALLOWEDCORE is reached, OVERLAYs will begin and a new buffer allocation will be restricted.

For more information about BUFFER specifications and readahead logic, refer to Using the Defaults Specification and Data Set Declaration.

OVERLAY-GOAL (cont.)

The change to the default value requires a control file update in addition to a DASDL update on existing databases.

RESIDENT LIMIT

The RESIDENT LIMIT parameter limits the amount of memory used for MEMORY RESIDENT buffers. When the RESIDENT LIMIT parameter is exceeded, no more MEMORY RESIDENT buffers can be added. The value of the RESIDENT LIMIT parameter cannot exceed the value of the ALLOWEDCORE parameter. The default value is one half the value of the ALLOWEDCORE parameter.

SYNCPOINT

The SYNCPOINT parameter controls the maximum number of transactions that can occur between syncpoints. The actual number of transactions between syncpoints can vary because some actions cause a syncpoint to occur before the maximum number of transactions is reached. An example of this type of action is the termination of a program that closed the database. The parameter applies only to audited databases. The maximum value that can be specified is 4095. The default value is 100.

The value of the SYNCPOINT parameter can be changed while the database is active by directing a message to the database stack. For instructions on how to change this parameter by using Visible DBS commands, refer to the Enterprise Database Server Utilities Operations Guide.

SYNCWAIT

The SYNCWAIT parameter limits the time, in seconds, that a program waits for a syncpoint. The minimum allowable value for the syncwait parameter is 1.

When the wait time reaches the limit, an implicit ENDTRANSACTION is performed at the next data management verb for those programs that are still in transaction state. This ENDTRANSACTION produces a normal syncpoint. An implicit ENDTRANSACTION cannot be performed if a program is suspended, waiting for a locked record.

The system then performs an implicit BEGINTRANSACTION before returning to the program. This ENDTRANSACTION and BEGINTRANSACTION do not free any records locked in the programs and do not commit the transaction.

If a database exception occurs or the program terminates abnormally, the entire transaction is backed out to the original explicit BEGINTRANSACTION. If the system fails, halt/load recovery also backs out the transaction to the original explicit BEGINTRANSACTION.

However, if a SINGLEABORT operation backs out a transaction by means of a tape audit, and if other tasks are in transaction state, then the system does not issue the implicit ENDTRANSACTION and BEGINTRANSACTION, to avoid the potential deadlock situation of another SINGLEABORT operation trying to open the same audit. Instead, the system temporarily disables SYNCWAIT until the SINGLEABORT operation completes processing the tape audit.

You can change the value of the SYNCWAIT parameter while the database is active by directing a message to the database stack through a Visible DBS command. However, to do so, the SYNCWAIT parameter must be specified in DASDL. For instructions on using Visible DBS commands, refer to the Enterprise Database Server Utilities Operations Guide.

To disable the SYNCWAIT parameter when it has been set, you must remove the SYNCWAIT syntax from the DASDL source file and then compile the DASDL by using the UPDATE option. To temporarily disable the SYNCWAIT parameter, set the number of seconds to an extremely large number, for example, 60,000,000.

SYNCWAIT (cont.)

When a SYNCWAIT occurs on a database for a user who accesses the database through a shared library, a pseudo endtransaction/begintransaction is not issued on the user stack in the following cases:

  • The library users have locked records of standard edition structures.

  • A user is waiting on a record of an XE structure locked by another shared library user.

If the database has XE structures declared, a potential deadlock situation exists if a shared library user attempts to issue the pseudo ENDTRANSACTION and BEGINTRANSACTION. If this occurs, SYNCWAIT will be disarmed.

Note: The LOCALBUFFERING option, and the SHAREDALLOWEDCORE, LOCALALLOWEDCORE, SHARED RESIDENT LIMIT, and LOCAL RESIDENT LIMIT parameters have been deimplemented. If this option or any of these parameters is used, the message “LOCALBUFFERING DEIMPLEMENTED — OPTION IGNORED” is returned.

Example 1

In this example, the parameter specification requests the following:

  • A syncpoint occurs after every five transactions.

  • Once five transactions have occurred, the Enterprise Database Server waits until all programs are out of transaction state. If the Enterprise Database Server has to wait for four or more seconds, any programs in transaction state are temporarily taken out of transaction state so that the syncpoint can occur.

  • A controlpoint occurs after every 15 syncpoints.

OPTIONS (AUDIT);

PARAMETERS
 (
  CONTROLPOINT = 15 SYNCPOINTS,
  SYNCPOINT = 5 TRANSACTIONS,
  SYNCWAIT = 4 SECONDS
 );

D RANDOM DATA SET
 (
  DKEY         NUMBER(10);
 );

A ACCESS TO D KEY DKEY MODULUS = 15;

RESTARTDS RESTART DATA SET
 (
  R-PROGRAMNAME          ALPHA(35);
  R-USERINFO             ALPHA(200);
           );

Example 2

This example encrypts item C and R using the AESGCM algorithm. A key set will be generated and must be backed-up before you can access the database. 

PARAMETERS
(
   DATAENCRYPTTYPE = AESGCM 
);       

DEFAULTS 
(
   DATAENCRYPTKEYSET
);

D  DATA SET
(
  A   ALPHA(5);
  B   BOOLEAN;
  C   NUMBER(9)  DATAENCRYPT;
  G   GROUP
  (
  N   NUMBER(S5,2);
  F   FIELD(20);
  );
);
S SET OF D KEY IS A, INDEX SEQUENTIAL

Efficiency Considerations for Parameters lists the efficiency measures you should consider when you specify your database parameters.

Table 4. Efficiency Considerations for Parameters

Parameter

Description

ALLOWEDCORE

The ALLOWEDCORE option designates that the distribution of buffers is to be left to run- time accessing characteristics. Overlaying does not take place until the total system core reaches the value specified by ALLOWEDCORE, and the buffers are selected for overlaying regardless of the memory subsystem.

CONTROLPOINT

CONTROLPOINT frequency affects database performance. Frequent controlpoints, in general, increase the number of I/O operations performed on database buffers. Conversely, infrequent controlpoints require that the recovery operation process more audit records when halt/load recovery is necessary.

SYNCPOINT

SYNCPOINT frequency affects database performance. No program can be in transaction state when a syncpoint is performed. When the number of transactions specified in the SYNCPOINT parameter have taken place, no program can enter transaction state.

A program which attempts to enter transaction state will be suspended until all programs currently in transaction state have left it, and syncpoint processing is complete. Frequent syncpoints will increase the probability that a program will be suspended awaiting completion of a syncpoint.

SYNCPOINT frequency has a second effect. When a syncpoint occurs, a syncpoint record is placed in the audit buffer and the audit buffer is then written to the audit trail. Frequent syncpoints will tend to increase the number of I/O operations performed on the audit trail. Note that database buffers need not be written at syncpoint time; only audit buffers are flushed.

Infrequent syncpoints can adversely affect recovery. Large SYNCPOINT values can increase the number of transactions which are lost and must be reprocessed following halt/load or Abort recovery. Recovery backs out all transactions since the last point at which no program was in transaction state. The number of transactions backed out will depend upon the activity against the database. In the case of a single program updating the database, no completed transactions which are reflected in the audit trail will be backed out. On the other hand, if two or more programs are updating the database, it is possible that no point exists since the last syncpoint at which all programs are concurrently out of transaction state. In this instance, all transactions since the last syncpoint would be backed out and would require reprocessing.


Prev  Up  Next
Examples of Using the Options Specification  Home  Using the Code File Specifications