home *** CD-ROM | disk | FTP | other *** search
/ Columbia Kermit / kermit.zip / protocol / variable.txt < prev    next >
Text File  |  2020-01-01  |  9KB  |  212 lines
  1. NEW KERMIT CLIENT-SERVER OPERATIONS
  2.  
  3. DRAFT, Sat Jul 30 18:23:49 1994
  4.  
  5. A. REMOTE PWD
  6.  
  7. Command: REMOTE PWD
  8.  
  9.    This asks the server to display its current working directory.
  10.    Until now, there was no system-independent way to make this inquiry;
  11.    you had to give a REMOTE HOST command like "pwd", "show default", etc.
  12.  
  13.    This new command works consistently for all servers that support it.
  14.    Like most other REMOTE commands, however, there is no way to capture the
  15.    results, short of program- or system-dependent redirection methods (but
  16.    see item B).
  17.  
  18. Protocol:
  19.  
  20.    Packet type: G
  21.    Data field:  A (mnemonic: "Area"), nothing follows the A.
  22.  
  23. Server response: Long form (S X D* Z B) or short form (Data field of ACK)
  24. response giving the name of the current storage area (disk, device,
  25. directory, filemode, etc), encoded in the normal fashion, or an Error packet
  26. if it does not understand or cannot execute the command.
  27.  
  28. B. QUERYING AND SETTING OF VARIABLES
  29.  
  30. The Kermit book lists among the "Generic" commands to be sent to a Kermit
  31. server by the client the V command (page 265).  To date, this has never been
  32. implemented.
  33.  
  34. In the interest of tighter coupling between client and server, the following
  35. implementation is suggested, and has been done in C-Kermit.
  36.  
  37. We distinguish among three types of variables:
  38.  
  39.  1. Read-only Kermit variables, such as time, date, current directory,
  40.     program version number, OS name, etc.  For example, the \v(name) built-in
  41.     variables of MS-DOS Kermit and C-Kermit.  We will call these KERMIT
  42.     variables.
  43.  
  44.  2. Read-only System variables, such as the Environment Variables of UNIX,
  45.     DOS, and OS/2, or the Logical Names of VMS; for example, the \$(NAME)
  46.     variables of MS-DOS Kermit and C-Kermit.  These will be called SYSTEM
  47.     variables.
  48.  
  49.  3. Read-write Kermit variables such as \%a-z, \%1-9, and \&a-z[] global
  50.     variables, and macros used as long-named global variables in MS-DOS
  51.     Kermit and C-Kermit.  For want of a better term, these will be called
  52.     USER variables.
  53.  
  54. The command for querying variables would have to specify both the type and
  55. name of the variable:
  56.  
  57. REMOTE QUERY { KERMIT, SYSTEM, USER } <name>
  58.   Gets the value of the named remote variable and makes it available in the
  59.   local read-only Kermit variable, QUERY.  In C-Kermit and MS-DOS Kermit, this
  60.   variable would be called \v(query).  If the query succeeds, the REMOTE
  61.   QUERY command also succeeds, and the QUERY variable is set accordingly.
  62.   If the query fails, the command fails, and the QUERY variable is set to the
  63.   empty string.
  64.  
  65.   The <name> of a KERMIT or SYSTEM variable is given in an
  66.   implementation-independent format without special syntax, e.g. TIME, DATE,
  67.   VERSION, PATH, USER, etc, rather than (say) \v(time), \$(PATH).  However,
  68.   in most cases, case matters in system variables.  The <name> of a USER
  69.   variable is given in the syntax of the server, e.g. \%a.
  70.  
  71. The command for setting variables works only for read-write (USER)
  72. variables, and so the variable type is not needed:
  73.  
  74. REMOTE ASSIGN <name> [ <value> ]
  75.   Asks the server to assign the value to the named remote user variable.
  76.   The <name> is in the syntax of the Kermit server.  The word "assign" is
  77.   chosen instead of "set" because "set" is already used for something else
  78.   (e.g. "remote set window 4").  The choice of "assign" rather than "define"
  79.   implies, at least for C-Kermit and MS-DOS Kermit, that the <value> will be
  80.   fully evaluated LOCALLY before being sent to the Kermit server.  For
  81.   example, "remote assign \%a \v(time)" would assign the client's current
  82.   time to the server's \%a variable.
  83.  
  84. On the server end, for security, we must have:
  85.  
  86.   { ENABLE, DISABLE } { QUERY, ASSIGN }
  87.  
  88. By default, like all other ENABLE/DISABLE items, the initial state is
  89. ENABLEd.
  90.  
  91. The following read-only Kermit variables -- names and meanings -- are
  92. suggested:
  93.  
  94.   DATE       Current date, dd mmm yy format, e.g. "08 Feb 91"
  95.   DAY        Current day of week, 3-letter abbreviation, Sun, Mon, ... Sat
  96.   DIRECTORY  Current (working) directory
  97.   HOME       Home directory
  98.   HOST       Name of this system, e.g. network host name
  99.   NDATE      Current date, numeric yyyymmdd format, e.g. "19910208"
  100.   NDAY       Current day of week, numeric, 0=Sunday, ... 6=Saturday
  101.   NTIME      Numeric time of day, seconds since midnight, local time
  102.   PLATFORM   Specific machine and/or operating system name, e.g. Solaris
  103.   PROGRAM    Kermit program name, e.g. "C-Kermit", "MS-DOS_Kermit"
  104.   SPACE      Number of free bytes available on current storage device
  105.   STATUS     0 if the most recent operation was successful, nonzero otherwise
  106.   SYSID      The Kermit code for the operating system (pp.275-278 of book)
  107.   SYSTEM     Generic operating system name, e.g. UNIX
  108.   TIME       Current time of day, hh:mm:ss format
  109.   TIMEZONE   Local timezone, 0-1439 (westward offset from GMT, in minutes)
  110.   VERSION    Numeric Kermit program version number
  111.  
  112. Most of these are already implemented in MS-DOS Kermit and C-Kermit.  
  113.  
  114. Protocol clarification:
  115.  
  116. The Data field of G packet contains a single-character function code
  117. followed by zero or more fields of the form:
  118.  
  119.   <len><data>
  120.  
  121. where <len> is a single character SP thru ~, indicating a length of 0 through
  122. 94, and <data> is that many characters of data.  This format prevents any
  123. field from being greater than 94 characters length.  However, the final <len>
  124. field is not, strictly speaking, necessary, since we don't need to know the
  125. length of the final <data> item -- it is simply "all the rest".  So it is now
  126. permissible for the FINAL field in the G packet, but no fields preceding it,
  127. to have a BLANK <len> indicator.  This means: all characters starting with the
  128. next one, through the end of the data field.  Of course, if the final field is
  129. 94 characters long or less, its length field can (and should) still be
  130. recorded in the normal way, so as to cause the least amount of disruption with
  131. existing Kermit programs.
  132.  
  133. Protocol:
  134.  
  135. 1. QUERY
  136.  
  137.    Packet type:  G
  138.    Data field:   V <len=1> Q <len=1> { G, K, S } <len> <name>
  139.    Where K = Kermit Variable; S = System Variable, G = User Variable
  140.  
  141. Examples: GV!Q!S$PATH
  142.           GV!Q!K$time
  143.           GV!Q!G#\%a
  144.  
  145. Server response:
  146.  
  147. If QUERY is disabled, the server responds with an Error packet stating
  148. "REMOTE QUERY disabled".  Otherwise:
  149.  
  150. A "short-form" response with the value of the variable in the data field of
  151. the ACK packet, encoded in the normal way, for example (in response to a query
  152. of the Kermit "time" variable):
  153.  
  154.   Y11:41:28
  155.  
  156. or a "long form" response (S X [ A ] D* Z B) with the value of the variable in
  157. the Data field(s) of the Data packet(s).
  158.  
  159. The short form response is optional but can be used if the entire text, after
  160. encoding, fits into the data field of an ACK packet.  NOTE: There is no reason
  161. why an ACK should not be a long-format packet, up to the maximum negotiated
  162. length in the client's direction.
  163.  
  164. If the variable does not exist or has no value, the null value (empty string)
  165. is returned.  If the server does understand this command, it responds with an
  166. Error packet.
  167.  
  168. The client, in turn, can treat the server response in the normal way, i.e.
  169. display it on the screen, or, more usefully, it can store in a variable, or
  170. both.  In MS-DOS Kermit and C-Kermit, the name of this variable should be
  171. \v(query).
  172.  
  173. Since there is nothing in the server response to indicate that this is query
  174. response, it is up to the client to set a flag when given a REMOTE QUERY
  175. command, to use it during the following protocol operation to store the
  176. resonse in the \v(query) variable, and to reset the flag upon next entry to
  177. the command parser.
  178.  
  179. 2. SET
  180.  
  181.    Packet type:  G
  182.    Data field:   V <len=1> S <len> <name> <len> <value>
  183.  
  184. Example: GV!S&myname$Olga
  185.  
  186. This requests the server to create the named variable, if necessary, and set
  187. its value to the one given, which can be null (in which case the length field
  188. for the value will indicate a zero length).
  189.  
  190. If ASSIGN is disabled, the server responds with an Error packet stating
  191. "REMOTE ASSIGN disabled".  Otherwise, the server responds with an ACK if
  192. successful, and Error packet on failure to set the variable.
  193.  
  194. Note that the final <len> field might be blank, which allows for the <value>
  195. field to be quite long.  After the protocol begins to execute and the server's
  196. maximum packet length is obtained, the client must check to see whether the G
  197. packet's length will be within the server's maximum.  If not, then instead of
  198. sending the G packet, it must send an Error packet saying "Command too long
  199. for server" and, if it is in local mode, also print this message on its own
  200. screen.  When receiving this Error packet, the server returns to server
  201. command wait, as it does whenever it gets an Error packet.
  202.  
  203. NOTE: It is unfortunate that application-level functionality is tied to
  204. transport-level concepts such as packet length, but it's far too late to do
  205. anything about it now.  A similar observation applies to file names, except
  206. that if a filename does not fit into a maximum-size F packet, it is simply
  207. truncated.  However, in this case, we don't want to truncate the value of a
  208. variable and report success when the operation did not have the intended
  209. effect.
  210.  
  211. (End)
  212.