home *** CD-ROM | disk | FTP | other *** search
/ OS/2 Shareware BBS: 35 Internet / 35-Internet.zip / slip-cm.zip / README < prev    next >
Text File  |  1994-04-08  |  11KB  |  259 lines
  1. SLIP Connection Manager (CM) for OS/2 TCP/IP V2
  2. -----------------------------------------------
  3.  
  4. Andy Robinson 
  5. netMAINE
  6. andy@maine.maine.edu
  7.  
  8. Features:
  9.  
  10.   * Allows offline composition of mail in a SLIP-only environment (stock
  11.     LAMAIL is not very friendly toward this activity).
  12.  
  13.   * Allows a pseudo-demand-dial capability for TCP/IP applications such 
  14.     as TELNET, FTP, etc.
  15.  
  16.   * Sends/retrieves mail via POP3 (LAMPOP) (Send capability requires
  17.     POP3 server to support XTND XMIT operation!!)
  18.  
  19. Prequisites:
  20.  
  21.   The following software packages must be installed on your computer
  22.   before installing SLIP/CM:
  23.  
  24.   * TCP/IP V2 for OS/2
  25.  
  26.   * LAMPOP (David Bolen's POP3 client for OS/2)
  27.  
  28.   SLIP/CM ASSUMES A SLIP-ONLY ENVIRONMENT!!  If your computer is 
  29.   permanently attached to an IP network, you probably don't need
  30.   SLIP/CM!
  31.  
  32.   SLIP/CM requires a POP3 server that can send mail using XTND XMIT
  33.   (this is a requirement of LAMPOP's SEND option).  If your POP3 
  34.   server does not support XTND XMIT, you'll either have to modify
  35.   the SLIP/CM code or do without SLIP/CM.
  36.  
  37. Package Contents:
  38.  
  39.   README              (this file)
  40.   CMANAGER.CMD        (connection manager main program)
  41.   CMPERFORM.CMD       (CM command interface)
  42.   CMSTART.CMD         (CM 'start connection' primitive)
  43.   CMSTOP.CMD          (CM 'stop connection' primitive)
  44.   CMFORCE.CMD         (CM 'force connection' primitive)
  45.   CMEXIT.CMD          (CM 'terminal CM' primitive)
  46.   CMWRAPPER.CMD       (template for CM application wrapper)
  47.   DEMANDFTP.CMD       (wrapper for FTP)
  48.   DEMANDFTPPM.CMD     (wrapper for FTPPM)
  49.   DEMAND3270.CMD      (wrapper for PMANT)
  50.   DEMANDGOPHER.CMD    (wrapper for IBM EWS Gopher client)
  51.   SETTIME.CMD         (wrapper for NISTP.EXE* (set time by NIST clock))
  52.   CHECKMAIL.CMD       (exchange mail (send and receive) via POP3 server)
  53.   SPMAIL.CMD          (send pending mail using POP3 client/server)
  54.   SENDMAIL.CMD        (front-end for SENDMAIL.EXE to allow offline compose)
  55.   TASKS.CMD           (list of tasks running on system)
  56.   TASK_ACTIVE.CMD     (determine if particular task is active)
  57.   SDATE.CMD           (generate "seconds since epoch" date form)
  58.  
  59.   * NISTP.EXE not included
  60.  
  61. Disclaimer:
  62.  
  63.   This package may be used, copied, and distributed at will, as long as
  64.   this README file accompanies all distributions, and as long as no fee is 
  65.   charged for this package or for any product which uses it (reasonable media
  66.   and/or transmission fees excluded).  Any modified versions of this 
  67.   package should include proper attributions and this README file.  
  68.  
  69.   This package is provided as-is, with no waranties expressed or implied
  70.   as to its suitability for any purpose including the one for which it was
  71.   designed. The author assumes no responsiblity for lost revenues, time, or 
  72.   productivity incurred due to the use of this package.  The user of this 
  73.   package assumes all responsibility for installation, configuration, and 
  74.   debugging.  The author is not under any obligation to support or update 
  75.   this package, though he will attempt to provide support on a time-available
  76.   basis.
  77.  
  78. Installation:
  79.  
  80.   *NOTE* This installation procedure has not been tested.  If you have
  81.   problems, please contact andy@maine.maine.edu immediately!
  82.  
  83.   1. Install TCP/IP V2 and LAMPOP
  84.  
  85.   2. Install this package into a directory in your PATH
  86.  
  87.   3. Add the following lines to CONFIG.SYS:
  88.  
  89.      SET TCPBIN=<\bin directory of TCP/IP hierarchy>
  90.      SET SLIP.POP_SERVER=<host name of POP3 server>
  91.      SET SLIP.POP_DIRECTORY=<incoming mail directory i.e., \etc\mail>
  92.      SET SLIP.POP_INDEX=<incoming mail index i.e., \etc\mail\inbox.ndx>
  93.      SET SLIP.USERNAME=<your SLIP service/POP3 username>
  94.      SET SLIP.PASSWORD=<your SLIP service/POP3 password>
  95.      SET SLIP.DIALSTRING=<dialstring for your SLIP service>
  96.  
  97.      REBOOT THE SYSTEM!
  98.  
  99.      *NOTE* That SLIP/CM assumes the username your SLIP provider uses
  100.      is the same as the username for the POP3 server (same with the
  101.      password).  If this is not the case, you will need to modify the
  102.      programs accordingly.
  103.  
  104.      *NOTE* Having a plaintext version of your password in CONFIG.SYS
  105.      may be a drawback.  A previous version of the program used VREXX
  106.      to issue a windowed prompt for the username and password--you may
  107.      wish to do something similar.
  108.  
  109.      *NOTE* For a better description of the POP_xxx variables, see the
  110.      documentation for LAMPOP.
  111.  
  112.      *NOTE* If your POP3 server does not support sending mail (via the
  113.      XTND XMIT operation), you can't use SLIP/CM.
  114.  
  115.      Examples (real life (almost)):
  116.  
  117.         SET TCPBIN=D:\Software\Package\TCPIP\BIN
  118.         SET SLIP.USERNAME=atr
  119.         SET SLIP.PASSWORD=snicker
  120.         SET SLIP.DIAL_STRING=ATDT1-800-555-1212
  121.         SET SLIP.POP_SERVER=pop3.some.net
  122.         SET SLIP.POP_DIRECTORY=D:\Software\Package\TCPIP\etc\mail
  123.         SET SLIP.POP_INDEX=D:\Software\Package\TCPIP\etc\mail\inbox.ndx
  124.  
  125.   4. Create the MODIFIED directory as a branch of TCPBIN:
  126.  
  127.         MKDIR %TCPBIN%\Modified
  128.  
  129.   5. Move SENDMAIL.EXE into the MODIFIED directory:
  130.  
  131.         COPY %TCPBIN%\sendmail.exe %TCPBIN%\modified
  132.         ERASE %TCPBIN%\sendmail.exe
  133.  
  134.   6. Copy SENDMAIL.CMD from this package into the TCPBIN directory:
  135.  
  136.         COPY <source>\SENDMAIL.CMD %TCPBIN%
  137.  
  138.   7. Modify (including renaming) the ANSREMOTE.CMD from this package
  139.      as necessary.  Unless you use ANSRemote, you will have to make
  140.      some changes to this file.  This may involve using SLIPTERM to
  141.      manually go through the SLIP login sequence first, then modifying
  142.      ANSREMOTE.CMD to do it automagically.
  143.  
  144.   8. Use TCP/IP Configuration or directly modify %etc%\SLIP.CFG to list
  145.      ANSREMOTE.CMD (or whatever you've renamed it to) as the SLIP startup
  146.      script.
  147.  
  148.   9. You are now basically ready to go.  If you want to customize any of
  149.      the wrappers, or design new wrappers for specific applications, go
  150.      for it.
  151.  
  152.  10. Start CMANAGER.CMD.  I put a program object pointing to CMANAGER in the
  153.      STARTUP folder so CMANAGER is always running.  
  154.  
  155.      *NOTE* You can set up program objects to call CMSTART and CMSTOP to
  156.      provide an manual SLIP setup/takedown capability.  
  157.  
  158.      *NOTE* Doubleclicking on the wrapper icons such as CHECKMAIL, 
  159.      DEMAND3270, etc., will start the respective sessions.  SLIP/CM is
  160.      smart enough to keep the connection going as long as there are any
  161.      active sockets, and will not re-start SLIP.EXE if it is already
  162.      running.
  163.  
  164. NOTES ABOUT MAIL SUPPORT
  165. ------------------------
  166.  
  167. SLIP/CM resorts to some kludges to implement offline composition of
  168. mail.
  169.  
  170. First, SLIP/CM replaces SENDMAIL.EXE with SENDMAIL.CMD.  SENDMAIL.CMD
  171. becomes the MTA for LAMAIL (SENDMAIL.EXE is saved in another directory).
  172.  
  173. When you send (F5) a message from LAMAIL, SENDMAIL.CMD gets control.
  174. SENDMAIL.CMD checks to see if SLIP.EXE is running.  If SLIP.EXE is running, 
  175. SENDMAIL.CMD calls LAMPOP (*not* SENDMAIL.EXE) to send the message 
  176. immediately.
  177.  
  178. If SLIP.EXE is *not* running, SENDMAIL.CMD writes a record to a file called 
  179. PENDING_MAIL in the %tmp% directory, and writes body of the mailfile to a
  180. unique filename in the %tmp% directory.  
  181.  
  182. If SENDMAIL.CMD is called with the -bd options (start daemon), SENDMAIL.EXE
  183. *is* invoked in daemon mode.
  184.  
  185. When you run CHECKMAIL.CMD, CMANAGER starts the SLIP connection.  Once the
  186. connection is established, CHECKMAIL calls LAMPOP to receive any mail pending
  187. on the POP3 server (CHECKMAIL uses the SLIP.xxxxx environment variables
  188. described in step 3 to pass information to LAMPOP).  
  189.  
  190. Once all the pending mail is received, CHECKMAIL calls SPMAIL.CMD.  
  191. SPMAIL.CMD scans the PENDING_MAIL file and uses LAMPOP to send any messages
  192. that were composed offline.  Once these messages have been successfully
  193. passed to the POP3 server, their %tmp% incarnations are erased and the
  194. PENDING_MAIL file updated accordingly.  If there are errors during 
  195. transmission, any and all unsent messages will be retained and will be
  196. retried the next time you run CHECKMAIL.
  197.  
  198. As you can see, the mail support is a kludge--and if you have any ideas as
  199. to how to improve the implementation, please let me know!!
  200.  
  201. NOTES ABOUT CMANAGER
  202. --------------------
  203.  
  204. The CMANAGER.CMD program manages the SLIP connection.  It receives requests
  205. to START or STOP via a REXX IPC queue called CMCOMMANDQUEUE.  The interface
  206. to this queue is CMPERFORM.CMD.  Using CMPERFORM, you can send arbitrary
  207. requests to CMANAGER.CMD.  CMANAGER only responds to the following requests:
  208.  
  209. 1. START -- start a SLIP connection
  210. 2. STOP -- stop a SLIP connection (quiesce)
  211. 3. EXIT -- terminate CMANAGER
  212. 4. FORCE -- force the SLIP connection immediately
  213.  
  214. Each of these requests has an associated primitive, CMSTART(), CMSTOP(),
  215. CMEXIT(), and CMFORCE().  The primitives provide the most convenient way
  216. to include CMANAGER functionality in REXX programs.  CMSTART() primitive
  217. can optionally block (using SLIPWAIT) until the SLIP connection becomes
  218. active.
  219.  
  220. Note that CPERFORM.CMD blocks until it receives an acceptance message on
  221. a separate (unique) IPC queue from CMANAGER.  If you use CPERFORM to
  222. send an unknown request, your program will block until you terminate it
  223. (i.e., with CTRL-C).  In any event, the response from CMANAGER does not
  224. indicate successful completion of the request--it only indicates that
  225. CMANAGER has seen your request and agreed that it is a legitimate request.
  226.  
  227. As far as SLIP/CM is concerned, TCP/IP applications are either wrapped 
  228. or unwrapped.  A wrapped application has a SLIP/CM front-end--for example, 
  229. DEMANDFTP, DEMAND3270, and CHECKMAIL. These applications can simulate a 
  230. demand-dial capability by calling the CMSTART/CMSTOP primitives.
  231.  
  232. Unwrapped applications are the raw programs supplied with TCP/IP, such as
  233. PING, PMANT, TELNET, FTP, etc.  These applications will not work unless
  234. the SLIP connection is active.  
  235.  
  236. The first time CMANAGER receives a START request, it will start the
  237. SLIP.EXE driver.  After that, it increments a counter of pending
  238. connections.  CMANAGER will not terminate the SLIP connection until:
  239.  
  240. 1. A FORCE request is received
  241. 2. The number of pending connections = 0 *and*
  242.    The number of active STREAM/DGRAM sockets = 0
  243.  
  244. Condition 2 is important:  it reduces repetitive invokations of SLIP.EXE,
  245. and it allows you to run "unwrapped" TCP/IP programs after SLIP is started
  246. For example, if you run DEMAND3270 to start a 3270 session to a remote host,
  247. then run PMPING (unwrapped), then terminate your 3270 session, the SLIP
  248. session will not be terminated until you terminate PMPING as well.
  249.  
  250. ALL SLIP/CM WRAPPERS SHOULD CALL BOTH CMSTART() AND CMSTOP()!  If
  251. a STOP request is somehow lost, the SLIP connection may not be terminated
  252. when it is supposed to be--which could lead to large connect-time bills.
  253. Make sure that any wrappers you write call CMSTOP() for every call to
  254. CMSTART()--and make sure that the wrappers have exits to ensure that 
  255. the CMSTOP() will be performed even if the wrapper is terminated abnormally
  256. by CTRL-C or a kill signal.
  257.  
  258.  
  259.