/ebcdic-t.txt

Large files files are truncated, but you can click here to view the full file

        Documentation for the EBCDIC Conversion Package (Trial Level 2)

        ---------------------------------------------------------------

                Written by: Ted Green and Thomas C. Burt

                Last change:   10/16/2003





Introduction

------------



The VEDIT Level-2 EBCDIC package converts EBCDIC files into ASCII with any

number of packed-decimal, binary, zoned, text and "ignore" fields.



The converted ASCII records can optionally have newline characters, e.g.

Carriage-Return and Line-Feed, appended to the end of each converted record.

They can also be output in DBASE format, with the DBASE header record being

automatically generated.



Other output options include quoting-and-comma delimiting each field or

appending a user specified delimiter string after each field; converting an

all-blank or null numeric field to zeros; and emitting an explicit decimal

point.



For EBCDIC to ASCII conversions, the converted file is normally saved as

"filename.ASC"; for DBASE output, the default extension is ".DBF". Or, the

user may explicitly give the output filename. In no case is the source data

file altered. 



Any conversion errors can optionally be reported in the file "ebcdic.err".

This file is initially deleted; therefore, a batch file can test for its

existence to determine whether there were any errors.



The conversion is completely controlled by a ".LAY" data layout file which

the user must create once for each type of file to be converted. This layout

file primarily lists the beginning and ending columns for each field and the

data type of the field. It also specifies the record length and specifies

whether newline characters are to be appended to the end of each converted

record.



As described below, a COBOL "copy-book" can often be automatically converted

into a .LAY data layout file. Therefore, we highly recommend that you

procure the "copy-book" for your data file(s).



Once the .LAY data layout file has been created, the conversion macro can

be manually run from within VEDIT, or automatically run from either a

Window's icon or a DOS or NT command line. The macro runs without any user

interaction and, when done, saves the converted file and displays it on the

screen. Optionally, the macro can automatically exit, in which case the

conversion requires no user interaction whatsoever.



To convert many files, EBCDIC-T.VDM can be used with the menu function {MISC,

WILDFILE macro} to automatically convert entire groups of files, e.g. all

files in a directory.



The speed of the conversion depends both on the size of the file and the

number of packed fields per record. The conversion speed is typically 10

megabytes per minute on a 1000mhz Pentium.



NOTES:  A custom conversion can also be performed on any desired fields using

        a custom written VEDIT macro. This is described in more detail later.



        The conversion supports additional technical options which are

        not described here. Please examine the description at the beginning

        of the EBCDIC-T.VDM file for additional details. The following

        capabilities of the Level-2 package are not described here:

        *  Preprocessing and postprocessing.



        *  Appending or prefixing padding characters to any specified field.



        Greenview Data is available on a contract basis to perform any part

        of the conversion for you, including creating the data layout file or

        even translating the EBCDIC file(s) that you supply. If you do not

        have the packed field locations for your file, we can often examine

        the file and determine them for you.







EBCDIC Conversion Files

-----------------------



Assuming you chose to include the "EBCDIC conversion files" during

installation, you will have the following files in the VEDIT Home Directory,

e.g. in "c:\vedit" or "c:\program files\vedit":



EBCDIC-T.VDM    The trial version of the EBCDIC Level 2 conversion macro

		described here. (Do not modify this file).



EBCDIC-2.VCM    EBCDIC conversion submacros; used only by custom macros;

                loaded automatically during preprocessing if any custom

                field ("c") is encountered. (Do not modify this file).



COBOL2V.VDM     The COBOL copy-book preprocessor. This is used by

                EBCDIC-T.VDM. It may also be run independently. (Do not

                modify this file).



RELAY.VDM       Generate output column numbers from a data layout (.lay)

                file. Handles quoted-comma-delimited fields and user

                specified field separators. This is used by COBOL2V.VDM. It

                may also be run independently. (Do not modify this file).



REGPREP.VDM     Used by EBCDIC-T.VDM to streamline the macro code, making

                it run faster. (Do not modify this file).



EBCDIC.LAY      A simple prototype data layout file to help you get started.

                It supports EBCDIC files with uniform fixed-length records.



        NOTE:   You must edit this file, as described below, before

                converting any files.



COBOL.COP       A sample COBOL "Copy-Book" corresponding to sample data file

                COBOL.EBC.



COBMIX.LAY      A prototype data layout file produced from COBOL.COP, above.

                Includes some initial .LAY specifications.



COBOL.LAY       A prototype data layout file produced from COBMIX.LAY,

                above. Converted by COBOL2V.VDM and RELAY.VDM into standard

               .LAY format.



COBOLD.LAY      A prototype layout file to produce DBASE output.

                Not supplied. Generated as stated in "Quick DBASE Test", q.v.



COBOL.EBC       A small example EBCDIC file with a layout corresponding to

                COBOL.COP.



COBOL.ASC       The converted ASCII file made from the example COBOL.EBC

                file.



COBOL.DBF       The converted ASCII file in DBASE format made from COBOL.EBC

                via COBOLD.LAY.



EBCDIC-T.BAT    A batch file for automating the conversion process.

                Win 95/98/NT/2000/XP users can create a shortcut icon to this

                batch file for "drag and drop" conversion.



EBCDIC-T.TXT    This documentation file.



