Figure 4-1: EBCDIC to ANSI Conversion
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.
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.
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.
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.
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.
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.
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:
to parameter must be used when filespec2
is required.
filespec1
and any directives, until it encounters filespec2.
If a to has been specified, it converts filespec1
to filespec2. Otherwise, it converts filespec1
to its default and then treats filespec2 as the
next filespec1.
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:
The conversion can be interrupted by pressing Ctrl+Break.
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=2is invalid.
This section describes the directives that are set by default, and then describes each directive in turn.
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.
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.
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.
ANS or EBC
None
ANS
Controls whether MDECONV is to check for invalid characters in the input file and what action to take if it finds an invalid character.
BAD:setting
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.
BAD:USER
Specifies the action to be taken when an error occurs.
ERR:setting
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.
ERR:USER
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.
EXTANS:extension
extension is any valid extension.
EXTANS:CBL
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.
EXTEBC:extension
extension is any valid extension
EXTEBC:EBC
Sets the logical record length of the fixed-length sequential EBCDIC file being read or written.
LRECL:nnn
nnn must be in the range 6 to 255
LRECL:80
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.
NTC:setting
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.
NTC:OFF
Most of the messages and errors given are self-explanatory, but you should note the following:
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.
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.
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.
An EBCDIC or ANSI non-text character has been found, depending on the conversion direction.
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.
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.
Figure 4-1: EBCDIC to ANSI Conversion
Figure 4-2: ANSI to EBCDIC Conversion
Figure 4-3: File Reorganization
The following sections describe the Data File Converter operations:
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.
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.
The following sections describe how to use the Data File Converter to convert data files and rebuild file indexes.
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.
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.
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.
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.
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.
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 |
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 |
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 |
This parameter is not used by DFCONV.
| Input-File | Selects the input file name for the defined operation. |
You then describe the file with the following parameters:
If the file being created is indexed, the keys are defined using the following records.
| Output-File | Sets the output file name for the defined operation. |
You then describe the output file with the following parameters:
If the file being created is indexed the keys are defined using the following records.
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).
You should be aware of the following points when defining the input and output files:
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.
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.
You should be aware of the following points when using Rebuild:
The error messages are described in the online reference help supplied with Mainframe Express.
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 Micro Focus, 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 Micro Focus 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.
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.
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).
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.
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).
FORMAT = VB
RECLEN = 406
BLKLEN = 410
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 © 2001 Micro Focus International Limited. All rights reserved.
This document and the proprietary marks and names
used herein are protected by international law.