Simtel MSDOS 1992 June/SIMTEL_0692.cdr/msdos/modem/cvtfon2a.arc/CVTFON.DOC

Text File | 1988-08-02 | 25KB | 612 lines

_C_v_t_F_o_n_ _2_._0a (written 02 Aug 88)

CvtFon converts the phone directories of various modem programs
from one format to another.  It supports Boyan, GT Power
14.00/13.00/11.00/9.2/9.1/9.0/8.0/4.2/Pre-4.2, K9X 6.1+, PC-Talk
III, PibTerm 4.0+/3.0, ProComm and ProComm Plus, Qmodem
2.2+/2.0/1.05, Telix 3.0/2.1, and Comma-Separated directory
formats.

The main idea of writing shareware is to let you use the program
before you buy it.  I hope this program facilitates trying out
different programs without going through the hassle of typing in
your phone directory all over again.

CvtFon is also useful for using phone directory utilities for
other programs (such as using QFonEdit to sort your ProComm
directory), changing files to a text file format for printing or
editing, exporting a directory to a database, and more...

NNOOTTEE::

   If you just want to know enough to get a phone directory
converted, and don't want to wade thru a lot of complicated
options, skip down to Basic, No Frills, Want-To-Get-It-Done Usage
below.


_S_y_n_t_a_x

For those who can read it, here is a standard DOS syntax diagram
(just like in the manual).  [Brackets] around an item mean that
it is optional.  Ellipses (...) mean you can use repeat that
item more than once.

CvtFon [?] [path][input file][=type[version]]
       [+[path][input file][=type[version]]]...
       [path][output file][=type[version]]
       [/PARAMETERS:speed[-parity[-data bits[-stop bits]]]]
       [/ECHO:echo] [/PROTOCOL:file transfer protocol]
       [/TERMINAL:term type] [/MAXSPEED:maximum speed]
       [/SORT[:field]] [/WIPE[:field]] [/KEEP] [/CHOOSE]
       [/INCLUDE:include string]... [/EXCLUDE:exclude string]...
       [/PREFIX:prefix[-digits]] [/SUFFIX:suffix[-digits]]
       [/DEFIX:affix]

Whew!  No one expects you to remember all that.  CvtFon will
display the syntax diagram for you if you type "CVTFON ?".
All those /OPTIONS are explained in the section titled Options
below.  I suggest that instead of trying to read the whole thing,
you read the other sections and just refer to that one when you
want to know how a particular option works.

I'll assume a basic familiarity with basic DOS concepts like
paths and subdirectories.  If those concepts are foreign to you,
DOS has a manual of its own, and many books are written on
understanding DOS.  (This isn't a professional manual.  If you
can't make head or tail out of it, or find someone who can, my
address is below.)


_I_n_p_u_t_ _a_n_d_ _O_u_t_p_u_t_ _F_i_l_e_s

CvtFon can read more than one input file.  Just type + before
every input file name after the first.

If the output directory has a fixed size (like a Qmodem
directory always contains 200 entries), CvtFon will insure that
the directory contains the proper number of entries.  For
example, CvtFon would only write the first 200 phone numbers to a
Qmodem directory, or add blank entries on the end if there were
less than 200.

*** Basic, No-Frills, Want-To-Get-It-Done Usage ****** Basic, No-Frills, Want-To-Get-It-Done Usage ***

    The simplest way to use CvtFon is to tell it what files to
    use and what kind they are.  You do this by specifing the
    full file name and directory type for every file.

    For example, to translate your Qmodem SST 3.0 QMODEM.FON
    directory to a PibTerm 4.1 PIBTERM.FON directory, you could
    type:

       CvtFon QMODEM.FON=QmodemSST3.0 PIBTERM.FON=PibTerm4.1

    That is all you really need to know to convert a directory
    from one format to another.  However, there are shortcuts if
    you know how to use them, and lots of options.  You can skip
    these if you just want to get the darn thing translated
    already.

