NEW KERMIT CLIENT-SERVER OPERATIONS DRAFT, Sat Jul 30 18:23:49 1994 A. REMOTE PWD Command: REMOTE PWD This asks the server to display its current working directory. Until now, there was no system-independent way to make this inquiry; you had to give a REMOTE HOST command like "pwd", "show default", etc. This new command works consistently for all servers that support it. Like most other REMOTE commands, however, there is no way to capture the results, short of program- or system-dependent redirection methods (but see item B). Protocol: Packet type: G Data field: A (mnemonic: "Area"), nothing follows the A. Server response: Long form (S X D* Z B) or short form (Data field of ACK) response giving the name of the current storage area (disk, device, directory, filemode, etc), encoded in the normal fashion, or an Error packet if it does not understand or cannot execute the command. B. QUERYING AND SETTING OF VARIABLES The Kermit book lists among the "Generic" commands to be sent to a Kermit server by the client the V command (page 265). To date, this has never been implemented. In the interest of tighter coupling between client and server, the following implementation is suggested, and has been done in C-Kermit. We distinguish among three types of variables: 1. Read-only Kermit variables, such as time, date, current directory, program version number, OS name, etc. For example, the \v(name) built-in variables of MS-DOS Kermit and C-Kermit. We will call these KERMIT variables. 2. Read-only System variables, such as the Environment Variables of UNIX, DOS, and OS/2, or the Logical Names of VMS; for example, the \$(NAME) variables of MS-DOS Kermit and C-Kermit. These will be called SYSTEM variables. 3. Read-write Kermit variables such as \%a-z, \%1-9, and \&a-z[] global variables, and macros used as long-named global variables in MS-DOS Kermit and C-Kermit. For want of a better term, these will be called USER variables. The command for querying variables would have to specify both the type and name of the variable: REMOTE QUERY { KERMIT, SYSTEM, USER } Gets the value of the named remote variable and makes it available in the local read-only Kermit variable, QUERY. In C-Kermit and MS-DOS Kermit, this variable would be called \v(query). If the query succeeds, the REMOTE QUERY command also succeeds, and the QUERY variable is set accordingly. If the query fails, the command fails, and the QUERY variable is set to the empty string. The of a KERMIT or SYSTEM variable is given in an implementation-independent format without special syntax, e.g. TIME, DATE, VERSION, PATH, USER, etc, rather than (say) \v(time), \$(PATH). However, in most cases, case matters in system variables. The of a USER variable is given in the syntax of the server, e.g. \%a. The command for setting variables works only for read-write (USER) variables, and so the variable type is not needed: REMOTE ASSIGN [ ] Asks the server to assign the value to the named remote user variable. The is in the syntax of the Kermit server. The word "assign" is chosen instead of "set" because "set" is already used for something else (e.g. "remote set window 4"). The choice of "assign" rather than "define" implies, at least for C-Kermit and MS-DOS Kermit, that the will be fully evaluated LOCALLY before being sent to the Kermit server. For example, "remote assign \%a \v(time)" would assign the client's current time to the server's \%a variable. On the server end, for security, we must have: { ENABLE, DISABLE } { QUERY, ASSIGN } By default, like all other ENABLE/DISABLE items, the initial state is ENABLEd. The following read-only Kermit variables -- names and meanings -- are suggested: DATE Current date, dd mmm yy format, e.g. "08 Feb 91" DAY Current day of week, 3-letter abbreviation, Sun, Mon, ... Sat DIRECTORY Current (working) directory HOME Home directory HOST Name of this system, e.g. network host name NDATE Current date, numeric yyyymmdd format, e.g. "19910208" NDAY Current day of week, numeric, 0=Sunday, ... 6=Saturday NTIME Numeric time of day, seconds since midnight, local time PLATFORM Specific machine and/or operating system name, e.g. Solaris PROGRAM Kermit program name, e.g. "C-Kermit", "MS-DOS_Kermit" SPACE Number of free bytes available on current storage device STATUS 0 if the most recent operation was successful, nonzero otherwise SYSID The Kermit code for the operating system (pp.275-278 of book) SYSTEM Generic operating system name, e.g. UNIX TIME Current time of day, hh:mm:ss format TIMEZONE Local timezone, 0-1439 (westward offset from GMT, in minutes) VERSION Numeric Kermit program version number Most of these are already implemented in MS-DOS Kermit and C-Kermit. Protocol clarification: The Data field of G packet contains a single-character function code followed by zero or more fields of the form: where is a single character SP thru ~, indicating a length of 0 through 94, and is that many characters of data. This format prevents any field from being greater than 94 characters length. However, the final field is not, strictly speaking, necessary, since we don't need to know the length of the final item -- it is simply "all the rest". So it is now permissible for the FINAL field in the G packet, but no fields preceding it, to have a BLANK indicator. This means: all characters starting with the next one, through the end of the data field. Of course, if the final field is 94 characters long or less, its length field can (and should) still be recorded in the normal way, so as to cause the least amount of disruption with existing Kermit programs. Protocol: 1. QUERY Packet type: G Data field: V Q { G, K, S } Where K = Kermit Variable; S = System Variable, G = User Variable Examples: GV!Q!S$PATH GV!Q!K$time GV!Q!G#\%a Server response: If QUERY is disabled, the server responds with an Error packet stating "REMOTE QUERY disabled". Otherwise: A "short-form" response with the value of the variable in the data field of the ACK packet, encoded in the normal way, for example (in response to a query of the Kermit "time" variable): Y11:41:28 or a "long form" response (S X [ A ] D* Z B) with the value of the variable in the Data field(s) of the Data packet(s). The short form response is optional but can be used if the entire text, after encoding, fits into the data field of an ACK packet. NOTE: There is no reason why an ACK should not be a long-format packet, up to the maximum negotiated length in the client's direction. If the variable does not exist or has no value, the null value (empty string) is returned. If the server does understand this command, it responds with an Error packet. The client, in turn, can treat the server response in the normal way, i.e. display it on the screen, or, more usefully, it can store in a variable, or both. In MS-DOS Kermit and C-Kermit, the name of this variable should be \v(query). Since there is nothing in the server response to indicate that this is query response, it is up to the client to set a flag when given a REMOTE QUERY command, to use it during the following protocol operation to store the resonse in the \v(query) variable, and to reset the flag upon next entry to the command parser. 2. SET Packet type: G Data field: V S Example: GV!S&myname$Olga This requests the server to create the named variable, if necessary, and set its value to the one given, which can be null (in which case the length field for the value will indicate a zero length). If ASSIGN is disabled, the server responds with an Error packet stating "REMOTE ASSIGN disabled". Otherwise, the server responds with an ACK if successful, and Error packet on failure to set the variable. Note that the final field might be blank, which allows for the field to be quite long. After the protocol begins to execute and the server's maximum packet length is obtained, the client must check to see whether the G packet's length will be within the server's maximum. If not, then instead of sending the G packet, it must send an Error packet saying "Command too long for server" and, if it is in local mode, also print this message on its own screen. When receiving this Error packet, the server returns to server command wait, as it does whenever it gets an Error packet. NOTE: It is unfortunate that application-level functionality is tied to transport-level concepts such as packet length, but it's far too late to do anything about it now. A similar observation applies to file names, except that if a filename does not fit into a maximum-size F packet, it is simply truncated. However, in this case, we don't want to truncate the value of a variable and report success when the operation did not have the intended effect. (End)