ADAFRM (Format And Create A New Database)

This document describes the utility "ADAFRM".

The following topics are covered:


Functional Overview

The utility ADAFRM creates the container files (ASSO, DATA, WORK) assigned to the database and establishes the database including the database system files. It can also be used to format the TEMP and SORT files.

The database is included in the ADABAS.INI file.

If the file DBnnn.INI does not yet exist, ADAFRM creates the DBnnn.INI file, including the default parameters derived from ADABAS.INI, and stores it in the appropriate database directory (please refer to Adabas Extended Operation for further information about the DBnnn.INI files).

The following rules apply for determining the locations for the container extents to be created:

  1. If an environment variable for the container extent exists, use the environment variable.

  2. If the DBnnn.INI file already exists before ADAFRM is started, and it contains an entry for the container extent, use the entry in the DBnnn.INI file.

  3. Otherwise create the container extent in the database directory ($ADADATADIR/dbnnn on Linux, %ADADATADIR%\dbnnn on Windows) with name XXXXx.nnn, where XXXX is the container type, x the container extent and nnn the database number.

Exceptions are the SORT and TEMP containers if they are created without creating a database at the same time; here the following rules apply:

  1. If an environment variable for the container extent exists, use the environment variable.

  2. Otherwise create the container in the current directory with the name XXXXx, where XXXX is the container type, and x the container extent.

If you create a database, but not if you only create the SORT or TEMP containers, the created container extents are stored in theDBnnn.INI file. If the DBnnn.INI file already was created before ADAFRM was started, all other values in the file are not changed; if the file didn’t exist, it is created with default values.

If you create only the SORT or TEMP containers without creating a database, no updates are performed in a DBnnn.INI file.

For the raw device interface, the utility ADADEV can be used if placement control is required. Raw devices and files in the file system may be used for database container files.

You can create up to 255 ASSO and 255 DATA container files. You can add more containers later using ADADBM's ADD_CONTAINER function.

After ADAFRM creates the container files, it initializes the global Adabas blocks, inserts the 3 Adabas system files (checkpoint file, ET data file, security file) and allocates space for them. The checkpoint file is allocated 3000 records, the ET data file is allocated 3000 records and the security file is allocated 200 records.

Block sizes from 1 kilobyte to 32 kilobytes may be used for database container files.

If you try to reformat a container file, the utility terminates with an error message. This ensures that the database is not accidentally overwritten.

If you create an encrypted database, the encryption algorithm and the key management system have to be specified. The ASSO and DATA container files are encrypted with the specified encryption algorithm. The key management system manages the corresponding encryption keys.

Note:
In order to use the encryption functionality, the Adabas Encryption for Linux (AEL) license is required.

This utility is a single function utility.

Procedure Flow

Procedure Flow ADAFRM

If a database is to be formatted:

Data Set Environment
Variable/
Logical Name
Storage Medium Additional Information
ADABAS.INI   Disk Adabas Extended Operations Manual
Associator ASSOx Disk  
Data storage DATAx Disk  
DBnnn.INI   Disk Adabas Extended Operations Manual
Control statements stdin/
SYS$INPUT
  Utilities Manual
ADAFRM messages stdout/
SYS$OUTPUT
  Messages and Codes
Work WORK1 Disk  

If a TEMP or SORT is to be formatted:

Data Set Environment
Variable/
Logical Name
Storage Medium Additional Information
Sort storage SORTx Disk  
Control statements stdin/
SYS$INPUT
  Utilities Manual
ADAFRM messages stdout/
SYS$OUTPUT
  Messages and Codes
Temporary storage TEMPx Disk  

Checkpoints

The utility writes no checkpoints.

Control Parameters

The following control parameters are only used when establishing a new database:

D    ASSOBLOCKSIZE = (number[K] [,number[K]] ... )

M    ASSOSIZE = (number[B|M] [,number[B|M]]...)

D    DATABLOCKSIZE = (number[K] [,number[K]] ... )

M    DATASIZE = (number[B|M] [,number[B|M]]...)

     DBID = number

     ENCRYPTION = keyword

     KMSTARGET = string

D    NAME {=|:} string

M    SORTSIZE = (number[M] [,number[M]] ... )

D    SYSFILES = (number, number, number)

M    TEMPSIZE = (number[M] [,number[M]] ... )

D    WORKBLOCKSIZE = number[K]

M    WORKSIZE = number[M | B]

ASSOBLOCKSIZE

ASSOBLOCKSIZE = (number[K] [,number[K]] ... )

This parameter specifies the block sizes that are to be used for the Associator container file(s). The first block size corresponds to ASSO1, the second to ASSO2 etc.

If block sizes are not specified, the default of 4K will be used.

For ASSO1, only blocks sizes from 2K to 8K can be specified. For ASSO2 to ASSOn, block sizes between 1K and 32K are permitted.

Note:
The ASSOBLOCKSIZE parameter should be specified once for each ASSOSIZE that is specified, i.e. these parameters should be specified in pairs. If ASSOSIZE is specified more frequently than ASSOBLOCKSIZE, then the last specified block size will be used for the containers that do not have a block size specified. The default value will be used if ASSOBLOCKSIZE is not specified at all.

ASSOSIZE

This parameter specifies the number of blocks or megabytes to be assigned to the Associator.

If the Associator is to be contained in more than one physical file, the size of each file must be specified.

