Developper's Notes Addendum

HANDLE TYPES AND STRUCTURE

Introduction

The handle is a number for dealing with I/O. When you open an object, you get a handle (in IX). After work, you have to close this handle. The handle structure is very interresting because it is the basis of the management of low level I/O. This document cannot unfortunatly be exhaustive, I just will describe what I have found.

1 - Handle basic structure

The handle structure is 16 bytes frame. They all are in the system RAM (bank $20). They are linked each other downward from $0AF0 (the first) to $0500 (the last). There is so 95 handles available.

Its address define the handle number (the IX value returned). The two first bytes are the link with the next (previous in memory order). The last one ($0500) points to $0000.

2 - Handle types

There is a lot of different handle types. It is always stored in the third byte. If this byte is zero, the handle is free. The structure of the handle depends on its type.

Type Description

$00 Free handle

$01 Device

$02 File/Directory

$03 Memory

$04 Process (or suspended task)

$05 Alarm

$06 Tri-handle

$FA Temporary data

$FB Serial port

Type	Description
$00	Free handle
$01	Device
$02	File/Directory
$03	Memory
$04	Process (or suspended task)
$05	Alarm
$06	Tri-handle
$FA	Temporary data
$FB	Serial port

3 - Structure organisation

3.1 - Device handle

IX+0A Device type
IX+0B Bank of DOR
IX+0C Address of DOR
IX+0E Slot offset if ROM
IX+0F Device code

Device type is :
@00000001 if RAM.-
@xxxxx011 if others

Device code is :
01 RAM.-
02 RAM.1
03 RAM.2
04 RAM.3
05 RAM.0
06 SCR
07 PRT
08 COM
09 NUL
0A INP
0B OUT
81 ROM.0
82 ROM.1
83 ROM.2
84 ROM.3

3.2 - File handle ($02)

Structure

Bytes Length DESCRIPTION

00 01 2 link to next handle

02 1 file handle type ($02)

03 1 dynamic id (of the associated application)

04 05 2 first block (read 'filing.pip' for format)

06 07 2 actual block where file pointer is

08 1 file pointer low byte address

09 1 file attributes (see below)

0A

0B

0C

0D

0E 0F 2 unused

Bytes	Length	DESCRIPTION
00 01	2	link to next handle
02	1	file handle type ($02)
03	1	dynamic id (of the associated application)
04 05	2	first block (read 'filing.pip' for format)
06 07	2	actual block where file pointer is
08	1	file pointer low byte address
09	1	file attributes (see below)
0A
0B
0C
0D
0E 0F	2	unused

File attribute byte:
bit 0 when resetted file is read protected
bit 1 when resetted file is write protected

3.3 - Memory handle ($03)

3.4 - Process handle ($04)

3.5 - Alarm handle ($05)

+02 Type
+03 Dynamic id
+04 (Low Byte)
+05 (High Byte) Next alarm handle (0000 if no alarm link)
+0F must be 00 for being processed...

After there is an internal format date/time. And data for action.

3.6 - Tri handle ($06)

+02 Type ($06)
+04 Slot (0-3)
+05 Table high byte address
+06 Bank
+07 Subtype

Subtype code is :
$F0 Filter handle
$F1 Wildcard handle
$F2 Alarm handle

These calls are managed with the RST $30 followed by one byte.
This byte define the reason. It is the table low byte for the jump.

3.7 - Temporary data ($FA)

Used by OS_EPR / EP_DIR for saving addresses.

+08 Address
+0A Bank

3.8 - Serial port ($FB)

4 - Application handles

They are called handles but they are never associated with data in the handle RAM area. It is in fact its order number when the index polls for applications. You never open one and never close one. Only the last byte (IXL) is significant. The first six bits define the application order number. It starts from 1 to 63. The two last bits define the slot (@00 for internal, @11 for slot 3). So, you can have 4*63=252 applications.

Application handle format (16 bits):

@00000000 ss aaaaaa (ss=slot, aaaaaa=application number)

For example, Index has always $0001 for 'handle'. And the first application in slot 3 is @00000000 11000001=$00C1. For more, read the process structure in 'process.pip'.

5 - Handles management

It is very complex. The basic rule is performed via OS_FN with its three reason codes.

FN_AH ($01) : allocate a handle of B type in IX
FN_VH ($02) : verify IX handle with B type
FN_FH ($03) : free the handle in IX

6 - System handles

Three first handles of the list are special system handles :

Handle Type Usage

$0AF0 $03 Filing system memory pool handle

$0AE0 $FB Serial port handle

$0AD0 $03 Director (Index) memory pool handle

Handle	Type	Usage
$0AF0	$03	Filing system memory pool handle
$0AE0	$FB	Serial port handle
$0AD0	$03	Director (Index) memory pool handle

They are stored in the RAM variables area at :

$0244 Filing system memory pool handle
$0E1E Director memory pool handle

They always remain opened as OZ needs them to manage Files and Processes. Just have a look with a memory dumper.

Thierry Peycru (Zlab), March 1998.