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 : 12
Date : September 5, 1999
Version : 4.0
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 4.0 Software only. This software release
is only available for Windows platforms (Win16 & Win32) and is not applicable
to any DOS release.
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).
- new 'delete directory' message. (2.1.1.3.16)
PAGE: 1
PC Share Data Interface Protocol
Author: J.Bird
Issue : 12
Date : September 5, 1999
Version : 4.0
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
1.11 Changes to this document since Issue 11
- issue for PCShare v4.0x
- remove obsolete DOS sections
Draw Line (2.1.1.2.7) & Draw Circle (2.1.1.2.8) messages extended to include
line styles.
New message Define Colour Palette Entry (2.1.1.2.10) added
PAGE: 2
PC Share Data Interface Protocol
Author: J.Bird
Issue : 12
Date : September 5, 1999
Version : 4.0
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
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
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
PAGE: 3
PC Share Data Interface Protocol
Author: J.Bird
Issue : 12
Date : September 5, 1999
Version : 4.0
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
2.1.1.2.2 Obsolete in this release
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
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
The following colours are available by default:
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
13 L/Magenta
14 Yellow
15 White
PAGE: 4
PC Share Data Interface Protocol
Author: J.Bird
Issue : 12
Date : September 5, 1999
Version : 4.0
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. This colour set aproximatly defines the standard VGA colours.
The Colour Id parameter allows up to 256 colours to be selected, the remaining
undefined values (16-255) or the first 16 may be redefined by use of the
Define Colour Palette Entry message (2.1.1.2.10) which allows any custom
colour to be defined. This colour can then be called up by any of the graphics
functions. Custom colours are unique to each window that is active and are
lost when a window is closed.
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 : $0B 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
Byte E : Width Width of line in pixels
Byte F : Style Style of line
This message draws a line between the requested co-ordinates in the specified
colour & width on the current active window. The defined styles are: 0 =
Solid, 1=Dashed, 2=Dotted. Dashed & Dotted styles are only supported with a
pixel width of 1.
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 : $09 Byte count
Byte 5 .. 6 : Radius Radius of circle
PAGE: 5
PC Share Data Interface Protocol
Author: J.Bird
Issue : 12
Date : September 5, 1999
Version : 4.0
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
Byte C : Width Width of circle in pixels
Byte D : Style Style of line
This message draws a circle of the specified radius at the request co-
ordinates, of the specified colour & width on the current active window. The
supported styles are 0=Solid, 1=Dashed, 2=Dotted. Dashed & Dotted styles are
only supported with a pixel width of 1.
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.11 Define Colour Palette Entry
Byte 0 .. 2 : $AA,$FF,$FF Message Header
Byte 3 : $35 Define Colour Palette Entry message id
Byte 4 : $04 Byte count
Byte 5 : Pal Id Entry in palette to define
Byte 6 : Red Red intensity of colour
Byte 7 : Green Green intensity of colour
Byte 8 : Blue Blue intensity of colour
This message allows an entry in the colour palette (0-255) to be defined to a
specified colour, given by the Red, Green & Blue intensities. This colour can
then be used in subsequent graphics operations by specifiying the required Pal
Id field in the colour entry. Colours 0-15 are preset to defaults so normally
entries 16-255 are defined using this message although the first 16 may be
altered if required.
2.1.1.2.11 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
PAGE: 6
PC Share Data Interface Protocol
Author: J.Bird
Issue : 12
Date : September 5, 1999
Version : 4.0
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
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 Windows
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
PAGE: 7
PC Share Data Interface Protocol
Author: J.Bird
Issue : 12
Date : September 5, 1999
Version : 4.0
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 Windows 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).
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.
2.1.1.3.3 Change Directory
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
PAGE: 8
PC Share Data Interface Protocol
Author: J.Bird
Issue : 12
Date : September 5, 1999
Version : 4.0
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.
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
PAGE: 9
PC Share Data Interface Protocol
Author: J.Bird
Issue : 12
Date : September 5, 1999
Version : 4.0
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
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)
PAGE: 10
PC Share Data Interface Protocol
Author: J.Bird
Issue : 12
Date : September 5, 1999
Version : 4.0
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
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
PAGE: 11
PC Share Data Interface Protocol
Author: J.Bird
Issue : 12
Date : September 5, 1999
Version : 4.0
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
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.
PAGE: 12
PC Share Data Interface Protocol
Author: J.Bird
Issue : 12
Date : September 5, 1999
Version : 4.0
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
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
Windows 3.1 this can be up to 13 characters (8 dot 3 filenames), for Windows
95/NT 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)
PAGE: 13
PC Share Data Interface Protocol
Author: J.Bird
Issue : 12
Date : September 5, 1999
Version : 4.0
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.
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 Obsolete
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
PAGE: 14
PC Share Data Interface Protocol
Author: J.Bird
Issue : 12
Date : September 5, 1999
Version : 4.0
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. Only the 16 predefined colours may be used in this message.
2.1.1.4.4 Obsolete
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.
Notes: ^[ = escape character (27)
PAGE: 15
PC Share Data Interface Protocol
Author: J.Bird
Issue : 12
Date : September 5, 1999
Version : 4.0
= 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
^G Bell. Yes.
^H Backspace. Yes.
^K Home. Yes.
^L Clear Screen. Yes.
^I Tab. Yes.
^[[20h Set new line mode. No.
^[[?1h Set cursor key to app. No.
^[[?3h Set number of cols 132. Yes.
^[[?4h Set smooth scrolling. No.
^[[?5h Set reverse video. Yes.
^[[?6h Set origin to relative. No.
^[[?7h Set auto wrap mode. Yes.
^[[?8h Set auto repeat mode. No.
^[[?9h Set interlacing mode. No.
^[[20l Set line feed mode. No.
^[[?1l Set cursor key to curs. No.
^[[?2l Set VT52 No.
^[[?3l Set number of cols 80. Yes.
^[[?4l Set jump scrolling No.
^[[?5l Set normal video. Yes.
^[[?6l Set origin to absolute. No.
^[[?7l Reset auto wrap mode. Yes.
^[[?8l Reset auto repeat mode. No.
^[[?9l Reset interlacing mode. No.
^[= Set alternate keypad. No.
^[> Set numeric keypad. No.
^[(A Set UK G0 characters. No.
^[)A Set UK G1 characters. No.
^[(B Set US G0 characters. No.
^[)B Set US G1 characters. No.
^[(0 Set G0 special chars. No.
^[)0 Set G1 special chars. No.
^[(1 Set G0 alt. ROM No.
^[)1 Set G1 alt. ROM No.
^[(2 Set G0 alt char ROM No.
^[)2 Set G1 alt char ROM No.
^[N Set single shift 2. No.
^[O Set single shift 3. No.
^[[m Turn off char. attrs. Yes.
^[[0m Turn off char. attrs. Yes.
^[[1m Turn bold mode on. Yes(font permitting)
^[[2m Turn low intesity mode. Yes.
^[[4m Turn underline mode on. Yes(font permitting)
^[[5m Turn blinking mode on. Pink.
^[[7m Turn reverse video on. Yes.
^[[8m Turn invisible mode on. Yes.
^[[;r Define window. No.
^[[A Move cursor up n lines. Yes.
^[[B Move cursor down n Yes.
PAGE: 16
PC Share Data Interface Protocol
Author: J.Bird
Issue : 12
Date : September 5, 1999
Version : 4.0
^[[C Move cursor right n Yes.
^[[D Move cursor left n Yes.
^[[H Move cursor to top left Yes.
^[[;H Move cursor to top left Yes.
^[[;H Move cursor position Yes.
^[[f Move cursor to top left Yes.
^[[;f Move cursor to top left Yes.
^[[;f Move cursor position. Yes.
^[D Move window up 1 line No.
^[M Move window down 1 line No.
^[E Move to next line. Yes.
^[7 Save cursor & attrs. Yes.
^[8 Restore cursor & attrs. Yes.
^[H Set TAB at current col. Yes.
^[[g Clear TAB at current colYes.
^[[0g Clear TAB at current colYes.
^[[3g Clear all TABs Yes.
^[#3 Double height/top half No.
^[#4 Double height/btm half No.
^[5m Single width, single hg Yes.
^[6m Double width, single gt No.
^[[K Clear line cursor right Yes.
^[[0K Clear line cursor right Yes.
^[[1K Clear line cursor left. Yes.
^[[2K Clear entire line. Yes.
^[[J Clear screen cursor dwn Yes.
^[[0J Clear screen cursor dwn Yes.
^[[1J Clear screen cursor up. Yes.
^[[2J Clear entire screen. Yes.
^[5n Device Status Report. No.
^[6n Get cursor position. No.
^[[c Identify terminal type. No.
^[c Reset terminal. Yes.
^[#8 Screen alignment displ. n/a
^[[2;1y Confidence power up. No.
^[[2;2y Confidence loopback. No.
^[[2;9y Repeat power up test. No.
^[[2;10y Repeat loopback test. No.
^[[0q Turn off all 4 leds. n/a
^[[1q Turn on led 1 n/a
^[[2q Turn on led 2 n/a
^[[3q Turn on led 3 n/a
^[[4q Turn on led 4 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.
^[C Move cursor right 1 character
PAGE: 17
PC Share Data Interface Protocol
Author: J.Bird
Issue : 12
Date : September 5, 1999
Version : 4.0
^[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
Status Message:
PAGE: 18
PC Share Data Interface Protocol
Author: J.Bird
Issue : 12
Date : September 5, 1999
Version : 4.0
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.
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
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.
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
This message close the display window with the given ident. If the window is
not already open, 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
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).
2.1.4.4 Get Window Status
PAGE: 19
PC Share Data Interface Protocol
Author: J.Bird
Issue : 12
Date : September 5, 1999
Version : 4.0
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.
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
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.
PAGE: 20