| Maintaining Files | Viewing and Editing Data Files | |
The file handler utilities are a suite of programs provided with Micro Focus COBOL for UNIX that you can use to manage your files.
Note: The file handler utilities remain available in this release of Object COBOL Developer Suite, but are being superceded by an enhanced Rebuild utility. Rebuild is the actively supported and strategic file management utility, while the file handler utilities will be removed from future product updates. For information on how you migrate to Rebuild see the section Migrating To Rebuild.
There are seven file handler utilities. Two of these work with all COBOL file organizations:
| Utility |
Description |
|---|---|
| fhconvert | file conversion utility |
| fhvalidate | file validation utility |
The other five utilities only work with indexed files:
| Utility |
Description |
|---|---|
| fhcreate | builds an empty indexed file |
| fhedit | adds and deletes indices |
| fhinfo | accesses file and index information |
| fhrebuild | re-indexes a corrupt file |
| fhreorg | reorganizes an indexed file |
The file handler utilities support five types of indexed file:
Printer sequential (line advancing) files are not supported.
To use the file handler utilities you need to specify a number of parameters. You can do this in one of two ways:
If you supply the parameters via a text file, the first two characters of each record must be the parameter type and the remainder of the record is the parameter value. You can insert comments in a parameter file by preceding the comment with a hash character (#). You also can insert blank lines to make the file more readable.
All output by the utilities is to standard output (stdout), except errors which are output to standard error (stderr).
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.
To invoke a utility from the command line, specify the utility name, any flags you want to include, plus the name of the parameter file you want to use:
utility-name [-e] [-p filename] [flags] parameter-filename
where the parameters are:
utility-name |
The name of the utility you want to run. | ||||||||||
-e |
Optional. Suppresses all screen output. | ||||||||||
-p |
Optional. Causes the IN or ON filename to be overwritten by the filename specified after this flag. | ||||||||||
filename |
The name of the file on which you want to run the utility. | ||||||||||
flags |
Optional. One or more of:
|
||||||||||
parameter-filename |
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 filename. |
If you specify a minus sign ( - ) instead of a parameter filename, you can enter parameters on the command line. To do this, type the parameters as you would in a parameter file, pressing Enter after each, including the last. When you have entered all the parameters, enter Ctrl+D.
You also can 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 all arguments are for input:
noargs |
A mandatory PIC 9(2) COMP-5 field that contains the number of arguments you supply. |
arg1 |
Mandatory. PIC X(n) field that contains the name of the utility you want to call. |
arg2 |
Mandatory. PIC X(n) field that contains the
first utility argument.
A utility argument can be |
arg3 |
Optional. PIC X(n) field containing the second argument. |
arg4 |
Optional. PIC X(n) field containing the third argument. |
arg5 |
Optional. PIC X(n) field containing the fourth argument. |
arg6 |
Optional. PIC X(n) field containing the fifth argument. |
arg7 |
Optional. PIC X(n) field containing the sixth argument. |
arg8 |
Optional. PIC X(n) field containing the seventh argument. |
arg9 |
Optional. PIC X(n) field containing the eighth argument. |
arg10 |
Optional. PIC X(n) field containing the ninth argument. |
The RETURN-CODE contains either zero for successful completion, or non-zero if the utility fails.
Records in relative, line sequential and fixed record length indexed files are terminated by one of two record delimiters. These are:
If the delimiter needs to be specified for a utility, it is specified in the parameter file used by the utility.
You should not specify a record delimiter for record sequential files or variable record length indexed files.
The following two tables list default file type parameters, where the first character is a letter and the second character is a digit. Table 8-1 shows the file type parameters for UNIX and Table 8-2 shows the file type parameters for DOS and OS/2.
Table 8-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 |
| IDXFORMAT"4" indexed | I4 | N/A | 1023 |
Note: Throughout this chapter, I0 indicates a C-ISAM file created using either the modified C-ISAM file handler provided with this COBOL system, or the standard C-ISAM file handler, while I3 indicates a Micro Focus COBOL indexed file, that is, an indexed file with variable length records, data compression or created by a program compiled using IDXFORMAT"3".
Table 8-2 is included so that you are aware of the differences should you want to convert files created on DOS or OS/2 systems to UNIX.
Table 8-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 |
| IDXFORMAT(4) indexed | I4 | N/A | 1023 |
The file handler utilities use a default block size of 1 kilobyte (1K), identical to the run-time system indexed file block size.
You can alter this default setting by setting the run-time tunable isam_block_size. See your Object COBOL User Guide for details.
When you create an indexed file, a primary index is created that 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 primary key, can hold duplicate values.
Keys are specified by a key description.
This description takes the following format:
[compression-type] (m:n:xxx/m:n:xxx/....)
where the parameters are:
compression-type
|
Optional. Can consist of:
C - all compression or any combination of: D - duplicates allowed |
m |
The start offset of the key in a record |
n |
The key length |
xxx |
The key type, that 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 section Example fhconvert Parameter File, that gives an example of a parameter file, illustrates the ways 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.
If you specify the -e option, any error messages are
suppressed. We recommend that you specify the -e option as
the first flag to suppress command line parsing errors.
When calling the utilities from COBOL, a file status and the RETURN-CODE are available to the calling program. The file status is returned in the external data item cob_util_last_error . The example code below demonstrates how to define and access the external data item cob_util_last_error. (The demonstration program, validate2, supplied with the file handler utilities, makes use of 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 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, use hyphens instead of underscores.
There are two possible types of error condition:
Details of utility errors can be found in the section Utility Error Messages. If the error indicates you have given invalid or duplicate parameters, the error message always displays the parameter file entry that is at fault.
For each file type two error variables are used: the error number and the error status. The names of these variables differ according to the file type. They are:
| Status Variables | |||
|---|---|---|---|
| File Type |
Error Number |
Status 1 |
Status 2 |
| indexed | iserrno | isstat1 | isstat2 |
| relative | rlerrno | rlstat1 | rlstat2 |
| sequential | sqerrno | sqstat1 | sqstat2 |
| line sequential | lserrno | lsstat1 | lsstat2 |
You can find full details of the error number and status variables in the section Utility Error Messages.
For UNIX operating system errors, the value of errno, is displayed in the error message. For more information consult your operating system documentation.
By default, any statically linked executable files created by your COBOL system exclude the file handler utilities.
The utilities are, however, 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
The fhconvert utility enables you to convert a file. You can change:
| Parameter Type |
Parameter Value |
Description |
||||||||||||||||
|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|
| IN | xxxxxxxxxx | Input filename (length is operating system dependent). | ||||||||||||||||
| IE | Optional. If omitted, .dat extension assumed for input file. | |||||||||||||||||
| IT | xx | Input file type. File types are:
|
||||||||||||||||
| ID | n | Optional - record delimiter (omit for indexed and
sequential files):
0 = LF (default) |
||||||||||||||||
| 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 filename | ||||||||||||||||
| OT | xx | Output file types. As input file types above. | ||||||||||||||||
| OD | n | Optional - record delimiter (omit for indexed and
sequential files):
0 = LF (default) |
||||||||||||||||
| 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 Type |
Parameter Value |
Description |
|---|---|---|
| OB | nnnn | Index block size 511, 1023 or 4095. |
| OE | Optional. If omitted, .dat extension assumed for output file. | |
| NL | xxxxx.... | Optional - NLS language name. |
| PK | DSLTC (m:n:xxx:m:n:xxx/...) | Primary key description. |
| AK | DSLTC (m:n:xxx:m:n:xxx/...) | Optional - alternate key description, one for each alternate key used in the file. |
| DC | nnn | Optional - data compression type (0 - 255, indexed and sequential files only) |
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 record sequential file, the following warning message is displayed:
Record delimiter has been specified for sequential file
The utility ignores the record delimiter as it is not applicable to record sequential files, and continues as normal.
If you specify data compression for an indexed output file type other than I3, I4 or S0, the following warning message is displayed:
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 data compression for a relative or line sequential file the following warning message is displayed:
Data compression only valid for ISAM files - ignored
fhconvert automatically disregards the data compression 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.
The fhcreate utility enables you to create an empty indexed file . You may find this utility particularly useful in situations where an application needs a file to exist but not necessarily hold any data.
| Parameter Type |
Parameter Value |
Description |
||||||||||
|---|---|---|---|---|---|---|---|---|---|---|---|---|
| ON | xxxxxxxxxx | Output filename (length is operating system dependent). | ||||||||||
| OT | xx | Output file type. File types are:
|
||||||||||
| 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. If omitted, .dat extension assumed for output file. | |||||||||||
| NL | Optional - NLS language name | |||||||||||
| PK | DSLTC (m:n:xxx/m:n:xxx/...) | Primary key description | ||||||||||
| AK | DSLTC (m:n:xxx/m:n:xxx/...) | Optional - alternate key description, one for each alternate key used in the file | ||||||||||
| DC | nnn | Optional - data compression type (0 - 255, indexed files and sequential files only) |
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 an indexed file type other than I3 or I4, the following warning message is displayed:
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.
The fhedit utility enables you to alter indices in an indexed file. There are two main functions:
You cannot delete the primary index using this utility.
You can use fhedit with the fhvalidate utility to repair corrupt indices. The fhvalidate utility gives details of the corrupt indices in the file.
| Parameter Type |
Parameter Value |
Description |
||||||||
|---|---|---|---|---|---|---|---|---|---|---|
| IN | xxxxxxxxxx | Input filename (length is operating system dependent). | ||||||||
| IE | Optional. If omitted, .dat extension assumed for input file. | |||||||||
| IT | xx | Optional - input file type. File types are:
|
||||||||
| NL | xxxxx | Optional - NLS language name. | ||||||||
| AK | DSCTL (m:n:xxx/m:n:xxx/...) | Alternate key description to be added. | ||||||||
| DK | DSCTL (m:n:xxx/m:n:xxx/...) | Alternate key description of the key to be deleted. |
Note: You cannot use fhedit with IDXFORMAT"4" indexed files.
The fhinfo utility enables you to obtain information about an existing indexed file. This information consists of file and index information.
Note: The number of records in a variable format file or a data compressed file cannot be determined and is given as -1.
| Parameter Type |
Parameter Value |
Description |
||||||||||
|---|---|---|---|---|---|---|---|---|---|---|---|---|
| IN | xxxxxxxxxx | Input filename (length is operating system dependent) | ||||||||||
| IT | xx | Optional - input file type. File types are:
|
||||||||||
| IE | Optional. If omitted, .dat extension assumed for input file. |
Example
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 filename
IT I0 # C-ISAM file
IE # is required when the data part is
created as test rather than test.dat.
The fhrebuild utility enables you to re-index a corrupt indexed file. You need to supply details of all the indices you want to create. You can also use this utility with the fhvalidate utility to repair a corrupt file. (You can use the Rebuild utility, which provides additional functionality and greater flexibility, to perform these tasks. See the chapter Maintaining Files for details on Rebuild.)
When using fhrebuild, you must always rebuild the file in the same format as the original file for the following parameters:
You can use fhvalidate to produce a parameter file which is used as input to fhrebuild.
If successful, fhrebuild replaces the existing file with the newly indexed file. However, inconsistencies in the data file can render an indexed file incapable of being rebuilt. If fhrebuild fails, the file is left in the same condition as before and an appropriate error message is displayed.
The parameter file records are:
| Parameter Type |
Parameter Value |
Description |
||||||||||
|---|---|---|---|---|---|---|---|---|---|---|---|---|
| ON | xxxxxxxxxx | Output filename (length is operating system dependent). | ||||||||||
| OT | xx | Output file type. File types are:
|
||||||||||
| 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. If omitted, .dat extension assumed for output file. | |||||||||||
| NL | xxxx.... | Optional - NLS language name | ||||||||||
| PK | DSLTC (m:n:xxx/m:n:xxx/...) | Primary key description | ||||||||||
| AK | DSLTC (m:n:xxx/m:n:xxx/...) | Optional - alternate key 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.
The fhreorg utility enables you to reorganize an indexed file using a specified key. Reorganizing a file using the most commonly accessed key can improve performance.
| Parameter Type |
Parameter Value |
Description |
||||||||||
|---|---|---|---|---|---|---|---|---|---|---|---|---|
| IN | xxxxxxxxxx | Input filename (length is operating system dependent). | ||||||||||
| IE | Optional. If omitted, .dat extension assumed for input file. | |||||||||||
| IT | xx | Input file type. File types are:
|
||||||||||
| KN | xxx | Key number of access key (1 = prime) | ||||||||||
| ON | xxxxxxxxxx | Output filename (length is operating system dependent). | ||||||||||
| OE | Optional. If omitted, .dat extension assumed for output file. | |||||||||||
| OT | xx | Output file type. File types are as for IT parameter above. | ||||||||||
| PK | DSLTC(m:n:xxx/..) | Primary key description for output file. | ||||||||||
| AK | DSLTC (m:n:xxx/..) | Optional - alternate key descriptions for output file. | ||||||||||
| KO | x | Record retrieval order:
0 = ascending order |
||||||||||
| DC | xxx | Optional - output file data compression type. |
The fhvalidate utility enables you to validate a file. It produces a simple report indicating success or failure.
For indexed files, additional information about corrupt indices is produced. You can use this information as a parameter file with fhedit and fhrebuild to re-index the file.
Note: You can use the Rebuild utility (see the chapter Maintaining Files for details) to carry out a more thorough validation of Micro Focus format indexed files.
Note: When using fhvalidate, you do not need to enter the record length for indexed files.
If your file uses data compression you must specify a file type of I3 or I4.
| Parameter Type |
Parameter Value |
Description |
||||||||||||||||
|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|
| IN | xxxxxxxxxx | Input filename (length is operating system dependent). | ||||||||||||||||
| IT | xx | Input file type. File types are:
|
||||||||||||||||
| IE | Optional. If omitted, .dat extension assumed for input file. | |||||||||||||||||
| ID | n | Optional. Record delimiter (omit for indexed and
sequential files):
0 = LF (default) |
||||||||||||||||
| 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). |
The following information messages are displayed by fhvalidate:
fhvalidate gives the following warning message if you include an 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 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.
The directory $COBDIR/demo/fhutils contains a number of programs that demonstrate how to use the file handler utilities.
Before using the demonstrations, you need to change to the $COBDIR/demo/fhutils directory and set up the files. To change directory, type:
cd $COBDIR/demo/fhutils
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 reinstates the supplied corrupt file, badfile, used in the demonstrations. It also ensures that all the necessary files are in $COBDIR/demo/fhutils.
All the programs have been compiled for animation.
The demo1 demonstration program uses the file handler utility fhinfo 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 used.
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.
The info1.inf parameter file is used by fhinfo to obtain information about the file demofile that you created by running the info1 demonstration program:
IN demofile IE
IN specifies the file about which you want to obtain information and IE specifies that the data file has no .dat extension.
Run the fhinfo utility by typing:
fhinfo -rv info1.inf
The following information is displayed:
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)
You can look at the source code of the program that created this file (info1.cbl) to see how the information displayed by fhinfo relates to the key and record definitions for the file.
Now run the fhinfo utility by typing:
fhinfo -f output -rv info1.inf
This time the information is sent to an output file called output which can be used as an input parameter file for other utilities - See the section Rebuilding a File using the -o Option.
Run the info1a demonstration program by typing:
cobrun info1a.int
Running this program is equivalent to entering the command fhinfo
-rv info1.
The info2 demonstration program creates a file called demofile2, an indexed file with variable length records.
Run the info2 program by typing:
cobrun info2.int
The info2.inf parameter file is used by fhinfo to obtain information about demofile2:
IN demofile2 IE
IN specifies the file about which you want to obtain information and IE specifies that the data file has no .dat extension.
Run the fhinfo utility by typing:
fhinfo -rv info2.inf
The following information is displayed:
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)
You can use the parameter file info1.inf:
IN demofile IE
to obtain information about demofile2 by typing:
fhinfo -p demofile2 -rv info1.inf
This causes the demofile reference in the parameter file to be overwritten with the filename demofile2 at execution time.
Run the info2a demonstration program by typing:
cobrun info2a.int
Running this program is equivalent to entering the command fhinfo
-rv info2.
The demo2 demonstration program uses the file handler utilities fhcreate and fhedit to create an empty indexed file and then 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 used.
The create.cre parameter file enables fhcreate to create an indexed file identical to the one you created by running info1 using demo1:
ON demofile3 # filename 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 exists. |
The create.inf parameter file enables the fhinfo utility to obtain information about the empty indexed file you created using create.cre:
fhinfo -rv create.inf
You can use fhinfo with fhcreate to create a file like demofile. To do this, you need to use fhinfo to obtain information about demofile. Although this produces all the information you require, 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 required by fhcreate, run fhinfo with the -o option, for example:
fhinfo -orv create.inf
So, to create a copy of the file you created by running info1, type:
fhinfo -orv info1.inf | fhcreate -p demofile3 -cv -
The minus sign ( - ) at the end of the command line specifies that
fhcreate takes its input from standard input (stdin) rather than a
parameter file and so the UNIX pipe command ( | ) redirects the output
from fhinfo to fhcreate. The -p option specifies that the
filename read in by fhcreate is to be replaced by the filename specified
on the command line, demofile3.
The create demonstration program contains code that calls fhcreate. To run the create program, type:
cobrun create.int
The edit.edi parameter file contains parameters that allow fhedit to add and remove alternate keys from the file you have just created (demofile3):
IN demofile3 # The filename
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:CHARTYPE) # And add another
To add these keys to your newly created file (demofile3), type:
fhedit -rv edit.edi
You can now re-run fhinfo to view the altered file:
fhinfo -rv create.inf
The edit demonstration program contains code that performs a read and write to an edited file. You can view the source of this program in edit.cbl. To run this program, type:
cobrun edit.int
The edit2 demonstration program contains code for the fhedit call used in the section edit.edi Parameter File, above. If you have already run fhedit, you must re-run fhcreate before continuing. To run edit2:
cobrun edit2.int
The demo3 demonstration program uses the file handler utilities fhvalidate and fhrebuild to validate a file and then rebuild it.
To demonstrate the use of these two utilities, a corrupt file, badfile and its index file badfile.idx are supplied. When you run setup, these files are copied to the indexed files corrupt and corrupt.idx, the files that you actually use.
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 used.
The validate demonstration program contains code to read and write to the indexed file corrupt:
cobrun validate.int
An error occurs indicating that the file is corrupt. You can validate the file and rebuild it so that next time you run validate, the error does not occur and the reads and writes to the file are successful.
The validate.val parameter file is used by fhvalidate to validate the corrupt indexed file corrupt:
IN corrupt # the corrupt files name IT I0 # indexed fixed IE # no .dat extension
To validate corrupt, type:
fhvalidate -rv validate.val
Firstly, fhvalidate reads the file sequentially. Next, it performs random reads on each of the keys. fhvalidate detects an error on record 8/7 and produces output that can be used 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 it as a parameter file to rebuild corrupt. To do this, re-run the fhvalidate utility by typing:
fhvalidate -f rebuild.reb -rv validate.val
This places the output in a file that, in this demonstration, is called rebuild.reb. You can now use rebuild.reb to rebuild the corrupt file:
fhrebuild -rv rebuild.reb
If you now re-run the validate demonstration program by typing:
cobrun validate.int
you can see that the reads and writes are successful. If you want to verify that the file has been successfully rebuilt, re-run fhvalidate as follows:
fhvalidate -rv validate.val
You can use the UNIX pipe command to redirect the output from fhvalidate to fhrebuild, without creating a parameter file:
fhvalidate -rv validate.val | fhrebuild -rv -
You can use the -o option so that the output from fhinfo can be used as input to fhvalidate:
fhinfo -orv validate.val | fhrebuild -rv -
To rebuild a file using fhinfo and fhvalidate, type:
fhinfo -f rebuild.reb -orv validate.val
fhrebuild -rv rebuild.reb
The validate2 demonstration program validates the file corrupt:
cobrun validate2.int
When you run validate2 the file status returned by fhvalidate is displayed.
The rebuild demonstration program contains code that performs a call to fhrebuild to rebuild the corrupt file. Before running this utility, the file rebuild.reb must exist. To run this program, type:
cobrun rebuild.int
The validate.inf parameter file provides parameters that enable fhinfo to obtain file information on the file corrupt. To run this utility, type:
fhinfo -rv validate.inf
The demo4 demonstration program uses fhconvert to convert a file.
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.
The convert demonstration program creates and writes records to an indexed file containing fixed length records. This file has data compression and key compression active. To create the file demofile4, type:
cobrun convert.int
The convert.int parameter file enables fhinfo to obtain information about the data and index of the demofile4:
fhinfo -rv convert.inf
The convert.rel parameter file enables fhconvert to convert the indexed file demofile4 to a relative file, demofile8:
IN demofile4 # Input indexed file IE # no .dat extension IT I3 # Input type ON demofile8 # Output filename 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
The convert.seq parameter file enables fhconvert to convert the indexed file demofile4 to the sequential file demofile6. The parameters are:
IN demofile4 # indexed input file IE # no .dat IT I3 # Input type ON demofile6 # output filename 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
The convert.lsq parameter file enables fhconvert to convert the indexed file demofile4 to the line sequential file demofile7:
IN demofile4 # indexed input file IE # no .dat IT I3 # Input type ON demofile7 # output filename 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
The convert.ind parameter file enables fhconvert to convert the compressed indexed file demofile4 to the uncompressed indexed file demofile5:
IN demofile4 # indexed input file IE # no .dat IT I3 # Input type ON demofile5 # output filename OT I3 # output type OE # no .dat extension OF 20 # fixed length records of 20 bytes
To convert demofile4 to an uncompressed indexed file, type:
fhconvert -rv convert.ind
The demo5 demonstration program uses fhreorg to reorganize an indexed file on a specified key, 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 used.
Run the reorg1.cbl demonstration program by typing:
cobrun reorg1.int
This creates an indexed file, demofile9 with fixed length records and one alternate key. The program writes four records and the contents of the keys are displayed as they are written.
The reorg.reo parameter file is used by fhreorg to create a copy of demofile9 called demofile10 with the data portion of the file organized on ascending alternate key 1:
IN demofile9 # filename of file to be reorganized IE # no .dat extension IT I0 # indexed fixed KO 0 # ascending KN 2 # key-2 (alternate key 1) ON demofile10 # filename of reorganized file OT I0 # indexed fixed OE # no .dat extension PK (0:4:CHARTYPE) # prime key
Run the fhreorg utility by typing:
fhreorg -crv reorg.reo
Running reorg2 is equivalent to entering the command fhreorg
-crv reorg.reo. To run the program, type:
cobrun reorg2.int
The reorg3 demonstration program reads the data portion of the reorganized file demofile10 as a relative file and displays the records as they are read. To run the program, type:
cobrun reorg3.int
As you can see, the records are now displayed in reverse order.
This example parameter file below converts a relative file to a C-ISAM file.
All parameters can be specified in upper or lower case (except path and filenames which are case sensitive). Tab characters and spaces are interchangeable. There is no significance in the order in which the parameters are written.
# parameter file used to convert a relative file to an indexed file # input parameters IN rel-file # input file name IT R0 # input file type - relative ID 0 # LF record delimiter IF 240 # fixed record length
# Output parameters
ON /pathname/isam-file # output file name
OT I0 # output file type - C-ISAM
OV 200/240 # Variable record length 200 min/240 max
OB 511 # block size (optional)
PK D(129:29:Chartype) # Prime key description
# key can have duplicates
# start byte is 129
# key length is 29
# key type is CHARTYPE
AK C (160 4:CHARTYPE) # Alternate key description
# key has compression
# start byte is 160
# key length is 4
# key type is CHARTYPE
AK (164:10*CHARSIZE:CHARTYPE) # Alternate key description
# start byte is 164
# key length is CHARSIZE*10
# key type is CHARTYPE
DC 001 # data compression type 1 for
# output ISAM file
# (This will automatically
# change OT from I0 to I3)
#------------------ end of parameter file ------------------
This section lists the error messages displayed by the file handler utilities. In addition to the error message, further information may be displayed, as follows:
You have included more than one record specifying the block size in the parameter file.
filename
either because you do not have permission to create a file in the
current directory, or there is an error in the information to convert or
create the file. filename
either because you do not have permission to create a file in the
current directory, or there is an error in the information to convert or
create the file. filename
either because you do not have permission to create a file in the
current directory, or there is an error in the information to convert or
create the file. filename
either because you do not have permission to create a file in the
current directory, or there is an error in the information to convert or
create the file. filename for one of
the following reasons:
filename is either not
in the current directory or is in some other way inaccessible. filename cannot be opened for one of
the following reasons:
filename cannot be opened for
one of the following reasons:
filename cannot be
opened for one of the following reasons:
filename cannot be opened
for one of the following reasons:
filename cannot be opened for
one of the following reasons:
filename cannot be opened
for one of the following reasons:
-r
flag in the command line, which will delete any existing configuration
file. filename.
This could be because the key already exists. No index has been added.
filename
has not been deleted. This may be because you tried to delete the
primary index. filename, and for some reason this has been
unsuccessful. The file cannot be rebuilt. filename, this could be because the file is
corrupt, or has been locked by another user. filename cannot be read for one of the
following reasons:
filename cannot be removed.
filename
because the file is corrupt, or has been locked by another user or is in
some other way inaccessible. You have included more than one record giving the file name in the parameter file.
You have included more than one record giving the file type in the parameter file.
You have given a record length for a fixed length file as well as for a variable length file for the input file. You can only specify one of these for a file. The file can be either fixed length or variable length but not both.
You have given a record length for a fixed length file as well as for a variable length file for the output file. You can only specify one of these for a file. The file can be either fixed length or variable length but not both.
You have included more than one record giving the length of record for a fixed length file in the parameter file.
filename
is not valid for your operating system. filename, or the file has
already been locked by another user. The block size you have given in the parameter file is not valid.
The value of the input file record delimiter you have given in the parameter file is invalid.
The value of the output file record delimiter you have given in the parameter file is invalid.
You have specified more than one .dat extension for an input file.
The name you have used for the input file is invalid for your operating system.
The type of file you have specified for the type of input file either does not exist, or is invalid for the utility you are using.
The information you have given in the parameter file regarding the input file is invalid, the minimum record length exceeds the maximum record length.
You have given more than one record for the record delimiter in the input file specified in the parameter file.
You have used an invalid block size in your parameter file.
The type of file you have specified in the parameter file either does not exist or is invalid for the utility you are using.
The fixed record length you have included in the parameter file is invalid.
The variable record length you have included in the parameter file is invalid.
The key description you have included in the parameter file either is missing or does not contain the correct values.
The key type specified in the key description is not valid.
You have specified more than one NLS type record in the parameter file.
-f flag in your command line,
this must be followed by the name of a file. You have either failed to
include a filename, or the name you have used is not valid for the
operating system you are using. -p flag in your command line,
this must be followed by the name of a file. You have either failed to
include a filename, or the name you have used is not valid for the
operating system you are using. You have specified more than one .dat extension for the output file in the parameter file.
The information you have given in the parameter file regarding the output file is incorrect, the minimum record length exceeds the maximum record length.
The name of the output file you have given in the parameter file is invalid for your operating system.
The type of output file you have specified in your parameter file either does not exist or is invalid for the utility you are using.
You have specified more than one record for the record delimiter for the output file in the parameter file.
You have given more than one prime key description in a parameter file. An indexed file can only have one prime key.
You have included a record in your parameter file that is not recognized by the utility you are using.
You have given more than one record in the parameter file for the length of record in a variable length file.
Certain errors are associated only with C-ISAM and X/Open compliant files. Therefore, the following sections are divided between C-ISAM and X/Open compliant files and other file types.
Error numbers are from -1 to 99 for operating system errors and greater than 99 for other errors. Unlike the other file types, the errors are identified by the error number, rather than the status codes.
These error messages apply to LEVEL II indexed files and the indexed file format supported by this COBOL system, relative files, sequentia l and line sequential files. The errors are identified by the status values rather than the error number. Generally, the error number is set to zero if the call is successful, or -1 if the call fails.
If the error number is set to -1 the appropriate values are returned to the status variables: status1 and status2. There are two significant settings for status1:
| Setting |
Description |
|---|---|
| 5 | points to certain indexed errors. These are listed below. |
| 9 | points to errors for all file types including indexed. These correspond to file status codes and are listed in the appendix File Status Code Tables. |
Errors associated with indexed files set status1 to 5, then status2 to one of the following:
In future releases of Object COBOL Developer Suite, the file handler utilities will be replaced by Rebuild.
Listed below are the features of the file handler utilities, together with their equivalent Rebuild options. In most cases there is a one-to-one mapping of these features.
| fhinfo | Replaced by rebuild -n. Rebuild gives
organization, recording mode, record length, and key description whereas
fhinfo gave file information and index information. |
| fhrebuild | Replaced by rebuild filename ....
This is a direct equivalent. |
| fhvalidate | Replaced by rebuild -f. The new
interface provides greater functionality. For formats 3, 4 and C-ISAM,
it checks data file structure, free space list (FSL) structure, FSL
entries match data file, index file structure, index and data match and
checks all the keys against the data file. For other file formats, the
integrity checking is on the same level as fhvalidate. |
| fhconvert | Replaced by rebuild filename,filename....
It is a direct equivalent. |
| fhcreate | No equivalent in Rebuild. This function enabled you to create an empty indexed file. You must write a simple COBOL program to recreate this functionality. |
| fhreorg | Replaced by rebuild -x. This feature
enables you to reorganize an indexed file on any record key. This
differs from fhreorg in that fhreorg enabled you to reorganize ascending
or descending. |
| fhedit | This is replaced by the rebuild filename...
command line. With the -k option you can create your own key structure
as long as the key structure is wholly contained within the minimum
record length. |
As with the file handler utilities, Rebuild can be invoked using COBOL CALL syntax as well as from the command line. For further information on Rebuild, you should refer to the chapter Maintaining Files.
Copyright © 1999 MERANT International Limited. All rights reserved.
This document and the proprietary marks and names
used herein are protected by international law.
| Maintaining Files | Viewing and Editing Data Files | |