              General Recipe for OS/2 TCP/IP (and IAK) PPP
                    Last updated 96/10/30

NOTE:  If you are going to use Compuserve as your internet
       service provider, download file CISPPP.TXT from OS2USER
       library 9.

This file is authored by Tony Rall of TEAMIBM (trall@almaden.ibm.com)
with some assistance from Howie Acheson (102562.102@compuserve.com) with
a special thanks to Ron Higgin, OS/2 Advisor, for his comments and
advice.


PURPOSE - To configure the "Dial Other Internet Provider" dialer for
          accessing an Internet Service Provider (ISP).


To establish an internet connection you must have one of the following
installed on your system:

   o OS/2 Warp V4 with the TCP/IP v4.0 feature installed. If you do 
      not have the TCP/IP feature installed you may do so using the
     "Selective Install for Networking" utility in the
     "Install/Remove" sub-folder of the "System Setup" folder. If
     you do this and do NOT have a LAN connection then use the
     "Easy" TCP/IP install procedure (NOTE: You CAN NOT install 
     TCP/IP v4.0 over the IBM Internet Connection for OS/2 from the 
     WARP 3.0 Bonus Pack. All remnants of the IIC must be removed 
     first.) or,

   o OS/2 WARP Connect V3 with the TCP/IP v3.0 feature installed.
      DO NOT install the IBM Internet Connection for OS/2 feature of 
      the WARP Connect Bonus Pack when the TCP/IP feature is 
      installed.  Installing the IIC over the WARP Connect TCP/IP 
      feature will render TCP/IP inoperative.  TCP/IP v3.0 uses the
      same dialer as IIC.  Therefore, you should download and install
      PPP.ZIP to ensure you are using the latest dialer (see above) 
      or,

   o OS/2 WARP V3 with the Bonus Pack's IBM Internet Connection for 
      OS/2(IIC) with the latest PPP update applied.  The PPP update 
      may be downloaded from library 9 ("Internet and OS/2") of
      the OS2USER forum as file name "PPP.ZIP", or FTP'd from 
      "ftp.ibm.net",  directory "/pub/PPP", as file name "PPP.ZIP". 
      In addition, download and install the TCP/IP Base Update 
      (PN71501) from Retrieve Software Updates.

     To install the PPP update:

        - place the "PPP.ZIP" file in your "\TCPIP" directory
        - Open an OS/2 command prompt session
        - Make the "\TCPIP" directory "current"
        - UNZIP (using InfoZip's unzipper) the "PPP.ZIP" file

     If you do not have the InfoZip unzipper, PKZIP (V2.04) or
     later may be used BUT you MUST run it from a DOS command
     prompt session and you MUST specify the PKUNZIP "-d" option.

=====================================================================
NOTE: CSD PN71501 (TCPIP Base Update) is NOT required for users of 
"OS/2 Warp Connect V3" or "OS/2 Warp V4".
=====================================================================

     IF you have the "Warp for Windows Users" (RED spine box)
     product you MUST also install OS/2 Fix Pack 5 or later.


Once you have the PPP update installed, you need to open the Dial
Other Internet Providers object. Warp V3 users will find this object
in the "Internet Utilities" subfolder of the "IBM Internet Connection
for OS/2" folder.  Warp V4 users will find the object in the
"Internet (Modem)" subfolder of the "Programs" folder.

Once you've fired up the "Dial Other Internet Providers" utility,
choose the Add Entry object, or select Add Entry from the Configure
pull-down menu, then configure dialer as follows:

* Your primary source of assistance for signing on to an Internet
  Service Provider(ISP) should be the ISP.  The ISP will have to
  provide you with some of the information to configure the dialer.

* If your provider has given specific instructions for connecting
  using OS/2 TCP/IP or the Warp IIC, follow them (to the
  letter).

====================================================================
GENERAL CAVEAT

The Internet is CASE SENSITIVE.  Any place in this document where
a case is shown for information to be entered into the dialer, be
sure to follow the case EXACTLY.  Be sure to understand and follow
the case for any information provided by your ISP.
====================================================================

 * Use the "Dial Other Internet Providers" application.

 * Click on "Add Entry"

 * Page 1: (Login Info)

     - In the Name:  field, type a "name" for this connection.
       BE SURE TO USE ALL UPPER CASE.  This name serves only to
       identify the target provider dialer entry.  The dialer
       itself does NOT reference this "Name", and hence, it may
       contain any name YOU find meaningful.

     - In the Description:  field, enter a description for this
       connection.  This is for descriptive purposes only.  The dialer
       does NOT use the contents of this field.

     - For the Login ID: field enter your User ID number.

     - Fill in your password.  If you leave Password blank, check
       "Required" and you will be prompted for your pw each time you
       dial.  IMPORTANT-If your password contains one or more blank
       characters (spaces), substitute the the TWO character string "\s"
       for EACH blank character.

     - For the Login Sequence use "NONE".  PAP authorization will be
       attempted by ppp.  If this does not work with your provider, try
       a completely blank Login Sequence.  If this doesn't work, look
       at the help information (put cursor in the area and hit F1).

    * General comments about the Login Sequence:

      o Several characters are invalid in a LS without being preceded
        by the escape character "\", plus other special characters
        (these same comments apply to the Login ID, password, and
        modem initialization strings):

          space - replace by "\s"
          carriage return - replace by "\r"
          back slash "\" - replace by "\\"
          double quote " - cannot be used at all (near as I can tell)
          2 second delay - use "\d"

      o The first string is sent FROM you to your provider - it is
        usually just a carriage return, "\r".

      o Alternate lines are those that the dialer is to wait for from
        your provider.  The dialer (actually slattach.exe) will ignore
        everything it receives until it get an exact match with the
        string you've entered - and the comparison is case-sensitive.
        If slattach doesn't get what it expects in (by default) one
        minute, it will abort the connection.

      o If it does get a match, it will send the next line in the
        Login Sequence.

      o The on-line help for the Login Sequence is reasonably good.  To
        see it, place your cursor in the LS and hit F1.  It omits a
        couple of details; you can get those using, at an OS/2 command
        prompt, "slattach -?".

    * If a Login Sequence, by itself, is insufficient for your needs,
      you must go to a Rexx script (a .cmd file).  One of the most
      frequent motives for this is when you have a provider that
      doesn't have enough phone lines to accommodate his customers
      (I would have to be pretty desperate to use a provider like
      that) - in this case, you may want an automatic redial script.
      The Login Sequence doesn't supply this capability.  (Note:
      using a response file (.rsp) provides no functional advantage
      over using a regular Login Sequence; the only impetus I can
      see for a response file is if slippm.exe has some undesirable
      side effects in your environment.)  WHEN SPECIFYING A "cmd"
      OR "rsp" FILE IN THE LOGIN SEQUENCE, IT MUST BE DONE IN LOWER
      CASE.

      Unfortunately, IBM does not include any sample scripts for
      ppp,but here are some samples in OS2USER library 9. If you
      feel that you need a Rexx scrip, I recommend trying to get
      a hold of pppdial.cmd, distributed at popular OS/2
      ftp sites as ppdialxx.zip.

      If you want to make your own, issue "ppp -?" for help on the
      parameters required by the ppp driver.  Annex.cmd (or
      slipup.cmd) would need to be changed in the following ways:

      The arguments are passed differently to ppp scripts than they
      were for slip.  They come in as individual parameters which,
      in Rexx, must be separated by commas in your script.  (The
      third parameter is CMD - I don't know of a use for it, so I
      discard it.)  The "parse arg" statement near the beginning of
      your script must look like this:

       parse  arg interface , port , . , dialcmd , username , password
       typical values: ppp0   com1       ATDTnnn   userid     password

      Change all occurrences of the function calls "slip_..." to
      "ppp_...".

      Assuming your provider supports PPP IP address configuration
      (this is dynamic and under the covers), you can remove the
      parsing of addresses, configuring the interface, and setting the
      default route - this will be taken care of automatically.

  - Connection Type: PPP


