HP 3000 Manuals HP 3000 Manuals
Demonstrating the File Handler Utilities
The File Handler utilities are supplied with a suite of demonstration
programs. The aim of the demonstration programs is to give you an
insight into the usage and the versatility of the File Handler utilities,
and also to allow you to see the correlation between COBOL file handling
syntax and the File Handler utilities.
We recommend that you view on the screen the contents of all files in
each of the demonstration programs. You may want to adopt their layout
and construction when creating files of your own. A knowledge of COBOL
and file structures would be useful but not essential for understanding
these demonstrations.
You will find descriptions of all files within the demonstration
programs. In addition, all COBOL sources that read, write or create
files have their records and files described using the File Handler
utilities parameter file entries. The following sections guide you step
by step through each of the demonstration programs.
File Handler Utilities Demonstration Programs
The demonstration programs use the seven File Handler utilities which,
for demonstration purposes, are grouped into five logical areas:
* fhinfo
* fhcreate and fhedit
* fhvalidate and fhrebuild
* fhconvert
* fhreorg
You invoke the utilities as shown in the section Invoking the File
Handler Utilities earlier in this chapter. An example command line is:
fhinfo -rv info.inf
where:
fhinfo is the utility
-rv tells the utility to overwrite any work files that exist
(r) and to display the copyright banner (v)
info.inf contains the parameters required by the utility
As mentioned earlier, input to all the utilities is via parameter files.
This input can be from a physical file or typed directly using the
utilities' additional capability of reading input from standard input
(stdin). To pass input from standard input, you should use a minus sign
( - ) instead of a parameter file-name on the command line. See below
for details of this feature.
The demonstration program files are contained in $COBDIR/demo/FHUTILS.
Before using the demonstrations, you will need to change to the
$COBDIR/demo/FHUTILS and set up the files. To change to the relevant
directory, type:
cd $COBDIR/demo/FHUTILS
You then type:
setup
to set up the files.
Running the setup program removes any files that were created by
previously running these demonstration programs, and will reinstate the
supplied corrupt file, badfile, which is used in the demonstrations later
in this chapter. It also ensures that all the necessary files for this
demonstration are in $COBDIR/demo/FHUTILS.
All programs have been compiled for animation, since animating them
allows you greater visibility of the demonstration programs. Once you
have run the setup program, you are ready to run the demonstration
programs.
demo1 Demonstration Program
The demo1 demonstration program uses the File Handler utility fhinfo.
fhinfo enables you to obtain information about a file and its index. Use
of fhinfo is restricted to indexed files.
demo1 uses the following six files:
info1.int (info1.cbl, info1.idy)
info1a.int (info1a.cbl, info1a.idy)
info1.inf
info2.int (info2.cbl, info2.idy)
info2a.int (info2a.cbl, info2a.idy)
info2.inf
The files are described in the following sections in the order in which
they are to be used.
info1 Demonstration Program.
Run the info1 demonstration program by typing:
cobrun info1.int
Running the info1 demonstration program creates an indexed file called
demofile with fixed length records, and writes one record to the file.
If you view the file info1.cbl you will see comments showing how the
COBOL syntax equates to fhinfo's output.
info1.inf Parameter File.
The info1 parameter file is used by fhinfo to obtain information about
demofile which you created by running the info1 demonstration program.
The info1.inf parameter file contains the following lines:
IN demofile
IE
IN specifies that the file-name from which you want to obtain information
is called demofile, and IE specifies that the data file has no .dat
extension, which is the default for all files created using your COBOL
system.
Run the fhinfo utility by typing:
fhinfo -rv info1.inf
You will see file information for demofile displayed on the screen after
the copyright banner as follows:
IN demofile
IE
IT I0
IF 20
# Number of records - 1
# Block size - 1023
NL n-computer
PK (0:8:CHARTYPE)
AK D(8:4:CHARTYPE)
AK (12:4:CHARTYPE)
AK (16:4:CHARTYPE)
By looking at the code that created this file (info1a.cbl), you can see
how this relates to the key and record descriptions for the file.
Rerun the fhinfo utility by typing:
fhinfo -f output -rv info1.inf
The file information of the file demofile displayed the first time you
ran fhinfo is sent to an output file called output. This allows you to
use the file output as a parameter file for other utilities. This is
described in the section Rebuilding a File using the -o Option later in
this chapter.
info1a Demonstration Program.
The info1a demonstration program contains code for the first call you
made to fhinfo from within a COBOL program.
Run the info1a demonstration program by typing:
cobrun info1a.int
When you run this program, the same information as when you ran fhinfo
-rv info1 will be displayed on the screen. For an explanation of the
code see the section Calling the File Handler Utilities from COBOL
earlier in this chapter.
info2 Demonstration Program.
The info2 demonstration program creates a file called demofile2 which is
similar to that created by running info1, except this time the file
contains variable length records.
Run the info2 program by typing:
cobrun info2.int
info2.inf Parameter File.
The info2.inf parameter file contains parameters similar to those
contained in the parameter file info1.inf, the only change is the
file-name:
IN demofile2
IE
IN specifies that the file-name from which you want to obtain information
is demofile2, and IE specifies that the data file has no .dat extension,
which is the default for all files created using your COBOL system.
Run the fhinfo utility by typing:
fhinfo -rv info2.inf
You will see the file information for demofile2 displayed on the screen
after the copyright banner as follows:
IN demofile2
IE
IT I3
IV 20/30
# Number of records - -1
# Block size - 1023
NL n-computer
PK (0:8:CHARTYPE)
AK D(8:4:CHARTYPE)
AK (12:4:CHARTYPE)
AK (16:4:CHARTYPE)
Although you have been supplied with the parameter file info2.inf, you
can reuse the parameter file info1.inf, which contains the following
parameters:
IN demofile
IE
To reuse this file to obtain information about demofile2, run the fhinfo
utility by typing:
fhinfo -p demofile2 -rv info1.inf
This causes the demofile reference in the parameter file to be
overwritten with the file-name demofile2 at execution time.
info2a Demonstration Program.
As with info1a, this program contains the code for the call to fhinfo
from COBOL to perform the first of the two example calls above.
Run the info2a demonstration program by typing:
cobrun info2a.int
When you run this program, the same information as when you ran fhinfo
-rv info2 is displayed on your screen.
demo2 Demonstration Program
The demo2 demonstration program uses the File Handler utilities fhcreate
and fhedit. fhcreate enables you to create an empty indexed file, and
fhedit allows you to add and delete alternate keys.
demo2 uses the following six files:
create.cre
create.int (create.cbl, create.idy)
create.inf
edit.edi
edit.int (edit.cbl, edit.idy)
edit2.int (edit2.cbl, edit2.idy)
The files are described in the following sections in the order in which
they are to be used.
create.cre Parameter File.
The create.cre parameter file contains parameters which enable fhcreate
to create an indexed file identical to the file you created by running
info1 using demo1, as follows:
ON demofile3 # file-name of file to be created
OE # no .dat extension
OT I0 # indexed fixed
OF 20 # fixed record length of 20 bytes
PK (0:8:CHARTYPE) # Prime key
AK D(8:4:CHARTYPE) # An alternate key with duplicates allowed
AK (12:4:CHARTYPE) # Another alternate key
AK (16:4:CHARTYPE) # And yet another
Create an empty indexed file by typing:
fhcreate -cv create.cre
where:
-c tells fhcreate to remove any work files and the indexed
file demofile3 if it already exists.
create.inf Parameter File.
The create.inf parameter file contains parameters which enable the fhinfo
utility to obtain information about the empty indexed file you created in
the section create.cre Parameter File above.
To obtain information on the empty indexed file, type:
fhinfo -rv create.inf
You can also use fhinfo in conjunction with fhcreate to allow you to
produce a file similar to demofile. To do this, you use fhinfo to obtain
information on the file demofile. However, although the information
produced is all you need to know to create a similar file, the parameter
types are incorrect; that is, fhinfo creates IN, IT, and so on, whereas
fhcreate requires ON, OT, and so on.
To change the parameter types to those that fhcreate require, rerun
fhinfo with the -o option by typing:
fhinfo -orv create.inf
Therefore, to create a copy of the file you created by running info1,
type:
fhinfo -orv info1.inf | fhcreate -p demofile3 -cv -
When you do this, fhinfo displays the file information on your screen
standard output (stdout). The fhcreate command takes its input from
standard input (stdin) signified by a minus sign ( - ) at the end of the
command line. By using the UNIX pipe ( | ) the output from fhinfo is
redirected to fhcreate. The -p option is specified to allow the
file-name read by fhcreate to be replaced by the file-name of this new
identical file demofile3.
create Demonstration Program.
The create demonstration program contains code which calls fhcreate from
COBOL. To run the create program, type:
cobrun create.int
edit.edi Parameter File.
The edit.edi parameter file contains parameters which allow fhedit to add
and remove alternate keys from the file you have just created (in this
case demofile3). Prior to running fhedit, you must run fhcreate,
otherwise you will get an error as fhedit attempts to add a key that
already exists.
The edit.edi parameter file contains
the following parameters:
IN demofile3 # The file-name
IT I0 # indexed fixed
IE # no .dat extension
AK DC(7:1:CHARTYPE) # Add a key with duplicates allowed and
compression
DK (12:4:CHARTYPE) # Delete a key
AK (12:2:INTTYPE) # And add another
To add these keys to your newly created file (demofile3), type:
fhedit -rv edit.edi
You can now rerun fhinfo as follows to view the new parameters of this
file:
fhinfo -rv create.inf
edit Demonstration Program.
The edit demonstration program contains code which performs a read and
write to an edited file. To see how this new structure relates to COBOL
syntax, view the edit.cbl source file. To perform the read and write to
a file, run this program (remembering to run fhcreate first) by typing:
cobrun edit.int
edit2 Demonstration Program.
The edit demonstration program contains code for the fhedit call used in
the section edit.edi Parameter File, above, but this time via a COBOL
program. If you have already run fhedit, you must rerun fhcreate before
continuing. To run this demonstration program, type:
cobrun edit2.int
demo3 Demonstration Program
The demo3 demonstration program uses the File Handler utilities
fhvalidate and fhrebuild. fhvalidate enables you to validate whether a
file is corrupt, how it is corrupt and produces output parameters so that
you can use fhrebuild to rebuild the file.
To demonstrate the use of these two utilities, there is a supplied
corrupt file, badfile, and its index file, badfile.idx. When you run
setup, these files are copied to the indexed files corrupt and
corrupt.idx, the files that you will actually use. If you want to
reinstate the corrupt file, you can copy these files yourself.
demo3 uses the following six files:
validate.val
validate2.int (validate2.cbl, validate2.idy)
info.inf
rebuild.int (rebuild.cbl, rebuild.idy)
validate.int (validate.cbl, validate.idy)
validate.inf
The files are described in the following sections in the order in which
they are to be used.
validate Demonstration Program.
The validate demonstration program contains code to read and write to the
indexed file corrupt. Run this program as follows:
cobrun validate.int
You will see that an error occurs, which indicates that the file is
corrupt. You can now validate the corrupt indexed file and rebuild it so
that next time you run validate, the error will not occur and the reads
and writes to this file will be successful.
validate.val Parameter File.
The validate.val parameter file is used by fhvalidate to allow it to
validate the corrupt indexed file corrupt.
This parameter file contains the same parameters as the parameter file
for fhinfo, except this parameter file includes the file type parameter
IT. This means that you can create one parameter file for use by both
utilities by including this parameter in the fhinfo parameter file,
although this is optional. Thus the parameter file contains:
IN corrupt # the corrupt files name
IT I0 # indexed fixed
IE # no .dat extension
To validate corrupt, type:
fhvalidate -rv validate.val
fhvalidate first validates the file by reading the file sequentially via
all the keys. It then validates the file by random reads on each of the
keys. You will find that fhvalidate detects an error on record 8/7 and
produces a parameter file for use with fhrebuild to rebuild corrupt. As
you can see, the output is displayed on the screen; you need to place the
output in a file so that you can use the parameter file to rebuild
corrupt. Using this method to rebuild a file, you use the parameter file
rebuild.reb as a stepping stone between fhvalidate and fhrebuild. To do
this, rerun the fhvalidate utility by typing:
fhvalidate -f rebuild.reb -rv validate.val
This places the output in a file which, in this demonstration, is called
rebuild.reb.
You can now use rebuild.reb to rebuild the corrupt file by typing:
fhrebuild -rv rebuild.reb
If you now rerun the validate demonstration program by typing:
cobrun validate.int
you will see that the reads and writes are successful. If you want to
verify that the file has been successfully rebuilt, rerun fhvalidate as
follows:
fhvalidate -rv validate.val
This is one of many ways to rebuild a file. Several other ways to
rebuild a file are described below.
Rebuilding a File without using a Parameter file.
The command you use to rebuild a file without using a parameter file is
almost the same as you use with fhcreate when duplicating a file. Type:
fhvalidate -rv validate.val | fhrebuild -rv -
Rebuilding a File using the -o Option.
You may recall that in the fhcreate demonstration programs earlier, you
used the -o option with fhinfo to produce 'ON, OT' type parameters. You
can use this functionality again to rebuild a file. Type:
fhinfo -orv validate.val | fhrebuild -rv -
This method shares the parameter files between fhinfo and fhvalidate, as
mentioned earlier in this chapter.
Combining fhinfo and fhrebuild to Rebuild a File.
To rebuild a file using fhinfo and fhvalidate, type:
fhinfo -f rebuild.reb -orv validate.val
fhrebuild -rv rebuild.reb
validate2 Demonstration Program.
The validate2 demonstration program performs the validation of the file
corrupt via a COBOL call. To run this program, type:
cobrun validate2.int
When you run validate2 a file status returned by fhvalidate is
displayed. The file status is accessed via the external variable
cob_util_last_error. For further details of the usage of this file
status, and how to decode this external variable, refer to the section
Calling the File Handler Utilities from COBOL earlier in this chapter.
rebuild Demonstration Program.
The rebuild demonstration program contains code which performs a call to
fhrebuild to rebuild the corrupt file. Before running this utility, the
file rebuild.reb must exist. To run this demonstration program, type:
cobrun rebuild.int
validate.inf Parameter File.
The validate.inf parameter file provides parameters which enable fhinfo
to obtain file information on the file corrupt. To run this utility,
type:
fhinfo -rv validate.inf
demo4 Demonstration Program
The demo4 demonstration program uses the File Handler utility fhconvert.
fhconvert allows you to convert one file type to another; for example,
indexed to relative, relative to sequential, line sequential to indexed,
and so on. This demonstration far from exhausts the uses of fhconvert,
it simply serves to explain what fhconvert can do.
demo4 uses the following six files:
convert.int (convert.cbl, convert.idy)
convert.ind
convert.inf
convert.seq
convert.lsq
convert.rel
These files are described in the following sections. You can use them in
any order, as long as you run the convert demonstration program first.
convert Demonstration Program.
The convert demonstration program contains code for creating and writing
records to an indexed file containing fixed length records. This file
has both data compression and key compression active. To create the file
demofile4, type:
cobrun convert.int
convert.inf Parameter File.
The convert parameter file enables fhinfo to obtain information about the
data and index of the demofile4 file you created in the section convert
Demonstration Program, above. Run the parameter file as follows:
fhinfo -rv convert.inf
convert.rel Parameter File.
The convert.rel parameter file contains parameters which enable fhconvert
to convert the indexed file demofile4 to a relative file, demofile8. The
contents of this file are as follows:
IN demofile4 # Input indexed file
IE # no .dat extension
IT I3 # Input type
ON demofile8 # Output file-name
OT R0 # File type relative
OE # no .dat extension
OF 20 # Fixed record length of 20 bytes
To convert demofile4 to a relative file, type:
fhconvert -rv convert.rel
convert.seq Parameter File.
The convert.seq parameter file provides parameters which enable fhconvert
to convert the indexed file demofile4 to the sequential file demofile6.
The parameters are as follows:
IN demofile4 # indexed input file
IE # no .dat
IT I3 # Input type
ON demofile6 # output file-name
OT S0 # Sequential output type
OE # no .dat extension
OF 20 # fixed records of 20 bytes
To convert demofile4 to a sequential file, type:
fhconvert -rv convert.seq
convert.lsq Parameter File.
The convert.lsq parameter file provides parameters which enable fhconvert
to convert the indexed file demofile4 to the line sequential file
demofile7. The parameters provided for this purpose are as follows:
IN demofile4 # indexed input file
IE # no .dat
IT I3 # Input type
ON demofile7 # output file-name
OT L0 # output type L0
OV 20/21 # variable length record varying 20 to 21
OE # no .dat extension
To convert demofile4 to a line sequential file, type:
fhconvert -rv convert.lsq
convert.ind Parameter File.
The convert.ind index parameter file provides parameters to enable
fhconvert to convert the compressed indexed file demofile4 to the
uncompressed indexed file demofile5. The parameters provided for this
purpose are as follows:
IN demofile4 # indexed input file
IE # no .dat
IT I3 # Input type
ON demofile5 # output file-name
OT I3 # output type
OE # no .dat extension
OF 20 # fixed length records of 20 bytes
To convert demofile4 to an indexed file, type:
fhconvert -rv convert.ind
demo5 Demonstration Program
The demo5 demonstration program uses the File Handler utility fhreorg.
fhreorg enables you to reorganize your indexed files on a specified key
and in either descending or ascending order.
demo5 uses the following four files:
reorg1.int (reorg1.cbl, reorg1.idy)
reorg2.int (reorg2.cbl, reorg2.idy)
reorg3.int (reorg3.cbl, reorg.idy)
reorg.reo
The files are described in the following sections in the order in which
they are to be used.
reorg1 Demonstration Program.
Run the reorg1.cbl demonstration program by typing:
cobrun reorg1.int
Running the reorg1 demonstration program creates an indexed file with
fixed length records with one alternate key, and writes four records.
The contents of the keys are displayed as they are written.
This file is called demofile.
reorg.reo Parameter File.
The reorg parameter file is used by fhreorg to reorganize the file
demofile which you create by running the reorg1 demonstration program.
The reorg.reo parameter file contains the following lines:
IN demofile # file-name of file to be reorganized
IE # no .dat extension
IT I0 # indexed fixed
KO 0 # ascending
KN 2 # key-2 (alternate key 1)
ON demofile2 # file-name of reorganized file
OT I0 # indexed fixed
OE # no .dat extension
Run the fhreorg utility by typing:
fhreorg -crv reorg.reo
This creates a copy of demofile called demofile2 with the data portion of
the files organized on ascending alternate key 1.
reorg2 Demonstration Program.
The reorg2 demonstration program contains the code produced by running
fhreorg in the above section.
Run the reorg2 demonstration program by typing:
cobrun reorg2.int
When you run this program, the same output as when you specified fhreorg
-crv reorg.reo is displayed on the screen. For an explanation of this
code, see the section Calling the File Handler Utilities from COBOL
earlier in this chapter.
reorg3 Demonstration Program.
The reorg3 demonstration program reads the data portion of the
reorganized file demofile2 as a relative file and displays the records as
they are read.
Run the reorg3 demonstration program by typing:
cobrun reorg3.int
This displays the contents of the keys read from the file and as you can
see, the records are now displayed in reverse order.