PreviousAccessing Mainframe Files Fileshare and CCINext"

Chapter 4: File Conversion Utilities

Mainframe Express supplies four utilities that help you move files between the mainframe and a PC:

Utility For use on: Function
MDECONV source files Converts downloaded files, that might contain embedded hexadecimal codes, from fixed-length sequential EBCDIC format to line sequential ANSI format
DFCONV data files Converts downloaded files to the format required on a PC
VRECGEN files containing variable-length records Modifies mainframe files into the format required on the PC so that they can be subsequently downloaded (supplied in source form for upload to the mainframe)
VRECGEN2 files containing variable-length records Modifies files uploaded from the PC into the format required on the mainframe (the reverse operation to VRECGEN, supplied in source form for upload to the mainframe)

Each of these utilities is described below. You can also find further information in the chapter Converting Data Files in your User's Guide.

4.1 MDECONV

The MDECONV utility converts files between fixed-length sequential EBCDIC format and line sequential ANSI format. It is intended for use by mainframe programmers who have used third-party utilities to download source files which contain embedded hexadecimal codes. If you use Mainframe Access to download the files, MDECONV is not required because Mainframe Access performs the appropriate conversion automatically.

MDECONV provides options for sensing whether a file is ANSI or EBCDIC and whether it contains non-text characters (NTCs). As conversion can be a lengthy process, it also provides options for handling errors, so that it can be run easily from batch files, or as a background task.

When MDECONV is processing a file, it flags as a non-text character (NTC) any character that is not represented in both the ANSI and EBCDIC character sets. NTCs might be the embedded hexadecimal codes you are trying to trap, they can be invalid characters, or they can be an indication that you are processing a file of the wrong character set. MDECONV enables you to specify what should happen when NTCs are encountered. In the ANSI character set, NTCs are defined as the characters outside the decimal range 32 to 126.

4.1.1 Operation

MDECONV is run from the Mainframe Express command line. The command line specifies which file is to be converted and provides directives to guide the processing of the file. If you want to process several files, you can specify the command lines in a file. This section explains the format of the command line. The following reference section gives details of the directives you can use.

4.1.1.1 Downloading Mainframe Files

All files to be used by MDECONV should be transferred between the mainframe and your PC as binary fixed-length sequential files. No carriage return /line feeds (CRLF) should be added or removed, nor any other translations or conversions performed. Ensure the correct options are set in your file transfer program to achieve this.

You should ensure that the logical record length (LRECL) directive is set to the same value as the logical record length on the mainframe file. This is necessary, as PC fixed-length sequential files do not contain information concerning the length of the records.

4.1.1.2 Converting Files Containing Non-Text Characters

After source code that contains NTCs has been converted, the values of the NTCs will appear to be corrupt when you debug the program on a PC. This is because the program uses the ANSI representation of the NTCs rather than the EBCDIC representation. To ensure that your program uses the EBCDIC representation, compile it specifying the CHARSET(EBCDIC) directive.

4.1.1.3 Invoking MDECONV

You invoke MDECONV from the command line. The command format is:

run mdeconv filespec1 [[to] filespec2][directives]

filespec1

identifies the file to be converted. It must contain at least the name of the file. If the location is omitted, the current location is assumed. If the extension is omitted, the appropriate default extension is used.

If an .ebt file is specified, MDECONV looks for the file specifications and directives in this file. Any parameters after filespec1 are ignored. .ebt files are described in the section Converting Several Files.

[to] filespec2

identifies the file to be created. It is optional. If it is omitted, the output file has the same name and location as filespec1, but the appropriate default extension is used. If filespec2 is supplied without a location, the location of filespec1 is assumed. If it is supplied without an extension, then the appropriate default is used.

The to parameter is optional.

directives

are directives affecting the behavior of MDECONV. See the section Directives later in this chapter for information on these directives.

4.1.1.4 Converting Several Files

If you want to convert several files, the name of the files can be entered into an .ebt file. This file contains a list of files to convert, with any directives required. Its format and contents are identical to the command line parameters, with the following exceptions:

