This document describes the utility "ADAFRM".

The following topics are covered:

• Functional Overview

• Procedure Flow

• Checkpoints

• Control Parameters

• Restart Considerations

• Control Statement Examples

---

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 UNIX, %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.

This utility is a single function utility.

Procedure Flow

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.

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.

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.

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.

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.