README for PPPDIAL.CMD

     OS/2 WARP REXX script to redial a PPP provider when busy. 

      Written by: Don Russell (c) April 1995
      send email to drussell@direct.ca

Change log: (most recent first)
     10 May 1995: Version 2.3
                    Recognize "protocol" response from Megahertz modem.
                    Add support to send CTRL- sequences from response file
                    Add support to issue OS/2 commands from the response file
                    Fix redialing when using the new slippm.exe from IBM (V2.0 R1.8h)
                    Additional [PPPDIAL...] response file parameters
     23 April 1995: Version 2.2
                    Recognize more modem responses...
                    Change some logic to make it easier to customize
                       to reject slow connections.
                    Improve response file handling.
                    Add response file keywords for setting pppdial parms.
                    Fix a bug or two :-)
     15 April 1995: Version 2.1
                    Fix processing of "hung connection"
                    (Dropped by V2.0 changes :-(  )
     14 April 1995: Version 2.0
                    Recognize CARRIER ... response from some 28.8 modems
                    Support multiple phone numbers
                    Get userid/password from dialer
                    Get timing info from modem
                    Support response file after login
      8 April 1995: Original

A note about distribution.... This script may be distributed freely provided
I am given credit for it. Please do not alter my name or e-mail address
nor the manner in which they are displayed.

There is no charge for the use of this script, but if you decide you
like it and continue to use it, I'd appreciate hearing from you via e-mail...
just a brief note saying which site you got it from and where you are using
it. A sort of "electronic" postcard from your home town. :-)
Please include your city and country as it's kind of hard to tell from some
e-mail addresses.

If you encounter problems, please e-mail me at drussell@direct.ca and I'll
do my best to help you out. Please use a subject line of PPPDIAL, including 
the version number.

NOTE: I've tested this as well as I can with a single provider. Given the
many providers and configurations, this may not work properly for you the
first time.

Specific things to watch for are the EXACT prompts used when the host
system is asking for a userid and password.

To change the script after it's been installed, use the EPM or E editor.
      EPM d:\TCPIP\BIN\PPPDIAL.CMD
   or E d:\TCPIP\BIN\PPPDIAL.CMD

INSTALLATION
If you double-click the pppdial.cmd file it will install itself.

It will move itself to the \tcpip\bin directory and display further
help. After displaying help it will erase the original pppdial.cmd file.
NOTE: Any previous version is replaced, without being prompted, so you
may wish to back up any existing pppdial.cmd file yourself.

After the script has been placed in the correct directory...

       - start the "dial other internet provider"
       - use modify entry (or add entry)
       - in the 'Login sequence:' field enter
               pppdial.cmd <response file>
                  <response file> (if specified) is referred to after a successful
                  modem connection. See below for file format.
       - save the changes
       - installation complete

FEATURES:

MULTIPLE PHONE NUMBERS
The "phone number" specified in the dialer field may be a list separated
by spaces. i.e 555-1212 800-123-4567, or it may be a file name which contains
a list of phone numbers, one on each line.

If you are using a file, include the drive and path name too.

RESPONSE FILE
Format of the "response file":

If a response file is being used it is up to the response file to provide
ALL necessary prompts and responses after the modem has successfully
connected.

The response file now behaves much more like the IBM doc says for their
stuff. The sequences [LOGINID] will be substituted for your login id
as a response, [PASSWORD] will be replaced with your password from the
dialer...
Note: case is respected, so it must be entered in all UPPER case.

CTRL- sequences may be sent from the response file by using the ^ (hat)
character. i.e. ^M will be sent as a carriage return.

Blank lines in the response file are ignored.

A line consisiting only of \r will cause a carriage return to be sent.

In addition I have added a [REPEAT] keyword required by some systems...
See the example response files a bit later on...

The response file is useful for systems that do not immediately prompt for
the userid, instead requiring the user to "press enter".

