Os2You 1.6 (read OS/2 to you) 1990-12-09 (c) 1990 Mikael Wahlgren
=========================================================================


Introduction
============
Os2You is a communication software to allow remote operation of any
OS/2 full screen text session and the DOS compatibility box(es), over
an asynchronous line (by cable or modem), a pipe or a remote pipe (over
a LAN). The program may be used in two different ways. You can run the
program as it is stand alone, but it is also possible to call the program
from your own program, allowing your own programs to offer remote operation.
The program can directly replace the program MaxPipe (TM of Peter
Fitzsimmons), and will be compatible with more programs than MaxPipe.

If you have got the distribution files packed in a ZIP-file, you should
unpack them first. Files included in this package:

OS2YOU.EXE The remote software
OS2YOU.DOC This documentation
LANTERM.EXE Terminal program using DOS on a LAN
LANTERM2.EXE Terminal program using OS/2 on a LAN or async line
DOS2YOU.EXE Program to access DOS compatibility box
DOSREDIR.EXE DOS-program required to use DOS compatibility box remote
INSTALL.EXE Installation/configuration program
TERMDEF.EXE Program to make terminal description files
????????.PRM Terminal description files for different terminals




Stand alone installation
========================
To configure the program in stand alone mode, you run the program INSTALL
from an OS/2 Command Prompt. Note that you should always use a Full
Screen text session for the programs. The asynchrous support device
driver COM0x.SYS driver should also be loaded in your CONFIG.SYS file.

When the program is properly configured for your system, you start the
program by typing "Os2You" at the OS/2 Command Prompt, or if you have
multiple configuration files, you type "Os2You " (you replace
with the configuration filename you want to use).

The program will now put the modem into auto answer mode (if your modem is
supported by the program), and wait for an incomming call, and answer
it. When the connection is established, the caller will be asked for
an ID and password and validate them with your configuration file.

If you have specified a callback number for the caller, the connection
will be closed, and the Os2You program will call the phone number in
the userlist entry (note that you should only include the phone number
in the user list entry and not the Hayes command prefix "ATD", but if
you want, it is possible to include any dialling command in the entry).
The caller will be asked for the password once again, and will then
be spawned to an OS/2 full screen text session.

If you have OS/2 1.2 or later, it is recommended to put the line
"AUTOFAIL=YES" in your CONFIG.SYS file. This will cause the operating
system NOT to generate pop-up error messages, which would cause the Os2You-
program to hang (or actually be suspended while waiting for a keystroke
from the "real" keyboard).




Using Os2You with pipes or remote pipes with a LAN
==================================================
If you want to use Os2You in a LAN, you should configure Os2You for stand
alone operation (se above), but replace the communication device with a
remote pipe name like "\Pipe\Os2You1" on the server, and
"\\Servername\Pipe\Os2You1" on the workstation accessing Os2You, and select
modem type "P". This will require the special terminal emulation program
LanTerm or LanTerm/2 on the remote machine.

The program LanTerm/2 is used on workstations running OS/2 and LanTerm is
used on workstations running DOS. Both programs function in similar way,
and are started with just one parameter specifying which pipe to use for
communication. Suppose you have configured the system with the pipe name
mentioned above. In this case you start LanTerm or LanTerm/2 by typing:

LanTerm \\Servername\Pipe\Os2You1
LanTerm2 \\Servername\Pipe\Os2You1

at the command line prompt. The LanTerm(/2) program is automaticly terminated
when you exit the remote session. If you terminate LanTerm2 abnormally (like
pressing Ctrl-Break), the host session will be closed at once, and Os2You will
wait for the next "caller" and LanTerm(/2) will be terminated.

If no parameter is specified when starting the LanTerm(/2) program, it will
look for an Os2You.CFG file and try to configure itself using the information
specified in the file (using the Install.EXE program). LanTerm/2 (for OS/2)
may be used for asynchronous communication devices as well as pipes, but
LanTerm (for DOS) will only work with pipes.

With LanTerm(/2) most keys that is possible to emulate with Os2You, are mapped
to their correct keys, except that you have to press twice, for
compatibility reasons. All Esc-sequences used over the asynchronous line
will work with LanTerm(/2) too.

