home *** CD-ROM | disk | FTP | other *** search
/ 1st Canadian Shareware Disc / 1st_Canadian_Shareware_Disc_1991.ISO / comms / slrn_100 / slearn.doc < prev    next >
Text File  |  1990-01-16  |  23KB  |  725 lines
  1.  
  2.  
  3.  
  4.  
  5.  
  6.  
  7.  
  8.                       | SLEARN (SALT learn utility) v1.00 |
  9.                       |                                   |
  10.                       | A SALT script creator for Telix   |
  11.                       |                                   |
  12.                       | Copyright (c) 1990 by Paul Roub   |
  13.                       | All Rights Reserved               |
  14.                       |                                   |
  15.                       | January 17, 1990                  |
  16.  
  17.  
  18.  
  19.  
  20.  
  21.  
  22.      SLEARN v1.00                                               Introduction
  23.  
  24.      Hopefully, this documentation will tell you all you need to know about
  25.      using SLEARN.  But if necessary, please direct further questions to me
  26.      through the following means:
  27.  
  28.           Compuserve EasyPlex E-Mail to 71131,157
  29.           Messages to Paul Roub in the FidoNet TELIX echo
  30.           Fido NetMail to Paul Roub at 1:135/47
  31.           Local BBS messages to Paul Roub on:
  32.                MOBS (305-895-1666)
  33.           US Mail to:
  34.  
  35.                Paul Roub
  36.                P.O. Box 141583
  37.                Coral Gables, FL 33114-1583
  38.  
  39.      When reporting a bug, please be specific as to the nature of the prob-
  40.      lem (i.e. what led up to it, what error message -- if any -- ensued,
  41.      can you repeat it, etc.).
  42.  
  43.  
  44.      The author makes no claims as to the suitability of this product for
  45.      any application.  In the event of malfunction, the author's liability
  46.      shall be limited to a replacement or refund.
  47.  
  48.  
  49.      ACKNOWLEDGEMENTS:  I wish to express my gratitude to Andrew Adler,
  50.      Lloyd Burt, Craig Merwitzer and Bruce Wilson for testing and assistance
  51.      above and beyond the call of duty.  Thanks also to Nick Anis and John
  52.      Dvorak.  And as always, particularly special thanks to Maria for exist-
  53.      ing.
  54.  
  55.  
  56.      Notes:
  57.      -----------------
  58.      You may distribute SLEARN freely (in fact, I would appreciate your
  59.      doing so), provided that you distribute only the full, unmodified ar-
  60.      chive (SLRN_100.ARC), with its full name intact, containing the follow-
  61.      ing files:  
  62.  
  63.           SLEARN.DOC
  64.           SLRNHIST.DOC
  65.           SLEARN.REG
  66.           SLEARN.EXE
  67.           SLEARN.SLT
  68.           SLEARN.SLC
  69.           SET_SCR.EXE
  70.           READTHIS.NOW  (Can be deleted after January 31, 1990)
  71.  
  72.      If you downloaded SLEARN from Compuserve, please rename SL100.ARC to
  73.      SLRN_100.ARC before distribution.  Feel free to distribute SLEARN in
  74.  
  75.      SLEARN Documentation                                             page 1
  76.  
  77.  
  78.  
  79.  
  80.  
  81.      SLEARN v1.00                                               Introduction
  82.  
  83.      other archive formats (such as ZIP, LHARC, ZOO, etc.) -- but again, you
  84.      must retain the full name, as in SLRN_100.LZH or SLRN_100.ZIP.
  85.  
  86.      If you're not sure whether you have the latest version of SLEARN, the
  87.      following systems are always kept up to date:
  88.  
  89.           MOBS (1:135/47)               305-895-1666
  90.           Floridays Deluxe              305-235-2227
  91.           The C Workshop (1:135/1)      305-226-3310
  92.           Telix Support BBS             416-439-8293
  93.           Compuserve IBMCOM Forum
  94.  
  95.      If, after trying out SLEARN, you wish to continue using it, you must
  96.      fill out and send in the registration form at the end of this document. 
  97.      You'll be supporting shareware, making possible future improved ver-
  98.      sions of this and other programs; you can also get the latest version
  99.      of SLEARN on disk.  Note that SLEARN may NOT be used in a business or
  100.      commercial environment without registration.  For further details, see
  101.      the Registration section at the end of this document.
  102.  
  103.      Is there something you don't like about SLEARN?  Something you think is
  104.      missing?  A screw-up in the documentation, etc...  let me know!  We aim
  105.      to please!
  106.  
  107.  
  108.  
  109.  
  110.  
  111.  
  112.  
  113.  
  114.  
  115.  
  116.  
  117.  
  118.  
  119.  
  120.  
  121.  
  122.  
  123.  
  124.  
  125.  
  126.  
  127.  
  128.  
  129.  
  130.  
  131.  
  132.  
  133.  
  134.      SLEARN Documentation                                             page 2
  135.  
  136.  
  137.  
  138.  
  139.  
  140.      SLEARN v1.00                                            Why use SLEARN?
  141.  
  142.      What's the problem?
  143.      -------------------
  144.      I've said it before -- Telix is the best communications program you'll
  145.      find.  However, not even Telix is perfect.  Two common complaints go
  146.      hand in hand: that Telix's script language (SALT) can be hard to learn
  147.      for non-programmers, and that Telix lacks a "learn" mode which can
  148.      automatically create SALT scripts for you.
  149.  
  150.      For example: assume you wanted to log on to QuickBBS system, such as
  151.      the Telix Support BBS.  You would call up, wait until you saw the
  152.      prompt
  153.  
  154.           Enter Your Name:
  155.  
  156.      then type your name followed by a carriage return.  The system would
  157.      then prompt you for your
  158.  
  159.           Password:
  160.  
  161.      which you would also type, followed by another carriage return.  
  162.  
  163.      Of course, you don't want to have to go through this every time you log
  164.      onto that board -- the process will never change, and will get quite
  165.      boring (just the type of thing you would expect your computer to spare
  166.      you from).  If you know Telix's SALT language, you could write a SALT
  167.      script to log on for you, such as:
  168.  
  169.           main()
  170.           {
  171.             waitfor("Your Name:", 30);    // wait for name prompt
  172.             cputs("Paul Roub^M");         // if you're me, this works!
  173.  
  174.             waitfor("Password:", 30);     // wait for password prompt
  175.             cputs(_entry_pass);           // send the password stored in
  176.                                           //   this entry in the dialing
  177.                                           //   directory
  178.           }
  179.  
  180.      You would then compile this script, insert it in your dialing directory
  181.      as the "linked script" for this system, and off you'd go.  From now on,
  182.      whenever you call this system, Telix will automatically run this script
  183.      to log on for you.
  184.  
  185.      While this is nice, there are two drawbacks:  It gets tedious when you
  186.      want to script more than a few prompts and responses, and some people
  187.      find SALT difficult to get the hang of.  It would be nice if Telix had
  188.      a "learn" mode.  A learn mode is a nice feature, found in some commu-
  189.      nications programs, which "watches" you as you perform some task.  It
  190.      notes what text is sent by the system you're connected to, and what
  191.      your responses are.  Using this information, it writes a script which
  192.  
  193.      SLEARN Documentation                                             page 3
  194.  
  195.  
  196.  
  197.  
  198.  
  199.      SLEARN v1.00                                            Why use SLEARN?
  200.  
  201.      will wait for the same prompts and send the same responses.  You would
  202.      invoke this learn mode, log onto the BBS, and the program would write
  203.      the script FOR you!
  204.  
  205.  
  206.      What's the solution?
  207.      --------------------
  208.      Now, Telix DOES have a learn mode.  It's called SLEARN, the SALT learn
  209.      utility.  SLEARN will write your SALT scripts for you -- it can even
  210.      compile the scripts and include them in your dialing directory, all
  211.      automatically!
  212.  
  213.  
  214.  
  215.  
  216.  
  217.  
  218.  
  219.  
  220.  
  221.  
  222.  
  223.  
  224.  
  225.  
  226.  
  227.  
  228.  
  229.  
  230.  
  231.  
  232.  
  233.  
  234.  
  235.  
  236.  
  237.  
  238.  
  239.  
  240.  
  241.  
  242.  
  243.  
  244.  
  245.  
  246.  
  247.  
  248.  
  249.  
  250.  
  251.  
  252.      SLEARN Documentation                                             page 4
  253.  
  254.  
  255.  
  256.  
  257.  
  258.      SLEARN v1.00                                     Setup and Installation
  259.  
  260.      Setup and Installation
  261.      ----------------------
  262.      This manual assumes a basic understanding of .SLT (SALT script) versus
  263.      .SLC (compiled SALT) files, as well as an understanding of terms such
  264.      as "Logon Script" and "Dialing Directory".  If these terms are unfamil-
  265.      iar to you, consult your Telix manual.  If you have any problems using
  266.      SLEARN, and can't solve them with your DOS, SLEARN or Telix manuals,
  267.      feel free to contact me through the means listed at the end of this
  268.      document.
  269.  
  270.      There are four important files involved in using SLEARN.  These are:
  271.  
  272.           slearn.slt  - SALT script to run SLEARN from Telix
  273.           slearn.slc  - Compiled version of slearn.slt
  274.           slearn.exe  - The main SLEARN program
  275.           set_scr.exe - used by slearn.slt
  276.  
  277.      SLEARN.SLT and SLEARN.SLC should be kept in the directory you have
  278.      defined as your Telix script directory.  If you haven't defined a
  279.      script directory, this will simply be your main Telix directory. 
  280.      SLEARN.EXE and SET_SCR.EXE should both be in a directory listed in your
  281.      DOS PATH environment variable (consult your DOS manual form more infor-
  282.      mation about environment variables and the PATH).  If you do not have a
  283.      PATH statement, SLEARN.EXE should be in the same directory as
  284.      SLEARN.SLT and SLEARN.SLC; SET_SCR.EXE should be in your main Telix
  285.      directory.
  286.  
  287.           NOTE: If you are using Telix SE, you will not find SLEARN
  288.           very useful, as Telix SE does not come with the program
  289.           CS.EXE, needed to compile the SALT scripts created by SLEARN. 
  290.           In this case, you will need to register your copy of Telix
  291.           (see the Telix coupon in the Dvorak book for details), or
  292.           find a BBS which has the Telix archives available (and use
  293.           Telix SE to download them) to get the full version of Telix.
  294.  
  295.      There are a few changes you may want to make to SLEARN.SLT, to config-
  296.      ure it to your personal needs.  By default, SLEARN.SLT runs
  297.      SET_SCR.EXE, which will modify your dialing directory, TELIX.FON.  If,
  298.      however, you will be using more than one dialing directory, you won't
  299.      want to do this -- SLEARN always modifies TELIX.FON, whether or not it
  300.      is the current dialing directory.  If you want to change this behavior,
  301.      change this line (in SLEARN.SLT)
  302.  
  303.           int       UseSetScr = 1;
  304.      to
  305.           int       UseSetScr = 0;
  306.  
  307.      Another change you may want to make is to change
  308.        
  309.           int       anonymous = 0;
  310.  
  311.      SLEARN Documentation                                             page 5
  312.  
  313.  
  314.  
  315.  
  316.  
  317.      SLEARN v1.00                                     Setup and Installation
  318.  
  319.      to
  320.           int       anonymous = 1;
  321.  
  322.      By default, scripts generated by SLEARN display the name of the system
  323.      to which you are connected.  The above change disables this.  Finally,
  324.      you can change
  325.  
  326.           int       UseEntryPass = 1;
  327.      to
  328.           int       UseEntryPass = 0;
  329.  
  330.      If you make this change, SLEARN will not recognize the password of the
  331.      system you are creating a script for.  More on this later.
  332.  
  333.      If you have made any of these changes, you will need to re-compile
  334.      SLEARN.SLT for them to be effective.  To do this, enter the command:
  335.  
  336.           CS slearn
  337.  
  338.      at the DOS prompt.  This will create a new version of SLEARN.SLC, the
  339.      compiled version of SLEARN.SLT.
  340.  
  341.  
  342.  
  343.  
  344.  
  345.  
  346.  
  347.  
  348.  
  349.  
  350.  
  351.  
  352.  
  353.  
  354.  
  355.  
  356.  
  357.  
  358.  
  359.  
  360.  
  361.  
  362.  
  363.  
  364.  
  365.  
  366.  
  367.  
  368.  
  369.  
  370.      SLEARN Documentation                                             page 6
  371.  
  372.  
  373.  
  374.  
  375.  
  376.      SLEARN v1.00                                               Using SLEARN
  377.  
  378.      Using SLEARN
  379.      ------------
  380.      The easiest, most automatic way to use SLEARN is through the SLEARN.SLT
  381.      script.  Just use Telix's Alt-G (run script) command to run SLEARN.  If
  382.      you are creating a logon script for a specific system, use TFE or Telix
  383.      to include 'slearn' as the Script field for that system's dialing dir-
  384.      ectory.  Then, just dial the entry from Telix.  When Telix connects to
  385.      the other system, it will automatically run SLEARN.
  386.  
  387.      Once SLEARN is running, simply go through the actions you wish to auto-
  388.      mate, just as if you were using Telix.  That is, when (for example) the
  389.      system asks for your name or password, just enter them as usual.  "Wri-
  390.      ting" the SALT script is as easy as that!  As a bonus, if you run
  391.      SLEARN by making it the connect script for a dialing directory entry,
  392.      and you have a password defined for that entry, you can just hit the F1
  393.      key to send your password for you (the SLEARN.SLC script will automat-
  394.      ically tell SLEARN what your password is, unless you tell it not to, as
  395.      explained above).  
  396.  
  397.           NOTE:  Keep in mind that SLEARN is not Telix.  You can re-
  398.           ceive and send text while using SLEARN, but you can not ac-
  399.           cess the Telix dialing directory, file transfers, or any
  400.           other telix features.  This also means that none of these
  401.           functions may be "learned".  As an alternative, try "learn-
  402.           ing" a process up to the last step before, for example, a
  403.           file transfer.  Afterwards, you can either add the transfer
  404.           command to the script yourself, or perform the transfer man-
  405.           ually when the script is run.  Either way, SLEARN gives you a
  406.           head start on automating the process.
  407.  
  408.      When you are done with the steps you wish to automate, hit Alt-X to
  409.      tell SLEARN to finish writing the SALT script for what you have just
  410.      done, and return to Telix.
  411.  
  412.      At this point, the SLEARN script will ask you whether you want to save
  413.      the script you have just created.  If you answer "no", the script will
  414.      be deleted.  Otherwise, SLEARN will ask you what name to use for the
  415.      new script -- or you may hit ENTER alone to choose the default name. 
  416.      SLEARN will then run CS.EXE to compile the script (it is important that
  417.      CS.EXE be present either in your Telix script directory, or in a direc-
  418.      tory listed in your DOS PATH -- otherwise, SLEARN will not be able to
  419.      locate and run the program).  And if you have not set "UseSetScr = 0"
  420.      as explained above, SLEARN will ask if you want to run SET_SCR.EXE to
  421.      install the name of the new script as the logon script for this entry. 
  422.      If you answer yes, SET_SCR will do so -- replacing the 'slearn' you had
  423.      entered with the name of the new script.
  424.  
  425.           WARNING: it is important that you have a dummy FON file named
  426.           ZZZ.FON in your Telix directory.  If you do not have such a file,
  427.           the SLEARN script will create one for you by copying TELIX.FON to
  428.  
  429.      SLEARN Documentation                                             page 7
  430.  
  431.  
  432.  
  433.  
  434.  
  435.      SLEARN v1.00                                               Using SLEARN
  436.  
  437.           ZZZ.FON.  This file is loaded when TELIX.FON is being modified, to
  438.           avoid modifying a file which Telix is currently using.
  439.  
  440.  
  441.  
  442.  
  443.  
  444.  
  445.  
  446.  
  447.  
  448.  
  449.  
  450.  
  451.  
  452.  
  453.  
  454.  
  455.  
  456.  
  457.  
  458.  
  459.  
  460.  
  461.  
  462.  
  463.  
  464.  
  465.  
  466.  
  467.  
  468.  
  469.  
  470.  
  471.  
  472.  
  473.  
  474.  
  475.  
  476.  
  477.  
  478.  
  479.  
  480.  
  481.  
  482.  
  483.  
  484.  
  485.  
  486.  
  487.  
  488.      SLEARN Documentation                                             page 8
  489.  
  490.  
  491.  
  492.  
  493.  
  494.      SLEARN v1.00                                             Advanced Usage
  495.  
  496.      Advanced Usage
  497.      --------------
  498.      There may be times when you wish to use the SLEARN program itself,
  499.      outside of Telix or without the use of the SLEARN.SLT script.  The
  500.      SLEARN program takes the following parameters (all parameters in brack-
  501.      ets are optional):
  502.  
  503.      slearn [-g] [-n <s>] [-p<n>] [-b<n>] [-s<s>] [-a] [-w <s>] filename
  504.  
  505.      The parameters have the following effects:
  506.  
  507.      -g        Sounds control-G's (bells) when SLEARN is run.  This is nor-
  508.                mally used when SLEARN is run from a dialing directory entry,
  509.                so that you'll know a connection has been made.  The reason I
  510.                haven't just included an alarm() command in the SLEARN.SLT
  511.                script is that during the time that the alarm is sounding,
  512.                some characters may be received by Telix from the remote. 
  513.                SLEARN will not see any of these characters, which may make
  514.                creating a logon script for that board impossible.  Basical-
  515.                ly, the object is to get SLEARN itself running as soon as
  516.                possible after a connection has been made, so that ALL
  517.                prompts you may need can be processed by SLEARN.  This option
  518.                probably won't be too useful from the DOS command line.
  519.  
  520.      -n <s>    Sets entry name to <s>.  This option is used by SLEARN.SLT so
  521.                that SLEARN can correctly note what board it is learning a
  522.                script for.  This name is included near the top of the
  523.                learned script file.  If the string is blank, no "Automatic
  524.                logon script for..." line is included in the learned script.
  525.  
  526.      -p<n>     Sets communications port to COM<n>.  This tells SLEARN what
  527.                communications port to use.  The default is COM1.
  528.  
  529.      -b<n>     Sets bps rate to <n>.  This tells SLEARN what speed your
  530.                modem will use.  The default is 2400 bps.
  531.  
  532.      -s<s>     Sets parity, data, stop to <s>.  This option sets the parity,
  533.                data bits, and stop bits parameters SLEARN will use when
  534.                communicating.  This should be a three-character string, the
  535.                first character being "N", "E", or "O" to represent No par-
  536.                ity, Even parity, or Odd parity;  the next character will be
  537.                7 or 8, depending on the number of data bits;  and the final
  538.                character should be 1 or 2 to set the number of stop bits to
  539.                use.  Common settings are "E71" and "N81" -- the default is
  540.                "N81".
  541.  
  542.      -a        Anonymous (don't include showname() function).  SLEARN nor-
  543.                mally includes in the learned script a call to a function
  544.                called showname(), which displays the name of the system to
  545.                which you are connected.  Actually, only the first 14 charac-
  546.  
  547.      SLEARN Documentation                                             page 9
  548.  
  549.  
  550.  
  551.  
  552.  
  553.      SLEARN v1.00                                             Advanced Usage
  554.  
  555.                ters are displayed.  This name overwrites Telix's "Alt-z for
  556.                help" message -- I consider the extra information to be worth
  557.                the sacrifice, but if it bothers you, use the -a switch.
  558.  
  559.      -w <s>    Sets the password for this script.  This is useful for two
  560.                reasons.  First of all, when running SLEARN you can send your
  561.                password (followed by a carriage return) simply by pressing
  562.                F1.  Second, whenever you send your password (by typing it or
  563.                by F1), SLEARN recognizes it, and instead of including the
  564.                literal password in the script, it uses Telix's _entry_pass
  565.                variable, which is always set to the name of the system you
  566.                are connected to (as stored in the dialing directory).  This
  567.                has two benefits:  (1) you can let other people have copies
  568.                of the script without giving away your password; and (2) if
  569.                you call more than one system with the same logon sequence,
  570.                but a different password, you can use the same script for all
  571.                of them -- the script will send the appropriate password for
  572.                each system.
  573.  
  574.      filename  Name of the SALT file to create.  This is the only parameter
  575.                REQUIRED by SLEARN.  This is the filename of the script
  576.                SLEARN will be learning.  If you specify a name without an
  577.                extension, the extension .SLT will be supplied for you.
  578.  
  579.  
  580.  
  581.  
  582.  
  583.  
  584.  
  585.  
  586.  
  587.  
  588.  
  589.  
  590.  
  591.  
  592.  
  593.  
  594.  
  595.  
  596.  
  597.  
  598.  
  599.  
  600.  
  601.  
  602.  
  603.  
  604.  
  605.  
  606.      SLEARN Documentation                                            page 10
  607.  
  608.  
  609.  
  610.  
  611.  
  612.      SLEARN v1.00                                         Registering SLEARN
  613.  
  614.                                   Registration
  615.  
  616.  
  617.           NOTE: SLEARN may NOT be used in a business or commercial
  618.           environment without registration.
  619.  
  620.      SLEARN is distributed as shareware.  The advantage of this is that you
  621.      get to try out the full, working program and see whether or not it
  622.      suits your needs.  If you find SLEARN useful, you must register the
  623.      program.  Just to prod your good will along, registration has a few
  624.      perks: you will receive the latest version of SLEARN on disk, along
  625.      with inexpensive on-disk updates to future versions.  Comments, sugges-
  626.      tions, and requests from registered users will of course have a higher
  627.      priority.  Without registrations, there will soon cease to BE future
  628.      versions of SLEARN, simply because I've got to make a living, and I
  629.      have no choice but to devote the bulk of my time to projects that will
  630.      help me pay my bills.
  631.  
  632.      To register SLEARN, just fill out the registration form below; be sure
  633.      to include your check or money order (in US Dollars), and mail it to
  634.      the address below.  Basic registration is ten dollars, including ship-
  635.      ping, handling, and the cost of a floppy disk (5 1/4", MS-DOS DS/DD,
  636.      with the latest version of SLEARN).  Registered users of previous
  637.      SLEARN versions can upgrade to the latest version for five dollars.  Of
  638.      course, once you've registered one version of SLEARN, you've registered
  639.      all future versions as well -- so you can simply download the latest
  640.      version from a BBS.  I provide the upgrade service for those who can't
  641.      find the latest version elsewhere.
  642.  
  643.      For a special price of only $15, you can register both SLEARN and TFE
  644.      (TelixFonEd), receiving both on disk, along with a collection of Telix
  645.      scripts, tips and utilities.
  646.  
  647.      Thank you for registering SLEARN.
  648.  
  649.      The registration form follows.
  650.  
  651.  
  652.  
  653.  
  654.  
  655.  
  656.  
  657.  
  658.  
  659.  
  660.  
  661.  
  662.  
  663.  
  664.  
  665.      SLEARN Documentation                                            page 11
  666.  
  667.  
  668.  
  669.  
  670.  
  671.      SLEARN v1.00                                         Registering SLEARN
  672.  
  673.                             SLEARN registration form
  674.  
  675.  
  676.      I would like to register SLEARN in the following manner (check one):
  677.  
  678.  
  679.      __ Regular registration (with the latest version on disk)        $10.00
  680.  
  681.      __ Register SLEARN and TFE, plus bonus scripts and utilities     $15.00
  682.  
  683.      I am enclosing a check or money order for the appropriate amount of US
  684.      dollars.
  685.  
  686.  
  687.      Name:               ___________________________________________________
  688.  
  689.      Street Address:     ___________________________________________________
  690.  
  691.      City, ST:           ___________________________________________________
  692.  
  693.      Zip:                _____________
  694.  
  695.      Home phone number (optional): (_____)-______________
  696.  
  697.      Work phone number (optional): (_____)-______________
  698.  
  699.  
  700.      Where did you find SLEARN?  ___________________________________________
  701.  
  702.  
  703.      Comments and/or Suggestions:  _________________________________________
  704.  
  705.      _______________________________________________________________________
  706.  
  707.      _______________________________________________________________________
  708.  
  709.      _______________________________________________________________________
  710.  
  711.      _______________________________________________________________________
  712.  
  713.  
  714.  
  715.      Please send this form, along with your check or money order, to:
  716.  
  717.           Paul Roub
  718.           P.O. Box 141583
  719.           Coral Gables, FL  33114-1583
  720.  
  721.  
  722.  
  723.  
  724.      SLEARN Documentation                                            page 12
  725.