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 (stdin)
during utility execution
Each utility has a unique parameterfile 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 commentlines 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 fhvalidate only 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 minussign ( - ) in place of the parameter file-name,
it enables 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 cobcallfhutilroutine.
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 all arguments are for input, and:
noargs is a mandatory PIC 9(2) COMP-5 field which contains the
number of arguments you supply
arg1 is a mandatory PIC X(n) field which contains the name of
the utility you want to call
arg2 is a mandatory PIC X(n) field which contains the first
utility argument.
A utility argument can be -e, -p, the name of the file on
which you want to run the utility, any of the flags -c, -f,
-o, -r or -v, or the name of your parameter file or a minus
sign ( - ) to use the parameters from standard input
(stdin). See the section Command Line above for
descriptions of these parameters.
arg3 is an optional PIC X(n) field which contains the second
utility argument
arg4 is an optional PIC X(n) field which contains the third
utility argument
arg5 is an optional PIC X(n) field which contains the fourth
utility argument
arg6 is an optional PIC X(n) field which contains the fifth
utility argument
arg7 is an optional PIC X(n) field which contains the sixth
utility argument
arg8 is an optional PIC X(n) field which contains the seventh
utility argument
arg9 is an optional PIC X(n) field which contains the eighth
utility argument
arg10 is an optional PIC X(n) field 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 file formats created by LEVEL II
or later versions of this COBOL system. The File Handler utilities
support five types of indexed files:
* C-ISAM format
* X/Open format
* LEVEL II format (created by LEVEL II or later versions of COBOL)
* Indexed file format used by this COBOL system
* IDXFORMAT"4"
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 the appendix 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
12-1 shows the file type parameters for the UNIX operating system running
this COBOL system. Table 12-2 shows the file type parameters for the DOS
or OS/2 operating systems running this COBOL system.
Table 12-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 12-1: Default UNIX File Type Parameters
------------------------------------------------------------
| | | | |
| | File Type | Delimiter | Block |
| | | | Size |
| | | | |
------------------------------------------------------------
| | | | |
| Indexed Fixed | I0 | N/A | 1023 |
| | | | |
------------------------------------------------------------
| | | | |
| Indexed Variable | I3 | N/A | 1023 |
| | | | |
------------------------------------------------------------
| | | | |
| Relative Fixed | R0 | 0 | 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 |
| | | | |
------------------------------------------------------------
| | | | |
| INXFORMAT(4)indexed | I4 | N/A | 1023 |
| | | | |
------------------------------------------------------------
Table 12-2: Default DOS and OS/2 File Type Parameters
------------------------------------------------------------
| | | | |
| | File Type | Delimiter | Block |
| | | | Size |
| | | | |
------------------------------------------------------------
| | | | |
| Indexed Fixed | I3 | 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 | 0 | N/A |
| | | | |
------------------------------------------------------------
| | | | |
| INXFORMAT(4)indexed | I4 | N/A | 1023 |
| | | | |
------------------------------------------------------------
Default Index Block Size
The File Handler utilities have a default block size of 1 kilobyte (1K),
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 the chapter 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 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
The appendix 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 compressed indexed files of the type used by
this COBOL system.
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 two-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. 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 the file handler
utilities, 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:
* utility errors
* file specific errors
Details of utility errors can be found in the appendix 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 Status2
-------------------------------------------------
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 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 staticallylinked 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 entry point 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 the chapter COBOL System Interface (cob) earlier in this manual for
details of the cob command.
fhconvert Utility
The fhconvert utility enables you to convertan 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
Value Value
------------------------------------------------------
IN xxxxxxxxxx input file-name (length
is operating system
dependent)
IE optional - when
specified, .dat
extension for input file
not required
IT xx input file type. File
types are:
I0 C-ISAM
I1 X/Open
I2 LEVEL II indexed
I3 Indexed files of the
format used by this
COBOL system
I4 IDXFORMAT"4" indexed
R0 Relative
S0 Sequential
L0 Line sequential
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 (omit for indexed
files)
IV mmmm/nnnn variable record length
minimum (m), maximum (n)
(omit for indexed files)
ON xxxxxxxxxx output file-name
OT xx output file types. As
input file types 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
Value Value
-----------------------------------------------------------
OB nnnn index block size 511,
1023 or 4095
OE optional - when
specified, .dat
extension for output
file 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 types I3, I4 and
S0, file type updated
fhconvert automatically selects the I3 file type to enable data
compression to be used. 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 the appendix 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 then invoke the utility.
fhcreate Parameter File Format.
The parameter file records are:
Parameter Parameter Description
Value 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 Indexed files of the
format
used by this COBOL
system
I4 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
Table 12-0. (cont.)
Parameter Parameter Description
Value Value
OE optional - when
specified, .dat
extension for output
file 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 used. All error messages returned by the File Handler
utilities are listed in alphabetical order in the appendix File Handler
Utility Error Messages, along with any other relevant information.
fhedit Utility
The fhedit utility enables you to alterindices 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.
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
Value Value
-----------------------------------------------------------
IN xxxxxxxxxx input file-name (length
is operating system
dependent)
IE optional - when
specified, .dat
extension for input file
not required
IT xx optional - input file
type. File types are:
I0 C-ISAM
I1 X/Open
I2 LEVEL II indexed
I3 Indexed files of the
format used by this
COBOL system
NL xxxxx optional - NLS language
name
AK DSCTL alternate key
(m:n:xxx/m:n:xxx/...) description to be added
DK DSCTL alternate key
(m:n:xxx/m:n:xxx/...) description of the key
to be deleted
NOTE You cannot use fhedit in with IDXFORMAT"4"indexed files.
For more information on keys, see the section Use of Keys in Indexed
Files earlier in this chapter.
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 the appendix File Handler Utility Error Messages,
along with any other relevant information. If your file uses 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 fhinfoutility enables 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.
NOTE The number of records in a variable format file cannot be
determined and is given as -1.
fhinfo Parameter File Format.
The parameter records are:
Parameter Parameter Description
Value 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 Indexed files of the
format used by this
COBOL system
I4 IDXFORMAT"4" indexed
IE optional - when
specified, .dat
extension for input file
not required
Example.
An example of the fhinfo parameter file using the listed parameter types
on a C-ISAM file called test, where the physical files created are test
and test.idx is:
IN test # input file-name
IT I0 # C-ISAM file
IE # is required when the data part is
created as test rather than test.dat.
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 the appendix File Handler Utility Error Messages,
along with any other relevant information.