Shortcut #1:  How to specify a directory type with only part of
              the program name

    By no means do you actually have to type =GTPowerComm12.10 to
    specify a GT PowerComm 12.10 directory.  =GT12.1 is enough
    for CvtFon to know what you mean.  As a rule, you need only
    type just enough letters to distinguish it from any other
    program.

    Example:  CvtFon only knows of one program beginning with Q,
    so =Q has the same effect as =QMODEM.  However, =P could mean
    ProComm, ProComm Plus, PibTerm, or PC-Talk III.  Two or three
    letters should be enough for any program except ProComm Plus,
    which requires =PROCOMMP to distinguish it from ProComm
    (OK, I got tired of typing it myself.  So, allow me to
    document the undocumented synonym of =PCPLUS, making =PCP
    the LCD.).

    You may have noticed I dropped the version numbers in the
    last example.  They usually aren't necessary.  When you don't
    give CvtFon a version number, CvtFon assumes you mean the
    latest version it knows about.

    Example: =QMODEM or =Q means the Qmodem 2.2 (and later)
    format, but for a Qmodem 2.0 file you would have to type
    =QMODEM2.0 or just =Q2.

Shortcut #2:  How to let CvtFon figure out the directory type

    If you don't tell CvtFon what kind of directory a file is,
    CvtFon will try to figure out the directory type from the
    file size.  This method only works for directories that are a
    fixed size (like a Qmodem directory, which is always 200
    entries long).  Some directory types don't have a fixed size
    (ex. GT Power), and even when they do, sometimes they'll have
    extra bytes tacked on the end.

    For instance, if you download a ProComm directory from a BBS
    with XMODEM, it might end up 4224 bytes long rather than 4150
    because of bytes "padded" on in order to send it in even 128-
    byte bundles.  You would have to append =PROCOMM to the input
    file name so that CvtFon would recognize it.

    If you give CvtFon an output file name but don't give it a
    directory type, CvtFon tries to determine the type of the
    directory if the file already exists.

Shortcut #3: How to let CvtFon figure out the file name

    When a directory type is given without a file name, the
    default file name for that program's phone directory is used:

        Program           Phone directory file name
        -------           -------------------------
        Boyan             BOYAN.FON
        Comma-Separated   input file with .CSV extension
        GT Power(Comm)    GT.DIR
        K9X               K9X.P
        Qmodem            QMODEM.FON
        PibTerm           PIBTERM.FON
        PC-Talk           PC-TALK.DIR
        ProComm           PROCOMM.DIR
        ProComm Plus      PCPLUS.DIR
        Telix             TELIX.FON

    For example, CVTFON =QMODEM =BOYAN converts QMODEM.FON to
    BOYAN.FON.

    If the file name ends in ':' or '\', CvtFon uses it as a
    path, and appends the default file name for that directory
    type.  For example, CVTFON \QMODEM\=QMODEM \BOYAN\=BOYAN
    would convert \QMODEM\QMODEM.FON to \BOYAN\BOYAN.FON.

    Example:

    CVTFON PC-TALK.FON=PC-TALK +\QMODEM\=QMODEM2.0 +=PRO
           FONDIRS.TXT=PIB

    will read a PC-Talk III directory named PC-TALK.FON, a Qmodem
    2.0 directory named \QMODEM\QMODEM.FON, and a ProComm
    directory named PROCOMM.DIR, then write all the entries to a
    PibTerm text-file phone directory named FONDIRS.TXT.


_E_x_a_m_p_l_e_s

Here's an example or two to illustrate the use of CvtFon, taking
advantage of the shortcuts listed above.

You have the ancient DIALER program (a memory-resident background
auto-dialer) on a Qmodem 1.13 disk, and you want to convert your
Qmodem 2.2 directory to a Qmodem 1.13 directory for DIALER.  You
could enter CVTFON =QM =QM1.13.

Or, you simply want to update your GT PowerComm 9.0 directory to
a GT PowerComm 13.00 directory.  CVTFON =GT9 =GT would be
sufficient.


