bldism

Create an ISAM file

WTSupported in traditional Synergy on Windows
WNSupported in Synergy .NET on Windows
USupported on UNIX
VSupported on OpenVMS

The bldism utility enables you to create an ISAM file from outside your programs. It prompts you to specify the name and type of ISAM file you want to create, and to define the length and key structure of its records.

To run bldism,

On

Enter this at the command line

Windows and UNIX

dbr DBLDIR:bldism [-k filename]

OpenVMS

run DBLDIR:bldism

Or, if you want to specify the -k option, set bldism up as a foreign command and start it from a symbol:

$ bldism:==$DBLDIR:bldism
$ bldism -k filename

-k filename

(optional) Specifies that bldism should not prompt for input but should instead create an ISAM file according to the XDL or FDL description in the specified file. Filename must be a specification for a file that contains a valid XDL or FDL description.

To find out what the valid input is at any prompt, enter a question mark character (?). To terminate bldism at any time, type the end-of-file character for your operating system.

Tip

On OpenVMS, generating an FDL with the “EDIT/FDL” system command optimizes files.

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.

Sample bldism

Enter name of the ISAM file to create: cusmas, v, c
What is the length of data records? (1-65534) 2000 
How many different keys? (1-255) 5 Primary key:
        Enter name of the Key field: name/segment/type/order 
        How many different segments? (1-8) 2 
                What type is segment #1? (A, D, I, U, or N [/ALL]) A/ALL 
                How long is segment #1? (1-99) 15 
                Where does segment #1 start? (1-1986) 16 
                Segment order to be ascending or descending? (A/D) D 
                How long is segment #2? (1-85) 15 
                Where does segment #2 start? (1-1986) 1 
                Segment order to be ascending or descending? (A/D) D 
        Are duplicate keys to be permitted? (Y/N) N 
1st alternate:
        Enter name of the Key field: company/type/density 
        What type is the key? (A/D/I/U/N/S/T/C) A 
        How long is the key? (1-255) 30 
        Where does the key start? (1-1971) 31 
        Are duplicate keys to be permitted? (Y/N) Y 
                Insert duplicates at front? (Y/N) Y 
        Key order to be ascending or descending? (A/D) A 
        What is the key packing density? (50-100) 75 
2nd alternate:
        Enter name of the Key field: address/segment/modify/density 
        How many different segments? (1-8) 3 
                How long is segment #1? (1-98) 20 
                Where does segment #1 start? (1-1981) 61 
                How long is segment #2? (1-79) 10 
                Where does segment #2 start? (1-1991) 51 
                How long is segment #3? (1-70) 10 
                Where does segment #3 start? (1-1991) 91 
        Are duplicate keys to be permitted? (Y/N) Y 
                Insert duplicates at front? (Y/N) N 
        Key order to be ascending or descending? (A/D) A 
        What is the key packing density? (50-100) 70 
3rd alternate:
        Enter name of the Key field: act_code/null 
        Replicating, Non-replicating, or Short null key? (R/N/S) R 
        Null value: 32 
        How long is the key? (1-255) 5 
        Where does the key start? (1-1986) 101 
        Are duplicate keys to be permitted? (Y/N) Y 
                Insert duplicates at front? (Y/N) Y 
        Key order to be ascending or descending? (A/D) A 
4th alternate:
        Enter name of the Key field: cust_number/density/type 
        What type is the key? (A/D/I/U/N/S/T/C) D 
        How long is the key? (1-255) 10 
        Where does the key start? (1-1986) 120 
        Are duplicate keys to be permitted? (Y/N) N 
        Key order to be ascending or descending? (A/D) A 
        What is the key packing density? (50-100) 90 
ISAM file successfully initialized

Running the bldism utility

To illustrate how to use bldism to create an ISAM file, let’s assume we want to create an ISAM file that stores customer information, such as customer name, company, and address. The bldism utility prompts us as follows for the information needed to create our ISAM file. (The example to which we refer throughout this section is found in Sample bldism.)

File prompts

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|NOTYBTE][, TEXT=text_spec][, TRACK_CHANGES][, RESILIENT]
[, FULLRESILIENT][, SEED=start_value]

filename

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

record_type

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

fixed = Fixed-length records (default)

multiple = Multiple fixed-length records (up to 32 record lengths per file)

variable = Variable-length records

COMPRESS

(optional) Compresses the data of the specified ISAM file. You cannot specify this option with a record type of multiple.

DENSITY=file_density