LEADZERO.CUS    An example of a custom macro for processing custom fields.

                This macro converts unpacked EBCDIC numbers to ASCII and then

                strips any leading zeroes. It optionally inserts a period

                before the second-last or third-last digit.



UNPAKDEC.VDM    A high-speed EBCDIC conversion macro that supports up to 32

                packed-decimal fields.



UNPAKDEC.TXT    Documentation file for the UNPAKDEC.VDM macro.







Quick Test

----------



You can perform a quick test by converting the supplied COBOL.EBC file using

the supplied COBOL.LAY data layout (COBOL copy-book) file. From a DOS/NT

command box, change to the directory containing VEDIT and into which you

placed the EBCDIC conversion file. This is typically "c:\vedit". Then, give

the command:



     vpw -x ebcdic-t.vdm cobol.ebc cobol.lay



This will leave you in the VEDIT editor with the converted file displayed.

Alternatively, to automatically save the file and exit, give the command:



     vpw -y -x ebcdic-t.vdm cobol.ebc cobol.lay



The following section "Performing the Conversion (Automatically)" describes

this in more detail.



NOTE:   The easiest way to perform this quick test is to open a DOS box in

        Windows, change to the directory containing the VEDIT file, (e.g.

        with the DOS command "cd \vedit") and then enter the commands above.



        You could run the quick test by selecting "Run" from the "Start"

        button, but then you will have to enter the full pathname to each

        file in the command.



        Once you have everything set up, you can create an icon on the

        Windows Desktop to perform the conversion via drag-and-drop.



        1. Right-click on the desktop and select New -> Shortcut.

        2. For the "Command line" or "Location of item", enter:



           c:\vedit\ebcdic-t.bat "%1"



           (This assumes VEDIT was installed into "c:\vedit").



        3. For the "Name of shortcut", enter any desired name, such as

           "EBCDIC conversion".



        4. You will now have an icon on your desktop.







Creating the .LAY Layout File

-----------------------------



The user must specify via a ".LAY" data layout file, typically EBCDIC.LAY,

the location of the packed, zoned and other special fields. The file's record

length and several options are also specified in the data layout file.



The data layout file is best understood from a simple example. Assume an

EBCDIC file with the following specs:



    Record length is 114

    Field between columns 10 and 14 is a packed-decimal number (unsigned)

    Field between columns 20 and 21 is a packed-decimal number (unsigned)

    Field between columns 22 and 23 is a packed-decimal number

    Field between columns 30 and 33 is a packed-binary number

    Field between columns 42 and 46 is a zoned number

    Field between columns 51 and 55 is an unsigned number

    Field between columns 56 and 59 is a short (single precision) floating point number

    Field between columns 60 and 67 is a long (double precision) floating point number

    All other fields are simple EBCDIC text



To convert this file and create a Windows/DOS text file with a Carriage-

Return and Line-Feed at the end of each record, the following layout file is

used: (This is the supplied prototype EBCDIC.LAY file)



    r=114,0            //Record length is 114, convert to DOS newlines

    o=z,b2z            //Output leading zeros (blank '+' sign; sign at end)

                       //Convert all-blank/null numeric fields to zeros

    e=0,ebcdic.err     //Only report serious errors in EBCDIC.ERR

    d 10-14 u v2       //Packed-decimal (no sign, explicit decimal point)

    d 20-21 u          //Packed-decimal (no sign)

    d 22-23            //Packed-decimal

    b 30-33,=9;        //Packed-binary (9 digits; default is 8)

    z 42-46            //Zoned number (5 digits plus sign)

    u 51-55            //Unsigned number; want leading blanks converted to zeros

                       //(o=b2z); otherwise redundant

    l 56-59,=7;  v2    //Short (single precision) floating point; upto 7 digits with two past a decimal point

    l 60-67,=12; v2    //Long (double precision) floating point; upto 12 digits, 2 fractional



As shown above, comments can be added to the layout file by preceding them

with "//".



The "r=114,0" indicates that this file has fixed-length records of 114 bytes.

Most EBCDIC files have fixed-length records. Note that unpacking fields will

increase the record length. The ",0" indicates that a Carriage-Return and

Line-Feed will be appended after each record in order to create a Windows/DOS

text file. Use ",1" to append just a Line-Feed to create a UNIX text file.



The "o=z,b2z" specifies that leading zeros are to be output, rather than

spaces and that all-blank/null numeric fields are to be converted to text

zeros. The conversion options are described below.



The "d" specifies a packed-decimal field. It must be followed by the

beginning and ending column numbers of the field. The "u" in the parameter

field specifies that this value is unsigned, so no sign is output, not even

a space. Note: a positive or negative sign in the input data will generate

an error. The "v2" specifies that an explicit decimal point is to be

output, followed by the last two digits of the packed decimal value.



The "b" specifies a packed-binary field. The maximum size of a packed-

binary field is eight bytes. Ordinarily, a 4-byte binary field is output in

an eight digit field. This can be changed with the ",=ndigits;" parameter as

described in the later topic "Formatting Numeric Data".



The "z" specifies a zoned number field. In a zoned field, the sign is

packed into the last digit; the other digits are not packed. The output

field is one greater than the input field so that the sign can be

expressed.



The "u" specifies a simple unsigned (non-packed) number. Since this

is no different from other EBCDIC text, it need not be included. Using it

here ensures that any leading spaces will be converted to zeros and allows