_O_p_t_i_o_n_s

Proceed at your own risk.  There are too many to memorize in one
sitting, so please, feel free to skip this secton and just refer
to it later when you want to know about a particular switch.  If
you can't remember what the switch was called, you can type
CVTFON ? for a reminder.

Help (?, /? or /HELP)

    Display a brief help message.  The same message is displayed
    when CVTFON is typed alone without any parameters.

Default Parameters (/PARAMETERS:speed[-parity[-data[-stop]]])
Default Echo (/ECHO:echo)

    When blank entries are written, the parameters and echo are
    set to defaults.  The defaults used are 1200 bps, no parity,
    8 data bits, and 1 stop bit, and no echo, but you can specify
    different defaults with these parameters.

    Example:

        CVTFON PC-TALK.DIR=PCTALK3 QFONEDIT.BAQ=QMODEM2.2
               /ECHO:YES /PARAMETERS:300-EVEN-7

    would read PC-TALK.DIR and write the entries to a Qmodem 2.2+
    phone directory named QFONEDIT.BAQ.  Since a PC-Talk III
    directory holds at most 60 numbers, and a Qmodem directory
    always contains 200 entries, at least 140 blank entries will
    be written.  These entries will be written with parameters of
    300 baud, even parity, 7 data bits, 1 stop bit, and echo on.

Default File Transfer Protocol (/PROTOCOL:transfer protocol)

    Some programs have a default file transfer protocol field.
    CvtFon normally sets this field to "none" when writing blank
    entries in this format, but you can specify another with this
    switch.  CvtFon uses PibTerm's two-letter protocol
    abbreviations internally, with a few additions.

        Abbrev.  Protocol
        -------  --------
          XK     XMODEM Checksum
          XC     XMODEM CRC
          X1     XMODEM/1K      (called "YMODEM" by GT Power,
                                 Qmodem)
          M7     MODEM7         (a weird XMODEM Batch)
          TE     Telink         (a less weird XMODEM Batch)
          T1     Telink/1K      (a GT Power exclusive,
                                 basically XMODEM/1K Batch)
          YM     YMODEM         (often XMODEM/1K in disguise)
          YB     YMODEM Batch   (True YMODEM, often called
                                 "YMODEM Batch" by programs
                                 that call XMODEM/1K "YMODEM")
          YG     YMODEM/G
          SL     SEAlink
          ML     Megalink
          ZM     ZMODEM
          KE     Kermit
          WX     WXMODEM
          CB     CIS B
          IM     Internal modem protocol

Default Terminal Type (/TERMINAL:term type)

    Some programs have a field for a terminal type to emulate.
    CvtFon normally sets this field to "none" when writing blank
    entries in this format, but you can specify another with this
    switch.  CvtFon uses three-letter terminal abbreviations
    internally, of my own design.

        Abbrev.  Protocol
        -------  --------
          TTY    TTY
          V52    VT52
          V10    VT100
          V12    VT102
          ANS    ANSI (used by many BBS systems)
          AVT    AVATAR (used by Opus BBS)
          IBM    IBM 3101
          327    3270
          H19    Heath/19
          AVP    ADDS Viewpoint
          AD3    ADM 3a
          AD5    ADM 5
          TEK    TekTronics 4010
          T91    Televideo 910
          T92    Televideo 920
          T93    Televideo 925
          T95    Televideo 950
          T96    Televideo 955
          WY5    WYSE 50
          WY1    WYSE 100

          And for PibTerm:

          GSP    Gossip (split-screen) mode
          HST    Host mode

