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.
