home
***
CD-ROM
|
disk
|
FTP
|
other
***
search
/
Columbia Kermit
/
kermit.zip
/
archives
/
protocol.tar.gz
/
protocol.tar
/
variable.txt
< prev
next >
Wrap
Text File
|
1994-07-30
|
9KB
|
212 lines
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 } <name>
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 <name> 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 <name> 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 <name> [ <value> ]
Asks the server to assign the value to the named remote user variable.
The <name> 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 <value> 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:
<len><data>
where <len> is a single character SP thru ~, indicating a length of 0 through
94, and <data> is that many characters of data. This format prevents any
field from being greater than 94 characters length. However, the final <len>
field is not, strictly speaking, necessary, since we don't need to know the
length of the final <data> 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 <len> 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 <len=1> Q <len=1> { G, K, S } <len> <name>
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 <len=1> S <len> <name> <len> <value>
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 <len> field might be blank, which allows for the <value>
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)