The bldism utility enables you to create an ISAM file outside your application by getting information from keyboard input, from a parameter file (output from the ipar utility), or from an ISAM definition language (XDL) keyword file. This topic describes the ISAM definition language file and the keywords required to create one. You can check your XDL syntax using the XDL Syntax Checker utility (xdlchk).
This topic includes the following:
Rules for XDL keyword files
The following rules apply to XDL keyword files:
- The file must contain valid XDL keywords followed by their assigned values. (See XDL keywords below.)
- The file may contain comments, which must begin with an exclamation point. The rest of the line following an exclamation point is ignored. Blank lines are also allowed.
- An XDL description must contain one FILE and one SIZE keyword. In addition, each key definition must contain exactly one LENGTH and one START keyword.
- The file attribute section of the definition may not contain more than one FILE, NAME, ADDRESSING, PAGE_SIZE, KEYS, NETWORK_ENCRYPT, SIZE_LIMIT, RECORD_LIMIT, ROLLBACK, STORED_GRFA, TRACK_CHANGES, RESILIENT, FULLRESILIENT, TEXT, TEXT_ALLOCATION, DENSITY, RECORD, SIZE, FORMAT, COMPRESS_DATA, STATIC_RFA, or SEED keyword.
- File keywords must follow FILE, record keywords must follow RECORD, and key keywords must follow KEY.
- A keyword and its value must be separated from other keywords and their assigned values by either a carriage return or a semicolon.
- All keywords and values may be abbreviated. However, they must not be abbreviated to the point to where they cannot be distinguished from other keywords and values. For example, you cannot abbreviate DENSITY to “D” because it cannot be distinguished from the DUPLICATES keyword. Abbreviating DENSITY to “DE,” however, is valid. Similarly, TYPE INTEGER can’t be abbreviated as “TYPE I,” because it cannot be distinguished from the FDL keyword value TYPE INT2. We suggest that you use the full keywords and values for readability.
Synergy ISAM (Windows and UNIX) recognizes both XDL and FDL keyword forms. OpenVMS, however, does not recognize the XDL forms. See Correspondence of XDL keywords to FDL keywords for more information.
XDL keywords
An XDL file must be composed of the following keywords and their values according to the rules listed in Rules for XDL keyword files:
FILE
Indicates the beginning of the XDL description. No value should be supplied.
NAME filename
The name of the ISAM file you want to create. This value is ignored when the XDL description comes from the OPEN statement. Instead, the filename in the OPEN statement is used. However, this value is used when the XDL description comes from bldism. The default extension is .ism.
ADDRESSING file_size
(optional) The address length of the ISAM file. Possible values are
32-bit signed file address for a maximum individual file size of 2Gb. (default)
48-bit file address for a maximum individual file size of 256 TB (equivalent to TBYTE in the parameter form). When creating a Revision 4 file, either value generates a 40-bit maximum file size of 1 TB.
Prohibits an implicit TBYTE setting.
PAGE_SIZE page_size
(optional) The size, in bytes, of the index blocks. Possible values are
512
1024
2048
4096
8192
16384
32768
The default is 4096 for Revision 6 files (and 1024 for Revision 4 files).
KEYS num_keys
(optional) The number of keys in the ISAM file, from 1 to 255. If not specified, the number of keys is calculated by counting the number of supplied key definitions.
ERASE_ON_DELETE yes|no
(optional) Controls what will happen to a record when it’s deleted. A value of yes causes the record to be erased (i.e., nulled out), and a value of no causes records that are deleted to be marked deleted, but their contents remain in the file until the space is physically reused. The default is no. ERASE_ON_DELETE cannot be used if TRACK_CHANGES is set.
NETWORK_ENCRYPT yes|no
(optional) Specifies whether the network encryption flag is enabled for this file. The default is no.
ROLLBACK yes|no
(optional) Controls the rollback function. A value of yes allows it, and a value of no prohibits it. The default is yes.
SIZE_LIMIT max_size
(optional) The maximum size the .is1 file is allowed to reach, in megabytes. If this limit is exceeded, a “File size limit exceeded” error (SIZLIMIT) occurs.
RECORD_LIMIT recs
(optional) The maximum number of records allowed in the .is1 file. If this limit is exceeded, a “File record limit exceeded” error (RECLIMIT) occurs.
TRACK_CHANGES yes|no
(optional) Specifies whether change tracking is enabled. The default is no.
RESILIENT yes|no
(optional) Indicates that the file should maintain constant synchronization between index and data (files) during updates for greater resilience. See Resynchronization and resilience for more information. The default is no. (64-bit Windows and UNIX only)
FULLRESILIENT yes|no
(optional) Same as RESILIENT, except that for all writes (STORE, WRITE, or DELETE), the data partition (.is1) data is written directly to disk using the file open flags FILE_FLAG_WRITE_THROUGH on Windows and O_DSYNC on UNIX. FULLRESILIENT will slow down disk access but with improved recoverability. You should benchmark your hardware characteristics and application performance requirements before using FULLRESILIENT instead of RESILIENT.
TEXT “text_string”
(optional) The text to add to the header of a file being created. To specify larger text strings, use multiple TEXT lines, which will be concatenated to represent a single logical line. The total amount of text you can specify is unlimited.
TEXT "Text is concatenated when more than one TEXT line is used " TEXT "so a larger text string can be added. IPAR outputs these " TEXT "quoted strings at 50 bytes."
TEXT_ALLOCATION text_size[K]
(optional) The amount of space to allocate for user-defined text in the file header, in bytes (rounded to the nearest kilobyte) or kilobyte blocks (if you specify the “K”). For example,
1024 allocates text space of 1KB (1024 bytes).
100 allocates text space of 1KB (1024 bytes).
1025 allocates text space of 2KB (2048 bytes).
2K allocates text space of 2KB (2048 bytes).
If TEXT is specified but TEXT_ALLOCATION is not, the default allocation size is either 32 bytes or the size of text_string if the concatenated text_string is larger than 32 bytes.
DENSITY file_density
(optional) The packing density of the index blocks. The minimum value is 50. The maximum value is 100. The default value is usually around 70 but can vary depending on the randomness of the inserted data. The packing density for all keys defaults to this file_density value unless a different density value is specified on individual keys.
RECORD
Indicates the beginning of the record definition. No value should be supplied.
SIZE rec_size
The size of the data records. Consult the Synergy ISAM capacities and limits table for the minimum and maximum possible values. In Synergy .NET and 64-bit traditional Synergy, if you create a file with a variable record type and a maximum record size of 0, the records in that file can exceed 64K and are limited only by the amount of memory you have available or 2 GB.
FORMAT rec_format
(optional) Specifies the format of the records. Possible values are
fixed = The records are of fixed length. (default)
multiple = The records are of multiple fixed length.
variable = The records are of variable length.
COMPRESS_DATA yes|no
(optional) Specifies whether the record data will be compressed. The default is no.
STATIC_RFA yes|no
(optional) Ignored on REV 6 and higher files because it is set automatically. Specifies whether the records have constant RFAs over the life of the specified ISAM file.
STORED_GRFA yes|no
(optional) Specifies whether the CRC-32 part of an RFA is generated and stored to each record header on each STORE or WRITE. The default is no.
PORT_INT pos:len
(optional) The starting position and length of the nonkey integer data within the record. Possible values for len are 1, 2, 4, and 8. The length may not cause the data to overlap any other nonkey integer data sections or keys. You can specify one or more PORT_INT keywords and their assigned values.
KEY n
The key number for a new key definition. The first key number must be 0, and the key numbers that follow must be sequential.
START pos_1[:pos_ n]
The 1-based starting position of the key or each segment of the key (up to eight segments), separated by colons. You must specify a start position for each segment defined.
LENGTH len_1[:len_ n]
The length of the key or each segment of the key (up to eight segments), separated by colons. The key can be up to 254 characters long on Windows and UNIX (251 if the key allows duplicates or 250 if the key allows duplicates and this is a terabyte file), or 255 characters on OpenVMS. You must specify a length for each segment defined.
TYPE type_1[:type_n]
The type of the key or each segment of the key (up to eight segments), separated by colons. If all segments are the same type, only type_1 is required; otherwise, you must specify a type for each segment defined. Possible values are
alpha = Alphanumeric type (default)
integer = Native integer type
decimal = Zoned decimal type
unsigned = Native unsigned integer type
nocase = Case-insensitive alphanumeric type
sequence = Sequence auto type
timestamp = Timestamp auto type
ctimestamp = Ctimestamp auto type
ORDER order_1[:order_n]
(optional) The sorting order of the key data or each segment of the key (up to eight segments), separated by colons. If all segments have the same order, only order_1 is required; otherwise, you must specify an order for each segment defined. Possible values are ascending (default) or descending.
NAME key_name
(optional) The named key of reference for Synergy ISAM. If the name contains spaces, it must be enclosed in quotation marks. The maximum key name length for Synergy ISAM is 15.
DUPLICATES yes|no
(optional) Specifies whether duplicate keys are allowed. The default is no.
DUPLICATE_ORDER dup_ord
(optional) Specifies whether records that contain duplicate keys will appear at the end or at the beginning of a list of matching records. Possible values are
fifo = Newer records appear at the end of the list. (default)
lifo = Newer records appear at the beginning of the list.
MODIFIABLE yes|no
(optional) Specifies whether the key is modifiable. This is not allowed on the primary key. The default is no.
NULL null_type
(optional) Specifies that the key is a null key. In this context, a null key means that when a record is stored and the specified key matches the null key value, no entry is placed in the index, thus saving file space, I/O, and processing. You can specify null keys on alternate keys only, not on a primary key. Possible values are
Specifies that null_val is a single character and must match each byte of the specified key. Numeric key segments always match on 0 (binary 0) for unsigned and integer and “0” (decimal zero) for decimal.
Specifies that null_val is a string that must match the key, from the beginning of the key and for the length of the string. For numeric keys, the string must represent a numeric value.
Specifies that the key won’t be stored if the record does not include the entire key on a STORE or WRITE. The file must be defined to have variable-length records.
VALUE_NULL null_val
(optional) The null value for a null key. The null value can be specified as either a single character or a string. If the null is replicating, the value refers to alpha segments only. Numeric key segments are always defined as their null or zero value and cannot be changed. If the key is specified as a nonreplicating null key, the allowable value depends on the type of the key:
- If the key is alphanumeric, an alpha string must be specified for the null value. If that key is segmented, the length of the alpha string must not cause the value to overlap a numeric segment.
- If the key is numeric and noreplicate was specified, a string that represents a numeric value is specified for the null value. The key may not be segmented. The allowable numeric values depend on the type and length of the key.
DENSITY key_density
(optional) The index packing density for the current key. The minimum value is 50. The maximum value is 100. The default value is similar to the value of 50. This key_density value overrides the file_density value (for this key only) if specified.
SEED start_value
(optional) Sets the starting value for a sequence autokey. Start_value must be positive and non-zero. SEED start_value remains part of the file even after the file is cleared. It's ignored if your file doesn’t have a sequence autokey.
Examples
This sample file below contains a valid XDL description.
FILE
NAME sample
ADDRESSING 48
PAGE_SIZE 4096
NETWORK_ENCRYPT no
TRACK_CHANGES no
FULLRESILIENT yes
KEYS 2
TEXT "APK 3.01"
TEXT_ALLOCATION 1K
RECORD
SIZE 110
FORMAT fixed
COMPRESS_DATA yes
ERASE_ON_DELETE yes
STATIC_RFA yes
PORT_INT 100:4
PORT_INT 104:4
KEY 0
START 1:16
LENGTH 15:4
TYPE alpha:integer
ORDER ascending:descending
NAME "Customer"
DUPLICATES no
MODIFIABLE no
KEY 1
START 31
LENGTH 30
TYPE nocase
NAME "Name"
DUPLICATES yes
DUPLICATE_ORDER fifo
MODIFIABLE no
Here is the same XDL description in a string format appropriate for using in the OPEN statement. Note that the keywords are separated by semicolons:
FILE; NAME sample, ADDRESSING 48; PAGE_SIZE 4096; NETWORK_ENCRYPT no; TRACK_CHANGES no; FULLRESILIENT yes; KEYS 2; TEXT 2; TEXT_ALLOCATION 1K; RECORD; SIZE 110; FORMAT fixed; COMPRESS_DATA yes; STATIC_RFA yes; PORT_INT 100:4; PORT_INT 104:4; KEY 0; START 1:16; LENGTH 15:15; TYPE alpha:integer; ORDER ascending:descending; NAME Customer; DUPLICATES no; MODIFIABLE no; KEY 1; START 31; LENGTH 30; TYPE nocase; NAME Name; DUPLICATES yes; DUPLICATE_ORDER fifo; MODIFIABLE no
Correspondence of XDL keywords to FDL keywords
The following table lists the XDL keywords and their corresponding FDL keywords.
|
XDL keyword |
FDL keyword |
|---|---|
|
FILE |
FILE |
|
NAME filename |
NAME filename |
|
ADDRESSING file_size |
— |
|
PAGE_SIZE page_size |
— |
|
KEYS num_keys |
— |
|
ERASE_ON_DELETE yes|no |
— |
|
FULLRESILIENT yes|no |
— |
|
NETWORK_ENCRYPT yes|no |
— |
|
SIZE_LIMIT max_size |
— |
|
RECORD_LIMIT recs |
— |
|
RESILIENT yes|no |
— |
|
ROLLBACK yes|no |
— |
|
TRACK_CHANGES yes|no |
— |
|
TEXT “text_string” |
— |
|
TEXT_ALLOCATION text_size[K] |
— |
|
DENSITY file_density |
— |
|
RECORD |
RECORD |
|
SIZE rec_size |
SIZE rec_size |
|
FORMAT rec_format |
FORMAT rec_format |
|
COMPRESS_DATA yes|no |
DATA_RECORD_COMPRESSION yes|no |
|
STATIC_RFA yes|no |
— |
|
STORED_GRFA yes|no |
— |
|
PORT_INT pos:len |
— |
|
KEY key_num |
KEY key_num |
|
START pos_1[:pos_n] |
POSITION fdl_pos (unsegmented) or SEG1_POSITION fdl_pos (segmented) where fdl_pos is the starting position of the key or segment. |
|
LENGTH len_1[:len_ n] |
LENGTH fdl_len (unsegmented) or SEG1_LENGTH fdl_len (segmented) where fdl_len is the length of the key or segment. |
|
TYPE ALPHA TYPE ALPHA TYPE INTEGER TYPE INTEGER TYPE UNSIGNED TYPE UNSIGNED (There are no equivalents for the zoned decimal and case-insensitive alphanumeric types or multiple segment types.) |
TYPE STRING TYPE DSTRING TYPE INT2 TYPE DINT2 TYPE BIN2 TYPE DBIN2 |
|
ORDER order_1[:order_n] |
— |
|
NAME key_name |
NAME key_name |
|
DUPLICATES yes|no |
DUPLICATES yes|no |
|
DUPLICATE_ORDER dup_ord |
— |
|
MODIFIABLE yes|no |
CHANGES yes|no |
|
NULL null_type |
NULL_KEY yes|no yes = The key is null. The null type defaults to replicate. no = The key is not a null key. |
|
VALUE_NULL null_val |
NULL_VALUE null_val |
|
DENSITY key_density |
INDEX_FILL key_density |
| SEED start_value | — |
