ISAMC

Create an ISAM file

WTSupported in traditional Synergy on Windows
WNSupported in Synergy .NET on Windows
USupported on UNIX
VSupported on OpenVMS
xcall ISAMC(file_spec, rec_size, num_keys, key_spec[, …])

Arguments

file_spec

The specification for the ISAM file you want to create and any additional options. The format for a file specification is described in the Discussion below. (a)

rec_size

The maximum size of the data records. The minimum record size is 4 (5 for terabyte files). (n)

num_keys

The number of keys in the ISAM file. You can specify between 1 and 255 keys. (n)

key_spec

One of the following: (a)

The format for a key specification is described in the Discussion below.

Discussion

The ISAMC subroutine creates an ISAM file. You can use the ISAMC subroutine to create any type of Synergy DBL–supported ISAM file: Synergy ISAM or RMS ISAM.

ISAMC tries to gain exclusive access to the specified file. If the file is currently in use, the ISAMC request is rejected with a “File in use by another user” error ($ERR_FINUSE).

Note

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.

File specification

filename[, record_type][, COMPRESS][, DENSITY=file_density][, I=pos:len[, …]]
&     [, ERASE_ON_DELETE][, NETWORK_ENCRYPT][, PAGE=page_size]
&     [, ROLLBACK|NOROLLBACK][, SGRFA][, SIZE_LIMIT=max_size]
&     [, RECORD_LIMIT=recs][, STATIC_RFA][, TBYTE|NOTBYTE][, TEXT=text_spec]
&     [, TRACK_CHANGES]

filename

The name of the ISAM file you want to create. The default extension is .ism. (a)

Tip

To make your code more portable, we recommend you do not use a file extension on the name of the ISAM file if you might sometime use a different ISAM file structure on another operating system, since some file structures require a specific extension.

record_type

(optional) One of the following types of ISAM files:

FIXED = Fixed‑length records. (default)

MULTIPLE = Multiple fixed‑length records.

VARIABLE = Variable‑length records.

COMPRESS

(optional) The record data will be compressed. You cannot specify this option with a record type of MULTIPLE.

DENSITY=file_density

A number between 50 and 100 that represents the default density percentage for each key in the file, which is the percentage each index block is filled. (See ISAM index density for more information and suggestions about setting the file density.)

I=pos:len

(optional) Defines a portable integer, where pos is the starting position of nonkey integer data (the first position of the record is 1) and len is the length of nonkey integer data (valid values are 1, 2, 4, 8). You can specify this option more than once to define up to 255 portable integers per file.

ERASE_ON_DELETE

(optional) Indicates that when a record is deleted, it will be erased (i.e., nulled out). If ERASE_ON_DELETE is not specified, records that are deleted are marked deleted, but their contents remain in the file until the space is physically reused. ERASE_ON_DELETE cannot be used if TRACK_CHANGES is set. (Windows and UNIX only)

NETWORK_ENCRYPT

(optional) Sets the network enycryption flag on the new file, which ensures that any client accessing that file must use encryption. (See Specifying the data to encrypt for slave encryption for more information.) (Windows and UNIX only)

PAGE=page_size

(optional) Specifies the size of each index block in the ISAM file. Valid values are 512, 1024, 2048, 4096, 8192, 16384, 32768. The default is 4096. (See Page size for more details and suggestions about setting the page size.) (Windows and UNIX only)

ROLLBACK | NOROLLBACK

(optional) Control the rollback function. ROLLBACK (default) allows it, and NOROLLBACK prohibits it. (Windows and UNIX only)

SGRFA

(optional) Generate and store the CRC‑32 part of an RFA to each record header on each STORE or WRITE. (Windows and UNIX only)

SIZE_LIMIT=max_size

(optional) Specifies the maximum number of megabytes the .is1 file is allowed to reach. If a STORE or WRITE operation exceeds this limit, an “File size limit exceeded” error (SIZLIMIT) occurs. (Windows and UNIX only)

RECORD_LIMIT=recs

(optional) Indicates the maximum number of records allowed in the .is1 file. If a STORE operation exceeds this limit, a “File record limit exceeded” error (RECLIMIT) occurs. (Windows and UNIX only)

STATIC_RFA

(optional) Ignored on REV 6 and higher files because it is set automatically. The records will have constant RFAs over the life of the specified ISAM file if RFAs are to be used on this file. (Windows and UNIX only)

TBYTE | NOTBYTE

(optional) TBYTE creates a file capable of holding 256 terabytes of data or index. NOTBYTE prohibits an implicit TBYTE setting. (Windows and UNIX only)

TEXT=text_spec

(optional) Adds the specified text allocation size and/or text string to the header of the file being created and/or allocates space for user‑defined text. See Specifying user‑defined text in the file data header for detailed syntax. (Windows and UNIX only)

TRACK_CHANGES

(optional) Enable change tracking. Requires a REV 6 or greater file (which is the default for ISAM files being created, unless it’s overridden by ISAMC_REV). Specifying TRACK_CHANGES also enables TBYTE automatically (unless NOTBYTE is specified). (Windows and UNIX only)

