home *** CD-ROM | disk | FTP | other *** search
/ kermit.columbia.edu / kermit.columbia.edu.tar / kermit.columbia.edu / sinclairqla / qlkerdoc.txt < prev    next >
Text File  |  1987-05-07  |  35KB  |  1,152 lines
  1.   QL-KERMIT                                          Edition DRAFT, 4-May-87
  2.  
  3.  
  4.  
  5.  
  6.  
  7.  
  8.  
  9.  
  10.  
  11.                          QL-KERMIT - Documentation
  12.                          =========================
  13.  
  14.  
  15.  
  16.  
  17.   1.  Introduction
  18.   ----------------
  19.  
  20.  
  21.   This  documentation briefly describes my (with acknowlegements to others -
  22.   see the  comments  at  the  front  of  the main program) implementation of
  23.   Kermit on the Sinclair QL.  It is assumed  that  the  reader is reasonably
  24.   familiar with Kermit and how to use a "standard" Kermit program.
  25.  
  26.   The first release version of QL-Kermit (referred to from here on as 'QLK')
  27.   comprises about 120K bytes of  C  source,  compiling to about 55K bytes of
  28.   object code.  Although the object will run on  a standard unexpanded QL, a
  29.   memory expansion (preferably to the maximum 640K) and at  least  one  disc
  30.   drive  is  an essential configuration for compilation or development work.
  31.   The Metacomco C Development Kit is also required.
  32.  
  33.   Refer to  the Building QL-Kermit  section  for information on building QLK
  34.   from source.
  35.  
  36.  
  37.  
  38.  
  39.  
  40.  
  41.  
  42.  
  43.  
  44.  
  45.  
  46.  
  47.  
  48.  
  49.  
  50.  
  51.  
  52.  
  53.  
  54.  
  55.  
  56.  
  57.  
  58.  
  59.  
  60.  
  61.  
  62.                                     Page 1
  63.  
  64.  
  65.  
  66.  
  67.   QL-KERMIT                                          Edition DRAFT, 4-May-87
  68.  
  69.  
  70.  
  71.  
  72.  
  73.   2.  Capabilities at a Glance
  74.   ----------------------------
  75.  
  76.  
  77.          Local operation                         Yes
  78.          Remote operation                        No
  79.          Transfer text files                     Yes
  80.          Transfer binary files                   Yes
  81.          Wildcard send                           No
  82.          ^X/^Z interruption                      Yes
  83.          Filename collision avoidance            No
  84.          Can time out                            Yes
  85.          8th-bit prefixing                       Yes
  86.          Repeat count prefixing                  No
  87.          Alternate block checks                  No
  88.          Terminal emulation                      Yes
  89.          Communications settings                 Yes
  90.          Transmit BREAK                          No
  91.          IBM mainframe communication             No
  92.          Transaction logging                     No
  93.          Session logging                         No
  94.          Raw transmit                            No
  95.          Act as server                           No
  96.          Talk to server                          Yes
  97.          Advanced server functions               No
  98.          Advanced commands for servers           Limited
  99.          Local file management                   Unnecessary
  100.          Handle file attributes                  No
  101.          Command files                           Yes
  102.          Command macros                          No
  103.          XON/XOFF flow control                   No
  104.          Split baud rates                        No
  105.  
  106.  
  107.   I have not implemented some  of  these  features for various reasons:  (a)
  108.   they are not relevant to  my  intended  use  of  QLK;   (b)  they would be
  109.   impossible  to  implement  on  the QL hardware (e.g. transmit BREAK);  (c)
  110.   they may be implemented at a later date.
  111.  
  112.   Note:  At present I have  only tested QLK transferring files to and from a
  113.   BBC  running  Lancs-Kermit  (version  1.45).   Therefore   I   have   only
  114.   extensively  tested  features which are used  by  this  configuration.   I
  115.   cannot guarantee that other facilities work well enough, if at all.
  116.  
  117.  
  118.  
  119.  
  120.  
  121.  
  122.  
  123.  
  124.  
  125.  
  126.  
  127.  
  128.                                     Page 2
  129.  
  130.  
  131.  
  132.  
  133.   QL-KERMIT                                          Edition DRAFT, 4-May-87
  134.  
  135.  
  136.  
  137.  
  138.  
  139.   3.  Using the program
  140.   ---------------------
  141.  
  142.  
  143.   Assuming that the binary version of QLK has been obtained or built, it can
  144.   be run by using the EXEC command (or, if you have Toolkit or Super Toolkit
  145.   fitted, EX).  The console window  will  clear, and the version string will
  146.   be displayed.  At this point it will  look  for  a startup file which will
  147.   typically  contain  a series of Kermit commands to configure QLK  for  the
  148.   intended   application.   As   supplied   the   file   searched   for   is
  149.   "flp1_qlk_take"; it can  be  altered  to look for a different file or on a
  150.   different device by changing the symbol DFTAKE in the header file ker_h.
  151.  
  152.   When this startup file has  ended,  or if none is found, the prompt "QLK>"
  153.   will be displayed.  (Fairly) standard Kermit commands  can now be entered;
  154.   these are listed in the next section.  The  following  control keys can be
  155.   used to control and edit command lines:
  156.  
  157.     F1   (HELP)  When pressed at the  beginning  of  a  field, indicate what
  158.          this  field  needs  to  be  completed with, or display  a  list  of
  159.          options.
  160.  
  161.     F3   (DELETE LINE)  Abandon the current  command  entirely.  ^U can also
  162.          be used.
  163.  
  164.     F4   (COMPLETE/DEFAULT)  If pressed at the beginning  of a field, supply
  165.          and display the default value  for that field (if any).  If pressed
  166.          in the middle of a 'keyword'  field, complete the field if what has
  167.          been  typed  already is valid and unambiguous.   If  these  do  not
  168.          apply, the key is ignored.  ESC can also be used.
  169.  
  170.     F5   (DELETE CHARACTER)  Delete the character to the left of the cursor.
  171.          The standard QL CTRL-LEFT, or ^H, can also be used.
  172.  
  173.     ^R   (REDISPLAY)  Replay the current command  line  (e.g.  if the screen
  174.          has been corrupted by another job's output).
  175.  
  176.   Commands  may  be  entered in either upper or lower case  (or  indeed  any
  177.   mixture of the two).
  178.  
  179.   Note that CTRL-C can be  used  to switch the keyboard input to another job
  180.   (assuming  that  QLK  has been started by  EXEC  or  EX);  this  makes  it
  181.   unnecessary to include commands in QLK for local file management.
  182.  
  183.   During file transfer, the following control keys are recognised:
  184.  
  185.     ^X   (INTERRUPT FILE)  If sending,  end transmission of the current file
  186.          and send an EOF packet with a Discard request.  Note that since the
  187.          current version of QLK does  not  support  the  sending of multiple
  188.          files, this key has an identical action to ^Z.
  189.  
  190.          If receiving, request the remote  system  to abort the transmission
  191.          of  the current file and continue with  the  next  one  (if  it  is
  192.  
  193.  
  194.                                     Page 3
  195.  
  196.  
  197.  
  198.  
  199.   QL-KERMIT                                          Edition DRAFT, 4-May-87
  200.  
  201.  
  202.          sending multiple files).
  203.  
  204.     ^Z   (INTERRUPT BATCH)  If sending, end transmission of the current file
  205.          and send an EOF packet with a Discard request, followed by  an  EOT
  206.          packet to end the batch.
  207.  
  208.          If receiving,  request  the remote system to abort the transmission
  209.          of the current file and  not  send  any  more  (if  it  is  sending
  210.          multiple files).
  211.  
  212.     ^T   (FORCE TIMEOUT)  If pressed while QLK is waiting for a packet to be
  213.          received, the wait will be  abandoned and a timeout simulated, thus
  214.          forcing QLK to resend the previous  packet or acknowledgment.  This
  215.          is  useful for manually unjamming the deadlock  caused  by  a  lost
  216.          packet, if for some reason the timeout facility is not being used.
  217.  
  218.     ^E   (FATAL ERROR)   If  for  some  reason  the  remote  system does not
  219.          support  ^X/^Z interruption, these control keys will have no effect
  220.          in stopping  the  transfer.  In this case pressing ^E will cause an
  221.          Error packet to be  sent  with an appropriate message - this should
  222.          cause any remote system to stop.
  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.  
  253.  
  254.  
  255.  
  256.  
  257.  
  258.  
  259.  
  260.                                     Page 4
  261.  
  262.  
  263.  
  264.  
  265.   QL-KERMIT                                          Edition DRAFT, 4-May-87
  266.  
  267.  
  268.  
  269.  
  270.  
  271.   4.  Commands
  272.   ------------
  273.  
  274.  
  275.   The commands available in QLK  are  listed  here,  with  the  syntax and a
  276.   description for each.  Note that a command or required keyword need not be
  277.   typed in full - only enough characters need be typed to make what is meant
  278.   unambiguous.
  279.  
  280.   UPPERCASE   is   to  be  typed  literally;  lowercase  indicates  variable
  281.   parameters; [brackets] indicate optional parameters.  Possible options are
  282.   seperated by ','s.
  283.  
  284.  
  285.  
  286.   CONNECT
  287.  
  288.   This enters terminal emulation on the currently selected serial line.  The
  289.   screen  will clear and the  cursor  reappears  in  the  top  left  corner.
  290.   Terminal emulation  is  extremely  dumb,  with  no support for any special
  291.   features of the QL screen or any  standard  video  terminal.   The special
  292.   keys recognised are:
  293.  
  294.     F2   (EXIT)  This returns to Kermit command mode.
  295.  
  296.     F3   (NULL)  This sends the ASCII code 0.
  297.  
  298.     F4   (^C)  This sends the ASCII code 3.
  299.  
  300.     F5   (DEL)  This sends the ASCII code 127.
  301.  
  302.    ENTER (EOL) Sends the currently defined  end  of line sequence, as set by
  303.          SET ENTER.
  304.  
  305.   All other keys are sent  to the serial line.  If the LOCAL-ECHO option has
  306.   been set to ON, the key  press  is  also  echoed  to the screen.  ENTER is
  307.   always echoed as a newline regardless of the setting of the  end  of  line
  308.   sequence.
  309.  
  310.  
  311.  
  312.   DO command-line
  313.  
  314.   This is equivalent to REMOTE HOST in  most  other  versions of Kermit.  It
  315.   sends the specified 'command-line' to  be  executed  by the remote server,
  316.   and displays the results on the QL screen.
  317.  
  318.  
  319.  
  320.   EXIT
  321.  
  322.   Exits the Kermit program.
  323.  
  324.  
  325.  
  326.                                     Page 5
  327.  
  328.  
  329.  
  330.  
  331.   QL-KERMIT                                          Edition DRAFT, 4-May-87
  332.  
  333.  
  334.  
  335.  
  336.   FINISH
  337.  
  338.   Sends a command to a remote server requesting it to exit server operation,
  339.   and return to Kermit command mode.
  340.  
  341.  
  342.  
  343.   GET remote [local]
  344.  
  345.   Asks the remote server to  send  a file.  'remote' is the file to be sent,
  346.   in the filename syntax appropriate to the  remote  system.  'local' is the
  347.   QL filename to store it under; if omitted, the  name that the remote sends
  348.   in  the File-Header packet will be translated to a suitable  QL  filename.
  349.   If 'local'  is  not  given, or if it is given but it includes no QL device
  350.   prefix, the file will be  stored  on the current DESTINATION device.
  351.  
  352.   Note that if the server  sends  multiple  files  as  a result of including
  353.   wildcards  in 'remote', then 'local' must not be given, otherwise  the  QL
  354.   will overwrite  the  just-received  file  each  time a new one is started.
  355.   However, QLK does not check this, and  it  may  even  be  useful  in  some
  356.   applications  (e.g.  to  see  the  files on the screen, give "scr_" as the
  357.   local name).
  358.  
  359.  
  360.  
  361.   HELP
  362.  
  363.   Displays  a summary of the control keys available in command, transfer and
  364.   terminal modes.
  365.  
  366.  
  367.  
  368.   QUIT
  369.  
  370.   Equivalent to EXIT.
  371.  
  372.  
  373.  
  374.   RECEIVE [local]
  375.  
  376.   Waits for  a  file  to  be  sent from a remote non-server.  'local' is the
  377.   filename that it will be stored under;  if  omitted,  the  name  that  the
  378.   remote sends in the  File-Header  packet  will  be used (as for GET).  The
  379.   remarks under GET regarding multiple files also apply here.
  380.  
  381.  
  382.  
  383.   SEND local [remote]
  384.  
  385.   Sends a file to a remote, whether a server or not.  'local' is the QL file
  386.   to be sent.  'remote', if  given,  is  the  name  that will be sent in the
  387.   File-Header packet; if omitted, the local name  will  be used.  If 'local'
  388.   has no QL device prefix, the current SOURCE device will be used.
  389.  
  390.  
  391.  
  392.                                     Page 6
  393.  
  394.  
  395.  
  396.  
  397.   QL-KERMIT                                          Edition DRAFT, 4-May-87
  398.  
  399.  
  400.  
  401.  
  402.   SET parameter option
  403.   SET sub-section parameter option
  404.  
  405.   Controls various options of the Kermit program.  See the next section.
  406.  
  407.  
  408.  
  409.   SHOW [what]
  410.  
  411.   Displays  the  current  Kermit  settings and parameters.  'what' indicates
  412.   what is to be shown, it may be:
  413.  
  414.          ALL             Everything except VERSION
  415.          COMMUNICATION   Settings relating to the serial ports and
  416.                          terminal emulation
  417.          DEVICES         Current default devices (see SET DEVICE)
  418.          FILE            Settings relating to file transfer
  419.          PREFIX          The current quote characters
  420.          SYSTEM          Settings which don't fit in anywhere else
  421.          TRANSFER        Protocol parameters, timeouts, etc.
  422.          VERSION         The current QLK version
  423.  
  424.   If 'what' is omitted, ALL is assumed.
  425.  
  426.  
  427.  
  428.   TAKE filename
  429.  
  430.   Read and execute Kermit commands from a file.  No file suffix is enforced,
  431.   but the suggested one is "_take".  If the filename  given has no QL device
  432.   prefix, then the current TAKE device will be used.
  433.  
  434.   If the TAKE-ECHO option is  set to ON, command lines read from a TAKE file
  435.   will be listed on the screen  prior  to them being executed.  They will be
  436.   preceded  by  "TAKE-n>",  where  n  is the TAKE  file  nesting  level,  to
  437.   distinguish them from commands typed at the keyboard.
  438.  
  439.   The TAKE command can be  used within a TAKE file, thus allowing them to be
  440.   nested to a maximum of 10 levels.  However, if an invalid command is read,
  441.   or if an error occurs during  a  file  transfer,  the entire stack of TAKE
  442.   files will be abandoned if the TAKE-ABORT option is set to ON.  (This does
  443.   not include a transfer interruption initiated by ^X or ^Z; however it does
  444.   include a fatal error initiated  by  ^E).  This can be disabled by setting
  445.   the TAKE-ABORT option to OFF.
  446.  
  447.  
  448.  
  449.  
  450.  
  451.  
  452.  
  453.  
  454.  
  455.  
  456.  
  457.  
  458.                                     Page 7
  459.  
  460.  
  461.  
  462.  
  463.   QL-KERMIT                                          Edition DRAFT, 4-May-87
  464.  
  465.  
  466.  
  467.  
  468.  
  469.   5.  The SET command
  470.   -------------------
  471.  
  472.  
  473.   The  options  that can be controlled by the SET command are  given  below.
  474.   Note that SEND,  RECEIVE,  FILE  and  DEVICE  are  logically sub-sections,
  475.   although they are described here as if they were seperate options.
  476.  
  477.  
  478.  
  479.   BAUD speed
  480.  
  481.   Set the baud rate for the currently set serial  line.  The valid rates are
  482.   those listed in the  QL  manual.   The setting on entry is for the current
  483.   speed to be retained (as set by the SuperBasic BAUD command).
  484.  
  485.  
  486.  
  487.   CONTROL-QUOTE char
  488.  
  489.   Sets the character that QLK will prefix control characters in packets that
  490.   it sends with, and indicate to the remote system that it will do so.  This
  491.   is normally '#', but can  be  changed for special applications.  Note that
  492.   QLK, when receiving packets, always uses the  quote  character  the remote
  493.   has asked it to.
  494.  
  495.  
  496.  
  497.   DEBUGGING OFF,ON,FULL
  498.  
  499.   Sets the debugging level.  OFF  is  the initial setting, no information is
  500.   displayed.  ON causes messages regarding file manipulation and packet read
  501.   failures to be displayed.  FULL in addition displays information regarding
  502.   the switcher state, and the contents of all incoming and outgoing packets.
  503.  
  504.  
  505.  
  506.   DELAY time
  507.  
  508.   Sets the wait, in seconds, between the SEND command being accepted and the
  509.   file transfer starting.  If connected  to  another  microcomputer  Kermit,
  510.   this  gives  time for the RECEIVE command to be typed on the other system.
  511.   The initial setting is 5 seconds.
  512.  
  513.   While QLK is  waiting ("Pausing" displayed) the wait can be interrupted by
  514.   pressing any key; the transfer will start immediately.
  515.  
  516.  
  517.  
  518.   DEVICE DESTINATION device
  519.  
  520.   Sets the default destination device for file transfers.  If the opening of
  521.   the file for the GET or RECEIVE commands fails due to a "Not found" error,
  522.  
  523.  
  524.                                     Page 8
  525.  
  526.  
  527.  
  528.  
  529.   QL-KERMIT                                          Edition DRAFT, 4-May-87
  530.  
  531.  
  532.   this string will be prepended  to  the file name and another attempt made.
  533.   No  checks are made on the validity  of  this  device,  and  the  trailing
  534.   underscore must  be  included.   Note that if the first attempt at opening
  535.   the file fails for some  reason other than "Not found" (e.g. "In use") the
  536.   addition of the device prefix will  not  be done and an error message will
  537.   be issued immediately.
  538.  
  539.   The initial setting is "flp2_".
  540.  
  541.  
  542.  
  543.   DEVICE SOURCE device
  544.  
  545.   Sets the default source device  for  file  transfers.   If  the local file
  546.   given in the SEND command is not found, this device  will  be prepended to
  547.   the name given  and  another  attempt  made  to   find  it.   The  remarks
  548.   applying to DESTINATION regarding other errors also apply here.
  549.  
  550.   The initial setting is "flp2_".
  551.  
  552.  
  553.  
  554.   DEVICE TAKE-FILE device
  555.  
  556.   Sets the default source device for command files read by the TAKE command.
  557.   The initial setting is "flp1_".
  558.  
  559.  
  560.  
  561.   EIGHT-BIT-QUOTE char
  562.  
  563.   Sets the character that QLK  will  use  for  8th-bit  quoting,  if  it  is
  564.   necessary and the remote system agrees to use the same character.  This is
  565.   normally  '&', but can be changed for special applications.
  566.  
  567.  
  568.  
  569.   ENTER CR,LF,CRLF,LFCR
  570.  
  571.   Sets the character(s) that will  be transmitted in terminal emulation mode
  572.   when the ENTER key is pressed.   CR  is  Carriage Return (ASCII 13); LF is
  573.   Line Feed (ASCII 10).  If it is set to  CRLF  or  LFCR then two characters
  574.   will be transmitted in succession.  The initial setting is CR.
  575.  
  576.  
  577.  
  578.   FILE INCOMPLETE DELETE,KEEP
  579.  
  580.   Controls  what  happens  to  a  partially  received  file if a transfer is
  581.   abandoned (by a ^X or  ^Z  interrupt)  or  fails  (due to an error or a ^E
  582.   interrupt).  If set to DELETE, the file is deleted; if  set  to  KEEP, the
  583.   partial file is retained.  The initial setting is DELETE.
  584.  
  585.  
  586.  
  587.  
  588.  
  589.  
  590.                                     Page 9
  591.  
  592.  
  593.  
  594.  
  595.   QL-KERMIT                                          Edition DRAFT, 4-May-87
  596.  
  597.  
  598.  
  599.  
  600.   FILE NAME NORMAL,UNTRANSLATED
  601.  
  602.   Controls  whether  file  names sent or received in File-Header packets are
  603.   translated  to or from a  standard  QL  format  before  use.   If  set  to
  604.   UNTRANSLATED, when sending the name sent will be identical to the name the
  605.   QL file  was opened with (not necessarily that given on the command line);
  606.   for receive, the name contained in the packet will be used for the QL file
  607.   (but the DESTINATION device will still be prepended if necessary).
  608.  
  609.   If set to  NORMAL,  the  QL  filename  will  be  translated to or from the
  610.   "standard"  Kermit  format  (as  described  in  the Protocol Manual).  The
  611.   conversions applied for sending are:
  612.  
  613.     (a)  The QL device prefix is stripped off
  614.     (b)  Lowercase letters are converted to uppercase
  615.     (c)  The last '_', if any, is changed to a '.'.
  616.  
  617.   The conversions applied on receiving are:
  618.  
  619.     (a)  Uppercase letters are converted to lowercase
  620.     (b)  Any '.'s are converted to '_'s.
  621.  
  622.   Note that, if a remote name is  given  in  the  SEND command, this will be
  623.   sent verbatim in the packet, even if NORMAL mode is set.   Similarly, if a
  624.   local name is given for GET or RECEIVE, this will not be translated (apart
  625.   from the possible addition of the DESTINATION device).
  626.  
  627.   The initial mode is NORMAL.
  628.  
  629.  
  630.  
  631.   FILE SUFFIX [string]
  632.  
  633.   Sets  a  possible  suffix string which is added to files sent by  QLK,  to
  634.   identify their source when  they  are  stored on a remote filestore.  If a
  635.   'string' is given, this (preceded  by  a '_') will be appended to outgoing
  636.   filenames before undergoing translation.  This suffix will not be added if
  637.   a remote name is given explicitly, or if UNTRANSLATED mode is set.
  638.  
  639.   If 'string' is not given, no suffix   will be added.  Initially, no suffix
  640.   is set.
  641.  
  642.   An example may be in  order  here  to clarify the interaction between send
  643.   translation and suffix addition.  If the SOURCE device  is  set to "flp2_"
  644.   and the SUFFIX to "ql", then the command:
  645.  
  646.          SEND main_c
  647.  
  648.   will  search  first  for  "main_c"   (and  not  find  it)  and  then  find
  649.   "flp2_main_c" (assuming that it exists  on  that  device).   Firstly,  the
  650.   suffix will be added to that name, giving "flp2_main_c_ql", then this will
  651.   be  translated  to  the  Kermit  format  -  making  the  name  sent in the
  652.   File-Header packet "MAIN_C.QL".
  653.  
  654.  
  655.  
  656.                                    Page 10
  657.  
  658.  
  659.  
  660.  
  661.   QL-KERMIT                                          Edition DRAFT, 4-May-87
  662.  
  663.  
  664.   If no file suffix is  set,  the  name  "flp2_main_c" will be translated to
  665.   Kermit format, thus sending "MAIN.C".
  666.  
  667.   If UNTRANSLATED mode had been set, then the name  sent in the packet would
  668.   be "flp2_main_c".
  669.  
  670.  
  671.  
  672.   FILE TYPE ASCII,BINARY
  673.  
  674.   Controls whether end-of-line translation  is  applied to file data sent or
  675.   received during a transfer.  If set  to  BINARY,  no  translation is done;
  676.   this  allows object files, etc. to be sent and received  exactly  as  they
  677.   appear in the filestore.
  678.  
  679.   If set to ASCII, end-of-line translation is done as follows:
  680.  
  681.   For sending, a QL end  of line (LF, ASCII 10) is sent in the packet as the
  682.   prefix sequence "#M#J", assuming that the  control-quote in use is '#'.  A
  683.   carriage return (ASCII 13) encountered in the  file  will be sent as "#M".
  684.   For receiving, "#M" is ignored and "#J" is written to the file as LF.
  685.  
  686.   This has the effect (assuming that the option is  set  correctly  at  both
  687.   ends  of the link) of allowing a printable text file on the sending system
  688.   to become  a  printable  text  file on the receiving system, regardless of
  689.   what means the other system uses to represent end of line.
  690.  
  691.   Note that the ASCII/BINARY setting has  no  bearing on whether the 8th-bit
  692.   of a byte is sent, with quoting or  otherwise.   It  affects  end  of line
  693.   translation only.
  694.  
  695.   The initial setting is ASCII.
  696.  
  697.  
  698.  
  699.   LINE [1,2]
  700.  
  701.   Sets the serial port to  be used for data transfer.  '1' selects ser1, '2'
  702.   selects ser2.  If '1' or '2'  is  not  given,  the old line is freed (thus
  703.   allowing another job to use that serial  port)  but no new line is opened.
  704.   Initially, no line is set.
  705.  
  706.  
  707.  
  708.   LOCAL-ECHO OFF,ON
  709.  
  710.   Controls whether keys pressed in terminal mode are echoed to the screen by
  711.   the QL, or by the  remote  computer.   Note  that  if it is set to ON, the
  712.   ENTER key is always echoed  as  a newline regardless of the setting of the
  713.   ENTER action.  The initial setting is OFF.
  714.  
  715.  
  716.  
  717.   PADDING [amount [character]]
  718.  
  719.   Controls whether padding is inserted after a transmitted packet,  to allow
  720.  
  721.  
  722.                                    Page 11
  723.  
  724.  
  725.  
  726.  
  727.   QL-KERMIT                                          Edition DRAFT, 4-May-87
  728.  
  729.  
  730.   for  communication line delays or remote system requirements.  'amount' is
  731.   the number  of  pad  characters that are to be transmitted; the default is
  732.   0 (no padding).  'character' is the character to be used (in decimal); the
  733.   default is NUL (ASCII 0).   If  'amount'  and  'character' are omitted, no
  734.   padding will be done.
  735.  
  736.   Note that the amount of  padding  and  the  character  used are subject to
  737.   negotiation  in  the  Send-Init  packet exchange.  The algorithms used are
  738.   explained later.
  739.  
  740.  
  741.  
  742.   PARITY NONE,ODD,EVEN,MARK,SPACE
  743.  
  744.   Selects the parity setting that  will  be used by the QL for transmission,
  745.   and checked on reception.  The initial setting is NONE.
  746.  
  747.   The  parity  setting  interacts  with  whether  8th-bit  quoting  will  be
  748.   specified or requested in the Send-Init packet  exchange.   See  the notes
  749.   later regarding this exchange.
  750.  
  751.  
  752.  
  753.   RECEIVE END-OF-LINE code
  754.  
  755.   Specifies  the end-of-line character that  QLK  will  request  the  remote
  756.   system to  terminate  a  packet  with.   This is specified in decimal; the
  757.   initial setting is Carriage Return (ASCII 13).   Note  that  QLK  does not
  758.   require  any end of packet marker, so this option is redundant.   It  also
  759.   appears pointless to allow this character to be specified in the Send-Init
  760.   exchange, since  if a different terminator to the default was required the
  761.   Send-Init packet or its acknowledgement could not be received!
  762.  
  763.  
  764.  
  765.   RECEIVE MARKER code
  766.  
  767.   Specifies, in decimal, the character  that  QLK  will look for to indicate
  768.   the start of an incoming packet.  The initial setting is SOH (ASCII 1).
  769.  
  770.  
  771.  
  772.   RECEIVE PACKET-LENGTH length
  773.  
  774.   Specifies the maximum packet length  that  QLK  will  request  the  remote
  775.   system to send.  The initial setting is  the  maximum  of  94.  A sensible
  776.   minimum is about 30, but this is not enforced by QLK.
  777.  
  778.  
  779.  
  780.   RECEIVE TIMEOUT time
  781.  
  782.   Specifies the time, in seconds,  that QLK will wait for an incoming packet
  783.   (if the timer is enabled).  The  initial  setting is 20.  The timeout used
  784.   is subject to Send-Init negotiation.
  785.  
  786.  
  787.  
  788.                                    Page 12
  789.  
  790.  
  791.  
  792.  
  793.   QL-KERMIT                                          Edition DRAFT, 4-May-87
  794.  
  795.  
  796.  
  797.  
  798.   RETRIES number
  799.  
  800.   Sets the number of times  that  QLK  will  retransmit  a  packet  when the
  801.   expected  reply  is  not  received succesfully.  This includes packet read
  802.   timeouts  (if  the timer is  enabled),  timeouts  forced  by  ^T,  packets
  803.   received with a bad checksum  or  unexpected  reception  of  a  previously
  804.   received  packet.   If  this  limit  is  exceeded, the transaction will be
  805.   aborted.   Note  that the retry limit applies  to  the  reception  of  one
  806.   particular packet, and not the total number of retries in a transaction.
  807.  
  808.   The initial setting is 5.
  809.  
  810.  
  811.  
  812.   SEND END-OF-LINE code
  813.  
  814.   Specifies the end-of-line character that QLK will terminate a packet with.
  815.   This is specified in decimal;  the  initial  setting  is  Carriage  Return
  816.   (ASCII  13).  The remarks under the corresponding RECEIVE option regarding
  817.   the specification of  this  parameter in the Send-Init exchange also apply
  818.   here.
  819.  
  820.  
  821.  
  822.   SEND MARKER code
  823.  
  824.   Specifies, in decimal, the character  that  QLK  will transmit to indicate
  825.   the start of a packet.  The initial setting is SOH (ASCII 1).
  826.  
  827.  
  828.  
  829.   SEND PACKET-LENGTH length
  830.  
  831.   Specifies the maximum packet length  that  QLK  will  send  to  the remote
  832.   system.  The initial setting is the maximum of 94.  A sensible  minimum is
  833.   about  30,  but  this is not enforced by QLK.  This length is  subject  to
  834.   Send-Init negotiation.
  835.  
  836.  
  837.  
  838.   SEND TIMEOUT time
  839.  
  840.   Specifies the time, in seconds,  that  QLK  will  ask the remote system to
  841.   wait for an incoming packet, if it has a  timeout  facility.   The initial
  842.   setting is 20.
  843.  
  844.  
  845.  
  846.   TAKE-ABORT OFF,ON
  847.  
  848.   Controls whether TAKE files are abandoned when a command or transfer error
  849.   occurs.   If it is set to ON, the entire stack of TAKE files (i.e. the one
  850.   containing the  command  causing the error, as well as any that called it)
  851.   is abandoned and control  returns  to the keyboard prompt.  If set to OFF,
  852.  
  853.  
  854.                                    Page 13
  855.  
  856.  
  857.  
  858.  
  859.   QL-KERMIT                                          Edition DRAFT, 4-May-87
  860.  
  861.  
  862.   the error is ignored and execution  continues with the next command in the
  863.   TAKE file.  See the description of the TAKE command for more information.
  864.  
  865.   The initial setting is ON.
  866.  
  867.  
  868.  
  869.   TAKE-ECHO OFF,ON
  870.  
  871.   Controls whether command lines read from a  TAKE  file  are  echoed on the
  872.   screen  before execution.  If set to ON, they are listed with  a  "prompt"
  873.   identifying their  source and the current level of TAKE file nesting.  See
  874.   the TAKE command for more information.
  875.  
  876.   The initial setting is ON.
  877.  
  878.  
  879.  
  880.   TIMER OFF,ON
  881.  
  882.   Controls  whether  QLK  will  time out if a packet being waited for is not
  883.   received within the specified or negotiated time.  If set to OFF, QLK will
  884.   never time out and will  wait  indefinitely  if  a  packet does not arrive
  885.   (execpt that a timeout can be simulated with ^T).  If  set  to ON, timeout
  886.   processing will be performed normally.  The initial setting is ON.
  887.  
  888.  
  889.  
  890.  
  891.  
  892.  
  893.  
  894.  
  895.  
  896.  
  897.  
  898.  
  899.  
  900.  
  901.  
  902.  
  903.  
  904.  
  905.  
  906.  
  907.  
  908.  
  909.  
  910.  
  911.  
  912.  
  913.  
  914.  
  915.  
  916.  
  917.  
  918.  
  919.  
  920.                                    Page 14
  921.  
  922.  
  923.  
  924.  
  925.   QL-KERMIT                                          Edition DRAFT, 4-May-87
  926.  
  927.  
  928.  
  929.  
  930.  
  931.   6.  Notes on Send-Init parameter negotiation
  932.   --------------------------------------------
  933.  
  934.  
  935.   Certain parameters relating to the  file  transfer  that  is just about to
  936.   start  are  negotiated  between  the  two  sides in the  Send-Init  packet
  937.   exchange.   The algorithms QLK uses to derive  the  parameters  eventually
  938.   used in  the  file  transfer  are  described  here.   Note that "send" and
  939.   "receive"  here  refer  to  packets and not necessarily file  data.   Also
  940.   observe that some Kermit implementations  may  well  ignore the parameters
  941.   requested in the exchange, and either impose their  own  defaults  or some
  942.   compromise (as QLK does in some cases).
  943.  
  944.  
  945.  
  946.   (a)  Packet length
  947.  
  948.   QLK asks the remote system  to  send it packets no longer than the RECEIVE
  949.   PACKET-LENGTH setting, but will not fail if  for  some reason this request
  950.   is ignored.  Initially the packet length that it sends  is  that specified
  951.   by SEND PACKET-LENGTH; however if the remote system requests it to  send a
  952.   shorter packet, QLK will do that.  The eventual length used is the minimum
  953.   of the QLK setting and the remote request.
  954.  
  955.  
  956.  
  957.   (b)  Timeout
  958.  
  959.   QLK requests the remote system to time out (if it is capable  of doing so)
  960.   after the SEND TIMEOUT interval.  The initial timeout QLK uses is that set
  961.   by  RECEIVE  TIMEOUT; if the remote system specifies that QLK should use a
  962.   longer interval, it  will do so.  The eventual receive timeout used is the
  963.   maximum of the QLK setting and the remote request.
  964.  
  965.  
  966.  
  967.   (c)  Padding amount
  968.  
  969.   QLK does not require  padding  on  receive,  and  always specifies that no
  970.   padding should be sent to it.  Initially the amount  of  padding sent, and
  971.   the  character  used, are those set by PADDING; after the exchange,  if  a
  972.   greater number of  padding  characters  are  requested by the remote, that
  973.   number will be used.  The padding character  sent is always that specified
  974.   in the packet.
  975.  
  976.  
  977.  
  978.   (d)  End of line
  979.  
  980.   QLK  sends  the  first  packets  with  the  terminator   defined  by  SEND
  981.   END-OF-LINE, and then uses that requested by the  remote,  if  given.  QLK
  982.   does  not  require a terminator on incoming packets, but requests that set
  983.   by RECEIVE END-OF-LINE for completeness.
  984.  
  985.  
  986.                                    Page 15
  987.  
  988.  
  989.  
  990.  
  991.   QL-KERMIT                                          Edition DRAFT, 4-May-87
  992.  
  993.  
  994.  
  995.  
  996.  
  997.   (e)  Control quote
  998.  
  999.   The quote characters are not  used  until  he  Send-Init exchange is over,
  1000.   therefore  no  initial  setting is relevant.  QLK will inform  the  remote
  1001.   system that it will  send  data  using the character set by CONTROL-QUOTE;
  1002.   for receiving data it will use the quote character the remote specifies.
  1003.  
  1004.  
  1005.  
  1006.   (f) 8th-bit quote
  1007.  
  1008.   The current parity setting interacts  with  8th-bit  quote  negotiation as
  1009.   follows:
  1010.  
  1011.   If the parity setting is  NONE,  QLK need not do 8th-bit quoting, but will
  1012.   do so if the remote requires it.   In  this case, the quote character used
  1013.   is that specified by the remote, if it requires  8th-bit  prefixing  to be
  1014.   done.  If the remote need not do 8th-bit quoting either, then it  will not
  1015.   be  done.   The  character  specified  by EIGHT-BIT-QUOTE is irrelevant in
  1016.   this case.
  1017.  
  1018.   If the parity setting is one  which  permits  only 7-bit transmission, QLK
  1019.   will specify that it needs  to  do 8th-bit prefixing.  The quote character
  1020.   used will depend on which side initiates the exchange:
  1021.  
  1022.   If QLK sends the Send-Init packet, it will request that 8th-bit quoting is
  1023.   to be done using the character currently  set.  If the remote replies that
  1024.   it  will  use  the  same character, or it  will  optionally  do  so,  that
  1025.   character will be used for the transaction.
  1026.  
  1027.   In the case where QLK reads the Send-Init packet and acknowledges with its
  1028.   own parameters, if the remote has specified optional quoting then QLK will
  1029.   indicate that it must use  the  set  character.  If the remote specifies a
  1030.   quote character, thus indicating that it must prefix,  then  QLK  will use
  1031.   the character specified too.
  1032.  
  1033.  
  1034.  
  1035.   (g)  Other parameters
  1036.  
  1037.   QLK supports only checksum type 1, and assumes that the remote will agree.
  1038.   Repeat  count prefixing is not supported; nor are any exotic features such
  1039.   as file attributes, sliding windows or long packets.
  1040.  
  1041.  
  1042.   Note  that, if any parameters are not specified by the remote system (i.e.
  1043.   if it sends a short  parameter  packet),  QLK  will  continue  to  use the
  1044.   initial settings as they were at the start of the transaction.
  1045.  
  1046.  
  1047.  
  1048.  
  1049.  
  1050.  
  1051.  
  1052.                                    Page 16
  1053.  
  1054.  
  1055.  
  1056.  
  1057.   QL-KERMIT                                          Edition DRAFT, 4-May-87
  1058.  
  1059.  
  1060.  
  1061.  
  1062.  
  1063.   7.  Building QL-Kermit from source
  1064.   ----------------------------------
  1065.  
  1066.  
  1067.   To  build  QLK  from  source  requires  a little more than the standard QL
  1068.   configuration.  The Metacomco C Development Kit is essential, and at least
  1069.   one disc drive.  Expansion memory, if available,  would  greatly  speed up
  1070.   compilation; the maximum of 640K is preferred.
  1071.  
  1072.   The source files required are:
  1073.  
  1074.          main_c                  Main program and global data
  1075.          cmd_c                   Command processor
  1076.          fns_c                   Protocol support routines
  1077.          swit_c                  Protocol state switcher
  1078.          us1_c                   User commands
  1079.          us2_c                   The SET command
  1080.          term_c                  Terminal emulation
  1081.          sbr_c                   General subroutines
  1082.  
  1083.          ker_h                   General definitions
  1084.          cmd_h                   Command processor definitions
  1085.          usr_h                   User command and option definitions
  1086.  
  1087.          kermit_link             Linker control file
  1088.  
  1089.   Also  required,  as  supplied  with  the  C  Development Kit, are stdio_h,
  1090.   ctype_h, qdos_h and fcntl_h.
  1091.  
  1092.   The device names in the  #include  statements and linker control file have
  1093.   been set assuming that a full configuration  of 640K of memory and 2 discs
  1094.   is available and that the source and object  files  will  be  stored  on a
  1095.   RAMdisc, which must be of at least 450 sectors.  The final executable file
  1096.   is best written to disc, since if the RAMdisc is made big enough  to  hold
  1097.   this  as  well  the  C  compiler will be a very tight fit in the remaining
  1098.   memory.  The system include files are assumed to be on flp1_.
  1099.  
  1100.   For other configurations, the files  will have to be edited to reflect the
  1101.   disposition of source and system files.
  1102.  
  1103.   Whatever the configuration, when all  the  source files have been compiled
  1104.   they can be linked with the Linker command line:
  1105.  
  1106.          -with DEV1_kermit -nolist -prog DEV2_kermit_exec
  1107.  
  1108.   where DEV1 is the device that kermit_link resides  on,  and  DEV2  is  the
  1109.   device that the executable file is to be written to.  Note that the Linker
  1110.   control file may also have  to  be  edited  to reflect the device that the
  1111.   object files are held on.
  1112.  
  1113.   After this has been done, Kermit can be run using EXEC (or EXEC_W).
  1114.  
  1115.  
  1116.  
  1117.  
  1118.                                    Page 17
  1119.  
  1120.  
  1121.  
  1122.  
  1123.   QL-KERMIT                                          Edition DRAFT, 4-May-87
  1124.  
  1125.  
  1126.  
  1127.  
  1128.  
  1129.   8.  Acknowledgments
  1130.   -------------------
  1131.  
  1132.  
  1133.   Thanks are due to:
  1134.  
  1135.   Robert Coughlan, lately of Liverpool  University, for writing the original
  1136.   version of QL-Kermit and making it available via Lancaster.
  1137.  
  1138.   The Lancaster Kermit Distribution Service,  and  especially  Alan Phillips
  1139.   whose  excellent  implementation of BBC-Kermit inspired me to  provide  it
  1140.   with something to talk to.
  1141.  
  1142.   David Gordon; for programming help,  QL  advice  and the loan of a machine
  1143.   and supporting bits.
  1144.  
  1145.   The writers of the original  C-Kermit,  from  which many of the algorithms
  1146.   used  in  QLK are taken;  also  the  original  developers  of  the  Kermit
  1147.   protocol.
  1148.  
  1149.   Sir Clive Sinclair; for taking  a  great  CPU,  building  a set of totally
  1150.   inadequate  hardware  around  it and  making  the  result  available  very
  1151.   cheaply.
  1152.