Tandy 600 User manual

TANDY
Reference D
CUSTOM MANUFACTURED FOR RADIO SHACK, ADIVISION OF TANDY CORPORATION

16 Bit Hand-Held Operating System
Programmers Reference Guide
©1986 Microsoft Corporation
Licensed to Tandy Corporation
All Rights Reserved.
BIOS and BIOS Specification
©1986 OKI Electric Industry Company LTD.
Licensed to Tandy Corporation
All Rights Reserved.
All portions of this software are copyrighted and are the
proprietary and trade secret information of Tandy Corpora-
tion and/or its licensor. Use, reproduction or publication of
any portion of this material without the prior written authori-
zation by Tandy Corporation is strictly prohibited.
Tandy 600
Programmers Reference Guide
BIOS and BIOS Specification
©1986 Tandy Corporation
All Rights Reserved
Reproduction or use, without the express written permission
from Tandy Corporation and/or its licensor, of any portion of
this manual is prohibited. While reasonable efforts have
been taken in the preparation of this manual to assure its
accuracy, Tandy Corporation assumes no liability resulting
from any errors or omissions in this manual, or from the use
of the information contained herein,
Tandy is aregistered trademark of Tandy Corporation.
10987654321

TANDY 600
PROGRAMMERS REFERENCE
BIOS AND BIOS SPECIFICATION
GUIDE

Table of Contents
Page
Section 1—Programmers Reference 1
Interrupt Vectors used by HH O/S 1
Descriptions of Interrupts 2
Error Codes 10
HH O/S Function Calls 11
HH O/S Database Function Calls 76
Applications Programs Under HH O/S 111
Device Drivers Under HH O/S 117
Section 2—BIOS Specification 123
Appendices:
A-Summation of O/S Functions 185
B-Changing Main Menu Labels 191
C-Program Transfer and Conversion 195
D-MS-WORKS Utilities for Development 197

Section 1
PROGRAMMERS
REFERENCE

Interrupt Vectors Used by HH O/S
The following interrupts are used by HH O/S:
INT No. Function
40h Reserved
41 h Reserved
42h HH O/S Function Call
43h DBMS Function Call
44h Free AMI File Space
45h File System Moving
46h Get File Address
47h Translate Address
48h Reserved
49h Reserved
4Ah Reserved
4Bh Reserved
4Ch RS-232C Receiver Hook
4Dh Interval Timer Hook
4Eh Power Low/Off Hook
4Fh Keyboard Queue Hook

Descriptions of Interrupts
INT42h Function Cal
AX
BX
CX
DX
SP:
BP:
SI:
Dl:
XXXXXXXX Entry; AH -Function Code
Other registers are function specific
Exit Function specific
IP:
FLG
CS
DS
SS
ES
See the section on Function Calls for descriptions of the available functions and their entry
and exit parameters.

INT 43h -DB Function Call
AX
BX
CX
DX
XXXXXXXX XXXXXXXX
XXXXXXXX XXXXXXXX
SP:
BP:
SI:
Dl:
IP:
FLG
CS
DS
SS
ES
Entry: AH -Function Code
DS:DX -Parameter Block
Exit AX -Return value or error code
See the section on DBMS Function Calls for descriptions of the available functions and their
entry and exit parameters.
3

INT 44h -Free AMI File Space
AX
BX
CX
DX
SP:
BP:
SI:
Dl:
IP:
FLG
CS
DS
SS
ES
XXXXXXXX XXXXXXXX
XXXXXXXX XXXXXXXX
Entry: CX -Number paragraphs of memory
needed
Exit: AX -Number of paragraphs of memory
released
This hook is provided as amechanism for the HH O/S to request that an application program
release memory space from its AMI. Whenever amemory request has occurred during the
execution of an O/S function call, and there is not sufficient free memory to satisfy the
request, HH O/S will invoke this interrupt with parameters specifying the amount of additional
memory required to satisfy the memory request. The application program may then free up
memory in its AMI file if possible, and return to HH O/S informing it of how much memory may
be recovered from the AMI file.
Some programs may run more efficiently if they can initially allocate alarge block of memory
to their AMI, and then incrementally release it back to the system as required. This hook is
provided to support such applications. It is never necessary for an application program to use
this hook vector.
On entry, CX will specify the number of paragraphs of memory that the O/S requires to
complete the current memory request. The segment registers DS and ES will contain the
same value as on the original entry to the O/S function being executed. The stack registers
SS and SP will point to the stack that was in effect on entry to the O/S function.