Maximum speed (/MAXSPEED:maximum speed)

    Any speeds above the limit you specify will automatically be
    reduced to the speed limit.  If you have a 9600-baud modem at
    work, and a 1200-baud modem at home, you could use this
    option to change all the 2400, 4800, and 9600 baud entries
    into 1200 baud ones.  You could use a batch file to
    automatically convert the directory, then replace it with the
    original, like this one for DOS 3.x:

        if "%PLACE%"=="OFFICE" goto :COMM
        if not "%PLACE%"=="HOME" goto :NOPLACE
        copy QMODEM.FON QMODEM.BAQ
        CvtFon QMODEM.BAQ =QMODEM /MAX:1200
        if ERRORLEVEL 1 goto :END
        :COMM
        Qmodem
        if not exist QMODEM.BAQ goto :END
        copy QMODEM.BAQ QMODEM.FON
        del QMODEM.BAQ
        goto :END
        :NOPLACE
        echo Please SET PLACE equal to HOME or OFFICE.
        :END

Sort (/SORT[:sort field])

    Sort entries by name, or any other field you specify.  In
    name sorting, if the first word is 'the', it is skipped.

    You can sort on NAME, PHOME number, SPEED, PARITY, DATA bits,
    STOP bits, ECHO, SCRIPT, PROTOCOL, TERMINAL type, number of
    CALLS, DATE of last call, TIME of last call, PASSWORD, or
    HOURS.  (I'm sure you've always wanted a program that could
    sort your phone directory by Echo on or off...)

    In addition, there are two pseudo-fields, AREA code and
    EXCHANGE.  These apply to AT&T phone numbers, international
    dialing and other phone number formats probably wouldn't
    work.  They both ignore any punctuation.  For example, "1 201
    463 0001", "[phone]" would both return 201 as the area
    code and 463 as the exchange.  Letters in this field are
    translated into digits, AT&T style.

Wipe (/WIPE[:field])

    Erase the contents of a particular field in conversion.  If
    you don't specify a field, it assumes you mean passwords.
    See /SORT above for a list of valid field names.

    For every entry, the field is blanked or set to the default
    for fields that you can give defaults for.  Wiping the
    password would leave blank passwords for every entry, but
    wiping the speed would set it to the default speed.

    For example, you're giving someone a copy of your phone
    directory, and you want to erase all the passwords, scripts,
    and last call dates for her.  You might use /WIPE
    /WIPE:SCRIPT /WIPE:DATE to clear those fields.

    Or, you just got a 2400 baud modem that "cycles down" to the
    correct baud rate when it connects.  You want to set the
    speed on all the entries to 2400, and let the modem choose
    the fastest speed possible for each number.  You could use
    /PARAM:2400 /WIPE:SPEED.

Include (/INCLUDE:search string)

    Include only entries containing a particular string in the
    name or phone number fields in the output file.  You can get
    very specific by selecting more than one.

Exclude (/EXCLUDE:search string)

    Exclude all entries containing a particular string in the
    name or phone number fields from the output file.  You can
    get very specific by selecting more than one.

Prefix (/PREFIX:prefix[-digits])

    Tacks on a prefix.  If you specify a number of digits, the
    prefix will only be attached to phone numbers with that
    number of digits.  Useful for adding a prefix to long-
    distance numbers. Only the last dash is used to separate the
    number of digits, any others are assumed to be part of the
    prefix.

    Example:

    I'm in California and want to call BBS's back home, only to
    find that all the northern Jersey numbers in my Qmodem
    directory don't have an area code attached.  I'm in the
    directory containing Qmodem, and I don't feel like typing
    more than I need to, so I enter CVTFON =Q =Q /PRE:(201)-7 to
    attach the area code to only the 7-digit phone numbers (the
    ones without area codes attached).

Suffix (/SUFFIX:suffix[-digits])

    Like /PREFIX, but tacks on a suffix, instead.

    Example:

    You're converting your Qmodem phone directory, in the
    \COMM\QMODEM subdirectory on your hard disk, into a Boyan
    directory, in the \COMM\BOYAN directory on your hard disk.
    You want to use the ! macro to dial Sprint and wait for it to
    answer, and the @ macro to send the access code after the
    phone number.  In Boyan, you do that by putting \! before and
    \@ after the phone number in the phone directory.  You might
    enter:

    CVTFON \COMM\QMODEM\QMODEM.FON=QMODEM
           \COMM\BOYAN\BOYAN.FON=BOYAN
           /PREFIX:\!-10 /SUFFIX:\@-10

