This document describes the utility "ADAFDU".
The following topics are covered:
The file definition utility ADAFDU defines a new base file and/or a LOB file in a database. It does not require the Adabas nucleus to be active.
The field definitions for a base file, including special descriptor definitions and referential integrity definitions for foreign keys, are read from the sequential file FDUFDT; the field definition of a LOB file is predefined. Additional input for ADAFDU is provided by parameters.
See Administration, FDT Record Structure for information about the syntax and use of the data definitions to define the logical structure of the file in the database.
See Administration, Loading And Unloading Data, File Space Estimation for information about formulae for calculating the Associator and Data Storage space requirements for a file.
This utility is a single-function utility.
If the nucleus is not active, ADAFDU itself creates the new file in ASSO and DATA
If the nucleus is active, ADAFDU calls the nucleus to create the new file in ASSO and DATA. In this case, no checkpoint is written, but the file creation is logged in the database log, and in case of a recovery, the file is created automatically.
| Data Set | Environment Variable/ Logical Name |
Storage Medium |
Additional Information |
|---|---|---|---|
| Associator | ASSOx | Disk | |
| Data storage | DATAx | Disk | |
| Control statements | stdin/ SYS$INPUT |
Utilities Manual | |
| ADAFDU messages | stdout/ SYS$OUTPUT |
Messages and Codes | |
| FDT information | FDUFDT | Disk,Tape (* see note) | |
| Protection Log | NUCPLG | Disk | Utilities Manual ADAPLP |
Note:
(*) A named pipe can be used for this sequential file
(not on OpenVMS, see Administration, Using
Utilities for details).
The utility writes a SYNP checkpoint if it is performed offline. If the utility is performed online, the file definition is written to the PLOG, a SYNX checkpoint is written.
The following control parameters are available:
ACBLOCKSIZE = numberK
ACRABN = number
ADAM_KEY = key
D ADAM_OVERFLOW = number
D ADAM_PARAMETER = number
ADD_LOBFILE = (number,number)
D ASSOPFAC = number
D [NO]BT
D [NO]CIPHER
D CONTIGUOUS = ([AC], [,DS] [,NI] [,UI])
D DATAPFAC = number
M DBID = number
DSBLOCKSIZE = numberK
DSRABN = number
D DSSIZE = number[B|M]
FDT
FILE = number
D [NO]FORMAT
LOBFILE = number [,LOBSIZE = number[B|M]]
D [NO]LOWER_CASE_FIELD_NAMES
D MAXISN = number
D NAME{=|:} string
NIBLOCKSIZE = numberK|(numberK,numberK)
NIRABN = number|(number,number)
D NISIZE = number[B|M]|(number[B|M],number[B|M])
[NO]PGM_REFRESH
D REUSE = (keyword [,keyword])
SYFMAX = number
UIBLOCKSIZE = numberK|(numberK,numberK)
UIRABN = number|(number,number)
D UISIZE = number[B|M]|(number[B|M],number[B|M])
ACBLOCKSIZE = numberK
This parameter allows you to specify a block size for the allocation of the address converter extent.
acblocksize = 6k
The address converter will be allocated with a block size of 6 kilobytes.
If the database does not contain enough space with this block size, ADAFDU aborts.
ACRABN = number
This parameter specifies the RABN at which the space allocation for the Address Converter is to start.
This parameter can be used to allocate the Address Converter to a given container file extent.
If this parameter is omitted, ADAFDU assigns the starting RABN.
ADAM_KEY = key
If this parameter is specified, the file is defined as an ADAM file. The key can be either a descriptor name or the keyword `ISN'. If an ADAM key is used, it must be defined with the UQ option in the FDT. It must not be a sub-, super-, phonetic or hyperdescriptor. It must not be a multiple-value field or a field within a periodic group. It must not have the NU/NC option.
ADAM_OVERFLOW = number
This parameter specifies the number of DATA overflow blocks for the file. Overflow blocks are required in case ADAM-calculated blocks get full. The overflow blocks are taken from the end of the file's DATA blocks.
At least one overflow block must be allocated.
The maximum is DSSIZE - 1.
Note:
When checking the maximum value, and DSSIZE is specified in
megabytes, it is assumed that the Data Storage block size is 32 - independent
of the actual value. If you want to specify a larger value for ADAM_OVERFLOW,
which is possible with a smaller Data Storage block size, DSSIZE must be
specified in blocks.
The default is 1.
ADAM_PARAMETER = number
This parameter specifies the number of consecutive ISNs to be stored in one block if the keyword `ISN' is specified for the ADAM_KEY parameter.
If the ADAM key is a descriptor with fixed-point format, the parameter specifies the number of consecutive values for one block. For other key formats, it specifies an offset into the values. See Administration for more information.
A value may be specified in the range 1 to 10000.
The default value is 8.
ADD_LOBFILE = (number, number)
The parameter ADD_LOBFILE is used to create a LOB file and assign it to an existing base file that is specified by the first number, the base file must not yet have an assigned LOB file. A LOB file, with the file number specified by the second number, is generated and assigned to the base file, and the base file is enabled for LOB processing. A file with the specified file number must not yet exist. The maximum number that can be specified is 32000. You can specify the parameters describing the data storage, the address converter, the normal and upper index of the LOB file, but the following should be taken into consideration:
The block size for LOB file data blocks must be 32 KB.
The block size for LOB NI and UI blocks must be < 16 KB.
It is not possible to specify FILE if you specify ADD_LOBFILE, and vice versa.
Because there are some predefined requirements for a LOB file, not all the other ADAFDU parameters make sense in connection with ADD_LOBFILE, for example the ADAM_* parameters. These parameters are ignored by ADAFDU when the LOB file is added.
ASSOPFAC = number
This parameter specifies the padding factor to be used for the file's index. The number specified is the percentage of each index block which is not to be used by a subsequent run of the mass update utility ADAMUP. This padding area is reserved for future use if additional entries have to be added to the block by the Adabas nucleus. This avoids the necessity of having to relocate overflow entries to another block.
A value may be specified in the range 0 to 95.
A small padding factor (0 to 10) should be specified if little or no descriptor updating is expected. A larger padding factor (10 to 50) should be specified if there is a large amount of descriptor updating in which new descriptor values are created.
You can change the padding factor at a later time using the utility ADAORD.
The default padding factor is 5.
[NO]BT
If NOBT is specified, this file will be a no-BT file, which means that modifications to this file are not made within normal transaction logic, and all modifications are kept in the database even if a transaction is backed out.
BT is the default.
Note:
The following points should be considered if the nucleus
crashes:
All database modifications for a no-BT file issued before the last ET command are applied to the database.
It is not defined whether database modifications for a no-BT file issued after the last ET command are applied to the database or not.
[NO]CIPHER
This option can be used to enable or disable data record ciphering.
Ciphering prevents the unauthorized analysis of Adabas container files. If ciphering is enabled, data records are ciphered when they are stored in a database by either the Adabas nucleus or by the mass update utility ADAMUP. The data records are then deciphered when they are requested by a user or application: this means that the ciphering is completely transparent to the user or application. See Administration, Adabas Security Facilities for further information about ciphering.
The default is NOCIPHER.
CONTIGUOUS = ( [AC] [,DS] [,NI] [,UI] )
This parameter is used to control ADAFDU's space allocations. If specified, ADAFDU ensures that only the first logical extent of the types specified is used.
By default, ADAFDU makes contiguous-best-try allocations.
DATAPFAC = number
This parameter specifies the padding factor to be used for the file's Data Storage. The number specified is the percentage of each data block which is not to be used when subsequently adding new records to the file with the mass update utility ADAMUP or with the Adabas nucleus. This padding area is reserved for future use if any record in the block requires additional space as a result of record updating by the Adabas nucleus. This avoids the necessity of having to relocate the record to another block.
A value in the range 0 to 95 may be specified.
A small padding factor (0 to 10) should be specified if there is little or no record expansion. A larger padding factor (10 to 50) should be specified if there is a large amount of record updating which will cause expansion.
You can change the padding factor at a later time using the utility ADAORD.
The default padding factor is 5.
DBID = number
This parameter selects the database to be used.
DSBLOCKSIZE = numberK
This parameter allows you to specify a block size for the allocation of the data storage extent.
dsblocksize = 6k
Data storage will be allocated with a block size of 6 kilobytes.
If the database does not contain enough space with this block size, ADAFDU aborts.
DSRABN = number
This parameter specifies the RABN at which the space allocation for Data Storage is to start.
This parameter can be used to allocate Data Storage to a given container file extent.
If this parameter is omitted, ADAFDU assigns the starting RABN.
DSSIZE = number [B|M]
This parameter specifies the number of blocks or megabytes to be assigned to Data Storage. By default, the size is given in megabytes.
The value specified for DSSIZE determines the size of the logical extent allocated to Data Storage for the file.
A contiguous-best-try allocation is made unless CONTIGUOUS=DS has been specified.
This parameter is mandatory for ADAM files - the dependencies between the parameters ADAM_OVERFLOW and DSSIZE are described for the parameter ADAM_OVERFLOW.
For non-ADAM files, this parameter can be omitted; in this case Adabas calculates a reasonable number of blocks to be used for Data Storage. If the size that is actually required is larger, the file is automatically increased.
FDT
If this parameter is specified, the FDT contained in the sequential file FDUFDT is displayed.
FILE = number
This parameter is required when a base file is to be created; it specifies the file number to be assigned to the file.
The `number' specified must not be currently assigned to another file in the database and must not exceed the maximum file number defined for the database. The maximum number that can be specified is 32000.
File numbers can be assigned in any sequence.
It is not possible to specify FILE if you specify ADD_LOBFILE, and vice versa.
[NO]FORMAT
This option is used to control whether the RABNs allocated for the file's index and Data Storage are to be formatted or not. The RABNs of the file's Address Converter are always formatted.
The default is NOFORMAT.
LOBFILE = number [, LOBSIZE = number[B|M]]
If LOBFILE is specified, a LOB file with the specified number is generated and assigned to the base file to be created, and the base file is enabled for LOB processing. A LOB file with the specified file number must not already exist. The maximum number that can be specified is 32000. You should take the following into consideration:
The block size for LOB file data blocks will be 32 KB.
The block size for LOB NI and UI blocks will be < 16 KB.
LOBSIZE specifies the size in Data storage of the LOB file, analogously to the parameter DSSIZE.
Adabas calculates reasonable sizes for the Address converter, the normal and upper index of the LOB file. If you want to specify these values yourself, you should create the base file first without specifying LOBFILE, and then you should call ADAFDU again and add the LOB file with the ADD_LOBFILE parameter.
[NO]LOWER_CASE_FIELD_NAMES
If LOWER_CASE_FIELD_NAMES is specified, Adabas field names are not converted to upper case. If NOLOWER_CASE_FIELD_NAMES is specified, Adabas field names are converted to upper case. The default is NOLOWER_CASE_FIELD_NAMES.
MAXISN = number
This parameter specifies the highest ISN expected in the file. The file definition utility ADAFDU uses this parameter to determine the amount of space to be allocated for the file's Address Converter (AC). The default value for MAXISN is 5000.
A contiguous-best-try allocation is made unless CONTIGUOUS=AC has been specified.
Note:
The value is rounded up to the number of ISNs that fit into the
Address converter blocks required to store MAXISN ISNs in the Address
converter, the exact value used as MAXISN for the file is:
(MAXISN
specified / (Address converter block size / 4) + 1) * (Address converter block
size / 4) -1. For example, using an Address converter with a block size of 4KB,
the default value of 5000 is increased to (5000 / (4096 / 4) + 1) * (4096 / 4)
-1 = 5119.
NAME {=|:} string
This parameter specifies the name to be assigned to the file. This name will appear together with data about this file in the database status report produced by the report utility ADAREP. A maximum of 16 characters are permitted. 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
The default value is FILE-n, where n is the file number.
NIBLOCKSIZE = numberK|(numberK,numberK)
This parameter allows you to specify a block size for the allocation of the Normal Index. Note that the Normal Index requires a block size >= 16 KB for large index values > 253 bytes, while a smaller block is allocated for descriptors with smaller descriptor values. The following must be taken into consideration:
If you specify one block size, the file is created with all normal index blocks having this size.
If you specify two block sizes, one value should be < 16K, and one value should be >= 16K. You should also specify two values for NISIZE; the first value for NIBLOCKSIZE corresponds to the first value of NISIZE, and the second value for NIBLOCKSIZE corresponds to the second value of NISIZE.
niblocksize = 6k
The normal index will be allocated with a block size of 6 kilobytes.
niblocksize = (8k,32k) nisize = (1000b,10m)
The normal index will be allocated with 1000 blocks of block size 8 KB and 10 MB of block size 32 KB.
If the database does not contain enough space with this block size, ADAFDU aborts.
NIRABN = number|(number,number)
This parameter specifies the RABN at which the space allocation for the Normal Index is to start. This parameter can be used to allocate the Normal Index to a given container file extent.
If two RABNs have been specified, one should have a block size < 16KB, and the other should have a block size of >= 16KB.
If this parameter is omitted, ADAFDU assigns the starting RABNs.
If both NIBLOCKSIZE and NIRABN are specified, the block sizes of the RABNs specified as NIRABN must be equal to the values specified as NIBLOCKSIZE.
NISIZE = number [B|M]|(number [B|M],number [B|M])
This parameter defines the number of blocks or megabytes to be assigned to the Normal Index. By default, the size is in megabytes.
If the block size cannot be derived from the NIBLOCKSIZE or the NIRABN parameter, the first value for NISIZE is used for blocks < 16KB, and the second value is used for blocks >= 16KB.
A contiguous-best-try allocation is made unless CONTIGUOUS=NI has been specified.
If this parameter is omitted, Adabas calculates a reasonable number of blocks to be used for the normal index.
adafdu: nisize = 100b
If the block size cannot be derived from the NIBLOCKSIZE or NIRABN parameter, 100 blocks with block size < 16KB are allocated for the Normal Index.
adafdu: nisize = (10m,1000b)
If the block size cannot be derived from the NIBLOCKSIZE or NIRABN parameter, 10 MB of blocks with block size < 16KB and 1000 blocks of block size >= 16KB are allocated for the Normal Index.
[NO]PGM_REFRESH
If PGM_REFRESH is specified, the file can be refreshed by an E1 command (reset to a state of zero records loaded) when it is loaded.
The default is NOPGM_REFRESH.
REUSE = ( keyword [,keyword] )
The REUSE parameter controls the reuse of Data Storage space or ISNs by Adabas.
NODS causes all newly-added records, together with records that have to be moved to another block (as a result of record expansion caused by updating) to be placed in the last used block in the Data Storage extent allocated to the file. If there is not sufficient space in this block, the next block is used.
If the DS keyword is specified, Adabas will scan the Data Storage Space Table (DSST) in order to locate a block with sufficient space. In this case, the first block found with sufficient space will be used.
The file control block for the specified file is modified to indicate the type of allocation to be used when adding new records or moving updated records.
The default value is DS.
If REUSE is set to NOISN, Adabas does not reuse the ISN of a deleted record for a new record. Each new record will be assigned the next-highest unused ISN.
If REUSE is set to ISN, Adabas may reuse ISNs of deleted records. ISN reusage is done as follows: when a new record is stored in the database, an Address Converter (AC) block is read and checked for a free ISN. In order to keep the overhead for ISN reusage small, only one AC block is read - if no free ISN is found in the AC block, handling is the same as when ISN reusage is switched off.
Note:
Setting REUSE to ISN, does not necessarily mean that ISN reusage is
actually done. Because unsuccessful ISN reusage means an overhead for reading
an additional AC block, Adabas sets ISN reusage to inactive if the probability
of finding a reusable ISN is small. After deleting enough records, ISN reusage
is then set to Active again.
The default value is NOISN.
adafdu: reuse = (isn, ds)
ISNs of deleted records can be reassigned to new records. The DSST is scanned for free space when a record is added to the database or when an updated record is moved in the database.
adafdu: reuse = isn
Reuse of data storage and ISNs is allowed.
adafdu: reuse = <cr>
Reuse of data storage and no reuse of ISNs is specified. This is the default setting.
SYFMAX = number
This parameter specifies the maximum number of values generated for a system generated multiple-value field. There is no explicit maximum value, but you should bear in mind, that you can get a record overflow if the value is defined too high; the compressed data record should also fit into one DATA block is SYFMAX values are defined for system generated multiple-value fields.
The default value is 1.
UIBLOCKSIZE = numberK|(numberK,numberK)
This parameter allows you to specify a block size for the allocation of the Upper Index. Note that the Upper Index requires a block size >= 16 KB for large index values > 253 bytes, while a smaller block is allocated for descriptors with smaller descriptor values. The following must be taken into consideration:
If you specify one block size, the file is created with all normal index blocks having this size.
If you specify two block sizes, one value should be < 16K, and one value should be >= 16K. You should also specify two values for UISIZE; the first value for UIBLOCKSIZE corresponds to the first value of UISIZE, and the second value for UIBLOCKSIZE corresponds to the second value of UISIZE.
uiblocksize = 6k
The upper index will be allocated with a block size of 6 kilobytes.
uiblocksize = (8k,32k) uisize = (1000b,10m)
The upper index will be allocated with 1000 blocks of block size 8 KB and 10 MB of block size 32 KB.
If the database does not contain enough space with this block size, ADAFDU aborts.
UIRABN = number|(number,number)
This parameter specifies the RABN at which the space allocation for the Upper Index is to start. This parameter can be used to allocate the Upper Index to a given container file extent.
If two RABNs have been specified, one should have a block size < 16KB, and the other should have a block size of >= 16KB.
If both UIBLOCKSIZE and UIRABN are specified, the block sizes of the RABNs specified as UIRABN must be equal to the values specified as UIBLOCKSIZE.
If this parameter is omitted, ADAFDU assigns the starting RABN.
UISIZE = number [B | M]
This parameter defines the number of blocks or megabytes to be assigned to the Upper Index. By default, the size is in megabytes.
If the block size cannot be derived from the UIBLOCKSIZE or the UIRABN parameter, the first value for UISIZE is used for blocks < 16KB, and the second value is used for blocks >= 16KB.
A contiguous-best-try allocation is made unless CONTIGUOUS=UI has been specified.
If this parameter is omitted, Adabas calculates a reasonable number of blocks to be used for the upper index.
adafdu: dbid = 1, file = 6, maxisn = 20000, dssize = 100B, adafdu: assopfac = 10, datapfac = 10, adafdu: uisize = 20b, nisize = 5
File 6 is to be loaded. The maximum number of expected records preset for the file is 20000. 100 blocks are allocated for Data Storage. The Associator and Data Storage block padding factors are both 10 percent. 20 blocks are allocated for the Upper Index and 5 megabytes for the Normal Index. The Normal Index ISN size is implicitly set to 2.
adafdu: dbid = 1, file = 7, maxisn = 350000, adafdu: assopfac = 5, datapfac = 15, adafdu: dssize = 100, adafdu: uisize = 2, nisize = 30
File 7 is to be loaded. The maximum number of expected records preset for the file is 350000. The Associator padding factor is 5 percent. The Data Storage padding factor is 15 percent. 100 megabytes are allocated for Data Storage. The Normal Index ISN size is implicitly set to 4.
adafdu: dbid = 1, file = 8, adafdu: maxisn = 10000, dssize = 20, adafdu: uisize = 10b, nisize = 50b
File 8 is to be loaded. The maximum number of expected records preset for the file is 10000. 20 megabytes are allocated to Data Storage. The padding factor for both the Associator and Data Storage is 5 percent (default).
adafdu: dbid = 1, file = 9, maxisn = 55000, dssize = 2000b, dsrabn = 30629, adafdu: uisize = 50b, nisize = 300b, adafdu: assopfac = 20, datapfac = 10
File 9 is to be loaded. The maximum number of expected records preset for the file is 55000. 2000 blocks are allocated for Data Storage. The Data Storage allocation will start at RABN 30629. 50 blocks are allocated for the Upper Index. 300 blocks are allocated for the Normal Index. The padding factor for the Associator is 20 percent. The padding factor for Data Storage is 10 percent.
adafdu: dbid = 1, file = 10, maxisn = 20000
File 10 is to be loaded. The maximum number of records expected for the file is set to 20000. All space allocation will be calculated by Adabas.