It is possible to start multiple sessions with Os2You using the same Pipe-
name. Each running copy of Os2You will be ready to receive a connect
request from a remote user, and the user will be connected to the first
free instance of Os2You. It isn't even necessary that the Os2You program
is started from the same machine in a LAN. You may start Os2You with
the same pipe name from any LAN station, and a connect request will be
directed to the first free instance.




Terminal emulation
==================
The included files should be run in an OS/2 full screen text session,
and will allow you to connect to it by modem or cable. In addition
to this program, you will need a terminal emulation program, that
is capable of emulating one of the included terminal emulation modes
available with Os2You. It doesn't matter which operating system your
terminal emulator is running. If you use OS/2 you may use the
LANTERM2 program included as your terminal program. It will
remap the keys to their corresponding Esc-sequences, and is also
compatible with Os2You binary mode, making Os2You send attribute
information. This program should be used if you run Os2You over
a LAN (Local Area Network).

The following terminals are supported by Os2You currently
(ANSI is default if none selected):

Terminal Description file
=============================== =================================
ANSI/VT100/VT102 ANSI.PRM (different from default)
Hazeltine 1500 HAZEL.PRM (not tested)
Televideo 910-955/ADM 5/Wyse 50 TELEVID.PRM (not very efficient)
VT52/Heath/Zenith/ADDS VP VT52.PRM

If you want to select another terminal emulation than the default
ANSI terminal, you should copy the corresponding terminal description
file to Os2You.PRM. Note that the description files only alter the
screen output, and does not care about different keystroke combinations
used by different terminals, except the ANSI escape keysequences. Also
note that some terminals will work better if you run Os2You in a screen
with only 24 lines (MODE CO80,24) instead of the more common 25 lines.

If your terminal is not supported with a terminal description file,
you may define your own terminal, using the included TERMDEF-program.
See section 'Defining your own terminal' below.

The program assumes a screen with 80 text columns, and at most 100
lines high. The program automaticly detects how many lines the
OS/2 session contains, but you have to configure your terminal program
for a screen size with at least the same amount of lines (it doesn't
matter if the terminal program uses more lines than the OS/2 session).
It is possible to alter the screen size with the MODE-command, while
connected to Os2You, as long as you keep the screen size rules in mind.

To "emulate" different keystrokes, Esc sequences are used. The following
Esc sequences are valid (note that upper/lower case letters are
significant):

ANSI Esc sequences for cursor movement, translated to the corresponding
arrow key.

Esc-i Insert
Esc-d Delete
Esc-h Home
Esc-e End
Esc-u PgUp
Esc-n PgDn
Esc-t Backtab
Esc-Esc Escape

Esc-A.. Alt-A..
Esc-Z Alt-Z

Esc-1.. F1..
Esc-9 F9

Esc-0 F10
Esc-- (minus) F11
Esc-= (equal) F12

Esc-c Send a Ctrl-Break signal
Esc-p Toggle between physical screen and logical screen
Esc-Break Force Os2You to exit (Break = 03H)
Esc-Space Updates the entire screen
Esc-? Display help text

All characters, except Esc, are translated directly to the corresponding
keystroke. ASCII 01H is translated to Ctrl-A, ASCII 02H to Ctrl-B and so
on.

The above table means that you should press Esc FIRST and THEN a
character. "Esc-i" means that you should press "Esc" first and then
followed by "i". Note that you have to press "Esc" twice, if you want
to emulate a "Esc" keystroke.



File transfer
=============
If you have M2Zmodem version 2.09 or later (another program from the
same source), you may use it to up/download between the host and remote.
I suggest that you copy the M2Zmodem.EXE and M2Zmodem.MSG-files into
the same directory you used for Os2You. Then you should include this
directory in your PATH and DPATH. Then you create the following files
in the same directory:

File Commands
=========== ===================
Sz.Cmd @echo off
M2Zmodem -f 1 -h -s %1

Rz.Cmd @echo off
M2Zmodem -f 1 -h -r

It is now possible to receive files from host to remote (download) by just
typing "Sz " at the command prompt (any wildcards allowed). If you
run M2Zmodem as terminal program at the remote (or any other terminal
program with Zmodem autodownload), the file transfer will be automaticly
started at the terminal side too, if not, you have to request download
in your terminal program.

To send files from remote to host (upload) just type "Rz" at the command
prompt. When you request upload in your terminal program, you should enter
which files to send.

