Category : OS/2 Files
Archive   : PM2YOU11.ZIP
Filename : M2ZMODEM.DOC

 
Output of file : M2ZMODEM.DOC contained in archive : PM2YOU11.ZIP

M2ZMODEM 2.12
=============

Introduction
============
M2ZMODEM is a stand alone ZModem file transfer protocol for OS/2.
The primary intention is to supply other terminal programs or BBS's
with the advanced Zmodem protocol, even if it is possible to use
M2ZMODEM as a terminal program too, by invoking the terminal feature
in this program. The terminal functions are quite limited, but
includes scripting, ZModem AUTO up and download. The scripting
ability makes it possible to auto dial, logon and much more.
The source is written in Modula-2 and compiled with JPI TopSpeed
Modula-2 OS/2-compiler.


Installation
============
The program was developed in the IBM OS/2 Extended Edition 1.20
environment, but should work with any OS/2 version. It uses the
COM0x.SYS driver delivered with the operating system. Install
M2ZMODEM by:

* Copy the files into any subdirectory on your harddisk (we use
C:\M2ZMODEM here as an example).

* If you want to alter the default messages to another language,
you should copy the appropriate MSG-file, to M2ZMODEM.MSG.
There are different MSG-files included for different languages.
They are named "MSG.xxx" there xxx is replaced by a country
code. To get swedish messages, you should type "COPY MSG.SV
M2ZMODEM.MSG". The default language is english (if you miss
"your" language, please contact me and we could work it out).

* Add this directory in your PATH and DPATH, either in your
CONFIG.SYS file or in a CMD-file (with the command
"SET DPATH=%DPATH%C:\M2ZMODEM;").

* Add the line "DEVICE=C:\OS2\COM01.SYS" if you have an AT-
compatible system, or "DEVICE=C:\OS2\COM02.SYS" if you have
a PS/2 compatible system.

* If you run OS/2 1.3 or earlier, and plan to use baudrates
higher than 19200 baud, insert the line "IOPL=SETBAUD" or
"IOPL=YES" in your CONFIG.SYS. This will only work for
standard COM1 and COM2 ports.

* If you plan to use the BBS protocol driver, with the SHELL
option, you should consider putting "AUTOFAIL=YES" in your
CONFIG.SYS (for OS/2 1.2 or later). See more about this below
(BBS protocol driver).

* Reboot your system.

Now you should be ready to run M2ZMODEM. You start the program
by typing "M2ZMODEM" at the command prompt. You may give several
options on the command line, described below. The program uses the
three environment variables "M2Z", "RZ" and "SZ" if they exists. The
M2Z variable is always merged to the command line, when M2ZMODEM is
started. If you select to send by M2ZMODEM the environment variable
"SZ" is also merged to the command line, and if you select receive
the variable "RZ" is merged.
An example on how to use these environment variables is showed
below:

SET M2Z=-l COM1 -b 19200 -h
SET RZ=C:\DOWNLOAD\
SET SZ=C:\UPLOAD\*.*

You may now start a download by just typing "M2ZMODEM -r" on the
command line, or start a upload by typing "M2ZMODEM -s".

This program will only run in a OS/2 full screen or a Presentation
Manager Text window, except for the optional Presentation Manager
status window, which only runs with Presentation Manager. Note that
the terminal feature performance is decreased when running in a
Presentation Manager text window. ZModem file transfer is not
affected by this, but the Presentation Manager status window
processing does load the file transfer thread a little, which could
affect performance when running high speed communications. If you
get performance problems, showing by extensive resending while
receiving files, even if the communication connection is perfect, you
should try to NOT load the PM status window. You should also
consider buying an enhanced 16550 UART.

If you run OS/2 1.2 there is a potential problem for you. The
first COM0x-drivers supplied with the operating system, has com-
patibility problems which makes it impossible to use the driver in
hardware handshaking mode (the "-h" option). If you have to use
hardware handshaking, I recommend you to use the COM0x-driver
supplied with OS/2 1.1. There are no conflicts using the OS/2 1.1
driver for OS/2 1.2.
If you run OS/2 1.2 or later, the program will automaticly fully
use the extended hardware buffering in the 16550 UART, if existing.
One potential problem in using the hardware buffering capabilities
is that the hardware handshaking has a slower response time, because
the driver send up to 16 characters after a hardware handshaking
signal. This should not be any big problem, because in the most
cases you want to enable the hardware handshaking to communicate with
modern high speed modems, with a higher DTE/DCE rate than the link
speed. These modems have buffering capabilities, and they usually
allow this behaviour.


Performance
===========
During development special care was taken to manage high speed
file transfers in background operation. Performance tests have
proved that there are no problems to perform file transfers with
about 1700 cps throughput over a 19200 baud connection, from the COM1
device to the COM2 device in background operation (not using the
extended hardware buffering). This means that the computer was busy
with both receiving and sending during the tests. A 16 Mhz 386/SX
computer was used for the performance tests. Disk I/O is internally
buffered in blocks of 16 kB. The performance is reduced a lot if the
operating system begins to swap memory to the harddisk during a file
transfer. This situation is not recommended.


