HP 3000 Manuals HP 3000 Manuals
Operation
To use the File Handler utilities you need to specify a number of
parameters. You can do this in one of two ways:
* by using a text editor to produce a line sequential file
* by entering the required parameters on standard input during
utility execution
Each utility has a unique parameter
file format which is described in that utility's section later in this
chapter.
The line sequential parameter file holds records, each consisting of a
parameter type and an optional parameter value. The parameter type is
always the first two characters of the record. The remainder of the
record is the parameter value.
You can insert comments and comment
lines in a parameter file. A comment is recognized by the first
character being a hash character ( # ). These characters and lines are
ignored by the utilities. There is no restriction on their content
except that the characters should be printable. You can also insert
blank lines to make the file more readable.
All utility output is to standard output (stdout), except errors, which
are output to standard error (stderr).
When you have created the parameter files, you then invoke the utilities.
Invoking the File Handler Utilities
You can invoke the File Handler utilities either from the command line or
by calling them from a COBOL program. The following sections describe
these methods.
Command Line.
The command line you use to invoke the File Handler utilities consists of
the utility name, any flags you want to include, plus the name of the
parameter file you want to use:
utility-name [-e] [-p file-name] [flags]
parameter-file-name
where:
utility-name is the name of the utility you want to run. This
can be any one of:
fhconvert
fhcreate
fhedit
fhinfo
fhrebuild
fhreorg
fhvalidate
-e is optional and suppresses all screen output (for
example, error messages)
-p is optional and causes the IN or ON file-name to be
overwritten by the file-name specified after this
flag
file-name is the name of the file on which you want to run the
utility
flags are optional and can be:
-c for use with fhconvert and fhcreate only
and deletes any existing file with the same
file-name and also invokes the -r flag
-f for use with fhinfo and specifies that you
want the file information to go to a file. If
you do not specify -f, the output goes to
standard output (stdout). Any file created
using the -f flag can be submitted to other
utilities; for example, the fhrebuild utility.
-o for use with fhinfo and produces output
parameters, as opposed to input parameters, to
allow the output parameter file to be used as
input to fhrebuild.
-r for use with any utility and overwrites any
existing temporary work file (filename.con)
-v for use with any utility and displays the
banner giving a version number and copyright
parameter-file-name is either the name of your parameter file, or a
minus sign ( - ) to use parameters from standard
input (stdin). See the section Using Standard Input
with the Utilities for further information on
specifying the minus sign in place of a parameter
file name.
Using Standard Input with the Utilities
When you specify the minus
sign ( - ) in place of the parameter file name, it allows you to enter
parameters interactively. To do this, you type parameters in the same
way as you would in a parameter file, pressing Enter after each
parameter, including the last entry. When you have typed all the
parameters you require, enter Ctrl+D to conclude parameter entry.
Calling the File Handler Utilities from COBOL.
You can also invoke any of the available utilities directly from your
COBOL application by incorporating a CALL to the "cobcallfhutil"
routine. The CALL has the following format:
CALL "cobcallfhutil" USING BY VALUE noargs,
BY REFERENCE arg1,
arg2,
arg3,
arg4,
arg5,
arg6,
arg7,
arg8,
arg9,
arg10
END-CALL
where:
noargs is a PIC 9(2) COMP-5 field (input, mandatory) which
contains the number of arguments you supply
arg1 is a PIC X(n) field (input, mandatory) which
contains the name of the utility you want to call.
arg2 is a PIC X(n) field (input, mandatory) which
contains the first utility argument.
arg3 is a PIC X(n) field (input, optional) which
contains the second utility argument.
arg4 is a PIC X(n) field (input, optional) which
contains the third utility argument.
arg5 is a PIC X(n) field (input, optional) which
contains the fourth utility argument
arg6 is a PIC X(n) field (input, optional) which
contains the fifth utility argument
arg7 is a PIC X(n) field (input, optional) which
contains the sixth utility argument
arg8 is a PIC X(n) field (input, optional) which
contains the seventh utility argument
arg9 is a PIC X(n) field (input, optional) which
contains the eighth utility argument
arg10 is a PIC X(n) field (input, optional) which
contains the ninth utility argument
The COBOL RETURN-CODE special register contains either zero for a
successful utility execution, or non-zero if the utility execution fails.
File Types Supported by the File Handler Utilities
The File Handler utilities support all Micro Focus file formats created
by LEVEL II or later versions of COBOL. The File Handler utilities
support five types of indexed sequential files:
* C-ISAM format
* X/Open format
* LEVEL II format (created by MF COBOL LEVEL II or later versions of
Micro Focus COBOL)
* Micro Focus format
* Micro Focus IDXFORMAT(4)
Relative, sequential and line sequential files are supported. Printer
formatted line advancing files, which are not normally intended for
access, are not supported. Full details of these file formats can be
found in Chapter 17 , File Formats later in this manual.
The utilities are mainly for use with indexed files although some
utilities also support relative, sequential and line sequential files.
Fixed record length and variable record length files are supported for
all file types except line sequential, which are fixed.
The different characteristics of the various file types are important
when using these utilities. These are described in the following
sections.
Line Sequential Files
Line sequential files have fixed length records sequentially organized
and stored with trailing spaces removed.
Sequential Files
Sequential files have their records stored in the order in which they are
written. This order is fixed. These can contain fixed or variable
length records.
Relative Files
Relative files are organized by records being stored in a specific
position in relation to the beginning of the file. These can contain
fixed or variable length records.
Indexed Files
Indexed sequential files consist of a series of fixed or variable length
records. An indexed sequential file is implemented as two separate
files: the data file and the key or index file.
Record Delimiters.
Fixed record length indexed, relative and line sequential records use one
of two record delimiters. These are:
* line feed (LF)
* carriage return and line feed (CR & LF)
For fixed record length indexed files you specify the delimiter in the
data file, not the index file.
If the delimiter needs to be specified for a utility, you set this in the
parameter file used by the utility.
You should not specify a record delimiter for sequential files or
variable record length indexed files.
Default File Type Parameters
The following two tables list default file type parameters, where the
first character is a letter and the second character is a digit. Table
13-1 shows the file type parameters for the UNIX operating system
running Micro Focus COBOL. Table 13-2 shows the file type parameters
for the DOS or OS/2 operating systems running Workbench or Micro Focus
COBOL.
Table 13-2 is included so that you are aware of the differences of
the file type parameters output should you want to convert files produced
under DOS or OS/2 to UNIX.
Table 13-1. Default UNIX File Type Parameters
----------------------------------------------------------------
| | | | |
| | File | Delimeter | Block |
| | Type | | Size |
| | | | |
----------------------------------------------------------------
| | | | |
| Indexed Fixed | I0 | N/A | 1023 |
| | | | |
----------------------------------------------------------------
| | | | |
| Indexed Variable | I3 | N/A | 1023 |
| | | | |
----------------------------------------------------------------
| | | | |
| Relative Fixed | R0 | 1 | N/A |
| | | | |
----------------------------------------------------------------
| | | | |
| Relative Variable | R0 | 1 | N/A |
| | | | |
----------------------------------------------------------------
| | | | |
| Sequential Fixed | S0 | N/A | N/A |
| | | | |
----------------------------------------------------------------
| | | | |
| Sequential Variable | S0 | N/A | N/A |
| | | | |
----------------------------------------------------------------
| | | | |
| Line Sequential | L0 | 1 | N/A |
| | | | |
----------------------------------------------------------------
| | | | |
| IDXFORMAT(4)indexed | I4 | N/A | 1023 |
| | | | |
----------------------------------------------------------------
Table 13-2. Default DOS File Type Parameters
----------------------------------------------------------------
| | | | |
| | File | Delimeter | Block |
| | Type | | Size |
| | | | |
----------------------------------------------------------------
| | | | |
| Indexed Fixed | I3 | N/A | 1023 |
| | | | |
----------------------------------------------------------------
| | | | |
| Indexed Variable | I3 | N/A | 1023 |
| | | | |
----------------------------------------------------------------
| | | | |
| Relative Fixed | R0 | 0 | N/A |
| | | | |
----------------------------------------------------------------
| | | | |
| Relative Variable | R0 | 0 | N/A |
| | | | |
----------------------------------------------------------------
| | | | |
| Sequential Fixed | S0 | N/A | N/A |
| | | | |
----------------------------------------------------------------
| | | | |
| Sequential Variable | S0 | N/A | N/A |
| | | | |
----------------------------------------------------------------
| | | | |
| Line Sequential | L0 | 0 | N/A |
| | | | |
----------------------------------------------------------------
| | | | |
| IDXFORMAT(4)indexed | I4 | N/A | 1023 |
| | | | |
----------------------------------------------------------------
Default Indexed Block Size
The File Handler utilities have a default block size of 1 Kbyte, which is
identical to the Run-Time System indexed file block size.
If you want to alter the default setting, you must use the cobconfig
variable isam_block_size. See Chapter 31 , Run-Time Configuration
later in this manual for details.
Use of Keys in Indexed Files
When you create an indexed file, a primary index is created which can
never be deleted.
When you set up a key, each key can be multi-part and each part can be in
a different area of the record; these do not have to be contiguous and do
not have to exist in any particular order. All keys, other than the
prime key, can hold duplicates.
Keys are specified by means of a key description.
This description takes the following format:
[compression-type] (m:n:xxx/m:n:xxx/....)
where:
compression-type is optional and can consist of:
C - all compression
or any combination of:
D - duplicates allowed
S - same key (duplicate) compression
L - leading compression
T - trailing compression
m is the start offset of the key within a record
n is the key length
xxx is the key type, which must currently be CHAR or
CHARTYPE
For example, to specify a prime key of length four bytes starting at
record offset zero, the entry would be:
PK (0:4:CHAR)
and to specify a multi-part alternate key for which duplicates are
permitted with same key compression, the first part starting at record
offset four having length two bytes and the second part starting at
record offset twelve having length six bytes would be:
AK DS (4:2:CHAR/12:6:CHAR)
To specify the key offset and key length, you can use any combination of
size mnemonics, digits and arithmetic calculations (addition,
subtraction, multiplication and division) including parentheses. The
precedence for arithmetic calculations is as follows:
( ) parentheses
* / multiplication and division
+ - addition and subtraction
Calculations are performed from left to right; integer values only are
accepted (no decimal values are accepted). You cannot use negative
numbers.
Consider the following examples:
10 + 6 / 2 = 10 + 3 = 13
(10 + 6) / 2 = 16 / 2 = 8
Appendix K , Example fhconvert Parameter File, which gives an example
of a parameter file, illustrates the ways in which you can give key
descriptions.
Indexed files can hold a number of indices. Further indices can be added
to files, by using the utility fhedit.
These utilities also support Micro Focus compressed indexed files.
Error Handling
If you specify the -e option with your File Handler utilities, any error
messages output will be suppressed. We recommend that you specify the -e
option as the first flag in order to suppress command line parsing
errors.
When calling the utilities from COBOL, a COBOL file status type error and
the RETURN-CODE are available to the calling program. The file status
item is returned in the 2 byte external data item cob_util_last_error.
This item is decoded in the same way as any COBOL file status item.
The first byte of the status is called status key 1. This reports on the
general success or failure of an input-output operation on a file. The
second byte is called status key 2, which contains any further
information available.
If you want to display this item with its correct decimal value, you must
use careful redefinition in order to avoid truncation of the value. This
is because the facility enables the storage of values greater than
decimal 99, as a binary value.
The example below shows you how to define and access the external data
item cob_util_last_error, and demonstrates one method of retrieving
status key 2 for display purposes. Note that truncation has been avoided
by redefining the two status bytes as one numeric data item (with a
length of two bytes) capable of storing up to four decimal digits. The
demonstration program, validate2, which is supplied with this product,
makes use of the data item cob_util_last_error.
working-storage section.
* Utility arguments
* external status and decoding variables
01 cob_util_last_error external.
03 status-1 PIC X.
03 status-2 PIC X.
03 status-2-9 redefines status-2 PIC 9.
01 reply-bin redefines cob_util_last_error PIC 9(4) comp.
01 reply-decode.
03 reply-1 PIC X.
03 reply-2 PIC 999.
procedure division.
* Code to call the utilities
perform get-file-status
* Status handling code
stop run.
* Decode the returned 2 byte status
get-file-status.
move status-1 to reply-1
if reply-1 not=9
move status-2-9 to reply-2
else
move low-values to status-1
move reply-bin to reply-2
end-if
This file status data item is also available when calling the utilities
from any language. In non-COBOL calling programs, the external variable
should be referenced as cob_util_last_error. For COBOL, the underscores
are mapped to hyphens.
Error Conditions
There are two possible types of error condition:
* those relating to errors within the use of the utility
* file specific errors.
Details of utility errors can be found in Appendix J , File Handler
Utility Error Messages.
If the error indicates you have given invalid or duplicate parameters,
the error message will always display the parameter file entry that is at
fault.
For each file type there are two error variables used to define the
problem encountered: the error number and the error status. The error
number gives a global definition of the error encountered with the error
status providing any additional information.
The names of the error number and status variables differ according to
the file type. They are:
File Type Error Number Status Variables
Status 1 Status 2
indexed iserrno isstat1 isstat2
relative rlerrno rlstat1 rlstat2
sequential sqerrno sqstat1 sqstat2
line lserrno lsstat1 lsstat2
sequential
You can find full details of the meaning of the error numbers and status
variables in Appendix J , File Handler Utility Error Messages.
If the error is concerned with the operating system, the value of
'errno', the operating system error variable, is displayed in the error
message. For more information consult your operating system
documentation.
Creating Statically Linked Executable Files.
By default, any statically
linked executable files created by your COBOL system will exclude these
utilities. The utilities will, however, be included if your COBOL
program contains a reference to the utility entrypoint cobcallfhutil.
Alternatively, you can ensure that the utilities are included by using
the -I fhutil option on your cob command line. For example:
cob -xvo newrts32 prog1.o prog2.o -I fhutil
See Chapter 2 , COBOL System Interface earlier in this manual for
details of the cob command.
fhconvert Utility
The fhconvert utility enables you to convert
an existing file to a different file format. You can change:
* file organizations to relative, sequential, line sequential or
indexed
* record types to fixed length or variable length
* file indices, which can be added or deleted
* the NLS language of the file for systems that support NLS (for
indexed files only)
* record delimiters
* file formats, for example C-ISAM to LEVEL II
* index block sizes (for indexed files only)
* the data compression type (for indexed files only)
This utility always produces a new file from the existing file unless an
error condition occurs. To use this utility you must first construct a
parameter file which holds details of the existing file as well as the
details of the file conversion. You then invoke the utility. The
parameter file holding details of the existing file can be created using
the utility fhinfo (see the section "fhinfo Utility" for further
details of how to do this).
fhconvert Parameter File Format.
The parameter file records are:
Parameter Parameter Description
Type Value
IN xxxxxxxxxx input file name (length is
operating system dependent)
IE optional - when specified no .dat
extension for input file (indexed
files)
IT xx input file type, file types are:
I0 C-ISAM
I1 X/Open
I2 LEVEL II indexed
I3 Micro Focus indexed
I4 Micro Focus IDXFORMAT(4)
indexed
R0 relative
S0 sequential
L0 line sequential
ID n optional - record delimiter (omit
for indexed and sequential files):
0 = LF delimited (default)
1 = CR and LF delimited
IF nnnn fixed record length in bytes (not
needed for indexed files)
IV mmmm/nnnn variable record length minimum
(m), maximum (n) (not needed for
indexed files)
ON xxxxxxxxxx output file name
OT xx output file type as input file
type above
OD n optional - record delimiter (omit
for indexed and sequential files):
0 = LF (default)
1 = CR and LF
OF nnnn fixed record length in bytes
OV mmmm/nnnn variable record length, minimum
(m), maximum (n)
In addition, the following information refers to indexed files only:
Parameter Parameter Description
Type Value
OB nnnn index block size 511, 1023 or 4095
OE optional - output extension .dat
not required
NL xxxxx.... optional - NLS language name
PK DSLTC primary key description
(m:n:xxx:m:n:xxx/...)
AK DSLTC optional - alternate key
(m:n:xxx:m:n:xxx/...) description, one for each
alternate key used in file
DC nnn optional - data compression type
(0 - 255, indexed and sequential
files only)
For more information on keys, see the section "Use of Keys in Indexed
Files" earlier in this chapter.
fhconvert Error Messages.
fhconvert gives the following warning message if you include the input
record size for an indexed file:
(IF/IV) Record length is ignored for input ISAM file
You do not need to give this information as fhconvert takes these details
from the file (you must include this information for other file types).
This is only a warning message; the utility should run normally unless an
error situation is detected.
If you include a record delimiter in the parameter file for a sequential
file you will see the following warning message:
Record delimiter has been specified for sequential file
The utility will ignore the record delimiter as it is not applicable to
sequential files, and continue as normal.
If you specify data compression type for an indexed output file type
other than I3 you will receive the following warning message:
Data compression only valid for file type I3, file type updated
fhconvert automatically selects the I3 file type to enable data
compression to be utilized.If you specify a data compression type for a
non-indexed output file type you will receive the following warning
message:
Data compression only valid for ISAM files - ignored
fhconvert automatically disregards the data compression type specified.
If an error is detected, the utility closes all files, then terminates,
displaying a message on the screen indicating the type of error detected.
All error messages returned by the File Handler utilities are listed in
alphabetical order in Appendix J , File Handler Utility Error
Messages, along with any other relevant information.
fhcreate Utility
The fhcreate utility enables you to create an empty indexed file.
You will find this utility particularly useful in situations where an
application needs a file to exist, although not necessarily hold any
data.
To use this utility you need to create a parameter file holding
information on the type of indexed file you want to create including
information about keys in the file. You invoke the utility by using the
command line.
fhcreate Parameter File Format.
The parameter file records are:
Parameter Parameter Description
type Value
ON xxxxxxxxxx output file name (length is
operating system dependent)
OT xx output file type, file types are:
I0 C-ISAM
I1 X/Open
I2 LEVEL II indexed
I3 Micro Focus indexed
I4 Micro Focus IDXFORMAT(4)
indexed
OF nnnn fixed record length in bytes (n)
OV mmmm/nnnn variable record length, minimum
(m), maximum (n)
OB nnnn optional - index block size 511,
1023 or 4095
OE optional - output extension .dat
not required
NL optional - NLS language name
PK DSLTC primary key description
(m:n:xxx/m:n:xxx/...)
AK DSLTC optional - alternate key
(m:n:xxx/m:n:xxx/...) description, one for each
alternate key used in file
DC nnn optional - data compression type
(0 - 255, indexed files only)
For more information on keys, see the section "Use of Keys in Indexed
Files" earlier in this chapter.
fhcreate Error Handling.
If an error is detected, fhcreate closes all files, then terminates,
displaying a message on the screen indicating the type of error detected.
If you specify a data compression type (other than 0) for a non-indexed
file you receive the following warning message:
Data compression only valid for ISAM files - ignored
fhcreate automatically disregards the data compression type specified.
If you specify a data compression type (other than 0) for an indexed file
type other than I3 or I4, you receive the following warning message:
Data compression only valid for files type I3, I4 or S0, file
type updated to I3.
fhcreate automatically selects the I3 file type to enable data
compression to be utilized. All error messages returned by the File
Handler utilities are listed in alphabetical order in Appendix J ,
File Handler Utility Error Messages, along with any other relevant
information.
fhedit Utility
The fhedit utility enables you to alter
indices in an indexed file. There are two main functions:
* adding and deleting indices
* repairing a corrupt file
You cannot delete the primary index using this utility.
You can use fhedit in conjunction with the fhvalidate utility to repair
corrupt indices. The fhvalidate utility gives details of the corrupt
indices in the file.
To use this utility you need to create a parameter file giving details of
the file you want to use, and details of the existing key(s) you want to
delete and/or the new key(s) you want to add. You then invoke the
utility using the command line.
Note that if you ran fhvalidate first, and the validation resulted in a
file suitable for use with fhedit, you can use this file as the parameter
file. In this case you do not need to create an additional parameter
file.
fhedit Parameter File Format.
The parameter file records are:
Parameter Parameter Description
type Value
IN xxxxxxxxxx input file name (length is
operating system dependent)
IE optional - no .dat extension for
indexed input file
IT xx optional - input file type, file
types are:
I0 C-ISAM
I1 X/Open
I2 LEVEL II indexed
I3 Micro Focus indexed
NL xxxxx optional - NLS language name
AK DSCTL alternate key description to be
(m:n:xxx/m:n:xxx/...) added
DK DSCTL alternate key description of the
(m:n:xxx/m:n:xxx/...) key to be deleted
For more information on keys, see the section "Use of Keys in Indexed
Files" earlier in this chapter.
Note: You cannot use fhedit in conjunction with IDXFORMAT(4) indexed
files.
fhedit Error Handling.
If an error is detected, fhedit closes all files, then terminates,
displaying a message on the screen indicating the type of error detected.
All error messages returned by the File Handler utilities are listed in
alphabetical order in Appendix J , File Handler Utility Error
Messages, along with any other relevant information. If your file
utilizes data compression you MUST specify a file type of I3. This is
the file type returned by fhinfo for files using data compression. You
do not need to specify the data compression type being used, as fhedit
uses the type already specified in the file.
fhinfo Utility
The fhinfo
utility allows you to obtain information about an existing indexed file.
This information consists of file and index information. To use fhinfo
you need to construct a parameter file containing the name and type of
file you want to use. You then invoke the utility. The information
output by fhinfo is in the format of the input parameters to fhvalidate.
fhinfo Parameter File Format.
The parameter records are:
Parameter Parameter Description
type Value
IN xxxxxxxxxx input file name (length is
operating system dependent)
IT xx optional - input file type, file
types are:
I0 C-ISAM
I1 X/Open
I2 LEVEL II indexed
I3 Micro Focus indexed
I4 Micro Focus IDXFORMAT(4)
indexed
IE optional - when specified no .dat
extension for input indexed file
fhinfo Error Handling.
If an error is detected, fhinfo closes all files, then terminates,
displaying a message on the screen indicating the type of error detected.
All error messages returned by the File Handler utilities are listed in
alphabetical order in Appendix J File Handler Utility Error Messages,
along with any other relevant information.
fhrebuild Utility
The fhrebuild utility enables you to completely
reindex a corrupt indexed file. You need to supply details of all the
indices you want to create.
You can use this utility in conjunction with the fhvalidate utility to
repair a corrupt file.
To use this utility you need to construct a parameter file containing the
name and type of file you are using (note that the output file name will
have the same name as the file you want to reindex). The details of all
keys you want to include should also be given. You then invoke the
utility using the command line.
When using fhrebuild, you must always rebuild the file in the same format
as the original file for the following parameters:
* fixed or variable length file
* record length
* record delimiter
If you used fhvalidate first, and the validation resulted in a parameter
file being produced for use with fhrebuild, you can use this file as the
parameter file. In this case do not need to create an additional
parameter file.
Note that fhrebuild, if successful, will replace the existing file with
the newly indexed file. However, this may not always be possible as
inconsistencies within the data file can render an indexed file incapable
of being rebuilt. If fhrebuild fails, the file will be left in the same
form as before using the utility and an appropriate error message given.
fhrebuild Parameter File Format.
The parameter file records are:
Parameter Parameter Description
type Value
ON xxxxxxxxxx output file name (length is
operating system dependent)
OT xx output file type, file types are:
I0 C-ISAM
I1 X/Open
I2 LEVEL II indexed
I3 Micro Focus indexed
I4 Micro Focus IDXFORMAT(4)
indexed
OF nnnn fixed record length in bytes (n)
OV mmmm/nnnn variable record length, minimum
(m), maximum (n)
OB nnnn optional - index block size 511,
1023 or 4095
OE optional - output extension .dat
not required
NL xxxx.... optional - NLS language name
PK DSLTC primary key description
(m:n:xxx/m:n:xxx/...)
AK DSLTC optional - alternate key
(m:n:xxx/m:n:xxx/...) description, one for each
alternate key used in file
DC nnn optional - data compression type
(0 -255)
For more information on keys, see the section "Use of Keys in Indexed
Files" earlier in this chapter.
fhrebuild Error Handling.
If an error is detected, fhrebuild closes all files, then terminates,
displaying a message on the screen indicating the type of error detected.
All error messages returned by the File Handler utilities are listed in
alphabetical order in Appendix J , File Handler Utility Error
Messages, along with any other relevant information.
fhreorg Utility
The fhreorg utility enables you to
reorganize an indexed file using any record key. Using this method of
file reorganization for the most common key of access may improve record
access performance.
To use this utility you need to create a parameter file holding
information on how you want to reorganize your indexed file, including
information about keys in the file.
You then invoke the utility from the command line or by using the CALL
interface documented in the section "Calling the File Handler Utilities
from COBOL" .
fhreorg Parameter File Format.
The parameter file records are:
Parameter Parameter Description
type Value
IN xxxxxxxxxx input filename (length is
operating system dependent)
IE optional - when no .dat extension
for input file
IT xx input file type, file type are:
I0 C-ISAM
I1 X/Open
I2 LEVEL II indexed
I3 Micro Focus indexed
I4 Micro Focus IDXFORMAT(4)
indexed
KN xxx key number of access key
(1 = prime)
ON xxxxxxxxxx output filename (length is
operating system dependent)
OE optional - when specified no .dat
extension for output file
OT xx output file type, file types are:
I0 C-ISAM
I1 X/Open
I2 LEVEL II indexed
I3 Micro Focus indexed
I4 Micro Focus IDXFORMAT(4)
indexed
PK DSLTC primary key description for output
(m:n:xxx/..) file
AK DSLTC optional - alternate key
(m:n:xxx/..) descriptions for output file
KO x record retrieval order:
0 = ascending order
1 = descending order
DC xxx optional - output file data
compression type
For more information on keys, see the section "Use of Keys in Indexed
Files" earlier in this chapter.
fhreorg Error Handling.
If an error is detected, the utility will close all files, then
terminate, displaying a message on the screen indicating the type of
error detected.
All error messages returned by the File Handler utilities are listed in
alphabetical order in Appendix J , File Handler Utility Error
Messages, along with any other relevant information.
fhreorg Restrictions.
It is not possible to reorder a selected portion of the file.
fhvalidate Utility
The fhvalidate utility enables you to inspect a file for
self-consistency. Once run you get a simple report indicating the
success or failure of the file inspection.
When using this utility with an indexed file, you obtain additional
information about corrupt indices. You can use this information directly
as a parameter file with the fhedit and fhrebuild to reindex the file.
You give the details of the file you want to inspect in the parameter
file (this information includes the type of file and the record length),
then invoke the utility by using the command line. You will see various
messages during and after the validation, which are detailed in the
section "Validation Information Messages" .
When used with an indexed file, if the file is found to be inconsistent,
a parameter file is created for use with either fhedit or fhrebuild,
whichever is appropriate. This parameter file is directed to standard
output (stdout) unless you specify the -f flag on the File Handler
command line (see the section "Command Line" earlier in this
chapter).
Note that if a parameter file is produced for use with the fhrebuild
utility, any inconsistencies within the data file may render the file
incapable of being rebuilt.
fhvalidate Parameter File Format.
When using fhvalidate, you do not need to enter the record length for
indexed files.
If your file utilizes data compression you must specify a file type of
I3.
The parameter file records are:
Parameter Parameter Description
type Value
IN xxxxxxxxxx input file name (length is
operating system dependent)
IT xx input file type, file types are:
I0 C-ISAM
I1 X/Open
I2 LEVEL II indexed
I3 Micro Focus indexed
I4 Micro Focus IDXFORMAT(4)
indexed
R0 relative
S0 sequential
L0 line sequential
IE optional - no .dat extension for
indexed input file
ID n optional - record delimiter (omit
for indexed and sequential files):
0 = LF (default)
1 = CR and LF
IF nnnn fixed record length in bytes (not
needed for indexed files)
IV mmmm/nnnn variable record length minimum
(m), maximum (n) (not needed for
indexed files)
Validation Information Messages.
File information messages associated only with fhvalidate are as follows:
# Cannot recover from previous error, quitting file validation.
* The preceding reported error has resulted in an unsuccessful
completion of the validation.
# Error - Index entries inconsistent with records on data file.
* The records in the data file do not fully correspond to the
information held in the index file, indicating the file is
inconsistent.
# Error detected on index nn, record nn. (iserrno )
* The specified record in an indexed file has been found to be
inconsistent.
# Error detected on index nn. (iserrno )
* The specified index has been found to be inconsistent.
# Error - Index record size incorrect.
* The index block size is not equal to 511 or 1023, this implies a
problem with the index file.
# Error reading record nn in filename. (errno)
* The specified record in the named file is inconsistent.
# File needs to be edited. Creating parameter file for fhedit.
* The utility has diagnosed the file can be best repaired by using
the fhedit utility. A parameter file is being constructed to use
with that utility.
# File needs to be rebuilt. Creating parameter file for fhrebuild
* The utility has diagnosed the file can be best repaired by using
the fhrebuild utility. A parameter file is being constructed to
use with that utility.
# Record length of record nn or record nn is inconsistent
* The length of the record is inconsistent with the specified length
of records in the file. This implies a problem with this record.
Validation of file was successful file-name
* This indicates that the named file inspected by the fhvalidate
utility has been found to be consistent.
Validation of file was unsuccessful file-name
* This indicates that the named file inspected by the fhvalidate
utility has been found to be inconsistent.
fhvalidate Error Handling.
fhvalidate gives the following warning message if you include the input
record size for indexed files:
(IF/IV) Record length is ignored for input ISAM file
You do not need to give this information as fhvalidate takes these
details from the file (you must include this information for other file
types). This is only a warning message. fhvalidate should run normally
unless an error situation is detected.
If you include a record delimiter in the parameter file for an indexed or
sequential file you will see one of the following warning messages:
Record delimiter has been specified for ISAM file
Record delimiter has been specified for sequential file
fhvalidate ignores the record delimiter as it is not applicable to
indexed or sequential files, and continues as normal.
If an error is detected, fhvalidate closes all files, then terminates,
displaying a message on the screen indicating the type of error detected.
All error messages returned by the File Handler utilities are listed in
alphabetical order in Appendix J , File Handler Utility Error
Messages, along with any other relevant information.