On Windows, terabyte files are only supported on Windows systems with the NTFS file system. They are not supported on FAT or FAT32 file systems.

On UNIX, some systems require you to set a large‑file option on the file system being used. Some (AIX in particular) require this to be done when the file system is first created, and others allow the option to be added later.

On OpenVMS, the I and STATIC_RFA options cause an “Invalid option” error ($ERR_INVOPT). OpenVMS files operate as if STATIC_RFA was specified.

If the specified file already exists, the ISAMC subroutine replaces it by default. To change this default, set the FLAGS subroutine’s flag 3. If flag 3 is set and ISAMC attempts to create a file that already exists, a “Cannot supersede existing file” error ($ERR_REPLAC) is generated.

You can abbreviate all file options for the ISAMC subroutine. However, for program clarity and to eliminate confusion with options that may be added in the future, we recommend that you specify the full option name.

Specifying user‑defined text in the file data header

The TEXT option in the file specification enables you to specify a section of text in the ISAM file header during file creation that can later be retrieved programmatically. For example, you can tag the file with an application version number, which you could then compare to a text string stored within the Repository for the corresponding structure or file. You could thus determine whether the Repository and data file were out of sync, and process accordingly.

The value of the TEXT option can be the size allocated for the text and/or the text string itself. Text_spec has one of the following formats:

text_size[K]

(optional) The amount of space to allocate for the text, in bytes (rounded to the nearest kilobyte) or kilobyte blocks (if you specify the “K”). The text contents are initialized to empty. For example,

TEXT=1024 allocates text space of 1KB (1024 bytes).

TEXT=100 allocates text space of 1KB (1024 bytes).

TEXT=1025 allocates text space of 2KB (2048 bytes).

TEXT=2K allocates text space of 2KB (2048 bytes).

“text_string”

The text string to add to the file header. The allocated space is the size of text_string or a minimum of 32 bytes. The size of the filename and all file options in ISAMC is 512 + 1024 bytes on Windows and 255 + 1024 bytes on UNIX, so for larger amounts of text, use an XDL file. For example,

TEXT=“APK 3.01” allocates text space of 32 bytes and loads the text “APK 3.01”.

text_size[K]:“text_string”

The amount of space to allocate for the text, in bytes (rounded to the nearest kilobyte) or kilobyte blocks (if you specify the “K”), and the text string to load at the beginning of the file text space. For example,

TEXT=1K:“APK 3.01” allocates text space of 1KB (1024 bytes) and loads the text “APK 3.01”.

Key specification

If key_spec is a single key specification or a dimensioned argument, the number of key_spec arguments or dimensions should be equal to or greater than the number specified by num_keys. A key specification in key_spec should have the following form:

START=pos_1[:pos_n], LENGTH=len_1[:len_n][, NAME=key_name]
&     [, TYPE=key_type_1[:key_type_n]][, ORDER=key_order_1[:key_order_n]]
&     [, DENSITY=key_density][, DUPS|NODUPS][, MODIFY|NOMODIFY][, ASCEND|NOASCEND]
&     [, ATEND|NOATEND][, COMPRESS[=compression]][, NULL=null_type
&     [, VALUE_NULL=null_val]]

START=pos_1[:pos_n]

The starting position of the key or each segment of the key, starting with the first. You can specify up to eight positions, separated by colons.

LENGTH=len_1[:len_n]

The length of the key or each segment of the key. You can specify up to eight lengths, separated by colons. The number of segment lengths must equal the number of start positions. The key (all segments combined) 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.

NAME=key_name

(optional) The named key of reference for Synergy ISAM access. If the name contains spaces, the key name must be enclosed in quotation marks. The maximum key name length is 15 for Synergy ISAM. RMS ISAM has no maximum length, but ISAMC only accepts a maximum of 32 characters.

TYPE=key_type_1[:key_type_n]

(optional) The type of key or segment. You can define one type for the key and all of its segments, or you can define a type for each segment. If you define the segments individually, you must include a type for every segment. See Key type for detailed information about each type.

ALPHA

Alphanumeric key (default)

NOCASE

Case‑insensitive alphanumeric key

DECIMAL

Zoned decimal key

INTEGER

Native integer key

UNSIGNED

Native unsigned integer key

SEQUENCE

Automatically incremented i8 key

TIMESTAMP

i8 time key automatically generated on every record update

CTIMESTAMP

i8 time key automatically generated on a record’s initial STORE

Important

On Windows and UNIX, using integer keys (INTEGER, UNSIGNED, SEQUENCE, TIMESTAMP, and CTIMESTAMP key types) in an ISAM file requires special handling when unloading and loading is performed. Due to the chance that one of these keys contains data that could be interpreted as a record terminator, unloading to a sequential (or text) file is not recommended. Instead, we recommend using the fconvert utility to generate a counted file (‑oc). (See fconvert for more information and further restrictions on text files.)