Start options
=============
When starting the program you may use the following options:

-a fn Executes script file specified by "fn". Only valid if you
invoke the terminal feature by the "-i" option.

-b n Select baudrate specified by "n" (n=decimal value between
110 and 19200, as specified in the COM0x.SYS documentation).
If not specified the system default will be used.

-c The file transfer will be directly followed by another, do
not send ZFIN to close ZModem connection. If not specified
the ZFIN header will be sent.

-d Suppress checking for carrier loss. If not specified the
program will abort if carrier loss is detected.

-e env Searchs for the environment variable "env" and merges this
to the command line options. It is possible to merge
several environment variables into the same command line.
By using the OS-command SET, one may simplify the startup
options for M2Z.

-f n Scan for COMx file handles and select the n'th found for
communication (n=decimal 0 < n < 65536).

-h Enables hardware handshaking CTS/RTS. Software handshaking
by Xon/Xoff is always enabled.

-his Enables history logging. Only used in combination with the
"-i" option. When enabled, it is possible to scroll
backwards to see old lines. This is done by putting the
keyboard in ScrollLock-mode, and press the Up-arrow key.
This feature creates a file called M2ZMODEM.HIS, that may
be inspected after the program is terminated. This option
might slow down execution. Default is to disable this
option.

-i Invokes the on line terminal feature.

-l dev Select device specified by "dev" for communication.

-n No sound when file transfer complete. Normally a beep is
performed before program ends.

-o fn Place log information in file specified by "fn". Note that
the file "fn" is incremented without any warning, if the
file exists.

-p n Specifies which translate table to use for the terminal
session. The "n" parameter is equal to the COUNTRY
parameter specified in the CONFIG.SYS file. If "n" is set
to zero, no translation will occur. If this option is not
specified the system country code will be used. This option
is only acted on if you invoke the terminal feature.
Currently only country 001, 046, 047 and 358 is implemented
(US/Sweden/Norway/Finland). Other country codes use the
USA character set.

-pm Loads the Presentation Manager status reporting window.

-prot x Specify another file transfer protocol. The default
protocol to use is Zmodem, but by specifying this parameter
you may select the one indicated by "x". Replace "x" by
XMODEM, XMODEM1K, YMODEM, YMODEMB, YMODEMG, YMODEMGB for
Xmodem, Xmodem/1K, Ymodem, Ymodem Batch, Ymodem-G or Ymodem-
G Batch. By replacing "x" with "BBS" you load a user
interface for the remote system (a BBS protocol driver).
This is suitable when you want to use M2Z to handle up and
downloads in your BBS.

-prty x Specifies that the program should execute with priority x,
where x is replaced by a decimal value. Current available
choices are: 0=Normal priority, 1=Default priority, 2=Time
Critical priority. Prty 0 will usually give the best
result, if you want to work with other programs in the
foreground (this is the lowest priority). Prty 2 will give
the M2Zmodem program a very high priority, resulting in good
performance in this program, while other programs get very
little time to execute. Prty 1 is equal to prty 0 if the
baud rate is below 9600 and equal to prty 2 if the baud
rate is 9600 or higher. Prty 1 is the default action, but
I recommend you to try prty 0 first, and see if you
encounter any problems, and in that case you could switch
back to prty 1.

-q Suppress status messages and keyboard scanning. If not
specified status messages will be displayed and keyboard be
scanned for operator abort.

-r dir Receive files into path specified by "dir". If you want to
download into default directory, specify the "-r" option
last on the command line, and omit the "dir" parameter.

-ren If the file already exists when receiving, the received file
will be renamed, with the prefix "1_", "2_" and so on. This
is the default action.

-res If the file already exists when receiving, it is assumed
that the existing file is incomplete, and is incremented by
the received file. If the existing file is greater than the
received file, the received file is ignored.

-s fn Send file(s) specified by "fn". You may use wildcards to
specify batch transfers.

-skip If the file already exists when receiving, the received file
will be skipped.

-t Suppress conversion of file names to upper cases. Normally
all file names are converted to all lower cases during send,
and converted back to all upper cases by the receiver. By
specifying this parameter the file names are transfered
exactly as they appear in the operating system.

-u n Select file handle specified by "n" for communication
(n=decimal value 0 <= n < 65536).

The options may be placed in any order, but must be separated by
spaces and prefixed with the minus sign.


Invoking M2ZMODEM from another communication program
====================================================
If you want to execute the program from your own communication
program, there are different techniques available for this, depending
on how your communication program is written. The problem is how to
specify which communication port to use, because some communication
programs does not allow other programs to access the same port as the
communication program. In any case, the communication program must
have the possibility to execute a child process (DosExecPgm), or
there is no way to invoke the Zmodem software, if you do not exit the
communication program first, and executes Zmodem from the OS/2
command line.

