1. Home /
2. Psion II /
3. System services /
4. CM/XP, Part 2

System services for the CM/XP part 2

Part 1:
  Allocator cells and their system services.
    AL$FREE AL$GRAB AL$GROW AL$REPL

    AL$SHNK AL$SIZE AL$ZERO
  Hardware services
    BT$NMDN BT$NMEN BT$NOF BT$NON

    BT$PPRG BT$SWOF
  Sound services
    BZ$ALRM BZ$BELL BZ$TONE
  Display services
    DP$EMIT DP$PRNT DP$REST DP$SAVE
    DP$STAT DP$VIEW DP$WRDY
  Device services
    DV$BOOT DV$CLER DV$LKUP DV$LOAD DV$VECT
  Editor services
    ED$EDIT ED$EPOS ED$VIEW
  Error services
    ER$LKUP ER$MESS
  File services
    FL$BACK FL$BCAT FL$BDEL FL$BOPN
    FL$BSAV FL$CATL FL$COPY FL$CRET
    FL$DELN FL$ERAS FL$FFND FL$FIND
    FL$FREC FL$NEXT FL$OPEN FL$PARS
    FL$READ FL$RECT FL$RENM FL$RSET
    FL$SETP FL$SIZE FL$WRIT
  Complex Floating point services
    FN$ATAN FN$COS FN$EXP FN$LN
    FN$LOG FN$POWR FN$RND FN$SIN
    FN$SQRT FN$TAN

Part 2:

  Table interpreter services.
    IT$GVAL IT$RADD IT$STRT IT$TADD
  Keyboard services.
    KB$INIT KB$TEST KB$GETK KB$BREK
    KB$FLSH KB$UGET KB$STAT
  Language services.
    LG$RLED LG$NEWP LN$STRT
  Menu services.
    MN$DISP
  Floating point arithmetic services.
    MT$BTOF MT$FADD MT$FBDC MT$FBEX
    MT$FBGN MT$FBIN MT$FDIV MT$FMUL
    MT$FNGT MT$FSUB
  Pack services.
    PK$PKOF PK$QADD PK$RBYT PK$READ
    PK$RWRD PK$SADD PK$SAVE PK$SETP
    PK$SKIP
  Run services.
    RM$RUNP
  Top level services.
    TL$ADDI TL$CPYX TL$DELI TL$XXMD
    TL$RSTR TL$LSET
  Timing services.
    TM$DAYV TM$TGET TM$UPDT TM$WAIT
  Utility display services.
    UT$DDSP UT$DISP UT$CDSP
  Utility services.
    UT$CPYB UT$ENTR UT$FILL UT$ICPB
    UT$ISBF UT$LEAV UT$SDIV UT$SMUL
    UT$SPLT UT$UDIV UT$UMUL UT$UTOB
    UT$XCAT UT$XTOB UT$YSNO

LZ Services
  Hardware services
    BT$TOFF
  Display services
    DP$CPRN DP$CSET DP$MSET DP$PVEW
    DP$UDG XT$BAR
  Editor services
    TL$ZZMD
  Error services
    ER$PRNT
  File services
    FL$FDEL FL$GETX FL$NCAT FL$VALX
    FL$WCAT FL$WCPY FL$WDEL FL$WFND
    FL$WPAR XF$SORT XT$DIRM
  Complex Floating point services
    FN$ASIN FN$ACOS FN$MAX FN$MEAN
    FN$MIN FN$STD FN$SUM FN$VAR
  Keyboard services.
    KB$CONK
  Language services.
    LG$EDIT LG$ENTR LN$XSTT
  Menu services.
    MN$1DSP MN$TITL MN$XDSP
  Timing services.
    TM$DNAM TM$MNAM TM$NDYS TM$TSET
    TM$WEEK
  Top level services.
    AM$ENTR CA$ENTR DI$ENTR NT$ENTR
    TI$ENTR WL$ENTR XF$ENTR XT$ENTR
  Utility services.
    UT$CMPB UT$SORT UT$WILD

Table interpreter services.

The following 4 services are used for table programs. A table consists of a list of bytes, which is interpreted by the IT$STRT service like a program. The advantage of this is that the user can supply a machine code subroutine to run for most table bytes, thus making the code more compact. Table programs are used in the ROM mainly for complex floating point system services (and for password codes on the LZ).

In a table program, the bytes $00-$14 have predetermined actions and the bytes $15-$FF are available for user defined actions. The first word of a table contains an offset to the list of addresses of the machine code subroutines that define the user actions. This list starts with the address that is to be called when action $15 is encountered, and ends with the address belonging to the highest defined action byte. The table program itself starts from the third byte of the table, i.e. immediately after the list offset.

The table program has 32 bytes of variable space assigned to it at ITT_REGS ($234D-$236C) and also its own independent stack area at ITT_STAK ($236D-$23AC).