(optional) 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 encryption flag on the new file, which ensures that any client accessing that file must use encryption. See Using client/server encryption for more information about encryption. (Windows and UNIX only)

Note

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 information and page size 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 “Output file is full” error (FILFUL) occurs. (Windows and UNIX only)

RECORD_LIMIT=rec

(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. Ensures that a record retains the same RFA across WRITE operations. Static RFA files aren’t fully self-reorganizing. (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. (Windows and UNIX only)

TRACK_CHANGES

(optional) Enable change tracking. Requires a REV 6 or greater file. Specifying TRACK_CHANGES also enables TBYTE automatically (unless NOTBYTE is specified). You cannot specify this option with a record type of multiple. (Windows and UNIX only)

RESILIENT

(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.

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.

Note

You can abbreviate any of the above options. However, to eliminate confusion with future additions of options and for program clarity, you can also specify the full option name. See ISAM file types for a discussion about the different ISAM file types. Also see Static RFAs for more information about static RFAs and data compression.

Note

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

In our example, we entered

cusmas, v, c

at this prompt to create an ISAM file named cusmas.ism that has variable-length records and compressed data.

In our example, we entered 2000 at this prompt; therefore, the maximum size of any data record within our ISAM file, cusmas.ism, is 2000 characters long.

In our example, we entered 4 at this prompt to specify four keys for our cusmas.ism file.

Key prompts

[key_name][/SEGMENT][/MODIFY][/NULL][/TYPE][/ORDER][/DENSITY]

key_name

(optional) An alpha expression that represents the name of the key and is used in key-of-reference specifications. The maximum key name length, including quotes, is 15 for Synergy ISAM. (RMS ISAM has no maximum length, but because the ISAMC subroutine accepts a maximum of 32 characters, your key name shouldn’t be any longer than 32 characters.)

/SEGMENT

(optional) Specifies that the key is segmented.

/MODIFY

(optional) Specifies that the key field is modifiable.

/NULL

(optional) Specifies that the key is a null key.

/TYPE

(optional) Indicates that you want to define a specific key type for each segment or for all segments.

/ORDER

(optional) Indicates that you want to define a specific key order for each segment. To assign the same order to all segments, don’t specify this option as part of the key specification; bldism prompts for the key order at the end of the key definition.

/DENSITY

(optional) Indicates that you want to define a specific density for this key.

You can abbreviate any of the above options; for example, /S for /SEGMENT, /M for /MODIFY, and /N for /NULL.

Note

You can’t specify the /MODIFY or /NULL options on the primary key. See Keys in ISAM files for more details about segmented, modifiable, and null keys.

In our example, we entered

name/segment/type/order

at this prompt to specify a segmented primary key called name.

In our example, this prompt does not appear, because our primary key is not a null key.

In our example, this prompt does not appear, because our primary key is not a null key.

In our example, we entered 2 at this prompt to assign two segments to the primary key, name.

In our example, we entered A/ALL at this prompt to specify that the type for both segments of our primary key is alpha.

In our example, we entered 15 at this prompt to specify that the length of the first segment of our primary key is 15 characters long.

This prompt is repeated for each segment assigned to this key. If this is not a segmented key, however, the following prompt appears:

How long is the key? (1-nnn)

to which you should respond with the length of the key field. Again, the length must not be greater than nnn. (See the note above.)

In our example, we entered 16 at this prompt to specify that the first segment of our primary key starts at position 16.

This prompt is repeated for each segment assigned to this key. If this is not a segmented key, however, the following prompt appears:

Where does the key start? (1-nnn)

to which you should respond with the starting character position of the key field. Again, the starting position must not be larger than nnn.

In our example, we entered D at this prompt to specify that the first segment of our primary key should be sorted in descending order.

See Ascending or descending keys for more information.

In our example, we entered N at this prompt to specify that the primary key should not allow duplicate keys.

See Duplicate keys for more information about duplicate keys.

In our example, this prompt does not appear, because we did not allow duplicate keys for this field.

On OpenVMS, you must answer N at this prompt; OpenVMS only allows duplicates to be inserted at the end of a list of matching records.

In our example, this prompt does not appear, because we specified /ORDER in the key specification and we were therefore prompted for the order of each segment individually.

See Ascending or descending keys for more information about ascending and descending keys.

In our example, this prompt does not appear, because we did not specify /DENSITY in the specification for the primary key.

In our example, bldism prompted us to name and define four key fields (the primary key and three alternate keys) because we specified four keys for our cusmas.ism file.