PSIONICS FILE - SYSCALLS.2 ========================== System calls (part 2) Last modified 1998-11-07 ======================== See part 1 for general notes and explanations. Fn $88 Sub $00 ProcId AX: -> process ID of the current process Gets the process ID of the current process. Fn $88 Sub $01 ProcIdByName fails AX: -> process ID eBX: (cstr) pattern Gets the process ID of a process whose name matches the pattern (usual wildcards apply, and case is ignored). Fn $88 Sub $02 ProcGetPriority fails AL: -> priority BX: process ID Gets the priority of the specified process. Fn $88 Sub $03 ProcSetPriority fails AL: new priority BX: process ID Sets the priority of the specified process. Fn $88 Sub $04 should only be called by the operating system. Fn $88 Sub $05 ProcCreateTask Tasks are processes which share the data segment of another process. They cannot be conveniently handled in OPL. Fn $88 Sub $06 ProcResume fails BX: process ID Take a process out of the suspended state and start it executing. Fn $88 Sub $07 ProcSuspend fails BX: process ID Place a process in the suspended state. If the process is waiting for a system service (e.g. a semaphore), then it will be suspended when the service has been carried out. Fn $88 Sub $08 ProcKill fails AL: reason code BX: process ID Kills the specified process, without allowing it to execute any cleanup code. Only use this on the current process or in emergencies. Fn $88 Sub $09 ProcPanicById fails AL: panic code BX: process ID Simulate the specified panic on the specified process. Fn $88 Sub $0A ProcNameById fails BX: process ID eDI: 13 byte buffer Places the name (a cstr) of the specified process in the buffer. Fn $88 Sub $0B ProcFind fails AX: -> process ID BX: 0 or process ID SI: 14 byte buffer eDI: (cstr) pattern Obtains process IDs for processes whose name matches the pattern ("?" and "*" wildcards have their Unix meaning, and case is ignored). BX should be zero to return the first matching process, or the process ID returned by a previous call to return subsequent matching processes. Process are returned in *task* ID order. The buffer is filled with a cstr giving the process name. Fn $88 Sub $0C ProcRename fails BX: process ID eDI: (cstr) new name Rename the specified process; the new name must be between 1 and 8 characters. Fn $88 Sub $0D ProcTerminate fails BX: process ID Terminates the indicated process. The process will be sent a termination message if it has so requested, and will be killed otherwise. Fn $88 Sub $0E ProcOnTerminate BX: message type When the current process is terminated, it will be sent a message of the specified type; type 0 cancels the request. After receiving the message and executing any clean-up code, the process should use ProcKill to kill itself. Fn $88 Sub $0F is reserved for the Shell process. Fn $88 Sub $10 ProcGetOwner fails AX: -> owning process ID BX: process ID Gets the ID of the process owning the specified process (normally the creator of that process). Fn $89 Sub $00 TimSleepForTenths fails CX: high half of delay DX: low half of delay Sleep for the specified delay (in units of 0.1 seconds). Changing the system clock does not affect the call. Only time when the machine is switched on is measured; any time when the machine is switched off will be in addition to the requested delay. Fn $89 Sub $01 TimSleepForTicks fails CX: high half of delay DX: low half of delay Sleep for the specified delay (in system ticks; there are 32 ticks per second on the Series 3 and 18.2 on the PC emulation). Changing the system clock does not affect the call. Only time when the machine is switched on is measured; any time when the machine is switched off will be in addition to the requested delay. Fn $89 Sub $02 TimGetSystemTime AX: -> high half of system clock BX: -> low half of system clock Reads the system clock (an abstime). Fn $89 Sub $03 TimSetSystemTime CX: high half of new system clock DX: low half of new system clock Sets the system clock to the given abstime. Fn $89 Sub $04 TimSystemTimeToDaySeconds CX: high half of abstime DX: low half of abstime DI: 8 byte buffer Splits an abstime into a day number and an interval, placed in the buffer as follows: Offset 0 (long): day number Offset 4 (long): interval Fn $89 Sub $05 TimDaySecondsToSystemTime fails AX: -> high half of abstime BX: -> low half of abstime SI: 8 byte buffer Converts a day number and an interval to an abstime. The former are in the buffer, in the same format as TimSystemTimeToDaySeconds. Fn $89 Sub $06 TimDaySecondsToDate fails SI: 8 byte buffer (day number and interval) DI: 8 byte buffer (broken down time) Converts a day number and an interval to broken-down time information. The former is in the same format as TimSystemTimeToDaySeconds. The latter is in the format: Offset 0 (byte): year - 1900 Offset 1 (byte): month (0 = January, 11 = December) Offset 2 (byte): day - 1 Offset 3 (byte): hours Offset 4 (byte): minutes Offset 5 (byte): seconds Offset 6 (word): day number in year (0 to 364 or to 365) Fn $89 Sub $07 TimDateToDaySeconds fails SI: 8 byte buffer (broken down time) DI: 8 byte buffer (day number and interval) Converts broken-down time to a day number and an interval. The day number in year (offset 6) is ignored. Fn $89 Sub $08 TimDaysInMonth fails AX: -> number of days in month CX: month * 256 + year - 1900 Gets the number of days in the specified month (0 = January, 11 = December). Fn $89 Sub $09 TimDayOfWeek AX: -> day of week (0 = Monday, 6 = Sunday) CX: high half of day number DX: low half of day number Gets the day of the week of the given date. Fn $89 Sub $0A TimNameOfDay fails AL: day of week (0 = Monday, 6 = Sunday) BX: 33 byte buffer The buffer is filled with a cstr giving the name of that day of the week. Fn $89 Sub $0B TimNameOfMonth fails AL: month (0 = January, 11 = December) BX: 33 byte buffer The buffer is filled with a cstr giving the name of that month. Fn $89 Sub $0C TimWaitAbsolute fails CX: high half of abstime DX: low half of abstime Sleep this process until the specified abstime. If the machine is turned off at that time, it will turn back on. Changing the system clock will affect when the call returns. Fn $89 Sub $0D TimWeekNumber fails AX: -> week number (1 to 53) CX: high half of day number DX: low half of day number Gets the week number of the specified day. Fn $89 Sub $0E TimNameOfDayAbb v3 fails AL: day of week (0 = Monday, 6 = Sunday) BX: 4 byte buffer The buffer is filled with a cstr giving the abbreviated name of that day of the week. The length of the abbreviated name varies between languages, but is the same for all days in a given language. Fn $89 Sub $0F TimNameOfMonthAbb v3 fails AL: month (0 = January, 11 = December) BX: 4 byte buffer The buffer is filled with a cstr giving the abbreviated name of that month. The length of the abbreviated name varies between languages, but is the same for all months in a given language. Fn $8A Sub $00 ConvUnsignedIntToBuffer AX: -> length of converted value BX: value to be converted CX: radix eDI: buffer to hold converted value The value is converted to a string in the specified radix and written to the buffer. No trailing zero byte is written; instead, the length of the string is returned. The radix can be any value from 2 to 200. If the radix is 11 or greater, digits greater than 9 are written as "A", "B", etc; characters other than digits and uppercase letters are used when the radix is 37 or more. Fn $8A Sub $01 ConvUnsignedLongIntToBuffer AX: -> length of converted value BX: low half of value to be converted CX: radix DX: high half of value to be converted eDI: buffer to hold converted value The value is converted to a string, in the same way as ConvUnsignedIntToBuffer. Fn $8A Sub $02 ConvIntToBuffer AX: -> length of converted value BX: value to be converted eDI: buffer to hold converted value The value is converted to a string in radix 10 and written to the buffer. If the value is negative, a leading "-" will be included. No trailing zero byte is written; instead, the length of the string is returned. Fn $8A Sub $03 ConvLongIntToBuffer AX: -> length of converted value BX: low half of value to be converted DX: high half of value to be converted eDI: buffer to hold converted value The value is converted to a string in radix 10, as for ConvIntToBuffer. Fn $8A Sub $04 ConvArgumentsToBuffer AX: -> length of converted format BX: buffer holding the format arguments SI: (cstr) format eDI: buffer to hold converted format The format is written to the buffer, with certain sequences of characters - "conversion specifiers" - being replaced by the values of arguments converted to strings. No trailing zero byte is written; instead, the length of the string is returned. All conversion specifiers begin with a percent sign (to include a literal percent in the output, use "%%"), followed by: - an optional alignment code - an optional width code (required if there is an alignment code) - an optional length code - a conversion code. The alignment code consists of two characters. The first is: - "-": left align (fill on the right) - "=": centre align (fill at both ends) - "+": right align (fill on the left). The second is either the character to fill with, or "*". In the latter case, the next word is taken from the arguments and used as the fill character. The default alignment is to right align filling with spaces ("+ "). Also, the alignment "+0" may be abbreviated to "0". The width code gives the number of characters generated by the conversion. If the output would be longer, it is truncated. The code is either an unsigned decimal number (not beginning with a zero), or "*". In the latter case, the next word is taken from the arguments and gives the (unsigned) width. The length code can be "l" or "L" (equivalent); it is equivalent to making the conversion code uppercase. Each conversion code (apart from "f") takes an argument of the type stated, and then converts it as described. Code Type Conversion "b" word convert to unsigned binary representation "B" long convert to unsigned binary representation "c" word output the character with that code "C" long output the character with that code "d" word convert to signed decimal representation "D" long convert to signed decimal representation "f" ---- output an empty string filled with the fill character. "F" ---- output an empty string filled with the fill character. "o" word convert to unsigned octal representation "O" long convert to unsigned octal representation "m" word output the value as 2 bytes, least significant first "M" long output the value as 4 bytes, least significant first "s" cstr output the cstr "S" cstr output the cstr "u" word convert to unsigned decimal representation "U" long convert to unsigned decimal representation "w" word output the value as 2 bytes, most significant first "W" long output the value as 4 bytes, most significant first "x" word convert to unsigned hexadecimal representation "X" long convert to unsigned hexadecimal representation Codes "m", "M", "w", and "W" are available in EPOC v2.17 and later only. Fn $8A Sub $05 ConvStringToUnsignedInt fails AX: -> converted value CX: radix SI: (cstr) string to convert -> pointer to first unused character The string is converted to an unsigned integer in the specified radix. The conversion ends at the first character which is not a valid digit for the radix, which may be the terminating zero byte; if the first character of the string is not valid, the call fails. The letters A to F, in either case, are used for digits 10 to 15 if the radix is 11 or more. The radix may be greater than 16, but the valid digits remain restricted to the range 0 to 15. Fn $8A Sub $06 ConvStringToUnsignedLongInt fails AX: -> high half of converted value BX: -> low half of converted value CX: radix SI: (cstr) string to convert -> pointer to first unused character The string is converted, in the same manner as ConvStringToUnsignedInt. Fn $8A Sub $07 ConvStringToInt fails AX: -> converted value SI: (cstr) string to convert -> pointer to first unused character The string is converted to an signed integer in radix 10. The conversion ends at the first character which is not a valid digit or leading sign; this may be the terminating zero byte. If the first character of the string is not a digit or sign, the call fails. Fn $8A Sub $08 ConvStringToLongInt AX: -> high half of converted value BX: -> low half of converted value SI: (cstr) string to convert -> pointer to first unused character The string is converted, in the same manner as ConvStringToInt. Fn $8A Sub $09 ConvFloatToBuffer fails AX: -> length of converted value DX: pointer to 6 byte conversion information block SI: address of real value to be converted DI: buffer to hold converted value The real value is converted to a cstr and placed in the buffer. The exact format of the string depends on the contents of the conversion information block: Offset 0 (byte): 0 = fixed format, 1 = exponent format, 2 = variable format Offset 1 (byte): maximum length of converted value Offset 2 (byte): number of decimal digits (fixed and exponent formats only) Offset 3 (byte): radix character Offset 4 (byte): triad character (fixed format only) Offset 5 (byte): triad threshold (fixed format only) If the converted value would be greater than the maximum length, or the real to be converted has an exponent less than -99 or greater than 99, the call fails and the contents of the buffer are undefined (note that the length of the buffer need only be the maximum specified plus an extra byte for the terminating zero). For fixed format, the resulting string will take the form: * minus sign if the value is negative; nothing if it is positive * the integer part of the number, with no leading zeros (one zero if the integer part is zero); if the triad threshold is non-zero and there are more than that number of digits in the integer part, then the triad character is inserted between groups of 3 digits * if the number of decimal digits is non-zero: - the radix character - the specified number of digits For example, the number 1234321.4731 is converted as follows (assuming that the radix character is "." and the triad character is ","): 0 decimal digits, triad threshold 0: "1234321" 0 decimal digits, triad threshold 5: "1,234,321" 0 decimal digits, triad threshold 7: "1234321" 2 decimal digits, triad threshold 5: "1,234,321.47" 6 decimal digits, triad threshold 1: "1,234,321.473100" For floating format, the resulting string will take the form: * minus sign if the value is negative; nothing if it is positive * one non-zero digit * if the number of decimal digits is non-zero: - the radix character - the specified number of digits * the letter "E" * a plus or minus sign * two digits (using leading zeros if necessary) For example, the number 1234321.4731 is converted as follows: 0 decimal digits: "1E+06" 2 decimal digits: "1.23E+06" 7 decimal digits: "1.234321E+06" 12 decimal digits: "1.234321473100E+06" Zero (with either sign) is always converted as "0E+00" or "0.000E+00" etc. For general format the resulting string will take a form depending on its value. If the maximum width is W and the real value is R, then: R <= -1E+(W-1) as for exponent format with W-7 decimal digits -1E+(W-1) < R <= -1E+(W-2) a string containing a minus sign and W-1 digits -1E+(W-2) < E <= -1E+(W-1) a string containing a minus sign and W-2 digits -1E+(W-3) < R <= -1E-4 a string containing a minus sign and then W-2 significant digits with the radix character in the appropriate position -1E-4 < R < 0 as for exponent format with W-7 decimal digits 0 = R the string "0" 0 < R < 1E-4 as for exponent format with W-6 decimal digits 1E-4 <= R < 1E+(W-2) a string containing W-1 significant digits with the radix character in the appropriate position 1E+(W-2) <= E < 1E+(W-1) a string containing W-1 digits 1E+(W-1) <= E < 1E+(W) a string containing W digits 1E+(W) <= R as for exponent format with W-7 decimal digits Fn $8A Sub $0A ConvStringToFloat fails DX: radix character SI: address of a word pointing to the start of the cstr to convert DI: address of real variable to be set Converts a string representing a floating-point value and places it in the variable. The string must have the form: * an optional sign * a mantissa containing at least one digit and an optional radix character * an optional exponent consisting of: - the letter "E" or "e" - an optional sign - an integer The resulting value must have an exponent in the range -99 to 99 inclusive. If it is outside this range, the call fails; for underflow the value 0 is stored, while for overflow an undefined value is stored. If the call succeeds, the pointer to the string is altered to point to the first character beyond the converted number. Fn $8B Sub $00 GenVersion AX: -> kernel version Gets the version of the operating system. Version 1.23 is reported as: $123A for alpha release $123B for beta release $123F for final release Fn $8B Sub $01 GenLcdType AL: -> display type Gets the display type: 0 = 640x400 LCD (MC) 1 = 640x200 LCD small version (MC) 2 = 640x200 LCD large version or CGA (PC emulation) 3 = 720x348 LCD or Hercules graphics 4 = 160x80 LCD (HC) 5 = 240x80 LCD (Series 3t) 6 = MDA (PC emulation) 7 = EGA monochrome (PC emulation) 8 = EGA colour (PC emulation) 9 = VGA monochrome (PC emulation) 10 = VGA colour (PC emulation) 11 = 480x160 LCD (Series 3a and Series 3c) 12 = 240x100 LCD (Workabout) 14 = 240x160 LCD (Siena) 255 = unknown Fn $8B Sub $02 GenStartReason AL: -> reason code Gets the reason for the last cold start: 0 = system RAM invalid 1 = forced power down 2 = user reset (using reset button) 3 = kernel fault 4 = new operating system installed The environment variables and the internal disc are valid after reasons 1 and 3, and are valid after reason 2 unless ESC was also pressed. Reason 1 only happens if a faulty device driver delayed a normal battery-low powerdown for too long. Fn $8B Sub $03 GenParse fails BX: 18 byte buffer Parse filenames according to certain basic rules. Unlike FilParse, this does not invoke any device drivers. The buffer has the format: Offset 0 (word): address of file name 1 (a cstr) Offset 2 (word): address of file name 2 (a cstr) Offset 4 (word): address of file name 3 (a cstr) Offset 6 (word): address of buffer to be filled with final name (a cstr) Offset 8 (word): address of 6 byte buffer Offset 10 (byte): device separator Offset 11 (byte): path separator Offset 12 (byte): extension separator Offset 13 (byte): maximum length of device including separators Offset 14 (byte): maximum length of path including separators Offset 15 (byte): maximum length of name Offset 16 (byte): maximum length of extension including separator The three filenames are split into 5 components, any of which may be missing. * node (ends with "::") * device (ends with device separator) * path (ends with last path separator) * name * extension (starts with extension separator) The final name is constructed by taking, for each component, the value from file name 1 if present, otherwise the value from file name 2 if present, and otherwise the value from file name 3. The 6 byte buffer is then filled in with the same data as for FilParse. File names 2 and 3 should be in different places in memory. Fn $8B Sub $04 LongUnsignedIntRandom AX: -> high half of random number BX: address of seed -> low half of random number Generates a 32 bit unsigned random number from a seed; the number also replaces the seed, so that the sequential calls with the same seed address will generate a random sequence based on the initial seed. Fn $8B Sub $05 GenGetCountryData BX: 40 byte buffer Fills the buffer with country-specific data: Offset 0 (word): country code (e.g. UK is 44) of locale Offset 2 (word): current offset from GMT in minutes (+ is ahead) Offset 4 (byte): date format (0 = MDY, 1 = DMY, 2 = YMD) Offset 5 (byte): time format (0 = am-pm, 1 = 24 hour) Offset 6 (byte): currency symbol position (0 = before, 1 = after) Offset 7 (byte): currency symbol separated with space (0 = yes, 1 = no) Offset 8 (byte): currency decimal places Offset 9 (byte): currency negative format (0 = minus, 1 = brackets) Offset 10 (byte): currency triad threshold Offset 11 (byte): triad separator Offset 12 (byte): decimal separator Offset 13 (byte): date separator Offset 14 (byte): time separator Offset 15 to 23: currency symbol (cstr) Offset 24 (byte): start of week (0 = Mon, 1 = Tue, ... 6 = Sun) Offset 25 (byte): currently active summer times: Bit 0: home Bit 1: European Bit 2: Northern Bit 3: Southern Bits 4 to 7: unused, always zero Offset 26 (byte): clock type (0 = analogue, 1 = digital) Offset 27 (byte): number of letters in day abbreviation (0 to 6) Offset 28 (byte): number of letters in month abbreviation (0 to 255) Offset 29 (byte): workdays (the set bits indicate the workdays) Bit 0: Monday Bit 1: Tuesday Bit 2: Wednesday Bit 3: Thursday Bit 4: Friday Bit 5: Saturday Bit 6: Sunday Bit 7: always zero Offset 30 (byte): units (0 = inches, 1 = centimetres) If the triad threshold is non-zero and there are more than that number of digits in the integer part of an amount of money, then the triad character should be inserted between groups of 3 digits. See ConvFloatToBuffer for a way to do this. Fn $8B Sub $06 GenGetErrorText AL: error number BX: 64 byte buffer The buffer will be filled with a cstr giving an error message corresponding to the error number (a generic message including the number is used when there is no stored message in the current locale). Fn $8B Sub $07 GenGetOsData CX: number of bytes to fetch SI: offset of first byte in kernel workspace DI: buffer to be filled in Copy a number of bytes from the kernel workspace to the current process. Within assembler code, this can also be done via GenDataSegment (see Psionics file KERNEL). Fn $8B Sub $08 only applies to MC systems. Fn $8B Sub $09 GenNotify fails AL: -> option chosen (0 = first, 1 = second, 2 = third) BX: first message (cstr, up to 63 characters plus the terminating zero) CX: second message (cstr, up to 63 characters plus the terminating zero) DX: first option (cstr, up to 15 characters plus the terminating zero) SI: second option (cstr, up to 15 characters plus the terminating zero) DI: third option (cstr, up to 15 characters plus the terminating zero) Sends a message to the notifier process and waits for a reply. The call fails if there is no notifier process running. The two messages are displayed, and the user is offered the three options. The chosen option is returned. Any of the arguments except BX may be zero instead; for CX this means that only one message is displayed, while for DX, SI, and DI it means that less options are offered (if all are zero, the option "CONTINUE" is offered). Fn $8B Sub $0A GenNotifyError fails AL: error number -> option chosen (0 = first, 1 = second, 2 = third) BX: first message DX: first option SI: second option DI: third option This call is equivalent to GenNotify with the second message derived from the error number via GenGetErrorText. Fn $8B Sub $0B and $0C are used by the notifier process. Fn $8B Sub $0D GenGetRamSizeInParas AX: -> system RAM size Gets the amount of system RAM fitted, in units of 16 bytes. Note that this is an unsigned value - $8000 represents 512 kb, not some negative amount. Fn $8B Sub $0E GenGetCommandLine AX: -> zero or command line Gets a pointer to the command line if the program was started with program information (see FilExecute). If so, the command line consists of a cstr giving the program executed, immediately followed by the program information (a qstr). Fn $8B Sub $0F GenGetSoundFlags AX: -> sound flags Gets the sound flags: Bit 0: keyboard clicks enabled Bit 1: sound via piezo buzzer enabled Bit 2: sound via SND: device driver enabled Bit 3: keyboard clicks: set=loud, clear=soft Bit 4: piezo buzzer: set=loud, clear=soft Bit 15: set=disable all sound, clear=obey individual flags Fn $8B Sub $10 GenSetSoundFlags BX: sound flags Sets the sound flags to new values (see GenGetSoundFlags). Fn $8B Sub $11 GenSound BX: duration in ticks CX: pitch code (frequency=512kHz/code) Makes a simple single-frequency note. Access to this call is sequenced; it will wait until the piezo buzzer is not in use, and will return when the sound has started to play. On the Series 3a, the piezo buzzer is emulated by the SND: device, but the emulation is complete (for example, this call works even when SND: is disabled by GenSetSoundFlags). Fn $8B Sub $12 GenMarkActive Fn $8B Sub $13 GenMarkNonActive These two calls alter the state of the current process to "active" (the default when the process starts) or "non-active". Whenever an active process restarts execution after being idle (basically when keywords such as IOWAIT, IOW, GET and so on return), the auto-off timer is reset; the machine switches off when the timer reaches the appropriate value. Fn $8B Sub $14 GenGetText fails AL: message number eBX: 64 byte buffer Copies a message (a cstr) from the kernel message table to the buffer. Fn $8B Sub $15 GenGetNotifyState AL: -> notify state (0=unattended, 1=notify) Gets the notify state for the process. If this is "unattended", then the file server will not call the notifier process when a correctable error occurs (such as an SSD with open file being removed), but will simply return an error. If it is "notify" (the initial state), then it will use GenNotify to request the user to fix the problem. Fn $8B Sub $16 GenSetNotifyState AL: notify state Sets the notify state for the process. See GenGetNotifyState for details. Fn $8B Sub $17 GenGetAutoSwitchOffValue AX: -> auto-off time in seconds, or $FFFF if disabled Gets the auto-off time. Fn $8B Sub $18 GenSetAutoSwitchOffValue BX: auto-off time in seconds, or $FFFF to disable Sets the auto-off time. Times of less than 15 are adjusted to 15. Fn $8B Sub $19 and $1A are for device drivers only. Fn $8B Sub $1B GenGetLanguageCode AX: -> current locale code Gets the current locale code. Locale codes are listed in the Psionics file LOCALES. Fn $8B Sub $1C GenGetSuffixes eBX: 93 byte buffer The buffer is filled with 31 cstrs giving the correct suffix for each of the 31 days of the month. The suffix for day N is at offset (3*N-3). Fn $8B Sub $1D GenGetAmPmText AL: 0=AM, 1=PM eBX: 3 byte buffer The buffer is filled with a cstr giving the correct suffix for "a.m." or "p.m." times. Fn $8B Sub $1E GenSetCountryData eBX: 40 byte buffer Sets the country-specific data to that in the buffer. See GenGetCountryData for the format of the buffer. Fn $8B Sub $1F GenGetBatteryType AL: -> battery type Gets the battery type from the following list: 0 = Unknown 1 = Alkaline 2 = NiCaD (600 mAh) 3 = NiCaD (1000 mAh) 4 = NiCaD (500 mAh) The battery type is used to control the warning thresholds. Fn $8B Sub $20 GenSetBatteryType AL: battery type Sets the battery type (see GenGetBatteryType). Fn $8B Sub $21 GenEnvBufferGet fails AX: -> size of value DX: length of pattern eSI: buffer filled with value eDI: pattern to search for Searches for an environment variable whose name matches the pattern (if there is more than one, which one is chosen is unspecified). The buffer is filled with the variable's value. Fn $8B Sub $22 GenEnvBufferSet fails CX: size of value (0 to 255) DX: length of name (1 to 16) eSI: buffer holding value eDI: name of variable Changes the value of the specified enviromment variable, creating it first if necessary. The name may not contain wildcards. Fn $8B Sub $23 GenEnvBufferDelete fails DX: length of name eDI: pattern to delete Searches for an environment variable whose name matches the pattern and deletes it (if there is more than one, which one is deleted is unspecified). Fn $8B Sub $24 GenEnvBufferFind fails AX: -> new handle BX: previous handle (0 for first call) DX: length of pattern eSI: 273 byte buffer eDI: pattern to search for Searches for each environment variable whose name matches the pattern. The call is made multiple times until it fails; the same pattern must be used each time. If the call succeeds, the buffer is filled with two qstrs, the first being the name and the second the value of the variable found. Fn $8B Sub $25 GenEnvStringGet fails eSI: 256 byte buffer eDI: pattern (cstr) Searches for an environment variable whose name matches the pattern (if there is more than one, which one is chosen is unspecified). The buffer is filled with the variable's value followed by a zero byte (thus a cstr). Fn $8B Sub $26 GenEnvStringSet fails eSI: value (cstr) eDI: name (cstr) Changes the value of the specified enviromment variable, creating it first if necessary. The name may not contain wildcards and is limited to 16 characters; the value is limited to 255 characters. Fn $8B Sub $27 GenEnvStringDelete fails eDI: pattern (cstr) Searches for an environment variable whose name matches the pattern and deletes it (if there is more than one, which one is deleted is unspecified). Fn $8B Sub $28 GenEnvStringFind fails AX: -> new handle BX: previous handle (0 for first call) eCX: 256 byte buffer eSI: 17 byte buffer eDI: pattern to search for Searches for each environment variable whose name matches the pattern. The call is made multiple times until it fails; the same pattern must be used each time. If the call succeeds, the 17 byte buffer is filled with the name of the variable, as a cstr, and the 256 byte buffer is filled with the value followed by a zero byte (thus also a cstr). Fn $8B Sub $29 GenCrc AX: -> CRC CX: buffer length DX: previous CRC SI: buffer Calculates the CCITT Cyclic Redundancy Checksum using the X^16+X^12+X^5+1 polynomial (e.g. the CRC of a single byte with value 1 is $1021). If the buffer is to be checked standalone, use zero as the previous checksum. If several blocks are to be checksummed as if they were one long block, use 0 as the previous CRC for the first block, and the previous result for the remainder. Fn $8B Sub $2A GenRomVersion AX: -> rom version number Gets the version of the system ROM (which includes both the operating system and many files). Version 1.23 is reported as: $123A for alpha release $123B for beta release $123F for final release Fn $8B Sub $2B and $2C are used by the alarm server process. Fn $8B Sub $2D GenAlarmId AX: -> alarm server pid Gets the process ID of the alarm server process, or 0 if none is running. Fn $8B Sub $2E GenPasswordSet fails uSI: (qstr) current password uDI: (qstr) new password Sets a new system password. The call will fail and take no action if the current password is incorrect. Fn $8B Sub $2F GenPasswordTest fails uSI: (qstr) password to test Succeeds if the system password is that provided. Fn $8B Sub $30 GenPasswordControl fails AL: new state (0 = off, 1 = on) uSI: (qstr) current password Turns the system password on and off. The call will fail and take no action if the current password is not provided. Fn $8B Sub $31 GenPasswordQuery AX: -> new state (0 = off, 1 = on) Get the status of the system password. Fn $8B Sub $32 GenTickle Resets the auto-off timer. A non-active process (see GenMarkNonActive) can use this to prevent auto-off. Fn $8B Sub $33 GenSetConfig @No documentation available at present@ Fn $8B Sub $34 GenMaskInit fails SI: (qstr) password DI: 18 byte encryption control block Initializes an encryption control block according to the password given. The contents of the control block for the current algorithm are: Offset 0 to 8: encryption key, generated from the password Offset 9 to 15: copy of offset 0 to 7 Offset 16 (word): current location within the key (initially zero) @The algorithm for generating the key from the password is unknown. It is possible that future versions of this call may implement multiple encryption algorithms, so AL, BX, CX, and DX - unused at present - should be set to zero. Fn $8B Sub $35 GenMaskEncrypt fails CX: length of buffer SI: encryption control block DI: buffer holding data to be encrypted Encrypts a block of data according to the encryption control block, which will be updated. The value of the encrypted data depend only on the original data and on the contents of the control block, which should normally be initialized by GenMaskInit. Provided that the control block is not modified in any other way, encrypting a block of data in two or more parts yields the same result as encrypting it all at once. The current encryption algorithm operates on a byte by byte basis as follows. For each data byte in turn, take the value of offset 16 in the control block (which will be from 0 to 15) and use it to select one of the first 16 bytes in the control block (that is, offset 16 = 0 selects offset 0, offset 16 = 1 selects offset 1, and so on). Add the selected byte to the data byte modulo $100. Finally, add 1, modulo 16, to offset 16 of the control block. An example of this algorithm in use can be found in the file WORD.FMT. It is possible that future versions of this call may implement multiple encryption algorithms, so AL, BX, and DX - unused at present - should be set to zero. Fn $8B Sub $36 GenMaskDecrypt fails CX: length of buffer SI: encryption control block DI: buffer holding data to be decrypted Decrypts a block of data according to the encryption control block, which will be updated. The data should have been encrypted with GenMaskEncrypt with the same initial control block. All comments applying to the latter call apply here. Fn $8B Sub $37 GenSetOnEvents v2.28 AL: 0=disable 1=enable Enables or disables reporting of power-on events. By default this is enabled on the Series 3 and disabled on other systems. Disabling may affect other applications. Fn $8B Sub $38 GenGetAutoMains v3 AX: -> setting Gets the setting of the external power auto-off flag. Zero means that auto-off will take place even if external power is present, while non-zero means that auto-off is suspended while external power is present. Fn $8B Sub $39 GenSetAutoMains v3 AL: new setting Sets the external power auto-off flag. Zero means that auto-off will take place even if external power is present (unless it has been disabled by setting the auto-off time to $FFFF), while non-zero means that auto-off is suspended while external power is present. Fn $8C Sub $00 FloatSin fails [sine] Fn $8C Sub $01 FloatCos fails [cosine] Fn $8C Sub $02 FloatTan fails [tangent] Fn $8C Sub $03 FloatASin fails [arc sine] Fn $8C Sub $04 FloatACos fails [arc cosine] Fn $8C Sub $05 FloatATan fails [arc tangent] Fn $8C Sub $06 FloatExp fails [exponentiation (base e)] Fn $8C Sub $07 FloatLn fails [natural logarithm (base e)] Fn $8C Sub $08 FloatLog fails [decimal logarithm (base 10)] Fn $8C Sub $09 FloatSqrt fails [square root] SI: argument (real) DI: result (real) Calculates the specified function of the argument. The argument and result may be stored in the same place; if not, the argument is not altered. The trignometric functions operate in radians. Fn $8C Sub $0A FloatPow fails DX: power (real) SI: base (real) DI: result (real) Calculates the result of raising the base to the indicated power. The result may be stored in the same place as either argument; if not, neither argument is altered. Fn $8C Sub $0B FloatRand SI: seed (long) DI: result (real) Generates a random real number based on the unsigned long integer seed, which is unaltered; the memory used for the two should not overlap. Fn $8C Sub $0C FloatMod fails DX: divisor (real) SI: dividend (real) DI: result (real) Calculates the dividend modulo the divisor, using the formula: result = dividend - divisor * FloatInt (dividend/divisor) The result may be stored in the same place as either argument; if not, neither argument is altered. Fn $8C Sub $0D FloatInt fails SI: argument (real) DI: result (real) Rounds the argument to the closest integer towards zero (i.e. zeros the fractional part of the argument). The argument and result may be stored in the same place; if not, the argument is not altered. Further system calls are described in Psionics file SYSCALLS.3.