<-- back

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.

*Commands

Do
XDo
HG_On
HG_Off
StartUnit
StopUnit
Files
Find
UUEncode
Mode

SWIs

WIMP related Date/Time FileI/O, Byte-sex Strings Misc
SISSetIconState
SICSetIconColour
SITSetIconText
GITGetIconText
GIVGetIconValue
GISGetIconState
GINGetIconNumber
OpenWind
OpenWindCentered
SetTitle
SetCaret
RealTime
ConvTime
ConvUTCTime
AddTime
SubTime
TimeToUnix
TimeFromUnix
ReadLine
BGet437
BPut437
WGetL
WGetB
WPutL
WPutB
SwapSex
Upper
ToLower
ToUpper
ReadLine
ReadOSVar
CRC16
CRC32
Sqrt
Div



DoExecutes 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

XDoExecutes 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

StartUnitenables 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

StoptUnitdisables 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_OnSwitches on the hourglass
Syntax:
*HG_On
^ Overview

HG_OffSwitches off the hourglass
Syntax:
*HG_Of
^ Overview

FilesFiles 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

FindFind lists all objects matching the given name in the given path
Syntax:
*Find <path> <pattern>
^ Overview

UUEncodeUUEncode encodes a binary file into 7-Bit printable ASCII characters
Syntax:
*UUEncode <binary file> <text file>
^ Overview

ModeMode 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



ddu_Upper 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 A
is equal to
SYS "ddu_CRC16",-1,Buffer,1024 TO CRC
Note: 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


wimpy@yeti.dk