The described configuration uses the fast and reliable Zmodem protocol for
file transfers. If you want to use another, like Xmodem, Xmodem-1K, Ymodem
or Ymodem-G, you could just alter the CMD-files to change your protocol.
The parameters for M2Zmodem are described further in the M2Zmodem.DOC file,
or written to screen, if you just enter M2ZModem at the command prompt.




DOS-compatibility box
=====================
When you run the OS/2 session remote, you may enter the command
"Dos2You" at the command line, and you will get access to the DOS-box
(if available). Note that any user running at the physical screen
will be interruptet when the DOS-box is entered. The cursor position
won't be set correctly when running the DOS session.

Dos2You requires OS/2 version 1.2 or later, and the DOS.SYS driver must
be loaded.

Note that your AUTOEXEC.BAT file should NOT contain any statements that
would require any keyboard input, as the Dos2You program gets control of
the DOS-box AFTER the AUTOEXEC.BAT file is executed, which means that any
user input in the AUTOEXEC.BAT is taken from the "real" keyboard.

To enable Dos2You, you should copy the DOSREDIR.EXE file to a directory
in your DOS-path, or load the DOSREDIR-program in your AUTOEXEC.BAT file.
The DOSREDIR-program is a resident program that will communicate with the
Os2You-program, allowing Os2You to control the DOS session. The DOSREDIR
program requires that a printer port is installed in the system, and will
demand IOPL (put the line "IOPL=YES" in your CONFIG.SYS file). The DOSREDIR
program MAY conflict with the printer stream, but should not cause any other
serious conflicts in your system.

When returning from the DOS-box you have to press Esc-P to reset Os2You to
not use the physical screen area. No extended keys like function keys will
work in the DOS-box.




Defining your own terminal
==========================
If your terminal is not supported by a terminal definition file, you may
create your own with the included TERMDEF program. The program will
create a file called Os2You.PRM (overwriting the existing file!). The
program will ask for several parameters. When not otherwise stated you
should enter the decimal values separated by spaces (max 20 values)
corresponding to the ASCII-code for the characters to be sent.

The program asks for the following:

1. Initializing string. String to initialize the terminal to selected
mode. In most cases should this string be left blank.

2. Cursor position; command. String to begin a cursor position command.

3. Cursor position; separator. String to separate row and column
parameters in cursor position command.

4. Cursor position; end. String to end cursor position command.

5. Cursor position; column first. Enter 'Y' if the column should be sent
as the first parameter, otherwise enter 'N', and the row will be sent
first.

6. Cursor position; column offset. Value with which the column is added
with, before the cursor position command is sent. The left most column
is treated as column 0.

7. Cursor position; row offset. Value with which the row is added
with, before the cursor position command is sent. The top row is
treated as row 0.

8. Cursor position; binary address. Enter 'Y' if the row and column
parameters should be sent as binary values, using one byte each.

9. Cursor position; maximum parameter length. Enter the length the
row and column parameters may be assigned at most. This value should
be set to 1 if binary address is selected. Sometimes it helps to set
this value to a very high value (65000), and cursor positioning will
be avoided at most times.

10.Cursor position; zero pad Col and Row parameters. Enter 'Y' if
the row and column parameters should be padded with leading zeros
up to the length indicated by the above parameter.

11.Scroll screen up. String sent to scroll the screen up one line.
It doesn't matter if the cursor is moved during this command, as
the cursor position will be restored automaticly by the program.
If no special scroll command is available with your terminal, you
should enter a string that places the cursor at the bottom row,
and advance one row.

12.Clear to end of line. String sent to clear the remaining (or all)
of the line the cursor is positioned at. The line should ONLY be
cleared, NOT deleted.

13.Clear screen. String sent to clear the entire screen, and position
the cursor at the home (upper left) position.


Some terminals require a short "breath" after some commands like
clearing the screen and positioning the cursor. This may be
accomplished by entering trailing zeros after the command strings.
Os2You will send these null characters, but your terminal will
in most cases ignore these characters and get their pause.




Calling Os2You from another program
===================================
If you want to start the program from the OS/2 Command prompt without
the phone answering capabilities, or want to call the program from
your own application, the program is started with some parameters.
The program may use a "hot" file handle (already opened).