all-blank/null numeric fields to be converted to zeros with the "o=b2z"

instruction.



Finally, the "l" specifies a short (single precision) or long (double

precision) floating point number. The short value is four bytes in length;

the long is eight. In the above example, the short value is expressed in a

seven digit field including the two fractional digits. The output field is

9 bytes long to account for the sign and the explicit decimal point.

Similarly, the long floating point value is output in a twelve digit field.

Any fractional digits contained in the actual data beyond the two that are

expressed are truncated. If the first truncated digit is five or greater the

final expressed digit is rounded up.



The complete list of possible field types is:



    b   Packed-binary field

    d   Packed-decimal field

    n   Packed-No-Zone (PNZ); no sign; additional digit can be packed.

    z   Zoned number field

    s   Signed ASCII decimal field; analogous to zoned decimal. '{', 'A'-'R'

        and '}' represent signed digits. Used when converting an ASCII file

        with compressed fields. Should be used with "u=ignore" to set

        the default conversion.

    u   Unsigned numeric field. Simple EBCDIC. Using it allows explicit

        decimal points to be output or leading spaces converted to zeros or

        having an all blank/null field converted to zeros.

    e   EBCDIC field. This is redundant and slows down conversion, but may

        help some users better visualize their file. Necessary when

        quoted-and-comma-delimited or user-specified delimiter or DBASE

        output is specified. Also required for the first or last item of

        an "out" bracketed section.

    h   Hex field. Output each byte as 2 hexadecimal digits.

    i   Ignore field. The bytes in this field will be passed on "as is".

    l   Floating point number. See topic "Floating Point Numbers".

    f   Fill field. The bytes in this field are replaced (filled) with ASCII

        spaces, or another specified padding character.

    x   Delete the field.



    c   Custom field. A custom macro is used to process this field.



The "b", "d", "l", "u" and "z" specifications can also take several options

which specify exactly how the number is converted. If no options are

specified, numbers are converted as follows:



    * Output space instead of '+' for positive values

    * Place the sign at the end of the number

    * Output numbers as signed values

    * Output leading zeros instead of spaces (due to "o=z")



The following options, which are specified after the column numbers, control

the conversion: (These override any "o=..." command settings).



    +   Use an explicit "+" sign for positive numbers, else a Space is

        used. Negative numbers are always converted with "-".

    b   Place the sign at the beginning of the number, else the sign is at

        the end of the number.

    u   The data is expressed as an unsigned number. This option overrides

        the "+" and "b" options.

    z   Use leading "0" in numbers; else leading zeros are replaced with

        Spaces.

    b2z Convert all-blank/null numeric fields to zeros.



See also the topics "Formatting Numeric Data" and "Floating Point Numbers".



Since it would be tedious to specify the same conversion options for every

field, you can specify the default options with the "o=..." command. For

example, "o=z" specifies that the converted numbers should have leading "0"

instead of spaces. The command "o=+bz" would place the sign, including '+',

and any leading zeros ahead of all unpacked numeric values by default. A

.LAY file should have at most one "o=..." command.



For some fields, you may want to disable one or more of the default options

set with the "o=..." command. This can be done with the following options:



    -   To use Space instead of "+" for positive numbers.

    e   To place the sign at the end of the number.

    s   The data is expressed as a signed value.

    p   To use blank padding instead of zeros to right justify small numbers.



NOTE:   These field options are only needed to override the default options

        set with the "o=..." command.



The numeric field specifications "b", "d", "l", "n", "u" and "z" (binary,

packed decimal, floating point, packed-no-zone, unsigned numeric and zoned

decimal) can also take an optional explicit decimal point position.



    v1  Place the decimal point "." one digit from the right.

    v2  Place the decimal point "." two digits from the right.

    v3  Place the decimal point "." three digits from the right.



For example, the layout file above could be modified with these options:



    r=114,0            //Record length is 114, convert to DOS newlines

    o=-ep,b2z          //Standard output default options

                       //Also, convert all-blank/null numeric fields to zeros

    e=0,ebcdic.err     //Only report serious errors in EBCDIC.ERR

    d 10-14 b          //Packed-decimal; place sign at beginning

    d 20-21 zv2        //Packed-decimal; include leading "0"

                       //  place decimal point two digits from right

    d 22-23 +b         //Packed-decimal; include "+" at beginning

    b 30-33 z          //Packed-binary; include leading "0"

                       //Note: output in an eight-digit field

    z 42-46 b          //Zoned number; place sign at beginning

    u 51-55 z          //Unsigned number in columns 51 thru 55; want leading blanks

                       //and all-blank/null fields converted to zeros; else redundant

    l 56-59            //Short (single precision) floating point integer; 7 digit

                       //  field with no decimal point

    l 60-67 v0         //Long (double precision) floating point integer; 16-digits;

                       //  decimal point but no fractional digits



Sometimes it is more convenient to specify the type and size of each field

instead of its beginning and ending columns. The following variation of the

