通讯/手机编程

开发平台：

Windows_Unix

ckermit2.txt：源码内容

where "xxx" is the connection type, e.g.
SET FLOW /REMOTE NONE
SET FLOW /DIRECT RTS/CTS
If you leave out the switch, SET FLOW works as before, choosing the flow
control method to be used on the current connection:
SET FLOW XON/XOFF
Thus, whenever you make a connection with SET PORT, SET LINE, DIAL, SET HOST,
TELNET, RLOGIN, etc, an appropriate form of flow control is selected
automatically. You can override the automatic selection with a subsequent
SET FLOW command, such as SET FLOW NONE (no switch included).
The flow control is changed automatically too when you give a SET MODEM TYPE
command. For example, suppose your operating system (say Linux) supports
hardware flow control (RTS/CTS). Now suppose you give the following
commands:
set line /dev/ttyS2 ; Automatically sets flow to NONE
set modem type usr ; Automatically sets flow to RTS/CTS
set modem type rolm ; Doesn't support RTS/CTS so now flow is XON/XOFF
IMPORTANT: This new feature tends to make the order of SET LINE/HOST and
SET FLOW commands matter, where it didn't before. For example, in VMS:
SET FLOW KEEP
SET LINE TTA0:
the SET LINE undoes the SET FLOW KEEP command; the sequence now must be:
SET FLOW /DIRECT KEEP
SET LINE TTA0:
or:
SET LINE TTA0:
SET FLOW KEEP
2.14. Trapping Connection Establishment and Loss
If you define a macro called ON_OPEN, it is executed any time that a SET LINE,
SET PORT, SET HOST, TELNET, RLOGIN or similar command succeeds in opening a
connection. The argument is the host or device name (as shown by SHOW
COMMUNICATIONS, and the same as v(line)). This macro can be used for all
sorts of things, like automatically setting connection- or host-specific
parameters when the connection is opened. Example:
def ON_OPEN {
switch %1 {
:abccorp.com, set reliable off, break
:xyzcorp.com, set receive packet-length 1000, break
etc etc...
}
}
If you define a macro called ON_CLOSE, it will be executed any time that
a SET LINE, SET PORT, SET HOST, TELNET, RLOGIN or any other kind of connection
that C-Kermit has made is closed, either by the remote or by a local CLOSE,
HANGUP, or EXIT command or other local action, such as when a new connection
is opened before an old one was explicitly closed.
As soon as C-Kermit notices the connection has been closed, the ON_CLOSE macro
is invoked at (a) the top of the command parsing loop, or (b) when a
connection is closed implicitly by a command such as SET LINE that closes any
open connection prior to making a new connection, or (c) when C-Kermit closes
an open connection in the act of exiting.
The ON_CLOSE macro was inspired by the neverending quest to unite Kermit and
SSH (*). In this case using the "tunnel" mechanism:
def TUNNEL { ; %1 = host to tunnel to
local %p
if not def %1 stop 1
assign tunnelhost %1 ; Make global copy
undef on_close
set macro error off
close connection ; Ignore any error
open !read tunnel start %1
read %p ; Get port number
if fail stop 1 Tunnel failure: %1
close read
if fail stop 1 Tunnel failure: %1 ; See Section 4.2.8.1
assign on_close { ; Set up close handler
echo Closing tunnel: m(tunnelhost)
!tunnel stop m(tunnelhost)
undef on_close
}
set host localhost:%p /telnet
if success end 0
undef on_close
stop 1 Connection failure: %1
}
In this case, when the connection stops, we also need to shut down the tunnel,
even if it is at a later time after TUNNEL has finished executing. This way
we can escape back, reconnect, transfer files, and so on until the connection
is broken by logging out from the remote, or by explicitly closing it, or by
EXITing from C-Kermit, at which time the tunnel is shut down.
When the connection is closed, no matter how, the ON_CLOSE macro executes
and then undefines (destroys) itself, since we don't want to be closing
tunnels in the future when we close subsequent connections.
Other such tricks can be imagined, including ending ON_CLOSE with a STOP
command to force the command stack to be peeled all the way back to the top,
for example in a deeply nested script that depends on the connection being
open:
def on_close { stop 1 CONNECTION LOST }
When C-Kermit invokes the ON_CLOSE macro, it supplies one argument (%1):
the reason the connection was closed as a number, one of the following:
2 - Fatal failure to negotiate a required item on a network connection.
1 - Closed by C-Kermit command.
0 - All others (normally closed by remote).
which may be used for any purpose; for example, to add a comment to the
connection log:
def on_close {
local %m
if not open cx end 0
switch %1 {
:0, .%m = Closed by remote, break
:1, .%m = Closed by me, break
:2, .%m = Network protocol negotiation failure, break
}
if def %m writeln cx {# %m}
}
(*) SSH can not be included in C-Kermit due to licensing, patent, and
USA export law restrictions. Furthermore, the 'ssh' client that is
distributed for UNIX can not be run by C-Kermit's PIPE command because
it does not use standard i/o.
2.15. Contacting Web Servers with the HTTP Command
C-Kermit 7.0 (at this writing, the UNIX version only) supports direct contact
and interaction with Web servers via HTTP 1.0 protocol. To make a connection,
use Kermit's normal method for making a TCP/IP connection, but specify the
HTTP port:
SET HOST <host> http [ <switches> ]
where <host> is the IP hostname or address, and http is the name of the
TCP port for the Web server. Relevant switches include:
/RAW
Treat the connection as a transparent binary pipe. This switch may be
required if a port other than 'http' is used.
/SSL
Make an secure private connection with SSL (only if SSL support is included
in your version of Kermit). In this case the port name might need to be
https rather than http, e.g. "set host secureserver.xyxcorp.com https /ssl".
/TLS
Make an secure private connection with TLS (only if TLS support is included
in your version of Kermit). In this case the port name would be https
rather than http.
Then you can issue an HTTP command. In most cases, the server closes the
connection when the command is complete. Example:
SET HOST www.columbia.edu http
IF FAIL EXIT 1 Can't contact server
HTTP GET kermit/index.html
At this point the connection is closed, since that's how HTTP 1.0 works. If
you want to perform additional operations, you must establish a new connection
with another SET HOST command.
The HTTP command acts as a client to the Web server, except instead of
displaying the results like a Web browser would, it stores them. Any HTTP
command can (but need not) include any or all of the following switches:
/AGENT:<user-agent>
Identifies the client to the server; "C-Kermit" or "Kermit-95"
by default.
/HEADER:<header-line>
Used for specifying any optional headers. A list of headers is provided
using braces for grouping:
/HEADER:{{<tag>:<value>}{<tag>:<value>}...}
For a listing of valid <tag> value and <value> formats see RFC 1945:
"Hypertext Transfer Protocol -- HTTP/1.0". A maximum of eight headers
may be specified.
/USER:<name>
In case a page requires a username for access.
/PASSWORD:<password>
In case a page requires a password for access.
/ARRAY:<arrayname>
Tells Kermit to store the response headers in the given array, one line per
element. The array need not be declared in advance. Example:
http /array:c get kermit/index.html
show array c
Dimension = 9
1. Date: Fri, 26 Nov 1999 23:12:22 GMT
2. Server: Apache/1.3.4 (Unix)
3. Last-Modified: Mon, 06 Sep 1999 22:35:58 GMT
4. ETag: "bc049-f72-37d441ce"
5. Accept-Ranges: bytes
6. Content-Length: 3954
7. Connection: close
8. Content-Type: text/html
As you can see, the header lines are like MIME e-mail header lines:
identifier, colon, value. The /ARRAY switch is the only method available
to a script to process the server responses for a POST or PUT command.
The HTTP commands are:
HTTP [ <switches> ] GET <remote-filename> [ <local-filename> ]
Retrieves the named file. If a <local-filename> is given, the file is
stored locally under that name; otherwise it is stored with its own name.
HTTP [ <switches> ] HEAD <remote-filename> <local-filename>
Like GET except without actually getting the file; instead it gets only
the headers, storing them into the given file, whose name must be given,
one line per header item, as shown above in the /ARRAY: switch description.
HTTP [ <switches> ] INDEX <remote-directory> [ <local-filename> ]
Retrieves the file listing for the given server directory.
NOTE: This command is not supported by most Web servers.
HTTP [ <switches> ] POST [ /MIME-TYPE:<type> ] <local-file> <remote-file>
Used to send a response as if it were sent from a form. The data to be
posted must be read from a file.
HTTP [ <switches> ] PUT [ /MIME-TYPE:<type> ] <local-file> <remote-file>
Uploads a local file to a server file.
HTTP [ <switches> ] DELETE <remote-filename>
Instructs the server to delete the specified filename.
(3) TERMINAL CONNECTION
3.1. CONNECT Command Switches
The following switches (see section 1.5) were added to the CONNECT command
in 7.0:
/QUIETLY
Don't print the "Connecting to..." or "Back at..." messages.
CQ is an invisible command synonym for CONNECT /QUIETLY.
/TRIGGER:string
Specify a trigger or triggers (Section 3.2) effective for this CONNECT
command only, temporarily overriding any current SET TERMINAL TRIGGER
values (Section 3.2).
Note: Other switches might also be available; type "connect ?" for a list,
"help connect" for a description of each.
3.2. Triggers
Triggers were added for UNIX, VMS, AOS/VS, and K95 in C-Kermit 7.0.
SET TERMINAL TRIGGER string
Tells C-Kermit to look for the given string during all subsequent CONNECT
sessions, and if seen, to return to command mode automatically, as if you
had escaped back manually. If the string includes any spaces, you must
enclose it in braces. Example:
SET TERMINAL TRIGGER {NO CARRIER}
Comparisons are made after character-set translation.
If a string is to include a literal brace character, precede it with a
backslash:
; My modem always makes this noise when the connection is lost:
SET TERMINAL TRIGGER |||ppp{{{{UUUUUUU
If you want Kermit to look for more than one string simultaneously, use the
following syntax:
SET TERMINAL TRIGGER {{string1}{string2}...{stringn}}
In this case, C-Kermit will return to command mode automatically if any of
the given strings is encountered. Up to 8 strings may be specified.
If the most recent return to command mode was caused by a trigger, the new
variable, v(trigger), shows the trigger value; otherwise v(trigger) is
empty.
The SHOW TRIGGER command displays the SET TERMINAL TRIGGER values as well as
the v(trigger) value.
3.3. Transparent Printing
As noted in the manual, C-Kermit's CONNECT command on UNIX is not a terminal
emulator, but rather a "semitransparent pipe" between the terminal or emulator
you are using to access C-Kermit, and the remote host to which C-Kermit is
connected. The "semitransparent" qualifier is because of character-set
translation as well as several actions taken by the emulator in response to
the characters or strings that pass through it, such as APCs, Kermit packets
(autodownload), triggers, etc.
The UNIX version of C-Kermit 7.0 adds another such action: Transparent
printing, also called Controller printing (as distinct from Autoprint or line
or screen print). It is intended mainly for use on UNIX workstation consoles
(as opposed to remote logins), but with some care can also be used when
accessing C-Kermit remotely.
Transparent printing is related to APC by sharing C-Kermit's built-in ANSI
escape-sequence parser to detect "printer on" and "printer off" sequences from
the host. When the printer-on sequence is received, all subsequent arriving
characters -- including NUL, control characters, and escape sequences --
are sent to the SET PRINTER device instead of to your screen until
the printer-off sequence is received, or you escape back, whichever happens
first. These bytes are not translated or modified or filtered in any way
by Kermit (except for possibly stripping of the 8th bit, as noted below), but
if filtering or translation is desired, this can be accomplished by your
SET PRINTER selection (e.g. by choosing a pipeline of filters).
By default, your SET PRINTER device is your default UNIX printer, but
it can also be a file, a command, or the null device (which causes all printer
material to be discarded). See "Using C-Kermit", 2nd Ed., p.41 for details.
Transparent printing is controlled by the command:
SET TERMINAL PRINT { ON, OFF }
When ON, transparent-print sequences are obeyed, and printing occurs on the
system where C-Kermit is running. When OFF, transparent print sequences are
ignored and passed through to your actual terminal or emulator, along with
the data they enclose. OFF is the default, for compatibility with earlier
C-Kermit releases. As noted in the manual, when the current SET PRINTER
device is a file, transparent-print material is appended to it; the file is
not overwritten.
SET TERMINAL BYTESIZE { 7, 8 }
SET PARITY { EVEN, ODD, MARK, SPACE, NONE }
If the terminal bytesize is 7, or PARITY is not NONE, the 8th bit of each
byte is stripped prior to printing.
The transparent-print escape sequences are:
<ESC>[5i
Printer On. Send all subsequent incoming bytes to the printer without
any kind of filtering, translation, or alteration. Note: <ESC> stands for
ASCII character number 27 (decimal), Escape.
<ESC>[4i
Printer Off. Resume displaying incoming bytes on the screen.
These are the same sequences used by DEC VT100 and higher terminals and other
ANSI X3.64 and ISO 6429 compatible terminals. There is no provision for
selecting other printer-control sequences.
Restrictions:
1. You must SET TERM TRANSPARENT-PRINT ON before you can use this feature.
2. Only the 7-bit forms of the escape sequences are supported. The 8-bit
CSI C1 control is not recognized.
3. Autoprint is not supported, since this requires a full-fledged terminal
emulator with direct access to the screen.
4. The start-print and stop-print sequences pass through to the screen (there
is no way to avoid this without causing unacceptable delays or deadlocks
in CONNECT mode). Thus if your terminal or emulator also supports
transparent printing via these same sequences, an empty file will be sent
to its printer. Normally this has no effect.
Point (4) is similar to the situation with autodownload and APC -- when you
have several Kermit clients in a chain, you should take care that these
features are enabled in only one of them.
Example 1:
set printer {|lpr -Plaser} ; Specify the printer (if not default).
set term print on ; Enable transparent printing.
set term byte 8 ; Enable 8-bit characters.
connect ; Enter CONNECT mode.
Example 2:
set printer /home/users/olga/printer.log ; Send printer material to a file.
Example 3:
set printer {| grep -v ^Received | lpr} ; Filter out some lines
Then use "pcprint" or "vtprint" commands on the host to initiate transparent
print operations. See "Using C-Kermit", 2nd Ed., p.406 for details.
Here is a sample "pcprint" shell script for UNIX:
#!/bin/sh
echo -n '<ESC>[5i'
if [ $# -eq 0 ]; then
cat
else
cat $*
fi
echo -n '<FF><ESC>[4i'
# (end)
(Replace "<ESC>" by the actual ASCII Escape character and "<FF>" by the
ASCII Formfeed character).
If you always want transparent printing enabled, put "set term print on"
in your C-Kermit customization file (~/.mykermrc in UNIX). The "set term
bytesize" selection, however, is a property of each separate connection.
3.4. Binary and Text Session Logs
C-Kermit 7.0 corrects an oversight in earlier releases, in which binary
session logs (SET SESSION-LOG BINARY) translated character sets and performed
various formatting transformations (e.g. "newline mode") before writing
characters to the session log. In C-Kermit 7.0, binary-mode session logging
writes characters as they come in, before anything (other that parity-bit
stripping) is done to them. Text-mode session logging records the characters
after processing.
(4) FILE TRANSFER
Every file is transferred either in text mode (which implies record-format
and character-set translation) or binary mode (in which each byte is sent
literally without any kind of conversion). The mode in which a file is
transferred is controlled by (a) the default mode, in the absence of any
other indications; (b) the SET FILE TYPE command; (c) various automatic
mechanisms based on client/server negotiations, directory information or
filename patterns, etc.
The default FILE TYPE was changed from TEXT to BINARY in C-Kermit 7.0
because:
. Transferring a text file in binary mode does less damage than
transferring a binary file in text mode.
. Only binary-mode transfers can be recovered from the point of failure.
. The automatic transfer-mode mechanisms switch to text mode on a per-file
basis anyway, so only those files that are not covered by the automatic
mechanisms are affected.
. All file transfers on the Web are done in binary mode, so people are
accustomed to it and expect it.
4.0. BUG FIXES, MINOR CHANGES, AND CLARIFICATIONS
4.0.0. Filenames with Spaces
Filenames that contain spaces are a major nuisance to a program like Kermit,
whose command language is line- and word-oriented, in which words are
separated by spaces and a filename is assumed to be a "word". In general
(unless noted otherwise in the description of a particular command), there is
only one way to refer to such files in Kermit commands, and that is to enclose
the name in braces:
send {this file}
Tells Kermit to send the file whose name is "this file" (two words, no
quotes). Of course, various circumlocutions are also possible, such as:
define %a this file
send %a
BUT, perhaps contrary to expectation, you can't use "32" to represent the
space:
send this32file
does not work. Why? Because the Kermit parser, which must work on many
operating systems including Windows, has no way of knowing what you mean by
"this32file". Do you mean a file whose name is "this file" in the current
directory? Or do you mean a file whose name is "32file" in the "this"
subdirectory of the current directory? Guessing won't do here; Kermit must
behave consistently and deterministically in all cases on all platforms.
Note that you can't use Esc or Tab within {...} for filename completion,
or question mark to get a filename list. However, you can include wildcards;
for example:
send {* *}
sends all files whose name contains a space.
All things considered, it is best to avoid spaces in file and directory names
if you can. Also see Section 5.4 on this topic.
4.0.1. Packet out of Window
C-Kermit 6.0 could send packets "out of window" if the window size was
greater than 1 and ACKs had arrived out of order. Fixed in 6.1.
4.0.2. MOVE after ADD SEND-LIST
ADD SEND-LIST followed by MOVE did not delete original files; fixed in 6.1.
Carrier loss was not detected during transfer; in 7.0 C-Kermit checks for
this (but results can not be guaranteed). In any case, the protocol will
eventually time out if the connection is lost.
4.0.3. GET and RECEIVE As-Names
In 5A(190) through 6.0.192, the GET and RECEIVE as-name did not properly
override the RECEIVE PATHNAMES setting. In 7.0 it does.
4.0.4. New Brief Statistics Listing
Version 7.0 adds a /BRIEF switch to the STATISTICS command, to display a short
file-transfer statistics report. /BRIEF is now the default. Use /VERBOSE to
see the full display, which is about 25 lines long.
4.0.5. Improved FAST Command
The preinstalled definition of the FAST macro did not take enough factors into
account. Now it sets packet lengths and window sizes appropriate to the
configuration. Furthermore, in IRIX only, it might restrict the SEND packet
length to 4000, to work around a bug in the IRIX Telnet server, depending on
the IRIX version (see ckubwr.txt, IRIX section). To see the built-in
definition of the FAST macro, type "show macro fast". To change it, simply
define it to be whatever you want -- it's just a macro, like any other.
4.0.6. The SET SEND BACKUP Command
Version 7.0 adds SET SEND BACKUP { ON, OFF }. This tells whether backup
files should be sent. Backup files are the ones created by Kermit (and EMACS,
and possibly other applications) to preserve old copies of files when creating
new ones with the same name. Kermit does this when receiving a file and its
FILE COLLISION setting is BACKUP (or RENAME, in which case it the new file
gets the backup name). On most platforms, the backup name is formed by adding:
.~n~
to the end of the filename, where "n" is a number. For example, if the
original file is oofa.txt, a backup file might be called:
oofa.txt.~1~
(or oofa.txt.~2~, etc). If you SET SEND BACKUP OFF, this tells Kermit not to
send files that have backup names. Normally, SET SEND BACKUP is ON (as shown
by SHOW PROTOCOL), and backup files are sent if their names match the SEND
file specification.
Also see PURGE, SET FILE COLLISION, SEND /NOBACKUP, DIRECTORY /[NO]BACKUP.
4.0.7. The SET { SEND, RECEIVE } VERSION-NUMBERS Command
VMS Only. Normally when sending files, VMS C-Kermit strips the version
number. For example, if the file is FOO.BAR;34, the name is sent as FOO.BAR
(without the ";34"). If you want to keep version numbers on when sending
files, use SET SEND VERSION-NUMBERS ON. The effect depends on the receiver.
Normally when receiving files, and an incoming filename includes a VMS-style
version number (such as FOO.BAR;34) VMS C-Kermit strips it before trying to
create the new file; this way the new file receives the next highest version
number in the customary manner for VMS. If you want version numbers on
incoming filenames to be used in creating the new files, use SET RECEIVE
VERSION-NUMBERS ON.
Normally these commands would be effective only when VMS C-Kermit is
exchanging files with a non-VMS Kermit program, since VMS-to-VMS transfers use
labeled mode unless you have gone out of your way to defeat it.
Example: You want to send all versions of all files in the current directory
from a VMS C-Kermit client to a UNIX C-Kermit server. Use:
set send version-numbers on
send *.*;*
The resulting Unix files will have VMS-style version numbers as part of their
name, for example "foo.bar;1", "foo.bar;2", etc.
Now suppose you want to send these files from Unix to another VMS system and
preserve the version numbers. Again we have a Unix C-Kermit server and VMS
C-Kermit client. Give these commands to the client:
set receive version-numbers on
get *
4.0.8. The SET { SEND, RECEIVE } { MOVE-TO, RENAME-TO } Commands
These commands are persistent global versions of the /MOVE-TO: and
/RENAME-TO: switches of the SEND, GET, and RECEIVE commands. They should
normally be used only when setting up a dedicated transaction-processing
application, in which each file is to be moved or renamed immediately after,
and only if, it is transferred successfully, so that (for example) an
independent, concurrent process can notice when new files appear and process
them immediately without having to guess whether they are complete.
4.0.9. SET FILE INCOMPLETE AUTO
SET FILE INCOMPLETE { KEEP, DISCARD }, which tells whether to keep or discard
incompletely received files, has a new option, AUTO, which is also the
default. It means KEEP the incomplete file if the transfer is in binary mode,
otherwise DISCARD it. This reduces the chances that a subsequent recovery
operation (RESEND, REGET, etc) could produce a corrupt file, since recovery
works only for binary-mode transfers.
4.1. FILE-TRANSFER FILENAME TEMPLATES
File-transfer filename templates allow files to be renamed automatically by
the file sender, the receiver, or both, during transfer of groups of files.
4.1.1. Templates in the As-Name
Prior to C-Kermit 6.1 and Kermit 95 1.1.12 the only options that could be
used to affect the names of files being transferred were SET FILENAMES
{ LITERAL, CONVERTED } and SET { SEND, RECEIVE } PATHNAMES { ON, OFF }, plus
the "as-name" feature of the SEND (MOVE, etc) and RECEIVE commands.
Previously, the as-name could be used only for a single file. For example:
SEND FOO BAR
would send the file FOO under the name BAR, but:
SEND *.TXT anything
was not allowed, since it would give the same name to each file that was sent.
When receiving:
RECEIVE FOO
would rename the first incoming file to FOO before storing it on the disk,
but subsequent files would not be renamed to FOO, since this would result in
overwriting the same file repeatedly. Instead, they were stored under the
names they arrived with.
Beginning in C-Kermit 6.1 and Kermit 95 1.1.12, it is possible to
specify as-names in SEND, RECEIVE, and related commands even for file
groups. This is accomplished by using replacement variables in the as-name,
along with optional material such character-string functions and/or constant
strings. An as-name containing replacement variables is called a filename
template.
The key to filename templates is the new variable:
v(filename)
During file transfer it is replaced by the name of each file currently being
transferred (after transfer, it is the name of the last file transferred).
So, for example:
send *.txt v(filename).new
sends each file with its own name, but with ".new" appended to it. Of course
if the name already contains periods, this could confuse the file receiver, so
you can also achieve fancier effects with constructions like:
send *.txt freplace(v(filename),.,_).new
which replaces all periods in the original filename by underscores, and then
appends ".new" to the result. So, for example, oofa.txt would be sent as
oofa_txt.new.
Another new variable that is useful in this regard is v(filenumber), which
is the ordinal number of the current file in the file group, so you can also:
send *.txt FILEflpad(v(filenum),2,0)
resulting in a series of files called FILE00, FILE01, FILE02, etc. (At the
end of the transfer, v(filenum) tells the number of files that were
transferred).
If you specify a constant as-name when sending a file group:
send *.txt thisnameonly
Kermit complains and asks you to include replacement variables in the
as-name. You should generally use v(filename) or v(filenumber) for this
purpose, since other variables (with the possible exception of date/time
related variables) do not change from one file to the next. But Kermit
accepts any as-name at all that contains any kind of variables for file
group, even if the variable will not change. So:
send *.txt %a
is accepted, but all files are sent with the same name (the value of %a, if
it has one and it is constant). If the variable has no value at all, the
files are sent under their own names.
Of course, the value of %a in the previous example need not be constant:
define %a FILEflpad(v(filenum),2,0)_at_v(time)
send *.txt %a
The RECEIVE command, when given without an as-name, behaves as always, storing
all incoming files under the names they arrive with, subject to SET FILE NAME
and SET RECEIVE PATHNAMES modifications (Section 4.10).
However, when an as-name is given in the RECEIVE command, it is applied to
all incoming files rather than to just the first. If it does not contain
replacement variables, then the current FILE COLLISION setting governs the
result. For example:
receive foo
will result in incoming files named foo, foo.~1~, foo.~2~, and so on, with the
default FILE COLLISION setting of BACKUP. If it does contain replacement
variables, of course they are used.
When receiving files, the v(filename) variable refers to the name that was
received in the incoming file-header packet, BEFORE any processing by SET
FILE NAMES or SET RECEIVE PATHNAMES. Since the filenames in file-header
packets are usually in uppercase, you would need to convert them explicitly
if you want them in lowercase, e.g.:
receive flower(v(filename)).new
4.1.2. Templates on the Command Line
On the command-line, use templates as shown above as the -a option argument,
bearing in mind the propensity of UNIX and perhaps other shells to treat
backslash as a shell escape character. So in UNIX (for example):
kermit -s oofa.* -a x.\v(filenum)
By the way, this represents a change from 6.0 and earlier releases in
which the as-name (-a argument or otherwise) was not evaluated by the command
parser. Thus, for example, in VMS (where the shell does not care about
backslashes), it was possible to:
kermit -s oofa.txt -a c:tmpoofa.txt
Now backslashes in the as-name must be quoted not only for the shell (if
necessary) but also for Kermit itself:
kermit -s oofa.txt -a c:\tmp\oofa.txt ; Kermit only
kermit -s oofa.txt -a c:\\tmp\\oofa.txt ; Shell and Kermit
You can also use the fliteral() function for this:
kermit -s oofa.txt -a fliteral(c:tmpoofa.txt) ; Kermit only
kermit -s oofa.txt -a \fliteral(c:\tmp\oofa.txt) ; Shell and Kermit
4.1.3. Post-Transfer Renaming
Filename templates are now also useful in SET { SEND, RECEIVE } RENAME-TO and
in the /RENAME-TO: switch, that can be given to the SEND, GET, or RECEIVE
commands; this is similar to an as-name, but is effective on a per-file basis
if and only if the file was transferred successfully.
MOVE-TO and RENAME-TO address a requirement commonly stated for transaction
processing and similar systems. Suppose, for example, a central system "X"
accepts connections from multiple clients simultaneously; a process on X waits
for a file to appear and then processes the file. This process must have a
way of knowing when the file has been completely and successfully transferred
before it starts to process it. This can be accomplished easily using
C-Kermit's SET { SEND, RECEIVE } { MOVE-TO, RENAME-TO } command or /MOVE-TO:
or /RENAME-TO: switches, described in Sections 4.7.1-3.
Here's an example for the client side, in which files to be sent are placed in
a certain directory (/usr/olga/tosend in this example) by another process when
they are ready to go. This might be in a hospital or big doctor's office,
where medical insurance claims are entered at a number of workstations, and
then deposited in the "tosend" directory, from which they are sent to a claims
clearinghouse. We assume the connection is already made and a Kermit server
is on the other end.
local srcdir findir ; Declare local (automatic) variables
assign srcdir /usr/olga/tosend ; Local source directory (files to send)
assign findir /usr/olga/sent ; Where to move files after they are sent
log transactions ; Keep a log of transfers
cd m(srcdir) ; Change to the source directory
while true { ; Loop forever...
send /move-to:m(findir) * ; Send all files
sleep 60 ; Sleep a minute
} ; Go back and do it again
Note how simple this is. Once each file is sent, it is moved so it won't be
sent again (you could also use SEND /RENAME-TO: or even SEND /DELETE). If a
transfer fails, the file is not moved and so we try again to send it next time
around. If there are no files to send, the SEND command does nothing but a
message is printed; you can avoid the message by checking first to see if any
files are in the directory:
while true { ; Loop forever...
if > ffiles(*) 0 - ; If there are any files
send /move-to:m(findir) * ; send them.
sleep 60 ; Sleep a minute.
} ; Go back and do it again.
It's even simpler on the server side (here again we assume the connection
is already in place):
local rcvdir findir ; Declare local (automatic) variables
assign rcvdir /usr/ivan/tmp ; Temporary receiving directory
assign findir /usr/ivan/new ; Where to move files after reception
log transactions ; Keep a log of transfers
cd m(rcvdir) ; Change to the source directory
set receive move-to m(findir) ; Declare move-to directory.
server ; Enter server mode.
A separate process (e.g. the medical claim-form decoder) can look for files
appearing in the /usr/ivan/new directory and process them with every
confidence that they have been completely received.
Note that the use of MOVE-TO can result in moved files overwriting one another
(the application would normally avoid this by assigning each transaction a
unique, e.g. based on customer number and claim number). But if filename
collisions are a possibility in your application, RENAME-TO might be a better
choice; you can use any variables you like in the template to ensure
uniqueness of the RENAME-TO filename; for example:
SET RECEIVE RENAME-TO v(filename)_v(ndate)_v(ntime)_v(userid)_v(pid)
4.2. FILE-TRANSFER PIPES AND FILTERS
4.2.1. INTRODUCTION
Beginning in C-Kermit 6.1 and Kermit 95 1.1.12, it is possible to send from a
command, or "pipe", as well as from a file, and to receive to a pipe or
command. In a typical example, we might want to transfer an entire directory
tree from one UNIX system to another (but without using the methods described
in Sections 4.3, 4.10, 4.11, and 4.15). We could do this in multiple steps as
follows:
1. Create a tar archive of the desired directory tree
2. Compress the tar archive
3. Transfer it in binary mode to the other computer
4. Decompress it
5. Extract the directory tree from the tar archive
But this is inconvenient and it requires a temporary file, which might be
larger than we have room for.
The new pipe-transfer feature lets you do such things in a single step,
and without intermediate files.
Additional new features, also discussed here, let you specify pre- and post-
processing filters for outbound and incoming files, and give you a way to
insert the output from shell or system commands into C-Kermit commands.
The file-transfer related features are available only with Kermit protocol,
not with any external protocols, nor with K95's built-in XYZMODEM protocols
(because XYZMODEM recovers from transmission errors by rewinding the source
file, and you can't rewind a pipe).
This section begins by discussing the simple and straightforward use of these
features in UNIX, in which pipes and input/output redirection are a
fundamental component and therefore "just work", and then goes on to discuss
their operation in Windows and OS/2, where matters are much more complicated.
4.2.1.1. TERMINOLOGY
Standard Input
This is a precise technical term denoting the normal source of input for
a command or program, which is the keyboard of your terminal by default,
but which can be redirected to a file or pipe.
Stdin
Abbreviation for Standard Input.
Standard Output
A precise technical term denoting the normal destination for output from a
command or program, which is your terminal screen by default, but which can
be redirected to a file.
Stdout
Abbreviation for Standard Output.
Stdio
Abbreviation for Standard Input / Standard Output.
I/O
Abbreviation for Input / Output.
Shell
Text-based system command processor, such as the UNIX shell, DOS
COMMAND.COM, etc.
Pipe
A mechanism by which the standard output of one program is sent to
the standard input of another.
Pipeline
A series of programs connected by pipes.
4.2.1.2. NOTATION
In command descriptions, "<command>" is replaced by a shell or system command
or pipeline. The command names specified in these commands are interpreted by
your shell, just as if you were typing them at the shell prompt, and so if
they are in your PATH, they will be found in the expected manner. Therefore
you don't have to specify complete pathnames for commands that are programs
(but it shouldn't hurt if you do).
The normal notation for I/O redirection is as follows:
< Read Stdin from the given file.
> Send Stdout to the given file.
| Send Stdout from the command on the left to the command on the right.
Examples:
sort < foo > bar
Sorts the lines in file "foo" and writes the results to file "bar"
grep -c "some text" *.txt | grep -v ":0" | sort | pr -3 | lpr
This is a command pipeline composed of 5 commands:
grep -c "some text" *.txt
Looks in all files whose names end with ".txt" for the string "some text"
and writes to Stdout the names of each file followed by a colon and the
number of occurrences in each.
grep -v ":0"
Prints to Stdout the lines from Stdin that do NOT contain the string ":0",
in this case, it removes the names of files that do not contain "some
text".
sort
Sorts the lines from Stdin alphabetically to Stdout.
pr -3
Arranges the lines from Stdin in three columns.
lpr
Prints its Stdin on the default printer.
Note that the Kermit features described here work only with commands that use
Stdio. If you attempt to use them with commands whose input and output can
not be redirected, Kermit will most likely get stuck. Kermit has no way of
telling how an external command works, nor what the syntax of the shell is, so
it's up to you to make sure you use these features only with redirectable
commands.
The quoting rules of your shell apply to the <command>. Thus in UNIX, where
C-Kermit tries to use your preferred shell for running commands, shell
"metacharacters" within commands must be escaped if they are to be taken
literally, using the methods normal for your shell. For example, the UNIX tr
(translate) command must have its arguments in quotes:
tr "[a-z]" "[A-Z]"
otherwise the shell is likely to replace them by all filenames that match,
which is probably not what you want. This is also true when using your shell
directly, and has nothing to do with Kermit.
4.2.1.3. SECURITY
Some sites might not wish to allow access to system commands or external
programs from within Kermit. Such access, including all the features
described here, can be disabled in various ways:
1. When building from source code, include -DNOPUSH among the CFLAGS.
2. At runtime, give the NOPUSH command.
3. For server mode, give the DISABLE HOST command.
4. Implicit use of pipes can be disabled as described in section 4.2.4.
Note: 3 and 4 are not necessary if you have done 1 or 2.
4.2.2. Commands for Transferring from and to Pipes
SEND /COMMAND sends data from a command or command pipeline, and RECEIVE
/COMMENT writes data to a command or pipeline. The GET /COMMAND command
asks a server to send material, and then writes the incoming material to a
command or pipeline. These features, along with switches (like "/COMMAND",
described in section 4.7) are new to C-Kermit 6.1. The following synonyms
are also provided:
CSEND = SEND /COMMAND
CRECEIVE = RECEIVE /COMMAND
CGET = GET /COMMAND
None of these commands can be used if a SEND or RECEIVE FILTER (respectively,
Section 4.2.3) is in effect, or if a NOPUSH command (Section 4.2.1.3) has been
given, or if the current protocol is not Kermit.
4.2.2.1. Sending from a Command
SEND /COMMAND <command> [ <as-name> ]
SEND /AS-NAME:<as-name> /COMMAND <command>
CSEND <command> [ <as-name> ]
These three forms are the same. They work like the SEND command, but
instead of sending a file, it sends the standard output of the given
<command>, either under the command's own name, or else with the given
<as-name>. If the <command> contains spaces, it must be enclosed in braces.
Braces should also be used for the <as-name> if it contains spaces. If
braces are included around either the <command> or the <as-name>, they are
removed after parsing but before use. As with SEND, the transfer is in text
or binary mode according the current FILE TYPE setting, unless you override
the global transfer mode by including a /TEXT or /BINARY switch. The
<command> must require no input.
When sending from a command or pipeline, C-Kermit has no way of knowing
in advance how much data will be sent, and so it can not send the size
to the other Kermit in the Attribute packet, and so the receiving Kermit
has no way of displaying "percent done" or a progress bar (thermometer).
Examples that make sense in text mode (illustrated by common UNIX commands):
SEND /COMMAND finger
CSEND finger
sends the current "finger" listing (who's logged in) under the
name "finger". The two forms "send /command" and "csend" are
equivalent; we won't bother showing them both in the rest of the
examples.
SEND /COMMAND:{finger}
CSEND {finger}
Same as previous example (braces are removed from "{finger}").
SEND /COMMAND:{ finger }
CSEND { finger }
Same as previous example, but note that the spaces are kept. This
does not prevent the shell from running the "finger" program, but
its output is sent under the name " finger " (with a leading and
trailing space).
SEND /COMMAND:finger /AS-NAME:userlist
CSEND finger userlist
sends the current finger listing under the name "userlist".
SEND /COMMAND:{finger | sort -r} /AS-NAME:userlist
CSEND {finger | sort -r} userlist
sends the current finger listing, sorted in reverse order, under the
name "userlist". The braces are needed to distinguish the <command>
from the <as-name>.
SEND /COMMAND:{finger | sort -r} /AS-NAME:{userlist}
CSEND {finger | sort -r} {userlist}
Same as previous example (braces are removed from "{userlist}").
SEND /COMMAND:{finger | sort -r} /AS-NAME:{freplace(v(filename),32,_)}
CSEND {finger | sort -r} {freplace(v(filename),32,_)}
Like the previous example, but sends the output of the <command> under
the name of the command, but with all spaces (32) replaced by underscores,
so the as-name is "finger_|_sort_-r".
Examples that make sense in binary mode (three equivalent forms are shown):
SEND /COMMAND /BINARY {tar cf - . | gzip -c} mydir.tar.gz
SEND /COMMAND /BINARY /AS-NAME:mydir.tar.gz {tar cf - . | gzip -c}
CSEND /BINARY {tar cf - . | gzip -c} mydir.tar.gz
Makes a tar archive of the current directory, compresses it with the GNU
gzip program, and sends it as "mydir.tar.gz". The other Kermit can, of
course, just store it as a file, or it can use CRECEIVE to uncompress and
dearchive it as part of the transfer process.
When using a "pipeline" of commands in the <command> field, obviously,
the first command must not require any input, and the last command should
produce some output, and all intermediate commands should get some input and
produce some output.
4.2.2.2. Receiving to a Command
RECEIVE /COMMAND <command>
CRECEIVE <command>
This is like RECEIVE, except incoming material is written to the standard
input of the given command, in text or binary mode according to the normal
rules for file reception. Be sure to include a redirector to a file (if the
command normally writes to standard output), or the output of the command
won't go anywhere. The <command> may contain spaces; braces are not needed,
but they are removed if used.
WARNING: C-Kermit has no way of knowing anything about the <command>, or even
whether it is a command. Thus this command will always cause C-Kermit to
enter protocol mode, as long as some text is specified in the <command> field.
However, if the text does not correspond to a command, the transfer will
eventually fail with a message such as "Error writing data" or "Failure to
close file".
Examples for text mode (in UNIX):
RECEIVE /COMMAND sort -r > reverse.txt
CRECEIVE sort -r > reverse.txt
The text that is received is sorted in reverse order and stored in
the file "reverse.txt". The two forms shown are equivalent.
RECEIVE /COMMAND {sort -r > reverse.txt}
CRECEIVE {sort -r > reverse.txt}
The same as the previous example; if braces are included, they are
simply removed.
RECEIVE /COMMAND {sort -r > flower(v(filename)).reverse}
CRECEIVE {sort -r > flower(v(filename)).reverse}
Same but stores result under the incoming filename, lowercased, and
with ".reverse" appended to it.
RECEIVE /COMMAND sort
CRECEIVE sort
Does nothing useful, since the output of sort has nowhere to go.
RECEIVE /COMMAND sort -r | pr -3 | lpr -Plaserjet
CRECEIVE sort -r | pr -3 | lpr -Plaserjet
The text that is received is sorted in reverse order, arranged into
three columns, and sent to the "laserjet" printer.
Examples for binary mode:
RECEIVE /COMMAND:{gunzip -c | tar xf -}
CRECEIVE {gunzip -c | tar xf -}
Assuming the data that is received is a compressed tar archive,
uncompresses the archive and passes it to tar for extraction. In this
case the braces are needed because otherwise the final "-" would be
taken as a command continuation character (see "Using C-Kermit", 2nd
Edition, p.33).
GET /COMMAND <remote-file> <command>
GET /COMMAND /AS-NAME:<command> <remote-file>
CGET <remote-file> <command>
This command tells the Kermit client to send a GET request for the given
remote file to a Kermit server. Unlike GET, however, the incoming material
is written to a command, rather than to a file. If the <remote-file> or the
<command> contain spaces, they must be enclosed in braces. The same
cautions about the <command> apply as for CRECEIVE. Examples (for UNIX):
GET /COMMAND oofa.txt sort -r > oofa.new
GET /COMMAND {oofa.txt} {sort -r > oofa.new}
CGET oofa.txt sort -r > oofa.new
CGET {oofa.txt} {sort -r > oofa.new}
These four are equivalent. Each of them requests the server to send
its "oofa.txt" file, and as it arrives, it is sorted in reverse order
and written to "oofa.new".
GET /COMMAND {profile exec a} lpr
GET /COMMAND {profile exec a} {lpr}
GET /COMMAND /AS-NAME:lpr {profile exec a}
GET /COMMAND /AS-NAME:{lpr} {profile exec a}
GET /COMMAND /AS:lpr {profile exec a}
CGET {profile exec a} lpr
CGET {profile exec a} {lpr}
Here the remote filename contains spaces so it MUST be enclosed in
braces. As it arrives it is sent to the lpr program for printing.
Braces are optional around "lpr" since it contains no spaces.
GET /COMMAND *.txt {cat >> new.txt}
GET /AS-NAME:{cat >> new.txt} /COMMAND *.txt
CGET *.txt {cat >> new.txt}
This gets all the ".txt" files from the server and concatenates them
all into a single "new.txt" file on the client.
GET /COMMAND *.txt {echo v(filename)>>new.txt;cat>>new.txt}
CGET *.txt {echo v(filename)>>new.txt;cat>>new.txt}
As above, but inserts each file's name before its contents.
4.2.3. Using File-Transfer Filters
The commands described in section 4.2.2 let you send the output of a command,
or receive data into a command. But what if you want to specify preprocessing
for files that you send, or postprocessing of files that you receive, even
when multiple files are involved? For this you need a way to specify send and
receive filters. The commands are SET SEND FILTER and SET RECEIVE FILTER;
SHOW PROTOCOL displays the current settings.
4.2.3.1. The SEND Filter
SET SEND FILTER [ <command> ]
This command specifies a <command> to be run on any file that you SEND (or
MOVE, MSEND, etc). It also applies to files sent when in server mode, in
response to GET commands, but not to the results of REMOTE commands like
REMOTE DIRECTORY, REMOTE TYPE, REMOTE HOST, etc. The <command> may be, but
need not be, enclosed in braces; if it is, the braces are stripped before
use. The output of this command is sent, rather than the file itself. The
current FILE TYPE setting (TEXT or BINARY) applies to the output of the
command. The <command> must contain at least one instance of v(filename),
for which the name of the actual file is substituted. If the <command> is
omitted, the send filter is removed and files are sent in the normal manner.
The SET SEND FILTER sets up a "global" filter -- that is, one that applies to
all subsequent file-sending commands until you change or remove it. You can
also specify a "local" filter to be used in a specific file-sending command by
using the /FILTER switch (see section 1.5); for example:
SEND /FILTER:<command> [ <other-switches> ] <filename>
Besides v(filename), you can include any other script programming notation in
the send filter: variable names, array references, calls to built-in string or
other functions, and so on. These are evaluated during file transfer, NOT
during parsing, and they are evaluated separately for each file.
When the SEND or MOVE (SEND /DELETE) command is used with a send filter, the
output from the filter is sent under the file's original name unless you
specify an "as-name" or template. The Attribute packet (if any) contains the
original file's attributes (size, creation date, etc). So (for example) if
the filter changes the file's size, the progress thermometer might be wrong.
(We can't send the size of the output from the filter, because it is not known
until the transfer is finished.) If you prefer that the size not be sent, use
"set attributes size off".
You can not use send filters with RESEND (SEND /RECOVER) or PSEND
(SEND /START).
Examples for text mode:
SET SEND FILTER sort -r v(filename) ; Braces may be omitted
SET SEND FILTER {sort -r v(filename)} ; Braces may be included
SEND *.txt
This sends every file in the current directory whose name ends with
".txt" under its own name, but with its lines sorted in reverse order.
SEND /FILTER:{sort -r v(filename)} *.txt
Same as above, but the filter applies only to this SEND command.
Braces are required in this case.
SET SEND FILTER {sort -r v(filename)}
SEND oofa.txt reverse.txt
Sends the oofa.txt file with its lines sorted in reverse order under
the name "reverse.txt".
SET SEND FILTER {sort -r v(filename)}
SEND oofa.* v(filename).reverse
Sends all the oofa.* files with their lines sorted in reverse order;
each file is sent under its own name but with ".reverse" appended to it.
SET SEND FILTER {tr "[a-z]" "[A-Z]" < v(filename)}
SEND *.txt
Sends all ".txt" files under their own names, but uppercasing their
contents.
Note that the SEND FILTER applies not only to files that are sent with
SEND, MOVE, MSEND, etc, but also to files sent by the C-Kermit server in
response to GET requests.
Examples for binary mode:
SET SEND FILTER {gzip -c v(filename)}
SEND /BINARY oofa.txt oofa.txt.gz
Sends the oofa.txt file, compressed by gzip, as oofa.txt.gz.
SEND /BINARY /FILTER:{gzip -c v(filename)} oofa.txt oofa.txt.gz
As above, but the filter applies only to this SEND command.
SET SEND FILTER {gzip -c v(filename)}
SEND /BINARY oofa.* fupper(replace(v(filename),.,_)).GZ
Sends all the oofa.* files, compressed by gzip, each under its own name,
but with the name uppercased, all periods within the name converted to
underscores, and ".GZ" appended to it. So, for example, "oofa.txt"
is sent as "OOFA_TXT.GZ".
In the gzip examples, note that the amount of data that is sent is normally
less than the original file size because gzip compresses the file. But Kermit
sends the original file size ahead in the attribute packet anyway (unless you
tell it not too). Thus the transfer will probably appear to terminate early,
e.g. when the receiver's file-transfer display thermometer is only at 40%.
If this annoys you, tell Kermit to "set attribute length off". On the other
hand, you can use the final position of the thermometer as a measure of the
effectiveness of compression.
4.2.3.2. The RECEIVE Filter
SET RECEIVE FILTER [ <command> ]
This command specifies that the given <command> will be run on any file
that is received before it is written to disk. The <command> may be, but
need not be, enclosed in braces; if it is the braces are stripped before
use. The following two commands are equivalent:
SET RECEIVE FILTER sort -r > v(filename)
SET RECEIVE FILTER {sort -r > v(filename)}
The RECEIVE filter <command> may contain a "v(filename)" sequence to be
replaced by the incoming filename from the file header packet, but it is not
required. However you must use it whenever your filter would normally write
to Stdout, otherwise its output will be lost.
The RECEIVE filter <command> may contain one or more "v(filename)"
sequence to be replaced by the incoming filename from the file header
packet, but it is not required. However you must use it whenever your
filter would normally write to Stdout, otherwise its output will be lost.
RECEIVE /FILTER:<command> and GET /FILTER:<command> can also be used to
specify a filter to be used for only one file-transfer operation.
UNIX examples for text mode:
SET RECEIVE FILTER lpr
RECEIVE
All the files that are received are sent to the default UNIX print
spooler.
RECEIVE /FILTER:lpr
Same as above, except the lpr filter is used only with this
RECEIVE command.
RECEIVE lpr
This is probably not what you want; it creates a file called lpr.
SET RECEIVE FILTER {sort -r > v(filename)}
RECEIVE
Stores each incoming file with its lines sorted in reverse order,
under its own name.
RECEIVE /FILTER:{sort -r > v(filename)}
As above, but the filter is used only for this RECEIVE command.
SET RECEIVE FILTER sort -r > v(filename)
RECEIVE reverse.txt
Stores each incoming file with its lines sorted in reverse order,
under the name "reverse.txt". The actual result depends on the
FILE COLLISION setting. If it is OVERWRITE and multiple files arrive,
then each incoming file destroys the previous one. If it is BACKUP
(the default), filename conflicts are resolve by adding "version numbers"
to the filenames: reverse.txt, reverse.txt.~1~, reverse.txt.~2~, etc.
SET RECEIVE FILTER sort -r > v(filename)
RECEIVE v(filename).reverse
Stores each incoming file with its lines sorted in reverse order,
under the name it arrived with, but with ".reverse" appended to it.
SET RECEIVE FILTER sort -r > v(filename)
RECEIVE flower(v(filename)).reverse
Like the previous example, but ensures that the filename is lowercase.
Examples for binary mode:
SET RECEIVE FILTER gunzip -c > v(filename)
RECEIVE
This receives one or more presumably compressed file and uncompresses
each one into a file having the same name it was sent with. For example,
if the file is sent with the name OOFA.TXT.GZ, it is stored with that
name, even after decompression.
SET RECEIVE FILTER gunzip -c > v(filename)
RECEIVE flower(fsubstring(v(filename),1,flength(v(filename))-3))
Like the previous example, but the resulting filename has its rightmost
three characters removed from it and the remainder is lowercased. So if
the incoming filename is OOFA.TXT.GZ, it is stored as oofa.txt after
decompression.
Of course you don't want to type such long hideous commands, so we have also
introduced several new functions:
fstripx(string[,character])
This function removes the rightmost segment of the string that starts with
the given character. If no character is given, period (.) is used. Thus
it is most conveniently used for stripping the extension from a filename
(or the decimal portion from a floating-point number written in US/UK
style). Examples:
fstripx(OOFA.TXT.GZ) => OOFA.TXT
fstripx(OOFA.TXT.GZ,.) => OOFA.TXT
fstripx(OOFA.TXT.GZ,X) => OOFA.T
fstripx(fstripx(OOFA.TXT.GZ)) => OOFA
fstripx($100.00) => $100
fstripn(string,number)
Removes the rightmost <number> characters from the string. Examples:
fstripn(OOFA.TXT.GZ) => OOFA.TXT.GZ
fstripn(OOFA.TXT.GZ,3) => OOFA.TXT
fstripn(OOFA.TXT.GZ,7) => OOFA
fstripb(string[,c1[,c2]])
Strips enclosing matching braces, brackets, parentheses, or quotes from
the string. The second argument, c1, specifies which kind of enclosure
to look for; if not specified, any enclosing (), [], <>, {}, "", '', or
`' are removed. If c1 is specified and c2 is not, then if c1 is an
opening brace, bracket, or parenthesis, the matching closing one is
supplied automatically as c2. If both c1 and c2 are specified, then to
be stripped the string must begin with c1 and end with c2. If the
string is not enclosed in the indicated manner, the result is the
original string. Examples:
fstripb("abc") => abc
fstripb([abc]) => abc
fstripb([abc) => [abc
fstripb(<abc>) => abc
fstripb(<abc>,[) => <abc>
fstripb((abc)) => abc
fstripb((abc),[) => (abc)
fstripb((abc),{(}) => abc
fstripb(+abc+) => +abc+
fstripb(+abc+,+) => abc
fstripb(+abc+,+,^) => +abc+
fstripb(+abc^,+,^) => abc
fstripb('abc') => abc
fstripb(`abc') => abc
fstripb(``abc'') => `abc'
fstripb(fstripb(``abc'')) => abc
Notice the special syntax required for including a literal parenthesis
in the argument list. As the last two examples illustrate, fstripb()
strips only one level at at a time; nesting can be used to strip a small
fixed number of levels; loops can be used to strip larger or indeterminate
numbers of levels.
flop(string[,char])
Removes the leftmost segment of the string that ends with the given
character. If no character is given, period (.) is used. Examples:
flop(OOFA.TXT.GZ) => TXT.GZ
flop(OOFA.TXT.GZ,.) => TXT.GZ
flop(OOFA.TXT.GZ,X) => T.GZ
To remove the leftmost <number> characters, just use fsubstring(s,<number>+1).
To return the rightmost <number> characters, use fright(s,<number>).
So the hideous example:
receive flower(fsubstring(v(filename),1,flength(v(filename))-3))
can now be written as:
receive flower(fstripx(v(filename)))
That is, the filename stripped of its extension and then lowercased. This
is not only shorter and less hideous, but also does not depend on the
length of the extension being 3.
Note that when a receive filter is in effect, this overrides your FILE
COLLISION setting, since Kermit has no way of knowing what the final
destination filename will be (because it does not know, and can not be
expected to know, the syntax of every version of every command shell on
every platform on the planet).
4.2.4. Implicit Use of Pipes
If you wish, C-Kermit can also examine incoming filenames to see if they
start with "!", and if so, the subsequent text is treated as a command to
read from or write to. For example, if a Kermit client is given the following
command:
get {!finger | sort}
the server on the other end, if it supports this feature, will run the
"finger" program, pipe its standard output to the "sort" program, and send
sort's standard output back to you. Similarly, if you:
send oofa.txt !sort -r > oofa.new
or, equivalently:
send oofa.txt {!sort -r > oofa.new}
or:
send /as-name:{!sort -r > oofa.new} oofa.txt
this has the receiver send the contents of the incoming oofa.txt file to
the sort program, which sorts the text in reverse order and stores the
result in oofa.new.
This use of the exclamation mark should be familiar to UNIX users as the
"bang" feature that lets you run an external application or command from
within another application.
Kermit's "bang" feature is disabled by default, since it is not unheard for
filenames to actually begin with "!". So if you want to use this feature,
you must enable it with the following command:
SET TRANSFER PIPES { ON, OFF }
ON enables the recognition of "!" notation in incoming filenames during
file transfer as an indicator that the remaining text is the name of a
command. OFF, the default, disables this feature and uses the text as
a filename in the normal fashion. This command does NOT affect SEND
/COMMAND, GET /COMMAND, CSEND, etc.
So using a combination of CSEND (SEND /COMMAND) and the "bang" feature, you
can transfer a directory tree all in one command (assuming the remote
Kermit supports pipe transfers and has them enabled):
CSEND {tar cf - . | gzip -c} {!gunzip -c | tar xf -}
or:
SEND /COMMAND:{tar cf - . | gzip -c} /as:{!gunzip -c | tar xf -}
Pay close attention to the syntax. Braces are needed around the <command>
because it contains spaces; braces are needed around the <as-name> because
it ends with "-". The <as-name> must begin with "!" or receiving Kermit will
not recognize it as a command. The CSEND command must NOT begin with "!"
unless you are running a command whose name really does start that character.
Similarly, you have a Kermit server send a directory tree to be unpacked
on the client end:
CGET {!tar cf - . | gzip -c} {gunzip -c | tar xf -}
or:
GET /COMMAND {!tar cf - . | gzip -c} /as:{gunzip -c | tar xf -}
Notice how, in this case, the bang is required in the remote command, to
distinguish it from a filename, but not in the local command, since by
definition of CGET (or GET /COMMAND), it is known to be a command.
SEND and RECEIVE FILTERs supersede the bang feature. For example, if a
file arrives under the name "!gunzip -c | tar xf -", but the receiving Kermit
also has been given a command like:
set receive filter sort -r > v(filename)
then the incoming data will be sorted rather than gunzipped.
Finally, if SET TRANSFER PIPES is ON (and in this case, this must be done in
your C-Kermit initialization file), you can send from a pipe on the C-Kermit
command line:
kermit -s "!finger | sort -r" -a userlist
In this case the "filename" contains spaces and so must be quoting using
your shell's quoting rules.
4.2.5. Success and Failure of Piped Commands
Commands or programs started by Kermit as a result of CSEND or CRECEIVE
commands, CGET, SEND /COMMAND, REDIRECT commands (see section 4.2.8.2),
implicit use of pipes, RUN commands, and so forth, should return their exit
status codes to the Kermit command that caused them to be run, and
therefore IF SUCCESS and IF FAILURE tests after these commands should work
as expected. For example:
CSEND blah < filename
should fail if there is no command called "blah" or if there is no file called
"filename". However, this is not foolproof and sometimes C-Kermit might think
a command succeeded when it failed, or vice versa. This is most likely to
happen when the highly system-dependent methods that Kermit must use to
determine a command's exit status code do not supply the right information.
It can also happen because some commands might define success and failure
differently from what you expect, or because you are using a pipeline composed
of many commands, and one of them fails to pass failing exit status codes up
the chain. The most likely culprit is the shell itself, which in most cases
must be interposed between Kermit and any external program to be run.
In any case, you can examine the following variable to find out the exit
status code returned to Kermit by the process most recently run by any command
that runs external commands or programs, including CSEND, CRECEIVE, REDIRECT,
RUN, etc:
v(pexitstat)
In UNIX, Windows and OS/2, the value should be -2 if no command has been run
yet, 0 if the most recent command succeeded, -1, -3, or -4 if there was an
internal error, and a positive number returned by the command itself if the
command failed. If the number is in the range 1-127, this is the program's
exit status code. If it is 128 or greater, this is supposed to indicate that
the command or program was interrupted or terminated from outside itself.
In Windows 95 and 98, the return values of the default shell are unreliable;
various third-party shells can be used to work around this deficiency.
In VMS, it is the actual exit status code of the command that was run. This
is an odd number if the command succeeded, and an even number if it failed.
You can see the associated message as follows:
run write sys$output f$message(v(pexitstat))
Or, more conveniently, use the new Kermit function:
echo ferrstring(v(pexitstat))
which converts a system error code (number) to the corresponding message.
4.2.6. Cautions about Using Pipes to Transfer Directory Trees
Although utilities such as tar and zip/unzip might be available on different
platforms (such as UNIX and Windows), this does not necessarily mean you can
use them successfully to transfer directory trees between unlike platforms.
For example:
CSEND {tar cf - . | gzip -c} {!gunzip -c | tar xf -}
when used from UNIX to Windows will have satisfactory results for binary
files, but not for text files. UNIX text files have lines ending with
Linefeed (LF) only, whereas Windows text files have lines ending in Carriage
Return and Linefeed (CRLF). Thus any text files that were in the archive
formed by the first tar command will be unpacked by the second tar command
in their original form, and will display and print incorrectly in Windows
(except in applications that have been explicitly coded to handle UNIX-format
text files). On the other hand if you told gzip to use "text mode" to do
record format conversion (assuming there was a way to tell it, as there is
with most "zip" programs), this would destroy any binary files in the archive.
Furthermore, if the archive contains text files that are written in languages
other than English, the "special" (accented and/or non-Roman) characters are
NOT translated, and are therefore likely show up as gibberish on the target
system. For example, West European languages are usually encoded in ISO Latin
Alphabet 1 in UNIX, but in PC code page 850 on the PC. Capital A with acute
accent is code point 193 (decimal) Latin-1, but 181 in CP850. So A-acute in
the UNIX file becomes Middle Box Bottom on the PC, and similarly for all the
other special characters, and for all other languages -- Greek, Russian,
Hebrew, Japanese, etc.
So when transferring text files between unlike platforms, you should use
direct Kermit file transfers so Kermit can apply the needed record-format and
character-set transformations. Use pipelines containing archivers like tar or
zip only if all the files are binary or the two systems use the same record
format and character set for text files.
Also see sections 4.3, 4.10, 4.11, and 4.15 for how to transfer directory
trees between both like and unlike systems directly with Kermit.
4.2.7. Pipes and Encryption
Of course pipelines could be used for encrypted file transfers, assuming
proper precautions could be taken concerning the transmission of the key.
But there is rarely a good way to do this. To illustrate using UNIX crypt:
csend {crypt key < filename} {!crypt key > filename}
Or, more ambitiously:
csend {tar cf - . | gzip -c | crypt key} {!crypt key | gunzip -c | tar xf -}
transmits the key in the file header packet as part of the (clear-text) remote
command, defeating the entire purpose of encrypting the file data.
But if you are connected in terminal mode to the remote computer and type:
creceive {crypt key > filename}
at the remote Kermit prompt, you have also transmitted the key in clear text
over the communications link.
At present, the only secure way to use CSEND and CRECEIVE with an encryption
filter is to have a human operator at both ends, so the key does not have to
be transmitted.
Theoretically it would be possible to use PGP software (Pretty Good Privacy,
by Phil Zimmerman, Phil's Pretty Good Software) to avoid key transmission
(since PGP uses separate public and private key and "lets you communicate
securely with people you've never met, with no secure channels needed for
prior exchange of keys"), but the specific method has yet to be worked out.
HINT: See the PGP User's Guide, e.g. at:
http://www.telstra.com.au/docs/PGP/
Especially the topic "Using PGP as a UNIX-Style Filter":
http://www.telstra.com.au/docs/PGP/pgpdoc2/pgpdoc2_17.html
In any case, better and more convenient security options are now available:
Kerberos authentication and encryption (described in the kerberos.txt file)
and the new ability to run C-Kermit "though" other communication programs,
described in Section 2.7.
4.2.8. Commands and Functions Related to Pipes
4.2.8.1. The OPEN !READ and OPEN !WRITE Commands
These are described in "Using C-Kermit", and are generally useful with reading
output from commands that produce more than one line on their standard output,
or writing multiple lines into commands that accept them on their standard
input.
In C-Kermit 7.0 CLOSE !READ is accepted as a synonym for CLOSE READ, and
CLOSE !WRITE for CLOSE WRITE.
Testing the success and failure of these commands, however, can be a bit
tricky. Consider:
open !read lalaskjfsldkfjsldkfj
(where "lalaskjfsldkfjsldkfj" is neither a valid command nor the name of a
program or script that can be run). OPEN !READ, in UNIX at least, translates
this into execl(shellpath,shellname,"-c",command). This means it starts your
preferred shell (e.g. from the SHELL environment variable) and asks it to
execute the given command. It must be this way, because your command can be a
either an internal shell command (which only your shell can execute) or an
external command, which only your shell knows how to find (it knows your PATH
and interprets, etc). Therefore unless OPEN !READ can't start your shell,
it always succeeds.
Continuing with the nonexistent-command example:
C-Kermit>open !read lalaskjfsldkfjsldkfj
C-Kermit>status
SUCCESS
C-Kermit>read line
C-Kermit>status
SUCCESS
C-Kermit>echo "m(line)"
"bash: lalaskjfsldkfjsldkfj: command not found"
C-Kermit>close read
C-Kermit>status
FAILURE
C-Kermit>
In other words, the failure can not be detected on OPEN, since the OPEN
command succeeds if it can start your shell. It can't be detected on READ,
since all this does is read output from the shell, which in this case happens
to be an error message. However, failure IS detected upon close, since this
is the occasion upon which the shell gives Kermit its exit status code.
For an illustration of this situation, see Section 2.14.
4.2.8.2. The REDIRECT Command
A second method of I/O redirection is offered by the REDIRECT command.
This is a rather advanced and tricky feature that is presently supported
only in UNIX C-Kermit, in OS-9 C-Kermit, and in Kermit 95. Syntax:
REDIRECT <command>
Runs the given <command>, sending its standard output to the current
communications channel (SET LINE, SET PORT, or SET HOST connection),
and reading its standard input from the same connection. Works only in
local mode -- i.e. a connection is required -- and then only if the given
command uses Standard I/O.
Example:
redirect finger
runs the local "finger" command and sends its output over the connection as
plain text, where presumably there is a process set up to read it. Another
example:
redirect finger | sort -r
shows the use of a pipeline.
Note: REDIRECT differs from CSEND/CRECEIVE in two important ways: (1) it does
not use the Kermit protocol, and (2) it uses a bidirectional pipe rather than
a one-way pipe.
The primary use of the REDIRECT command is to run external protocols, such as
sz/rz in UNIX for ZMODEM, when they work over Standard I/O(*). Example:
set host xyzcorp.com
(login, etc)
redirect sz oofa.zip
lets you make a Telnet connection with C-Kermit and then do a ZMODEM transfer
over it. ZMODEM protocol messages go both ways over the same connection
simultaneously.
It is possible to use C-Kermit on UNIX as your PPP dialer and then to REDIRECT
the connection to the PPP software, but C-Kermit 7.0 offers a better approach
to PPP dialing in its new EXEC command (Section 1.23).
In theory, you can also redirect an interactive process. For example, suppose
you tell Kermit 95 to wait for an incoming TCP/IP connection:
set host * 3000
and then tell C-Kermit on UNIX to:
set host kermit95hostname 3000
redirect ksh
and then tell Kermit 95 to CONNECT: now you are talking to the UNIX K-shell;
you can give commands (pwd, ls, etc) and see the results. In practice, the
K-shell's terminal modes are messed up because (a) it is not going through the
Unix terminal driver, and (b) it is "smart" and knows it is being redirected,
and so acts in a decidedly inhospitable manner (other applications like EMACS,
vi, etc, simply refuse to run if their standard i/o has been redirected).
(*) Only pre-1988 versions of the publicly-distributed sz/rz programs use
Standard I/O; those released later than that do not use Standard I/O and
therefore do not work with REDIRECT. However, Omen Technology does offer
an up-to-date redirectable version called crzsz, which must be licensed
for use.
4.2.8.3. Receiving Mail and Print Jobs
As of 7.0, and in UNIX only, files that are sent to C-Kermit as mail (when
the other Kermit uses a MAIL or SEND /MAIL command) or to be printed (via
REMOTE PRINT or SEND /PRINT) are now piped directly to the mail or print
program, rather than written to temporary files and then mailed or printed and
then deleted. This has the advantages of (a) not requiring a temporary file,
and (b) allowing mail to have a proper subject in place of the filename.
Temporary files were bad not only because they required (a) space, and (b)
writeability of the current directory, but also because using them could
result in wiping out an existing file. See section 4.7 for more about SEND
/MAIL and SEND /PRINT.
4.2.8.4. Pipe-Related Functions
The fcommand(<command>) function runs the given shell or system command and
returns the command's standard output as its value (with any newline
characters stripped from the end), unless the result is too long, in which
case it returns the empty string. The maximum length for the result is at
least 1022 bytes, and it might be longer on some platforms. Examples (UNIX):
C-Kermit> echo "fcommand(date)"
"Fri Apr 18 13:31:42 1997"
C-Kermit> echo "fcommand(finger | wc -l)" ; how many users logged in?
" 83"
C-Kermit> evaluate fcommand(finger | wc -l) * 2
166
C-Kermit> echo Welcome to fcommand(tty) on fcommand(date)
Welcome to /dev/ttyre on Fri Apr 18 13:31:42 1997
C-Kermit> echo "fcommand(ls oofa.*)"
"oofa.c
oofa.h
oofa.o"
C-Kermit> cd /directory-with-thousands-of-files
C-Kermit> echo "fcommand(ls -l)" ; This would be too long
""
C-Kermit>
If a command's output would be too long, you can use the other, more laborious
method of reading from a command: OPEN !READ <command>, READ each line,
CLOSE !READ.
The frawcommand(<command>) function is identical to fcommand(<command>),
except it does not remove trailing newline characters:
C-Kermit> echo "frawcommand(date)"
"Fri Apr 18 13:31:42 1997
"
C-Kermit> echo "frawcommand(ls oofa.*)"
"oofa.c
oofa.h
oofa.o
"
C-Kermit>
Use frawcommand() if you want to retain the final line terminators, or if
the command's output is "binary". But remember that if the result of this
(or any other) function contains any NUL (ASCII code 0) characters, the first
NUL will terminate the result string because this is how C strings work
(it's "C-Kermit", remember?).
These functions are useful not only locally, but also in the client/server
arena. If you need to get the results from a system command on the server
end into a variable on the client end, just do:
[ remote ] query kermit command(date)
The result is in the local v(query) variable; see "Using C-Kermit", 2nd Ed.,
pp.359-360 for details.
4.3. Automatic Per-File Text/Binary Mode Switching
When transferring files between like systems (e.g. UNIX-to-UNIX), binary mode
can be used for all files unless character-set translation is needed, and in
fact Kermit programs of recent vintage recognize each others' platforms and
switch to binary mode automatically when it is appropriate (e.g. DOS to OS/2,
or UNIX to UNIX). (Exception: LABELED mode is chosen for VMS-to-VMS and
OS/2-to-OS/2 transfers so complex file formats can be preserved.)
On a client/server connection between like systems, the transfer mode is
currently determined by the file sender, rather than always by the client.
If the client is sending, it controls the transfer mode. If a GET command is
sent to the server, the server sends all files in binary mode if its TRANSFER
CHARACTER-SET is TRANSPARENT; otherwise it uses text mode for text files
(according to its text-pattern list) and binary mode for binary files. Of
course, the client can control the server's transfer character-set with the
REMOTE SET TRANSFER CHARACTER-SET command.
When transferring files between unlike systems, however, (e.g. UNIX-to-DOS),
some files (such as executable program images) must be transferred in binary
mode but others (such as plain-text files) must be transferred in text mode so
their record format and character sets can be appropriately converted. If a
binary file is transferred in text mode, it is ruined. If a text file is
transferred in binary mode, then at the very least, its format can be
incorrect; at worst it is also corrupted because its character set was not
converted (in extreme cases the corruption is total, e.g. because one system
is ASCII-based and the other EBCDIC).
4.3.1. Exceptions
VMS C-Kermit, when sending files to a non-VMS system, switches to text or
binary mode automatically for each file, based on the record format in the
file's directory entry; thus the mechanisms described in this section do not
apply to VMS C-Kermit, yet the effect is the same: automatic text/binary mode
switching when VMS C-Kermit is sending files. See the VMS Appendix of "Using
C-Kermit" for details.
Kermit versions that support LABELED or IMAGE transfer mode are likewise
not affected by this feature when one of those modes is selected (normally
used only when transferring between like systems).
Kermit versions that support file-transfer pipes and filters are not affected
by this feature when pipes or filters are used, since the output of a pipe or
filter (such as gzip) is likely to require transfer in a different mode than
the original file.
Finally, SEND /TEXT or SEND /BINARY will force files to be sent in the
indicated mode, overriding all automatic transfer-mode-choosing mechanisms.
4.3.2. Overview
Suppose you give C-Kermit a command like:
SEND *.*
And suppose the pattern *.* matches a mixture of text files (such as program
source code) and binary files (such os object modules or executable programs).
C-Kermit 6.0 and earlier (except on VMS) send all files in the same mode:
whatever you said in your most recent SET FILE TYPE command, or else whatever
mode was chosen automatically according to the rules on page 236 of "Using
C-Kermit", 2nd Ed.
But when text and binary files are mixed in the same group, and the files are
being transferred to an unlike system (e.g. UNIX to IBM Mainframe), this
results in corruption of either all the text files or all the binary files.
Stream-oriented file systems such as in UNIX and DOS do not record any
information about the file to tell us whether the file should be transferred
in binary or text mode, making it impossible to select the transfer mode
for each file in a group automatically with any certainty.
However, we can use some fairly-well established file naming conventions for
this purpose. C-Kermit 7.0 lets you provide lists of filename patterns that
are used to separately determine the file type for each individual file being
transfered. A pattern is a string, possibly containing the special characters
"*" (asterisk, which matches any string of zero of more characters) and/or "?"
(question mark, which matches any single character). For example "a*b"
matches all files whose names start with "a" and end with "b", such as "ab",
"arb", "ababababab", etc, but not "abba". And "a?b" matches any file whose
name starts with "a", ends with "b", and is exactly 3 characters long.
NOTE: When typing commands at the C-Kermit prompt, you must
prefix "?" with to override its normal function of giving help.
(Also see section 4.9 for additional pattern-matching notations that might
be available in your version of C-Kermit.)
When you have specified filename recognition patterns, C-Kermit can transfer
the ones whose names match any of the binary-mode patterns in binary mode, and
those with names that match any of the text-mode patterns in text mode, and
those whose names match neither in the prevailing mode you have chosen, or
that was chosen automatically via peer recognition.
4.3.3. Commands
SET FILE PATTERNS { ON, OFF, AUTO }
This tells Kermit whether to do per-file filename pattern-matching to
determine text or binary mode. The normal and default setting is AUTO,
which means to use pattern lists to switch transfer mode only when it is
certain that the other Kermit program supports automatic notification of
transfer mode (via Attribute packets) on a per-file basis (this information
is obtained automatically during protocol startup negotiation). ON means to
always determine the transfer mode from the filename and pattern list when
sending files. Use OFF to disable this feature (without resetting your
pattern lists). Also note that if you have selected LABELED file transfer
(SET FILE TYPE LABELED), this takes precedence over filename-matching
patterns and all files are sent in labeled mode.
SET TRANSFER MODE MANUAL
Disables the use of filename patterns, no matter what the FILE PATTERNS
setting.
REMOTE SET TRANSFER MODE MANUAL
Client command to disable automatic transfer mode, and therefore also
filename patterns, in the server. Synonym: REMOTE SET XFER MODE MANUAL.
{ GET, SEND, etc } { /BINARY, /TEXT }
Including a /BINARY or /TEXT (or, where supported, /IMAGE or /LABELED)
switch with a file-transfer command changes the transfer mode to manual
for that command only, and therefore disables patterns that that command.
SET FILE BINARY-PATTERNS [ <pattern> [ <pattern> [ <pattern> ... ] ] ]
A list of zero or more patterns, separated by spaces (not commas). Letters
in a pattern are case-sensitive if the underlying filenames are case
sensitive (as in UNIX), and case-insensitive otherwise (as in Windows). If
a file's name is matched by any pattern in the list and SET FILE PATTERNS is
ON, the file is sent in binary mode. Examples:
SET FILE BINARY-PATTERNS *.gz *.Z *.tar *.zip *.o *.so *.a *.out ; UNIX
SET FILE BINARY-PATTERNS *.EXE *.ZIP *.OBJ *.COM ; DOS or OS/2 or Windows
If a pattern contains spaces, enclose it in braces.
SET FILE TEXT-PATTERNS [ <pattern> [ <pattern> [ <pattern> ... ] ] ]
Like SET FILE BINARY-PATTERNS, but the patterns choose text files rather
than binary ones. Examples:
SET FILE TEXT-PATTERNS *.TXT *.KSC *.HTM* *.BAT ; DOS, Windows, OS/2
ADD BINARY-PATTERNS [ <pattern> [ <pattern> [ <pattern> ... ] ] ]
Adds one or more patterns to the BINARY-PATTERN list.
ADD TEXT-PATTERNS [ <pattern> [ <pattern> [ <pattern> ... ] ] ]
Adds one or more patterns to the TEXT-PATTERN list.
REMOVE BINARY-PATTERNS [ <pattern> [ <pattern> [ <pattern> ... ] ] ]
Removes one or more patterns from the BINARY-PATTERN list. The given
patterns are matched with the ones in the BINARY-PATTERNS list with
case sensitivity if the underlying file system has case-sensitive names
(as do UNIX and OS-9), otherwise with case independence.
REMOVE TEXT-PATTERNS [ <pattern> [ <pattern> [ <pattern> ... ] ] ]
Removes one or more patterns from the TEXT-PATTERN list.
SHOW PATTERNS
Displays the current pattern selections.
Whenever you give a SET FILE BINARY-PATTERNS or SET FILE TEXT-PATTERNS
command, the previous list is replaced. If you give one of these commands
without a pattern list, the previous list is removed.
When patterns are active and files are being sent, text patterns (if any) are
applied first (but only if not RESENDing and not sending in LABELED mode),
then binary patterns, so if the same pattern appears in both lists, binary
mode is chosen.
4.3.4. Examples
Here's an example that might be used when sending files from UNIX:
set file type binary
set file text-patterns *.c *.h *.w *.txt makefile
set file binary-patterns *.o
msend makefile wermit wart ck*.[cwho] ck*.txt
Note that "wermit" and "wart" do not match any patterns so they are sent in
the prevailing mode, which is binary. Also note the use of "makefile" as a
pattern that does not contain any wildcard characters (there is no other
convention to distinguish among "wermit" and "wart", which are binary
executables, and "makefile", which is a text file, purely by their names).
Most C-Kermit implementations have a default pattern list built in, which
includes patterns that are almost certain to succeed in picking the right
transfer mode. Others are omitted due to ambiguity. For example ".hlp", and
".ini" are generally binary types in Windows but text types everywhere else.
NOTE: ".doc", used for decades to denote plain-text documentation
files, now more often than not denotes a Microsoft Word Document, so
".doc" is now considered a binary type since it does less harm to
transfer a plain-text document in binary mode than it does to transfer
an MS Word file in text mode (except when IBM mainframes are involved!)
ANOTHER NOTE: ".com" files are binary in DOS-like operating systems,
but they are text (DCL command procedures) in VMS. VMS C-Kermit sends
.COM files in text mode; K95 sends them in binary mode. If you download
a .COM file from VMS to DOS or Windows, and then upload it to another
VMS system, be sure to use SEND /TEXT to preserve its textness.
You can see the default pattern list by starting C-Kermit without its
initialization file (e.g. "kermit -Y") and using the SHOW PATTERNS command.
If you will be depending on this feature, be sure to examine the list
carefully in conjunction with the applications that you use.
The default pattern list does not take "backup files" into account because
(a) people usually don't want to transfer them; and (b) it would make the
pattern lists more than twice as long. For example, we would need to include
both *.txt and *.txt.~[0-9]*~ for ".txt" files, and similarly for all the
others. Instead, you can use SEND /NOBACKUP (or SET SEND BACKUP OFF) to
skip over all backup files.
Put your most commonly-used safe pattern declarations in your C-Kermit
customization file (ckermod.ini, .mykermrc, k95custom.ini, etc).
As noted, SET FILE PATTERNS is ON by default. Sometimes, however, it is
desirable, or necessary, to force files to be sent in a particular mode, and
often this must be done from the command line (e.g. when using Kermit as a
download helper in a Web browser like Lynx). The -V command-line options is
equivalent to SET FILE PATTERNS OFF and SET TRANSFER MODE MANUAL. Example:
kermit -Vis oofa.txt
forces oofa.txt to be sent in binary mode, even though ".txt" might match a
text pattern.
4.4. File Permissions
"Permissions" refers to a code associated with a file that specifies who is
allowed to access it, and in what manner. For example, the owner, the members
of one or more groups, the system administrator, and everybody else, might be
allowed various combinations of Read, Write, Append, Execute, or Listing
access.
The permission code goes by different names on different platforms. In UNIX,
it might be called the filemode. In VMS, it is called the file protection
(or protection mask).
The comments in this section presently apply only to the UNIX and VMS versions
of C-Kermit, to which these features were added in version 7.0; the DOS,
Windows, and OS/2 file systems embody no notions of protection, and so MS-DOS
Kermit and Kermit 95 do not send file permissions, and ignore them when
received.
The permissions for a received file are determined by a combination of the
file transfer mode (VMS-to-VMS transfers only), whether a file of the same
name exists already, whether permissions of the file are received in the file
attribute packet, and the setting of ATTRIBUTES PROTECTION.
The default for ATTRIBUTES PROTECTION is ON. If no attributes are received,
the effect is the same as if attributes PROTECTION were OFF.
For VMS-to-VMS transfers, the default LABELED mode simply copies the
protection code from source to destination.
4.4.1. When ATTRIBUTES PROTECTION is OFF
If no file of the same name exists, system defaults determine the permissions
of the new file. Otherwise, the actions taken depend on the current FILE
COLLISION setting: BACKUP, OVERWRITE, RENAME, etc, as documented in "Using
C-Kermit". But now the new file (if it is created at all) automatically
inherits the permissions (mode bits) of the existing file in a way that is
appropriate for the platform.
4.4.1.1. Unix
All mode bits are inherited except the directory bit, since the
incoming file can not possibly be a directory. (In any case, it is not
possible to receive a file that has the same name as an existing directory
unless FILE COLLISION is set to RENAME).
4.4.1.2. VMS
Files with the same name as an existing file, transferred in modes other than
LABELED between VMS systems, inherit the protection of the prior version.
4.4.2 When ATTRIBUTES PROTECTION is ON
File permissions can be conveyed as part of the file transfer process, in
accordance with the Kermit protocol definition. If the file sender puts
system-dependent and/or system-independent versions of the file protection
(permissions) into the Attribute (A) packet, the file receiver can set the new
file's permissions from them. Otherwise, the permissions are set the same as
for ATTRIBUTES PROTECTION OFF.
When the incoming A packet contains system-dependent permissions, the file
receiver checks to see if the sender has the same system ID (e.g. both the
sending and receiving systems are UNIX, or both are VMS); if so, it decodes
and uses the system-dependent permissions; otherwise it uses the generic ones
(if any) and applies them to the owner field, setting the other fields
appropriately as described in the following sections.
Setting the incoming file's protection from the A packet is controlled by SET
ATTRIBUTES PROTECTION (or PERMISSION), which is ON by default, and its status
is displayed by SHOW ATTRIBUTES.
The main benefit of this feature is to not have to "chmod +x" an executable
file after transfer from UNIX to UNIX. Its cross-platform benefits are less
evident, perhaps to retain the status of the Unix 'x' bit on a VMS system,
for subsequent transfer back to a Unix system.
4.4.2.1. System-Specific Permissions
System-specific file permissions are used when the two Kermit programs
recognize each other as running on the same type of system. For example,
both are running under some form of UNIX (it doesn't matter which UNIX
variation -- HP-UX, Solaris, AIX, etc -- all use the same scheme for file
permissions); or both are running under VMS (even if one is on an Alpha and
the other on a VAX, and/or one is old and the other is new).
4.4.2.1.1. UNIX
UNIX supports three categories of users, File Owner, Group, and World,
and three types of file access permission: Read, Write, and Execute. Thus,
a UNIX file's permissions are expressed in 9 bits.
The system-dependent permission string for UNIX is a 3-digit octal string, the
low-order 9 bits of the st_mode member of the stat struct; we deliberately
chop off the "file format" bits because they are not permissions, nor do we
convey the setuid/setgid bits, lock bit, sticky bit, etc.
4.4.2.1.2. VMS
VMS supports four categories of users, System, File Owner, Group, and World,
and four types of file access permission: Read, Write, Execute, and Delete.
Thus, a VMS file's permissions are expressed in 16 bits.
The system-dependent protection string for VMS is a 4-digit hexadecimal
string, corresponding to the internal-format protection word of the file
(RWED for each of World,Group,Owner,System). A new file normally gets all 16
protection bits from the original file of the same name.
Note: VMS-to-VMS transfers take place in LABELED mode when the two C-Kermits
recognize each other's platform as VMS (unless you have disabled LABELED-mode
transfers). In this case, all of a file's attributes are preserved in the
transfer and the protection mask (and other information) is taken from the
file's internal information, and this takes precedence over any information
in the Attribute packets. You can defeat the automatic switching into
LABELED mode (if you want to) with SET TRANSFER MODE MANUAL.
4.4.2.2. System-Independent Permissions
The system-independent ("generic") protection is used when the system IDs of
the two Kermit programs do not agree (e.g. one is UNIX, the other is VMS).
The generic protection attribute includes the following permissions (not all
are applicable to every file system): Read, Write, Append, Execute, Delete,
Search. The generic permissions are derived from the owner permissions of
the source file, thus, a Unix 'w' permission becomes VMS Write,Delete.
The Owner field of the new file's permissions is set from the incoming
generic protection attribute.
In UNIX, the Group and World permissions are set according to your umask,
except that execute permission is NOT set in these fields if it was not also
set in the generic protection (and consequently, is set in the Owner field).
In VMS, the System, Group, and World permissions are set according to the
process default file permission (as shown in VMS by SHOW PROTECTION), except
that no permissions are allowed in these fields that are not included in the
generic permissions.
Note that the VMS and UNIX interpretations of Execute permission are not
identical. In UNIX, a file (binary executable, shell script, etc) may not
be executed unless it has Execute permission, and normally files that are
not intended for execution do not have Execute permission. In VMS, Read
permission implicitly supplies Execute capability. Generally files that have
Read permission also have explicit Execute permission, but files (binary
executables, DCL command procedures) that have Read permission and not
Execute permission can still be executed.
4.5. File Management Commands
4.5.1. The DIRECTORY Command
Prior to C-Kermit 7.0, the DIRECTORY command always ran an external system
command (such as "ls" on UNIX) or program to product the directory listing.
This had certain advantages, mostly that you could include system-dependent
options for customized listings, e.g. on UNIX:
dir -lt c* | more
or in VMS:
directory /size/date/protection/except=*.obj oofa.*;0
This approach, however, carries some disadvantages: C-Kermit can't return
SUCCESS or FAILURE status for (e.g.) "dir foo" according to whether the file
"foo" exists; and it runs an inferior process, which might be a problem in
some environments for resource and/or security reasons, and won't work at all
in a "nopush" environment (e.g. one in which C-Kermit is configured to forbid
access to exterior commands and programs, e.g. in a VMS "captive account").
In C-Kermit 7.0 on VMS and UNIX, and in K95 1.1.18 and later, the DIRECTORY
command is internal to Kermit. It can be run in a "nopush" environment and
returns SUCCESS or FAILURE status appropriately. In UNIX it prints all dates
and times in a consistent way (unlike ls). In VMS it prints precise file
sizes, rather than "blocks". It offers several formatting and other options,
but it is not necessarily more flexible than the corresponding external
commands or programs (the UNIX "ls" program, the VMS "directory" command).
The syntax is:
DIRECTORY [ switch [ switch [ ... ] ] ] [ filespec ]
If no filespec is given, all files in the current directory are listed.
Optional switches include all the standard file-selection switches presented
in Section 1.5.4, plus:
/ALL
Show both regular files and directories; this is the default.
/ARRAY:x
Instead of displaying a directory listing, put the files that would have
been shown (based on the filespec and other selection switches) in the
given array. The array need not (and should not) be predeclared; if the
array already exists, it is destroyed and reused. The array name can be a
single letter, like "a", or any fuller form, such as "&a", "&a", "&a[]",
etc. If the /ARRAY switch is included, the following other switches are
ignored: /BRIEF, /VERBOSE, /HEADING, /PAGE, /ENGLISHDATE, /ISODATE,
/XFERMODE, /MESSAGE, /SORT, /REVERSE, /ASCENDING. In other words, only
file selection switches are meaningful with /ARRAY: /FILES, /DIRECTORIES,
/ALL, /DOTFILES, /NOBACKUP, /RECURSIVE, /SMALLER, /LARGER, /AFTER,
/BEFORE, /EXCEPT, etc. The resulting array has the number of files (n) as
its 0th element, and the filenames in elements 1 through n. Example:
dir /array:&a /files /nobackup /after:19990101 /larger:10000 [ab]*
show array &a
/FILES
Only show regular files.
/DIRECTORIES
Only show directories.
/BACKUP
In UNIX, OS-9, K-95, and other versions that support SET FILE COLLISION
BACKUP and create backup files by appending .~n~ to the filename (where
"n" is a number), /BACKUP means to include these files in directory
listings. This is the default.
/NOBACKUP
This is the opposite of /BACKUP: that is, do not include backup files in
the listing.
/BRIEF
List filenames only; use a compact format, as many filenames as will fit
across the screen (based on the longest name). A brief listing is always
sorted alphabetically.
/VERBOSE
List one file per line, and include date, size, and (in UNIX only)
permissions of each file. This is the opposite of /BRIEF, and is the
default.
/PAGE
Pause at the end of each screenful and give a "more?" prompt, even if
SET COMMAND MORE-PROMPTING is OFF.
/NOPAGE
Don't pause at the end of each screenful and give a "more?" prompt, even if
SET COMMAND MORE-PROMPTING is ON. If neither /PAGE or /NOPAGE is given,
paging is according to the prevailing COMMAND MORE-PROMPTING setting (which
can be displayed with SHOW COMMAND).
/ENGLISHDATE
Show dates in dd-mmm-yyyy format; mmm is the first three letters of the
English month name.
/ISODATE
Show dates in yyyy-mm-dd format; mm is the month number, 1-12.
This is the opposite of /ENGLISHDATE, and is the default.
/HEADINGS
Print a heading before the listing and a summary at the end.
/NOHEADINGS
Don't print a heading before the listing or a summary at the end.
This is the opposite of /HEADINGS, and is the default.
/XFERMODE
Only in Kermit programs that support SET FILE PATTERNS. If this switch is
included, and the filename matches any FILE BINARY-PATTERN (Section 4.3),
"(B)" is printed after the filename; otherwise, if it matches a FILE
TEXT-PATTERN, "(T)" is printed.
/NOXFERMODE
Don't display transfer-mode indicators. This is the opposite of /XFERMODE
and is the default.
/RECURSIVE
Show files not only in the given directory, but also in its subdirectories
(if any), their subdirectories, etc.
/NORECURSIVE
Don't show files in subdirectories. This is the opposite of /RECURSIVE,
and is the default.
/MESSAGE:text
This lets you specify a short text string to be appended to the end of
each directory listing line (a space is supplied automatically). If the
text contains any spaces, enclose it in braces, e.g. /MESSAGE:{two words}.
/NOMESSAGE
Don't append any message to the end of each directory listing line
(default).
/SORT:[{NAME,SIZE,DATE}]
Sort the listing by name, size, or date. If the /SORT switch is given
but the "sort-by" keyword is omitted, the listing is sorted by name.
/SORT:NAME /ASCENDING (alphabetic sort by name) is the default.
/NOSORT
Don't sort the listing. Files are listed in whatever order they are
supplied by the operating system, e.g. inode order in UNIX.
/REVERSE
If the /SORT switch is given, reverse the order of the sort.
Synonym: /DESCENDING.
/ASCENDING
If the /SORT switch is given, sort the listing in normal order.
This is the opposite of /REVERSE and is the default.
Note that most of the DIRECTORY-specific switches come in pairs, in which
one member of a pair (e.g. /NOHEADINGS) is the opposite of the other
(e.g. /HEADINGS).
If you always want to use certain options, you can set them with the SET
OPTIONS DIRECTORY command (Section 1.5.5). Use SHOW OPTIONS to list the
options currently in effect. To make the desired options apply every time you
run C-Kermit, put a SET OPTIONS DIRECTORY command in your C-Kermit
customization file, specifying the desired options. Options set in this
manner apply to every subsequent DIRECTORY command. Of course, if you include
switches in a DIRECTORY command, these override any defaults, built-in or
custom. Example:
DIRECTORY ; Use "factory defaults"
SET OPTIONS DIRECTORY /SORT:SIZE /REVERSE /HEADINGS ; Customize defaults
DIRECTORY ; Use customized defaults
DIR /SORT:NAME ; Override customized default SORT key
SET OPT DIR /RECURS ; Add /RECURSIVE to customized defaults
DIR /ASCEND ; Override customized default SORT order
Notes:
. Only a single sort key is supported; there is presently no way to
have multiple sort keys.
. If the /BRIEF switch is given, all other switches (except /[NO]RECURSIVE,
/[NO]DOTFILES, /DIRECTORIES, /FILES, and /ALL) are ignored.
. /SORT:<anything> gives incorrect results if any files have lengths
greater than 10 digits (i.e. that are more than 9999999999 bytes long, i.e.
if they are 10GB or more in size) because the overlong length field causes
the date and name fields to be misaligned.
. /SORT:NAME is redundant in VMS since VMS returns filenames in alphabetic
order anyway.
. /SORT:NAME ignores alphabetic case on platforms where case does not matter
in filenames, but this works only for unaccented Roman letters A-Z.
. /SORT:NAME is currently based on code values, and so works fine for ASCII,
but will probably produce unexpected results for files with non-ASCII or
8-bit characters in their names. (Locale-based sorting raises rather
significant issues of portability, size, performance, etc.)
. /SORT:DATE works right only for ISO-format dates, not English ones.
. /SORT:SIZE sorts the size field lexically. On some platforms
(e.g. Windows), the size of a directory file is listed as "<DIR>" rather
than as a number; in this case, the "<DIR>" files are gathered at the end
(or beginning, depending on the sort order) of the listing.
. /RECURSIVE is accepted but ignored in AOS/VS. Use the normal
system-specific filespec notation, e.g. "dir #.txt".
. /RECURSIVE has no affect when a full, absolute pathname is given; e.g.
"dir /recursive /tmp/foo" (where "foo" is a regular file) only shows the
"/tmp/foo" file. If you want to see all "foo" files in the /tmp tree,
do "cd /tmp" and then "dir /recursive foo".
. If a file size of -1 is shown, or date-time of 0000-00-00 00:00:00, this
means the file was located, but access to information about the file was
denied to C-Kermit.
. In VMS, if FOO.DIR;1 is a directory within your current directory,
"directory foo" and "directory [.foo]" list the files in the [.FOO]
subdirectory, but "directory foo.dir" lists the directory file itself;
similarly for "*.dir" versus "[.*]", etc.
. In UNIX, if "foo" is a directory within your current directory,
"directory foo" lists the files in the foo directory. If you want to
list the foo directory file itself, put an asterisk at the end:
"dir foo*".
Hint: How to find the biggest files in a directory tree:
cd xxx ; (root of tree)
directory /sort:size /recursive /reverse /dotfiles /page
Another hint: If you often use several different directory-listing formats,
define macro shortcuts for them:
DEFINE WD DIRECTORY /SORT:DATE /REVERSE %* ; Reverse chronological order
DEFINE SD DIRECTORY /SORT:SIZE /REVERSE %* ; Reverse order of size
DEFINE ND DIRECTORY /SORT:NAME /ASCEND %* ; Alphabetical by name
DEFINE DL DIR /DIR /SORT:NAME /ASCEND %* ; Alphabetical directory list
Put these definitions in your C-Kermit customization file. Note that "%*"
(Section 7.5) in these definitions lets you include other switches in your
macro invocations, e.g.:
wd /headings *.txt
Of course you can still access your external directory listing program by
using RUN or "!", e.g. in VMS:
run directory /size/date/protection/except=*.obj oofa.*;0
or:
!dir /size/date/prot/exc=*.obj oofa.*;0
In UNIX, use "!ls" or just "ls" (which is a special synonym for "!ls").
4.5.2. The CD and BACK Commands
In 7.0, the CD command has a new friend, the BACK command. BACK
means "CD to my previous current directory". A second BACK brings you back
to where you were before the first one; thus successive BACK commands switch
back and forth between two directories.
4.5.2.1. Parsing Improvements
The CD command, as well as other commands that parse a directory name, were
changed in 7.0 to provide all the expected functions: completion on Tab
or Esc, directory-name lists on ?, etc. Other affected commands include
SET SERVER GET-PATH, SET TEMP-DIRECTORY, SET FILE DOWNLOAD-DIRECTORY, and
SPACE. CD and REMOTE CD also now work with logical names.
In VMS, the situation is a bit complicated since a directory name can look
like "DEV:", "[FOO.BAR]", "DEV:[FOO.BAR]", "[FOO]BAR.DIR;1", etc. Completion
and ?-help might not always work, but they do in many cases. Examples:
cd ? Lists all subdirectories of the current directory
cd []? Ditto
cd k? Ditto, but only those starting with K
cd [foo]? Lists all subdirectories of the [FOO] directory
cd [-]? Lists all subdirectories of the superior directory
cd [--]? Lists all subdirectories of the directory 2 levels up
cd [...]? Lists all directories below the current one
cd [foo.? Does not work.
C-Kermit allows all of the following in VMS:
cd bar CD to subdirectory BAR of the current directory
cd .bar Ditto
cd [.bar] Ditto
cd bar.dir etc...
cd bar.dir;
cd bar.dir;1
cd [foo.bar]
cd bar.baz This can go more than 1 level deep...
cd dir: (where logical name DIR is defined as [FOO.BAR])
As well as the following:
cd .. Go up one level as in UNIX
cd . The current directory
cd My login directory
Note that "cd -" (go up one level) does not work as expected, because "-" is
Kermit's command continuation character. However, "cd [-]", and "cd {-}" have
the desired effect (and so does "cd ..", which is easier to type).
4.5.2.2. The CDPATH
The CD command in the UNIX, Windows, OS/2, and VMS versions of C-Kermit, as of
version 6.1 / 1.1.12, searches the CDPATH for the given directory, if it is not
absolute and if a CDPATH environment variable is defined. Example (in UNIX
ksh or bash):
$ export CDPATH=$HOME:$HOME/kermit:/tmp
Now if you give a "cd xxx" command, no matter what your current directory is,
if the "xxx" directory is not a subdirectory of your current directory, then
the xxx subdirectory of your home directory is used or if that does not exist,
then the xxx subdirectory of the kermit subdirectory of your home directory is
used or if that does not exist, then /tmp/xxx is used. This is how the ksh
"cd" command works, and now the C-Kermit CD command works the same way.
In VMS, you can define CDPATH to be a list of directories that contain actual
directory delimiters, and/or logical names representing directories, using
commas to separate them, e.g.:
$ define cdpath [HOME],[SOMEOTHERDIR],[HOME.MISC]
or:
$ define cdpath SYS$LOGIN:,DISK1:[HOME],DISK2:[SCRATCH.IVAN]
Example:
$ define cdpath SYS$LOGIN:,[IVAN],[OLAF],[OLGA.MISC]
$ kermit
DISK1:[OLGA] C-Kermit> cd blah
tries the BLAH subdirectory of the user's login directory, then [OLGA.BLAH],
[IVAN.BLAH], [OLAF.BLAH], and [OLGA.MISC.BLAH], in that order, using the first
one it finds, failing if it finds none.
In C-Kermit 7.0, you may also set the CDPATH from the Kermit prompt:
SET CD PATH <path>
Allows the CD PATH to be set from within C-Kermit.
SHOW CD shows the CD path and all other information relevant to the CD command.
4.5.2.3. CD Messages
Whenever you change directory, you can have C-Kermit display a "Read Me" file
from the new directory automatically. The commands are:
SET CD MESSAGE { ON, OFF, FILE <list> }
ON enables this feature; OFF (the default) disables it. File lets you
specify the name of the "Read Me" file. A list of names to look for can be
given in the following format:
{{name1}{name2}{name3}{...}}
e.g. SET SERVER CD-MESSAGE FILE {{./.readme}{README.TXT}{READ.ME}}
The default list of CD-message files is system dependent.
SHOW CD shows your current directory, previous directory, CD path, and CD
message info.
4.5.3. Creating and Removing Directories
The MKDIR command now allows you to create multiple directories at once:
C-Kermit> mkdir a/b/c/d
creates the directory a in the current directory (if it doesn't exist
already), and then creates a subdirectory b of the a directory (if it didn't
exist already), and so on.
If you use MKDIR to try to create a directory that already exists, C-Kermit
will print a warning ("?Directory already exists"), but the MKDIR command
will still succeed. If you want to avoid the warning message, use
IF DIRECTORY first to check if the directory already exists.
The RMDIR command, however, will not remove more than one directory, nor
will it remove a directory that contains any files. (There is, as yet, no
RMDIR /RECURSIVE command, although one might be added later.)
In VMS, these commands (like CD) are more forgiving of your syntax than is the
DCL command shell; "mkdir oofa" is equivalent to "mkdir [.oofa]" and so on.
Also in VMS, you'll find that C-Kermit's RMDIR command is easier than deleting
a directory in DCL, since it automatically first gives it owner delete
permission if you are the owner.
4.5.4. The DELETE and PURGE Commands
The DELETE command now offers a selection of switches, and has a new
companion, the PURGE command. First, DELETE:
DELETE [ switches... ] filespec
Deletes the file or files that match the filespec, which may contain
wildcards (Section 4.9).
Optional switches include the standard file-selection switches presented in
Section 1.5.4, plus:
/ASK
Before deleting each file, ask permission interactively. Answers are
Yes or OK (delete the file), No (don't delete it), or Quit (stop executing
the DELETE command).
/NOASK
Don't ask permission to delete each file.
/LIST
List each file and show whether it was deleted. Synonyms: /LOG, /VERBOSE.
/NOLIST
Don't list files while deleting them. Synonyms: /NOLOG, /QUIET.
/HEADING
Print a heading and summary line.
/NOHEADING
Don't print a heading and summary line.
/PAGE
When listing, pause at the end of each screenful and give the "More?"
prompt. If you reply "n" (no), the DELETE command terminates.
/SIMULATE
Do everything implied by the given switches and filespec, except do not
actually delete any files. This lets you preview which files would be
deleted; implies /LIST.
Now the PURGE command:
PURGE [ switches... ] [ filespec ]
(VMS only) Runs the DCL PURGE command. Switches and filespec, if any,
are passed directly to DCL without parsing or verification. Deletes
excess versions of the given (or all) files. The rest of this section
does not apply to VMS.
PURGE [ switches... ] [ filespec ]
(UNIX only) Deletes "backup files" that match the filespec, which may
contain wildcards (Section 4.9). If no filespec is given, all backup
files in the current directory are selected (subject to modification by
any switches). Do not include backup notation in the filespec.
Explanation:
To avoid destroying preexisting files when a new file arrives that has the
same name, C-Kermit backs up the old file by appending a "backup number" to
its name. In UNIX, the backup suffix consists of a period, a tilde, a number,
and another tilde. For example, if a file called oofa.txt exists and a new
oofa.txt file arrives, the original is renamed to oofa.txt.~1~. If another
oofa.txt file arrives, the existing one is renamed to oofa.txt.~2~. And so
on. This system is compatible with the one used by EMACS. Thus over time, if
you receive a lot of files with C-Kermit or edit them with EMACS, backup files
can build up. The new PURGE command lets you clean out accumulated backup
files:
Optional switches include the standard file-selection switches presented in
Section 1.5.4, plus all the switches listed above for the DELETE command,
plus:
/KEEP:n
Retains the 'n' most recent (highest-numbered) backup files for each file.
For example, if oofa.txt, oofa.txt.~1~, oofa.txt.~2~, oofa.txt.~10~,
oofa.txt.~12~, and oofa.txt.~100~ exist, "purge /keep:2 oofa.txt" deletes
oofa.txt.~1~, oofa.txt.~2~, and oofa.txt.~10~, and keeps oofa.txt,
oofa.txt.~12~, and oofa.txt.~100~. If /KEEP is given without a number,
one (the highest numbered) backup file is kept.
CAUTION: The PURGE command should be used only when *.~*~ files truly are
backup files. This is the case for EMACS, and it is the DEFAULT for C-Kermit.
However, if C-Kermit's FILE COLLISION has been set to RENAME, newly received
files will look like backup files. In that case, don't use the PURGE command
or you'll be removing new files rather than old ones. (Use SHOW FILE to find
the FILE COLLISION setting.)
The PURGE command is presently available only in UNIX. The command succeeds
if it deleted any files, or if it deleted no files but there were no errors.
It fails if it deleted no files and there were errors (i.e. deletion was
attempted but failed). In VMS, backup file versions are handled automatically
by the OS, and a PURGE command can be used at the VMS prompt to clean them up.
If you want certain switches to be supplied automatically with each DELETE or
PURGE command, you can set them with SET OPTIONS (Section 1.5.5) and you can
display any such settings with SHOW OPTIONS. Of course you can override them
on a per-command basis by including switches in your PURGE or DELETE command.
Also see SET FILE COLLISION, SHOW FILE, SEND /NOBACKUP, SET SEND BACKUP, and
DIRECTORY /[NO]BACKUP.