SUNINDEX
The SUNINDEX utility creates an ISAM key file using the specified key positions in the associated data file. SUNINDEX uses one of the following command lines:
|
|
|
|
|
|
Note the following:
If no extension is specified for {txt}, the extension TXT is assumed.
If the {txt} file does not exist, it is created if the {Lnn} specification is given.
If {isi} is not specified, the file name in {txt} is used with the extension ISI. If {isi} is specified without an extension, ISI is used.
If neither {txt} nor {isi} are located in the current directory, the directories specified in the PLB_PATH environment variable are searched for the existence of both {txt} and {isi} files.
The {mode} parameter invokes logging of program messages when the '-L' or '-Q' parameter values are specified. The '-L' and '-Q' parameter values are mutually exclusive.
Warning: The {log} file name must be specified when using the '-L' or '-Q' parameter values. Otherwise, the first file specification is used for logging. Also, the {mode} can include a leading '-d' parameter value that can invoke additional debug program messages.
|
Mode |
Meaning |
|
D |
Output debug program messages. If the L/Q options are being used, the debug program messages are output to the {log} file. |
|
L |
Write all messages to the log file. |
|
Q |
Append all messages to the log file. |
Files larger than 4GB require fixed length records and will not work with space compressed or variable length records.
{Lnn} specifies the longest record length. A maximum record length of 65,529 bytes is supported. This parameter is required when creating or indexing a null file or when indexing a variable record length or space compressed file and the first record is not the longest record in the file.
If {Lnn} is not specified on the command line, the record length is determined by the first record in the data file. If the input file is of fixed length records, all records in the file are assumed to be that length during the SUNINDEX procedure.
In addition to the actual key specifications, {keyspecs} supports the following options:
B
C
Default compact. ISI and TXT files are opened in a shared mode and the TXT file is locked for the duration of the compact operation. When using the format (2), the ISI command line is changed to specify the OUTISI name as the output for any future re-index operation.
C=0
Compact operation is executed the same as the default '-c' option except the ISI command line is not changed.
C=1
The compact operation is executed where the compact locking is not used. In this case, the TXT file is opened in an EXCLUSIVE mode to insure that the sunindex utility has control of the files to execute the compact. This option can not be specified in the same command line as the '-c' option.
C=2
The compact operation is executed without accessing the TXT file. In this case, the ISI file is opened in the exclusive mode. This option is only available under Windows and is not available under Linux.
Example:
D
Allow duplicate keys in the ISAM key file (default).
E
Create a file containing any duplicate keys found during indexing.
F={nn}
Records are fixed length binary with NO end of record bytes.
G={nn}
Records are fixed length binary with normal end of record bytes.
I{ininame}
When specified, the utility will first look for any operational keywords in {inifile}. If the keyword is not found, the UET is searched. The filename specified by {ininame} must be a fully qualified name. If a full path is not specified, the filename must exist in the current working directory.
N
Do not allow duplicate keys in the ISAM key file. If any duplicate keys are found, the output file is deleted. Use the 'E' option to create an error file containing duplicate key information.
N$
Ignore duplicate keys and any duplicate key warning messages are suppressed.
NO
The index file is created ignoring duplicate keys and not adding them into the file. For PLB OPEN operations, the IFILE is tagged as a NODUP file.
O[={n}
The ISI file headers are marked for use by a Windows or Linux PL/B runtime. The {n} OS type value is optional. If the {n} value is not specified, the ISI files are marked for an OS type based on the operating system in use. If the {n} value is specified, the value must be one (1) for Windows or two (2) for Linux.
Examples:
If the utility is being executed under WIndows, the 'data.isi' index file is marked such that a Windows runtime ( PLBWIN, PLBCON, ...) can open the ISI file. If the utility is being executed under Linux, then the 'data.isi' index file is marked such that a Linux runtime ( PLB ) can open the ISI file.
The 'data.isi' index file is marked such that a Windows runtime can open the ISI file.
The 'data.isi' index file is marked such that a Linux runtime can open the ISI file.
P{nn}{=|#}{c}
Primary Key Specification for partial indexing. If specified, only the records that match the specification are included in the index file. Since only a single character may be specified for this option, multiple P options may select on multiple positions in a record. The {nn} specifies the position to perform the check on, the {=|#} specifies an equal or not equal condition on the specified position, and the {c} is the character to match on. A single character for {c} may be specified between the double quotes characters as in p3="X".
P{type}\"{col}{func}{'string'}\" MS-DOS
P{type}\"{col}{func}{\'string\'}\" Linux
Alternate Primary Key Specification for partial indexing. This alternate form and the old form may not be used at the same time. This alternate form allows multiple selection criteria to be specified with logical 'AND' and 'OR' operations. Multiple occurrences of {col}{func}{'string'} may be used when separated by a logical operator. See examples at the end of this section.
Q
Quit without creating the output file if the input file does not exist.
S
Allow space compressed records in the data file. The 'V' and 'W' options are assumed.
U
Treats upper/lower case characters equally in all READ operations.
V
Allow variable length records. If the 'S' option is not given, these records cannot be space compressed. The 'W' option is assumed.
W
Write all new records at the end of the file. Assumed if the 'S' or 'V' options are specified.
X
Disable record counter display.
Y
Do not place {txt} drive information into ISI header.
Z
Do not place drive or path information into ISI header.
The alternate primary key specification is as follows:
|
Field |
Description |
Character |
Description |
|
type |
the selection operation to be performed. |
= |
indicates that records that match the specified criteria are to be selected. |
|
|
|
# |
indicates the records that do not match any of the specified criteria operations are to be selected. |
|
col |
the location in the record where the conditional test is to be performed. A value larger than a record size results in a false condition for record selection. |
|
|
|
func |
the conditional test to be performed for the current operation. |
L or <
|
Less Than
|
|
'test' |
the character string for the current conditional test. This field is enclosed in single quotes. |
|
|
|
logical |
a logical AND or OR operation for multiple comparisons. Evaluation occurs left to right. |
& |
AND operator. This take precedence over the OR operator. |
|
|
|
| |
OR operator |
The 'D' option allows duplicate ISAM keys to be indexed/written to the file. This is the default mode for all SUNINDEX operations.
The 'E' option creates a file using the {isi} file name with an ERR extension that contains any duplicate key entries. This option, when used without the 'N' option, has no effect on the generated ISAM key file.
The 'N' option specifies that duplicates are not to be allowed in the key file. If any duplicate key entries are found, they are written to an error file (see 'E' option) and the key file is deleted upon completion of the procedure. Use of this option requires unique keys so that any attempt to add a duplicate key forces a trappable I/O error.
Records in the data file need not be in fixed and/or non space compressed format. If the 'S' option is given, the records may be both variable length and space compressed. If the 'S' option is given, the 'W' option is assumed.
Records written to the data file may be variable length and not be space compressed. The 'V' option is used if this is the case. As with the 'S' option, the 'W' option is assumed.
The 'W' option causes new records added to the file to be written at the end of file at all times. Deleted record space is not re-used and this space is not recovered until the file is reformatted.
It is possible to have all lower case letters converted to upper case for the ISAM key file by specifying the 'U' option as the first item in {keyspecs}. This does not affect the data in {txt}, only the key information that is written to the {isi} file.
Each part of key specification must give a starting and ending record position, separated by a hyphen (-) unless a one byte key and must be separated by commas.
The sum of the key specifications cannot exceed 150 positions.
The entire command line must be entered on one line. It cannot be continued to subsequent lines with a colon (:) as with the SUNAAMDX utility.
The data file is not re-written to discard any deleted record space. Only a new ISAM key file is created.
The information about the isam file may be retrieved by specifying the isam file name followed by the 'i' option. The command that was required to generate the file is displayed.
The isam file may be re-indexed without knowing any of the key specs by specifying the isam file name followed by the 'r' option.
Approximately 160k of free memory is needed to execute the SUNINDEX utility.
If 'TMPDIR=path' (Linux implementations of this name vary) is defined in the User Environment Table when the SUNINDEX utility is executed, the specified path is used as the default path for creating the temporary files. If {work} and TMPDIR are both not specified, the temporary work files are placed in the root directory of the current drive.
Alternate primary record selection and selected output specifications do not support structuring. For example, a specification of
P=\"5='Y'|5='N'&10='M'|10='F'\" MS-DOS
P=\"5=\'Y\'|5=\'N\'&10=\'M\'|10=\'F\'\" Linux
P=\"5='Y'&10='M'|5='Y'&10='F'|5='N'&10='M'|5='N'&10='F'\" MS-DOS
P=\"5=\'Y\'&10=\'M\'|5=\'Y\'&10=\'F\'|5=\'N\'&10=\'M\'|5=\'N\'&10=\'F\'\" Linux
If neither {txt} nor {isi} are located in the current directory, the directories specified in the PLB_PATH environment variable are searched for the existence of both {txt} and {isi} files.
The primary key (P{nn}{=|#}{c}) option must be used for an IFILE that is included in a FILELIST declaration. If an ISI is generated using the alternate primary key specification (P{type}"{col}{func}{'string'}") option, the IFILE opened to this ISI file cannot be included in a FILELIST declaration. Otherwise, an I23 subcode 40 error is given for any FILELIST WRITE or UPDATE operations executed. Note also that:
The alternate primary data is not available in an ISI header. Prior to 8.5.C, the ISAM keys for this form of an ISI file could be invalid after a FILELIST WRITE/UPDATE operation.
Use of the primary key specification (P{nn}{=|#}{c}) for generation of an ISI file has always worked for an IFILE included in a FILELIST declaration before and after changes made for 8.5C.
SUNINDEX supports the PLB_FNC keyword that forces file names to lowercase or mixed case when they are created.
The compact option reads all of keys in an ISI file and rebuilds the ISI file with all of the keys packed to reduce the number of isam tree sectors. The compact option has been implemented to allow the ISI to be compact in-place. Also, the compact option has modes to adapt to various environments that an end user encounters.
The Alternate Primary Record Specification and the Alternate Selective output Specification expressions support mathematical comparisons for the {op} operations. This allows a mathematical type indicator ( i.e. {N|n} ) to be included in the expression after the {c} starting column position.
The mathematical type indicator can be specified in the {comp} expression using the following syntax format:
Where:
Note:
If the optional {N|n} comparison type is used, the {string} must be specified as a valid numeric string as follows:
Leading blanks are skipped and count against the total field size being compared. Any blank or white-space characters found after the first valid numeric character causes and invalid numeric {string} declaration.
A single leading '-' (i.e. negative character) is supported which can ONLY be specified after any leading blanks and before any valid numeric digits or decimal point.
A single decimal point character can be specified in the {string} numeric declaration.
All other characters specified in the {string} numeric declaration must be '0' to '9' digits.
If the optional {N|n} comparison type is used, an invalid numeric {string} declaration causes an error from the index utility as follows:
If the optional {N|n} comparison type is used, the record that includes an invalid numeric field found at the {c} starting position may or may not be included in the selection record output depending on the logical evaluation of the 'S=' or 'S#' expression being used.
Examples for {N|n} usage:
In this scenario, the key for any records that has a valid numeric Primary selection criteria is included in the ISI. Keys for records with invalid selection criteria are not included in the ISI as well as any records that have a value of zero for the selection criteria.
In this scenario, all records that do NOT have a value of '1.00' are included in the ISI keys including records with invalid numeric fields.
In this scenario, the selected record keys do not include any invalid numeric fields encountered. In this case, the selected record keys only include records that have valid numeric fields whose value is not equal to '1.00'.
See Also: SUNINDEX Examples, Utilities
|
|