original example shows this. Note how the "+" is used:



    r=114,0             //Record length is 114, convert to DOS newlines

    o=z,b2z             //Output leading zeros (blank '+' sign; sign at end)

                        //Convert all-blank/null numeric fields to zeros

    e=0,ebcdic.err      //Only report serious errors in EBCDIC.ERR

    e +9                // 9 columns of EBCDIC text    (1 - 9)

    d +5                // 5 columns of Packed-decimal (10-14)

    e +5                // 5 columns of EBCDIC text    (15-19)

    d +2                // 2 columns of Packed-decimal (20-21)

    d +2                // 2 columns of Packed-decimal (22-23)

    e +6                // 6 columns of EBCDIC text    (24-29)

    b +4                // 4 columns of Packed-binary  (30-33)

    e +8                // 8 columns of EBCDIC text    (34-41)

    z +5                // 5 columns of Zoned number   (42-46)

    e +4                // 4 columns of EBCDIC text    (47-50)

    u +5                // 5 columns of EBCDIC digits  (51-55)

    l +4                // 4 columns of short (single precision) floating point (56-59)

    l +8                // 8 columns of long  (double precision) floating point (60-67)

    e +47               //47 columns of EBCDIC text    (56-76)



The name of the data layout file can be either EBCDIC.LAY or filename.LAY,

where 'filename' is the name of the file being converted. The name of the

layout file can also be explicitly specified. This is described below under

"Conversion Options".







Floating Point Numbers

----------------------



The EBCDIC conversion packages support IBM 360-style floating point numbers

in the range 10E-18 through 10E18. Output is fixed format, right justified.

The field is specified like the other numeric fields; e.g.,



        l bc,ec[,=ndigits;] [sop] [v[n]] // comment



where the beginning and ending columns must be four or eight bytes long;

"sop" are the standard options "+buz-esp", 'v' specifies that an explicit

decimal point is to be output and 'n' specifies the number of digits to

output past the decimal point. The optional "ndigits" specifies the total

number of digits output, both before and after the decimal point (See

"Formatting Numeric Data"). It must be sufficiently large to express the

whole-number digits as well as the fractional digits "vn". There will

always be at least one digit before the decimal point, even if just zero.

The default "ndigits" is 7 for short floats and 16 for long floats.



Floating point numbers with magnitudes greater than 10E18 are treated as

erroneous; their output fields are filled with BAD_CHARs and error messages

are generated in EBCDIC.ERR. Numbers with magnitudes between zero and 10E-18

are output as zeros.



(Technical)

Floating point numbers have an intrinsic truncation error associated with

them. IBM's standard floating point number has 6 significant hexadecimal

digits and a sign and exponent packed into 4 bytes, with a certain amount of

truncation error associated with the 6th digit. This can be transformed into

a decimal representation of about 7 digits with a significant amount of

error in the eighth digit. Accordingly, the eighth digit is truncated and

the preceding digit(s) is/are rounded up when the truncated digit was

greater than or equal to five. For double precision (eight bytes), seven-

teen significant decimal digits can be output.



NOTE:   The EBCDIC conversion packages correctly handle these truncation

        issues according to the IBM documentation.



If the conversion instruction specifies fewer significant digits than can

be validly expressed, the last digit output is rounded up when the non

displayed subsequent digit is five or greater. Double rounding (from 4 to

5  during conversion and then from 5 to 6 for displaying) is prevented.



If the conversion instruction specifies more digits than can be validly

expressed, zeros are used for the excess positions.







Using a COBOL Copy-Book for the .LAY Layout File

------------------------------------------------



For simple data files containing neither REDEFINES nor OCCURS clauses, it

is possible to "cut and paste" the COBOL copy-book into the .LAY layout

file. The COBOL copy-book must be preceded by a "p=" line and followed by

a "q=" line.



The following example converts the same file in the same way as the

original example (this is the supplied prototype COBMIX.LAY file):



r=114,0            //Record length is 114, convert to DOS newlines

o=z,b2z            //Output leading zeros (blank '+' sign; sign at end)

                   //Convert all-blank/null numeric fields to zeros

e=0,ebcdic.err     //Only report serious errors in EBCDIC.ERR

//

p=                 //Start of COBOL data specifications

                   //Vedit comments and blank lines are OK after the "p=" line



      ***************************************************************     000100

      *                                                             *     000110

      *   SAMPLE COPY-BOOK                                          *     000120

      *                                                             *     000130

      *   RECSIZE = 114 BYTES                                       *     000140

      *                                                             *     000150

      ***************************************************************     000160

                                                                          000170

       01  SAMPLE-REC.                                                    000180

           03  SA-KEY.                                                    000190

               10  SA-KEY-ALPHA           PIC X(7).                       000200

               10  SA-KEY-NUMERIC         PIC 9(2).                       000250

           03  SA-PAC-DEC-1               PIC 9(7)V99   COMP-3.           000300

           03  FILLER                     PIC X(5).                       000350

           03  SA-PAC-DEC-2               PIC 999       COMP-3.           000400

           03  SA-PAC-DEC-3               PIC S9(3)     COMP-3.           000450

           03  FILLER                     PIC X(6).                       000500

           03  SA-SIGNED-BINARY           PIC S9(9)     COMP.             000550

           03  FILLER                     PIC X(8).                       000600

           03  SA-ZONED-DECIMAL           PIC S9(5).                      000650

           03  FILLER                     PIC X(4).                       000700

           03  SA-ANOTHER-NUMERIC         PIC 9(5).                       000750

           03  SA-FLOAT                   PIC S9(5)V99  COMP-1.           000800

           03  SA-DOUBLE                  PIC S9(10)V99 COMP-2.           000850

           03  FILLER                     PIC X(47).                      000900