Many actions need parameters and these of course usually follow immediately after the action byte. The predefined actions often use a single byte in the range $E0-$FF to denote the 32 byte variables, and numbers in the range $00-$DF as ordinary numbers. If an address in the table is given as a parameter then the address is given as an offset from the start of the table. Note that the start of the table is the word pointing to the user action address list, not the start of the table program.

The following functions are predefined:
00  RETURN: Return from a table subroutine, i.e. pulls a table address from the table stack and continues the table program there.
01  CALL: Calls a table subroutine also passing the given parameters. The action byte is followed by: - a byte denoting the number of bytes passed to the subroutine. - the subroutine address (as offset from table start) - the list of bytes to pass to the subroutine. The parameters to be passed are put in the table variables before calling the subroutine, so at most 32 bytes can be passed along, and the previous values of the variables $E0-$?? are overwritten. See also action 10.
02  BRANCH FALSE: Branches if the result of a previous comparison was false, see the actions 08 and 09. The relative jump following the action byte is different from the relative jumps in ordinary machine code, in that the branch is calculated from the current action byte. Thus a branch of 2 will do nothing. Negative branches are allowed.
03  BRANCH TRUE: Like action 02, except that it branches if the result of a previous comparison was true.
04  CASE: Jumps to one of a list table addresses depending on a variable. The action byte is followed by a variable ($E0-$FF) and a table address. The address points to a case-list which is in the following format: byte, table address; byte, table address; .... etc. If the variable matches one of the bytes on the list, CASE will cause a jump to the associated address. A byte of $FF can be used in the last list entry to denote the ELSE case, which will be called whenever the variable doesn't match any of the earlier entries.
05  VECTOR: Jumps to one of a list table addresses depending on a variable, like the BASIC instruction ON x GOTO. The action byte is followed by a variable, and a table address. The table address points to a list of table addresses. If the variable contains 0 the interpreter takes the first table address on the list and jumps to it, 1 uses the second address etc.
06  JUMP: Jumps to the given table address.
07  BRANCH: Branches a given distance. See action 02.
08  EQUAL: The action byte is followed by two bytes, which can be numbers or variables. This action tests whether the two values are equal.
09  UNEQUAL: The action byte is followed by two bytes, which can be numbers or variables. This action tests whether the two values are different.
0A  ASSIGN: The action byte is followed by a variable, and a byte value that may be either a number or a variable. This action assigns the value to the given variable.
0B  ADD: The action byte is followed by a variable, and a byte value that may be either a number or a variable. This action adds the value to the given variable.
0C  SUB: The action byte is followed by a variable, and a byte value that may be either a number or a variable. This action subtracts the value from the given variable.
0D  PUSH: Pushes the given address on the table stack. This first subtracts two from the stack pointer ITA_SPTR and then stores the given word at this new value of ITA_SPTR. See also action 0F.
0E  CALLMC: Calls the machine code routine at the given address. Note that the address is an absolute address, not a table offset. The variable $E0 is passed in the B register when the routine is called.
0F  POP: Pops a word off the table stack, by adding two to the stack pointer ITA_SPTR. Note that the value that was on the top of the stack is lost. For this reason, the table stack is not used for temporarily storing data, just for storing return addresses when table subroutines are called. User defined actions can use the stack for other purposes.
10  JSR: Calls the table subroutine at the given address, without passing any parameters. See also action 01. The subroutine is exited by the action 00.
11  RANGE: The action byte is followed by three bytes, which can be numbers or variables. This action tests whether the first value lies between the other two, i.e. whether v2<=v1<=v3.
12  PEEK: The action byte is followed by a variable and a table address. This action stores the contents of the table address in the variable.
13  POKE: The action byte is followed by a byte (variable or number) and a table address. This action stores the given value at the table address.
14  END: Ends the table program normally, returning to next instruction after the IT$STRT call with register B=0 and the zero flag set. This can also be called in a table subroutine.

The system variable ITA_PCNT ($D7) is used as a table program counter. At the start of a user action routine, ITA_PCNT still points to the action byte. The user routine must end with B containing the number to add to ITA_PCNT for it to point to the next table instruction (i.e. 1 if no parameters were used).
To quit the table program during a user action, pull one return address from the machine stack, load B with an error code and perform a RTS instruction.
The system variable ITA_SPTR ($DB) contains the table stack pointer, which contains the address of the last word pushed on the stack.
The system variable ITA_UVC ($234B) points to the absolute address of the list of user action addresses.
The system variable ITA_BAS ($D9) points to the absolute address of the table, i.e. the address given when IT$STRT was called.
The system variable ITA_TEST ($DD) contains the result of comparisons, i.e. the result from actions 08, 09 and 11. Actions 02 and 03 test whether this value is zero (false) or non-zero (true). User actions may of course use this byte in other ways.