On OpenVMS, RMS supports alpha keys, unsigned integer keys (i1, i2, i4, and i8), and signed integer keys (i2, i4, and i8).

ORDER=key_order_1[:key_order_n]

(optional) Defines the order of the key or the order of each key segment: DESCENDING (or D) or ASCENDING (or A).

You can define one key order for the key and all of its segments, or you can define a key order for each segment. If you define the segments individually, you must include a key order for every segment.

This value overrides the ASCEND | NOASCEND option.

On OpenVMS, the ORDER option is ignored. RMS does not support key segments of varied order. Use the ASCEND | NOASCEND option to specify the key order instead.

DENSITY=key_density

(optional) Specifes a number between 50 and 100 that represents the density percentage for that key. (See Key density for more information and suggestions about setting the key density.) This value overrides the file density for each key for which it is specified.

DUPS | NODUPS

(optional) Specifies whether duplicate keys are allowed. The default is no duplicates (NODUPS).

MODIFY | NOMODIFY

(optional) Specifies whether the key is modifiable. The default is not modifiable (NOMODIFY). The primary key cannot be modified.

ASCEND | NOASCEND

(optional) Specifies whether the key data will be sorted in ascending or descending order. The default is ascending order (ASCEND). This option is overridden by the ORDER option if it is specified.

ATEND | NOATEND

(optional) Specifies whether records that contain duplicate keys will appear at the end or at the beginning of a list of matching records. The default is at the end (ATEND).

On OpenVMS, records that contain duplicate keys are always inserted at the end of a list of matching records, which means that the ATEND option is ignored. If you specify NOATEND on RMS ISAM, an “Invalid option” error ($ERR_INVOPT) is generated.

COMPRESS=compression

(optional) Specifies that the RMS ISAM key will be compressed. This key COMPRESS option differs from the data COMPRESS option in File specification. The default option is ALL. (OpenVMS only)

You can specify the following options:

INDEX | NOINDEX

Compresses the index. The default is INDEX.

KEY | NOKEY

Compresses the key within the data. The default is KEY.

RECORD | NORECORD

Compresses the record within the data. The default is RECORD.

ALL

Compresses all of the applicable options above.

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 this key has a null value, no entry is placed in the index, thus saving file space, I/O, and processing. By default, a key is assumed to be null if it is filled with spaces. You can change this assumption using the VALUE_NULL option. The default null value is blank for alpha keys and 0 for numeric keys. You can specify null keys on alternate keys only, not on a primary key.

Null_type can be one of the following types on all operating systems except OpenVMS, where the null_type argument is optional and may only ne REPLICATE if specified. See Null keys for more information.

REPLICATE

Specifies that null_val is a single character and must match each byte of the specified key.

NOREPLICATE

If the key is alpha, specifies that null_val is a string that must match the key, from the beginning of the key, for the length of the string. If the key is numeric, specifies that null_val must match the numeric key value.

SHORT

Specifies that the key won’t be stored if the record doesn’t include the entire key on a STORE or WRITE. The file must have variable‑length records.

VALUE_NULL=null_val

(optional) Indicates the null value for a null key, which can be specified as either a single character or a string. The default null value is a space. Enclosing the value in quotation marks is optional. For example:

"chr"       :       "0", " ", "\0"          ASCII representation
val         :       48,   32,   0           Binary representation
string      :       abc, "abc"              Nonreplicating string
numeric     :       100, "100"              Nonreplicating numeric string

On OpenVMS, null keys are only allowed on alpha keys and null_val can only specify a single character. When every byte of the key matches this character, the key is considered to be null, and no index entry is created. If a string is specified as null_val, the first character of the string is considered to be the null value character.

If conflicting qualifiers and settings are specified, the last one takes precedence.

If you use ^VARARGARRAY, note that key_spec is the last declared argument for this routine.

See also

Examples

The example below creates a compressed ISAM file named cusmas.ism with variable‑length records that have a maximum record size of 2000. It specifies the following four keys:

keyspec1="start=1:16, len=15:15, name=name"
keyspec2="start=31, len=30, name=company, dups, noascend"
keyspec3="start=61:81:91, len=20:10:10, name=address, dups, modify,
  &      atend"
keyspec4="start=101, len=5, name=""acct code"", dups, null=replicate,
  &      value_null=32"

xcall isamc("cusmas, variable, compress", 2000, 4, keyspec1, keyspec2, 
  &   keyspec3, keyspec4)

The example below creates an ISAM file named temp.ism that has a record size of 20. It has one key that starts at position 1 and is five characters long. This file is compressed and allows variable‑length records. (This example illustrates how you can abbreviate all file options for the ISAMC subroutine.)

xcall isamc("temp, c, v", 20, 1, "start=1, len=5")

The example below shows key_spec as a dimensioned argument.

record
    keyspecs    ,[3]a25         ,"start=1, length=5, dups"
  &                             ,"start=10, length=5, dups"
  &                             ,"start=20, length=5, dups"
    .
    .
    .
    xcall isamc("file1", 128, 3, keyspecs)