q=                 //End of COBOL data specifications





Notes:  The COBOL statement lines must be included verbatim, maintaining

        the 1-6,7,8-72,73-80 columnar format. For statements covering

        more than 1 line, the entire statement must be included, not just

        the picture format.



        Other than COBOL statement lines, only blank lines, Vedit comment

        lines and Column setting "c=col" lines (see below) may appear between

        the "p=" and "q=" lines.



Alternatively, each individual packed field's COBOL statement can be cut and

pasted into the layout file. It is necessary to indicate the beginning column

number of each non-contiguous field, as in the following example:



r=114,0         //Record length is 114, convert to DOS newlines

o=z,b2z         //Output leading zeros (blank '+' sign; sign at end)

                //Convert all-blank/null numeric fields to zeros

e=0,ebcdic.err  //Only report serious errors in EBCDIC.ERR

//

p=              //Start COBOL section

                //Columns 1-9 are simple EBCDIC

c=10            //Starting column # for upcoming packed-decimal field

           03  SA-PAC-DEC-1               PIC 9(7)V99   COMP-3.           000300

                //Columns 15-19 are simple EBCDIC

c=20            //Starting column # for upcoming packed-decimal fields

           03  SA-PAC-DEC-2               PIC 999       COMP-3.           000400

           03  SA-PAC-DEC-3               PIC S9(3)     COMP-3.           000450

                //Columns 24-29 are simple EBCDIC

c=30            //Starting column #

           03  SA-SIGNED-BINARY           PIC S9(9)     COMP.             000550

                //Columns 34-41 are simple EBCDIC

c=42            //Starting column #

           03  SA-ZONED-DECIMAL           PIC S9(5).                      000650

                //Columns 47-50 are simple EBCDIC

c=51            //Starting column #

           03  SA-ANOTHER-NUMERIC         PIC 9(5).                       000750

           03  SA-FLOAT                   PIC S9(5)V99  COMP-1.           000800

           03  SA-DOUBLE                  PIC S9(10)V99 COMP-2.           000850

                //Columns 68-114 are simple EBCDIC

q=              //End COBOL section





More complicated copy-books with "OCCURS" and "REDEFINES" clauses should

first be converted to a normal .LAY file with the supplied COBOL2V.VDM macro

as described below.







Performing the Conversion (Manually)

-------------------------



NOTE:   The conversion is normally performed automatically (see below),

        but you can also run it manually.



To convert files manually, it is necessary to have the data layout file named

EBCDIC.LAY in the current or VEDIT Home Directory.



1.  Open the EBCDIC file to be converted.



    NOTE: Steps 2. thru 4. are optional; they just let you review the EBCDIC

          file before it is converted.



2.  Assuming the file has fixed-length records, set the correct record

    length with {CONFIG, File handling, File type}.



3.  Press <Alt-D> (the hot-key for {VIEW, Toggle display mode}) several times

    to switch to EBCDIC mode. The non-packed fields should now be readable.



4.  Open the file EBCDIC.LAY and ensure that it is correct. In particular,

    the "r=" should be set to the same record length that you set above.



    Switch back to the data file's buffer.



5.  Select {MISC, Load/Execute macro}.



    Enter the file name "ebcdic-t.vdm" or select this file in the dialog box.

    Use the default register number "100".



6.  The macro will start, display its sign-on message and immediately begin

    performing the conversion. It displays a progress message of how many

    records have been converted.



    The conversion creates a new file with the same filename, but an ".ASC"

    extension.



7.  When done, the beginning of the converted file will be displayed on the

    screen.



8.  Select {FILE, Exit} to exit the editor.







Performing the Conversion (Automatically)

-------------------------



The conversion can be performed automatically from a command line or with a

DOS batch file. Win 95/98/NT/2000/XP users can create a shortcut icon to the

batch file; you can then drag-and-drop the file to be converted onto the

icon.



1a. From a DOS or NT command line, use the following command to run the

    32-bit Windows VEDIT with the conversion macro:



        c:\vedit\vpw -x ebcdic-t.vdm filename



    where 'filename' is the name of the file to be converted.

    (This assumes VEDIT was installed in c:\vedit.)



2a. This will immediately start the conversion. When done, the converted file

    will be saved and shown on the screen. You must still exit the editor.



    To also automatically exit, use the command:



        c:\vedit\vpw -y -x ebcdic-t.vdm filename



    This will convert and save the file, and exit VEDIT without any user

    intervention whatsoever.



-OR-



1b. Use the supplied EBCDIC-T.BAT batch file which contains the command to

    run the 32-bit Windows VEDIT and automatically convert the specified

    file:



        c:\vedit\vpw -x ebcdic-t.vdm %1 %2



    Therefore, to convert the file with name 'filename', give the command:



        ebcdic-t filename



2b. This will convert and save the file, and exit VEDIT without any user

    intervention whatsoever.



    If desired, you can have VEDIT display the converted file before saving

    and exiting. The comments in the EBCDIC-T.BAT file describe how to

    do this.



NOTE:   These commands assume that the EBCDIC data file, EBCDIC-T.BAT and

        EBCDIC.LAY are in the current directory. If not, you may need to

        specify the full pathname to the files.



        EBCDIC-T.BAT also assumes that VEDIT was installed into the

        "C:\VEDIT" directory. If you installed VEDIT into another directory,

        e.g. "C:\Program Files\VEDIT", you must edit the EBCDIC-T.BAT file

        to specify the correct directory.