Example

run mdeconv test.ebt

where test.ebt contains:

ans prog1 ntc:warn

prog2.cbl to ebc prog3

prog4 ans extans:cbl

performs the following:

4.1.1.5 Interrupting the Conversion

The conversion can be interrupted by pressing Ctrl+Break.

4.1.1.6 Using the MDECONV Environment Variable

The MDECONV environment variable can contain default directives for MDECONV. It should be set using the operating system SET command and should contain a string of directives, separated by commas instead of spaces.

Example

set mdeconv=lrecl:72,extebc:cbl

This sets the default logical record length to 72, and the default EBCDIC extension to .cbl. With these defaults, the input ANSI file is overwritten. This command could be included in your autoexec.bat file (refer to your operating system manual for more details).

Note: You cannot use an equals (=) character in environment variable definitions, so

set mdeconv=lrecl=2

is invalid.

4.1.2 Directives

This section describes the directives that are set by default, and then describes each directive in turn.

4.1.2.1 Default Directives

The default extensions used for filespec1 and filespec2 depend on the direction of conversion.

The ANSI extension (which can be set using the EXTANS directive, described below) is used for filespec1 when converting from ANSI to EBCDIC, and for filespec2 when converting from EBCDIC to ANSI.

The EBCDIC extension (which can be set by the EXTEBC directive, described below) is used for filespec1 when converting from EBCDIC to ANSI, and for filespec2 when converting from ANSI to EBCDIC.

By default, the ANSI extension is .cbl, and the EBCDIC extension is .ebc. So, by default:

run mdeconv ebc prog

converts prog.cbl to prog.ebc, and:

run mdeconv ans prog

converts prog.ebc to prog.cbl.

4.1.2.2 Command Line Directives

Some of the directives have values. You can use a colon (:) or equals (=) character to separate a directive from its value. For example, LRECL:77 is the same as LRECL=77.

The directives which can be specified for MDECONV are listed in the table below.


ANS and EBC

Specifies the direction of conversion. ANS causes the file to be converted from EBCDIC to ANSI. EBC causes the file to be converted from ANSI to EBCDIC.

Syntax
ANS or EBC
Parameters

None

Default

ANS


BAD

Controls whether MDECONV is to check for invalid characters in the input file and what action to take if it finds an invalid character.

Syntax
BAD:setting
Parameters

setting is one of the following:

ABORT Abort the current conversion and stop.
FAIL Fail the current conversion, go onto the next one.
OFF Do not check for invalid characters.
USER Ask the user (Continue, Fail, Abort).
WARN Warn the user and continue.

It can be abbreviated to A, F, O, U, or W.

Default

BAD:USER


ERR

Specifies the action to be taken when an error occurs.

Syntax
ERR:setting
Parameters

setting is one of the following:

ABORT Abort the current conversion and stop.
FAIL Fail the current conversion, go onto the next one.
USER Ask the user (Retry, Fail, Abort).

It can be abbreviated to A, F, or U.

Default

ERR:USER


EXTANS

Sets the default ANSI extension to extension. Whenever an extension for an ANSI file (either the input file in an ANSI to EBCDIC conversion, or the output file in an EBCDIC to ANSI conversion) is omitted, this default extension is used.

Syntax
EXTANS:extension
Parameters

extension is any valid extension.

Default

EXTANS:CBL


EXTEBC

Sets the default EBCDIC extension to extension. When an extension for an EBCDIC file (either the input file in an EBCDIC to ANSI conversion, or the output file in an ANSI to EBCDIC conversion) is omitted, this default extension is used.

Syntax
EXTEBC:extension
Parameters

extension is any valid extension

Default

EXTEBC:EBC


LRECL

Sets the logical record length of the fixed-length sequential EBCDIC file being read or written.

Syntax
LRECL:nnn
Parameters

nnn must be in the range 6 to 255

Default

LRECL:80


NTC

Controls whether MDECONV is to check for non-text characters (NTC) in the input file and what action to take if it finds an NTC.

Syntax
NTC:setting
Parameters