It is the callers responsibility to set the communication port as
wanted, and Os2You will use the current settings when called.

When the program exits, it restores the communication port to it's previous
state. If a program was successfully spawned the program will exit with
Exit-code set to zero. If the program failed by any reason, the Exit-code
will be set to a non zero value (currently only Exit-code=1 is used).

The parameter syntax is like this:

Os2You ...

Tells which communication device to use. It is
possible to pass a "hot" device handle by replace
the device name with a percent sign directly followed
by the device handle decimal coded (like %4). The
device name may be replaced by a pipe name, but special
care should be taken, when using this possibility. The
best choice when using pipes is to use the stand alone
interface.

Tells how long delay to use between each screen
update (in milliseconds). I recommend a value
between 100 and 2000.

Tells how long to allow operator inactivity before
Os2You is forced to exit (in seconds). If set to
0 (zero) the feature will not be active at all. If
preceeded with a "-" (minus sign) the program will
be terminated if carrier is lost.

Tells which program to load for remote operation.
(Typically CMD.EXE).

... The remaining parameters are optional and are passed as
parameters to .

Examples:

Os2You COM1 1000 300 CMD.EXE /K DIR

This command will tell Os2You to use COM1 and update the screen each 1000
millisecond. If no remote keystroke is received within 300 seconds the
program will be forced to exit. CMD.EXE is loaded for remote operation
with the parameters "/K DIR" (which will tell CMD.EXE to display a
directory list).

Os2You %4 100 -0 CMD.EXE

This command will tell Os2You to use device handle 4 (decimal value) and
update the screen each 100 millisecond. If carrier i lost the program will
be terminated. but no inactivity timer is set.



To be compatible with MaxPipe (TM of Peter Fitzsimmons) an alternate calling
syntax is automaticly invoked, if the second parameter if NOT a number.
In this case, the syntax will be like:

Os2You ...

Tells which communication device to use. It is
possible to pass a "hot" device handle by replace
the device name with a number corresponding to a
the device handle decimal coded (like %4). The
device name may be replaced by a pipe name, but special
care should be taken, when using this possibility. The
best choice when using pipes is to use the stand alone
interface.

Tells which program to load for remote operation.
(Typically CMD.EXE).

... The remaining parameters are optional and are passed as
parameters to .

The parameter will allways be set to 100, no inactivity timer, and no
carrier loss check will be performed.



To select which communication parameters to use, you should use the MODE-
program, included with the operating system. See more in the documentation
for the operating system to see how to configure your communication line.
All communication parameters set with MODE, will be used with Os2You.

Example:

MODE COM1:2400,N,8,1,OCTS=ON,DTR=ON,RTS=HS,BUFFER=ON

This command will tell Os2You to use baud rate 2400, no parity, 8 data bits,
1 stop bit, hardware handshaking CTS/RTS and use the extended hardware
buffering capabilities.





Using callback when calling from another program
================================================
If you want Os2You to use callback processing when calling the program
from another program, you should insert a parameter with the user name
anoywhere in the command line parameter syntax BEFORE the program name
to execute. You should put '"'-signs (double quotes) directly before and
after the user name. The user name must be included in the OS2YOU.CFG
file by running the INSTALL-program. Some examples:

Os2You "Mikael Wahlgren" COM1 1000 300 CMD.EXE /K DIR

This command will tell Os2You to use COM1, callback the user "Mikael
Wahlgren" and update the screen each 1000 millisecond. If no remote
keystroke is received within 300 seconds the program will be forced
to exit. CMD.EXE is loaded for remote operation with the parameters
"/K DIR" (which will tell CMD.EXE to display a directory list).


Os2You "Another User" %4 100 -0 CMD.EXE

This command will tell Os2You to use device handle 4 (decimal value),
callback "Another User" and update the screen each 100 millisecond.
If carrier i lost the program will be terminated. but no inactivity
timer is set.


Os2You "Third User" %4 CMD.EXE

This command will tell Os2You to use device handle 4 (decimal value),
callback "Third User" and update the screen each 100 millisecond.




Multi user configuration
========================
By using Os2You you may actually use OS/2 in a multi user like manner. Note
that Os2You lacks any sort of security control for file managing, which a
"normal" multi user operating system includes.



RELEASE NOTES
=============

1.0: First release.

