ProfitPress Mega CDROM2 …eeware (MSDOS)(1992)(Eng)/ProfitPress-MegaCDROM2.B6I/TEXT/UTILITY/CTRANS15.ZIP/C-TRANS.DOC

Text File | 1992-04-11 | 14.4 KB | 415 lines

                              C-TRANS
                              ═══════


               Fast, flexible Character Set Translator

       (c) Copyright 1990,91 by Klaus Hartnegg, D-7835 Teningen




Description
───────────
C-Trans is a fast, flexible translator between any two character sets.
It can act either on disk files or as filter for pipes.

Translation tables for Ascii <--> Ebcdic translation are built in.
You can easily create your own translation tables or modify existing
ones.



Usage
─────
Syntax :  C-TRANS /options [infile [outfile]]

Options: You can place options on the command line wherever you want.

   E2A          convert from EBCDIC to ASCII

   A2E          convert from ASCII to EBCDIC

   F <filename> read conversion table from file. For a description
                of the syntax for this file read the section
                "Translation Tables" below.

   I            invert translation table, i.e. do the reverse
                translation.


Infile and outfile are the names of an input and output-file. When
outfile is omitted, a temporary file will be used and be moved over
infile after the conversion has ended successfully.

Infile and outfile may contain wildcard characters "?" and "*".

Infile may be a directory instead a file. In this case all files
within this directory will be converted.

Outfile may be a directory too. In this case the name for the output
file(s) will be derived from the input file(s).

When both infile and outfile are directories all files from
the input directory will be converted and the results be written
to the output directory.


You can also use C-TRANS as a unix-like filter i.e. it can read data
from the standard input and write the translated data to standard
output. C-TRANS will assume being used as filter whenever the standard
input is being redirected. Please read your DOS manual to learn more
about pipes and how redirecting standard input and output.



Examples:

- convert the file "ANY.TXT" from EBCDIC to ASCII
  C-TRANS /e2a ANY.TXT

- convert "EBCDIC.TXT" to "ASCII.TXT"
  C-TRANS /e2a EBCDIC.TXT ASCII.TXT

- convert all files in the directory "D:\TEXTS\EBCDIC" from EBCDIC to ASCII
  C-TRANS /e2a D:\TEXTS\EBCDIC

- the same again but leave files in D:\TEXTS\EBCDIC alone and
  write output to D:\TEXTS\ASCII
  C-TRANS /e2a D:\TEXTS\EBCDIC D:\TEXTS\ASCII


use C-TRANS as unix-like filter:

- show EBCDIC.TXT on screen using MORE:
  TYPE EBCDIC.TXT | C-TRANS /e2a | MORE

- as above but add missing line feeds (will need separate program CrLf!)
  TYPE EBCDIC.TXT | C-TRANS /e2a | CRLF | MORE



Batch files
───────────
To create batch files E2A and A2E for conversion from ebcdic to
ascii and vice versa, just issue these two DOS commands:
    echo c-trans %1 %2 /e2a >e2a.bat
    echo c-trans %1 %2 /a2e >a2e.bat

Note however that DOS does not allow to use batch files as filters.
If you want to pipe a file through such a batch file, you have
to use this construction:  type test.txt | command /c e2a
instead of                 type test.txt | e2a
of course you can also use type test.txt | c-trans /e2a

This is a restriction of DOS, not one of c-trans.


Default Options
───────────────
If C-TRANS finds a file "C-TRANS.OPT" it will accept the content of it's
first line as default options. Options that you include on the command
line will be appended to these default options. The options A, E, and I
work as toggle-switches, i.e. you can include an option already present
as default option on the command line again to reset it.

C-TRANS.OPT will first be searched in the current directory and then in
the same directory where C-TRANS.EXE resides in.



A note for Unix users
─────────────────────
This program will usually accept both
a) '/' and '-' as switch character (to start an option)
b) '\' and '/' as path separator
But: you can not start a filename with '/'.

However if you have your switch character variable set to a different
value than the default (the default is '/', changing it is not possible
any more with Dos 5) then
a) your value OR '-' can be used as switch character
   (or only '-' if this is your value)
b) filenames are allowed to start with '/'