* Page 2: (Connect Info)

  - Leave blank Your IP Address, Destination IP Address, Netmask.

  - Don't change the MRU (ppp seems to ignore this anyway).

  - Domain Nameserver - add the numeric IP address of your provider's
    primary nameserver, e.g., 1.2.3.4

  - Your Host Name - enter a name for your PC (mine is "trall").  Put
    the same name in your CONFIG.SYS following other SET statements near
    the top of your CONFIG.SYS (first 20 lines or so).

        SET HOSTNAME=TRALL

    You must reboot for this to take effect.

  - Your Domain Name - usually the name of your provider, e.g.,
    netcom.com


* Page 3: (Server Info)

  - All of this information is optional.  Entering it correctly will
    make it easier to use the related applications.  Your provider
    should supply anything you use here.


* Page 4: (Modem Info)

  - Modem Type - I don't mess with this, but if you don't understand
    the commands for your modem and you can find it in the list, go
    ahead and select it. (See below)

  - Com Port - Get this right.  Note that if you use anything above
    com2 you need to define it in CONFIG.SYS with a COM.SYS statement.

  - Speed (Baud) - This misnamed field is referring to what is
    actually called the DTE speed - the data transfer rate between
    the com port and the modem.  In general, the higher, the better.
    But the standard com support (COM.SYS) currently supports no
    higher than 57600.  If you seem to be having problems communicating
    with the modem, drop this to 9600 to ensure that this is not the
    cause.

  - Data Bits - Leave at 8.

  - Parity - Leave at NONE.

  - Prefix - Leave at ATDT (unless you don't have tone dialing; then
    use ATDP).

  - Mode - Leave at Dial

  - Initialization Strings - If your modem type was not in the list
    at the top of the page, see below.