setting is one of the following:

ABORT Abort the current conversion and stop.
FAIL Fail the current conversion, go onto the next one.
OFF Do not check for non-text characters.
USER Ask the user (Continue, Fail, Abort).
WARN Warn the user and continue.

It can be abbreviated to A, F, O, U, or W.

The difference between FAIL and ABORT is apparent only in .ebt files. FAIL enables all following conversions to proceed, while ABORT stops immediately. .ebt files are described in the section Converting Several Files earlier in this chapter.

Default

NTC:OFF


4.1.3 MDECONV Error Messages

Most of the messages and errors given are self-explanatory, but you should note the following:

4.1.3.1 File errors

In general, any file errors, except "file not found" are given as their Micro Focus file status error and when they occurred (for example opening a file). In normal use, they should not occur.

Incorrect Logical Record Length

This message is given when a sequential file is opened for input and is incompatible with the current logical record length. If you continue from this error, the part record at the end of the file is also written to the output file. In general, this happens when LRECL is set to the wrong value; you should not proceed with the conversion. This error also often occurs when converting a line sequential ANSI file to EBCDIC.

Warning: file contains ANSI characters

Warning: file contains EBCDIC characters

When either of these errors occur, the conversion which is taking place is likely to be in the wrong direction. The method used to ensure a file contains ANSI or EBCDIC characters is generally reliable for most text files, so you should think carefully before proceeding with the conversion because you will probably find invalid characters in the output file.

NTC found in record : nnnnnn at column : nnn

xxxxxx non-text character found

An EBCDIC or ANSI non-text character has been found, depending on the conversion direction.

4.2 DFCONV

The DFCONV utility, also known as the Data File Converter, converts data files. DFCONV is a command line utility. To find out more about the GUI version of the Data File Converter, see the chapter Converting Data Files in your User's Guide.

The utility provides a batch and called program interface to enable conversion of file formats, organizations and data formats and reorganization of indexed files using data file conversion profiles.

Use the Data File Converter :


Note: In order to convert between character sets on records with non-text data items; that is, COMPUTATIONAL data and numeric data, you must have previously created a record layout file. For more information on record layout files, see the chapter Using Record Layouts with Data Files in your User's Guide.


4.2.1 Processes Involved

The following three figures show the processes involved in data and file conversion.

The Profile file contains information about the conversion process. The information in the profile file can be modified for similar conversion processes. A profile file is required for each conversion using the batch or called program interface.

A
Figure 4-1: EBCDIC to ANSI Conversion

A
Figure 4-2: ANSI to EBCDIC Conversion

A
Figure 4-3: File Reorganization

4.2.2 Operation

The following sections describe the Data File Converter operations:

4.2.2.1 Command Line Batch Interface

The command line is:

run dfconv profile-fname [input-fname] [output-fname]

where:

profile-fname is the name of the profile file which contains the details of the task you want to perform (see the section Defining File Conversion with a Profile File later in this chapter).
input-fname is optional and is the name of the input file.
output-fname is optional and is the name of the output file.

The input and output filenames are optional as they can be extracted from the profile file. If you specify filenames on the command line as well as in the profile file, those on the command line take precedence.

After conversion, the operating system error level (ERRORLEVEL) is set to non-zero if an error occurred during conversion. If you are running the conversion from a batch file, you can interrogate this to determine what action to take after the conversion.

4.2.2.2 Call Batch Interface

If a profile for a conversion exists you can invoke the Data File Converter to do the conversion using the following interface:

call dfconv using dfconv-params

where:

 01 dfconv-params.
     03 profile-filename    PIC X(65).
     03 input-filename      PIC X(65).
     03 output-filename     PIC X(65).

and:

profile-filename is the name of the profile file containing the details of the data file conversion (see the section Defining File Conversion with a Profile File later in this chapter).
input-filename is the name of the input file
output-filename is the name of the output file.

If you specify filenames in the parameter fields as well as in the profile file, those in the parameter fields take precedence.