If your software has opened the communication device with the
SHARE mode field set to DENY NONE, you just invoke Zmodem as you do
from the command line, using the "-l" option, by specifying the
device name to use.

If your software has opened the communication device with the
SHARE mode field set to anything else than DENY NONE and has set the
INHERITANCE field set to TRUE, you could try to invoke Zmodem by
specifying the device handle to use, using the "-u" option. This is
only possible if the communication program used makes the device
handle available to the user.

If your software has opened the communication device with the
SHARE mode field set to anything else than DENY NONE and has set the
INHERITANCE field set to TRUE, but does not make the device handle
available for the user, you could try to invoke Zmodem by using the
"-f" option. In most cases you should select "-f 1" option, which
makes the Zmodem software scan all available device handles, and
locks to the first appropriate device handle for communications. If
your communication program only supports one open communication
device at the time, this should work fine. If on the other hand,
your software supports multiple concurrent open communication
devices, it could be hard to know which occurence to use. It is NOT
always that way that COM1 is the first occurence and COM2 the second
and so on. It is rather so that the first occurence corresponds to
the port first opened. If you program first opens COM2 then COM3 and
last COM1, these ports will correspond to "-f 1", "-f 2" and "-f 3"
respectively.

Any device that is compatible with COM0x.SYS may be used. The
only restriction is that the device name can not begin with the
percent sign ("%COM10" is illegal).

When M2ZMODEM exits, the return code is set to:

0 If at least one file was sent/received.
1 If a command line parse error occured.
2 If send or receive failed.
Zmodem specifikations
=====================
The baudrate is not limited in the software, but the COM0x.SYS
drivers currently only supports speeds from 110 up to 19200 bauds.
The communication line is always set to 8 databits, no parity and 1
stopbit. The line characteristics is restored to its previous
condition when exiting the program (except for the baud rate).
Software handshaking with Xon/Xoff is always enabled, and hardware
handshaking with CTS/RTS is optionally enabled. The DTR signal is
always set and RTS is set, if not used for hardware handshaking. All
these parameters are reset to their previous conditions when exiting.

All filenames are sent exactly as they appear in the operating-
system over the Zmodem protocol (upper and lower cases filenames will
be sent). Operating systems not supporting both upper and lower case
filenames always send filenames in lower case. When M2Zmodem
receives files it will try to determine if the filename is a long
filename (if it should permit both upper and lower case filenames).
If the received filename contains ANY upper case letter, or if it
does not conform to the 8+3 MS-DOS naming convention, it will use the
filename exactly as received, otherwise the filename will be
converted to all upper case. This means that if you transfer files
between two M2Zmodem programs, the filename will be transmitted
exactly as it appears in the operating system, except if the filename
is ALL lower case, and conforms to the 8+3 format. By specifying the
"-t" option, you can disable conversion alltogether, resulting in
filenames with all lower case, if it isn't sent by a operating system
supporting both upper and lower case filenames.

The program will select 32 bit CRC error checking if receiver has
indicated this capability.

File compression and decryption is not yet implemented in
M2ZMODEM. The program escapes control characters as specified in
Omen technology documentation. 8th bit escaping and escaping of all
control characters is not yet implemented.

If a file already exists when receiving, the program may resume
the file (increment it), rename the file or skip it. The default
action is to rename the file, but this may be altered by the command
line options. If the file is renamed this is done by giving the
received file name a prefix of "1_", "2_" and so on. Note that if
you run on a HPFS-drive it is possible that the new file name, will
not conform to the 8+3 standard "old" file name format. And if you
on the other hand don't run a HPFS-drive, the file name prefix is
truncated to 8 characters.

During a file transfer, it is possible to abort the ZModem session
by pressing the Escape key (if you are lucky).


OTHER FILE TRANSFER PROTOCOLS
=============================
The M2ZMODEM program may use other file transfer protocols than
the default (and best) Zmodem protocol. By specifying the "-prot"
option you may select another. These currently are:

XMODEM Xmodem.
XMODEM1K Xmodem with optionally 1024 bytes block length.
While receiving block length is detected automa-
ticly, which means there is no difference between
XMODEM and XMODEM1K for receive sessions.
YMODEM Ymodem with optionally 1024 bytes block length.
This is the same as Xmodem, but the file name, and
some other parameters are sent to the receiver.
YMODEMB Ymodem batch, is the same as YMODEM, but a batch
file transfer protocol, making it possible to send
several files in a session.
YMODEMG Ymodem-G, is the same as YMODEM, but the protocol
does not wait for ACK/NAK between the data blocks.
This protocol should only be used with modems using
error correction, because it can't recover any
transmission errors.
YMODEMGB The same as Ymodem-G, but a batch protocol.
BBS By specifying this parameter, you put M2Z in server
mode (BBS protocol driver). See more about this
below.

When not using batch protocols, only the FIRST found file, if you
specify a wild card file specification, is sent.

