kfl (05/05/83)
YAM (Yet Another Modem program)
by Chuck Forsberg
******** Highlights ********
Conversational mode with optional capture to file and
multiple page review of past output. File capture of
long files works with any system which responds to XOFF
within 400 characters.
Flexible uploading of suitable files to many types of
remote systems, even Bulletin Boards without normal
uploading capability.
Error checking file exchange with programs using Ward
Christensen's protocol with optional Cyclic Redundancy
Check. Enhanced error recovery and transfer abort
logic.
Batch transmission of files with compatible programs.
High speed operation; 9600 baud file transfer and
conversational terminal operation, buffered printer
operation at >>1200 baud. Full printer buffering
allows use of slow printers, or printers with burst
transfers (line printer, MX80, etc.). Function key
escape sequences can be buffered, wllowing proper
operation when keyboard baudrate exceeds modem baud
rate.
Disk utility functions including directory listing,
change disk and/or user number, erase files, disk free
space calculation, file transfer time calculation, CRCK
file check, and local listing of files. Great
flexibility in specifying filenames. New data may be
appended to existing ASCII files. Optionally, YAM can
maintain log of files sent and/or received with disk,
filename, baud rate, and the name of the remote system.
Able to send files to TWX type machines.
Matching program (XYAM) for use by remote systems as
XMODEM replacement obtained from same source files,
allows batch transfer of files with full CRC checking.
Matching programs (sb.c and rb.c) are available for
Version 7 and System III Unix(tm).
Written in a modern high level systems language ( C )
for ease of portability and maintenance.
Manual Revised 01-04-83 Page 1
YAM/XYAM 3.44 Manual Page 2
******** Rosetta Stone ********
CAPTURE
When in the T(term) function, ALL data coming from the
remote is captured in a circular buffer.
DUMPING
When a receive file is open as a result of a "t
filename" command, and the circular buffer is nearly
full, that data is written out to the receive file if
Dumping is on. Setting Squelch mode (see below) turns
Dumping off until a ^R character is encountered.
FUNCTION
An operation supported by yam, such as DIR, TYPE, S, R,
or T(term). A command may set or reset a MODE, or
perform 0 or more FUNCTIONS.
IFF
If and only if.
MODE
Many modes affect the way the term function handles
data.
OPTION
Option(s) apply to the S and R commands only.
PREFIX
A letter that prefixes a command to modify its action.
TWX
Teletypewriter Exchange (Teletype Copr. TM). A
protocol (of sorts) used to send files (usually paper
tape) between Teletype machines.
{}
Required argument.
[]
Optional argument.
pattern ...
An empty pattern represents all files on the default
disk with the current user number. A disk identifier
without filename represents all files on that disk with
the current user number. Unambiguous and ambiguous
filenames may be specified in any combination. A
pattern may contain any combination of the above.
Manual Revised 01-04-83 Page 2
YAM/XYAM 3.44 Manual Page 3
******** Prefixes and Commands ********
-{mode[s]}
Enable mode(s) affecting file transmission/reception
with the term function. (The "s" and "r" commands
always send data transparently.)
a:
Change to a: disk (or b, etc.) CP/M versions print the
free disk space in kilobytes.
a1:
Change to a: disk user 1 WARNING: Do NOT change user
number when file(s) are open; CP/M 2.2 gets terribly
confused. CP/M versions print the free disk space in
kilobytes.
a
Archive prefix. When used with any command that
accepts wildcards, causes files with the F3 ("Tag3")
bit set to be excluded. When used with the s or dirr
commands, causes the F3 bit to be set after successfull
completion of operations on each file. This facility
may be used to selectively transmit only those files
that have been changed since the last transmission.
The user should verify that the F3 bit is reset when
files are changed by particular programs (such as
Mince).
bm
Set baudrate to m. Example: "b19200" NOTE: some 212
type modems work better if the baud rate is set to
slightly less than 1200 baud; e.g., 1180 baud.
bye
Dump any call in progress by dropping DTR (data
terminal ready). A call or b (set baudrate) command
must be given to reassert DTR before making or
answering another data call.
call name
Searches the PHONES file for name. If the search is
successful, enable Data Terminal Ready (DTR), and set
baudrate to the value (if present) corresponding to
name. NOTE: some 212 type modems work better if the
baud rate is set to slightly less than 1200 baud; e.g.,
1180 baud. If autodial is supported, dial the
telephone number. The specifics of autodial operation
may vary with the implementation. If autodial is not
supported, the telephone number is displayed. It is
Manual Revised 01-04-83 Page 3
YAM/XYAM 3.44 Manual Page 4
not necessary to type the entire name as it appears in
the file, as YAM will find the first entry that matches
name. Example: "call tcbbs" or "call tc"
chat
Chat keyboard to keyboard. Characters typed by either
keyboard are echoed to both ends, and RETURNS echo as
RETURN/LINEFEED. Chat will become hostile if the other
end also echoes characters.
close
Dump capture buffer if a receive file is open, close
files.
crck [pattern ...]
Perform the "crck" function on the specified files.
The "crck" algorithm is stolen from version 4.3
CRCK.ASM.
dir [pattern ...]
Display pathnames matching pattern alphabetized across
the page. The usual ambiguous filenames are allowed
under CP/M provided a correct version of setfcb() is
used. Since dir or any other commands which accept a
pattern use the circular buffer for filename expansion,
be sure to write out any captured data first! Example:
"dir" "dir *.c" "dir yam*.c" "dir *.c *.h"
dirr [pattern ...]
Displays the directory with the number of sectors in
each file. The number of files matched, number of
blocks, number of kb allocated to those files, and
estimated transmission time at the current baudrate for
all files listed are displayed. Transmission time
estimate is based on batch transmission from a Z89 with
700kb Tandon drives to a Cromemco 4mHz 4fdc system with
Persci 277 drive. Time includes file i/o but not error
correction.
d{mode[s]}
Disable mode(s) affecting file transmission or
reception with the term function. (The "s" and "r"
commands always send data transparently.)
erase pattern ...
Erase the named files. For each matched pathname, the
user is prompted for Y, N, or Q. Y erases the file, N
skips to the next file, and Q or anything else aborts
the command. The number of free blocks on the default
disk is displayed.
Manual Revised 01-04-83 Page 4
YAM/XYAM 3.44 Manual Page 5
e{mode[s]}
Enable mode(s) affecting file transmission/reception
with the term function. (The "s" and "r" commands
always send data transparently.)
flip {ans,org}
Flip the local modem between answer and originate
modes. This command is not supported by all versions
of YAM. See FLIP.
f[mode[s]] name
Send file 'name' in the term function. The optional
mode enables one or modes. If squelch is enabled,
preface with ^R and append with ^T. If Q mode is
enabled, name is opened, sending is stopped, and YAM
remains in command mode. See also type/list command.
help
Displays a command summary. This command closes any
open send file.
initialize
Initializes yam to all its default values. Does not
reset the disk system (see "reset").
kill
Kill all data in the capture buffer. Restores the
pointers to their initial positions.
link
Link two ports. Assuming correct port settings (see
yam3.c), characters from the MODEM port are sent to the
port selected with the Mport command. Characters
received from the port selected are buffered in the
circular buffer and transmitted to the MODEM. Keyboard
characters are sent to the slected port. Operation
assumes that MODEM port is the slower of the two. Exit
from this term - like mode is with kbd control E.
list pattern [...]
List the file(s) specified by one or more possibly
ambiguous pattern(s). This command closes any open
send file. Yam or Xyam compiled with USQ defined will
automatically detect squeezed files and print them in
ASCII. List stops/resumes printing with ^S.
Keyboarding ^X cancels, and ^K skips to the next file
(it might take a few whacks of the keyboard to get YAM
to hear it.) XYAM prefaces each file with ^R and
suffixes it with ^T. The standard putchar() is used,
so tabs and newlines are expanded. The printer can be
enabled with ^P on the command line. Because tabs are
Manual Revised 01-04-83 Page 5
YAM/XYAM 3.44 Manual Page 6
expanded, files containing tabs will get larger if
downloaded with the list command; if you can't use the
s command, at least use type. Likewise, because
newlines are expanded to cr/lf, there will usually be
two carriage returns per line.
mn
Change modem data port to (decimal) n. Example: "m224"
o
Disable the modem by turning off DTR.
off
Disable modem and return to operating system.
pxm
Set Parameter x to value m.
reset [size]
Dump the capture buffer; if a file is open, close all
files, and reset CP/M's disk system. This allows
swapping diskettes. The optional argument size becomes
the size of the circular capture buffer, useful for
debugging.
replot [m]
Redisplay the last m lines received from the modem. If
m is 0 or absent, redisplay starting with the earliest
data. A screenful is displayed at a time. The
commands accepted in replot mode are listed below.
rewind
Rewind the buffer pointers for the display, printer,
and file dump from the term function. The effect of
this command is the same as if the data had been sent
another time.
r[options] [file ...]
Receive with options 1 or more files using the Ward
Christensen protocol. If no filename is given, batch
mode is assumed. (Note: batch mode is not compatible
with MODEM7.) If more than one filename is given, a
single file transfer will be made for each. If the
RESTRICTED option is defined, a file received in error
will be unlinked (erased).
s
Displays status information.
s[options] pattern ...
If batch mode is specified with the b option, 0 or more
Manual Revised 01-04-83 Page 6
YAM/XYAM 3.44 Manual Page 7
files are sent according to the ambiguous pathname(s).
If batch mode is not specified, the named unambiguous
file(s) are sent each in single file mode.
type pattern [...]
Type the file(s) specified by one or more possibly
ambiguous pattern(s). This command closes any open
send file. Yam or Xyam compiled with USQ defined will
automatically detect squeezed files and print them in
ASCII. Type stops/resumes printing with ^S.
Keyboarding ^X cancels, and ^K skips to the next file.
XYAM prefaces each file with ^R and suffixes it with
^T. Direct console output (bios(4, ...) is used.
t[c][mode] [file]
The term function with optional capture to file. 0 or
more modes may be enabled. The c (close) option causes
data in the capture buffer to be written and closed
immediately. View mode causes the term function to
display control characters by prefixing ^ to the
corresponding letter. A receive file previously opened
by 't file' will not be closed by 't'.
Keyboarded characters are treated in either of two ways
depending on the value of Exitchar (see parameters,
below). If Exitchar is non zero, term will return when
a character matching Exitchar is keyboarded, and all
others are passed without any special action.
Otherwise, the following subcommands are available:
^@ Break. Sends a break signal to the remote. The
break key on your terminal will probably generate
a ^@ (NULL) character. After the break is sent,
any remaining keyboard input (usually garbage from
a break character) is discarded.
^E Exits from the term function back to main
command level. Rapidly typing ^E^E will instead
cause one ^E to be transmitted.
^F Iff Q mode is in effect, transmit ANSWERBACK to
the remote. This is equivalent to HEREIS on a
Teletype machine.
^Q Iff a send file is open and its transmission has
been stopped by a XOFF, transmission is resumed.
Otherwise no special treatment.
^S Iff a send file is open and it is being
transmitted, transmission is stopped. Otherwise
no special treatment.
Manual Revised 01-04-83 Page 7
YAM/XYAM 3.44 Manual Page 8
^V Replots up to 24 lines starting with either the
first character received after the last character
keyboarded, or about 48 lines back if less than
400 characters have been received since the last
character sent. This allows the output from the
last command to be conveniently reviewed. Replot
then awaits next replot command (see below). ^V^V
typed quickly sends one ^V instead.
The following received characters are recognized in the
term function, when they are fetched from the circular
buffer for the display.
^E Iff Q mode is in effect, transmit ANSWERBACK to
the remote.
SO If Cis02 mode is in effect, turns on the Compuserve
A protocol. This protocol is used with the XFTRAN
program and the DOW command of SIG/ACCESS. See
yam4.c and Compuserve's CP-MIG user group for
more information.
XOFF Stops file transmission from yam.
XON Resumes file transmission.
TAB Tab characters are expanded to spaces on the
display. BUG: Since YAM does not decode cursor
addressing commands, these commands should not be
intermixed with tabs on the same line.
w
Write dumps the circular buffer to the receive file, if
open.
x
eXit to CP/M. Dumps and closes any open files. If YAM
has been "nobooted", this command will avoid the CP/M
warm boot. Any letters after x will cause the command
to be ignored, so users may keyboard "xyam s file" from
XYAM command prompt without untoward results.
;
Semicolon is an optional command delimiter which may be
used in place or RETURN in order to place multiple
commands on a line. Since commands such as "t" have an
indefinite number of operands, the semicolon must be
used to string commands together. Example: "sb
*.c;off" batch transmits all *.c files, then
disconnects. Unfortunately, CP/M's CCP clobbers ; and
Manual Revised 01-04-83 Page 8
YAM/XYAM 3.44 Manual Page 9
everything past it in the command line, so use
backslash instead.
\
An alternate to ; for CP/M systems.
NATHAN
The NATHAN command sends the rest of the physical
command line to the modem, starting with the very next
character. This command works with SUBMIT and XSUB (if
lowercase isn't needed). Normally a cr/lf is sent as
the end of each line, but this may be changed by
relevant mode(s).
Manual Revised 01-04-83 Page 9
YAM/XYAM 3.44 Manual Page 10
******** MODES used with D, E, F, T or U commands ********
!
Negates the sense of the following mode. For example,
t!l will turn off the line printer.
2
"2" causes formfeed from the remote to clear the screen
(CLEARS string defined in bdscio.h). Also enables
Compuserve A protocol if this feature is included.
a
A return from the keyboard is sent as return, linefeed.
If half duplex, both are sent to the console.
b
Binary mode of TRANSMISSION with T function. All 8
bits are sent. Handy for downloading binary files to
adjacent machines without any modem program. Don't
confuse this with the S function which uses the
Christensen protocol. Also don't confuse with i mode
which affects files received with the T function.
d
Directly enables/disables dumping of captured text is
squelch mode is in effect. If squelch mode is not in
effect, always enables dumping.
e
With term command, echo characters received from the
modem to the modem. Use this only for keyboard to
keyboard communication, and then only at one end.
Reset after each command. Does not imply "Half
Duplex".
With the f command, selects an alternate file
transmission function sendecho() which waits for an
echo to each character transmitted (for Throttle/10
seconds). The echoed character is output to console.
See "propagating yam" below. Often it is fairly easy
to write a simple receive routine which synchronizes
with the sender by the simple expedient of echoing the
characters received. On Heath/Zenith CP/M system, the
pip device "TTY:" does just that.
f
Full duplex.
g
Resumes (GO) sending file once in the term function,
equivalent to XON. Disabling GO causes a file queued
Manual Revised 01-04-83 Page 10
YAM/XYAM 3.44 Manual Page 11
for transmission to wait for an XON character.
h
Half Duplex. Displays keyboarded characters as they
are sent to the modem.
i
Image transparent data dumping, all 8 bits of all
characters received, including NULLS. This overrides
the t and/or z modes.
l
List unit (Printer) on. Since the printer is
separately buffered, it needn't be as fast as the
incoming data as long as the difference doesn't exceed
the buffer size. The rewind command may be used to get
extra copies of the received data.
n
Called nlmode, after the corresponding tty mode in Unix
systems. Send NEWLINE (lf) only when transmitting file
(no CR). Send keyboarded CR as NEWLINE. When
receiving a file to disk with the term function,
NEWLINE is stored on disk as \r \n. This mode is
useful when communicating with a Unix system. When
uploading files using cat(1), nlmode avoids sending
extra blank lines.
o
Onetrip. Exit back to CP/M before the next prompt.
p
Send CR only at end of line, and then pause until
echoes from remote have stopped. Useful for sending
files to bulletin boards where the remote needs time to
prepare for the next text line.
r
Called crmode. Sends CR only at the end of each
transmitted line.
s
Squelch the dumping of captured data with ^T and
unsquelch with ^R. These characters are not copied to
the file. When a receive file is opened with Squelch
mode is selected, writing to the file is turned off.
Selecting squelch mode automatically turns writing off;
disabling squelch automatically turns it on. (See "d"
above).
t
Manual Revised 01-04-83 Page 11
YAM/XYAM 3.44 Manual Page 12
If Waitnum is more than 1, wait for echoes to stop
after sending each Waitnum characters for period Pause.
If Waitnum==1, send at 1/Throttle, measured in loops of
the term() function. The default values of Waitnum and
Throttle provide transmission at about 50 words per
minute regardless of baud rate. This is handy because
many remote systems cannot accept input at full speed.
v
View control characters as ^C. Useful in shutting up
the bloody bell. In addition to the above, v
distinguishes characters with the parity bit set by
prepending a tilde (~). Note: View mode is distinct
from view option. This mode is reset after each
command.
w
Wait to receive GOchar after sending a CR at the end of
a line. Default for GOchar is linefeed (see g
parameter below). If GOchar is not received, the wait
times out in the same manner as with p mode.
x
Exit from the term function when EOF is encountered on
transmitted file.
z
Close file when ^Z is encountered while dumping the
capture buffer. Otherwise ^Z is ignored. It should be
noted that The Source coughs up an occasional ^Z just
as the "UPI" program is about to output something
interesting.
Manual Revised 01-04-83 Page 12
YAM/XYAM 3.44 Manual Page 13
******** Options used with S or R commands ********
All options are reset after each command.
b
Batch option. Pathnames are provided by the sender.
Disk names are excluded from the transmitted
pathname(s), and may not be specified for batch option
reception (use the change directory command).
c
Request Cyclic Redundancy Check instead of simple
checksum. This option must be specified with the R
function. The receiving program automatically signals
the sending program if CRC is to be used. The
probability of an undetected transmission error is much
less if CRC is used in place of arithmetic checksum.
k
Use 1 K byte blocks with the S and R functions.
Default block length is 128. Increases throughput when
the baudrate is high, relative to the response times of
the channel and computers. NOTE: some 212 type modems
work better if the baud rate is set to slightly less
than 1200 baud; e.g., 1180 baud. This is especially
true if using 1k blocks.
q
Quiet option inhibits some of the status information.
Quiet option is not necessary for proper operation at
higher baudrates.
t
Execute the term function after file transfer(s).
v
View the data being transmitted. Correct data is
displayed once. Viewing ascii files does not interfere
with correct transmission at extreme baud rates,
although throughput will be affected. For each sector,
data is viewed once before sending/after receiving.
y
Yes it is OK to clobber a file already on disk. If
absent, the operator is given a choice of appending to
the current file (a), erasing it (y) or aborting (n).
Manual Revised 01-04-83 Page 13
YAM/XYAM 3.44 Manual Page 14
******** Parameters used with P command ********
gm
Set GOchar to m (decimal). Default is linefeed. (See
w mode.) Some remote systems accept uploads with a ?
for each line. Optimum operation with such a system
might call for pg63 pp10000 pt90 ftw filename. The
first sets the goahead character to question mark, the
second sets the timeout to a long delay, the third sets
throttle to a speed which allows the remote to echo at
300 baud (assuming no tabs), and finally the command to
send the file with throttle and wait at end of line
(also eliminating the lf). If this sounds too complex
you can always go back to longhand.
em
Set Exitchar to m (decimal). Same format as GOchar
discussed above. If defined (non-zero), term function
will return when m is keyboarded, and ALL other
keyboarded characters are passed to the remote. Be
sure not to set Exitchar to something you can't
keyboard!
wn
Set Waitnum to n. See "w" mode for details. Default
is 1.
tm
Set Throttle to m. The default value corresponds to
about 80 words per minute sending speed.
pm
Set Pause to m. When the free characters in the
circular buffer reach 400, an XOFF is sent. Pause
controls the time which must then pass without
characters received before believing that the other end
really has obeyed the XOFF character, as opposed to the
sometimes lengthy Compuserve hitches in the getalong.
If Pause is too short, it is possible that a lurch in
output will be interpreted as acknowledgement of the
XOFF, only to have more characters arrive whilst yam is
occupied dumping the buffer to disk. When this
happens, unfortunate characters are routed to the
proverbial bit bucket, and you can retry the download
as the timesharing service increments the connect
charge. The default value seems suitable for Source
over Tymnet and BBS systems. Pause is also the echo
wait period used with the p mode, as well as the
timeout for w mode. Some bulletin board programs
require a longer pause when accepting files with the p
or w mode.
Manual Revised 01-04-83 Page 14
YAM/XYAM 3.44 Manual Page 15
******** Replot Commands ********
Commands within replot consist of a single character.
Replot maps uppercase, lowercase, and control
characters together in decoding commands.
b
Beginning of buffer
k
Kills entire buffer contents.
v
backspace
Previous page (some overlap provided)
space
Next page
p
Backup one line and redisplay
n
LF
Advance one line
x
Exit after diaplaying rest of buffer contents. This
effectively restores the screen and keyboard to the
same state they were in before replot was entered, so
you can see where you were in keyboarding to the
remote. For example, suppose you are typing in a line
of commands and you need to "thumb back" through the
remote's output for some vital nugget of information.
(After you enter a 20 line email message, NOW
Compuserve asks you for the 8 digit account number to
mail it to!) So you hit some Control V's until you see
it on the screen. Now you can't remember whether you
typed a space after the last part of you command to the
remote. No sweat, just exit replot with x and you'll
see just where you were (But don't forget that number!)
z
Kill the rest of the buffer by setting the character
insertion pointer to just after the end of the current
display. This subcommand should not be used if some
data has been sent to either the list device (with tl)
or a receive file (t filename) since the last kill
command as the pointers might get out of sync and
attempt to output the entire 64k memory space, entrails
and all.
Manual Revised 01-04-83 Page 15
YAM/XYAM 3.44 Manual Page 16
OTHERWISE
Return to previous function
Manual Revised 01-04-83 Page 16
YAM/XYAM 3.44 Manual Page 17
******** Sample YAM Session ********
A sample session might be:
A0>yam b19200 b: Set 19kb, Change to b disk
dirr yam?.? yamhlp.mss List files and calculate xmsn time
sb yam?.? yamhlp.mss Send them to a local system
call hydepark Can't remember the phone number!
t Term Function
minirbbs
E Enter a message, etc.
^E
ftp letter Open 'letter' and send to bbs, using
prompt and throttle modes to slow
transmission so the remote system won't
drop characters. YAM remains in T(erm)
after the file is sent.
xmodem s foo.bqr Command host to download a file
^E
rt secret.tqp Download the file, then back to term function
^V pause ^V^V Flip back three pages,
to first part of directory listed previously
CR Back to term function
More keyboarding with remote, logoff
(^E if CDO defined, term will exit by itself)
off Drop DTR so modem won't answer calls,
Return to CPM
Manual Revised 01-04-83 Page 17
YAM/XYAM 3.44 Manual Page 18
******** Notes ********
The transmission of pathnames in batch mode differs
from that used in MODEM7. Yam sends the pathname as a
null terminated string in a standard Ward Christensen
type packet with a sector number of 0. Disk specifiers
(B:) are not sent. The sender waits for an initial NAK
before sending the pathname. An explicit NAK is sent
by the receiver at intervals when is ready to receive a
pathname. Upon receiving and acknowledging the
pathname packet, the receiver opens the file and then
sends the initial NAK for the data in the file. A null
pathname terminates batch transmission.
The remainder of the pathname sector is set to nulls.
Future versions of YAM (running on 8086 MS-DOS, for
example), may add optional fields after the first null
for file information such as modification time (should
not be transmission time!!), or exact length.
When operating with a timesharing system and/or through
network or satellite links, considerable delays in
transmission and responce to blocks may severely reduce
throughput of an FTP (file transfer protocol). The k
option causes the s command to use 1024 byte blocks,
rather than the standard 128. At high baud rates, this
reduces the protocol related overhead up to 87 per
cent, depending on file length, by reducing the number
of blocks which must be sent and acknowledged by a
factor of 8. 1024 byte blocks are selected by the
sender. An STX at the beginning of each block
(otherwise SOH for 128 bytes) inicates this block is 1k
long. Pathnames are always sent with 128 byte blocks.
Files sent with 1k blocks may not agree with their
originals due to the addition of up to seven extra 128
byte sectors (padded with CPMEOF).
Buffering problems on some timesharing systems may
mitigate againgst use of 1k blocks at high baudrates.
Readiness to receive sectors with Cyclic Redundancy
Check (2 bytes) instead of the usual additive checksum
is indicated by a 0103 (ASCII "C") for initial "naks"
instead of 025. CRC option is highly recommended when
using 1k blocks.
File transmission is compatible with MODEM7 in single
file, standard block length mode. File transmission
may be aborted by sending a SEQUENCE of CAN (^X)
characters. Each character keyboarded will cause
Manual Revised 01-04-83 Page 18
YAM/XYAM 3.44 Manual Page 19
readline() to return a TIMEOUT error, thus regaining
keyboard control relatively easily.
I routinely send files at 9600 baud between a Z89 (2
mHz) and a Cromemco 4mHz system. This still works at
9600 baud even with CRC! Reception in the term
function seems to works well at 9600 baud on a Z89
provided the printer is off. If you use bios calls for
terminal i/o (e.g., TRS-80 version), the maximum speed
may be less in the term function.
*#Use these numbers for comparison. Your mileage and
range may differ depending on clock speed, circuit
distance and RFI/EMI. Calif. est. lower.
Quiet mode is not necessary for proper operation at
19kb, although it does increase throughput slightly.
View option (S and R commands) does not decrease
maximum baud rate, although throughput is obviously
affected according to the ratio of terminal speed to
communications rate.
Printer operation with bios calls or view mode
substantially reduces the highest baudrate possible
with the term function without losing characters
(independent of actual printer speed). The term
function will send XOFF to prevent buffer overflow if
the printer is on, or if a receive file is in use.
Term function on the Cromemco with a 300 baud printer
works fine at 4800 baud.
Baudrate selection routines are provided for the
Cromemco TUART and Z89 serial board (8250's).
If you want YAM to use the modem port's current
baudrate, provide a readbaud() function (in yam5.c) and
don't define INITBAUD. If you can't read the modem
port's baudrate, define DEFBAUD default_baudrate. If
you wish yam to initialize the modem port, define
INITBAUD.
In the term function, use of the circular buffer
provides some advantages.
Incoming data may come in at a rate higher than
the display and/or printer. Tab expansion for the
display does not compromise this ability.
The user may decide to save a timesharing session
on the disk AFTER it has started (or possibly even
Manual Revised 01-04-83 Page 19
YAM/XYAM 3.44 Manual Page 20
finished) as long as the buffer pointers have not
wrapped around.
The same ability also applies to the printer. The
printer need not be as fast as the modem as long
as the Tortoise is allowed to catch up.
Received data may be redisplayed (rep command).
At high speeds, the display will fall behind the
incoming data, as storing of raw modem data into the
buffer takes precedence over all else. As a result, a
defective or incorrectly programmed modem port which
sources data at high speed can lockout the keyboard.
If yam "goes away" when entering the term function,
this may be the cause.
If insufficient stack space is provided above the end
of the circular buffer, yam may sulk when attempting to
exit from the term function. The amount of stack space
is determined in the init function (in yam1.c) where
bufend is initialized.
The t and z modes affecting dumping of captured data
take effect when the circular buffer is written to the
receive file, not as the characters are first received
from the data port.
The append option (available if receiving filename
where filename exists) operates by calculating the
length of the file, searching the last NSECTS records
for ^Z, and positioning the pointers appropriately.
Since YAM fills the rest of the entire last record with
^Z, the last record of an existing file may be "cleaned
up" by the command sequence "kill tc filename" which
clears the capture buffer, opens filename for append,
and then closes it without adding any text.
Communicating with TWX Machines
YAM has certain features which facilitate sending files
to TWX machines. Files for transmission to TWX
machines conventionally begin with the local
answerback, which may be triggered by a ^F in the file.
After the test of the file, add an ENQ (^E) which
releases the TWX machine's answerback, another ^F to
send your answerback, and finally a ^D to allow the TWX
machine to disconnect.
To send a file, the following sequence is recommended:
Manual Revised 01-04-83 Page 20
YAM/XYAM 3.44 Manual Page 21
yam call name fq sendfile thqx logfile close off
Both sendfile and logfile should be open by the time
connection is made, or the called TWX machine may not
get a timely response to its ENQ (^E). Since YAM uses
the same file descriptor for looking up phone numbers
and receive files, you cannot open the receive file
before using the call command.
If printer operation is desired, change the thqx to
thqxl.
Manual Revised 01-04-83 Page 21
YAM/XYAM 3.44 Manual Page 22
******** Installing Yam ********
Yam consists of yam.h, yamsys.h, yam8.asm, and
yam[1235710].c. Yam currently supports the Z89 (with
aux board), Cromemco TUART, TRS-80 II, and Apple
(currently with Z19 console).
Yamsys.h is not part of the distribution; one of the
configuration dependent header files is copied to
yamsys.h. SOME of these files are: Yamz89.h is used
for Z89 computers (check the port definitions to be
sure they agree with your usage.) Yamtuart.h is setup
for a TUART board at 60H. Yamz89xm.h describes an
XMODEM configuration with the Z89. Yamtrsii.h
describes a TRS-80 Mod II. One of these (Or one you
write for your system) should be copied to yamsys.h
before compiling the files.
YAM also references some of the definitions in
BDSCIO.H. When cross-compiling a version of yam for a
different system, be sure to reference a bdscio.h file
suitable for the target system. Alternatively, one
might #undef CDATA and any other definitions which
otherwise would speak with forked tongue; YAMLYLE.H
will be an example of this trick.
Starting with Version 3.08 there will be multiple
versions of yam5.c depending on the target system.
There haven't been any changes to yam5.c (except for
porting to new systems), so you should be fairly safe
hanging on to your current version. If you do have a
special version of yam5, please edit out ALL code and
comments not directly relevant to your application
(including the unused versions of readline) to minimize
storage space and transmission time for RCP/M's
handling yam.
Compilation should be with -e 7500 for all files and -o
for yam[235] and yam10 for best runtime performance.
Note that yam[147] are NOT compiles with -o; the
execution speed of the functions in these files is
unimportant, and it is better to save code space by not
using -o. Consult the .sub files for examples. If you
have added some code for autodial, etc., the externals
need to start higher. If the externals start below the
end of code, YAM will say "urk" and exit, hopefully
before doing anything REALLY nasty.
Yam should be linked with the object module with the
largest set of "local globals" first. Currently, this
is yam10. These variables overlay similar variables in
Manual Revised 01-04-83 Page 22
YAM/XYAM 3.44 Manual Page 23
some other files. They are not required
simultaneously, but the linker must see the largest
common area first to allocate sufficient room for them.
(N.B.: I do not recommend this hack as a general
method!)
Yam can be made somewhat smaller if the -o is left out
and the external address is downsized accordingly. To
make the smallest YAM possible, define CDOS and
RESTRICTED and then leave off as many optional #defines
as possible. The bdsnew library (assembly language
versions of some standard functions) may be used with
slight improvments in code size and speed.
I have found YAM to be handy for transferring files
between adjacent machines; hence all the attention to
high speed operation.
If your machine uses a different type of UART chip, or
a built-in modem card, then the yamsys.h and yam5.c
files will need work.
Proper operation of YAM cannot be guaranteed with BDS C
versions prior to 1.46. If you don't have that
version, send 8 bucks and a copy of your software
license (a Xerox of your distribution disk showing its
label should do) to:
BDS C Users Group
Robert Ward
Dedicated Microsystems Inc
409 E Kansas ST
Yates Center, Kansas 66783
Versions before 1.46 are a no-no.
Manual Revised 01-04-83 Page 23
YAM/XYAM 3.44 Manual Page 24
*************************************
********** PROPAGATING YAM **********
*************************************
Often the question arises, "How do I get YAM (or
whatever) into this neat new machine with the *%!@$@
format disks?
The b mode was put in just for you! First, cross-
compile a version of YAM with a yamsys.h file
appropriate for the target machine. Then, connect the
two machines RS232 ports together, and initialize those
ports so they talk to each other. Presumably, YAM is
running on the host machine. Now run ddt, sid, zsid,
dcon, or whatever and write a tiny program up in fairly
high memory (above the highest address used by YAM, say
7000h).
This program will:
1. Set HL to 100h
2. Wait for UART for data available
3. Input data from UART (Note: UART must be in 8 bit,
no parity mode)
4. Store data to memory (mov m,a)
5. Increment HL
6. Jump to 2 above.
When the file is all sent, interrupt the program, jump
to location 0. Then you can save YAM.COM. If you
can't interrupt this program without blowing it away,
you'll have to change it to detect the end of data
(perhaps count the number of bytes received in the DE
register) and make the program jump to location 0.
Another possibility would be to unload the yam-
target.com image into a hex file ( UNLOAD2.ASM works
fine ). Then run pip in the target machine with input
from the serial port and output to a file using pip's B
parameter. With the B parameter, pip buffers incoming
data in memory until an XOFF (Control-S) is received.
To get that, send the file from the host with "yam f
file.hex" and from time to time hit two ^S's on the
host keyboard. The first ^S stops the transfer, the
second will be passed to the other machine where pip
will see it. When pip has written out the buffer, type
^Q on the host to resume. (Be sure to stop often
enough so pip's buffer doesn't overflow.) (With pip, go
slow -300 baud is much better then typing it in by
hand!) (If the target system seems to be echoing
characters, slowing down the transfer with the t mode
may help.) Finally, load the file with the target
Manual Revised 01-04-83 Page 24
YAM/XYAM 3.44 Manual Page 25
system's load command. Also, if the target system is
echoing characters (TTY: input device) the FE file
command may be easier to use.
Once you have a working yam in the target machine,
other files come across effortlessly with the batch
file transfer option.
Happy propagation and may your machines trap fertile
YAM's.
Notes on Uploading Files
If the remote has YAM, XYAM, MODEM, XMODEM, or
umodem, you can upload files with the s command on your
computer and the corresponding r command on the remote.
Newer versions of some of these programs support Cyclic
Redundancy Check as an alternative to the simple
checksum used by the original Ward Christensen
protocol. CRC is much better at detecting errors and I
recommend its use where available.
Unfortunately, this protocol is not implemented
on the popular timesharing services The Source and
Compuserve. It is often possible to upload files using
the F command, perhaps with one or more modes. Your
chances of success improve if you set "enab flow" when
connecting to Telenet. If using Tymnet, type ^R^X just
before the host computer name to enable flow control
with XOFF and XON. It often helps to use "half duplex"
when connecting to the computer.
Important #define's
MODOUT(c)
This outputs the character c to the modem. This macro
need not check whether the modem is ready for a
character as that has already been done. MODOUT(c)
must return immeadiately regardless of what is in c.
LPOUT(c)
Likewise, unadorned output of c to the printer.
LPOUT(c) must return immeadiately regardless of what is
in c.
TTYOUT(c)
Unadorned output of c to the local display. YAM checks
that the local display is ready before executing
TTYOUT(c). TTYOUT(c) must return immeadiately
regardless of what is in c. Caution if using bdos
function 6 which has special cases for 0xFE and 0xFF.
Manual Revised 01-04-83 Page 25
YAM/XYAM 3.44 Manual Page 26
MYSYSTEM
Defining this causes yam2 to be compiled with a call to
yam4.c for handling the Compuserve A protocol for file
transfer (see 2 mode). Unless you know what you are
doing, you should use the following even if it is a
bloody lie as xftran may not accept something original.
If this is included, you will need yam4.c, otherwise
not.
#define MYSYSTEM
"#CPMHeath/Zenith,CC,HC,PA,PL 15"
SCREAMER n
Compiles a call to yterm() instead of term() if
baudrate > n and no speical modes have been set which
would be rendered useless. Without yterm, maximum
baudrate may be limited to much less than 9600. Yterm
is written in assmebly language and must be modified
slightly according to the local hardware configuration.
The yterm function is in yam9.csm.
Note: if you miss only the first few characters in a
line, and if your system has memory mapped video,
screamer won't help you much; you need to speed up the
scrolling process! Note that yterm lacks much of
term's functionality. On a Z89 with direct bios
keyboard input, yterm functions at 19200 baud.
ANSWERBACK
This string is transmitted from term function in Q mode
in response to keyboard ^F or ^E received from remote.
Conventionally, ANSWERBACK consists of "\r\n<phone-
number> <user name> <city>\r\n\021" where city is a
three or four letter abbreviation specified by Western
Union Telegraph company. Teletype answerbacks are
limited to 20 characters, a limitation which needn't
concern us.
PHONES
This file (usually "A:YAMPHONE.T") contains a list of
names, phone numbers, and baudrates. The names must be
in lower case.
HELPFILE
Contains a short summary of commands and other useful
information about YAM suitable for use as an online
cribsheet. Currently a helpfile exists only for XYAM.
CDOS
Manual Revised 01-04-83 Page 26
YAM/XYAM 3.44 Manual Page 27
Makes YAM work on CDOS operating system by deleting
CP/M 2.2 operations such as user number, calculate file
length, etc. If you have CP/M 1.4, CDOS just might do
the trick for you.
KBMASK
This is normally 0177 to strip parity from keyboarded
characters, but may be 0377 if a full 8 bit keyboard is
used.
USERINIT
Causes init() to call a user supplied function
userinit().
TERMRESET
A string enclosed in quotes which sets the terminal to
the mode desireable for the term function. TERMRESET
as defined for the Z19 turns on wraparound.
RXNONO
Define this as a string of characters, any of which
would cause your terminal and/or cbios grief if not
suppressed by term function.
ESCCAL
Many terminals seend escape sequences for certain keys.
In a typical modem program configuration, these
sequences will fail to transmit properly because the
modem (300 or 1200 baud) cannot transmit the characters
as fast as the terminal generates them. I ESCCAL is
defined, yam will check for rapid escape sequences and
buffer the following characters. ESCCAL should be set
to the lowest number (shortest delay) that will
recognize the sequences. This logic is not needed if
the keyboard is interrupt driven. This feature may not
work if the remote is sending data at maximum speed the
instant the function key is used. For more
information, study the functions on yam3.c that
reference abptr and/or abend.
STATLINE
Define this if your terminal has an extra (viz., 25th)
line usable for status information which does not
scroll up nor interfere with scrolling. lpstat()
writes to the entire status line, clearing out any
previous contents. pstat() writes starting at the 48th
position, not disturbing any information written by
lpstat().
MODEMSTUFF
If you provide routines setbaud(), readbaud(), bye(),
Manual Revised 01-04-83 Page 27
YAM/XYAM 3.44 Manual Page 28
and onhook(), define MODEMSTUFF to exclude the default
dummy routines.
AUTODIAL
If your modem supports autodial, write your own version
of dial() and define AUTODIAL to suppress the default
routine.
FLIP
If you have a flip() subroutine in your yam5, this
causes flip to be included as a command. See
yam5pmmi.c for an example of a flip routine.
MIERROR
If your uart has a separate register for error bits
(not the register that holds receive data available),
mierror should be an expression which returns non zero
in case of overrun, framing, or other error, but not
carrier dropout. This version of readline has not been
tested.
MIREADYERROR
Define this if data available and the error bits are in
the same register, especially if reading that register
clears some error bits, or if the error bits are valid
only if data available.
IOTYPE
This defaults to char for i/o mapped systems with 256
ports. This may be defined to unsigned or long for
systems with more ports (8086 or memory mapped i/o).
Z19
Generates output for Z19 functions, especially status
(25th) line.
USQ
Allows the type command to automatically recognize
squeezed files and display them in ASCII form. Adds
1000 hex to program size.
RXLOG
Log all files received from remote systems in RXLOG.
Information stored includes user number, disk,
filename, baudrate, and the name of the remote system
given in the last call command (LASTCALR in xyam).
TXLOG
Log all files transmitted to remote systems in TXLOG.
Information same as above.
Manual Revised 01-04-83 Page 28
YAM/XYAM 3.44 Manual Page 29
LOGFILE
Must be defined if either of the above are.
NATHAN
Students of American History will recall the famous
patriot Nathan Hale who said "I regret that I have but
one asterisk for my country." Octal code 052.
Manual Revised 01-04-83 Page 29
YAM/XYAM 3.44 Manual Page 30
******** XYAM Differences ********
XYAM is produced by defining XMODEM in the file
'yamsys.h'. Consult 'yamz89xm.h' and 'yamx.sub' for an
example. Certain #defines are especially applicable to
XYAM:
RESTRICTED
Certain commands and options are disabled. Filenames
with '.BAD' extensions and files with $SYS or TAG2 bits
set cannot be opened. They will not appear with DIR or
DIRR commands.
A file with extension of '.COM' will be uploaded with a
'.OBJ' extension. Existing files cannot be
overwritten. If a file is received (r command) in
error, it will be unlinked.
CDO
Define a test for carrier drop out so that XYAM will
automatically exit T(erm) function when the connection
is broken.
BYEPROG
Bye, O and OFF commands chain to BYEPROG.COM if BYEPROG
is defined (as a string). For systems wishing to use a
BYE.COM to request comments.
Manual Revised 01-04-83 Page 30
YAM/XYAM 3.44 Manual Page 31
Recent Revisions/Enhancements to YAM
3.44 Name changes and typo corrections for
portability.
3.43 Nlmode and crmode now affect file xmsn with the
sendecho function as well as term.
3.42 inp() and outp() calls in yam3.c changed to
equivalent macros for portability. Disk block
calculation fixed re Paul Homchick.
3.41 Keyboard excape sequences buffered (see ESCCAL).
LOOPBACKNONO and u command removed.
3.39 Modem port selection has been moved from yam1 to
yam5. CISlen is no longer a settable parameter. Low
is no longer a settable parameter. All parameter
commands now take a decimal number; this avoids
problems encountered in previous versions when
attempting to set GOchar to colon. FE sends an ascii
file to computers with charaacter echo (pip file=tty:).
A bug which caused spurious XOFF to be sent when
sending file in term mode has been fixed. Z100 version.
9-16-82
3.37 Increased some timeouts in yam2.c for better
operations with sluggish remotes. 9-1-82
3.35 NULL sends break in yam3 (was ^B^B). 8-28-82
3.34 Changed starting point of replot command and also
speeded it up by using externs. 8-1-82
3.33 Changed yterm() to assembly subroutine, p/o
yam9.csm. Changed yam8 to .csm format also. Removed y
command (selection is automatic). 7-31-82
3.31 Added A prefix, LINKPORT, and completed Micro-Com
autodial routine. 7-23-82
3.30 Added k flag for 1024 byte block FTP, as well as
other improvements to yam2.c 7-11-82 Added y command, a
faster subset of the t command. Capture to file now
ignores CR, trnaslates LF into CR-LF unless image mode.
Moved time-sensitive functions from yam7 to yam10,
allowing memory savings by not using -o on yam7.c.
3.29 Removed Join mode. Added x command. "Added"
TTYOUT, MODOUT, and LPOUT macros (with argument) to
reduce conditionals in YAM3.C and YAM7.C 6-26
3.28 Added FLIP for PMMI type modems. The memory usage
change made in 3.26 has been cleaned up by use of a
union to assure correct memory layout regardless of the
compiler used. A yam5pmmi.c file for the pmmi modem
now exists. 6-12-82
3.27 Changed autodial() function for CAFPERS. 6-11-82
3.26 Further changes to aid maintenance of different
versions of yam. Needs BDS C 1.46 to compile due to
nested conditionals. init() moved to yam7.c. Memory
usage changed allowing larger buffer area.
3.25 NATHAN defined. CIS protocol entry changed to
help error recovery. 5-31-82
Manual Revised 01-04-83 Page 31
YAM/XYAM 3.44 Manual Page 32
3.24 Corrected usage of CLKMHZ
3.23 Official 8-bit version. Added -, o mode
(Onetrip), and Cislen parameter. Jeff Martin's
corrections added to manual.
3.22 Unofficial Version. Includes CIS/MNET A file
transfer protocol optional with yam4.c (see MYSYSTEM).
Changed Cis02 handling. Changed statline in yam2 to
display number of characters received in kilobytes.
Some coding changes reflecting awkward sequences
discovered while porting to CP/M-86 on IBM PC version.
3.20 New Base Version (for dif's). Changed error
printouts in yam2. Documentation update.
3.19 J mode joins short lines when at less than column
40.
3.18 N mode now prepends \r to \n when the term
function is receiving a file. 1-1-82.
3.17 Added E parameter 12-19-81.
3.16 Setting Squelch (TS ES FS or DS) automatically
sets Dumping to not Squelch. In Twxmode half duplex,
transmitted file is copied to receive file (if open),
and is printed if print mode is on. 12-16-81.
3.15 Added term Q mode for TWX operations with
ANSWERBACK. Changed wcgetsec() logic so noise hits on
the line before the first sector do not cause a speedup
in the timeout parameter. 12-14-81.
3.14 Added append option for receiving files, replot K
subcommand, changed previous K subcommand to Z. In N
mode, keyboard CR is transmitted as NL. 12-11-81.
3.13 For non STATLINE, changed "Awaiting Pathname NAK"
to "+" and "Awaiting initial NAK" "^".
3.12 Added replot X and K subcommands, changed type
unsqueeze to avoid array overflow problems on long
pathnames. Added term function break subcommand
(requires sendbrk() function in yam5.c). 11-5-81.
3.11 Added Cis02 mode for Compuserve access, fixed
logfile problem (first few files didn't show). Tab
expansion fix courtesy Jeff Martin (I thought it was
the Z89!) 11-28-81.
3.10 Changed yam10.c to stop printout on ^Z in file
11-22-81.
3.09 Cosmetic change to type command in xyam. 11-17-
81.
3.08 Added USERINIT option useful for some
implementations. 11-14-81.
3.07 Minor change to yam1.c for benefit of memory-
mapped systems 11-11-81.
3.06 IOTYPE added for memory mapped systems List
command now distinct from type. Cosmetic changes to
opentx(). 11-8-81.
3.05 Added automatic recognition and display of
squeezed files. Inclusion of the unsqueeze feature
Manual Revised 01-04-83 Page 32
YAM/XYAM 3.44 Manual Page 33
(#define USQ) may require clink -r 800 11-7-81.
3.04 Added GOchar parameter, enhanced view mode 11-6-
81.
3.03 Number of sectors and xmsn time printed when
opening files 11-5-81.
3.02 Xyam resets user number when exec'ing BYEPROG.
11-01-81.
3.01 Added INITBAUD. Your yam?????.h may need
revision. 10-31-81.
3.00 Nomenclature changed to facilitate differential
file updates 10-25-81.
2.34 Added era and NATHAN commands, O mode. 10-24-81.
2.33 Changed Unixish "FILE" to struct _buf in yam.h.
10-21-81.
2.32 Added BYEPROG define, deleted T, U, and W
commands from XYAM. 10-18-81.
2.31 Corrected tab expansion and kbd XON XOFF handling
in yam3.c 10-17-81.
2.30 Supports CRC error checking option compatible
with XMODEM45 10-15-81. Chat function now in both
yam/xyam.
2.24 Added free disk space report on a: etc. command,
Upchuck function.
2.23 Added "crck" command.
Manual Revised 01-04-83 Page 33