,nj
,pc @
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

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

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)

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

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.