Conversion Options

------------------



By default, the name of the data layout file is EBCDIC.LAY. Optionally, you

can use "filename.LAY", where 'filename' is the name of the file being

converted. You can also explicitly specify the name of the .LAY file.

EBCDIC.LAY is convenient when you have many files of the same type;

filename.LAY is better when each file is of a different format.



The "-n" invocation switch causes filename.LAY to be used as the layout file.

Therefore, use the following command to automatically run the conversion

macro:



        c:\vedit\vpw -n -x ebcdic-t.vdm datafile.ebc



    where 'datafile.ebc' is the name of the file to be converted.

    datafile.lay will be used as the name of the layout file.



Alternatively, you can explicitly specify the name of the layout file. This

is necessary when the .LAY layout file is in a different directory. Use the

command form:



        c:\vedit\vpw -x ebcdic-t.vdm datafile.ebc layout.lay



    where 'datafile.ebc' is the name of the file to be converted.

    'layout.lay' is the name of the data layout file.







Using Different Directories

---------------------------



By default, the EBCDIC source file "datafile.ebc", the data layout file

EBCDIC.LAY and the resulting ASCII file "datafile.asc" must all be in

the same directory. However, you can specify separate directories with

the command:



vpw -x ebcdic-t.vdm \dir1\datafile.ebc -a \dir2\datafile.asc \dir3\layout.lay



    where '\dir1\datafile.ebc' is the pathname of the file to be converted.

          '\dir2\datafile.asc' is the pathname of the converted file.

          '\dir3\layout.lay' is the name of the data layout file.



This format lets you specify the full pathname of the converted file and of

the data layout file.





---------------

ADVANCED TOPICS

---------------



Quoted-Comma-Delimited ASCII File

---------------------------------



Consider the following relatively simple .LAY file:



    r=76,0              //Record length is 76, convert to DOS newlines

    o=z,b2z             //Output leading zeros (blank '+' sign; sign at end)

                        //Convert all-blank/null numeric fields to zeros

    e=0,ebcdic.err      //Only report serious errors in EBCDIC.ERR

    e +9                // 9 columns of EBCDIC text    (1 - 9)

    d +5                // 5 columns of Packed-decimal (10-14)

    e +5                // 5 columns of EBCDIC text    (15-19)

    d +2                // 2 columns of Packed-decimal (20-21)

    d +2                // 2 columns of Packed-decimal (22-23)

    e +6                // 6 columns of EBCDIC text    (24-29)

    b +4                // 4 columns of Packed-binary  (30-33)

    e +8                // 8 columns of EBCDIC text    (34-41)

    z +5                // 5 columns of Zoned number   (42-46)

    e +4                // 4 columns of EBCDIC text    (47-50)

    u +5                // 5 columns of EBCDIC digits  (51-55)

    e +21               //21 columns of EBCDIC text    (56-76)



One converted ASCII record might look like this:



    ABCDEFGHI123456789 ABCDE123 123 ABCDEF1234567890ABCDEFGH12345 ABCD12345ABCDE...



It is difficult to tell where one field ends and the next begins. Therefore,

the conversion can optionally quote each field and separate them with commas.

Therefore, the converted ASCII record would look like this:



    "ABCDEFGHI","123456789 ","ABCDE","123 ","123 ","ABCDEF","123456789 ","ABCDEFGH","12345 ","ABCD","12345","ABCDE..."



To select this option, add the "qcd" command to the .LAY file:



    r=76,0              //Record length is 76, convert to DOS newlines

    o=z,b2z             //Output leading zeros (blank '+' sign; sign at end)

                        //Convert all-blank/null numeric fields to zeros

    qcd                 //Create quoted-comma-delimited ASCII

    e +9                //9 columns of EBCDIC text    (1 - 9)

    ...



Please be aware of these notes when creating a quoted-comma-delimited file:



*  The "qcd" command must appear in the .LAY file before any field specs.



*  All fields, including simple EBCDIC text fields, must be specified.



*  Only use the "qcd" command when necessary - it slows down the conversion

   by about 20%. Although it makes the ASCII file more humanly readable,

   most database programs, such as Microsoft Access (tm), can import based

   on beginning and ending columns and don't need a quoted-comma-delimited

   file.



*  When quoting and comma delimiting output fields, any quotes that appear

   in text fields may confuse programs that later try to process the output.

   To automatically convert quotes to apostrophes, use the EBCDIQ.TBL

   conversion table as explained in the topic "Alternative EBCDIC to ASCII

   Translation Tables", below.







User Specified Field Delimiter String

-------------------------------------



As an alternative to quoting and comma delimiting each field, a custom string

can be used to separate fields. E.g., to separate the fields with " | "

(space, pipe, space), place the following command at the beginning of the

.LAY layout file:



        v=Reg_Set(XDREG,/ | /);



This is an example of the "v=" specification which executes Vedit macro

commands. The text register specified by internal value XDREG (currently 17,

when not being run under WILDFILE.VDM) is set to the specified string.

EBCDIC-2.VDM appends T-Reg(XDREG) to the end of each specified output field

and to the end of each set of unspecified (default) fields.