Technical notes:
────────────────
When codes are encountered that C-TRANS can not translate, their position
and the unknown code will be shown. When there are more than 10 errors
in a file C-TRANS will switch to batch-mode and show no more errors. In
this case the total number of errors will be displayed at the end of the
conversion.

C-TRANS will conserve the file date when it is not used as filter.

Execution speed is about 6 kByte per second on a 12 MHz AT but will
decrease dramatically if there are less than 100 kByte RAM available.

Please note that in many EBCDIC-coded texts, lines are terminated with
carriage return only but no line feed or vice versa. You can use my
program CRLF after converting to ASCII to correct this. For the same
reason you may want to use STRIPCrLf to remove all carriage returns
or line feeds before converting to EBCDIC. Both programs are included
in my software package CRLF. If you need them try looking at the same
source from where you got C-TRANS.

If you can't find CRLF there look in SIMTEL or just register C-TRANS,
you will automatically get unregistered versions of other programs,
that I am distributing as shareware, including (of course c-trans).
See the file HARTNEGG.LST for a list of all programs.


Using your own Translation Tables
─────────────────────────────────
You can use C-TRANS to do any translation that you want by supplying your
own translation table. You only have to do two things:
1. Use a text editor to create a text file that contains 256 numbers in
   the range -1..255 separated by blanks and/or line breaks.
2. then tell E2A to use this file as translation table with the /F-option
   described above by supplying the name of this file

C-TRANS interprets the numbers in this file in the following way:
the numbers themselves are the codes that shall be generated and their
position in the file determine which characters will be translated to this
code. Example: the very first number in that file is the code to that all
input characters with code 0 will be translated. The second number is the
code to that all input characters with code 1 will be translated and so on.

When C-TRANS finds a -1 in this file, it reports to have found a character
that it can't translate whenever the corresponding code is encountered
in the input.

I have included six examples that you may simply use as your translation
tables or you may use one of them to start with when building your own table:

ASCII.DAT   This file contains IBM's official translation table (*) from
            EBCDIC to ANSI X3.4-1977 ( = 7 bit ASCII). I found it in
            the appendix of a fortran reference book describing IBM'S
            Fortran for VM/CMS operating system.

ISO.DAT     contains IBM's official translation table (**) from EBCDIC
            to ISO 2022, found in the same book.

3090.DAT    This one contains the EBCDIC to ASCII translation table of an
            IBM 3090 running VM/CMS that I am working on at the university.
            Sorry, I have no idea why IBM's computers use a different
            translation than listed in their own tables.

3270.DAT    This is even one more EBCDIC to ASCII translation table. It is
            taken from a 3270-Terminal description; also directly from IBM.

E2A.DAT     This is a mixture of 3090.DAT and 3270.DAT which is
            possibly the best choice for an EBCDIC to ASCII translation
            but not very useful when reverted.

DEFAULT.DAT this contains the default translation table of E2A. It
            differs from ASCII.DAT for 7 characters taken from 3090.DAT,
            see below (***). I didn't use E2A.DAT as default because that
            seems to be not so good for ASCII to EBCDIC translation.


(*) well, not exactly. I have corrected some obvious errors:

       ┌─────────────────────────────────── EBCDIC-code
       │        ┌────────────────────────── IBM's official description
       │        │               ┌────────── IBM's official table
       │        │               │      ┌─── my change
       │        │               │      │

       77  left parenthesis    43 +  ┐ 40 (
       78  plus sign           33 ! ┐└ 43 +
       79  logical or          -    └  33 !
       90  Exclamation point   93 ]    33 !


(**) I have again corrected an obvious error:

       90  Exclamation point   93 ]    33 !


