ADAFRM (Format And Create A New Database)

#### Search Results

Search

# ADAFRM (Format And Create A New Database)

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 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.

3. If a database ID is specified, the corresponding encryption information stored in ASSO1 is read. If the database has been created with encryption, TEMP containers are also encrypted.

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. If a dbid is supplied, the corresponding entries are added in the DBnnn.INI file in case they are missing.

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

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 | Utilities Manual |
ADAFRM messages | stdout |  | 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 |  | Utilities Manual
ADAFRM messages | stdout |  | 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. When formatting TEMP and/or SORT, for an encrypted database, a dbid is mandatory. The encryption information stored in ASSO1 is read, and the TEMP and/or SORT container are encrypted accordingly. For the unencrypted case, a dbid may be given, but is not mandatory.

### 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_128_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. See Adabas Security Features > Adabas Encryption for Linux > Key Management System for all supported key management systems.

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.

If a SORT container is to be used with an encrypted database, a dbid has to be specified. The encryption information stored in ASSO1 is read and the SORT container is encrypted accordingly. For the unencrypted case, a dbid may be give, but it is not necessary.

### 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.

If a TEMP container is to be used with an encrypted database, you must specify a dbid. The encryption information stored in ASSO1 is read, and the TEMP container is encrypted accordingly. For the unencrypted case, a dbid may be given, but is not mandatory.

### 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.

### On this page

- Functional Overview
- Procedure Flow
- Checkpoints
- Control Parameters
- Restart Considerations
- Control Statement Examples