bldism

Create an ISAM file

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,

dbr DBLDIR:bldism [-k filename]

run DBLDIR:bldism

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

Options

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

Discussion

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.

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

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

• Enter name of the ISAM file to create: Enter the name of the ISAM file you want to create as follows:

            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)

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.

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.

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.

• What is the length of data records? (1 - 65534) Enter the expected maximum size of any data record (up to 65,534 characters long on Windows and Unix or 32,234 characters on OpenVMS). The minimum record size is 4. To determine the record size, remember to include the key field, but don’t include space for record terminators; no record terminators are stored as part of an ISAM file.

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.

• How many different keys? (1 - 255) Enter the number of keys you want to specify (up to 255 keys). A separate index is created for each key, thereby enabling keyed access to records using any one of the keys. Updating an ISAM file, however, modifies each key index. Remember that for each key you specify, you increase update processing time and increase disk space usage.

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

Key prompts

• Primary key:
  Enter name of the Key field: Enter a name for the primary key field of the specified ISAM file, as follows:

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

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.

• Replicating, Non-replicating, or Short null key? (R/N/S) If you specified /NULL at the previous prompt, enter R if you want the key to be a replicating null key, N if you want it to be a nonreplicating null key, or S if you want it to be a short null key. If the key is not a null key, this prompt doesn’t appear.

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

• Null value: Enter the value of the null key. If you specified a replicating null key, enter a value representing a single character. If you specified a nonreplicating null key, enter a string as the null value. If you specified a short null key or if this key is not a null key, this prompt doesn’t appear.

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

• How many different segments? (1-8) Enter the number of segments you want assigned to this key. You can specify up to eight segments. If this is not a segmented key, this prompt doesn’t appear.

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

• What type is segment #1? (A, D, I, U, or N[/ALL]) This prompt is displayed if you specified /TYPE at the “Enter name of the Key field” prompt. Enter A for alpha, D for decimal, I for integer, U for unsigned integer, or N for case-insensitive alpha. If you want to define the rest of the segments as having the same type as the first without being prompted again, type /ALL immediately following the A, D, I, U, or N.

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

• How long is segment #1? (1-nnn) Enter the length of the first segment. The value nnn is displayed as 255 or as the difference between 255 and the previously defined record length, whichever is smaller. The length of the segment must not be greater than nnn.

  An overall key length of 255 is only valid for OpenVMS files. A warning is displayed if the overall key length exceeds 254 characters when bldism is run on a Windows or Unix machine. An error is generated at creation time if the destination of a file being created with a key that exceeds 254 characters is Windows or Unix. (The term overall key length refers to the combined segment length if the key is segmented or the length of the key if the key is not segmented, plus 3 bytes on Windows or Unix if the key allows duplicates, or 4 bytes for terabyte files.)

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

• Where does segment #1 start? (1-nnn) Enter the starting character position of the segment. The value nnn is calculated from the defined record and segment lengths. The starting position must not be larger than nnn.

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.

• Segment order to be ascending or descending? (A/D) This prompt is displayed if you specified /ORDER at the “Enter name of the Key field” prompt. Enter A to force the segment into an ascending order or D to force it into a descending order. If you enter A, the READS statement sequentially retrieves records starting with the lowest segment value and progressing to the highest segment value. If you enter D, READS retrieves records from the highest to the lowest segment values. Note that the order of segment values is based on the eight-bit ASCII collating sequence.

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.

• Are duplicate keys to be permitted? (Y/N) Enter Y if you expect the file to contain multiple records having the same key value. Enter N to ensure that no two records will ever have the same key value. If you enter N, the STORE statement signals a “Duplicate key specified” error ($ERR_NODUPS) each time you attempt to store a record having a key value that is already present in the file.

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.

• Insert duplicates at front? (Y/N) This prompt appears only if you are allowing duplicate keys for this key field. Enter Y if you want to insert duplicate keys at the front of records possessing the same key value. Enter N if you want to insert duplicates at the end of such records. If you enter Y, duplicate records are retrieved in last-in-first-out (LIFO) order. If you enter N, duplicate records are retrieved in first-in-first-out (FIFO) order.

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.

• Key order to be ascending or descending? (A/D) Enter A to force keys into an ascending order or D to force them into a descending order.

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.

• What is the key packing density? (50-100) This prompt is displayed if you specified /DENSITY at the “Enter name of the Key field” prompt. Enter a value between 50 and 100 to specify the density percentage for this key.

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

• 1st - 255th alternates: The bldism utility repeats the preceding key prompts for as many keys as you specified for the ISAM file you want to create.

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.