Delete Affix (/DEFIX:affix)

    Deletes a prefix or a suffix.

    Example:

    You live in the 415 area code and you want to sort all your
    entries by area code.  The local numbers don't have area
    codes attached in your phone directory, but you want them
    sorted as if they did.  You could use /PREFIX:(415)-7
    /SORT:AREA, then run CvtFon again with /DEFIX:(415), so that
    the entries in your area code would be positioned that way.

Choose (/CHOOSE)

    Displays each entry on the screen and allows you to decide
    whether to write it to the output file or not.

Keep Blanks (/KEEP)

    Reads blank entries (defined as those without meaningful
    phone numbers), so that deliberate spacing between entries
    will be preserved (to keep them on separate directory "pages"
    for example).  Usually they are ignored when encountered, so
    that they are not written to the output file (which may or
    may not put them on the same "page").

Long Distance Strings (/PLUS, /MINUS, /AT, /POUND, and /BANG)

    ProComm uses the characters +, -, @, #, and ! for phone
    number affixes.  PC-Talk III uses only + and -.  ProComm Plus
    uses affixes lettered letters A-J (CvtFon treats A thru E
    like + thru !).  They all store the strings attached to these
    macros in the phone directory.  CvtFon will convert these
    properly.  However, every time you convert from ProComm to
    Qmodem to ProComm again, you would lose them, since Qmodem
    saves the affixes in a separate file.  So, CvtFon will let
    you specify values for these macros with the /PLUS, /MINUS,
    /AT, /OCTOTHORPE, and /EXCLAMATION parameters (/+, /@, /#,
    and /! are also acceptable, but /- is not).

    Example:

    You use the ! macro in ProComm to dial the Sprint long
    distance system, wait for it to answer, and send a 0 before
    the phone number, and the @ macro to follow it with your
    Sprint access code.  You could use a batch file to convert
    your Qmodem directory to a ProComm directory, and write it
    with the same macros.  The batch file would contain a line
    like:

    CVTFON QMODEM.FON=QMODEM PROCOMM.DIR=PROCOMM
           /!:1-800-877-8000,,,0 /@:12345678901234


_I_m_p_o_r_t_i_n_g_ _t_o_ _D_a_t_a_b_a_s_e_s_ _w_i_t_h_ _C_o_m_m_a_-_S_e_p_a_r_a_t_e_d_ _F_i_l_e_s

Many database programs will read files in comma separated form,
one entry to a line, each field separated by a comma, numbers
left alone and everything else enclosed in "quotation marks".
It's an easy format to write a program to read, too.

Of course, a program needs to know what order the fields are in.
CvtFon always reads and writes in this order: Name, Phone number,
Speed, Parity, Data bits, Stop bits, Echo, Script, Protocol,
Terminal type, number of Calls, Date of last call, Time of last
call, Password, Hours.

Most programs don't use one or more of these fields.  CvtFon
writes only the fields it has read, and any in between to
preserve this order.  For example, if none of the input files
contain Echo, Calls, Date, Time, or Password fields, CvtFon would
write the fields, by the order listed above, up to Protocol,
using the default value for echo.

Comma-separated input files should be in the same order.  CvtFon
will read them line by line, reading as many fields in the above
order as it finds.


_C_o_m_p_a_t_i_b_l_e_ _P_h_o_n_e_ _D_i_r_e_c_t_o_r_i_e_s

Some communications programs use phone directory files that are
compatible with those of existing programs, or require only
slight modification.  Here are a few:

Canine Express (K9X) version 4.50 uses a 228-entry PibTerm-format
phone directory named K9X.P.  Some earlier versions were the same
but without the last three columns- parity, data bits, and stop
bits- since Canine is fixed (ouch!) at N-8-1.

