PSIONICS FILE - SYSCALLS.3 ========================== System calls (part 3) Last modified 1998-07-22 ======================== See part 1 for general notes and explanations. Fn $8D is used for the Window Server, and is described in the Psionics file WSERVER. Fn $8E Sub $00 to $10 control various parts of the hardware, and should not be used by OPL programs. Fn $8E Sub $11 HwGetSupplyStatus BX: 6 byte buffer Gets information about the power supply. The buffer is filled with the following data: Offset 0 (word): main battery voltage in mV Offset 2 (word): backup battery voltage in mV Offset 4 (word): positive if external power is available, zero if not available, and negative if the detector is disabled because an SSD door is open. The returned voltages should be taken with a grain of salt: I have observed the following values: 1800: no main batteries 1800: low main batteries 2056: new main batteries 2300: no lithium battery 2556: lithium battery fitted Fn $8E Sub $12 HwLcdContrastDelta AL: step direction Alters the LCD contrast by one step, upwards if AL is between 0 and 127, and downwards if it is between 128 and 255 (all inclusive). Fn $8E Sub $13 HwReadLcdContrast AL: -> setting Gets the current LCD contrast setting. On a Series 3, only the bottom 4 bits are significant. Fn $8E Sub $14 HwSwitchOff CX: delay in quarter seconds Switches the machine off for the specified time, then back on again ($FFFF means never turn back on). The machine will also be turned on by external events, alarms, and timers. The delay must be at least 9 (2.25 seconds). Fn $8E Sub $15 should only be used by device drivers. Fn $8E Sub $16 HwExit Exits the emulation on PC systems; has no effect on actual Psion machines. Fn $8E Sub $17 to $1A should only be used by device drivers. Fn $8E Sub $1B HwGetPsuType AL: -> PSU type Gets the PSU type: 0 = old MC, 1 = MC "Maxim", 2 = Series 3t, 3 = Series 3a Fn $8E Sub $1C HwSupplyWarnings BX: 8 byte buffer Gets information about the power supply. The buffer is filled with the following data: Offset 0 (word): main battery good voltage threshold in mV Offset 2 (word): backup battery good voltage threshold in mV Offset 4 (word): main battery nominal maximum voltage in mV Offset 6 (word): backup battery nominal maximum voltage in mV The values will depend on the battery type set by GenSetBatteryType. Fn $8E Sub $1D HwForceSupplyReading @No documentation available at present@ Fn $8E Sub $1E HwGetBackLight AX: -> current value On systems fitted with a backlight, this value indicates control of the backlight function. If the top bit is set, the operating system will ignore the backlight toggle key. The remaining bits give the auto-light-off time in ticks (1/32 second); zero means that auto-light-off is disabled. Fn $8E Sub $1F HwSetBackLight BX: new value Sets the backlight control value (see HwGetBackLight). Fn $8E Sub $20 HwBackLight fails AL: action -> status before call This call fails if no backlight is fitted. Otherwise, the actions are: 0 = switch backlight off 1 = switch backlight on 2 = toggle backlight 3 = no action The status returned is that of the backlight before the call: 0 = off, 1 = on. Fn $8E Sub $21 controls various parts of the hardware, and should not be used by OPL programs. Fn $8E Sub $22 HwSupplyInfo v3 BX: 22 byte buffer Fills the buffer with additional information about the power supply: Offset 0 (byte): main battery status: 0 = not present 1 = very low voltage 2 = low voltage 3 = good voltage Offset 1 (byte): worst main battery status since batteries last inserted Offset 2 (byte): non-zero if backup battery voltage is good Offset 3 (byte): non-zero if external supply is present Offset 4 (word): warning flags Bit 0: set if power supply too low for sound Bit 1: set if power supply too low to use flash Bit 2: set if offset 6 changed because system clock changed clear if offset 6 changed because the batteries were changed Offset 6 (long): abstime when batteries inserted Offset 10 (long): ticks running on battery Offset 14 (long): ticks running on external supply Offset 18 (long): mA-ticks (i.e. mAhours * 60 * 60 * 32) Fn $8E Sub $28 HwGetScanCodes v3 BX: 20 byte buffer The buffer is filled with information describing the state of each key on the keyboard. For the Series 3a, the offset and bit for each key are given in the following table ("2:4" means offset 2, bit 4). System 9:1 Esc 15:0 Delete 4:0 1 14:1 A 12:2 N 0:6 Data 7:1 Tab 0:2 Enter 0:0 2 14:2 B 8:6 O 4:5 Word 11:1 Control 4:7 ShiftR 6:7 3 10:6 C 10:3 P 2:5 Agenda 3:1 ShiftL 2:7 Up 14:5 4 8:2 D 10:4 Q 12:1 Time 1:1 Psion 0:7 Left 0:4 5 8:3 E 10:5 R 8:1 World 5:1 Menu 10:7 Down 0:5 6 14:3 F 10:1 S 12:4 Calc 3:0 Diamond 8:7 Right 0:1 7 6:6 G 8:5 T 8:4 Sheet 1:0 Space 8:0 Help 6:2 8 4:3 H 14:6 U 6:5 + and = 2:3 - and _ 2:2 9 4:4 I 4:2 V 10:2 * and : 2:6 / and ; 2:1 0 2:4 J 6:4 W 12:5 , and < 6:1 . and > 14:4 K 4:1 X 12:6 L 4:6 Y 0:3 M 6:3 Z 12:3 Fn $8E Sub $29 HwGetSsdData Nothing is known about this call except its name. @@@@@@ Fn $8E Sub $2A HwResetBatteryStatus v3.9 The battery status is reset, exactly as if the main batteries had been removed and then replaced. Fn $8E Sub $2B HwEnableAutoBatReset v3.9 AX: -> (if querying) 1 = enabled, 0 = disabled BX: 1 = enable, 0 = disable, -1 = query Enables, disables, or queries the current setting of the automatic reset of the battery status. This is intended for use on the Workabout, where the batteries can be recharged in situ. Fn $8E Sub $2C HwGetBatData v3.9 AX: -> address of a data structure in kernel data space The data is described in the KERNEL file. Fn $8E Sub $2E HwReLogPacks v3.9 fails This has the same effect as opening and then closing the SSD doors. Fn $8E Sub $2F HwSetIRPowerLevel v3.9 AX: -> previous level (0 = low, 1 = high) BX: new level (0 = low, 1 = high) Sets the IR power level, returning the previous level. Fn $8E Sub $30 HwReturnTickCount v3.9 AX: tick count Returns a tick count that is incremented 32 times per second. Fn $8E Sub $31 HwReturnExpansionPortState v3.9 AX: -> port type and state BX: -> zero Returns the type and state of the expansion port: Bits 0 to 7: non-zero if SSD doors are open, or something has just been plugged into or removed from the Honda expansion connector Bits 8 to 14: connector type: 0 = Series 3t/3a, 1 = Workabout LIF, 2 = Siena Honda, 3 = Series 3c Honda, 4 = HC Bit 15: 1 = contains Condor chip, 0 = no Condor chip Fn $8F GenDataSegment This call is only useful in assembler code; it sets ES to point to the start of the kernel data space (accessible in OPL using GenGetOsData). Fn $90 ProcPanic AL: reason Panic the current process; this call never returns. Fn $91 ProcCopyFromById fails BX: process ID CX: number of bytes to copy SI: remote address of first byte to copy eDI: local address of first byte to copy Copy a number of bytes from the indicated process to the current process. Fn $92 ProcCopyToById fails BX: process ID CX: number of bytes to copy SI: local address of first byte to copy DI: remote address of first byte to copy Copies a number of bytes from the current process to the indicated process. Fn $93 CharIsDigit Fn $94 CharIsHexDigit Fn $95 CharIsPrintable Fn $96 CharIsAlphabetic Fn $97 CharIsAlphaNumeric Fn $98 CharIsUpperCase Fn $99 CharIsLowerCase Fn $9A CharIsSpace Fn $9B CharIsPunctuation Fn $9C CharIsGraphic Fn $9D CharIsControl AL: character to test EQ: -> set if test fails, clear if test succeeds Tests to see whether the character has the indicated property. These functions are language dependent. Fn $9E CharToUpperChar Fn $9F CharToLowerChar Fn $A0 CharToFoldedChar AL: character 1 -> converted character 1 AH: character 2 -> converted character 2 Converts two characters to uppercase, lowercase, or folded (uppercase with no accents). These functions are language dependent. Fn $A1 BufferCopy CX: length to be copied SI: address of "from" buffer eDI: address of "to" buffer Copies a number of bytes from one buffer to another. The case of the buffers overlapping is handled correctly. Fn $A2 BufferSwap CX: length to be swapped SI: address of buffer 1 eDI: address of buffer 2 Swaps the contents of two buffers. The case of the buffers overlapping is handled correctly. Fn $A3 BufferCompare Fn $A4 BufferCompareFolded BX: length of buffer 2 CX: length of buffer 1 SI: address of buffer 1 eDI: address of buffer 2 UL: -> set if buffer 1 less than buffer 2 EQ: -> set if buffers are identical The contents of the two buffers are compared byte-for-byte, using unsigned comparisons, and the result flags set accordingly. BufferCompareFolded acts as if each character had been passed to CharToFoldedChar before comparison. Fn $A5 BufferMatch fails Fn $A6 BufferMatchFolded fails CX: length of buffer DX: length of pattern SI: address of buffer eDI: address of pattern The buffer is examined to determine whether it matches the pattern (using the usual wildcards); the call fails if it does not. BufferMatchFolded acts as if each character had been passed to CharToFoldedChar before comparison. Fn $A7 BufferLocate fails Fn $A8 BufferLocateFolded fails AH: character -> [undefined] AX: -> offset of character CX: length of buffer SI: address of buffer The buffer is searched to determine if the character occurs within it; the call fails if it does not. If it does, the offset from the start of the buffer of the first occurence is returned. BufferLocateFolded acts as if each character had been passed to CharToFoldedChar before comparison. Fn $A9 BufferSubBuffer fails Fn $AA BufferSubBufferFolded fails AX: -> offset BX: length of buffer 2 CX: length of buffer 1 SI: address of buffer 1 eDI: address of buffer 2 Buffer 1 is searched to determine if buffer 2 occurs within it; the call fails if it does not. If it does, the offset from the start of buffer 1 of the first occurence of buffer 2 is returned. BufferSubBufferFolded acts as if each character had been passed to CharToFoldedChar before comparison. Fn $AB BufferJustify AX: -> address of first uncopied character BX: length of buffer 2 CX: length of buffer 1 DX: fill character * 256 + control code SI: address of buffer 1 eDI: address of buffer 2 Buffer 1 is copied into buffer 2, and the remaining space filled with the fill character according to the control code (0 = fill at end, 1 = fill at start, 2 = centre the copied data). If buffer 1 is longer than buffer 2, then the contents will be truncated to fit. If the length of buffer 2 is negative, then it is assumed to be the same as that of buffer 1 (and the data is just copied). Fn $AC StringCopy Fn $AD StringCopyFolded SI: cstr eDI: large enough buffer The cstr is copied into the buffer. StringCopyFolded passes each character through CharToFoldedChar during the copy. Fn $AE StringConvertToFolded SI: cstr Each character of the cstr is passed through CharToFoldedChar. Fn $AF StringCompare Fn $B0 StringCompareFolded SI: cstr 1 eDI: cstr 2 UL: -> set if cstr 1 less than cstr 2 EQ: -> set if cstrs are identical The contents of the two cstrs are compared byte-for-byte, using unsigned comparisons, and the result flags set accordingly. StringCompareFolded acts as if each character had been passed to CharToFoldedChar before comparison. Fn $B1 StringMatch fails Fn $B2 StringMatchFolded fails SI: cstr to be searched eDI: pattern (cstr) The cstr is searched to determine if the pattern occurs within it (using the usual wildcards); the call fails if it does not. StringMatchFolded acts as if each character had been passed to CharToFoldedChar before comparison. Fn $B3 StringLocate fails Fn $B4 StringLocateFolded fails Fn $B5 StringLocateInReverse fails Fn $B6 StringLocateInReverseFolded fails AH: character -> [undefined] AX: -> offset of character SI: cstr The cstr is searched to determine if the character occurs within it; the call fails if it does not. If it does, the offset from the start of the cstr of the first (for StringLocate and StringLocateFolded) or last (for the two Reverse calls) occurence is returned. The two Folded calls act as if each character had been passed to CharToFoldedChar before comparison. Fn $B7 StringSubString fails Fn $B8 StringSubStringFolded fails AX: -> offset SI: cstr 1 eDI: cstr 2 Cstr 1 is searched to determine if cstr 2 occurs within it; the call fails if it does not. If it does, the offset from the start of cstr 1 of the first occurence of cstr 2 is returned. StringSubStringFolded acts as if each character had been passed to CharToFoldedChar before comparison. Fn $B9 StringLength AX: -> length of the cstr eDI: cstr Returns the length of a cstr, excluding the terminating zero byte. Fn $BA StringValidateName fails AL: maximum number of characters permitted AH: non-zero if an extension is permitted eDI: cstr The cstr is checked to see if it a valid name, and the call fails if it is not. A name is valid if it: * begins with a letter; * contains only letters, digits, dollar signs ($), underscores (_), and at most one dot; * if AH is zero, does not contain a dot; * contains no more than the specified number of characters before the dot (if any); and * contains no more than 4 characters after the dot, if any. @The manual says 3 characters, but my tests accept 4.@ Fn $BB LongIntCompare AX: high half of P BX: low half of P CX: high half of Q DX: low half of Q SL: -> set if P less than Q EQ: -> set if P equals Q Compares P and Q (both signed longs) and sets the result flags accordingly. Fn $BC LongIntMultiply fails AX: high half of P -> high half of product BX: low half of P -> low half of product CX: high half of Q DX: low half of Q Multiples P and Q (both signed longs); the call fails if the result cannot be represented as a signed long. Fn $BD LongIntDivide fails AX: high half of P -> high half of quotient BX: low half of P -> low half of quotient CX: high half of Q -> high half of remainder DX: low half of Q -> low half of remainder Divides P by Q (both signed longs); the call fails if Q is zero. The remainder will have the same sign as P. Fn $BE LongUnsignedIntCompare AX: high half of P BX: low half of P CX: high half of Q DX: low half of Q UL: -> set if P less than Q EQ: -> set if P equals Q Compares P and Q (both unsigned longs) and sets the result flags accordingly. Fn $BF LongUnsignedIntMultiply fails AX: high half of P -> high half of product BX: low half of P -> low half of product CX: high half of Q DX: low half of Q Multiples P and Q (both unsigned longs); the call fails if the result cannot be represented as a unsigned long. Fn $C0 LongUnsignedIntDivide fails AX: high half of P -> high half of quotient BX: low half of P -> low half of quotient CX: high half of Q -> high half of remainder DX: low half of Q -> low half of remainder Divides P by Q (both unsigned longs); the call fails if Q is zero. Fn $C1 FloatAdd fails Fn $C2 FloatSubtract fails Fn $C3 FloatMultiply fails Fn $C4 FloatDivide fails SI: address of Q DI: address of P Calculates the specified one of P+Q, P-Q, P*Q, or P/Q, and places the result in P. Both P and Q are reals. Fn $C5 FloatCompare SI: address of Q DI: address of P SL: -> set if P is less than Q EQ: -> set if P equals Q Compares two reals and sets the result flags appropriately. Fn $C6 FloatNegate DI: address of P Negates a real in-situ. Fn $C7 FloatToInt fails Fn $C8 FloatToUnsignedInt fails AX: -> result SI: address of real Converts a real to a signed or unsigned int; the call fails if the result is out of range. FloatToUnsignedInt ignores the sign of the real. Fn $C9 FloatToLong fails Fn $CA FloatToUnsignedLong fails AX: -> high half of result BX: -> low half of result SI: address of real Converts a real to a signed or unsigned long; the call fails if the result is out of range. FloatToUnsignedLong ignores the sign of the real. Fn $CB IntToFloat Fn $CC UnsignedIntToFloat AX: value DI: address of real Converts a signed or unsigned int to a real. Fn $CD LongToFloat Fn $CE UnsignedLongToFloat AX: high half of value BX: low half of value DI: address of real Converts a signed or unsigned long to a real. Fn $CF LibSend Fn $D0 LibSendSuper AX: -> method result BX: handle of object to receive the message CX: message number DX: argument 1 SI: argument 2 DI: argument 3 These functions send a message to an object and invoke a method on that object. LibSend starts searching for the method in the class of the object, and LibSendSuper in the superclass. Fn $D1 to $D3 can only be used from assembler. Fn $D4 Dummy This function has no effect. Fn $D5 GenIntByNumber AL: Fn -> error and result flags SI: argument block DI: result block This call is equivalent to the OS keyword; it calls another system call with the arguments and results stored in 12 byte blocks. Fn $D6 is used for the Window Server, and is described in the Psionics file WSERVER. Fn $D7 is normally only used by the C library. Fn $D8 is used for accessing DBF files. See the Psionics file DBF.FMT. Fn $D9 LibEnterSend AX: -> method result BX: handle of object to receive the message CX: message number DX: argument 1 SI: argument 2 DI: argument 3 This is identical to LibSend, except that it also starts a new "entry-exit region". The method description will state when this is needed. Fn $DA IoKeyAndMouseStatus @No documentation available at present@ Fn $DB StringCapitalise SI: cstr The first character of the cstr is passed through CharToUpperChar, and the remaining characters through CharToLowerChar. Fn $DC ProcIndStringCopyFromById fails BX: process ID CX: maximum length to copy SI: address of location holding address of cstr eDI: buffer This copies a cstr from the indicated process to the current process. The cstr is found via a pointer also in the memory of the indicated process, and the address of this pointer is specified. This call is equivalent to making two calls to ProcCopyFromById, the first to find the location of the cstr, and the second to fetch it, except that the contents of the buffer beyond the terminating zero are unspecified. Fn $DD is reserved for the window server. Fn $DE IoSerManager @No documentation available at present@