The first line of the response file is a "synchronization" keyword to
indicate whether we are to wait for a prompt, or do we need to start by
sending. The keyword must be either GO or WAIT

Lines in the file are used in pairs: assuming we wait for a prompt after
logging in, the first line will be WAIT, the second line is what we wait
for, the third line is what we send in response...

If WE must "start" the conversation after logging in, the first line in the
file will be GO and the second line will be sent right away. We will wait
for the system to reply with what we have in line 3 and so on.

List of "keywords" supported in the response file. They must start in
column 1 and be UPPER case: (These ones are new in V2.3)

[PPPDIAL_PHONE] Specify the phone number to be dialed. This may be a
                         blank delimited list or a drive:\path\filename of a file
                         that contains a list of phone numbers, one per line.
                         i.e. [PPPDIAL_PHONE] 482-7000
                              [PPPDIAL_PHONE] c:\myphone.lst
[PPPDIAL_PREFIX] The dial prefix used to dial phone numbers.
                         i.e. [PPPDIAL_PREFIX] ATDT70#W
[PPPDIAL_DO_NOT_USE_DIALER] No value is used here. This keyword indicates
                         that all information will be provided by the response file.
                         If this is not used, then prefix and phone number etc will be
                         obtained from the dialer, replacing values specified in the
                         response file.
[OS/2] any text after this keyword will be passed to OS/2 unmodified.
          One of the more useful commands I presume will be the START command.

Some sample response files...
---cut ---
GO
[REPEAT] \r ogin: 10
[LOGINID]
Password:
[PASSWORD]
--- cut ---

GO tells pppdial that it must initiate the conversation after the modems
connect rather than wait for a response.
[REPEAT] causes pppdial to send a "return" (\r) and wait for a ogin: as a
prompt. If the requested prompt is not received this will be repeated 10
times. Note if the count is missing, pppdial will REPEAT 1000 times.

On successful receipt of "ogin:", [LOGINID] is substituted with your id from
the dialer and sent to the host. We wait for Password: and finally [PASSWORD]
is obtained from the dialer and sent to the host.

--- cut ---
WAIT
ogin:
[LOGINID]
ssword:
[PASSWORD]
--- cut ---

This has almost the same effect as the above example except pppdial waits for
the desired text instead of sending a <return> first. (This is how pppdial
behaves if no response file is used)

The following keywords are recognized within the response file and are not
used to send to the host nor are they expected as "prompts" from the host.

[PPPDIAL_CARRIER_TIMEOUT] allows setting of Modem Register 7 value.
                           (Usually this is determined dynamically, but I've had
                            reports of it causing problems with some modems.)
[PPPDIAL_DELAY]          allows specifying the number of seconds between dial attempts
[PPPDIAL_INIT1]          allows setting 1 or 2 modem init strings (include AT)
[PPPDIAL_INIT2]          allows setting a second modem init string (include AT)
[PPPDIAL_MAX_REDIAL]     allows setting a maximum number of redial attempts
[PPPDIAL_REM]           allows comments to be placed in your response file

[PPPDIAL_PHONE] Specify the phone number to be dialed. This may be a
                         blank delimited list or a drive:\path\filename of a file
                         that contains a list of phone numbers, one per line.
                         i.e. [PPPDIAL_PHONE] 482-7000
                              [PPPDIAL_PHONE] c:\myphone.lst
[PPPDIAL_PREFIX] The dial prefix used to dial phone numbers.
                         i.e. [PPPDIAL_PREFIX] ATDT70#W
[PPPDIAL_DO_NOT_USE_DIALER] No value is used here. This keyword indicates
                         that all information will be provided by the response file.
                         If this is not used, then prefix and phone number etc will be
                         obtained from the dialer, replacing values specified in the
                         response file.
[OS/2] any text after this keyword will be passed to OS/2 unmodified.
          One of the more useful commands I presume will be the START command.