If the application program is able to release any memory from its AMI file, it should do so. The
space freed will always be taken from the end of the file, so that any internal data structures
necessary should be moved down to place the free memory at the end of the file. The
application program should then return to the O/S by doing an IRET instruction and return in
AX the number of paragraphs of memory actually made available to the O/S to recover from
the end of the AMI file. If no memory was made available, AX must contain 0.
Any changes to DS, ES, SS, or SP within this hook routine will be remembered by the O/S
and those changed registers will be restored before returning to the application when the O/S
function call completes. If, for example, the application program's stack were at the end of the
AMI, the hook routine could copy the data on the stack down by the requested amount, adjust
SP to point to the new stack location, and then perform the IRET. HH O/S would then
remember the new location of the application program's stack, and that stack would be in
effect when the interrupted function call completes.
HH O/S will have pushed some critical information onto the application program's stack before
performing the INT 44h instruction. For this reason, the hook routine must preserve the
contents of the stack, although it is allowed to move its location.
HH O/S is not reentrant. For this reason, the INT 44h hook routine may not make any HH O/S
function calls. The INT 44h hook routine is allowed to perform any of the HH O/S interrupts
that are explicitly listed as being reentrant.

INT 45h -File System Moving Hook
AX
BX
cx
DX
SP:
BP:
SI:
Dl:
IP:
FLG
CS
DS
SS
ES
Entry: none
Exit: none
The internal file system under HH O/S is an in-memory system. Each file is contained in a
single block of memory up to 64k bytes in size, with the files stored contiguously in memory.
For this reason, when one file grows or shrinks, it causes other files in the system to be
moved to either make more room for afile that is expanding or to occupy the space left by a
file that is contracting.
Because of this dynamic nature of the file system, programs which refer to files through
absolute address pointers need to be kept aware of the movement of files in the system.
Whenever HH O/S moves aportion of the file system, it will invoke the File System Moving
hook. The user provided hook routine can then adjust any internal pointers necessary. Any
program which is concerned about the absolute address of an item in the file system can use
this hook to keep its file pointers current.
The sequence of operations will be as follows:
1. The affected portions of the file system will be moved.
2. The values which were in the program's segment registers at the time of the current
function call will be adjusted as appropriate for the file system movement taking place.
3. The segment portion of the vector address for the File System Moving interrupt will be
adjusted as appropriate for the movement taking place.

4. The File System Moving interrupt will be invoked. The application should adjust any pointers
necessary. The Translate Address interrupt can be used to aid in making these
adjustments. When the hook routine has completed any adjustments it needs to make, it
should perform an IRET to return to HH O/S.
5. HH O/S will complete whatever function call caused the file system to move, and then
return to the program as usual.
Because HH O/S adjusts the program's segment registers automatically, it will not be
necessary for aprogram to use this hook unless it refers to files using absolute file addresses
rather than the read/write function calls. Use of this hook requires careful programming, and
should generally be avoided.
NOTE: HH O/S is not reentrant. Hook routines should not perform any O/S or DBMS
function calls. The only O/S operations allowed within the hook routine are INT
46h, Get File Address, and INT 47h, Translate Address.

INT46h -Get File Address
AX
BX
CX
DX
XXXXXXXX XXXXXXXX
XXXXXXXX XXXXXXXX
SP:
BP:
SI:
Dl:
IP:
FLG
CS
DS
ss
ES
Entry: BX -File handle of opened file
Exit: AX -Status code or file segment
address
HH O/S is not reentrant. For this reason, device drivers and interrupt service routines can't call
HH 0/S functions. If adevice driver, or an interrupt service routine needs to be able to find the
absolute address of afile it may do so using this interrupt.
If HH O/S is not able to supply the file address at the time of the call, the Invalid Access
Request error will be returned. In this case, the program should repeatedly call INT 46h until
this error no longer occurs.
If BX contains OFFFFh, the address of the AMI for the currently executing program is returned.
8

INT 47h -Translate Address
AX
BX
CX
DX
SP:
BP:
SI:
Dl:
IP:
FLG
CS
DS
SS
ES
XXXXXXXX XXXXXXXX
XXXXXXXX XXXXXXXX
Entry: CX -Number of addresses to translate
DS:DX -Pointer to block of addresses to
translate
Exit none
XXXXXXXXXXXXXXXXXXX
User hook routines which use the File System Moving hook (INT 45h), may use this interrupt
to adjust file segment pointers. The contents of DS:DX point to ablock of words containing
segment addresses which may need adjustment, and CX specifies the number of values in
the block. This function will adjust these segment addresses to the corresponding new
segment address based upon the current motion of the file system. This function will only
return meaningful values when called from within ahook routine which was invoked through
INT 45h.