(***) the differences between ASCII.DAT and DEFAULT.DAT are:

       13  Carriage return     13 CR   -1     ─┐ I have no idea why the 3090
       21  new line ack.       -1      13 CR  ─┘ uses these two reversed
       74  Cent sign           91 [   155 ¢
       79  logical OR          33 !   124 |
      106  vertical line      124 |   179 │
      173                      -1      91 [
      189                      -1      93 ]



In spite I had some official documents directly from IBM I was not
able to find the ultimate translation tables. I guess such a thing
does not exist since every Ebcdic implementation seems to be a bit
different. Finally I found the table now included in DEFAULT.DAT, that
seems to be the best compromise. It allows to convert in both
directions when working with the IBM 3090 running VM/CMS that we have
at the university. I'm not sure whether that table will work fine on
all IBM's.

When someone can find better translation tables - please tell me!



Known Bugs:
───────────
Please avoid translating a file to itself. The contents of that
file can get lost.


Revision history
────────────────
1.0,  July 1990
program started as a slow, unflexible Ebcdic to Ascii convertor

1.1,  August 1990
- command line options
- reverse translation
- user definable translation table
- default options in disk file

1.2, September 1990
- error messages were written to the output file rather than to the
  screen when output was redirected
- included 3270.DAT
- included E2A.DAT
- key-file support for easier registration

1.3, October 1990
- changed translation table DEFAULT.DAT. Now ASCII to EBCDIC works better
- added - and / support for unix users

1.4, November 1990
- some more errors in the file search routine
- wildcards now allowed on unregistered copies too
- 5 second registration reminder
- visual byte counter during the translation

1.41, 10-Feb-1991
- circumventing error of DR-DOS with directory detection

1.42, 16-Feb-1991
- the previous version didn't work on XT's

1.5, 01-Aug-1991
- some minor error corrections
- speed increased by 15%
- uses unique filename now for temporary file
- renamed from E2A to C-TRANS
  (registered users of E2A can request new key-files for free)

1.5a, 10-Apr-1992
minor changes only, cleaned up a little bit


future plans:
─────────────
- enhanced error detection
- enhanced wildcard-handling
  (allow things like "*DAT.TXT" and "F*1.DAT")
- option to exclude some files from the conversion process

You can encourage me to spend much more time into the further
development of this program by paying the registration fee!



Included files
──────────────
C-TRANS .EXE  the executable
C-TRANS .DOC  this documentation

ASCII   .DAT ┐
ISO     .DAT │
DEFAULT .DAT │ sample translation tables
3090    .DAT │
3270    .DAT │
E2A     .DAT ┘

ORDER   .FRM   order form
HARTNEGG.LST   list of all my shareware programs



Disclaimer
──────────
It is a well known fact that it is impossible to proof that any given
(non trivial) program is error free. Of course this software has been
tested extensively but is is nevertheless not possible to guarantee that
it will work correctly in all possible situations.

This software is provided as-is, without warranty of any kind. The
author shall not be liable to the user for any direct, indirect or
consequential loss arising from the use of or inability to use this
software.



License
───────
This is a shareware product and thus not free. It is fully protected by
international copyright laws.

Shareware is distributed through public access channels so that you can
evaluate it before deciding wether or not to buy it. If you decide to
use this software then you are both under legal and moral obligations to
register it (see separate file ORDER.FRM for a registration form; Visa
and Master Card accepted!). If you decide not to use it you are under no
obligation, just don't use it any more.

All corporate, business, government or other entities have to register
BEFORE using this software.

You are free to copy and distribute this software as long as all files
belonging to it are distributed together and are not modified in any
way. If possible please distribute the original ZIP archive.

You must NOT give the key-file away (see below). This file is proof of
your registration and contains your name and serial number.



Registering
───────────
Upon payment of the registration fee you will receive a diskette with
- the current versions of ALL programs that I distribute as shareware
- the key-file(s) for the program(s) that you registered
  (if any of my programs finds its corresponding key-file it will not
  display the annoying shareware reminder any more)

FREE UPDATE to ALL future versions: the key-files will not only work for
the present, but also for all future versions of the same program, i.e.
you have to register only once!


The shareware system and the continued availability of quality shareware
products depend on YOUR willingness to register and pay for the software
that you use. It's the registration fees YOU pay which allows to support
and continue to develop such products! Without this support I can not
continue spending so much time in improving this program.

Show your support for shareware by registering those programs you
actually use. Shareware is kept alive by YOUR support!


────────────────────────────

   Klaus Hartnegg
   Kleist-str. 7
   D-7835 Teningen
   Germany


This software is under development. Error reports and other comments are
welcome. Please do not hesitate to use electronic mail for communication.
(these addresses may be valid only until end of 1992)

Bitnet   : hartnegg@dfrruf1
Internet : [e-mail]