This has been prepped as a raw ASCII document and can be sent direct to a printer using a fixed width font
PC Share Data Interface Protocol
Author: J.Bird
Issue : 11
Date : September 5, 1999
Version : 3.2
PC Share Data Interface Protocol
1. Introduction
Message protocol descriptions/capabilities of system between Host computer
and PC Sharer software.
This document is for use with Version 3.0 Software only. There are two
releases of PC-Share, the current Windows release and an upgraded DOS release.
This document pertains to both versions of software, differentiating where
necessary.
1.1 Changes to this document since Issue 1
- updated Mode Change Message (2.1.2.1) to include status response
- included graphic mode descriptions (2.1.1.2.1.1)
- clarified File transfer status messages
- included recognized & actioned VT100 sequences.
1.2 Changes to this document since Issue 2
- updated all status responses to single byte
- included all PC capable graphics modes and Dragon hi-res emulation
(2.1.1.2.1.1)
- redefine file transfer protocol in line with OS9
- maximise VT100 emulation
- include Dragon OS9 GO51 emulation codes
- moved all transfers to single I/O port, define HDISK messages
- implement miscellaneous command structure
1.3 Changes to this document since Issue 3
- baselined document for PCShare V2.X
- restore message header to all status responses
- remove status byte from graphics mode change for V2.X (2.1.1.2)
- remove remaining TBD's (palette data 2.1.1.2.3.1)
- modify file read operations to return status info prior to transferring data
(2.1.1.3.7, 2.1.1.3.8)
- update file status bytes to remove obsolete codes and add new codes
(2.1.1.3.14)
- remove references to deleted functions
- clarify VT100 codes (2.1.2.2)
- include missing Dragon OS9 GO51 codes (2.1.2.3)
1.4 Changes to this document since Issue 4
- initial spec for PCShare V2.1
- add text attributes (colours) message (2.1.1.4.3)
- extended text mode selection (2.1.1.2.1.1)
- removal of GETSTAT & SETSTAT messages, replaced with unique messages for
each GetStat and SetStat function code (2.1.1.3.12 - 2.1.1.3.15)
- add messages for transferal of DOS directory information (2.1.1.3.17).
- 'Change Directory' message returns current directory to host computer
(2.1.1.3.3).
PAGE: 1
PC Share Data Interface Protocol
Author: J.Bird
Issue : 11
Date : September 5, 1999
Version : 3.2
- new 'delete directory' message. (2.1.1.3.16)
1.5 Changes to this document since Issue 5
- baseline issue for PCShare V2.1
- move text mode selection from Graphics Mode (2.1.2.1.1) to a new message
(2.1.1.4.3)
- add support for multiple hard drives (2.1.3.1, 2.1.3.2)
- colour attribute change in VT100 codes
1.6 Changes to this document since Issue 6
- update for new V2.2 release
- new 'device ready' message (2.1.1.3.18)
- PC COM Port configuration message (2.1.1.3.19)
- Extended usage for 'Get File Size' message for serial devices (2.1.1.3.12)
- Additional error code/status byte 'device not ready' (2.1.1.3.20)
- new 'Read Clock' message (2.1.1.4.5)
1.7 Changes to this document since Issue 7
- prelim issue for PCShare V3.0 MS-Windows release
- MS-Windows interface (2.1.4)
- remove obsolete messages with this release (Execute DOS Command, and Set
Text Mode messages)
- graphical interface changes for Windows (2.1.1.2)
1.8 Changes to this document since Issue 8
- baseline issue for PCShare V3.0 DOS and Windows
- include details of both DOS and Windows releases
1.9 Changes to this document since Issue 9
- change to read directory protocol ready for Win95 version:
- issued with PCShare v3.1x
File Open (2.1.1.3.2) used to open a directory
File Close (2.1.1.3.4) used to close a directory
Read Directory Entry (2.1.1.3.17) message structure changed
1.10 Changes to this document since Issue 10
- issue for PCShare v3.2x
Read PC Clock (2.1.1.4.5) year field extended to 4 digits for Y2K
2. PC Remote Sharer System Interface Definition
The PCRSS has one external interface, comprising a single 8 bit wide input and
output port. Each interface is defined as follows: Data is passed in the form
of either textual data to be displayed, or supervisor messages which request
special functions to be performed.
2.1 Data Interface
PAGE: 2
PC Share Data Interface Protocol
Author: J.Bird
Issue : 11
Date : September 5, 1999
Version : 3.2
Data arriving at the input Port is interpreted as textual or message data.
2.1.1 Message Data
Messages issued across the interface are prefaced by a 3 byte header
identifying them. The following data packet will then define the actions to be
performed. If a partial or incomplete message header is received, the received
part of the message header is deemed to be text to be displayed. Messages
comprising integer (2 byte) or long integer (4 byte) words are transmitted
most significant byte (MSB) first. Messages which require a response packet
will be prefaced by the 3 byte message header prior to the packet info to be
transferred in order to allow the host computer to syncronise up the i/o
interface. Note that this response header message may not include the command
byte or packet length. See individual messages for details.
2.1.1.1 Message Header
A message header is identified by the following 3 byte hexadecimal seqence
arriving at the port.
MESSAGE HEADER: $AA, $FF, $FF
COMMAND BYTE : $nn
PACKET LENGTH : $mm
The following byte identifies the command to be performed, and hence the
structure of the remaining data packet. The next byte identifies the length of
the data packet being transmitted.
2.1.1.2 Graphics Messages
These messages affect the graphics operaton of a PC-Share window. Graphics
commands are issued to the current host active window (see 2.1.4.3).
2.1.1.2.1 Set Graphics Mode Message (Windows Version only)
Byte 0 .. 2 : $AA,$FF,$FF Message Header
Byte 3 : $00 Move cursor message
Byte 4 : $06 Byte count
Byte 5 .. 6 : X-co-ord X pixel range
Byte 7 .. 8 : Y co-ord Y pixel range
Byte 9 : X-Sign Origin of X position
Byte 10 : Y-Sign Origin of Y position
This message creates a graphics area of X-pixels by Y-pixels for the current
window. All subsequent X and Y co-ordinates issued through graphics messages
must fall within this range for the window. When the graphics area is
displayed it is scaled to fit the current window size. A value of 0 in both
ranges de-activates graphics mode. The origin values determine where all co-
ordinates are drawn relative to:
X, Y origin Description
0, 0 Origin is top left corner of window
0, 1 Origin is bottom left corner
1, 0 Origin is top right corner
1, 1 Origin is bottom right corner
PAGE: 3
PC Share Data Interface Protocol
Author: J.Bird
Issue : 11
Date : September 5, 1999
Version : 3.2
2.1.1.2.2 Mode Change Message (DOS Version only)
Byte 0 .. 2 : $AA,$FF,$FF Message Header
Byte 3 : $00 Mode Change
Byte 4 : $01 Byte count
Byte 5 : mode Graphics mode id
This message initiates a screen mode change where nn is the graphics mode id
to change to. On receipt of this message the PCRSS will attempt the requested
mode change. If the change is sucessful, the PC will enter graphics mode,
otherwise it will remain in text mode. All other graphics commands will be
ignored unless graphics mode has first been selected.
2.1.1.2.2.1 Graphic Modes (DOS Version only)
The graphics modes available will depend on the graphics card installed in the
host PC, and inherently on the capabilities of the Borland C++ V3.0 GRAPHICS.H
library. The following modes are defined:
Mode ID Description
0 Last Text mode - default (80*25) [80*24 in GO51 emulation mode]
1 CGA 320*200 palette C0
2 CGA 320*200 palette C1
3 CGA 320*200 palette C2
4 CGA 320*200 palette C3
5 CGA 640*200 2 colour
6 MCGA 320*200 palette C0
7 MCGA 320*200 palette C1
8 MCGA 320*200 palette C2
9 MCGA 320*200 palette C3
10 MCGA 640*200 2 colour
11 MCGA 640*480 2 colour
12 EGA 640*200 16 colour
13 EGA 640*350 16 colour
14 EGA64 640*200 16 colour
15 EGA64 640*350 4 colour
16 EGAMONO 640*350 2 colour
17 HERC 720*348 2 colour
18 VGA 640*200 16 colour
19 VGA 640*350 16 colour
20 VGA 640*480 16 colour
21 Dragon PMODE emulation with 16 colours
Dragon PMODE emulation uses a VGA mode, and scales the X/Y co-ordinates
accordingly. The VGA palette is used for colours, which will not tie up with
the expected PMODE palette values.
Other values are undefined in this release of software.
2.1.1.2.3 Move Graphics Cursor Message
Byte 0 .. 2 : $AA,$FF,$FF Message Header
Byte 3 : $01 Move cursor message
Byte 4 : $04 Byte count
PAGE: 4
PC Share Data Interface Protocol
Author: J.Bird
Issue : 11
Date : September 5, 1999
Version : 3.2
Byte 5 .. 6 : X-co-ord X co-ordinate of cursor
Byte 7 .. 8 : Y co-ord Y co-ordinate of cursor
This message moves the current graphics cursor position to the specified X and
Y co-ordinates. The Window/screen display is unaffected.
2.1.1.2.4 Colour Change Message
Byte 0 .. 2 : $AA,$FF,$FF Message Header
Byte 3 : $02 Colour Change message
Byte 4 : $01 Byte count
Byte 5 : Colour Colour id
This message changes the current colour to the requested colour id. The window
display is unaffected.
2.1.1.2.4.1 Colour Palette Values
(DOS Version Only)
Colour palette values depend on the graphics mode selected, and fall into 3
categories:
- for monochrome/2 colour modes a palette value of 0 indicates black, and any
other number indicate white or the other colour the card/monitor is capable of
displaying.
- for CGA modes, the colour values available depend on the palette selected
(either C0, C1, C2 or C3 - see Graphics Mode descriptions).
CGA Palette No. Colour 0 Colour 1 Colour 2 Colour 3
C0 Black L/Green L/Red Yellow
C1 Black L/Cyan L/Magenta White
C2 Black Green Red Brown
C3 Black Cyan Magenta L/Grey
all other palette values are undefined.
(Windows and DOS EGA/VGA modes)
The following colours are available:
Colour ID Colour
0 Black
1 Blue
2 Green
3 Cyan
4 Red
5 Magenta
6 Brown
7 L/Grey
8 D/Grey
9 L/Blue
10 L/Green
11 L/Cyan
12 L/Red
PAGE: 5
PC Share Data Interface Protocol
Author: J.Bird
Issue : 11
Date : September 5, 1999
Version : 3.2
13 L/Magenta
14 Yellow
15 White
Depending on the capabilities of your graphics card and video mode selected,
some of these colours may not appear or may appear as hatched or shaded
colours.
2.1.1.2.5 Set Point Message
Byte 0 .. 2 : $AA,$FF,$FF Message Header
Byte 3 : $03 Set Point message id
Byte 4 : $05 Byte count
Byte 5 .. 6 : X co-ord X co-ordinate of point
Byte 7 .. 8 : Y co-ord Y co-ordinate of point
Byte 9 : Colour Colour of point
This message sets the requested X & Y co-ordinate on the active window to the
requested colour.
2.1.1.2.6 Clear Screen Message
Byte 0 .. 2 : $AA,$FF,$FF Message Header
Byte 3 : $04 Clear screen message id
Byte 4 : $01 Byte count
Byte 5 : Colour Colour of screen
This message clears the active window to the requested colour.
2.1.1.2.7 Draw Line Message
Byte 0 .. 2 : $AA,$FF,$FF Message Header
Byte 3 : $05 Draw line message id
Byte 4 : $09 Byte count
Byte 5 .. 6 : X1 co-ord Starting X co-ordinate of line
Byte 7 .. 8 : Y1 co-ord Starting Y co-ordinate of line
Byte 9 .. A : X2 co-ord Ending X co-ordinate of line
Byte B .. C : Y2 co-ord Ending Y co-ordinate of line
Byte D : Colour Colour of line
This message draws a line between the requested co-ordinates in the specified
colour on the current active window.
2.1.1.2.8 Draw Circle Message
Byte 0 .. 2 : $AA,$FF,$FF Message Header
Byte 3 : $06 Draw circle message id
Byte 4 : $07 Byte count
Byte 5 .. 6 : Radius Radius of circle
Byte 7 .. 8 : X co-ord Centre X co-ordinate of circle
Byte 9 .. A : Y co-ord Centre Y co-ordinate of circle
Byte B : Colour Colour of circle
This message draws a circle of the specified radius at the request co-
ordinates, of the specified colour on the current active window.
PAGE: 6
PC Share Data Interface Protocol
Author: J.Bird
Issue : 11
Date : September 5, 1999
Version : 3.2
2.1.1.2.9 Read Pixel Colour Message
Byte 0 .. 2 : $AA,$FF,$FF Message Header
Byte 3 : $07 Read Pixel Colour message id
Byte 4 : $04 Byte count
Byte 5 .. 6 : X co-ord X co-ordinate of pixel to read
Byte 7 .. 8 : Y co-ord Y co-ordinate of pixel to read
Status Response
Byte 0 .. 2 : $AA,$FF,$FF Message header
Byte 3 : $01 Byte count
Byte 4 : Colour Colour of requested pixel
This message requests the colour of the specified pixel. Upon receipt of this
message, the PCRSS will send the colour of the pixel to the output port. See
para 2.1.1.2.3.1 for the colour value returned.
2.1.1.2.10 Default/Current Settings
The software will maintain a current cursor and colour setting per window.
These settings will be utilised whenever a graphics message sets a cursor co-
ordinate to $FFFF or a colour to $FF. On power up, the current cursor &
current colour will be set to 0. The current colour can only be set by the
Colour Change Message, from which point on all colour bytes within messages
which are set to $FF will utilise this colour.
The current graphics cursor position can be explicitly set by the Move Cursor
Message, which simply updates the current position. The current cursor
position is also updated by any other operation which specifies a cursor
position, for example a request to draw a circle at co-ordinates 100,100 will
set the current cursor position to 100,100.
An example sequence might be:
$AA,$FF,$FF -- Message header
$05,$09 -- line command & byte count
$00,$04,$00,$04 -- starting X/Y is 4,4
$00,$10,$00,$10 -- ending at 16,16
$FF -- using default colour
$AA,$FF,$FF -- Message header
$05,$09 -- line command & byte count
$FF,$FF,$FF,$FF -- starting at last posn (16,16)
$00,$60,$00,$60 -- ending at 140,140
$02 -- using colour 2
2.1.1.3 File Handling Messages
The following messages are interpreted as commands to perform MS-DOS file and
disk operations.
2.1.1.3.1 File Create
Byte 0 .. 2 : $AA,$FF,$FF Message Header
Byte 3 : $08 Create message id
PAGE: 7
PC Share Data Interface Protocol
Author: J.Bird
Issue : 11
Date : September 5, 1999
Version : 3.2
Byte 4 : $01+filenm Byte count
Byte 5 : access mode File access mode
Byte 6 .. nn : filename (chars) ASCII filename/pathname.
Status Message
Byte 0 .. 2 : $AA,$FF,$FF Message Header
Byte 3 : status Status byte
Byte 4 : DOS FCBN File Control block number
This message creates the specified file which must be a valid MS-DOS filename.
On completion of the command, a two byte status message is returned. See para
2.1.1.3.14 for definitions of the status byte returned. The access mode must
be either write only or update. See para 2.1.1.3.15 for definitions of access
modes. The DOS file control block number is only valid if the operation was
successful. All filenames should be terminated with a carriage return (CR).
2.1.1.3.2 File Open
Byte 0 .. 2 : $AA,$FF,$FF Message Header
Byte 3 : $09 Open message id
Byte 4 : $01+filenm Byte count
Byte 5 : access mode File access mode
Byte 6 .. nn : filename (chars) ASCII filename/pathname.
Status Message
Byte 0 .. 2 : $AA,$FF,$FF Message Header
Byte 3 : status Status byte
Byte 4 : DOS FCBN File Control block number
This message opens the specified MS-DOS file (or directory) for the access
mode specified. A two byte status message is returned as per File Create. All
DOS devices may be opened with this queue (ie. LPT1 for the printer). In all
but two cases, the filename is simply passed to MS-DOS for processing - the
special cases are COM ports and access to the MS-Windows clipboard.
COM ports can be opened in two ways. A filespec of 'COMn' (n=1 to 4) opens the
port through DOS (normally sufficient for serial printers). A filespec of
'COMn:' opens the port using the COM port handling code built into PCShare and
allows asynchronous communications to occur between PC and host computer,
through the 'Device Ready' and 'Get File Size' calls along with the standard
read/write calls.
Directory files may only be opened for read access only (dir+read).
(Windows Version Only)
Text files (up to 64K) can be copied directly to/from the MS-Windows clipboard
by specifying the name 'CLIP:', however the file access mode must be either
READ or WRITE.
Use of the 'CLIP:' filename with the DOS release will simply result in a
normal disk file access of filename 'CLIP.'
2.1.1.3.3 Change Directory
PAGE: 8
PC Share Data Interface Protocol
Author: J.Bird
Issue : 11
Date : September 5, 1999
Version : 3.2
Byte 0 .. 2 : $AA,$FF,$FF Message Header
Byte 3 : $0A Change directory message id
Byte 4 : $filenm Byte count
Byte 5 .. nn : filename (chars) ASCII dirname/pathname.
Status Message
Byte 0 .. 2 : $AA,$FF,$FF Message Header
Byte 3 : status Status byte
Byte 4 : $dirnm Byte count
Byte 5 .. nn : current dir name ASCII current directory
This message executes a DOS change directory command according to the
directory path specified. The PCRSS software will respond with a status
message, which if the operation was successful will be followed by the current
full DOS directory in the form C:\name1\name2\name(n). The byte count supplied
indicates the length of the directory name. On a single tasking host computer,
the message can be used to change to a new directory and ignore the returned
current directory data.
If the host computer supports multi-tasking it should use this message to
validate that the directory exists, and use the return information to keep
track of where on the DOS disk it's current path is. All subsequent filenames
or directory names not specifying a full path should use this information in
their pathnames or issue a Change Directory request to that path prior to
performing the operation. For example, if the current directory is C:\TEMP and
you want to open a file TEST.DAT in that directory you should supply the
filename as C:\TEMP\TEST.DAT *not* just as TEMP.DAT. Likewise, if you want to
change into the sub-directory TESTDATA, specify C:\TEMP\TESTDATA as the
directory to change to. This is because DOS is a single tasking system, and if
another task on the host computer issues a change dir message, to C:\DOS for
example and the former task did not specify the full directory name, just
using TEMP.DAT the file would then be created in the C:\DOS directory.
2.1.1.3.4 File Close
Byte 0 .. 2 : $AA,$FF,$FF Message Header
Byte 3 : $0B File Close message id
Byte 4 : $01 Byte count
Byte 5 : DOS FCBN File Control block no.
Status Message
Byte 0 .. 2 : $AA,$FF,$FF Message Header
Byte 3 : status Status byte
This message closes the specified DOS file control block number and returns a
single byte status message.
2.1.1.3.5 File Delete
Byte 0 .. 2 : $AA,$FF,$FF Message Header
Byte 3 : $0C Delete file message id
Byte 4 : $filenm Byte count
Byte 5 .. nn : filename (chars) ASCII filename/pathname.
PAGE: 9
PC Share Data Interface Protocol
Author: J.Bird
Issue : 11
Date : September 5, 1999
Version : 3.2
Status Message
Byte 0 .. 2 : $AA,$FF,$FF Message Header
Byte 3 : status Status byte
This message deletes the DOS file specified and returns a single status byte
message.
2.1.1.3.6 Make Directory
Byte 0 .. 2 : $AA,$FF,$FF Message Header
Byte 3 : $0D Make directory message id
Byte 4 : $filenm Byte count
Byte 5 .. nn : filename (chars) ASCII dirname/pathname.
Status Message
Byte 0 .. 2 : $AA,$FF,$FF Message Header
Byte 3 : status Status byte
This message creates the specified directory and returns a single status byte.
2.1.1.3.7 File Read (Binary)
Byte 0 .. 2 : $AA,$FF,$FF Message Header
Byte 3 : $0E Read data message id
Byte 4 : $03 Byte count
Byte 5 : DOS FCBN File Control Block No
Byte 6 .. 7 : Byte count Size of block to read (requested)
Status Message
Byte 0 .. 2 : $AA,$FF,$FF Message Header
Byte 3 : status Status byte
Byte 4 .. 5 : Byte count Size of block read (actual)
Byte 6 .. n : data Transfer data
This operation requests a binary read from the DOS FCB specified of up to 64K-
1 bytes. If the status byte does not indicate any error, then a byte count
indicating the actual number of byte obtained is returned, followed by the
data itself. The byte count actual will be the same as requested unless end-
of-file occured part way through the block. An end-of-file error will then be
returned in the status byte the next time File Read is called. Note that
status bytes 0 .. 3 are only returned if any error (including EOF) occured.
2.1.1.3.8 File Read (Text)
Byte 0 .. 2 : $AA,$FF,$FF Message Header
Byte 3 : $0F Readln data message id
Byte 4 : $03 Byte count
Byte 5 : DOS FCBN File Control Block No
Byte 6 .. 7 : Byte count Size of block to read (requested)
Status Message
Byte 0 .. 2 : $AA,$FF,$FF Message Header
PAGE: 10
PC Share Data Interface Protocol
Author: J.Bird
Issue : 11
Date : September 5, 1999
Version : 3.2
Byte 3 : status Status byte
Byte 4 .. 5 : Byte count Size of block to read (actual)
Byte 6 .. n : data Transfer data
This message requests a text read from the requested file control block of up
to 64K-1 bytes. If the status byte does not indicate any error, then a byte
count indicating the actual number of byte obtained is returned, followed by
the data itself. The byte count actual will be the same as requested unless
end-of-file occured part way through the block or an end of line terminator
occurs prior to the block size requested. If EOF occured an end-of-file error
will then be returned in the status byte the next time File Read is called.
Note that status bytes 0 .. 3 are only returned if any error (including EOF)
occured.
2.1.1.3.9 File Seek Request
Byte 0 .. 2 : $AA,$FF,$FF Message Header
Byte 3 : $10 File Seek message id
Byte 4 : $05 Byte count
Byte 5 : DOS FCBN File Control Block No
Byte 6 .. 9 : File position
Status Message
Byte 0 .. 2 : $AA,$FF,$FF Message Header
Byte 3 : status Status byte
This message sets the logical file pointer within the file control block to
the longword value specified.
2.1.1.3.10 File Write (binary)
Byte 0 .. 2 : $AA,$FF,$FF Message Header
Byte 3 : $11 File Write message id
Byte 4 : $03 Byte count
Byte 5 : DOS FCBN File Control Block No
Byte 6 .. 7 : Byte count Size of block to write (requested)
Byte 8 .. n : transfer data
Status Message
Byte 0 .. 2 : $AA,$FF,$FF Message Header
Byte 3 : status Status byte
Byte 4 .. 5 : Byte count Size of block written (actual)
This message requests a binary write to the requested file control block of up
to 64K-1 bytes. If the status byte indicates an error has occured, the byte
count word will not be transferred. Under V2.X of the PCRSS, if no error
occured the byte count actual will always match the byte count requested.
2.1.1.3.11 File Write (text)
Byte 0 .. 2 : $AA,$FF,$FF Message Header
Byte 3 : $12 File Writeln message id
Byte 4 : $03 Byte count
Byte 5 : DOS FCBN File Control Block No
PAGE: 11
PC Share Data Interface Protocol
Author: J.Bird
Issue : 11
Date : September 5, 1999
Version : 3.2
Byte 6 .. 7 : Byte count Size of block to write (requested)
Byte 8 .. n : transfer data
Status Message
Byte 0 .. 2 : $AA,$FF,$FF Message Header
Byte 3 : status Status byte
Byte 4 .. 5 : Byte count Size of block written (actual).
This message requests a text write to the requested file control block of up
to 64K-1 bytes. If the status byte indicates an error during the write, then
the byte count word will not be sent. The Byte Count actual will match the
Byte Count requested unless an end-of-line character occured in the data block
prior to the requested size, in which case data only up to and including the
first end-of-line character will be written.
2.1.1.3.12 Get File Size
Byte 0 .. 2 : $AA,$FF,$FF Message Header
Byte 3 : $13 Get File Size message id
Byte 4 : $01 Byte count
Byte 5 : DOS FCBN File Control Block No
Status Message
Byte 0 .. 2 : $AA,$FF,$FF Message Header
Byte 3 : status Status byte
Byte 4 .. 7 : File Size Size of file in bytes
This message returns the file size of the File Control block specified as a 4
byte longword. For serial device (COMx) opened in PCShare serial mode (see
File Open message) this message will return the number of bytes available in
the receive queue.
2.1.1.3.13 Get File Position
Byte 0 .. 2 : $AA,$FF,$FF Message Header
Byte 3 : $14 Get File Size message id
Byte 4 : $01 Byte count
Byte 5 : DOS FCBN File Control Block No
Status Message
Byte 0 .. 2 : $AA,$FF,$FF Message Header
Byte 3 : status Status byte
Byte 4 .. 7 : File Position Current file position
This message returns the current file pointer of the File Control block
specified as a 4 byte longword.
2.1.1.3.14 Test For End-Of-File
Byte 0 .. 2 : $AA,$FF,$FF Message Header
Byte 3 : $19 EOF message id
Byte 4 : $01 Byte count
Byte 5 : DOS FCBN File Control Block No
PAGE: 12
PC Share Data Interface Protocol
Author: J.Bird
Issue : 11
Date : September 5, 1999
Version : 3.2
Status Message
Byte 0 .. 2 : $AA,$FF,$FF Message Header
Byte 3 : status Status byte
This message returns the End-Of-File status for the File Control block
specified as the status byte.
2.1.1.3.15 Set File Size
Byte 0 .. 2 : $AA,$FF,$FF Message Header
Byte 3 : $1A Set File Size message id
Byte 4 : $05 Byte count
Byte 5 : DOS FCBN File Control Block No
Byte 6 .. 9 : File Size Longword file size
Status Message
Byte 0 .. 2 : $AA,$FF,$FF Message Header
Byte 3 : status Status byte
This message sets the file size of the File Control block number specified.
2.1.1.3.16 Delete Directory
Byte 0 .. 2 : $AA,$FF,$FF Message Header
Byte 3 : $1B Delete directory message id
Byte 4 : $filenm Byte count
Byte 5 .. nn : filename (chars) ASCII dirname/pathname.
Status Message
Byte 0 .. 2 : $AA,$FF,$FF Message Header
Byte 3 : status Status byte
This message deletes the specified directory and returns a single status byte.
The directory must be empty for the delete to succeed.
2.1.1.3.17 Read Directory Entry
Byte 0 .. 2 : $AA,$FF,$FF Message Header
Byte 3 : $1C Read Directory Entry ID
Byte 4 : DOS FCBN File Control Block No.
Byte 5 .. 6 : direntry Directory entry no.
Status Message
Byte 0 .. 2 : $AA,$FF,$FF Message Header
Byte 3 : status Status byte
Byte 4 : byte count Length of pathname
Byte 5 .. nn : entry name Filename/directory name
This message returns information about a given directory entry of a DOS
directory. The directory must have previously been opened with the open
command with read directory access and the directory entry number must be an
PAGE: 13
PC Share Data Interface Protocol
Author: J.Bird
Issue : 11
Date : September 5, 1999
Version : 3.2
integer number from 0 to total no. of entries. A status byte of EOF is
returned if an entry higher than the number of directory entries is supplied.
If the operation is successful, a byte count is returned indicating the length
of the directory entry to be returned, followed by the entry information. For
MS-DOS and Windows 3.1 this can be up to 13 characters (8 dot 3 filenames),
for Windows 95 a maximum of 255 characters can be returned.
2.1.1.3.18 Test Device Ready
Byte 0 .. 2 : $AA,$FF,$FF Message Header
Byte 3 : $1F Test Device Ready ID
Byte 4 : $01 Byte count
Byte 5 : DOS FCBN File Control Block No.
Status Message
Byte 0 .. 2 : $AA,$FF,$FF Message Header
Byte 3 : status Status byte
This message tests if a DOS serial device opened in PCShare serial mode has
data available for the host computer. The Status Byte returns 00 (Okay) if
data is available and 07 (Device Not Ready) if no data is available. For non
serial device, a Device Not Ready is always returned.
2.1.1.3.19 Set COM Port Configuration
Byte 0 .. 2 : $AA,$FF,$FF Message Header
Byte 3 : $20 Set COM Port Config ID
Byte 4 : $05 Byte count
Byte 5 : COMn COM Port ID (1-4)
Byte 6 : Baud Rate Id Baud Rate Id (0-10) - see below.
Byte 7 : Data Bits No. of data bits (5-8)
Byte 8 : Parity Id Parity Id(0=None,1=Odd,2=Even,3=Mark,4=Spc)
Byte 9 : Stop Bits No. of stop bits (1-2).
Baud Rate Settings are as follows: 0 - 110, 1 - 150, 2 - 300, 3 - 1200, 4 -
2400, 5 - 4800, 6 - 9600, 7 - 19200, 8 - 38400, 9 - 57600, 10 - 115200.
This message configures a PC's COM port ready for serial IO with the host
computer. All 4 ports can be configured. The settings supplied in this message
only take effect when the port is opened in PCShare serial mode (see File Open
message) otherwise they revert to the DOS MODE command settings.
2.1.1.3.18 Status Byte
The following status byte values are defined:
00 = OK
01 = File Not Available. File could not be found or is unable to be created
or opened.
02 = Buffer Allocate Failure. A file read/write transfer buffer could not be
allocated.
03 = Read Failure.
04 = Write Failure.
05 = End of File.
PAGE: 14
PC Share Data Interface Protocol
Author: J.Bird
Issue : 11
Date : September 5, 1999
Version : 3.2
06 = General IO failure. Other error condition prevented the function from
being performed correctly.
07 = Device Not Ready. Device has no data available.
2.1.1.3.19 Open/Create Access Modes
The following access modes are permitted for Open/Create calls:
01 = Read (not create)
02 = Write
03 = Update
8x = Open directory file (combined with either read,write or update).
2.1.1.4 Miscellaneous Messages
The following messages request the PCRSS to perform various miscellaneous
functions.
2.1.1.4.1 Execute DOS Command Message (DOS Version only)
Byte 0 .. 2 : $AA,$FF,$FF Message Header
Byte 3 : $15 Execute DOS message id
Byte 4 : $cmdlen Byte count
Byte 5 .. nn : DOS Command ASCII DOS command
This message causes the ASCII command string to be extracted, and the PCRSS to
fork a new command shell to execute the command. No status is returned, the
results will be displayed on screen. The usual limitations apply with forked
shells - loading TSR's or executing Windows is not advisible. The PCRSS will
be unable to respond to further requests until the command has completed.
2.1.1.4.2 Emulation Select Message
Byte 0 .. 2 : $AA,$FF,$FF Message Header
Byte 3 : $16 Emulation message id
Byte 4 : $01 Byte count
Byte 5 : Emulation byte Select code
This message selects the terminal emulation which will be performed by the
PCRSS within the current active window or screen. Currently defined modes are:
0 = No Emulation
1 = VT100
2 = Dragon OS9 GO51 codes
2.1.1.4.3 Set Text Attributes Message
Byte 0 .. 2 : $AA,$FF,$FF Message Header
Byte 3 : $1D Text Attributes message id
Byte 4 : $02 Byte count
Byte 5 : Fore Colour Text colour
Byte 6 : Back Colour Text background colour
This message sets the text colours displayed for the current active window.
See paragraph 2.1.1.2.3.1 for EGA/VGA colour palette values valid for this
message. DOS Version: Text colours default to white on black in graphics
PAGE: 15
PC Share Data Interface Protocol
Author: J.Bird
Issue : 11
Date : September 5, 1999
Version : 3.2
modes.
2.1.1.4.4 Set Text Mode Message (DOS Version only)
Byte 0 .. 2 : $AA,$FF,$FF Message Header
Byte 3 : $1E Text Mode message id
Byte 4 : $01 Byte count
Byte 5 : Mode Mode code
This message sets the current text mode according to the mode id code as
follows:
0 = 40*25 (24 in GO51 mode)
1 = 80*25 (24 in GO51 mode)
2 = 80*43/50 (EGA/VGA monitors only)
Text colours and attributes remain unchanged.
2.1.1.4.5 Read PC Clock
Byte 0 .. 2 : $AA,$FF,$FF Message Header
Byte 3 : $21 Read Clock Message Id
Byte 4 : $00
Status Message
Byte 0 .. 2 : $AA,$FF,$FF Message Header
Byte 3 : $07 Byte Count
Byte 4 .. 5 : Year Time/date packet
Byte 6 : Month
Byte 7 : Day
Byte 8 : Hour
Byte 9 : Minutes
Byte 10 : Seconds
This message reads the current system time and date from the PC and returns it
in a 7 byte packet to the host computer.
2.1.2 Text Data
Bytes arriving at the input port that are not recognized as valid messages are
treated as textual data to be displayed. All textual data is sent to the
current active window (see 2.1.4.3). Prior to displaying, the data may be
passed through a piece of terminal emulation software depending on the
emulation mode selected for the window. The emulation mode will interpret
special escape sequences and perform screen handling operations (such as
cursor positions) accordingly.
2.1.2.2 Recognized & Processed VT100 Escape Sequences (Release 3.0)
Recognized & processed VT100 escape codes are detailed in the table below. Any
escape sequence not listed as recognized will be output to the PCs screen or
active window as text allowing any other external peice of software to handle
it if required. Any escape sequence listed as recognized but not processed
will not be sent to the screen.
PAGE: 16
PC Share Data Interface Protocol
Author: J.Bird
Issue : 11
Date : September 5, 1999
Version : 3.2
Notes: ^[ = escape character (27)
= ASCII single or double digit character. Vertical coord.
= ASCII single or double digit character. Horizontal co-ord.
= ASCII single or double digit character.
VT100 Sequence Description Processed
DOS Version Windows Version
^G Bell. Yes. No.
^H Backspace. Yes. Yes.
^K Home. Yes. Yes.
^L Clear Screen. Yes. Yes.
^I Tab. Yes. Yes.
^[[20h Set new line mode. No. No.
^[[?1h Set cursor key to app. No. No.
^[[?3h Set number of cols 132. No. Yes.
^[[?4h Set smooth scrolling. No. No.
^[[?5h Set reverse video. Yes. Yes.
^[[?6h Set origin to relative. No. No.
^[[?7h Set auto wrap mode. Yes. Yes.
^[[?8h Set auto repeat mode. No. No.
^[[?9h Set interlacing mode. No. No.
^[[20l Set line feed mode. No. No.
^[[?1l Set cursor key to curs. No. No.
^[[?2l Set VT52 No. No.
^[[?3l Set number of cols 80. No. Yes.
^[[?4l Set jump scrolling No. No.
^[[?5l Set normal video. Yes. Yes.
^[[?6l Set origin to absolute. No. No.
^[[?7l Reset auto wrap mode. No. Yes.
^[[?8l Reset auto repeat mode. No. No.
^[[?9l Reset interlacing mode. No. No.
^[= Set alternate keypad. No. No.
^[> Set numeric keypad. No. No.
^[(A Set UK G0 characters. No. No.
^[)A Set UK G1 characters. No. No.
^[(B Set US G0 characters. No. No.
^[)B Set US G1 characters. No. No.
^[(0 Set G0 special chars. No. No.
^[)0 Set G1 special chars. No. No.
^[(1 Set G0 alt. ROM No. No.
^[)1 Set G1 alt. ROM No. No.
^[(2 Set G0 alt char ROM No. No.
^[)2 Set G1 alt char ROM No. No.
^[N Set single shift 2. No. No.
^[O Set single shift 3. No. No.
^[[m Turn off char. attrs. Yes. Yes.
^[[0m Turn off char. attrs. Yes. Yes.
^[[1m Turn bold mode on. light blue Yes(font permitting)
^[[2m Turn low intesity mode. Yes. Yes.
^[[4m Turn underline mode on. light green Yes(font permitting)
^[[5m Turn blinking mode on. Yes. Pink.
^[[7m Turn reverse video on. Yes. Yes.
^[[8m Turn invisible mode on. Yes. Yes.
^[[;r Define window. Yes. No.
^[[A Move cursor up n lines. Yes. Yes.
PAGE: 17
PC Share Data Interface Protocol
Author: J.Bird
Issue : 11
Date : September 5, 1999
Version : 3.2
^[[B Move cursor down n Yes. Yes.
^[[C Move cursor right n Yes. Yes.
^[[D Move cursor left n Yes. Yes.
^[[H Move cursor to top left Yes. Yes.
^[[;H Move cursor to top left Yes. Yes.
^[[;H Move cursor position Yes. Yes.
^[[f Move cursor to top left Yes. Yes.
^[[;f Move cursor to top left Yes. Yes.
^[[;f Move cursor position. Yes. Yes.
^[D Move window up 1 line Yes. No.
^[M Move window down 1 line Yes. No.
^[E Move to next line. Yes. Yes.
^[7 Save cursor & attrs. Yes. Yes.
^[8 Restore cursor & attrs. Yes. Yes.
^[H Set TAB at current col. Yes. Yes.
^[[g Clear TAB at current colYes. Yes.
^[[0g Clear TAB at current colYes. Yes.
^[[3g Clear all TABs Yes. Yes.
^[#3 Double height/top half No. No.
^[#4 Double height/btm half No. No.
^[5m Single width, single hg Yes. Yes.
^[6m Double width, single gt No. No.
^[[K Clear line cursor right Yes. Yes.
^[[0K Clear line cursor right Yes. Yes.
^[[1K Clear line cursor left. Yes. Yes.
^[[2K Clear entire line. Yes. Yes.
^[[J Clear screen cursor dwn Yes. Yes.
^[[0J Clear screen cursor dwn Yes. Yes.
^[[1J Clear screen cursor up. Yes. Yes.
^[[2J Clear entire screen. Yes. Yes.
^[5n Device Status Report. No. No.
^[6n Get cursor position. No. No.
^[[c Identify terminal type. No. No.
^[c Reset terminal. Yes. Yes.
^[#8 Screen alignment displ. No. n/a
^[[2;1y Confidence power up. No. No.
^[[2;2y Confidence loopback. No. No.
^[[2;9y Repeat power up test. No. No.
^[[2;10y Repeat loopback test. No. No.
^[[0q Turn off all 4 leds. n/a n/a
^[[1q Turn on led 1 n/a n/a
^[[2q Turn on led 2 n/a n/a
^[[3q Turn on led 3 n/a n/a
^[[4q Turn on led 4 n/a n/a
2.1.2.3 Dragon OS9 GO51 Codes
All the Dragon OS9 GO51 escape codes are recognized and actioned:
^[ = Escape
^[A Set Cursor position.
Note X & Y are single byte values as opposed to their ASCII
representation used under VT mode.
^[B Clear to end of line.
PAGE: 18
PC Share Data Interface Protocol
Author: J.Bird
Issue : 11
Date : September 5, 1999
Version : 3.2
^[C Move cursor right 1 character
^[D Move cursor up 1 line
^[E Move cursor down 1 line
^[F Reverse field on
^[G Reverse field off
^[H Underline on. Represented by selecting red characters.
^[I Underline off.
^[J Clear to end of screen.
^[K Scroll up one line.
^[L Scroll down one line.
^G Bell (not actioned under Windows version)
^H Backspace
^J Line Feed
^L Home
^M Cls/Home
2.1.3 Hard Disk Implementation
The pseudo hard disks are implemented by the following two messages to read &
write a specific logical sector number on a given drive.
2.1.3.1 Read Sector Message
Byte 0 .. 2 : $AA,$FF,$FF Message Header
Byte 3 : $17 Read Sector message id
Byte 4 : $05 Byte count
Byte 5 : Drive Drive number
Byte 6 .. 9 : LSN Logical Sector no.
Status Message:
Byte 0 .. 2 : $AA,$FF,$FF Message Header
Byte 3 : Status byte
Byte 4 .. n : Sector data
This message requests the specified sector according to the LSN supplied from
the secified drive. The Logical Sector Number specifies the sector number on
the shared hard drive number from 0 to a possible 2^24-1. Up to 256 drives are
theorhetically possible.
The PCRSS will first transfer a status byte (see para 2.1.2.1.14 for status
byte definitions), and if is ok the sector data will then follow. The amount
of data transferred depends on the sector size configuration defined when the
PCRSS is setup.
2.1.3.2 Write Sector Message
Byte 0 .. 2 : $AA,$FF,$FF Message Header
Byte 3 : $18 Write Sector message id
Byte 4 : $05 Byte count
Byte 5 : Drive Drive number
Byte 6 .. 9 : LSN Logical Sector no.
Byte 10.. n : sector data
PAGE: 19
PC Share Data Interface Protocol
Author: J.Bird
Issue : 11
Date : September 5, 1999
Version : 3.2
Status Message:
Byte 0 .. 2 : $AA,$FF,$FF Message Header
Byte 3 : Status byte
Upon receiving this message, the PCRSS will transfer the sector data to the
LSN specified on the shared hard drive specified and return a single status
byte indicating the status of the transfer.
2.1.4 Windows Messages
These messages provide the host computer's interface to the MS-Windows
environment. For DOS versions, these messages are recognized and where
necessary provide a default status response to enable the same driver set to
be utilised with both DOS/Windows provided an attempt is not made to open more
than one window.
2.1.4.1 Open Window
Byte 0 .. 2 : $AA,$FF,$FF Message Header
Byte 3 : $30 Open Window message ID
Byte 4 : $winname Byte count
Byte 5 .. nn : winname (chars) ASCII window name
(Windows Version)
Status Message:
Byte 0 .. 2 : $AA,$FF,$FF Message Header
Byte 3 : $01 Byte count
Byte 4 : WIN-ID Window ID
This message opens a new display window within PC-Share and gives it the name
specified. A status message is returned indicating the new identity of the
window just opened. A window ID of 0 is returned if the window could not be
opened.
(DOS Version)
Status Message:
Byte 0 .. 2 : $AA,$FF,$FF Message Header
Byte 3 : $01 Byte count
Byte 4 : $01 Dummy Window Id.
This message is ignored, the status message always returns with a dummy window
identifier of 1.
2.1.4.2 Close Window
Byte 0 .. 2 : $AA,$FF,$FF Message Header
Byte 3 : $31 Close Window message id
Byte 4 : $01 Byte count
Byte 5 : WIN-ID Window ID
(Windows Version)
PAGE: 20
PC Share Data Interface Protocol
Author: J.Bird
Issue : 11
Date : September 5, 1999
Version : 3.2
This message close the display window with the given ident. If the window is
not already open, this message is ignored.
(DOS Version)
This message is ignored.
2.1.4.3 Set Active Window
Byte 0 .. 2 : $AA,$FF,$FF Message Header
Byte 3 : $32 Set Active Window message ID
Byte 4 : $01 Byte count
Byte 5 : WIN-ID Window ID
(Windows Version)
This message sets the specified window as active for the host computer. All
subsequent text, graphical and video control (eg. emulation select) output
will then be sent to this window. This window need not be the same as the
currently selected one within MS-Windows (see 2.1.4.4 Get Active Window).
(DOS Version)
This message is ignored.
2.1.4.4 Get Window Status
(Windows Version)
Byte 0 .. 2 : $AA,$FF,$FF Message Header
Byte 3 : $33 Get Active Window Message ID
Byte 4 : $01 Byte count
Byte 5 : WIN-ID Window ID
Status Message:
Byte 0 .. 2 : $AA,$FF,$FF Message Header
Byte 3 : $nn Byte Count
Byte 4 .. nn : Input Text Keyboard/Paste buffer
This message requests the PC to pass any textual data that may have been sent
to the window id specified. This can come from the PC's keyboard or from the
Windows clipboard via a Paste request. Up to 255 bytes of data may be returned
in this message as specified by the byte count. A byte count of 0 indicates no
data has been sent to the window.
(DOS Version)
Byte 0 .. 2 : $AA,$FF,$FF Message Header
Byte 3 : $33 Get Active Window Message ID
Byte 4 : $01 Byte count
Byte 5 : $xx Don't care
Status Message:
Byte 0 .. 2 : $AA,$FF,$FF Message Header
Byte 3 : $nn Byte Count
Byte 4 .. nn : Input Text Keyboard buffer
This message requests the PC to pass the contents of the (PCShare) keyboard
buffer to the host computer. Up to 255 bytes of data may be held and
PAGE: 21
PC Share Data Interface Protocol
Author: J.Bird
Issue : 11
Date : September 5, 1999
Version : 3.2
subsequently returned to the host computer at any one time. A byte count of 0
indicates no data is available in the buffer.
2.1.4.5 Get Active Window
Byte 0 .. 2 : $AA,$FF,$FF Message Header
Byte 3 : $34 Get Active Window message id
Byte 4 : $00 Byte Count
(Windows Version)
Status Message:
Byte 0 .. 2 : $AA,$FF,$FF Message Header
Byte 3 : $01 Byte count
Byte 4 : WIN-ID Window ID
This message requests the currently selected window within MS-Windows (ie. the
one currently highlighted). If PCShare does not have the current focus, then
the last valid window to be selected is returned.
(DOS Version)
Status Message:
Byte 0 .. 2 : $AA,$FF,$FF Message Header
Byte 3 : $01 Byte count
Byte 4 : $01 Dummy Window Id
This message is ignored, a default status message is sent in response.
PAGE: 22