If a `B' is appended to the number, the size is in blocks, otherwise it is in megabytes.

DATABLOCKSIZE

DATABLOCKSIZE = (number[K] [,number[K]] ... )

This parameter specifies the block sizes that are to be used for the Data Storage container file(s). The first block size corresponds to DATA1, the second to DATA2 etc.

If block sizes are not specified, the default of 32K will be used.

Note:
The DATABLOCKSIZE parameter should be specified once for each DATASIZE that is specified, i.e. these parameters should be specified in pairs. If DATASIZE is specified more frequently than DATABLOCKSIZE, then the last specified block size will be used for the containers that do not have a block size specified. The default value will be used if DATABLOCKSIZE is not specified at all.

DATASIZE

DATASIZE = (number[B|M] [,number[B|M]]...) 

This parameter specifies the number of blocks or megabytes to be assigned to the Data Storage.

If the Data Storage is to be contained in more than one file, the size of each file must be specified.

If a `B' is appended to the number, the size is in blocks, otherwise it is in megabytes.

DBID

DBID = number

This parameter selects the database to be created.

The minimum value is 1 and the maximum value is 255.

Note:
This parameter only needs to be set when formatting ASSO, DATA and WORK. It must not be entered when formatting only SORT or TEMP.

ENCRYPTION

ENCRYPTION = keyword

This parameter specifies that the database to be created is encrypted, and assigns the encryption algorithm. The keyword can take the values AES_256_XTS, AES_128_XTS and NO. Depending on the keyword specified, the ASSO and DATA container files are encrypted using XTS Advanced Encryption Standard with a key length of 256 bits (AES_256_XTS), a key length of 128 bits (AES_256_XTS), or they are not encrypted (NO).

The default value is NO.

Note:
Database encryption cannot be disabled.

KMSTARGET

KMSTARGET = string

This parameter specifies the key management system to be used if the database to be created is encrypted. Supported values are FILE and AWS. Depending on the value specified, either the Adabas file-based key management system or the AWS key management service is used to create, store and manage encryption keys.

The default value is FILE.

NAME

NAME {=|:} string

This parameter specifies the name to be assigned to the database. This name will appear in the title of the database status report produced by the report utility ADAREP. If you specify an equals sign, the value given for 'string' will be converted to upper case; if you specify a colon, no upper-case conversion is performed.

A maximum of 16 characters may be specified.

If this parameter is omitted, a default value of `GENERAL-DATABASE' is assigned.

SORTSIZE

SORTSIZE = (number[M] [,number[M]] ... )

This parameter specifies the number of megabytes to be assigned to the SORT dataset.

If the SORT dataset consists more than one extent, the size of each extent must be specified. Up to 50 extents can be specified. The SORT dataset can be formatted independently.

SYSFILES

SYSFILES = (number, number, number)

This parameter specifies the file numbers to be reserved for the Adabas system files. These file numbers must not be used subsequently for user files.

The first value specifies the file number of the checkpoint file.

The second value specifies the file number of the security file.

The third value specifies the file number of the user data file.

The default setting is SYSFILES=(1, 2, 3).

TEMPSIZE

TEMPSIZE = (number [M] [,number[M]] ... )

This parameter defines the number of megabytes to be assigned to TEMPx.

If the TEMP dataset is to be contained in more than one physical file, the size of each file must be specified.

This component may be formatted independently.

WORKBLOCKSIZE

WORKBLOCKSIZE = number[K]

This parameter specifies the block size that is to be used for the WORK file.

If no block size is specified, the default of 16K will be used.

WORKSIZE

WORKSIZE = number [B|M]

This parameter defines the number of blocks or megabytes to be assigned to WORK1.

If a `B' is appended to the number, the size is in blocks, otherwise it is in megabytes.

Restart Considerations

ADAFRM does not have a restart capability. An interrupted ADAFRM run must be restarted from the beginning. Associator, Data Storage and WORK must be formatted together.

The files created during an earlier run have to be deleted first.

Control Statement Examples

Example: Formatting a database

adafrm: dbid = 1, name = DATABASE_1
adafrm: assosize = (200M, 100M), assoblocksize = (2K, 4K)
adafrm: datasize = (500M, 500M, 2M), datablocksize = (4K, 16k)
adafrm: worksize = 50M, workblocksize = 16K

A new database is created with the DBID 1 and the name "DATABASE_1". Two ASSO container files are created: ASSO1 has a size of 200 megabytes and a blocksize of 2 kilobytes, and ASSO2 has a size of 100 megabytes and a blocksize of 4 kilobytes. There are three DATA containers. DATA1 and DATA3 have a blocksize of 4 kilobytes, DATA2 has a blocksize of 16 kilobytes. There is a single WORK container file with a block size of 16 kilobytes. The file numbers 1, 2 and 3 will be used for the 3 system files.

Example: Formatting an encrypted database

adafrm: dbid = 2, name = DATABASE_2
adafrm: assosize = (200M, 100M), assoblocksize = (2K, 4K)
adafrm: datasize = (500M, 500M, 2M), datablocksize = (4K, 16k)
adafrm: worksize = 50M, workblocksize = 16K
adafrm: encryption = aes_256_xts

A new database is created with DBID 2, and the name "DATABASE_2”, and with the same layout as in the example above. In this database, the ASSO and DATA container files are encrypted with algorithm AES_256_XTS. The encryption keys are created and managed by the Adabas file-based key management system (default: KMSTARGET = FILE).

Example: Formatting SORT and TEMP

adafrm: sortsize = (10M,10M)
adafrm: tempsize = 10M

Explanation: Two container files, each 10 megabytes in length, are to be formatted as SORT1 and SORT2. A container file, 10 megabytes in length, is to be formatted as TEMP1.