UTILS3a Developers' Handbook

Introduction
Utils3a is a program which is expandable by third parties.  The core program was written by Graham Tappenden at Psion GmbH between November 1993 and March 1994.  The proposal for this 'plug-in' option came from Bruno Neeser in CompuServe.

This document explains how to expand Utils3a with your own utilities.  This creates several advantages:

1.	You do not have to write a 'front-end' for your software.

2.	There are already a lot of people using the 'front-end' software, so they will not have
	to learn a completely new product.

3.	The 'front-end' is now known to be relatively 'bug-free', and any even if bugs are found
	they are not your problem.

How to get your software to interact with Utils3a

Your program should take the following form:

PROC Main:
	mINIT
	UtilMenu:
	MENU
ENDP

PROC UtilMenu:
	mCARD ...,...,...
	    ...
	mCARD ...,...,...
ENDP

PROC UtilSel:(k%,f$)
	IF k%=%p
		...
	ELSEIF
		...
	ENDIF
ENDP

Main is a dummy procedure, which allows us to place mCARDs in a sub-procedure.

UtilMenu is where you place the menu items which apply to your software.  These will be added to the Utils main menu.

UtilSel is where you decide upon the actions to take.  k% is the key pressed, and f$ is the filename selected.  See a later note about the choice of hotkeys.

You can then add your own procedures.  It is recommended that you do NOT duplicate any of the library procedures mentioned in this document, unless you specifically wish to alter the way they work.

Finally, you should translate the program, and move the .OPO file to \APP\UTILS3A on the same drive as UTILS3A.APP.  The file should also be given the extension .UTL.

Some basic rules to follow

1.	If you need to save any settings, save them in the \INI\ directory on the internal drive.
	Do NOT use the names UTILS3A.INI or ASSOC.INI.

2.	Start all temporary filenames with a tilde (~).

3.	Do NOT alter any of the variables which you may reference from the main program.  If
	you do, then it is at your own risk.

4.	Make your programs as multi-lingual as possible.  More about this later.

Selecting the Hotkeys

1.	You should select the hotkeys so as not to conflict with those already in use in the main
	program, since these will be given priority.  Different languages use different hotkeys.

2.	Try to stick to the conventions used in the System screen, eg. C for Copy.

Making your program Multi-lingual

Making a program fully multi-lingual is a complex process.  This has been made slightly easier here, since the main program does all of this for you.

You can reference an array r$ to call the translation of your word, and r% for the associated hotkey, eg. Instead of writing "File" in a program, write r$(2).  On a German 3a, this will then appear as "Datei".

Here is a list of the words you can access, along with their hotkeys in English and German.

001
<DIR>








002
File



003
Copy
c
k

004
Delete
d
l

005
Rename
r
u

006
Attribute
a
a

007
Make Directory
+
+

008
Remove Directory
-
-






009
Options



010
Sort
s
s






011
Utils



012
DBF Utils
f
f

013
Hex Editor
h
h






014
Extras



015
New Window
N
N

016
Move Window
M
V

017
Size Window
S
G

018
Close Window
L
S

019
Zoom +
z
z

020
Zoom -
Z
Z

021
Exit
x
x






022
No more windows



023
Busy








024
New Window



025
Path



026
File Attributes



027
Read Only



028
Modified



029
Hidden



030
System








031
No
n
n

032
Yes
y
j








033
Not available



034
Copy File



035
From



036
To



037
Copied



038
Delete File



039
Cancel



040
Confirm



041
Deleted



042
Rename File



043
Renamed








044
Select Sort



045
Order



046
None



047
Name



048
Extension



049
Size



050
Date



051
Sorting








052
Directory



053
Created



054
Removed








055
Insert Field
i
f

056
Sort File
s
s

057
Break at line



058
Entry



059
of



060
Sort on field



061
Ascending



062
Descending








063
HexEdit



064
Overlay not found



065
Move



066
Size



067
Open
o
o

068
Search



069
Address
a
a

070
String
s
k

071
Protection
p
t

072
Address
w
d

073
On



074
Off



075
Open File



