Documentation of the *commands and SWIs of ddUtil version 0.44 © Digital Developments by Birger Harzenetter
This Module is FreeWare. You are allowed to use and copy it free of charge as long as you don't ask for money. You can include it in your own applications provided you spread it for free too and leave a short copyright notice in your documentation. You do not need to include this file, however if you don't please point out that the documentation is available from here.
Thanks are due to the contributors to the comp.sys.acorn.programming newsgroup especially for the superb soulutions included as ddu_Div and ddu_Sqrt.
Do XDo |
HG_On HG_Off |
StartUnit StopUnit |
Files Find |
UUEncode Mode |
WIMP related | Date/Time | File I/O, Byte-sex | Strings | Misc | |||||||||||||||||
---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|
SIS SetIconState SIC SetIconColour SIT SetIconText GIT GetIconText GIV GetIconValue GIS GetIconState GIN GetIconNumber OpenWind OpenWindCentered SetTitle SetCaret |
RealTime ConvTime ConvUTCTime AddTime SubTime TimeToUnix TimeFromUnix |
ReadLine BGet437 BPut437 WGetL WGetB WPutL WPutB SwapSex |
ToLower ToUpper ReadLine |
ReadOSVar CRC16 CRC32 Sqrt Div |
Do | Executes a given string after GSTransing it. |
---|---|
Syntax: | *Do <anything> |
Usefull to pass special characters or to expand variables, or even execute a variables content. | |
^ Overview | |
XDo | Executes a given string after GSTransing it and without returning errors. |
Syntax: | *XDo <anything> |
Usefull to pass special characters or to expand variables, or even execute a variables content. Errors during execution of the command are displayed but not flagged to the caller. So that e.g. an obey file will not be aborted then. | |
^ Overview | |
StartUnit | enables a SCSI device for further operation [and prevent the medium being from being removed] |
Syntax: | *StartUnit [-]<SCSI-Id> |
Sends a Start Unit and optionally a Lock Medium command to the given SCSI device. | |
^ Overview | |
StoptUnit | disables a SCSI device from further operation [and ejects the medium] |
Syntax: | *StopUnit [-]<SCSI-Id> |
Sends a Stop Unit and optionally a Unlock Medium command with the eject bit set to the given SCSI device. | |
^ Overview | |
HG_On | Switches on the hourglass |
Syntax: | *HG_On |
^ Overview | |
HG_Off | Switches off the hourglass |
Syntax: | *HG_Of |
^ Overview | |
Files | Files lists all currently used file handles and their status |
Syntax: | *Files |
The status is shown by the following letters, where a capital means the flag is active for that file:r object is open for reading w object is open for writing m object has been modified e EOF reached l data lost | |
^ Overview | |
Find | Find lists all objects matching the given name in the given path |
Syntax: | *Find <path> <pattern> |
^ Overview | |
UUEncode | UUEncode encodes a binary file into 7-Bit printable ASCII characters |
Syntax: | *UUEncode <binary file> <text file> |
^ Overview | |
Mode | Mode changes the display to the given resolution and colour depth |
Syntax: | Syntax: *Mode <HRes> <VRes> <ln2bpp> |
Where ln2bpp=0 for 2 colours, 1 for 4, 2 for 16, 3 for 256, 4 for 65536 and 5 for 16M colours. 256 colour modes are always with full palette. | |
^ Overview | |
Only existant for compatibility issues. DO NOT USE This call is identical to ddu_ToUpper, but might be removed in a future release. Use ddu_ToUpper ONLY in new software! | |
(SWI &506CE) | |
re-entrant | |
^ Overview | |
ddu_ToLower | Convert a string to lower-case letters |
(SWI &506CF) | |
re-entrant | |
on entry: | R0=Pointer to string, control terminated |
on exit: | All registers preserved |
BASIC example: |
SYS "ddu_ToLower","MixED cASe" TO Low$ |
^ Overview | |
ddu_ToUpper | Convert a string to upper-case letters |
(SWI &506CE) | |
re-entrant | |
on entry: | R0=Pointer to string, control terminated |
on exit: | All registers preserved |
BASIC example: |
SYS "ddu_ToUpper","MixED cASe" TO Up$ |
^ Overview | |
ddu_ReadOSVar | Gives the contents of an OSVariable |
(SWI &506C1) | |
not re-entrant | |
on entry: | R0=Pointer to variable name |
on exit: | R0=Pointer to contents, CR terminated |
BASIC example: |
SYS "ddu_ReadOSVar","Sys$Time" TO Var$ |
^ Overview | |
ddu_RealTime | Gives the current 5-byte realtime as a 10-digit hexadecimal number. |
(SWI &506C2) | |
not re-entrant | |
on entry: | - |
on exit: |
R0=Pointer to string holding the current realtine as a 10-digit hexadecimal number
see ddu_ConvTime for an example |
^ Overview | |
ddu_ConvTime | Converts a given 5-byte realtime to a string, using Territory_ConvertDateAndTime and the configured settings for timezone and dst offsets. |
(SWI &506C3) | |
not re-entrant | |
on entry: |
R0=Pointer to 10-digit hexadecimal string giving
the time to be converted. The string need not to be terminated, but will be corrupted! If R0=0 the current realtime is used R1=Pointer to format string, control terminated |
on exit: | R0=Pointer to resulting string, CR terminated |
BASIC example: |
SYS "ddu_RealTime" TO RT$ SYS "ddu_ConvTime",RT$,"%24:%mi" TO T$is equal to SYS "ddu_ConvTime",,"%24:%mi" TO T$(see 'Format field names' (PRM 1-402) for details of the format string) |
^ Overview | |
ddu_ConvUTCTime | Converts a given 5-byte realtime to a string, using Territory_ConvertDateAndTime and no timezone or dst offsets. |
(SWI &506C6) | |
not re-entrant | |
See ddu_ConvTime for documentation | |
^ Overview | |
ddu_AddTime | Adds two 5-byte values |
(SWI &506C7) | |
not re-entrant | |
on entry: |
R0=Pointer to 10-digit hexadecimal string
R1=Pointer to 10-digit hexadecimal string Note: Boths strings must be exactly 10 digits long but need not to be terminated. |
on exit: | R0=Pointer to 10-digit hexadecimal string containing the result |
^ Overview | |
ddu_SubTime | Subtracts two 5-byte values |
(SWI &506C8) | |
not re-entrant | |
See ddu_AddTime for documentation | |
^ Overview | |
ddu_TimeToUnix | Converts a given 5-byte time to a 32-bit unix timestamp |
(SWI &506C9) | |
not re-entrant | |
on entry: |
R0=Pointer to 10-digit hexadecimal string
If R0=0 the current realtime is used Note: The string must be exactly 10 digits long but need not to be terminated. |
on exit: | R0=Unix timestamp |
^ Overview | |
ddu_TimeFromUnix | Converts a 32-bit unix timestamp to a timestring |
(SWI &506CA) | |
not re-entrant | |
on entry: | R0=Unix timestamp |
on exit: | R0=Pointer to 10-digit hexadecimal string containing result |
^ Overview | |
ddu_Sqrt | Calculates the sqare root |
(SWI &506CC) | |
re-entrant | |
on entry: | R0=integer |
on exit: |
R0=integer result
the C flag holds the first after comma digit use adc r0,r0,#1 to round result
|
^ Overview | |
ddu_Div | Signed Division with variable fraction result |
(SWI &506CD) | |
re-entrant | |
on entry: |
R0=Divident
R1=Divisor R2=fraction, number of bits. if R2>32 the result will be integer |
on exit: | R0=Result of division |
^ Overview | |
ddu_CRC16 | Calcuates 16-Bit CRCs compatible with the X/Y/Z-Modem polynominal (&8408) |
(SWI &506C4) | |
re-entrant | |
on entry: |
R0=Old (or start) CRC value
If R1<256 or R2=0 R1=Byte to add If R1>=&8000 and R2>0 R1=Start address of buffer in memory R2=Length of buffer |
on exit: | R0=New CRC value |
BASIC example: |
CRC=-1 FOR A=0 TO 1023 SYS "ddu_CRC16",CRC,Buffer?A TO CRC NEXT Ais equal to SYS "ddu_CRC16",-1,Buffer,1024 TO CRCNote: ddUtil versions <0.31a checked for R1>&8000 instead of R1>=&8000! |
^ Overview | |
ddu_CRC32 | Calcuates 32-Bit CRCs compatible with the Z-Modem polynominal (ANSI X3.66; &EDB88320) |
(SWI &506C5) | |
re-entrant | |
See ddu_CRC16 for documentation | |
^ Overview | |
ddu_BGet437 | Reads a character from an open file converting it from IBM codepage 437 encoding to ISO 8859-1 (Latin1) encoding. Note: exact conversion is not possible for all characters. |
(SWI &506D8) | |
not re-entrant | |
on entry: | R0=File handle |
on exit: |
R0 preserved
R1=character read |
^ Overview | |
ddu_BPut437 | Writes a character to an open file converting it from ISO 8859-1 (Latin1) encoding to IBM codepage 437 encoding. Note: exact conversion is not possible for all characters. |
(SWI &506D9) | |
not re-entrant | |
on entry: |
R0=File handle
R0=character to write |
on exit: | All registers preserved |
^ Overview | |
ddu_WGetL | Reads an 32-Bit word in little endian notation from an open file. |
(SWI &506D0) | |
not re-entrant | |
on entry: | R0=File handle |
on exit: |
R0 preserved
R1=Word read |
^ Overview | |
ddu_WGetB | Reads an 32-Bit word in big endian notation from an open file. |
(SWI &506D1) | |
not re-entrant | |
on entry: | R0=File handle |
on exit: |
R0 preserved
R1=Word read |
^ Overview | |
ddu_WPutL | Writes an 32-Bit word in little endian notation to an open file. |
(SWI &506D2) | |
not re-entrant | |
on entry: |
R0=File handle
R1=Word to write |
on exit: | All registers preserved |
^ Overview | |
ddu_WPutB | Writes an 32-Bit word in big endian notation to an open file. |
(SWI &506D3) | |
not re-entrant | |
on entry: |
R0=File handle
R1=Word to write |
on exit: | All registers preserved |
^ Overview | |
ddu_SwapSex | Swaps the byte-sex of an 32-bit word from little endian to big endian notation or vice versa. |
(SWI &506D4) | |
re-entrant | |
on entry: | R0=Word to swap |
on exit: | R0=Word swapped |
^ Overview | |
ddu_ReadLine |
Reads a CR or LF terminated line out of a file and places
it into a block of memory. The string in memory is always CR terminated. If the line won't fit into the buffer the rest is discarded. If no buffer is given an internal buffer is used and the length of the string is set to 254 characters. |
(SWI &506D5) | |
not re-entrant | |
on entry: |
R0=file handle to read from
R1=pointer to buffer R2=Size of buffer Note: R2 on exit contains the number of bytes read including any bytes that did not fit into the buffer and have been discarded. |
on exit: | R2=Number of bytes read |
BASIC example: |
SYS "ddu_ReadLine",File,Blk,255 TO ,,Len |
^ Overview | |
ddu_SIS | Set an icons state |
(SWI &506E0) | |
not re-entrant | |
on entry: |
R0=Window handle
R1=Icon handle R2=0 make icon shaded R2=1 make icon normal R2=2 make icon selected R2=3 make icon selected and shaded |
on exit: | All registers preserved |
BASIC example: |
SYS "ddu_SIS",Window,Icon,2 |
^ Overview | |
ddu_SIC | Set an icons colour |
(SWI &506E1) | |
not re-entrant | |
on entry: |
R0=Window handle
R1=Icon handle R2=Foreground colour R3=Background colour If R3=0..15 the icon gets a filled background If R3=-1 the icon background gets transparent |
on exit: | All registers preserved |
BASIC example: |
SYS "ddu_SIS",Window,Icon,7,11 |
^ Overview | |
ddu_SIT | Set an inderected icons text. This call also clears the selected and shaded bits. |
(SWI &506E2) | |
not re-entrant | |
on entry: |
R0=Window handle
R1=Icon handle R2=Pointer to string or value If R2>=&8000 the Sting at this address is copied into the icon If R2<&8000 it is converted to a decimal number string first |
on exit: | All registers preserved |
BASIC example: |
SYS "ddu_SIS",Window,Icon,"25"is equal to SYS "ddu_SIS",Window,Icon,25 |
^ Overview | |
ddu_GIT | Get an inderected icons text. |
(SWI &506E3) | |
not re-entrant | |
on entry: |
R0=Window handle
R1=Icon handle |
on exit: | R0=Pointer to text, CR terminated |
BASIC example: |
SYS "ddu_SIS",Window,Icon TO Text$ |
^ Overview | |
ddu_GIV | Get the numerical value of an inderected icons text. |
(SWI &506E7) | |
not re-entrant | |
on entry: |
R0=Window handle
R1=Icon handle R2=Base if >=2 AND <=36, otherwise ignored |
on exit: | R0=Value |
BASIC example: |
SYS "ddu_GIV",Window,Icon TO Value SYS "ddu_GIV",Window,Icon,16 TO Value(see OS_ReadUnsigned (PRM 1-448) for a description of R2, possible errors and on how the value is treated) Note: ddUtil versions <0.37 returned an error if the icon was empty; now it returns 0. |
^ Overview | |
ddu_GIS | Get an icons state. |
(SWI &506E8) | |
not re-entrant | |
on entry: |
R0=Window handle
R1=Icon handle |
on exit: |
R0=1 If icon is selected, =0 otherwise
R1=Pointer to icon block |
BASIC example: |
SYS "ddu_GIS",Window,Icon TO State |
^ Overview | |
ddu_GIN | Get the number of the first icon in an ESG that is selected. |
(SWI &506E9) | |
not re-entrant | |
on entry: |
R0=Window handle
R1=ESG |
on exit: | R0=Icon number or -1 if none selected |
BASIC example: |
SYS "ddu_GIN",Window,ESG TO Icon |
^ Overview | |
ddu_OpenWind | Open a window on top of the pile |
(SWI &506E4) | |
not re-entrant | |
on entry: | R0=Window handle |
on exit: | All registers preserved |
BASIC example: |
SYS "ddu_OpenWind",Window |
^ Overview | |
ddu_OpenWindCentered | Open a window on top of the pile with the work area centered to the screen |
(SWI &506EA) | |
not re-entrant | |
on entry: | R0=Window handle |
on exit: | All registers preserved |
BASIC example: |
SYS "ddu_OpenWindCentered",Window |
^ Overview | |
ddu_SetTitle | Set a windows title bar text |
(SWI &506E5) | |
not re-entrant | |
on entry: |
R0=Window handle
R1=Pointer to text |
on exit: | R0-R5 corrupted |
BASIC example: |
SYS "ddu_SetTitle",Window,"New title" |
^ Overview | |
ddu_SetCaret | Set the caret to the given icon at a specified position into the displayed string. |
(SWI &506E6) | |
not re-entrant | |
on entry: |
R0=Window handle
R1=Icon handle R2=Number of Characters into the string to position the caret at. |
on exit: |
R2=Number of Characters into the string the
caret was set at.
If R2 on entry is larger than the number of characters the icon contains at the moment the call is made, it will be adjusted to be to the right of the last character in the icon. You can use this feature to position the caret at the end of the icons contents by giving a non-sensible value in R2 on entry, like -1. |
BASIC example: |
SYS "ddu_SetCaret",Window,Icon,-1 |
^ Overview | |