Note:   To use the "/" character as part of the string, the string delimiting

        "/" may be replaced by any of '"`\.







Alternative EBCDIC to ASCII Translation Tables

----------------------------------------------



It is sometimes necessary or desirable to translate EBCDIC text characters

to a different ASCII character than normal. Three alternative translation

tables are supplied for this purpose: EBCDIQ.TBL which converts quotes to

apostrophes; EBCDIL.TBL which converts "low values" (0x00 - 0x3f) into

ASCII spaces; and EBCDILQ.TBL which does both. The "Q" table are provided

for use when output is being quoted and comma delimited. The "L" tables

are provided for cases when uninitialized text fields or, perhaps,

undocumented packed fields are present in supposedly simple text fields.

The result of treating them as text is gibberish in the ASCII output.



To use one of these tables, include the following, appropriately edited,

line near the beginning of your .lay file:



    v=Translate_Load("EBCDIQ.TBL")	// Convert EBCDIC " to ASCII '



This assumes that the table has been copied to your VEDIT home directory

or is in the directory containing the data file being translated.







Formatting Numeric Data

-----------------------



The numeric field specifiers "b", "d", "l", "n", "u" and "z" have an

associated default output width dependent on the individual data type, the

size of the input field, the presence and location of a sign and the

presence of an explicit decimal point.



The location of the sign (plus, minus or blank) has been well explained in

the topic "Creating the .LAY Layout File". The sign may also be suppressed

by the unsigned option 'u'. E.g., "b 1,4 u". The output for this binary

field is eight columns - the standard number of digits stored in a 4-byte

binary. There is no sign to be expressed for the unsigned numeric fields 'u'

(simple numeric) and 'n' (packed, no zone).



To output an explicit decimal point, use the "v[n]" option, where 'n' is

the number of digits following the decimal point. E.g.,"d 1,4 v2". The

output for this packed decimal field is nine columns in the format

"ddddd.ffs" where 's' is the sign. If 'n' is omitted or 0, nothing

is output past the decimal point.



To control the actual number of digits output, use the ",=ndigits;" option,

where "ndigits" is the total number of digits to be output both before and

after any explicit decimal point. E.g., "l 1,4,=6; v2". The output of this

floating point field is eight columns in the format "dddd.ffs". The default

size is nine columns. I.e., "l 1,4 v2" generates "ddddd.ffs".



The number of digits output can be greater or less than the default number

of digits contained in a numeric field. If greater, leading zeros/blanks

are normally output. For the case of floating point fields only, specifying

more digits past the decimal point than are contained in the actual data

results in trailing zeros being output.



Specifying fewer digits than the default must be done with care. If fewer

digits are specified than are actually contained in any field other than a

floating point's fractional digits, a BAD_CHAR will be placed into the

field's first output column and an error message will be output to

EBCDIC.ERR.



The defaults for binary numbers are two, four, eight and eighteen digits for

one-, two-, four- and eight-byte binary numbers. (Note: IBM does not support

one-byte binary numbers).



The default for packed decimals is 2*(ending column - beginning column) + 1.



The default for packed, no zone is 2*input size, where input size = (ending

column - beginning column + 1).



The default for short (single precision) floating point (input size = 4) is

7.



The default for long (double precision) floating point (input size = 8) is

16.



Following are examples of binary fields with the total output field size

given in the comment field:



        o=+z            //Output leading zeros and '+' for nonnegative values

        b 1,4,=9;       //10 bytes (9 digits + sign)    PIC S9(9) COMP.

        b 1,4  u        // 8 bytes (8 digits, no sign)  PIC  9(8) COMP.

        b 1,4,=10;      //11 bytes (10 digits including any leading zeros + sign)



        b 1,1  u        //1 byte  (1 digit,  no sign)  PIC X.

        b 1,1,=2; u raw //2 byte2 (2 digits, no sign)  PIC X.

        b 1,1,=2;   raw //3 bytes (2 digits + sign)

        b 1,1  -        //2 bytes (1 digit, trailing sign, space if positive)

        b 1,1  -b       //2 bytes (1 digit, leading  sign, space if positive)



        b 1,2           // 5 bytes (4 digits + sign)    PIC S9(4)  COMP.

        b 1,8           //19 bytes (18 digits + sign)   PIC S9(18) COMP.

        b 1,8,=14;      //15 bytes (14 digits + sign)   PIC S9(14) COMP.







Reporting Errors

----------------



Any conversion errors can optionally be reported in a file; the default

filename is "ebcdic.err" in the same directory as the converted output file.

Alternatively, you can specify a different filename or a full pathname with

the "e=" command (see below).



Three kinds of errors can be reported:



*   Syntax errors in the ".LAY" file and other serious errors which prevent

    any data from being converted. The ebcdic.err file will contain a

    description of the error.



*   Errors in the data file. When bad data, e.g. an invalid packed-decimal

    number is encountered, it is converted to spaces and the conversion

    continues. Optionally, up to the first 'n' data errors can be reported.

    The ebcdic.err file will contain a description and the position in the

    data file of the error.



*   Any unexpected conditions which cause the conversion to stop. These are

    reported with "***** Unexpected breakout occurred." in the ebcdic.err

    file.



Our experience is that many data files contain insignificant errors in some

fields. In some cases the field is defined in the copy-book, but is never