076
Not found










077
Application



078
Associate
t
v

079
Command



080
Alias



081
Move
m
b

082
Tag
T
M

083
Refresh
R
K

084
Directory Tree
Y
Y

085
Cannot close this window



086
Reset



087
Move File



088
Tagged



089
Moved








090
File Search
H
U

091
Current Path



092
Current Drive



093
Local Drives



094
All Drives








095
Change Drive
y
y

096
Drive



097
found



098
Searching








099
Write Protected



100
Dynamic



101
Internal



102
Dual Density



103
Hard Disk



104
Floppy Disk



105
Disk Info
*
*

106
Size



107
Free



108
Total files



109
Modified files



110
Backed up



111
files




Library Procedures
You can call any of the following procedures, to save time in writing your code:

PROC getk%:		Returns the value of a key pressed

PROC Size&:(f$)	Returns the size of the specified file as a long integer
PROC Modst&:(f$)	Returns the date and time stamp of the file specified
PROC FileDir%:(f$)	Returns 0 if f$ is a file, and 1 if it is a directory
PROC DiskTtl%:(f$)	Returns 0 if f$ is a file, and 1 if it is a disk title, as found of
			remote PC drives
PROC Lang$:		Returns the language code for the machine being used
			eg. 01 for English, 03 for German

PROC NextWin:	Moves to the next window
PROC PrevWin:	Moves to the previous window

PROC Attrib:(f$)	Calls the attribute dialog
PROC AttGet%:(f$)	Returns the attributes of the file specified as an integer
PROC AttSet%:(f$,m%)
			Sets the attributes of the file specified

PROC Error:(err%)	Raises an error message
PROC SaveIni:	Saves the utils3a.ini file with the current settings

PROC RunProg:(app$,com$,f$,ext$,als$,opa$)
			Runs another program

PROC StatWin:(s%)	Sets the status window to a particular size, and re-positions the
			other windows accordingly

PROC DirList$:	Returns a list of the available directories in the other windows

PROC CopyFile:(f$)	Calls the copy dialog
PROC DelFile:(f$)	Deletes the file with confirmation
PROC RenFile:(f$)	Calls the rename dialog
PROC MoveFile:(f$)	Calls the move dialog

PROC MakeDir:	Calls the make directory dialog
PROC RemDir:	Calls the remove directory dialog

PROC CopyDir:(s$,d$)
			Copies a directory including sub-directories
PROC DelTree:(s$)	Does a recursive delete

PROC Assoc:(f$)	Calls the association dialog

PROC Refresh:	Refreshes all windows

PROC Windows%:	Returns the number of open windows

Advanced Functionality
There are several arrays which you can access to determine where you are in the system, each array has elements one to six, ie. one element per window.

WDir$		The currently selected directory
Wfont%	The currently selected font
Wsort%	The currently selected order to be sorted

A further variable, AppPfad$ (this is NOT an array) contains the location of the utils3a.app file, thus allowing the location of the program files to be determined.

Two further arrays contain pointers to the data in each window.

Wptr%		this is the pointer to the top of the file list
Wcurr%	this is the pointer to the currently selected file

At the address pointed to, is the following structure:

		The length of the filename	(one byte)
		The filename			(variable)
		A pointer to the previous file	(two bytes)
		A pointer to the next file	(two bytes)
		The file tag			(one byte)

If you wish to re-draw a window, call ShowDir:(win%), where win% is the number of the window (ie. 1 to 6).  To re-scan a window, call ScanDir:(win%).

To clear all the file tags call MarkNone:(win%).

To switch to a particular window, call UseWin:(win%).

The variable curr% contains the number of the current window.

The following extra function are availble by first loading EXTRA21.OVL:

PROC devlist$:	Returns a list of the currently available devices


NOTE: You should never really have to change any of the data held in these structures, since there is usually a procedure already defined to do this for you.

Nor the author, nor Psion GmbH are responsible for any loss or damage caused as a use of this program, nor as a result of any loss or damage which may occure by use of this information by third parties.
Utils3a Developers' Handbook

{SEITE|7}