Various flavors of PC-Talk abound.  CompuServe has one in
particular that supports the B protocol and more than 60 entries.
To allow for this, CvtFon will read as many entries as it finds,
but can only write standard PC-Talk III files.

The shareware program called Termulator was renamed to ProComm
early on because of a commercial program with the same name.
ProComm versions earlier than 2.3 do not allow scripts (called
"command files" in ProComm) to be attached to directory entries.
However, the directory structure is the same, since extra space
was left for future expansion, only the file name, TERMULTR.DIR,
is different.

Lotus 1-2-3 can read comma-separated files if the lines end with
a trailing comma and the .PRN extension is used.  The .CSV files
CvtFon writes can be made into .PRN files with little difficulty,
and .PRN files may be read without modification.


_E_r_r_o_r_s

Most errors cause CvtFon to abort, display an error message, and
return an ERRORLEVEL reflecting the kind of error encountered:

     1 = User break
     2 = DOS error
     3 = I/O error
     4 = Critical error
     5 = Fatal error
     6 = Other error

A user break is returned if you halt the program with Ctrl-Break
or choose the Abort option in Choose mode.

Most DOS and I/O errors are external, that is, caused by
conditions outside CvtFon.

Critical and Fatal errors are usually internal bugs in the
program itself.  This could be faulty programming or perhaps just
a garbled download.

Other errors are mistakes that I went to the trouble to check for
specifically.  Many are caused by invalid command line
parameters.  You can get a brief reminder the command syntax by
typing "CVTFON ?".


_F_u_t_u_r_e_ _F_e_a_t_u_r_e_s

Future versions may or may not be able to:

 o Read DIF files. [(tm) Software Arts, Inc.]
 o Sort on two or more fields.
 o Ask the user questions with magic windows and everything.
   Be usable.  Grow much bigger.
 o Read/write comma-separated files with other field configurations.
   Probably by choosing from a magic window.

 o Support other modem programs.  If you have one you wish
   supported, tell me about it!  Better yet, tell me the
   format!


_S_u_g_g_e_s_t_i_o_n_s

If you find this program useful, please send any comments,
complaints, and correspondence to:

   Steve Linhart
   Re: CvtFon 2.0a
   R.P.O. 5139, CN 5063
   New Brunswick, New Jersey  08903

or call my BBS, The Cork Board, at [phone].  You can also
send FidoNet mail to node 1:107/345.


_C_o_n_t_r_i_b_u_t_i_o_n_s (or "What? He's letting me off the hook?")

I may regret this now that I'm in college, but, yes, I'm letting
you off the hook.  In a way, this program is my payment to the
authors of the communications programs involved.  It would
simplify things for me if in return, my name appeared on their
mailing lists (hint, hint).

Pay for whatever communications program you settle on, then if
you still feel obligated to pay for this program, send your money
to a worthy charity, public television, or listener-supported
radio.


_D_i_s_t_r_i_b_u_t_i_o_n_ _N_o_t_i_c_e

Free license is granted to the public for non-commercial use, and
to all users to give unmodified copies of this program to others.
Please share this program with anyone who might find it useful.

I encourage the distributors of Boyan, GT Power, K9X, PC-
Talk, PibTerm, ProComm Plus, Qmodem, and Telix to include CvtFon,
unmodified, on their distribution media, as long as they don't
encompass it in their license agreements, or increase the cost of
their distribution media solely for the inclusion of this
program.  (In other words, if you license only your own programs
on the disk, not the entire disk, and don't charge extra for
throwing in CvtFon.)

ProComm Plus is a registered trademark of Datastorm Technologies,
Inc.

1-2-3 and Lotus are registered trademarks and DIF is a trademark
of Software Arts, Inc.
FidoNet is a trademark of Tom Jennings.
MS-DOS is a trademark of Microsoft, Inc.
Turbo Pascal is a trademark of Borland International.