|
WSupported on Windows
|
USupported on Unix
|
VSupported on OpenVMS
|
NSupported in Synergy .NET
|
xcall ISAMC(file_spec, rec_size, num_keys, key_spec[, ...])
Arguments
The specification for the ISAM file you want to create and any additional options. (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)
One of the following: (a)
- A variable that contains a single key specification. You must include a key_spec for each key in the ISAM file.
- A dimensioned argument of at least num_keys elements defining each key being created.
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).
|
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. |
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][, RESILIENT][, FULLRESILIENT]
filename
The name of the ISAM file you want to create. The default extension is .ism. (a)
|
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. (Windows and Unix only)
VARIABLE = Variable-length records.
COMPRESS
(optional) Causes the record data to 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 over a network must use encryption. (See Using client/server encryption for more information on encryption.) (Windows and Unix only)
|
|
The network encryption flag applies to all remote access from a Synergy application—not just xfServer access. This means that attempting to access the file via a network path specification (e.g., a mapped drive on Windows) will generate the error $ERR_NETCRYPT. There is no prohibition to accessing the file locally. |
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) Controls the rollback function. ROLLBACK (default) allows it, and NOROLLBACK prohibits it. (Windows and Unix only)
SGRFA
(optional) Generates and stores 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) Enables change tracking. Specifying TRACK_CHANGES also enables TBYTE automatically (unless NOTBYTE is specified). (Windows and Unix only)
(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. (64-bit Windows and Unix only)
FULLRESILIENT
(optional) Same as RESILIENT, except that for all writes (STORE, WRITE, or DELETE), data is written directly to disk using the file open flags FILE_FLAG_WRITE_THROUGH on Windows and O_DSYNC on Unix.
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 (INVOPT). OpenVMS files operate as if STATIC_RFA was specified.
|
|
For better performance on OpenVMS, instead of creating files with ISAMC, you should use the OpenVMS FDL editor and open files in O:I mode with the FDL qualifier. |
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.
|
|
The following file options require a REV 6 or greater file (which is the default for ISAM files being created, unless it’s overridden by ISAMC_REV): ERASE_ON_DELETE SEED SGRFA SIZE_LIMIT TEXT TRACK_CHANGES RECORD_LIMIT ROLLBACK | NOROLLBACK RESILIENT | FULLRESILIENT |
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.
Alphanumeric key (default)
Case-insensitive alphanumeric key
Zoned decimal key
Native integer key
Native unsigned integer key
Automatically incremented i8 key
i8 time key automatically generated on every record update
i8 time key automatically generated on a record’s initial STORE
|
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 (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:
Compresses the index. The default is INDEX.
Compresses the key within the data. The default is KEY.
Compresses the record within the data. The default is RECORD.
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 be REPLICATE if specified. See Null keys for more information.
Specifies that null_val is a single character and must match each byte of the specified key.
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.
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.
|
|
The following TYPE options require a REV 6 or greater file: TIMESTAMP SEQUENCE CTIMESTAMP |
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
- Synergy DBMS
- Your RMS ISAM documentation
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:
- The primary key is named “name” and has two segments, which start at positions 1 and 16. The length of each segment is 15. This key does not allow duplicates, and it is not modifiable. Data for this key is sorted in descending order.
- The first alternate key is named “company” and has one segment, which starts at position 31 and is 30 characters long. This key allows duplicates, and it is not modifiable. Key data is sorted in descending order, and records that contain duplicates appear at the beginning of a list of matching records.
- The second alternate key is named “address” and has three segments, which start at positions 61, 81, and 91. The length of the first segment is 20, and the length of the second and third segments is 10. This key allows duplicates, and it is modifiable. Key data is sorted in ascending order, and records that contain duplicates appear at the end of a list of matching records.
- The third alternate key is named “acct code” and has one segment, which starts at position 101 and is five characters long. (Note that the key name contains a space and therefore must be quoted. Remember that two quotation marks in a string place one quotation mark in the string.) This key allows duplicates, and it is not modifiable. Key data is sorted in ascending order, and records that contain duplicates appear at the beginning of a list of matching records. This key is also a replicate null key with a null value of 32. When all five bytes of this key are blank, no key entry will exist for that record in the index. We could easily have left out the value_null spec and accomplished the same result.
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)
