isload

Load, unload, or clear an ISAM file

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

The isload utility enables you to load or unload ISAM or relative files or to clear ISAM files from outside your programs. It is primarily used to load ISAM files from text to sequential files.

Important

Whenever possible, isload opens the ISAM file exclusively. Because this support may not be available on all operating systems, please use isload with caution.

To run isload,

On

Enter this at the command line

Windows and UNIX

dbr DBLDIR:isload

OpenVMS

run DBLDIR:isload

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

Tip

On Windows and UNIX we suggest using the fconvert utility (see fconvert) for much faster operation of loading and unloading files.

On OpenVMS we suggest using the system command CONVERT/FDL for much faster operation of loading and optimizing files.

Sample isload

Option: unload

Enter name of ISAM file to be UNLOADed: cusmas,key=1

Record length:  2000

Number of keys  4

Enter name of sequential file into which to UNLOAD: secust

What progress reporting interval? 25

—> Begin unloading ISAM to sequential (at 14:14:43)

at 14:14:43

at 14:14:43

at 14:14:43

at 14:14:43

25 in

50 in

75 in

100 in

25 out

50 out

75 out

100 out

0 errors

0 errors

0 errors

0 errors

… End of input file test

—> Finish unloading ISAM to sequential (at 14:14:43, took 0 seconds)

Records input: 100 Records output: 100 Errors detected: 0

… normal termination of ISLOAD

Running the isload utility

To illustrate how you use isload to unload a file, let’s assume we want to unload our ISAM file, cusmas.ism. The isload utility prompts us as follows for the information needed to unload our ISAM file. (The example to which we refer throughout this section is found in Sample isload.)

UNLOAD

Unloads the specified file to a sequential file without modifying the file.

LOAD

Loads the specified file by adding new records to the existing records.

CLEAR

Clears the specified ISAM file and restores it to its original empty state.

STOP

Terminates the isload utility.

Note

The file you want to unload, load, or clear must already have been created using either bldism or the ISAMC subroutine. You can abbreviate any of the above options; for example, U for UNLOAD or L for LOAD.

In our example, we entered the UNLOAD option to unload our ISAM file, cusmas.ism.

Important

Use CLEAR with extreme caution; clearing an ISAM file deletes all existing records.

Enter the specification for the ISAM file you want to unload, load, or clear as follows:

file_spec[, RELATIVE][, KEY=keynum]

file_spec

The specification for the file you want to load, unload, or clear. The default extension is .ism. File_spec can be up to 100 characters long.

RELATIVE

(optional) Indicates that the file to load or unload is a relative file. You can abbreviate this option to any number of characters (for example, R or REL).

Note

The RELATIVE specification is valid for LOAD or UNLOAD operations only.

keynum

(optional) The number of the alternate key by which you want to unload the specified ISAM file. By default, the file is unloaded in primary key order. Specifying the KEY=keynum option enables you to unload a file by an alternate key.

Note

The KEY=keynum option is valid for UNLOAD operations only.

In our example, we entered the filename cusmas,key=1 to unload our ISAM file by the first alternate key. The isload utility then displayed a record length of 2000 and 4 keys for our ISAM file, cusmas.ism.

After you enter a filename and press enter, the isload utility displays the maximum length of records and the number of keys for the specified file. If you selected the clear option, the isload utility now clears the specified ISAM file and terminates. If you selected the unload or load option, isload displays the next prompt.

Enter the name of the sequential file into which you want to write records during the unload operation or from which you want to read records during the load operation. The file specification and corresponding qualifier list can be up to 100 characters long, as follows:

file_spec[, FIXED|COUNTED][, NOLOCK]

file_spec

The specification for the sequential file into which you want to unload records or from which you want to load records. The default extension is .ddf. (TT: is recognized as the terminal.) File_spec can be up to 100 characters long, including any of the optional qualifiers listed below.

FIXED

(optional) Specifies that the sequential file will contain fixed‑length records of the maximum length specified at creation.

COUNTED

(optional) Specifies that the sequential file will contain variable‑length records. A counted file is used and recognized only by isload and fconvert for the purpose of loading and unloading ISAM files. (COUNTED is not available for files created with record sizes greater than 64K.)

NOLOCK

(optional) Specifies that record locking will not occur. NOLOCK can only be used when a file is being loaded; it is not valid with the UNLOAD option.

Note

By default, the file is loaded from or unloaded to a sequential file. Because ISAM files allow binary data, however, record terminators and end‑of‑file characters can be embedded in records. Therefore, for ISAM files containing records that have binary data or integer fields, use the optional FIXED or COUNTED options in the sequential filename specification. (When ­isload unloads to a counted sequential file, it stores the count in portable integer form. These counted sequential files are portable between big‑endian and little‑endian machines.)

During unload operations, if the specified output file fills up, isload displays an “Output file is full” error ($ERR_FILFUL) and prompts you for the name of the continuation file into which you want to write further output. If you type the end‑of‑file character at this prompt, isload terminates without unloading all of the records from the specified ISAM file.

During load operations, if you encounter the end of the specified sequential file, isload displays the message

End of input file filename

and prompts you for the name of the continuation file from which to continue reading records. If you type the end‑of‑file character at this prompt, isload closes the specified ISAM file and terminates.

In our example, we entered the filename secust to unload our cusmas.ism file to the sequential file secust.ddf.

If you enter a number of records at this prompt, the progress notification line displays the time isload began loading or unloading, the number of records that isload has processed, and the number of errors that occurred during that portion of the unload or load operation.

In our example, we entered the number 25 at this prompt and isload displayed a progress notification line every 25 records.

During both load and unload operations, I/O errors might occur. Whenever an error is encountered, isload displays an error message that identifies the file involved, the record number, and the error detected. You can then either skip the record that triggered the error or abort processing. If you abort, isload closes both the ISAM file and the sequential file, retaining whatever it unloaded or loaded prior to the abort.

In our example, isload didn’t encounter any errors and terminated normally.