The Ymodem-G protocol is not recommended for receiving files in
high speeds when not running the program in foreground, because this
protocol does not support error recovery. There will be a risk of
overruns, making the whole transfer abort. Generally the ZModem
protocol is the best, and the therefore the effort has been con-
centrated on evaluating a good implementation of this protocol.


BBS PROTOCOL DRIVER
===================
By specifying the option "-prot BBS" you put M2Z in server mode.
M2Z will display a menu with available protocols on the remote
system, and ask the user to select one of these.
Then M2Z will ask for which files to up/download. If the user
specified a batch file transfer protocol, it is possible to use
wildcards and/or specify multiple files, separated by spaces. After
this, the user will be asked to start his/her file transfer proce-
dure.
This interface is suitable if you want to install M2Z to handle
up and downloads in your BBS. The parameters to the "-r" and "-s"
options, should only contain valid path names in this case, and NOT
filenames (it is not necessary to specify any pathname at all). A
path name is terminated with a backslash. An example is showed
below:

M2ZMODEM -l COM1 -b 19200 -s C:\TXTFILES\ -prot BBS -h

This command line will start M2Zmodem for the COM1 device, 19200
baud, and start the BBS protocol driver, and only pick files from the
C:\TXTFILES\ directory. Hardware handshaking will be used.

M2ZMODEM -l COM1 -b 19200 -r C:\UPLOAD\ -prot BBS

This line will start the BBS protocol driver and put all uploaded
files in the C:\UPLOAD\ directory.

If no action is taken within the BBS protocol driver for about 1
minute, the program is terminated by itself, to prevent a user from
hanging the BBS.

To pass parameters to the BBS protocol driver, there is an
environment string "M2ZBBS" you may set. The string may contain
several parameters, separated by spaces, or by ";". Possible
parameters are:

BAUD.xxx Tells the protocol driver to user the baudrate
"xxx" (decimal value) to estimate download time.
This parameter does NOT affect the real line
characterstics. If this parameter is not specified
the protocol driver will read the real baudrate
from the device used. If "0" is specified, the
parameter is ignored, and the real baudrate will
be used.
MAX.xxx Sets the download limit. Replace "xxx" with a
decimal value. The string "MAX.512000" would set
the download limit to 512000 bytes. Default is no
dwonload limit.
NODIR This option disables listing of selected files,
before a download. Only a summary of how many
files, and bytes are displayed. Default is to
display a directory.
PATH.xxx Sets the protocol driver to use the path names in
the "xxx" environment string, as download direc-
tories. The "xxx"-environment should contain
pathnames terminated by a backslash, separated by
";" or space. If specified when starting when a
user does an upload, only the first path in "xxx"
will be acted on. The environment string "xxx" is
only acted on up to the 2048 first characters.
SHELL.xx Sets the password to access the SHELL command, to
"xx". "xx" may be any string, but only the first
15 characters are checked. The password should NOT
contain the ";" character. If the password is set
to "YES", no password check is done at all. If the
password is set to "NO", the user will not be able
to shell at all. Default is to not let the user
shell at all.
TERM.xxx There "xxx" is a terminal name. Available terminals
are:
ANSI Sends ANSI-BBS sequences.
TTY Does not send any terminal
sequences at all, but CR, BS and
FF.
0 The same as "TTY" above.
1 The same as "ANSI" above.
TIME.xxx There "xxx" is replaced by the amount of time left
for the user in seconds. Default is no time limit.

Be careful with the SHELL option. Only text applications may be
run in the SHELL, and not even all of the text applications runs well
in the SHELL. OS/2 commands run well in the SHELL, and some other
programs too.
If no input or output was made for the last five minutes, the
SHELL will be automaticly closed, and you will be returned to the
HOST menu.
You always close the SHELL manually by pressing the ESC-key twice
while in the SHELL. If a program hangs because it was not suitable
to run in the SHELL, you should be able to kill this program by
pressing the ESC-key.
Note that a SHELL user have a lot of power in your system. He/she
may delete any files, format disks, change your userlist.

If you plan to use the BBS protocol driver, with the SHELL option,
you should consider putting "AUTOFAIL=YES" in your CONFIG.SYS (for
OS/2 1.2 or later). This will disable the error pop-ups and give a
error message instead. This is necessary for the SHELL option,
because error pop-ups can't be fetched by the BBS protocol driver.
If an hard error occurs while you run the SHELL option, and you have
not enabled the AUTOFAIL option, the program will "hang" awaiting
response from the "real" keyboard.

A setup example is showed below:

SET NORMAL=C:\TWIT\;C:\NORMAL\;C:\SECRET\;D:\;
SET EXTRA=%NORMAL%D:\EXTRA\;
SET SYSOP=%EXTRA%D:\SYSOP\;D:\SECRET\;
SET M2ZBBS=TERM.ANSI;MAX.512000;NODIR;PATH.NORMAL
M2ZMODEM -l COM1 -b 19200 -prot BBS -s C:\TWIT\;

