ISAM definition language

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:

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

32-bit signed file address for a maximum individual file size of 2Gb. (default)

40 or 48

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.

NO40 or NO48

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.

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.

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.

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

replicate

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.

noreplicate

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.

short

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:

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
    KEYS            2
    TEXT            "APK 3.01"
    TEXT_ALLOCATION 1K
RECORD
    SIZE            110
    FORMAT          fixed
    COMPRESS_DATA   yes
    ERASE_ON_DELETE yes
    FULLRESILIENT   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

NETWORK_ENCRYPT yes|no

SIZE_LIMIT max_size

RECORD_LIMIT recs

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

RESILIENT yes|no

FULLRESILIENT 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)
SEGn_POSITION fdl_pos

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)
SEGn_LENGTH fdl_len

where fdl_len is the length of the key or segment.

TYPE ALPHA
ORDER ASCENDING

TYPE ALPHA
ORDER DESCENDING

TYPE INTEGER
ORDER ASCENDING
LENGTH 2
LENGTH 4
LENGTH 8

TYPE INTEGER
ORDER DESCENDING
LENGTH 2
LENGTH 4
LENGTH 8

TYPE UNSIGNED
ORDER ASCENDING
LENGTH 2
LENGTH 4
LENGTH 8

TYPE UNSIGNED
ORDER DESCENDING
LENGTH 2
LENGTH 4
LENGTH 8

(There are no equivalents for the zoned decimal and case-insensitive alphanumeric types or multiple segment types.)

TYPE STRING

TYPE DSTRING



TYPE INT2
TYPE INT4
TYPE INT8



TYPE DINT2
TYPE DINT4
TYPE DINT8



TYPE BIN2
TYPE BIN4
TYPE BIN8



TYPE DBIN2
TYPE DBIN4
TYPE DBIN8

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