1.1: Screen updates are improved.

The program has an option to terminate if carrier lost.

The program could terminate with a GP error when run on a PS/2
system. The port-parameters was not correctly restored. This
is now corrected.

1.2: The alternate parameter syntax is introduced.

The program is altered in order to allow M2Zmodem to work with
the same COM-port as Os2You without conflicts.

1.3: Improved "partial screen" scrolling.

1.4: Improved non scrolling performance.

1.5: Bug, that made the program incompatible with some programs
(especially programs polling the keyboard) is fixed.

DOS-box added.

Stand alone configuration improved and operation simplified.

DOS-box security not implemented yet (which would prevent
not selected users to use the DOS-compability box with the
DOS2YOU program). Just remove the Dos2You-program if you
don't want remote operation of the DOS-box.

No help texts available in the installation program.

The 5-minutes limitation in unregistered copies removed.
Unregistered copies are full featured, but this doesn't
mean that you should run the program on a regular basis
without registering.

1.6 Callback processing possible when calling Os2You from another
program by including a user name in the command line parameters
separated by double quotes.

Possible to run Os2You remote over a LAN or via any other pipe.
Use the included Lanterm2-program. If you want to write your
own LAN terminal emulation program, this is done by simply
read/write characters from/to the pipe. The pipe is defined
as a duplex message pipe with 100 bytes buffer in each direction.
An unlimited number of instances are allowed.

Possible to use Os2You with almost any ASCII terminal, by altering
the Os2You.PRM file. Some common terminal definitions and a very
simple program (TermDef.EXE) to define your own terminal are included.

A simple terminal program (LANTerm2.EXE) is included. It will work
with pipes or serial devices. It reads the Os2You.CFG file to
configure itself. Most keys are mapped to their corresponding
ESC-sequences. With this program you may also switch on the
binary mode of Os2You, which will transfer attribute information too.
This is only recommended when running via a pipe. LanTerm.EXE is
the corresponding program for DOS (except it will only work with
pipes). Note that LanTerm (for DOS) is not tested in network
environments, as I couldn't find any OS/2 network with DOS Lan
Requesters able to access pipes at all. When tested between the
DOS-box and an OS/2 session the program worked as it should.




Planned enhancements
====================
The following is a list a enhancements planned in a future release. It
isn't sure that the next release of the program will include these
enhancements though. Probably the next major release (2.0) of Os2You will
be released when OS/2 2.0 is released and any adjustments necessary for
Os2You to work with OS/2 2.0 will be made.

1. A special terminal program with enhanced terminal features for DOS
and OS/2. This will fasten operation, and ease operation, as it you
wouldn't have to remember Esc-sequences to emulate different keys.
Only to registered users.

2. A task manager, making it possible to switch to any OS/2 full screen
text session, and run them remote. Some limitiations will apply
when not running the "original" OS/2 session. Only to registered users.

3. The DOS-box will be improved when OS/2 2.0 is out. No further effort
to improve the DOS-box before that will be made, as the method probably
will have to be changed anyhow.




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 at least 200 SEK (about $30), 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.
This registration file will enable features in the program not available
in unregistered configurations. Note, that the registration file you
get is valid for any future release of this program, and that you will
be treated as registered to any future release.

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).


My bank account is: My address is:

Account no: 414 46 44-4 Mikael Wahlgren
PostGirot Sweden Inter. Kransen 4E
S-105 06 STOCKHOLM S-416 72 GOTHENBURG
Sweden Sweden

SWIFT: PGSI SE SS
Telex: 10185 pgint S


If you are located in one of the following countries I think it would be
easier and cheaper to use the banking service listed (with the same
account no as listed above) addressed to Sweden.
===================

Algeria Compte chques postaux
Belgium Compte chques postaux
Denmark Postgirokonto/Postkonto
Finland Postgirokonto/Postisiirtotili
France Compte chques postaux
Great Britain Girobank Account
Iceland Pstgirreikning
Italia Conto corrente postale
Japan Postal Giro Account
Luxembourgh Compte chques postaux
Marocco Compte chques postaux
the Netherlands Postrekening/Girorekening
Norway Postgirokonto
Switzerland Compte chques postaux/Postcheckkonto Conto corrente postale
Spain Cuenta corriente postal
Tunis Compte chques postaux