This sequence will load the protocol driver, and the user will be
able to download files from the paths specified in the "NORMAL"
environment string. If you replace the "PATH.NORMAL" string by
"PATH.SYSOP" the user will be able to download files from the paths
specified in the "SYSOP" environment string instead. If the argument
passed with "PATH." is not valid like "PATH.UNKNOWN", the path
specified on the command line will be used, in this example the
"C:\TWIT\" path. If no path is specified on the command line, the
current directory will be used.

The same rules apply to uploads, but only the first path specified
will be used. If you load M2Z by:

M2ZMODEM -l COM1 -b 19200 -prot BBS -r C:\UPLOAD\

If the "EXTRA" user uploads files, the files will be placed in the
"C:\TWIT\" path. If the "UNKNOWN" user uploads a file, it will be
placed in the "C:\UPLOAD\" path.

Upper or lower cases are not significant. To pass parameters back
from the BBS protocol driver, the environment string "M2ZBBSRC" is
reserved. Currently no parameters are returned from the BBS protocol
driver.

Yet another example on how you may use the BBS protocol driver.
Suppose you have a door in your BBS-system, that starts the CMD-file
M2ZDOOR.CMD and passes the following parameters:

%1 Download limit in Kbytes for download passed as a
decimal value.
%2 Level for the user passed as a decimal value
between 1 and 9.

Before the BBS is started, the following environment strings are
set:

SET LEVEL1=C:\DISGRACE\;C:\TWIT\;
SET LEVEL2=%LEVEL1%C:\LIMITED\;
SET LEVEL3=%LEVEL2%C:\NORMAL\;
SET LEVEL4=%LEVEL3%C:\WORTHY\;
SET LEVEL5=%LEVEL4%C:\PRIVIL\;
SET LEVEL6=%LEVEL5%C:\FAVORED\;
SET LEVEL7=%LEVEL6%C:\CLERK\;
SET LEVEL8=%LEVEL7%C:\ASSTSYSOP\;
SET LEVEL9=%LEVEL8%C:\SYSOP\;

The M2ZDOOR.CMD file could now look like:

@ECHO OFF
SET M2ZBBS=TERM.ANSI;MAX.%1000;PATH.LEVEL%2;
M2ZMODEM -l COM1 -b 19200 -prot BBS -s C:\TWIT\;


FILE SERVER PROGRAM
===================
A simple program to set up a file server is included, called
M2ZSERV. It is suitable primary for personal use, when you want to
fetch files from your business machine, when you are at home, to just
mention an example. It is NOT a full featered BBS, but is much
easier to setup. You start the program by typing:

M2ZSERV device

Replace "device" with the device name you want to set up the
server for, like "COM1". You have to put your modem into auto
answer, and the cabling must deliver the DCD line correctly (or set
to constant high, but it is not recommended). Dropping DTR should
result in a hang up, but it is not necessary.

When carrier is detected the program will ask for a "Enter"
keystroke, and wait for one second to get this keystroke. If the
keystroke was not received, the program will alter the baudrate to
the next lower, and try again. The program cycles all baudrates
around until the "Enter" keystroke is detected (or carrier lost).
The baudrates scanned is 19200, 9600, 2400, 1200 and 300 baud. By
this scanning, the program should be compatible with any modem
supporting auto answer.

After the program has fixed for a baudrate, it will ask for
username and password, validate them by checking the USERLIST.BBS
file, and fetch the user level. The format for USERLIST.BBS is
showed by the example file included (each entry MUST be followed by
a CR/LF sequence). There are four parameters defined (yet), each
terminated by a ";".

1. User name (not case sensitive)
2. Password (case sensitive)
3. User level (not case sensitive)
4. Shell password (case sensitive). If this field
contains the word "YES", no password check will be
done. If this field contains "NO", the user will
not be able to shell at all. All other combi-
nations sets the password according to the field.
Only the first 15 characters are validated, and the
password should not contain the ";" character. Se
more about the SHELL option above (BBS protocol
driver).
5. Complete callback string. If this is empty, no
callback processing will be used.

An example:

Mikael Wahlgren;secret;Sysop;shellpassword;ATDT1234567
Who knows;my secret;Twit;NO;;

The program will ask if the user wants to download, upload or
disconnect, and loads the appropriate BBS protocol driver interface.
The user will return to this menu after each file transfer request.
The user will be able to access directories for download, according
to the environment string, complying with the user level you set.
If you set the user level to "SYSOP" for an user, the user will be
able to access "C:\", "C:\SYSOP\", "C:\EXAMPLE\HELLO", if the
environment string "SYSOP" is previously set to:

SET SYSOP=C:\;C:\SYSOP\;C:\EXAMPLE\HELLO\;