The following keywords cause some action to be taken by pppdial.cmd.
   [LOGINID]         Your login ID as specified in the dialer
   [PASSWORD]        Your password as specified in the dialer. (See notes
                     below regardin the IBM Dialer)
   [REPEAT]          Allows a string to be sent to the host until a specified
                     prompt is received.

Examples....

--- cut ---
GO
[PPPDIAL_REM] Note: GO is still required first... and we use GO instead of WAIT
[PPPDIAL_REM]       because our first action is a [REPEAT] which means WE start.

[PPPDIAL_REM]   I only want to connect at 14400...
[PPPDIAL_INIT1] AT&N8

[PPPDIAL_REM] Only retry dialing 20 times
[PPPDIAL_MAX_REDIAL] 20

[PPPDIAL_REM] the 10 second default is too long... use 5 seconds...
[PPPDIAL_DELAY] 5

[PPPDIAL_REM] My modem S7 value is 35, but my modem won't tell pppdial that properly
[PPPDIAL_CARRIER_TIMEOUT] 35

[PPPDIAL_REM]  OK, parms have been defined... let's get to prompt/reply part...

[PPPDIAL_REM]  My provider wants me to "press enter" until the Login: prompt appears
[PPPDIAL_REM]  (By leaving out the 10 (number of times to try) pppdial.cmd will try
[PPPDIAL_REM]  1000 times)
[REPEAT] \r Login: 10
[LOGINID]
Password:
[PASSWORD]
--- cut ---

A note about the IBM Dial Other Provider program...
If you do not put your password in the entry field in the dialer app, then
you must code the password either in the script itself, or in a response
file. Unfortunately, when the dialer prompts you for it.. it doesn't put it
anywhere readily available by pppdial.cmd :-(

When you specify a .cmd file in the "login sequence field" IBM chose to
disable some of the fields on the "modem info" page and even erase some of
the info from the ini file pppdial reads to get information. So, if you need
a modem init string of something other than ATH0Z then you need to use the 
[PPPDIAL_INIT1] and/or [PPPDIAL_INIT2] commands in the response file.

TIPS & HINTS

If you have a modem init string different from ATH0Z and don't want to use a
"response file" to define [PPPDIAL_INIT1]... you may put it in the "dial prefix"
in the dialer. For example if you want to turn off the speaker...

   ATM0DT is a good "dial prefix" :-)

If you want to be sure that you are always connecting at the highest speed, your
modem may support a command to enforce that. (My USR Courier supports an &N
command that says what speed to connect at - do not negotiate down! (Or UP) )

By putting the &N (or your modem command) in the dial prefix like AT&N8DT then
if the connection WOULD be slow, the modem does not connect and pppdial will
dial again, with the idea that line conditions will be better next time.

Note: This command can not be used to set a MINIMUM connect rate. (at least not
with my modem. If I use &N6 to set the speed to 9600 then even if a 14.4 WOULD
have been OK... the modem says "No, only 9600". Check your modem manual for 
similar commands... there MAY be one that says "minimum connect speed"... and
hey! if not, why not write some e-mail to your modem manufacturer and ask for
such a feature... If enough people ask... :-)

FUTURE ENHANCEMENTS
I'd like to support a "wait for callback" facility for people who log in to a system,
get authorized and then the host phones them back. I have no way to test this myself,
though I think I can implement it OK. If you require this facility, I'd like to hear from you.
I need to see how the "conversation" would go... (e-mail me at drussell@direct.ca)

I also want to be able to support a "minimum connection speed" so a user
could specify a minimum of 9600 (for example) and if the connection were
made at 2400, it would hang up and dial again.

This is 'sort of' implemented but requires changes by the user to
pppdial.cmd, not too elegant :-(
I may end up supporting this via the "response file" so each person can specify
which modem responses to "reject".

Don Russell
*Team OS/2*
Vancouver British Columbia Canada