Keyboard services.

The keyboard is checked by the OCI interrupt routine, which normally occurs 20 times a second. The routine first calls the keyboard poll routine (its address is held in bta_poll, $205A), which scans the keyboard. If it reports that there are keys being pressed, then the keyboard translation routine (its address is held in bta_tran, $205C) is called which returns which character that corresponds to, taking into account the state of the Caps/Num locks, auto-repeat delays etc. The ascii value of the key is then saved in the keyboard buffer.

The keyboard buffer holds any keys that have been pressed until the organiser's software is ready to use them. It can contain up to 16 keys, and is found at kbt_buff, $20B0-F. It is a wraparound buffer, so it can be considered to be a loop without a fixed beginning. The offset to the oldest key is held in kbb_back ($73), the number of keys is kbb_nkys ($74).

Language services.

Menu services.

Floating point arithmetic services.

Pack services.

Run services.

Top level services.

Timing services.

Utility display services

Format control strings.

The following two system services can be used to display information on the screen at the current cursor position. They use a format control string which controls the way the information is displayed.

In the simplest case, the format control string is simply a string of characters to be displayed. The characters '%', '+', '-' and '}' are reserved for special purposes as described below. Control characters can be used, except for 0 which signals the end of the format control string. The LZ has an extra control character available, viz. 31 which will centralize the next string on the current line, clearing the left and right sides of the line.

The character '%' can be followed by a letter to indicate what kind of information is to be displayed and in what way. Here is the list of letters and what they do:
  %a  display ASCII character
  %i  display signed integer word in decimal
  %j  display signed integer byte in decimal
  %u  display unsigned integer word in decimal
  %v  display unsigned integer byte in decimal
  %x  display unsigned integer word in hex
  %y  display unsigned integer byte in hex
  %s  display a lbc string
  %b  display text buffer (address and length byte given)
  %f  fill field (for this type a field width must be included; see below)

These combinations need further information on what is to be displayed. Both the following system services assume that this information has been pushed onto the machine stack. Thus if the byte $F0 were pushed on the stack and one of the following services were called with the format string '%v' then '240' would be printed on the screen.

These combinations can also be used for left justifying the data to be displayed. This is done by inserting the length of the field to be used between the '%' character and the control letter in ASCII decimal format. Thus if '%10v' were used to display the byte $F0 then '240       ' would be printed, which is ten characters long. Note that with the '%' character the data is always left justified, so if a field width is included spaces are added to the right.

The control character '+' can also be used for left justifying. This time however the character to be used to fill out the field must be given as well as the field width. Thus using '+X10v' to print $F0 will show the string '240XXXXXXX'.

The control character '-' can be used for right justifying. This is used in the same way as '+' so the character to be used to fill out the field must be given as must the field width. Thus using '-010v' to print $F0 will show the string '0000000240'. Note how the first '0' is the fill character and not part of the field width.

The field width can be up to 99 characters wide, and if the string does not fit on the screen it will scroll vertically upwards. If the data to be displayed does not fit inside the given field width then only some of the characters can be displayed. With '%' and '+' the data is left justified so the leftmost characters are displayed, and similarly with '-' the rightmost. For example '-02v' shows $F0 as '40', while '+02v' or '%2v' shows it as '24'.

The character '}' is used as shorthand for '-02v'. This shows the last two digits of a single unsigned byte, including a leading 0 if necessary.

To display the characters '%', '+', '-' and '}' themselves simply precede them by '%'. Thus '%+' displays '+' and '%%' displays '%'.

The control letter 'f' is used when a sequence of characters is needed. For example, '%16f' displays 16 spaces. A field width must be given in this case. To display a sequence of another character you must use '+', for example '+*16f' shows 16 asterisks.

All the control letters (except for 'f') need to know what number or string is to be displayed, and this information is taken from the stack. For example, to display a time ' 7:45' when A contains the hours and B the minutes, then you must use PSHB, PSHA followed by one of the following system services with the control string '- 2v:}'. Note that the hours are pushed last so that they are popped from the stack first and hence displayed first.

When the control letter 'b' is used a text buffer is displayed. To use this option, you must push the length (1 byte) of the text first, followed by the address of the buffer. For control letter 's' only the address needs to be pushed as the string stored there has a lbc.

It goes without saying that you must be sure that the correct amount of data is pushed or else the stack is corrupted. Care must also be taken that the data is pushed in the correct order, that the control letters in the format control string are in lower case, and that the format control string ends with a zero byte.

LZ users (and probably users of other multi-lingual machines) should note that if format control strings from the ROM are used (i.e. strings at an address with bit 15 set) then the characters $60 to $FF are used to denote various system messages, which will then be displayed in the current language.

Utility services