used and contains garbage. Therefore, we suggest ignoring errors in the data

file unless the data is really critical and you are willing to take the time

to track down the errors on the mainframe side. When data error reporting is

enabled, only the first 'n' errors are reported to prevent creating huge

error files.



The "e=" command in the ".LAY" file controls which errors are reported in the

error file and can override the name of the file. Some examples are:



e=1000,ebc-data.err



        Up to the first 1000 errors in the data file will be reported.

        Specifies that the name of the error file is "ebc-data.err".

        This will be written to the main output directory which is the

        same as the source data file unless altered by the "-a outpathname"

        invocation option.



e=200



        Up to the first 200 errors in the data file will be reported. The

        default error file "ebcdic.err" will be used.



e=0



        Most errors in the data file will not be reported and will not

        cause an error file to be created. Severe errors will still be

        reported. These are mostly encountered by the preprocessor and

        will have been fixed before production runs are made.



e=0,\errdir\ebcdic.err



        Exactly the same as "e=0". It explicitly gives the location and

        name of the error file.





When the conversion starts, any existing "ebcdic.err" file is deleted. A

batch file can therefore test for the existence of ebcdic.err to determine if

the conversion was successful or not. The supplied EBCDIC-T.BAT file does

this with the batch commands:



        IF NOT EXIST ebcdic.err GOTO DONE

        ECHO -

        ECHO Conversion had errors!

        ECHO See the file EBCDIC.ERR for details.

        ECHO -

        PAUSE

        :

        :DONE







Advanced Commands

-----------------



The new "out" command allows diverting just part of a record to its own

file. To link extracted data to its parent record, a unique ID # is

automatically generated. Associated with this are 4 new commands, "b=",

"d=", "a=" and "n=" (see below).







Outputting a record section to its own file (out)

-------------------------------------------------



It is possible to output a section of a record to its own file by using the

'out "fname"' ... 'out' brackets. This can be done even when the parent

record is being output to its own file. The unique ID #, discussed below, is

appended to both the end of the section and the end of the parent record.



    out ["fname"] Use the "out" commands as brackets around a section to

                  divert the output to the file "fname". The first "out"

                  requires the filename. The first and last fields must

                  be explicitly defined. For example,



                             ...

                             out "special.asc"

                             e   510,579

                             out

                             ...



                 converts columns 510 through 579 from simple EBCDIC to ASCII

                 and outputs the results into file "special.asc". The unique

                 ID will be appended to the end of the line in "special.asc"

                 and to the end of the parent record's output line.



                 The first and last fields (here, the same) have been

                 explicitly specified, even though ordinarily they could have

                 been omitted.







Unique ID #'s for Extracted Fields

----------------------------------



When data fields are being output to their own files, it is helpful and

sometimes necessary to generate a unique ID # for associating the extracted

portions of the data record with the main portion. The unique ID is output

at the end of the extracted portion and at the end of the parent record.

For Level-2 this occurs for 'out "fname"' ... 'out' bracketed sections

(see above).



The unique ID # consists of a 5-digit "# days elapsed since base date"

followed by a 1-digit "daily run #" (default value is 0) followed by a

6-digit "record #". The five-digit elapsed days count allows for 270+

unique years. The 6-digit record count allows for 999,999 records to be

processed in a single day. The "daily_run_#" allows more than one such

run per day. This value must be explicitly set (see below).



The ID's are generated automatically, based on the day of the run and the

input record #. To control the ID generation, 4 commands have been added:

"b=base_date" (default = 1/1/2000); "d=run_date" (default = current date);

"a=additional_offset" (default = 0) and "n=l,m[,n]" to control the number

of digits in the unique ID (default = 5 digits for days elapsed, 6 digits

for the record # and 1 digit for the run #).



To change the run date, add the "d=run_date" command to the .LAY file. Dates

are expressed in mm/dd/yyyy format. The year must be completely expressed.

The separator may be any of "_./\:-".



To change the base date from its default of 1/1/2000, add the "b=base_date"

command; e.g.,



        b=1/1/1900      // Include dates from the previous century



To change the number of digits in the unique ID to 4 digits for # days

elapsed since base date and 5 digits for the record # use the "n=d,r"

command; e.g.,



        n=4,5           // 4 digits for days elapsed since base date

                        // 5 digits for record count

                        // There is still 1 digit reserved for the

                        // daily run #



In case more than one data set is processed for a given base_date and

run_date, one can include the "a=additional_offset" command in order

to generate unique ID's in the 2nd and later runs. Set the offset greater

than or equal to the last record # processed in the previous run(s); e.g.



        a=9999          // Previous run ended with record 9,999



As an alternative, one can employ the digit reserved for the daily run #

by adding the run # to the invocation command line after the "-u"

parameter, which is placed after all specified filenames. For the second

run of the day this might be:



       c:\vedit\vpw -x ebcdic-2.vdm datafile.ebc layout.lay -u 2







DBASE output

------------



To easily produce DBASE-style output, set the second parameter in the

"r=reclen,parm2" specification in the .LAY file to "DBASE-III". During

preprocessing, a DBASE header record - including automatically generated or

explicitly entered field names - is generated for the output file.



The automatically generated names are of the form "Fn", where 'n' is the

field's index, counting from 1.



A second letter 'A', 'B', ... is automatically generated between 'F' and 'n'

for each section being output to its own file via …