When the user has selected up or download, the M2ZSERV program
will execute the M2ZBBS.CMD batch file (by calling "CMD /C M2ZBBS %1
%2"), with the parameters:

%1 Operation. "-s" for download and "-r" for upload.
%2 User level.

By altering the included M2ZBBS.CMD file, you may select different
options in the M2ZMODEM BBS protocol driver.

The only way to terminate the M2Z HOST mode, is by pressing CTRL-
BREAK or CTRL-C when the session is in foreground.


TERMINAL FEATURE
================
I simple but fast terminal feature is implemented in the program.
It emulates an ANSI terminal, and it is possible to execute scripts
(automatic terminal sessions) and upload/download files with the
ZModem protocol.
The terminal function has built in translate tables for different
countries. The correct translate table is automaticly activated by
inspecting the COUNTRY-code specified in your CONFIG.SYS file (if no
other translate table is specified by the "-p" option). Currently
only 001, 046 and 358 country tables are implemented.
The terminal session has AUTO ZModem Up/Download capability, which
means it detects when you requested a ZModem file transfer from a BBS
and automaticly invokes the Up/Download routines. You may also
request download or upload manually by pressing the PgDn or PgUp
function keys.
You may execute a script file by pressing ALT-S and give the file
name of the script. The M2ZMODEM script language is a very simple
way to automate terminal sessions. The following commands are
available:

INITIAL "string" Sends "string" to the remote at.

RESPOND "await" "string" Whenever "await" is received
"string" is sent to the remote.

DELAYED RESPOND "await" "string" "n" Whenever "await" is received
"string" is sent to the remote,
after "n" seconds delay (n=deci-
mal value).

QUIT "await" Whenever "await" is received the
script execution is finishing and
you are back to normal terminal
operation.

EXIT Marks end of script file.

With scripting it is possible to perform redial, logon, download,
logoff and much more, by just specifying a script file. A sample
script file, which will redial a BBS and then logon to the system
is showed:

INITIAL "ATDT 12345678!"
DELAYED RESPOND "BUSY" "ATDT 12345678!" "5"
DELAYED RESPOND "NO DIALTONE" "ATDT 12345678!" "5"
RESPOND "Press Escape twice to load BBS" "@@"
RESPOND "Password: " "secret!"
RESPOND "Name: " "My Name!"
RESPOND "More (Y/N)" "N"
QUIT "Main menu"
QUIT "NO CARRIER"
EXIT

Note that it not is significant in which order you place your
script instructions. Each instruction is valid concurrently as long
as the script is executed. You abort a script execution by pressing
the escape key. In text strings "!" are replaced with (03H)
and "@" are replaced by (1BH). Only the first 100 instructions
are acted on. Upper and lower cases are significant. It is still
possible to use the terminal functions while executing a script file.

By pressing ALT-D you will display the dialling directory. The
dialling directory is placed in a file called "M2ZMODEM.DIR", and
has the following format:

Name;Number;Scriptfile;
Mikael Wahlgren;4631196417;AutoDial;
.
.
.
Example;123;AutoDial;

The first parameter is the name of the entry, the second parameter the
phone number to use, and the third parameter is the script file used for
dialling. If you select an entry in the dialling directory, the program
will load the associated script file, and replace all occurencies of "#"
in the script file, by the phone number in the dialling entry, and then
execute the script. An example of a dialling script file is included and
called AUTODIAL.

You exit the terminal session (and the whole program) by pressing
ALT-X.
Note, that it is impossible to abort the program with CTRL-C if
running the terminal session.


PRESENTATION MANAGER SUPPORT
============================
There is a limited support for Presentation Manager. By speci-
fying the "-pm" option on the command line, you can load a Presen-
tation Manager ZModem file transfer status window. This window
displays the same information as the PopUp in text windows.
It is possible to interface with the communication program, in
order to write an own status window, or monitor the file transfer
status. This is done by writing a Presentation Manager application,
with the file name "M2ZPM.EXE", which opens a named pipe called
"\PIPE\M2ZPM" in message mode (as client). The message block is
defined like:

WORD Message type
DWORD Value 1
DWORD Value 2
DB 40 40 character ASCIIZ

Possible message types are:

0 Send before each transfer session. This message
is sent only once per transmission, even if it is
a batch transfer.
1 ASCIIZ contains file name.
2 Value 1 contains file size.
3 ASCIIZ contains file transfer message.
4 Value 1 contains ZModem frame type.
5 Value 1 contains throughput value, Value 2 contains
file position, ASCIIZ contains calculated remaining
file transfer time.
6 Value 1 contains amount of ZModem errors.

The pipe is closed when the M2ZMODEM program exits. Before the
pipe is closed, it is reset, to ensure that the client has read all
messages. A non working client that won't read the pipe, could
prevent M2ZMODEM from exiting successfully. A buffer of 1024 bytes
is allocated to the pipe. If the buffer is full, M2ZMODEM won't
write any messages to the buffer, until it clears. The client should
not assume that the whole message block is always transfered. It is
possible that the message is truncated to include only the valid part
of the message block.


RELEASE LOG
===========

- Version 1.00 1989-12-11
==========================
First official release of M2ZMODEM. All previous versions is just
test shoots.

- Version 1.01 1990-01-06
==========================
All source is packed in the .EXE file and no DLL's are used any
more.

The status reporting window is altered and irrelevant information
removed.

Filenames not complying with the 8+3 format is supported.

File transfers greater than 64 Kb correctly closed.

- Version 1.11 1990-01-09
==========================
Remaining transfer time deisplayed instead of total transfer time.

Faster ZModem session shutdown (Over and Out operation improved).

Keyboard scanning changed to improve compatibility with other
programs calling M2ZMODEM. A DosGetFocus is called before trying to
access the keyboard. M2ZMODEM locked if the calling program was
blocked awaiting for characters from the keyboard in the previous
versions.

The VIO is switched to ANSI-mode and the cursor is hidden when
M2ZMODEM starts, and restored to its previous state when exiting.

- Version 2.00 1990-01-19
==========================
The full power of the 16550 extended hardware buffering is enabled
by setting the receive trigger level at 8 characters and transmit
buffer load count to 16 characters. See more about this above.

The parameters for the COM-port is restored to its previous condi-
tion, when exiting the program. This was not done correctly before.

A simple terminal feature with scripting ability is implemented.
By specifying the "-i" option the program will go on line in ANSI
terminal mode. See more about the terminal feature above.

The cursor and ANSI state is unaltered when starting the program
without parameters. Previously the program put the screen into ANSI
off.

- Version 2.01 1990-01-20
==========================
The terminal functions are enhanced with break signal, clear
screen, help screen.

The hang-up command has been altered to both lower DTR and send
the AT-command for hang up.

The license file system is introduced.

The status reporting window is now designed as a "pop-up". The
screen is restored to its previous condition when exiting. The
colors are selected to be compatible with both color, black/white,
monochrome display adapters. When exiting the program, the color
attributes are reset, regardless of the condition when entering the
program.

The log file is now incremented, if it already exists, and not
overwritten. Each log record is marked with date and time.

- Version 2.02 1990-01-31
==========================
The status window is altered. Instead of showing the block check
status, the transfer rate is displayed.

The possibility to set environment variables, and refer to these
with the "-e" option is added. It is possible to merge several
environment variables together at the same command line.

The file transfer time estimate is calculated in a smarter way.
The current CPS value is used for the calculation, instead of the
baudrate. This makes the time estimate more correct for modems with
a higher DTE-DCE line speed, than the link speed.

- Version 2.03 1990-02-01
==========================
When running at speeds of 9600 baud or higher, or using the
default baud rate, the process priority is changed to class 3 (Time
Critical).

Some minor corrections have been made in the log file.

The transfer time is displayed in minutes with only one decimal,
to avoid the similarity with the mm:ss format (making you believe it
is displaying minutes and seconds).

A Presentation Manager status reporting window is now implemented.
This is loaded by specifying the "-pm" option.

The program may now resume, rename or skip a file, if it already
exists on the target system. Which action to take, depends on the
command line options. Default is to rename the file.

If file modification time was not specified in the ZFILE header,
an incorrect (and abnormal) file time was set. This is corrected,
and the file time is set to the current time, if not specified.

The XModem category file transfer protocols are added. By using
the option "-prot" you may select Xmodem, Xmodem/1K, Ymodem, Ymodem-
Batch, Ymodem-G or Ymodem-G-Batch. The protocols are called
"XMODEM", "XMODEM1K", "YMODEM", "YMODEMB", "YMODEMG" and "YMODEMGB"
resp.

- Version 2.04, 1990-02-13
===========================
Some minor changes have been made in the log file, in respect to
X/Ymodem file transfers.

The BBS Protocol Driver is loaded. This is a user interface for
those who want to use the M2Z to handle up and download in the BBS.
This is loaded by specifying the option "-prot BBS".

The Presentation Manager status window program M2ZPM, would cause
a hang, if the stream of messages from M2Z was too active. This
should now be fixed.

If an upload was requested, with a system just echoing back the
characters, the system would circle around sending NAKs to itself.
This is corrected, and now the system sends ZRQINITs every 10 second.

It is now possible to abort transfers by pressing the left mouse
button at the "" field.

Some corrections have been made in the Ymodem protocols.

The program is now easily "translatable" to other languages, by
putting almost all messages in a message file.

Asynchronous write processing has been implemented in the Zmodem
protocol, to increase the throughput. A test seemed to indicate that
the performance increased a little (but not much).

- Version 2.05, 1990-02-19
===========================
The synonyms "0" for "TTY" and "1" for "ANSI" terminals in the BBS
interface parameters are added.

The parameter "TIME." is added in the BBS interface, and a simple
time estimate is displayed before a transfer. The time estimate,
does not count with the overhead of different protocols.

Hang when unathorized user logged into the M2Z HOST, removed.

The remaining time in the file transfer status window is now back
to the "mm:ss" format, but now really displays minutes:seconds.

New registration information.

SHELL function in M2Z HOST program.

- Version 2.06, 1990-04-27
===========================
The screen dump fature is altered to append CR/LF at end of each
row, to allow text editing.

The redisplay feature is added (see "-his" option above).

The treatment of upper/lower cases in filenames is altered, to be
more automatic. Now M2Zmodem will makes its very best to determ if
it is a "long" filename, and if upper/lower case characters should
be kept. The only case when M2Zmodem will fail to keep the same
format of the filename is if the filename contains ONLY lower case
characters and conforms to the 8+3 character old DOS naming conven-
tion, in which case the filename will be converted to all upper
cases. This conversion may be overrided by the "-t" option.

Some cosmetical changes in menus and messages. M2Zmodem now uses
window popups.

The keyboard handling is altered, to also enable the arrow keys
on the numerical part of the keyboard (if not in NumLock mode). The
separate arrow keys are treated the same way as before.

The SHELL to OS/2 option in the BBS protocol driver is fixed. In
previous version, you could get a protection error when exiting the
SHELL mode. This should now be fixed.

It is now possible to alter the COM parameters (baudrate, parity,
data and stop bits) in the terminal session by pressing ALT-P.

The mouse is now used in the terminal session. The mouse button
1 (usually the left one) will send the character at the mouse pointer
location, to the COM port. Mouse button 2 (usually the right one)
will send ANSI escape sequences to the COM port, to position the
cursor at the same location as the mouse pointer. It is possible to
"drag" the mouse, when the left button is pressed, in order to send
a string.

- Version 2.07, 1990-05-06
==========================

The external program Os2You (also a MW-product) is used for
shelling to OS/2.

- Version 2.08, 1990-07-29
==========================

M2ZServ is capable of callback processing.

M2Zmodem is altered to not conflict with Os2You if used concur-
rently on the same communication port.

- Version 2.09, 1990-09-11
==========================

Documentation corrected. Script command INITIATE replaced with
INITIAL (only in documentation, have always been INITIAL in program).

Dialling directory added.


- Version 2.10, 1991-02-17
==========================

Changed compiler. Changed behaviour of some keys, like Ctrl-P,
grey Enter.


- Version 2.11, 1991-08-26

Changed compiler, and fixed file date. This version is also
compatible with PMTERM.

Zmodem file transfer now works with named pipes to use the protocol
via the asynchronous network gateway implemented by Os2You.

Zmodem file transfers would hang in certain situations (ZCRC header).
This is now fixed.


- Version 2.12, 1992-05-22

Incorporated SetBaud, which now enables baudrates up to 115200 baud.
If you are running OS/2 1.3 or lower, insert the line "IOPL=SETBAUD"
or "IOPL=YES" in your CONFIG.SYS, and you will now be able to use
baudrates up to 115200 bauds.



- Planned enhancements
======================
* ASCII upload.
* Prestel emulation.
* Better redisplay function.

GUARANTEE
=========
This software is released "as is". I believe it works as
described in this documentation, but if it does not, I am not
responsible for any harm you may suffer from this. I will try to
correct any bugs you report. Even if you register the product this
will be true.


Important license information
=============================
It is illegal (or at least unethical) to patch the program in any way.
Any reverse engineering (disassembling or monitoring) is not an approved
use of the application.

If you register the software with 300 SEK (about $50), you will get a
license file and a copy of the most recent version of the program. In
this case, you will also get rid of the registration screen during logon.

If you use the program on a regular basis, or in commercial use, you must
register with minimum the above mentioned sum for each machine running
the program. For use in the Scandinavian countries (Sweden, Norway and
Denmark), I have the right to refuse registration of a user and prohibit
commercial use of the program, if I wish. This will be the case, if the
use of the program conflicts with commercial interests related to me.

You are encouraged to spread this program (without registration file)
to anyone that might be interested.

If you want to register, send swedish banknotes, or let bank transfer
money to my account (note that you should send all money in swedish
currency), or pay by VISA or MC. If you pay by VISA or MC, please
complete the ORDER.DOC form and mail or fax it to me.

My address is:

Mikael Wahlgren
Kransen 4E
S-416 72 GOTHENBURG
Sweden

Fax +46 31 196417
Phone +46 31 196074


ACKNOWLEDGMENTS
===============
J. R. Louvau's source code TPZSFZ for DOS, was "looked at" while
developing this source (which is completely different, and in another
language, but the Pascal source gave some useful hints).

Joaquim Homrighausen's 32 bits CRC calculation was altered and
implemented in this source.

Chuck Forsberg, Omen Technology and Telenet developed the ZModem
protocol.

Jensen & Partners International developed the TopSpeed Modula-2
OS/2 compiler, which is a very powerful development environment for
OS/2 programming.



TRADEMARKS
==========
OS/2 is a trademark of IBM Corporation.
PS/2 is a registered trademark of IBM Corporation.
PC/AT is a registered trademark of IBM Corporation.
IBM is a registered trademark of International Business Machines
Corporation.
Omen is a trademark of Omen Technology Incorporated.
386/SX might be a trademark of Intel Corporation.