Modem Init Strings

There is also a file titled MODEMIAK.ZIP in OS2USER library 9 that
contains an updated and expanded list of modems and init strings that
can be used with the dialer.

Another option is to use the initiation strings suggested for use in
the IBM Dialer.  You can view these by using your editor and loading
the file MODEM.LST that resides in x:\TCPIP\ETC.

=====================================================================
NOTE: If you are using OS/2 Warp Connect V3 or OS/2 Warp V4 the
      "MODEM.LST" (and other files normally found in the
      "x:\TCPIP\ETC" directory) will be located (by default) in the
      "x:\MPTN\ETC" directory.
=====================================================================

The reason there are 2 init.  strings is that some modems require a
delay between a reset and any other commands.  Typically the first
command is to reset to factory defaults; then the other string is used
to make any changes needed from those defaults.  In practice, most
modems work fine with just one string (which can be quite long), and
this avoids the 2 second delay that is inserted between the 2 strings.

If you cannot find a string(s) that work, I recommend you try this (in
Init. string 1; leave Init. string 2 blank):

   AT&FM1E1S0=0&C1&D2

Not all of these commands are available on every modem; if you
get ERROR when you dial (as a response from the modem), start removing
stuff until you don't.

 &F    reset to factory defaults (check your modem manual to see if
       there is a different command for this; if there are several,
       use the one for asynchronous communication with RTS/CTS
       (hardware) flow control)

 M1    speaker on (usually a default)

 E1    echo on (so you can see the commands being sent to the modem,
       including the dial string)

 S0=0  no auto-answer

 &C1   signal true carrier-detect

 &D2   hang-up when DTR drops (this is how slip/ppp makes the modem
       break the connection)


ESTABLISHING THE INTERNET CONNECTION

Then to establish your PPP connection, select the NAME of the
connection and choose DIAL.  You will then see the initialization of
the modem, the dialing, the logging in, and you should see messages in
the Status Window reporting the remote IP address, VJ compression
enabled, and that the default route address has been assigned.  Do
not be concerned if you see a couple of "fcs" error notices.

  The final line will be

       "[PPP] Enter Ctrl-C or Ctrl-Break to End Session"

When you see the above messages, then the connection is complete and
you can envoke any of the internet applications. You must leave the
dialer running while you have the PPP connection active. You may want
to minimize the dialer after the connection is established.

The first thing you should do after connecting to the internet is to use
the "Retrieve Software Updates" and download "Base Update for TCP/IP
(PN71501).  This will allow the full functions of the IBM WebExporer.
No other CSD's or TCP/IP updates are required.


  PROBLEM SOLVING
The number one reason for an unsuccessful connection is having illegal
characters (usually spaces) in the script, modem strings, password
and/or user ID.  Be sure and check by placing your cursor at the
beginning of a space, pressing and LMB while dragging the cursor to
the end of the space or to the end of the line of the script.  There
should be not empty spaces in any of the "fill in" spaces and only one
space at the end of each line in the script.

IMPORTANT
If you are using WARP v4 be sure you have not installed TCP/IP v4.0 
over the WARP 3.0 Bonus Pak IBM Internet Connection for OS/2.  You 
must remove the IIC by deleting all TCPIP references in your 
CONFIG.SYS, rebooting and deleting all the TCPIP directories, 
subdirectories and files.

* After clicking on the Dial icon, it switches to Hang-up and then
  immediately switches back to Dial - quitting immediately.

  - Make sure there are no spaces in your userid or password; you
    can substitute "\s" for any spaces.

  - Your com port is not defined to OS/2.  On ISA bus machines,
    COM1 and COM2 are the only ones defined by default.  If you use
    COM3 or 4, you need to add a COM.SYS statement to config.sys (and
    reboot).

    - Make sure the Netmask (on page 2 of the dialer settings) is not
    255.255.255.255 - I consider it best to leave this field totally
    blank.

  - Your com port is still held by some other program (another com
    or fax program).  You must exit that program before dialing.

  - Anyone using the original red spine Warp (for Windows) and
    communications apps should have at least fix pack 5 installed.

