home *** CD-ROM | disk | FTP | other *** search
/ Between Heaven & Hell 2 / BetweenHeavenHell.cdr / 300 / 256 / msxsys.doc < prev    next >
Text File  |  1984-07-28  |  14KB  |  387 lines
  1.  
  2.                SPECIFICATION FOR KERMIT SYSTEM-DEPENDENT MODULES
  3.  
  4.                       by Jeff Damens, Columbia University
  5.  
  6. All the system-independent global data structures used in Kermit-MS are defined
  7. in the file MSDEFS.H.
  8.  
  9. The routine MSXxxx.ASM contains system-dependent support for system xxx, except
  10. for terminal emulation, which is in MSXxxx.ASM, described below.
  11.  
  12. The  routines  in the MSX module may change any registers but the stack pointer
  13. and segment registers, unless otherwise noted.  A routine that  returns  via  a
  14. RET  instruction is said to return normally; a routine that skip returns is one
  15. that returns to three bytes past the normal return address.
  16.  
  17. Global variables that must be defined in the system-dependent module:
  18.  
  19. XOFSNT          byte.  This should be set to a non-zero value if we  are  doing
  20.                 flow  control  and  have  sent  an XOFF character to the remote
  21.                 host, zero otherwise.
  22.  
  23. MACHNAM         byte.  A  $-terminated  string  identifying  the  machine  this
  24.                 version of Kermit is for; it is printed when Kermit starts up.
  25.  
  26. SETKTAB         byte.  A keyword table associating terminal key names to 16-bit
  27.                 scan  code  values, used in the set key command.  If the kermit
  28.                 version can accept arbitrary decimal values as scan codes,  the
  29.                 word "SCAN" should appear in the table with a scan value of -1.
  30.                 If  key  redefinition is not implemented, the first byte of the
  31.                 table should be a zero.
  32.  
  33. SETKHLP         byte.  A $-terminated string to be printed when ? is  typed  in
  34.                 the  SET KEY command.  This is usually simply a list of the key
  35.                 names in  SETKTAB.    SETKHLP  must  be  defined  even  if  key
  36.                 redefinition  is not implemented, to satisfy the linker; if key
  37.                 redefinition  is  not  implemented,  SETKHLP  will   never   be
  38.                 displayed.
  39.  
  40. COUNT           word.   The number of characters in the serial input buffer, if
  41.                 known.  This is how Kermit knows to send an XON if  the  serial
  42.                 handler  has  sent an XOFF.  If the number of characters in the
  43.                 buffer isn't known, COUNT should be 0.
  44.  
  45. These are the required entry points for the system dependent  dependent  module
  46. MSXxxx.ASM.
  47.  
  48. SERINI
  49.  
  50. Parameters      None.
  51.  
  52. Returns         Normally, no return value.
  53.  
  54. Description     Perform  any initialization that must be done before the serial
  55.                 port can  be  used,  including  setting  baud  rate,  interrupt
  56.                 vectors,  etc.  Parity and baud rate should be set according to
  57.                 the values in the PORTINFO structure.   The  external  variable
  58.                 PORTVAL  points to the PORTINFO structure for the current port.
  59.                 Calling SERINI more than once without an  intervening  call  to
  60.                 SERRST should have no effect.
  61.  
  62.  
  63. SERRST
  64.  
  65. Parameters      None.
  66.  
  67. Returns         Normally, no return value.
  68.  
  69. Description     Undoes  any  initialization done by SERINI, including resetting
  70.                 the serial port, restoring any  interrupt  vectors  changed  by
  71.                 SERINI,   etc.     Calling  this  more  than  once  without  an
  72.                 intervening call to SERINI should be harmless.
  73.  
  74.  
  75. CLRBUF
  76.  
  77. Parameters      None.
  78.  
  79. Returns         Normally, no return value.
  80.  
  81. Description     Remove and discard from the  serial  port's  input  buffer  any
  82.                 characters  sent by the remote host that have not yet been read
  83.                 by Kermit, and set COUNT to 0.  This  is  used  before  a  file
  84.                 transfer  to flush NAK's that accumulate in the buffer when the
  85.                 remote host is in server mode.
  86.  
  87.  
  88. OUTCHR
  89.  
  90. Parameters      A character in AH.
  91.  
  92. Returns         Skip returns if the character  has  been  transmitted;  returns
  93.                 normally  if  the character can not be transmitted because of a
  94.                 hardware error.
  95.  
  96. Description     Sends the character in AH out  the  currently  selected  serial
  97.                 port.    OUTCHR  can  assume  that SERINI will have been called
  98.                 previously. OUTCHR should call the external  routine  DOPAR  to
  99.                 set  the parity of the character if the communications hardware
  100.                 doesn't automatically set  parity.    Flow  control  should  be
  101.                 honored;  the external variable PORTVAL contains a pointer to a
  102.                 PORTINFO structure (as  defined  in  MSDEFS.H)  containing  the
  103.                 current flow control definitions.
  104.  
  105.  
  106. COMS
  107.  
  108. Parameters      None.
  109.  
  110. Returns         Normally   if  a  parse  error  is  encountered,  skip  returns
  111.                 otherwise.
  112.  
  113. Description     Called by the SET PORT command.  On  a  machine  with  multiple
  114.                 serial  ports,  COMS  should  parse for the name or number of a
  115.                 serial port and make that the port used by succeeding calls  to
  116.                 SERINI, PRTCHR, OUTCHR, and SERRST.  It should set the external
  117.                 variable   PORTVAL  to  point  to  one  of  the  external  port
  118.                 structures  PORT1  or  PORT2,  and  set  COMFLG  in  the  FLAGS
  119.                 structure to 1 for port one, 0 for port 2.  For implementations
  120.                 that  use  only one serial port, COMS should print a message to
  121.                 that effect and skip return.
  122.  
  123.  
  124. VTS
  125.  
  126. Parameters      None.
  127.  
  128. Returns         Normally  if  a  parse  error  is  encountered,  skip   returns
  129.                 otherwise.
  130.  
  131. Description     Parses  for  an  ON  or  OFF,  sets HEATH-19 emulation while in
  132.                 terminal emulation appropriately.  The VTFLG field of the FLAGS
  133.                 structure should be set non-zero if HEATH-29 emulation  is  on,
  134.                 zero  otherwise.  If HEATH-19 emulation is not done, VTS should
  135.                 print a message and skip return.
  136.  
  137.  
  138. DODEL
  139.  
  140. Parameters      None.
  141.  
  142. Returns         Normally, no return value.
  143.  
  144. Description     Erases the character immediately to the left of the cursor from
  145.                 the screen, then backs up the cursor.
  146.  
  147.  
  148. CTLU
  149.  
  150. Parameters      None.
  151.  
  152. Returns         Normally, no return value.
  153.  
  154. Description     Move the cursor to the left margin, then clear the line.
  155.  
  156.  
  157. CMBLNK
  158.  
  159. Parameters      None.
  160.  
  161. Returns         Normally, no return value.
  162.  
  163. Description     Clears the screen and homes the cursor.
  164.  
  165.  
  166. LOCATE
  167.  
  168. Parameters      None.
  169.  
  170. Returns         Normally, no return value.
  171.  
  172. Description     Homes the cursor.
  173.  
  174.  
  175. LCLINI
  176.  
  177. Parameters      None.
  178.  
  179. Returns         Normally, no return value.
  180.  
  181. Description     Performs any system-dependent initialization required  by  this
  182.                 implementation.
  183.  
  184.  
  185. PRTCHR
  186.  
  187. Parameters      None.
  188.  
  189. Returns         Normally,  with  the next character from the currently selected
  190.                 serial port in AL.  Skip returns if no character is available.
  191.  
  192. Description     Reads the next character from the current serial port.   PRTCHR
  193.                 can assume SERINI has been called previously, and should handle
  194.                 flow control correctly.
  195.  
  196.  
  197. DOBAUD
  198.  
  199. Parameters      None.
  200.  
  201. Returns         Normally, no return value.
  202.  
  203. Description     Sets  the baud rate for the current port.  The baud rate should
  204.                 be obtained from the BAUD  field  of  the  PORTINFO  structure,
  205.                 pointed to by the external variable PORTVAL.
  206.  
  207.  
  208. CLEARL
  209.  
  210. Parameters      None.
  211.  
  212. Returns         Normally, no return value.
  213.  
  214. Description     Clears from the cursor to the end of the current line.
  215.  
  216.  
  217. DODISK
  218.  
  219. Parameters      None.
  220.  
  221. Returns         Normally, no return value.
  222.  
  223. Description     Sets  the external variable DRIVES to the number of disk drives
  224.                 attached to the machine.
  225.  
  226.  
  227. GETBAUD
  228.  
  229. Parameters      None.
  230.  
  231. Returns         Normally, no return value.
  232.  
  233. Description     Store current baud rate of the currently selected port  in  the
  234.                 BAUD  field of the current PORTINFO structure, which is pointed
  235.                 to by PORTVAL.  If the baud rate is to default to a  particular
  236.                 value,  this  routine  can store that value into the BAUD field
  237.                 instead.
  238.  
  239.  
  240. BEEP
  241.  
  242. Parameters      None.
  243.  
  244. Returns         Normally, no return value.
  245.  
  246. Description     Rings the terminal bell.
  247.  
  248.  
  249. PUTHLP
  250.  
  251. Parameters      A pointer to a string in AX.
  252.  
  253. Returns         Normally, no return value.
  254.  
  255. Description     Writes the null-terminated string given in AX to the  terminal.
  256.                 This  is used to display help and status messages.  The IBM and
  257.                 Rainbow versions write the string in a reverse video box.
  258.  
  259.  
  260. PUTMOD
  261.  
  262. Parameters      A pointer to a string in AX.
  263.  
  264. Returns         Normally, no return value.
  265.  
  266. Description     Writes the null-terminated string given in AX to the last  line
  267.                 of the screen, in inverse video if possible.
  268.  
  269.  
  270. CLRMOD
  271.  
  272. Parameters      None.
  273.  
  274. Returns         Normally, no return value.
  275.  
  276. Description     Clears the line written by PUTMOD.
  277.  
  278.  
  279. POSCUR
  280.  
  281. Parameters      Row in DH, column in DL.
  282.  
  283. Returns         Normally, no return value.
  284.  
  285. Description     Positions  the  cursor to the row and column given in DX.  Rows
  286.                 and columns both originate at 0 (not 1!).
  287.  
  288.  
  289. SENDBR
  290.  
  291. Parameters      None.
  292.  
  293. Returns         Normally, no return value.
  294.  
  295. Description     Send a break to the current serial port.
  296.  
  297.  
  298. SHOWKEY
  299.  
  300. Parameters      Pointer to a terminal argument block in AX (see TERM below).
  301.  
  302. Returns         Normally, with a string pointer in AX and  the  length  of  the
  303.                 string in CX.
  304.  
  305. Description     Called  by the SHOW KEY command.  Reads a key from the terminal
  306.                 and  returns  a  string   containing   implementation-dependent
  307.                 information  about  the  key.  In  the  usual  case, the string
  308.                 contains the key's (machine-dependent) scan code, and the key's
  309.                 definition (if any) from the  terminal  argument  block.    The
  310.                 length  of  the  returned string should be returned in CX.  The
  311.                 string may contain any characters; unprintable characters  will
  312.                 be  quoted  when  the string is printed.  If the implementation
  313.                 does not support key redefinition, SHOWKEY may return a  static
  314.                 string saying so.
  315.  
  316.  
  317. TERM
  318.  
  319. Parameters      Pointer to terminal argument block in AX.
  320.  
  321. Returns         Normally, no return value.
  322.  
  323. Description     Do  terminal  emulation,  based  on  argument  block  described
  324.                 below...
  325.  
  326.  
  327.  
  328. The terminal emulator is  supplied  in  the  file  MSYxxx.ASM.    The  terminal
  329. argument block passed to the terminal emulator has the following fields:
  330.  
  331. FLGS            Byte containing flags.  Flags are:
  332.  
  333.                 SCRSAM (80H)    If   on,   the   terminal   emulator  shouldn't
  334.                                 re-display the screen when entered.
  335.  
  336.                 CAPT (40H)      Capture output.  If on, the routine  passed  in
  337.                                 field  CAPTR is called with each character sent
  338.                                 to the screen.
  339.  
  340.                 EMHEATH (20H)   Emulate a Heath-19 terminal if on.
  341.  
  342.                 HAVTT (10H)     A key redefinition table is present.
  343.  
  344.                 TRNCTL (08H)    Print control character X  as  ^X  (useful  for
  345.                                 debugging).
  346.  
  347.                 MODOFF (04H)    Do not display emulator mode line if on.
  348.  
  349.                 LCLECHO (01H)   Echo  keyboard  characters  on  the  screen  in
  350.                                 addition to sending them to the port.
  351.  
  352. PRT             Port to use for terminal emulation, used  only  in  mode  line.
  353.                 This is just a copy of COMFLG in FLAGS.
  354.  
  355. COLS            Number of columns on screen.
  356.  
  357. ROWS            Number of rows on screen.
  358.  
  359. CAPTR           Routine  to  call  to with each character sent to the screen if
  360.                 CAPT flag is on.  Characters are passed in AL.
  361.  
  362. BELLD           Bell divisor (used only on IBM).
  363.  
  364. KLEN            Number of keys in key redefinition table, if HAVTT flag is on.
  365.  
  366. KTAB            Address of key redefinition table.  The key redefinition  table
  367.                 is a table of KLEN 16-bit scan codes.  Each (machine dependent)
  368.                 scan code represents a key that is redefined.
  369.  
  370. KRPL            Address  of  key  replacement table.  The key replacement table
  371.                 parallels the key redefinition table given in KTAB.  Entries in
  372.                 the replacement table are  16-bit  pointers  to  redefinitions.
  373.                 Each  redefinition  has  a  one-byte  length,  followed  by the
  374.                 definition.
  375.  
  376. ESCC            Escape character (single byte).  When this character  is  typed
  377.                 to the emulator, it should return.
  378.  
  379. BAUDB           byte.    Bits  describing the baud rate so it can be printed on
  380.                 the mode line.  This is  a  copy  of  the  BAUD  field  in  the
  381.                 PORTINFO  structure.    Currently  used  only  on the IBM.  See
  382.                 MSDEFS.H for possible values.
  383.  
  384. PARITY          byte.  Current parity to print on the mode line.    This  is  a
  385.                 copy  of PARFLG in the PORTINFO structure.  Currently used only
  386.                 on the IBM.  See MSDEFS.H for possible values.
  387.