This document describes the utility "ADAFRM".
The following topics are covered:
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:
If an environment variable for the container extent exists, use the environment variable.
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.
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:
If an environment variable for the container extent exists, use the environment variable.
Otherwise create the container in the current directory with the name XXXXx, where XXXX is the container type, and x the container extent.
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.
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 |
The utility writes no checkpoints.
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 = (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.
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 = (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 = (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 = 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 = 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 = 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 {=|:} 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 = (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 = (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 = (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 = 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 = 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.
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.
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.
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).
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.