XIO Reference

XIO (eXtended Input/Output) commands provide access to device-specific CIO operations beyond the standard open, close, get, put, and print commands.

Overview

XIO allows you to execute special device-specific commands that are not available through standard CIO operations. Each device handler can implement its own set of XIO commands.

Syntax

XIO #iochn, cmd, aux1, aux2, dev / X.

Performs a general input/output operation on device dev, over channel iochn, with the command cmd and auxiliary bytes aux1 and aux2.

Note: The arguments of XIO statements are in different order than Atari BASIC, for consistency with other statements the iochn is the first argument.

Example:

XIO #1, 33, 0, 0, "D:FILE.TXT"  ' Delete file

Standard XIO Command Codes

These commands are supported by most device handlers:

Code	Operation	Description
3	OPEN	Open a channel (same as OPEN statement)
5	GET RECORD	Get a record (same as INPUT)
7	GET CHARACTERS	Get characters (same as GET)
8	PUT RECORD	Put a record
11	PUT CHARACTERS	Put characters (same as PUT)
12	CLOSE	Close a channel (same as CLOSE statement)
13	STATUS REQUEST	Get device status (same as STATUS statement)
17	DRAW LINE	Draw a line (graphics)
18	FILL	Fill area (graphics)

Disk File Operations

These commands are typically used with disk drives (D: device):

Code	Operation	Description
32	RENAME	Rename a file
33	DELETE	Delete a file
35	LOCK FILE	Lock a file (prevent deletion)
36	UNLOCK FILE	Unlock a file
37	POINT	Set file position
38	NOTE	Get file position
40	LOAD BINARY FILE	Load binary file
41	SAVE BINARY FILE	Save binary file (Atari DOS, SpartaDOS 2.3/3.2)

Example - Delete a file:

XIO #1, 33, 0, 0, "D:OLD.TXT"
IF ERR() <> 1 THEN ? "Error deleting file"

Example - Rename a file:

XIO #1, 32, 0, 0, "D:OLD.TXT,D:NEW.TXT"
IF ERR() <> 1 THEN ? "Error renaming file"

Directory Operations

Directory operations vary by DOS version:

MyDOS

Code	Operation
34	CREATE DIRECTORY
41	CHANGE DIRECTORY

SpartaDOS

Code	Operation
34	LOCK DISK (SpartaDOS 2.3/3.2)
39	GET FILE LENGTH
41	SAVE BINARY FILE (SpartaDOS 2.3/3.2)
42	CREATE DIRECTORY
43	DELETE DIRECTORY
44	CHANGE DIRECTORY
45	SET BOOT FILE
46	UNLOCK DISK (SpartaDOS 2.3/3.2)
49	SET FILE ATTRIBUTES (SpartaDOS X)

Disk Formatting

Code	Operation	Description
253	FORMAT SINGLE DENSITY	Format disk (DOS 2.5)
254	FORMAT DISK	Format disk (default format)

Warning: Formatting operations will erase all data on the disk!

NOTE and POINT

While NOTE and POINT are available as XIO commands (codes 38 and 37), FORGE provides built-in NOTE and POINT statements that are safer and easier to use:

XIO method (not recommended):

' Get file position
XIO #1, 38, 0, 0, "D:FILE.TXT"
SEC = PEEK(ICBLL)  ' Low byte
BYT = PEEK(ICBLH)  ' High byte (actually byte offset)

FORGE method (recommended):

NOTE #1, SEC, BYT  ' Much simpler and safer!

See NOTE/POINT for complete documentation.

Device-Specific Commands

Different devices may support additional XIO commands. Consult the device documentation for specific commands.

R: Device Commands

R: devices (serial ports) may support additional commands for:

Setting baud rate
Configuring serial parameters
Controlling modem functions

See R: Handler for details.

Graphics Commands

Graphics devices support commands like:

DRAW LINE (17)
FILL (18)

Error Handling

Always check ERR() after XIO operations:

XIO #1, 33, 0, 0, "D:FILE.TXT"
IF ERR() <> 1 THEN
  ? "XIO Error: "; ERR()
ENDIF

Common Patterns

Delete a File

XIO #1, 33, 0, 0, "D:FILE.TXT"
IF ERR() = 1 THEN
  ? "File deleted"
ELSE
  ? "Error: "; ERR()
ENDIF

Rename a File

XIO #1, 32, 0, 0, "D:OLD.TXT,D:NEW.TXT"
IF ERR() = 1 THEN
  ? "File renamed"
ELSE
  ? "Error: "; ERR()
ENDIF

Lock/Unlock a File

' Lock file
XIO #1, 35, 0, 0, "D:IMPORTANT.TXT"

' Later, unlock file
XIO #1, 36, 0, 0, "D:IMPORTANT.TXT"

Best Practices

Use FORGE statements when available - NOTE/POINT statements are safer than XIO
Always check errors - Use ERR() after every XIO call
Document device-specific commands - Different devices support different commands
Test thoroughly - XIO commands can have device-specific behavior
Handle errors gracefully - Some commands may fail on certain devices

Troubleshooting

XIO fails:

Check channel is open (if required)
Verify command code is supported by device
Check device name is correct
Verify aux parameters are correct

Unexpected behavior:

Consult device-specific documentation
Check DOS version compatibility
Verify command parameters

xio-reference