isCOBOL Evolve : SDK User's Guide : Utilities : JUTIL
JUTIL
The JUTIL utility manages JISAM files.
Usage:
jutil [-e=encryption_key]
      -info filename [-x]
      -load filename binary_sequential_file [-n] [-r|s] [-rs=#]
      -unload filename binary_sequential_file [-k=#]
      -loadtext filename line_sequential_file [-n] [-r|s] [-rs=#]
      -unloadtext filename line_sequential_file [-k=#]
      -loadr2 filename binary_sequential_file [-n] [-r|s]
      -shrink filename [-a]
      -check filename
      -rebuild filename [-a] [-f]
      -getimg filename
      -makeimg filename imgstring
      -gen [filelist] [directory]
      -convert filename directory
or
iscrun -utility jutil [-e=encryption_key]
                      -info filename [-x]
                      -load filename binary_sequential_file [-n] [-r|s] [-rs=#]
                      -unload filename binary_sequential_file [-k=#]
                      -loadtext filename line_sequential_file [-n] [-r|s] [-rs=#]
                      -unloadtext filename line_sequential_file [-k=#]
                      -loadr2 filename binary_sequential_file [-n] [-r|s]
                      -shrink filename [-a]
                      -check filename
                      -rebuild filename [-a] [-f]
                      -getimg filename
                      -makeimg filename imgstring
                      -gen [filelist] [directory]
                      -convert filename directory
Where:
• encryptionKey is the key to decrypt encrypted files.
• jisamFile is the name of the JISAM file to which the utility refers.
• sequentialFile is the name of a binary or line sequential file.
• imageString is a sequence of digits
• fileList is a text file.
• outputDirectory is an existing and writable directory.
• Parameters enclosed in square brackets are optional.
• The -e option should be used only when processing encrypted files. See Working on Encrypted Files for details.
JUTIL Commands:
JUTIL has a number of useful options:
Options
 
-info
Displays file information. If "-x" was passed, then extended information is shown. The extended information includes the description of each key segment and the alternate collating sequence characters list.
-load
Imports data from sequentialFile to jisamFile. JisamFile must exist. The data read from sequentialFile is appended to the existing records in JisamFile, unless the "-n" option is used. If "-n" option is used, then JisamFile is emptied before loading records.
The "-rs" option allows to specify the sequentialFile record length. If the option is not used, then JUTIL assumes that the record length of sequentialFile is the same as the record length of JisamFile.
If a unique key violation occurs, JUTIL behaves according to command line options as follows:
• if "-r" was used, the jisamFile record is rewritten with the content of the SequentialFile record;
• if "-s" was used, the duplicated record is skipped, and the loading process proceeds to the next record;
• if neither "-r" nor "-s" options were used, the loading process aborts.
-unload
Exports data from jisamFile to sequentialFile. If sequentialFile exists, it is overwritten.
The "-k" option allows to specify which key must be used to read jisamFile. A value of 1 identifies the primary key, a value of 2 identifies the first alternate key, and so on. By default, data is read using the primary key.
-loadtext
Imports data from line sequentialFile to jisamFile. jisamFile must exist. The data read from sequentialFile is appended to the existing records in JisamFile, unless the "-n" option is used. If "-n" option is used, then JisamFile is emptied before loading records.
The "-rs" option allows to specify the sequentialFile record length. If the option is not used, then JUTIL assumes that the record length of sequentialFile is the same as the record length of JisamFile. JUTIL reads a new line from sequentialFile and then truncates the read data according to the record length.
If a unique key violation occurs, JUTIL behaves according to command line options as follows:
• if "-r" was used, the jisamFile record is rewritten with the content of the SequentialFile record;
• if "-s" was used, the duplicated record is skipped, and the loading process proceeds to the next record;
• if neither "-r" nor "-s" options were used, the loading process aborts.
-unloadtext
Exports data from jisamFile to line sequentialFile. If sequentialFile exists, it is overwritten.
The "-k" option allows to specify which key must be used to read jisamFile. A value of 1 identifies the primary key, a value of 2 identifies the first alternate key, and so on. By default, data is read using the primary key.
-loadr2
Imports data from the sequentialFile generated by Recover2 RM utility to the jisamFile. jisamFile must exist. The data read from sequentialFile is appended to the existing records in JisamFile, unless the "-n" option is used. If "-n" option is used, then JisamFile is emptied before loading records.
If a unique key violation occurs, JUTIL behaves according to command line options as follows:
• if "-r" was used, the jisamFile record is rewritten with the content of the SequentialFile record;
• if "-s" was used, the duplicated record is skipped, and the loading process proceeds to the next record;
• if neither "-r" nor "-s" options were used, the loading process aborts.
-shrink
Compresses jisamFile by removing deleted records.
If "-a" was passed, then no user confirmation is required.
-check
Checks for file integrity.
-rebuild
Repairs a corrupted file. Before replacing the corrupted file with the repaired file, it asks for user confirmation. If "-a" was passed, then no user confirmation is required.
If "-f" was passed, then duplicated records are marked as deleted and the rebuild process completes. Without "-f" the first duplicated record found interrupts the rebuild process.
 
A JIsam archive consists of two files: an index files and a data file. The rebuild process will only rebuild the index file by reading through the data file. It will not change the data file, with the exception of removing duplicate primary keys when the -f switch is used. It also will not build the index file if it isn't found. If the data file is corrupted or the index file is missing, the -rebuild process will fail.
 
If the rebuild process fails, some temporary files may be left on disk.
-getimg
Returns a string representing file characteristics. See Image String format below for details about the string format.
-makeimg
Generates a new JIsam file according to the given image string. See Image String format below for details about the string format.
-gen
Creates a new empty JIsam file. See JIsam file generation for details.
-convert
Converts Micro Focus IDX3, IDX8 or CISAM indexed files to JIsam. See Micro Focus file conversion for details.
Working on Encrypted Files
When processing an encrypted file, the -e option must be used along with the other options to specify the encryption key. For example, the following command unloads the content of an encrypted file with the key "i5C0B0L":
jutil -e=i5C0B0L -unload CUSTOMERS custdata.txt
or
iscrun -utility jutil -e=i5C0B0L -unload CUSTOMERS custdata.txt
Note - Rebuilding (-rebuild) or shrinking (-shrink) a file with the wrong encryption key may garble the file content permanently. Pay particular attention when you use -rebuild and -shrink on encrypted files.
Image String format
The image string has the following format:
MaxRecSize, MinRecSize, NumKeys, [ NumSegs, Dups [ SegSize, SegOffset ] ... ] ...
Where:
• MaxRecSize is a five-digit number representing the maximum record length.
• MinRecSize is a five-digit number representing the minimum record length.
• NumKeys is a three-digit number representing the number of keys in the file.
• NumSegs is a two-digit number representing the number of segments in a key.
• Dups is a one-digit number representing the duplicate flag of a key. 0 means that duplicates are not allowed, 1 means that duplicates are allowed.
• SegSize is a three-digit number representing the size of a segment in a key.
• SegOffset is a five-digit number representing the offset of a segment in a key.
 
SegSize and SegOffset are repeated for each segment of the key
NumSegs, Dups and segments description are repeated for each key
Note - spaces in are shown to improve readability, they are not part of the format. Fields in the first pair of brackets are repeated for each key, fields in the second pair of brackets are repeated for each segment of the key.
Example - the following string applies to a file with a fixed record length of 108 bytes, a primary key composed of one segment of three bytes and an alternate key with duplicates composed of two segments, the first of two bytes in size and the second of three bytes in size:
00108,00108,002,01,0,003,00000,02,1,002,00003,003,00005
Options shortcuts
JUTIL allows to use options thru shortcuts, you don't need to type the whole word, only the first unique bytes are tested.The following table explains which digits are testedby JUTIL when parsing options:
option
number of digits tested
digits tested
-info
2
"-i"
-load
6
"-load "
-unload
8
"-unload "
-loadtext
6
"-loadt"
-unloadtext
8
"-unloadt"
-loadr2
6
"-loadr"
-shrink
2
"-s"
-check
3
"-ch"
-rebuild
2
"-r"
-getimg
4
"-get"
-makeimg
2
"-m"
-gen
4
"-gen"
-convert
3
"-co"
When the first digits of the option you type match with one of the strings in 'digits tested' column, then the corresponding option is checked and, if parameters are wrong or missing, the single option usage is shown.
In the other cases, the whole usage is shown.
Exit Status
JUTIL terminates with one of the following exit status:
Status
Meaning
0
No errors
3
File is corrupt
255
Fatal error or incorrect command line
Thin Client
JUTIL can be used in thin client environment as well. Use this command to start it:
iscclient -hostname <server-ip> -port <server-port> -utility jutil <arguments>
Server side paths must be used in the arguments.