On return from the Data File Converter, RETURN-CODE is set to non-zero if an error occurred, and the error number is returned in the profile-filename field.

4.2.3 Using the Data File Converter

The following sections describe how to use the Data File Converter to convert data files and rebuild file indexes.

4.2.3.1 File Format and Data Conversion

Converting files from one format to another enables data to be restructured from one format to another. For example, you can convert from sequential organization to indexed organization. You can also add extra secondary indices as the needs of an application change. When using the Data File Converter, you do not need to recreate data already produced or write special conversion programs.

The Data File Converter also provides a facility to convert mainframe report files so that you can print them from a PC.

One of the major inhibitors to data transfer between the mainframe and the PC can be the inability to translate complex file structures between the IBM mainframe data format of EBCDIC (Extended Binary Coded Decimal Interchange Code) and the PC data format of ANSI (American National Standards Institute).

The File Converter environment addresses this problem for the development environment by enabling the file to remain in EBCDIC format even though it is being used by ANSI programs. However, you might need to have the data file translated to ANSI. This is normally because the data needs to be accessed by some software outside this system which does not handle EBCDIC data, or because the program needs to access other files which are in ANSI format, for example a database system.

Although many file transfer packages convert files from one format to another, they are restricted to converting the whole file to the other data format. Typical data files and database records have complex record structures with a mix of text and binary data that must be translated accordingly. The Data File Converter provides an easy method for data conversion using record layout descriptions (see the chapter Using Record Layouts with Data Files in your User's Guide).

The Data File Converter can also convert internal floating-point formats between IEEE format and S/370 format.

4.2.3.2 EBCDIC to ANSI Conversion

A mainframe file should be transferred to the PC in binary format. If this file is initially a variable-length indexed file, you can use the mainframe program VRECGEN to perform an initial reformat of the file on the mainframe. The file can then be downloaded and processed by the Data File Converter.

4.2.3.3 Mainframe to PC Print Conversion

A mainframe report format file is a file downloaded to the PC from the mainframe or a file created by an application, downloaded to the PC and run on the PC.

A mainframe report format contains carriage-control characters which are converted by the Data File Converter to PC printable formats. When defining the mainframe report files, the record length includes the carriage-control character and the records must be fixed length. In PC Print files, the record length is solely the data length.

You can print the PC print format files on any standard ANSI printer capable of printing 132 characters per line. As some ANSI printers print only 80 characters per line, you might have to print your files in compressed mode to achieve this.

If you specify the input file as a mainframe report format file, but it was created on the PC using a downloaded mainframe application, you may receive error message 139, Input file not "real" mainframe report format. This can occur if the printer output has been created in PC format rather than the mainframe report format. Check directives used to control the compilation and execution of the program.

The Data File Converter provides specific support for conversion between Mainframe Report files and PC Print files. Conversion to or from these formats to other formats is not supported.

4.2.3.4 Indexed File Reorganization

As indexed files are updated by adding, deleting and altering records, the index and data structures become disjointed, making processing less efficient. In addition, space left by deleted records is not always reused, making the file bigger than it needs to be. After a large number of changes have been made, it is worth reorganizing an indexed file. By ensuring that the input and output file settings are identical, the data and indices can be rebuilt in an ordered sequential manner, reclaiming any free space, and so providing optimum file performance and integrity.

4.2.3.5 Defining File Conversion with a Profile File

This section describes the entries required in the profile file to convert a file, or to restructure a file from one organization to another. For example, you might want to add extra secondary indices to an indexed file, or to convert a sequential or relative file to an indexed file, or convert an indexed file to a relative file.

DFS Profile File Version  V09.B01.07

Batch-Process: Convert-file
                   ***************************************************
                   *           (Twin)                  (Single)      *
                   * Options:  Convert-File            Rebuild-index *
                   *           Rebuild-index-and-data  None          *
                   ***************************************************
Strt-file:              drive:\path\filename.STR
Edit-Mode:     Quick
                   * Options:  Quick/Full                            *
--------------------------------------------------------------------------------
Input-File     drive:\path\inputfile.dat
   Format:         Micro-Focus
                       * Options:  Micro-Focus         IDXFORMAT(4)  *
                       *           Btrieve             C-ISAM        *
                       *           LEVEL-II            ESDS          *
   Organization:   VRECGEN
                       * Options:  Sequential  Line-Sequential       *
                       *           Indexed     Mainframe-Report-ANSI *
                       *           Relative    Mainframe-Report-mach *
                       *           VRECGEN     PC-Print              *
   Record-Format:  Variable
                       * Options:  Fixed/Variable                    *
   Character-Set:  EBCDIC
                       * Options:  ASCII/EBCDIC                      *
   Floating-Point: 370
                       * Options:  IEEE/370                          *
   Compression:    Off
                       * Options:  On/Off                            *
   Min-Rec-Length: 352
   Max-Rec-Length: 633
--------------------------------------------------------------------------------

Output-File    drive:\path\outputfile.dat
   Format:         Micro-Focus
   Organization:   Indexed
                       * Options:  Sequential  Line-Sequential       *
                       *           Indexed     Mainframe-Report-ANSI *
                       *           Relative    PC-Print              *
                       *           VRECGEN2                          *
   Record-Format:  Variable
   Character-Set:  EBCDIC
   Floating-Point: 370
   Compression:    Off
   Min-Rec-Length: 352
   Max-Rec-Length: 633
                       * Key to settings                             *
                       *       d=      allow duplicates              *
                       *       s=      sparse character set          *
                       *       Compression                           *
                       *           cd= on duplicates                 *
                       *           cl= on leading spaces             *
                       *           ct= on trailing spaces            *
   Prime-key :   1:1, 2:6

   Alt-Key  1:   8:1
                 d,cl
   Alt-Key  2:   9:1
                 d,cd,ct
   Alt-Key  3:   10:5

The first record in the file identifies the format of the profile file. The profiles used by DFCONV are the same format as used with earlier Workbench products.

4.2.3.5.1 Specifying the Conversion Operation

The operation to be performed is selected as a parameter to the Batch-Process option.

Batch-Process Selects the operation to be performed on the defined file(s):

Convert-file
Rebuild-index
Rebuild-index-and-data

An Input-File is defined for all operations and an Output-File is defined for Convert-file and Rebuild-index-and-data. The Rebuild-index operation recreates the file index for the input data file so an Output-File description is not required.

Strt-file Selects the file containing the Record Layout descriptions for the input file.

No-structure
location\filename.str

If the data file is being converted between EBCDIC and ANSI and the records contain non-text data items then a record layout description is required to define the data items requiring conversion and those to be left unconverted (for example, binary values). The record layouts are created with the Record Layout Editor and stored in files with an .str file extension.

Edit-Mode Selects the edit mode if this profile is read by the Data File Editor

Quick
Full

This parameter is not used by DFCONV.

4.2.3.5.2 Specifying the Input File parameters

Input-File Selects the input file name for the defined operation.

You then describe the file with the following parameters:

Parameter
Description
Format Selects the file format for the input file.

Micro Focus
ESDS
Btrieve
IDXFORMAT(4)
C-ISAM
LEVEL-II

The default format is Micro Focus and this would normally be used for files downloaded from the host and recreated on the PC. If the selected file is an emulation of the mainframe VSAM entry-sequenced data set then ESDS should be selected as this provides the emulation of VSAM ESDS on the PC.

Organization Selects the file organization for the input file.

Line sequential
Sequential
Indexed sequential
Relative
VRECGEN
ANSI Mainframe Report (The mainframe report with ANSI carriage control characters)
Machine Mainframe Report (The mainframe report with machine code carriage control characters)
PC Print.

Record-Format Selects the record format for the input file.

Fixed
Variable

Note: Variable length Mainframe Report files are not supported.

Character-Set Selects the character encoding used in the input file.

ASCII
EBCDIC

Note: The character encoding used in Mainframe Express are EBCDIC and ANSI. ASCII is used in earlier Workbench products but represents ANSI in this utility.

Floating-Point Selects the type of floating point format that is used in the input file.

IEEE
370

Compression Indicates use of data compression for the input file.
Available settings are:

On
Off

Note: this should only be set to On if the file was created with data compression.

Min-Rec-Length Sets the minimum record length for the input file.

If the file is fixed length this should be set to the same value as the maximum record length.

Max-Rec-Length Sets the maximum record length for the input file.

If the file being created is indexed, the keys are defined using the following records.

Prime-key Sets the start position (column) and length of the prime key.

position:length (for example, 1:12). A colon is used to separate the position and length fields.

A second record in the profile file sets the key flags required for the indexed file being created. The flags are separated by a comma (for example: d,cd).

d allow duplicate record keys
s sparse character - not supported
cd compress duplicate record keys
cl compress leading spaces on record keys
ct compress trailing spaces on record keys

4.2.3.5.3 Specifying the Output File
Output-File Sets the output file name for the defined operation.

You then describe the output file with the following parameters:

Parameter
Description
Format Sets the file format for the output file.

Micro Focus
ESDS
Btrieve
IDXFORMAT(4)
C-ISAM
LEVEL-II.

The default format is Micro Focus and this would normally be used for files created on the PC. If the file is required to be an emulation of the mainframe VSAM entry-sequenced data set, then ESDS should be selected as this provides the emulation of VSAM ESDS on the PC. For VSAM KSDS and RRDS, select Micro Focus format.

Organization Sets the file organization for the output file.

Line sequential
Sequential
Indexed sequential
Relative
VRECGEN2
ANSI Mainframe Report (The mainframe report with ANSI carriage control characters)
PC Print.

Record-Format Sets the record format for the output file.

Fixed
Variable

Note: Variable length Mainframe Report files are not supported.

Character-Set Sets the character encoding to be used in the output file.

ASCII
EBCDIC

Note: The character encodings used in Mainframe Express are EBCDIC and ANSI. ASCII is used in earlier Workbench products but represents ANSI in this utility.

Floating-Point Sets the type of floating point format that is used in the output file.

IEEE
370

Compression Selects use of data compression for the output file.

On
Off

Min-Rec-Length Sets the minimum record length for the output file.

If the file is fixed length this should be set to the same value as the maximum record length.

Max-Rec-Length Sets the maximum record length for the output file.

If the file being created is indexed the keys are defined using the following records.

Prime-key Sets the start position (column) and length of the prime key.

position:length (for example, 1:12). A colon is used to separate the position and length fields.

A second record in the profile file sets the key flags required for the indexed file being created. The flags are separated by a comma (for example: d,cd).

d allow duplicate record keys
s sparse character - not supported
cd compress duplicate record keys
cl compress leading spaces on record keys
ct compress trailing spaces on record keys

Alternate keys are defined following the prime key by using "Alt-Key 1:" as the key word for the first alternate key and "Alt-Key 2:" for the second alternate key. The format of the two records in the profile file defining the alternate keys are as defined for the Prime key.

You are allowed to define up to 63 alternate record keys by specifying for each the POSITION and LENGTH in the record and whether duplicate values are permitted. Each key can be split and you can define overlapping keys.

Split keys are defined by including multiple POSITION and LENGTH definitions within the key definition record separated by comma and then a space (for example, 1:12, 20:5).

4.2.3.5.4 General Conversion Information

You should be aware of the following points when defining the input and output files:

4.2.3.6 File Rebuild

The interface to Rebuild from the Data File Converter supports the rebuilding of corrupt indices.

DFS Profile File Version  V08.U04.01

Batch-Process: Rebuild-index
                   ***************************************************
                   *           (Twin)                  (Single)      *
                   * Options:  Convert-File            Rebuild-index *
                   *           Rebuild-index-and-data  None          *
                   ***************************************************
Strt-file:     No-structure
Edit-Mode:     Quick
                   * Options:  Quick/Full                            *
--------------------------------------------------------------------------------
Input-File     e:\test\testidx.dat
   Format:         Micro-Focus
                       * Options:  Micro-Focus         IDXFORMAT(4)  *
                       *           Btrieve             C-ISAM        *
                       *           LEVEL-II            ESDS          *
   Organization:   Indexed
                       * Options:  Sequential  Line-Sequential       *
                       *           Indexed     Mainframe-Report-ANSI *
                       *           Relative    Mainframe-Report-mach *
                       *           VRECGEN     PC-Print              *
   Record-Format:  Variable
                       * Options:  Fixed/Variable                    *
   Character-Set:  ASCII
                       * Options:  ASCII/EBCDIC                      *
   Floating-Point: IEEE
                       * Options:  IEEE/370                          *
   Compression:    Off
                       * Options:  On/Off                            *
   Min-Rec-Length: 352
   Max-Rec-Length: 633
                       * Key to settings                             *
                       *       d=      allow duplicates              *
                       *       s=      sparse character set          *
                       *       Compression                           *
                       *           cd= on duplicates                 *
                       *           cl= on leading spaces             *
                       *           ct= on trailing spaces            *
   Prime-key :   1:1, 2:6

   Alt-Key  1:   8:1
                 d
   Alt-Key  2:   9:1
                 d

The Rebuild function can be used for rebuilding indexed sequential files only. To rebuild other file formats, use the file conversion function with identical settings for the input and output files.

4.2.3.6.1 Recovery of Corrupt Indexed Files

Indexed files that have a corrupt index can be recovered using this option. Indices can become corrupt if, for example, a power loss occurs when a program has opened and changed an indexed file, but has not yet closed it. A flag indicating that this has occurred is detected in the file and reported by subsequent accesses to that file. No further operations can be done on the file until its integrity has been recovered.

Rebuild rebuilds just the index, which is all that is required for the recovery. If the index is already in existence, Rebuild attempts to recover the index using the information in that file.

As an alternative to DFCONV, you can use the FixFile utility to rebuild indexed files. This is described in the chapter Rebuilding Corrupt Indexed Files in your User's Guide.

4.2.3.6.2 General Rebuild Information

You should be aware of the following points when using Rebuild:

4.2.4 Data File Converter Error Messages

The error messages are described in the online reference help supplied with Mainframe Express.

4.3 VRECGEN

VRECGEN is a mainframe utility that enables you to create a copy of a variable-length mainframe file which embeds record length information in the data records for download from the mainframe to the PC. The source code for the VRECGEN utility (vrecgen.cbl) is provided by MERANT, but you might need to modify it before use, in order to specify options not catered for by the supplied version of vrecgen.cbl.

The file created by VRECGEN has a two-byte record length field preceding each of the variable length data records. The record length field contains a value which is the two-byte record length field plus the length of the variable length data record. This is necessary because most file transfer software (for example, IBM SEND/RECEIVE) works with logical records and strips off the "Record Descriptor Word" which contains the length for each record. Without this information, it is impossible to separate the records to rebuild the data set on the PC.

The file created by VRECGEN is in a special download format and should be transferred to the PC in binary format using the standard Transfer utility. The file can then be processed through the Data File Converter.


Note: The source code to VRECGEN (vrecgen.cbl) is provided by MERANT primarily as a model, rather than as a final utility that meets the needs of all sites without modification. You should edit your version of vrecgen.cbl so that it contains the specific values that meet your application or site requirements. A typical reason for editing vrecgen.cbl is to increase the maximum record length to be more than 32,000 bytes.


4.3.1 Installing the VRECGEN Program

If you plan to download variable-length test files, you must first upload and compile the VRECGEN program in your mainframe environment. This program is provided as a sample COBOL program for converting mainframe variable-length format files.


Note: Each site should review the provided source code and determine maximum and minimum lengths for its variable-length files. These values (plus 4 for the MVS "Record Descriptor Word") should be used in the OCCURS DEPENDING ON clause of the record descriptions in the sample FDs.


The source code file for VRECGEN is copied onto the PC as part of the installation procedure; the file name is vrecgen.cbl and it is copied to the mfe\mfide\source directory.

After you install Mainframe Express, upload the vrecgen.cbl file to the mainframe, specifying conversion from ANSI to EBCDIC. Verify that the file is in fixed file, 80-byte card image format.

Compile VRECGEN on your mainframe using your COBOL Compiler.

The following options should be specified when compiling this program. Some are compiler options, some run-time options, and some are link-edit options. Use only those applicable to your specific environment and compiler:


Note: If you use VS COBOL II, Release 3 or above, and receive a file status of 39, recompile VRECGEN using the CMPR2 compile option.


4.3.2 Running the VRECGEN Program

You need to supply the appropriate JCL information before running the VRECGEN on the mainframe. Enter the following JCL skeleton pointing to the correct STEPLIB, input data set, and output data set:

//MYJOB   JOB (ACCOUNTING INFORMATION)
//STP1    EXEC PGM=VRECGEN
//STEPLIB DD DSN=STEPLIB,DISP=SHR
//SYSOUT  DD SYSOUT=*
//INPDD   DD DSN=INPUT.OS.DATA.SET.DISP=SHR
//OUTDD   DD DSN=OUTPUT.OS.DATA.SET,
//        DISP=(NEW,CATLG,DELETE),
//        DCB=(RECFM=VB,LRECL=LLL,BLKSIZE=BBB),
//        SPACE=(TRK,(X,Y),,RLSE),
//        UNIT=SYSDA

Note: When you fill in the LLL (LRECL) and BBB (BLKSIZE) values for the output file, refer to the values specified in the FD for OUTDD in your version of VRECGEN. The default LRECL and BLKSIZE from the program is 32700, but must be changed so that the JCL, FD in VRECGEN, and file-label on the input file are consistent.

The resulting output files are in the special download format, ready to be transferred to the PC using the standard transfer facility. Be sure, when you do the download, to specify a binary transfer and not to use the carriage control characters, CR (carriage return) and LF (line feed).

4.4 VRECGEN2

VRECGEN2 is a mainframe utility that converts files in Micro Focus variable-length record format to mainframe format. Thus it enables you to upload these files and use them on the mainframe.

4.4.1 Installing and Running VRECGEN2

VRECGEN2 is copied into the mfe\mfide\source directory during installation. If required, you should upload it to the mainframe in the same way as VRECGEN.

The following steps show you how to upload a variable length data file whose records are between 100 and 400 bytes long. It assumes you have already uploaded vrecgen2.cbl (using CRLF and ANSI as parameters).

  1. Convert your variable-length PC file to VRECGEN2 output format using the Data File Converter, specifying the minimum and maximum record lengths as 100 and 400 respectively. Note that because the Data File Converter prepends two bytes containing the record length, the actual minimum and maximum lengths are 102 and 402 respectively. If the file is in ANSI format, you should also convert it to EBCDIC format at the same time.

  2. On the mainframe, allocate a data file to receive the file from the PC. Use the following parameters:

    FORMAT = VB

    RECLEN = 406

    BLKLEN = 410

  3. Upload the file. Don't set CRLF insertion, and if you converted to EBCDIC at step 1, don't specify ANSI.

  4. Change the source of vrecgen2.cbl on your mainframe so that the FD for the output file matches the format of the required mainframe data file.

  5. Compile and link vrecgen2.cbl.

  6. Run VRECGEN2. The JCL is the same as for VRECGEN, except for the following changes:

A valid variable length file should result as the output. The following shows the format of a VRECGEN2 format file, using a record length of 100 bytes as an example:

Bytes
Contents
1-4 Record descriptor word.
5-6 Record length.
7-106 Record data. The record is padded with null bytes if it is shorter than the maximum record size.

The VRECGEN and VRECGEN2 file formats are incompatible in that VRECGEN format is used to download files from the mainframe and VRECGEN2 format is used to upload Micro Focus format files to the mainframe.


Copyright © 1999 MERANT International Limited. All rights reserved.
This document and the proprietary marks and names used herein are protected by international law.

PreviousAccessing Mainframe Files Fileshare and CCINext"