/ebcdic-t.txt
Plain Text | 1700 lines | 1278 code | 422 blank | 0 comment | 0 complexity | dca44a05cdc47e2f41e3e69e943ca024 MD5 | raw 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 an "out" command.
- Alternatively, specify the letter, e.g. 'N', on the "out" command:
-
- out "fname",FN
-
- See, also, "Defining Explicit Field Names for DBASE, below.
-
- Other details, such as the header terminating 0x0d, file terminating 0x1a
- and record leading space, are also automatically generated. Currently, all
- fields are specified as type 'C' (character).
-
- Each field in the record must be specified in the .LAY file, the same as for
- quoting and comma delimiting. However, the preprocessor will automatically
- strip the default field specifications after generating the header data for
- the field. This provides a dramatic increase in run-time performance for the
- normal case where there are only a few packed fields per record.
-
- See also COBOL2V.VDM and RELAY.VDM for DBASE options.
-
-
-
- Quick DBASE Test
- ----------------
-
- You can perform a quick test by converting the supplied COBOL.EBC file after
- generating COBOLD.LAY from COBOL.COP. 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 cobol2v.vdm cobol.cop -a cobold.lay -u dbase
-
- This will leave you in the VEDIT editor with the converted layout file
- displayed. A preliminary .XRF file is also generated which is of no
- practical interest. Select {FILE, Exit} to exit the editor, saving the
- layout file and doing as you will with the .XRF file.
-
- Now, to convert the EBCDIC data, producing an ASCII file in DBASE format,
- give the command:
-
- vpw -x ebcdic-t.vdm cobol.ebc cobold.lay
-
- Since COBOLD.LAY does not specify otherwise, EBCDIC-T.VDM automatically
- generates names for each field, creates the DBASE header record, translates
- COBOL.EBC into ASCII and displays the results. To view the DBASE header
- record, select {MISC, More macros, DBASE}. This pops up a second edit window
- with the DBASE header information converted into meaningful text.
-
-
-
- Viewing DBASE Files
- -------------------
-
- Greenview Data, Inc. provides two macros to aid viewing DBASE files. For
- information, see the VEDIT "Help" topic "DBASEKEY.VDM Macro": from within
- VEDIT, select {Help, Search for help on...} and enter DBA into the "Index"
- input box; click [Display]; then select "DBASE.VDM Macro" and click [Display].
- The first topic gives a more complete discussion of DBASE.VDM. The immediately
- following topic discusses "DBASEKEY.VDM" which you may prefer for common use.
-
-
-
- Defining Explicit Field Names for DBASE
- ---------------------------------------
-
- To have explicit field names entered into the DBASE header record, enter them
- into the .LAY file comment section just past the ASCII-output-column numbers.
- Also, include the line "xrf=1" or "xrf=on" at the beginning of the .LAY file.
- Then, run RELAY.VDM to produce an .XRF file that contains the explicit names
- in the first column group, auto-generated names in the second column group,
- and COBOL copy-book names in the third column group.
-
- When EBCDIC-T.VDM is run, the "xrf=on" specification will cause the .XRF file
- to be loaded during preprocessing and the first short name encountered from
- each line to be placed into the DBASE header record. Thus, it is possible to
- give explicit names to just a few important fields, using auto-generated names
- for the remaining fields.
-
- DBASE names are limited to ten characters; they must begin with a letter and
- may contain only letters and digits. See "COBOL2V.VDM and DBASE Output",
- below, for an example.
-
-
-
- Using the COBOL2V.VDM Macro
- ---------------------------
-
- Although a COBOL copy-book can often be pasted directly into a .LAY file, it
- is usually better to first convert the copy-book into a normal .LAY file.
- There are several reasons for this:
-
- * A normal .LAY file allows more flexibility in how each field is converted.
- E.g., you can specify different "+bz" options for each packed field.
-
- * The "X" PIC specification frequently contains binary or custom coded data.
- It also is used for undefined data. Undefined data frequently translates
- not merely into strange looking text but also into unwanted control codes.
- These fields must be deleted or blank filled in the .LAY file.
-
- * Removing simple EBCDIC (non-numeric) field specifications speeds up the
- conversion.
-
- * More complicated copy-books with "OCCURS" and "OCCURS DEPENDING ON ..."
- clauses may require manual changes to the .LAY file. (The latter also
- requires the EBCDIC Level-4 package.)
-
- * "REDEFINES" in the copy-book are not automatically supported. Most can be
- ignored, but others require manually setting up a different record type.
- (The latter also requires the EBCDIC Level-3 package.)
-
- The supplied COBOL2V.VDM macro converts COBOL copy-book statements, e.g. "PIC
- X(7)", into normal ".LAY" specifications, e.g. "e 1 7". It also generates the
- "r=max_rec_size,0" specification. The original copy-book statements are
- maintained in commented form.
-
- When COBOL2V.VDM is being run by EBCDIC-T.VDM on copy-book statements that
- have been pasted into a .LAY file, the COBOL statements must be surrounded by
- "p=" and "q=" brackets. Greenview layout specifications must not occur within
- the bracketed copy-book sections.
-
- When COBOL2V.VDM is being run directly on a copy-book, these brackets are
- not required unless .LAY data layout specifications other than "c=0" are
- included; the "c=0" specifications themselves are required when multiple
- record types are present in order to reset the input column counter.
-
- Because some copy-book "X" pictures actually contain binary data, you may
- want to change them to "B" for binary or "H" for hex or "N" for
- Packed-No-Zone (PNZ) which are recognized by the COBOL2V.VDM macro.
- Otherwise, edit the .LAY file after conversion and change the 'e'
- specifications to 'b' for binary, 'h' for hex or 'n' for PNZ.
-
- NOTES: This macro comments out all "REDEFINES" clauses. If a redefinition
- contains packed/zoned/binary data that differs from the original
- definition, a separate record description must be compiled for each
- definition. This requires the EBCDIC Level-3 support package.
-
- The rare COMP-1 (FLOAT) and COMP-2 (DOUBLE) formats are supported only
- in the range 10E-18 thru 10E18, in fixed form only. Please contact us
- if you need larger powers of 10 or scientific notation.
-
- Unsigned numeric fields (PIC 9) are translated to a "u" specification.
- This allows specifying explicit output decimal points, leading zeros
- and converting all-blank/null fields to zeros.
-
- COBOL2V.VDM is internally used by the EBCDIC-T.VDM macro, but can also be run
- separately.
-
- >>> To convert a COBOL copy-book into a .LAY data layout file:
-
- 1. Save the copy-book as a .LAY file, e.g. "myfile.lay".
-
- 2. Edit the .LAY file as necessary.
-
- 3. Save the file.
-
- 4. Convert the .LAY file, e.g. "myfile.lay" with the command:
-
- vpw -x cobol2v.vdm myfile.lay
-
- The following is the result of running COBOL2V on the supplied COBOL.LAY file:
-
- //
- // COBOL.LAY - (Slightly) modified sample COBOL copy-book for converting
- // EBCDIC files with packed fields into ASCII.
- //
- // (If there are REDEFINES present, this will probably
- // be just the first of many passes).
- //
- 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
- // *************************************************** 000100
- // * * 000110
- // * SAMPLE COPY-BOOK * 000120
- // * * 000130
- // * RECSIZE = 114 BYTES * 000140
- // * * 000150
- // *************************************************** 000160
- // 000170
- // 01 SAMPLE-REC. 000180
- // 03 SA-KEY. 000190
- e 1,7 // 1 10 SA-KEY-ALPHA PIC X(7). 000200
- u 8,9 // 8 10 SA-KEY-NUMERIC PIC 9(2). 000250
- d 10,14 u v2 // 10 03 SA-PAC-DEC-1 PIC 9(7)V99 COMP-3. 000300
- e 15,19 // 20 03 FILLER PIC X(5). 000350
- d 20,21 u // 25 03 SA-PAC-DEC-2 PIC 999 COMP-3. 000400
- d 22,23 // 28 03 SA-PAC-DEC-3 PIC S9(3) COMP-3. 000450
- e 24,29 // 32 03 FILLER PIC X(6). 000500
- b 30,33,=9; // 38 03 SA-SIGNED-BINARY PIC S9(9) COMP. 000550
- e 34,41 // 48 03 FILLER PIC X(8). 000600
- z 42,46 // 56 03 SA-ZONED-DECIMAL PIC S9(5). 000650
- e 47,50 // 62 03 FILLER PIC X(4). 000700
- u 51,55 // 66 03 SA-ANOTHER-NUMERIC PIC 9(5). 000750
- l 56,59,=7; v2 // 71 03 SA-FLOAT PIC S9(5)V99 COMP-1. 000800
- l 60,67,=12; v2 // 80 03 SA-DOUBLE PIC S9(10)V99 COMP-2. 000850
- e 68,114 // 94 03 FILLER PIC X(47). 000900
- // 140 (RecLen)
-
-
- Alternatively, for simple copy-books, run COBOL2V.VDM on the copy-book directly:
-
- vpw -x cobol2v.vdm cobol.cop -a myfile.lay
-
- Following is the result of the above process on the supplied file "COBOL.COP"
- which produced the file "MYFILE.LAY":
-
-
- r=114,0 // Input reclen, emit DOS newlines
- // * ************************************************************** 000100
- // * * 000110
- // * SAMPLE COPY-BOOK * 000120
- // * * 000130
- // * RECSIZE = 114 BYTES * 000140
- // * * 000150
- // * ************************************************************** 000160
- // 000170
- // 01 SAMPLE-REC. 000180
- // 03 SA-KEY. 000190
- e 1,7 // 1 10 SA-KEY-ALPHA PIC X(7). 000200
- u 8,9 // 8 10 SA-KEY-NUMERIC PIC 9(2). 000250
- d 10,14 u v2 // 10 03 SA-PAC-DEC-1 PIC 9(7)V99 COMP-3. 000300
- e 15,19 // 20 03 FILLER PIC X(5). 000350
- d 20,21 u // 25 03 SA-PAC-DEC-2 PIC 999 COMP-3. 000400
- d 22,23 // 28 03 SA-PAC-DEC-3 PIC S9(3) COMP-3. 000450
- e 24,29 // 32 03 FILLER PIC X(6). 000500
- b 30,33,=9; // 38 03 SA-SIGNED-BINARY PIC S9(9) COMP. 000550
- e 34,41 // 48 03 FILLER PIC X(8). 000600
- z 42,46 // 56 03 SA-ZONED-DECIMAL PIC S9(5). 000650
- e 47,50 // 62 03 FILLER PIC X(4). 000700
- u 51,55 // 66 03 SA-ANOTHER-NUMERIC PIC 9(5). 000750
- l 56,59,=7; v2 // 71 03 SA-FLOAT PIC S9(5)V99 COMP-1. 000800
- l 60,67,=12; v2 // 80 03 SA-DOUBLE PIC S9(10)V99 COMP-2. 000850
- e 68,114 // 94 03 FILLER PIC X(47). 000900
- // 140 (RecLen)
-
- Note that the "r=114,0" line was produced automatically. The first column
- of numbers past the comment lead-in characters gives the beginning column
- numbers for the translated fields. The final comment gives the length of
- the translated record, not counting the newline terminators.
-
-
-
- Options for COBOL2V.VDM
- -----------------------
-
- COBOL2V.VDM now supports command line options via the "-u option_list"
- parameter on its invocation line:
-
- vpw -x cobol2v.vdm myfile.cob -a myfile.lay -u option_list
-
- The option_list can be any of the following, separated by spaces:
-
- DOS UNIX MAC DBASE ISHORT NORELAY CC=column_number NAMES
-
- When "-u" is not specified, the defaults are DOS and CC=20.
-
- The "-a myfile.lay" parameter, above, renames the output file to "myfile.lay"
- while leaving the source file "myfile.cob" unaltered.
-
- COBOL2V.VDM now generates the "r=reclen" specification automatically.
- The default is to generate "r=reclen,0" for DOS-terminated output lines.
- Specify "-u UNIX" to generate "r=reclen,1" to append just a Line-Feed
- character to the translated output records.
-
- The default starting column for comments is currently 20. To change this
- to column 'n', specify "cc=n".
-
- Ordinarily, COBOL2V.VDM invokes RELAY.VDM, which converts "+size" to
- "begcol,endcol" format and places the output column numbers into the
- comment field. To keep the "+size" format use "-u NORELAY". To then
- generate output column numbers, run RELAY.VDM, perhaps with "-u INSERT".
- To later convert the "+size" format to "begcol,endcol", run RELAY.VDM
- with the "-u CONVERT" option.
-
-
-
- COBOL2V.VDM and DBASE Output
- ----------------------------
-
- The Level-2 translation package can now output records in DBASE format.
- Specifying the "-u DBASE" DOS command line invocation option will generate
- the "r=reclen,DBASE-III" specification in the .LAY file. (It also generates
- a .XRF file containing short field names alongside the COBOL long names).
-
- The Level-2 package can automatically generate short field names to put into
- the DBASE header record. Or, the user can create the short names within the
- comment section of the .LAY file. If this is desired, the "-u DBASE ISHORT"
- options should be included on the COBOL2V.VDM invocation line.
-
- For example, the following output (compressed horizontally) was produced by:
-
- vpw -x cobol2v.vdm cobol.cop -a myfile.lay -u dbase ishort cc=17
-
-
- r=114,DBASE-III // Input reclen, emit DBASE-3 records
- // * ************************************************* 000100
- // * * 000110
- // * SAMPLE COPY-BOOK * 000120
- // * * 000130
- // * RECSIZE = 114 BYTES * 000140
- // * * 000150
- // * ************************************************* 000160
- // 000170
- // 01 SAMPLE-REC. 000180
- // 03 SA-KEY. 000190
- e 1,7 // 2 F1 10 SA-KEY-ALPHA PIC X(7). 000200
- u 8,9 // 9 F2 10 SA-KEY-NUMERIC PIC 9(2). 000250
- d 10,14 u v2 // 11 F3 03 SA-PAC-DEC-1 PIC 9(7)V99 COMP-3. 000300
- e 15,19 // 21 F4 03 FILLER PIC X(5). 000350
- d 20,21 u // 26 F5 03 SA-PAC-DEC-2 PIC 999 COMP-3. 000400
- d 22,23 // 29 F6 03 SA-PAC-DEC-3 PIC S9(3) COMP-3. 000450
- e 24,29 // 33 F7 03 FILLER PIC X(6). 000500
- b 30,33,=9; // 39 F8 03 SA-SIGNED-BINARY PIC S9(9) COMP. 000550
- e 34,41 // 49 F9 03 FILLER PIC X(8). 000600
- z 42,46 // 57 F10 03 SA-ZONED-DECIMAL PIC S9(5). 000650
- e 47,50 // 63 F11 03 FILLER PIC X(4). 000700
- u 51,55 // 67 F12 03 SA-ANOTHER-NUMERIC PIC 9(5). 000750
- l 56,59,=7; v2 // 72 F13 03 SA-FLOAT PIC S9(5)V99 COMP-1. 000800
- l 60,67,=12; v2 // 81 F14 03 SA-DOUBLE PIC S9(10)V99 COMP-2. 000850
- e 68,114 // 95 F15 03 FILLER PIC X(47). 000900
- // 141 (RecLen)
-
- Notice the location of the DBASE names. Names are limited to 10 characters;
- they must begin with a letter and consist only of letters and digits. The
- letter 'F', above, stands for "field".
-
- Also, notice that the first output field starts in column 2. This is due
- to the initial DBASE "deleted-record" field which contains an asterisk to
- denote a deleted record or is blank otherwise.
-
- The purpose of the ISHORT parameter is to produce a uniform 11-character-
- plus-one-space name field that the user can then easily overwrite with the
- desired names. (This field was trimmed above for display purposes). If auto
- generated names are acceptable, this name field is unnecessary. Further, the
- field can be optionally produced later by RELAY.VDM; but, since inactive lines
- are not adjusted, the commented-out copy-book becomes misaligned.
-
- After editing the DBASE names, it is necessary to run RELAY.VDM to produce a
- .XRF file containing the names. E.g., continuing the above example,
-
- vpw -x relay.vdm myfile.lay
-
- produces the file MYFILE.XRF as well as adjusting output column numbers for
- any changes made to the .LAY file.
-
- To instruct EBCDIC-T.VDM to use MYFILE.XRF, include "xrf=1" or "xrf=on"
- in the .LAY file. Thus, a fully edited .LAY file might begin:
-
- //
- // MYFILE.LAY - Sample data layout file for converting EBCDIC files with
- // packed fields into ASCII, output into DBASE style records.
- // Produced from COBOL.COP.
- //
- r=114,DBASE-III // Input reclen, emit DBASE-3 records
- e=0,ebcdic.err // Only report serious errors in EBCDIC.ERR
- o=z,b2z // Output leading zeros (blank '+' sign; sign at end)
- // Convert all-blank/null numeric fields to zeros
- xrf=on // <----- Necessary to force use of .XRF file with explicit field names
- // Otherwise, field names will be auto-generated.
- //
- // * ***************************************** 000100
- // * * 000110
- // * SAMPLE COPY-BOOK * 000120
- // * * 000130
- // * RECSIZE = 114 BYTES * 000140
- // * * 000150
- // * ***************************************** 000160
- // 000170
- // 01 SAMPLE-REC. 000180
- // 03 SA-KEY. 000190
- e 1,7 // 2 KEYNAME 10 SA-KEY-ALPHA PIC X(7). 000200
- u 8,9 // 9 KEYNUM 10 SA-KEY-NUMERIC PIC 9(2). 000250
- ...
-
-
-
- Using the RELAY.VDM Macro
- -------------------------
-
- When an EBCDIC file with packed fields is converted into an ASCII file, the
- records are longer in the ASCII file and the fields do not start in the same
- column as in the EBCDIC file.
-
- The supplied RELAY.VDM macro calculates the (ASCII) output column number for
- each field in a .LAY file and adds the output column number to the .LAY file
- in the comment field. When the DBASE option is selected, it also generates a
- .XRF file containing user supplied field names. See topics "Options for
- RELAY.VDM" and "RELAY.VDM and DBASE Output", below.
-
- The ASCII output column numbers are very useful for viewing the ASCII file
- and for creating a database "import filter". For example, consider the sample
- .LAY from above:
-
- 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
-
- RELAY.VDM changes the sample .LAY file above to:
-
- 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 // 10 Packed-decimal (no sign, explicit decimal point)
- d 20-21 u // 25 Packed-decimal (no sign)
- d 22-23 // 28 Packed-decimal
- b 30-33,=9; // 38 Packed-binary (9 digits; default is 8)
- z 42-46 // 56 Zoned number (5 digits plus sign)
- u 51-55 // 66 Unsigned number; want leading blanks converted to zeros
- //(o=b2z); otherwise redundant
- l 56-59,=7; v2 // 71 Short (single precision) floating point; upto 7 digits
- // with two past a decimal point
- l 60-67,=12; v2 // 80 Long (double precision) floating point; upto 12 digits,
- // 2 fractional
- // 93 (RecLen)
-
- The RELAY.VDM macro is used by COBOL2V.VDM but may be run stand-alone on any
- .LAY file:
-
- c:\vedit\vpw -x relay.vdm layout.lay
-
-
- RELAY.VDM handles numeric output options, taking into account the signed or
- unsigned option, explicit decimal points, maximum # digits to be ouput, field
- padding options, the "quoted-comma-delimited" command "qcd", any user
- specified output field delimiter string, e.g. "v=Reg_Set(XDREG,/ | /)" and
- the DBASE output option (regarding which, see below). Use this macro any time
- a substantive change is made to the layout file.
-
-
- Options for RELAY.VDM
- ---------------------
-
- RELAY.VDM now supports options on its invocation command line:
-
- c:\vedit\vpw -x relay.vdm layout.lay -u option_list
-
- where option_list is any sequence of the following, blank separated:
- DOS UNIX MAC DBASE
- cc=col_num
- INSERT OVERWRITE
- DETAB RETAB
- ISHORT OSHORT
- CONVERT
- NOXREF
- NOD
-
- The options from the first line cause the "r=reclen" line to be
- edited to form:
- r=reclen,0 // DOS
- r=reclen,1 // UNIX
- r=reclen,2 // MAC
- r=reclen,DBASE-III // DBASE
- respectively. The default is to use the "r=reclen" line "as is".
- Output column numbers are affected by the presence or absence of
- DBASE on the "r=reclen" line. Also, see "RELAY.VDM and DBASE Output",
- below.
-
- Specifying "col_num" via the "cc=col_num" option sets the start of the
- comment fields to the specified column.
-
- Ordinarily, when run "stand alone", output-column-numbers overwrite the
- first several columns past the comment indicators. Use the "INSERT"
- option to insert the column numbers instead of ovewriting.
-
- RELAY.VDM detabs the .LAY file when it begins. It again detabs the file
- when finished, unless more than 6 tabs were present in the source file.
- Use one of DETAB, to force, or RETAB, to prevent, the second detabbing.
-
- CONVERT forces RELAY.VDM to change any "+len" field specifications into
- the standard "begin_col,end_col" format.
-
- NOXREF prevents RELAY.VDM from generating/overwriting any .xrf file
- when the DBASE option is present whether specified by the"-u DBASE"
- option or by the "r=len,DBASE-III" line in the .lay file.
-
- NOD forces RELAY.VDM to ignore the presence of any explicit decimal
- point "vn" option on any field specification.
-
-
-
- RELAY.VDM and DBASE Output
- --------------------------
-
- Even when DBASE style output is wanted eventually, it may be desirable,
- while producing the .LAY specifications, to output normal line termination
- characters for easier viewing. To later convert the .LAY file for DBASE
- output, just run RELAY.VDM with the "-u DBASE" option:
-
- vpw -x relay.vdm myfile.lay -a mydbf.lay -u DBASE
- or
- copy myfile.lay myfile.sav
- vpw -x relay.vdm myfile.lay -u DBASE
-
- This will edit the "r=reclen" specification to include the DBASE-III output
- parameter and update the ASCII output column numbers to reflect the
- DBASE initial "record-deleted" field. For example:
-
- r=114,DBASE-III // Input reclen, emit DOS newlines
- ...
- e 1,7 // 2 10 SA-KEY-ALPHA PIC X(7). 000200
- ...
- // 132 (RecLen)
-
- The (unedited) comment in the "r=" specification is now incorrect.
- The first ASCII output field starts in column 2 because of the DBASE
- "deleted-field" column.
-
- Alternatively, one could edit the .LAY file, replacing ",0" with ",DBASE-III"
- and then run RELAY.VDM to update the ASCII output column numbers:
-
- vpw -x relay.vdm myfile.lay
-
- If explicit DBASE field names are desired, you might want to use the
- "ISHORT" parameter:
-
- vpw -x relay.vdm myfile.lay -u dbase ishort
-
- This will generate short names for each field in a uniform 12 space field.
- One can then overwrite the names with the desired explicit field names.
- You must also include the "xrf=on" or "xrf=1" specification in the .LAY
- file. When finished creating the short names, it is necessary to run
- RELAY.VDM again to generate a .XRF file containing the explicit names:
-
- copy myfile.lay myfile.sav // Be safe!
- vpw -x relay.vdm myfile.lay
-
- (Notice the absence of the "-u" parameter).
-
- The pertinent lines from the .LAY file are shown below. See "COBOL2V.VDM
- and DBASE Output", above, for a more complete example.
-
- r=114,DBASE-III // Input reclen, emit DBASE-3 records
- xrf=on // <----- Necessary to force use of .XRF file with explicit field names
- // Otherwise, field names will be auto-generated.
- // Also, RELAY.VDM must have been run to generate the .XRF file
- e 1,7 // 2 KEYNAME 10 SA-KEY-ALPHA PIC X(7). 000200
- u 8,9 // 9 KEYNUM 10 SA-KEY-NUMERIC PIC 9(2). 000250
- ...
-
- Note: "ISHORT" inserts; whereas, "OSHORT" overstrikes.
-
-
-
- Custom Field Conversion
- -----------------------
-
- The layout file can specify the field type of "c" to convert a field using a
- custom VEDIT macro. This topic is complex and specialized; only an overview
- is given here.
-
- Custom conversion fields don't necessarily have anything to do with EBCDIC.
- They could be used to clean up a file which has already been converted to
- ASCII, or even to convert a file which was exported from a Window/DOS
- database or spreadsheet program. For example, it could be used to create
- a file with quoted and comma-delimited fields.
-
- The supplied custom macro LEADZERO.CUS 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.
-
- When specifying custom fields, the name of the custom macro must also be
- specified. For example, the following lines in the layout file use
- LEADZERO.CUS to convert one field:
-
- v=Reg_Load(EBC_Settings(CustomMacro),'leadzero.cus')
- c 15,19 :2 //Insert "." before last 2 digits
-
- The ":2" is an option that can be passed to the custom macro. Its meaning
- will depend upon the particular custom macro.
-
- To enable RELAY.VDM to properly generate ASCII output columns for each field
- into the comment field of the .LAY file, any "inflation" must be indicated
- using the "i=inflation;" option. E.g.,
- c 15,19 i=1; :2 // Inserting '.' before the last 2 digits inflates
- // the output by one column.
-
- If any custom field is encountered in the .LAY file during preprocessing,
- the file "EBCDIC-2.VCM" is loaded. This contains code to process the
- standard fields. Thus, if under certain conditions, a field is to be
- treated specially, the custom code can process it, but otherwise just
- pass the field along. To do this, just "call('code_letter'-32). E.g.,
- if the custom macro wishes to simply unpack a packed decimal field with
- standard options: "call('d'-32)".
-
- Both standard and custom options are available to the custom macro.
- The syntax for the custom field in the .LAY file is:
-
- c colspec [sop] [i=inflation;] [#r] [:cusops] [// comments]
-
- where "sop" are the standard options for any field; "i=inflation" has been
- discussed above; "r" is the text register containing the custom macro
- (default is EBC_Settings(CustomMacro) which is Text_Register 12 unless
- the conversion is being performed under WILDFILE.VDM or WILDFWIZ.VDM).
- To access the custom parameters, switch to the .LAY buffer; CurPos will be
- just past the ":". E.g.,
-
- Buf_Switch(XLAY)
- process custom parameters starting at CurPos.
- Buf_Switch(XDATA)
- process XInpFieldSize data bytes starting at CurPos.
-
- The custom macro must completely process the specified bytes, leaving CurPos
- at the start of the next data field.
-
- Users who need custom conversions and are very familiar with the VEDIT macro
- language can use LEADZERO.CUS as a template for creating their own custom
- macros. LEADZERO.CUS and EBCDIC-T.VDM contain internal (terse) documentation
- on how custom macros work.
-
- However, users may want to contract us to write any needed custom macros.
-
-
-
- Contact Greenview Data, Inc
- ---------------------------
-
- Sales: 1-800-458-3348 sales@vedit.com
- Tech support: (734) 996-1300 support@vedit.com
- Fax: (734) 996-1308
- Website: www.vedit.com
-
- Greenview Data, Inc.
- PO Box 1586
- Ann Arbor, MI 48106