Error Codes
In general, HH O/S indicates the success or failure of an operation by returning astatus code
in AX. On return from the function call, the carry flag will be clear if no error occurred and the
operation succeeded. If the carry flag is set, then the operation failed, and the status code in
AX gives the reason for the failure. The list below gives the general meaning of each of the
defined status codes. If any other error code is received, it should be treated as ageneral
error indication.
The following error codes are returned by HH O/S functions calls:
1Un-implemented function
2File not found
4Too many open files
5File access denied
6Invalid file handle
8Out of memory
9Invalid memory block
11 Bad file format
12 Invalid access request
18 No more files
20 File too big
21 Internal file system error
22 Bad file name
23 Exec failure
24 General I/O error
25 Bad application header
26 File checksum error
27 Device not found
28 Invalid time
29 Invalid date
In addition to those listed above, the following error codes can be returned by the data base
functions:
40h Record already opened
41 hNo opened record
42h Record not found
43h Field not found
44h Too many fields
45h No fields defined
46h Uninitialized data
47h Bad field data size
48h Field already exists
49h Bad sort key specified
4Ah Query buffer overflow error
4Bh Bad field type specified
4Ch Too many records
4Dh Record too big
4Eh Invalid Query buffer
10

HH 0/S Function Calls
The following is alist, in numeric order, of all function calls supported by HH 0/S. The function
code numbers are given in hexadecimal. Function calls 00 -57 are similar to the same
numbered functions in MS-DOS. Although similar in nature, these functions are not necessarily
identical to the MS-DOS functions. Function calls numbered higher than 57 are not equivalent
to any MS-DOS functions and perform operations unique to the HH O/S environment.
Page
01 -Read Keyboard with Echo 13
02 -Display Character on Console 14
08 -Read Keyboard without Echo 15
09 -Display Character String 16
0B -Check Keyboard Status 17
0C -Flush Keyboard Buffer and Read Keyboard 18
25 -Set Interrupt Vector 19
29 -Parse File Name 20
2A -Get Date 21
2B -Set Date 22
2C -Get Time 23
2D -Set Time •24
2E -Set Disk Verify After Write Flag 25
35 -Get Interrupt Vector 26
36 -Get Disk Free Space 27
3C -Create File 28
3D -Open File 29
3E -Close File 30
3F -Read From File 31
40 -Write to File 32
41 -Delete File 33
42 -Position File Pointer 34
43 -Get/Set File Attributes 35
44 -I/O Control for Device 36
48 -Allocate Memory Block 38
49 -Release Memory Block 39
4B -Execute Program 40
4C -Terminate aProcess 42
4D -Get Process Termination Status 43
4E -Find First Matching File 44
4F -Find Next Matching File 46
54 -Get Disk Verify Flag Setting 47
56 -Rename File 48
57 -Get/Set Date/Time of File 49
DO -Expand File 50
D1 -Reduce File 52
D2 -Return Absolute File Pointer 53
D3 -Return File Size 55
D4 -Return Free Memory Size 56
D5 -Get File Mark 57
D6 -Sound Error Tone 58
11

D7 -Set Error Tone 59
D8 -Get Program File Handle 60
D9 -Get Workspace File Handle 61
DA -Get i'th File Directory Entry
DB -Get Address of Free Memory 62
DC -Init Math Pack Data Area 63
DD -Set Timer Channel 64
DE -Set Alarm Data/Time 65
DF -Get Current Alarm Setting 66
E0 -Get/Set Event Flag 67
E1 -Set File Size Limit 69
E2 -Set Function Key Definition 70
E3 -Reopen File 71
E4 -Memory Management for Device Driver Installer 72
E5 -Touch Panel Support 73
E6 -Lock File Open 74
E7 -Get/Set Alarm Program Definition 75
12

FUNCTION 01 h-Read Keyboard and Echo
AX
BX
CX
DX
SP:
BP:
SI:
Dl:
IP:
FLG
CS
DS
SS
ES
XXXXXXXX xxxxxxxx Entry: AH =01 h (function code)
Exit AX =Character Typed
Function 01 hwaits for acharacter to be typed at the keyboard, then echos the character to
the display and returns it in AX.
13

FUNCTION 02h Display Characters on Console
AX
BX
CX
DX
SP:
BP:
SI:
Dl:
IP:
FLG
CS
DS
SS
ES
XXXXXXXX
XXXXXXXX
Entry: AH =02h (function code)
DL =Character to be displayed
Exit: None
Function 02h displays the character in DL on the LCD display
14

FUNCTION 08h -Read Keyboard Without Echo
AX
BX
CX
DX
SP:
BP:
SI:
Dl:
IP:
FLG
CS
DS
SS
ES
XXXXXXXX XXXXXXXX Entry: AH =08h (function code)
Exit: AX =Character from keyboard
Function 08h waits for acharacter to be typed on the keyboard, and then returns it in AX. The
typed character is not echoed to the LCD display.
15