* The dialer does not appear to talk to the modem and, after one
  minute, terminates with a failure.  On some hardware combinations
  there appears to be a flow control problem on the com port.
  Issuing the following command before dialing may help:
  MODE.COM COMn:1200

  On other modems, forcing the modem to reset after the previous
  connection helps.  Change &D2 in your modem init. string to &D3
  (not all modems support this command).

  Other users have solved this problem by replacing com.sys with
  the shareware (by Ray Gwinn) SIO.SYS, generally available at your
  favorite download sites.

*  Message in dialer window and in ppp0.log "..could not determine
    hostname". Make sure you have this statement in config.sys:
        SET HOSTNAME=nameofmypc

  Lacking this, ppp.exe may hang for one minute before redial
  attempts.

* [io_event] Unsupported protocol (xxxx) received.
  The remote server is trying to setup additional communications
  protocols (such as IPX) that ppp.exe does not support.  This is just
  an informational message.  Ppp.exe will reject that protocol; this
  will not cause a problem unless the server insists on that protocol
  being supported.

* [io_event] Unsupported protocol (2080) received.
  This is a special case of the previous item.  The 2080 is definitely
  not a ppp protocol - it happens to be a couple of ASCII characters
  typically used to format text (non-ppp) messages.  In other words,
  the server is not yet in ppp mode (but OS/2 is).

  This usually means that either:

  - you didn't get correctly logged in (from the server's viewpoint),
    and it is sending you error messages, but ppp.exe is expecting
    formatted ppp messages at this point

  - you did get logged in, but the server is sending a few more
    text messages, such as:

     Ok, you're on
     Let me get my ppp code fired up
     Hold on a sec
     Ok, it's up
     Have a good day

  If you want to eliminate this error, you have to find out what the
  messages are.  In the first case (bad login), correcting the login
  should suffice.  In the second, you'll need a fancier Login Sequence
  (not a blank or NONE LS).  One way to determine what is being sent
  is to put an intentional error in your LS: after the last line to be
  sent to the server add a line with "xxxyyy".  This won't match, so
  the Status window will display all messages received.  If it wasn't
  indicating a login error, replace the xxxyyy with the last part of
  the last such message.  In the example above, the last line in your
  Login Sequence should contain:

     good\sday

* Invalid FCS - Bad phone line or modem, or, more likely, ppp.exe has
  entered ppp mode while the remote system is still sending text
  messages.  The latter can often be corrected by improvising a better
  Login Sequence.  But don't do anything at all if you just get a few
  of these messages at the start of the connection.  If they continue
  throughout your session, you should try to correct the problem -
  usually a phone or modem problem.

  - getting a better serial card (with a buffered uart)

  - running the com port at a lower speed ("baud" on page 4)

  - replacing the serial cable

  - getting a better phone connection

  - using a better initialization string for the modem

  - suppressing modem compression (such as V.42bis)

  - replacing the modem

  - replacing com.sys with the shareware sio.sys (or vice versa). SIO
    is available from CIS in OS2BVEN library 4 as SIOxxx.ZIP or from
    most OS2 BBB's.

* After the message "Enter Ctrl-C or Ctrl-Break to End Session", you get:

   notice : DCD lost, exiting
   info : Exit called
   info: Terminating link

  - This could be caused by an attempt by your system to send mail to
     a mail gateway if you do not have a correctly configured mail setup.
     Messages may end up queued in etc\mqueue\.  When you make your
     connection an attempt is made to send these messages immediately.  If
     you still have a bad mail configuration, you can get the error
     described above, and ppp (erroneously) hangs up.  Erase the files in
     the etc\mqueue directory and try redialing.

  - The problem may be in your modem cable.  Older modem cables frequently
     did not have all pins (25) and/or wires.  If you have an older cable, try
     a new one.

* You tell the system to hangup, but the modem stays off-hook (it does
  not hangup).  This can run up your phone bill (if a toll call) and
  can foul up your next connection attempt.  There are 2 ways that
  software can tell the modem to hangup:

  The "+++ ATH0" escape sequence and command will make most modems
  hangup, but I know of no way to make the dialer issue this.

  The method used by the dialer is to drop DTR.  Unfortunately this
  requires that the modem pay attention to the DTR signal, and modems
  can be configured to ignore it.  On many modems the default setting
  is to obey DTR (and hangup when it drops); on other modems &D2 should
  be included in the init. string.

  Some modems may not recognize the change in the DTR signal.  This
  can be controlled by the setting of S25, on at least most modems.
  If &D2 by itself is insufficient to provoke hangup, add S25=5 to
  your modem initialization string.


