The PSION Organiser II Homepage
 
Home
Technical Reference
Introduction
System
Versions
Operating
System
Memory Usage
Filing System
System Timing
System Board
Power Supply Board
Display
Keyboard
Interface Slots
Packs
General
Flashpacks
Low Level
Access
External
Interfacing
Comms Link
Psion Link
Protocol
Utility System
Services
Built-in
Applications
LZ Passwords
Programming
Language
General
Q-Code
Table
Interpreter
System Services
 

Technical Reference Manual

Q-CODE

OPERANDS

OPERATORS

COMMAND OPERATORS

FILE OPERATORS

OTHER OPERATORS

 

INTEGER FUNCTIONS

FLOATING POINT FUNCTIONS

STRING FUNCTIONS

INDEX OF OPERANDS

INDEX OF OPERATORS

INDEX OF FUNCTIONS

EXAMPLES

OPERANDS

Each operand stacks either a constant value or a pointer to a variable.

There are a number of types of operands. Operands are named after their type, the types are:

IntegerINT
Floating pointNUM
StringSTR
Constants (i.e. not variables)CON
ArraysARR
Simple (i.e. not array)SIM
Offset from RTA_FPFP
Indirect offset from RTA_FPIND
Left side (i.e. assigns)LS
FieldFLD
Stack byte/wordLIT
Refer to the fixed memoriesABS
Internal NameOp + BytesAdded to the stack
QI_INT_SIM_FP$002The integer
QI_NUM_SIM_FP$012The floating point number
QI_STR_SIM_FP$022The string

These operands take the following word, add it to RTA_FP (see section Language Pointers) and stack the variable at that address.

Internal NameOp + BytesStack
QI_INT_ARR_FP$032Drops element number, adds an integer from the array
QI_NUM_ARR_FP$042Drops element number, adds a floating point number from the array
QI_STR_ARR_FP$052Drops element number, adds a string from the array

These operands take the following word, adds it to RTA_FP to get the start of the array. The required element number is dropped off the stack and checked against the maximum size of the array. The address of the element is then calculated and the variable stacked.

Internal NameOp + BytesAdded to the stack
QI_NUM_SIM_ABS$062Floating point number

This operand gives access to the calculators memories, M0 to M9. The operand is followed by the offset to the memory required.

Internal NameOp + BytesAdded to the stack
QI_INT_SIM_IND$072The integer
QI_NUM_SIM_IND$082The floating point number
QI_STR_SIM_IND$092The string

These operands take the following word, add it to RTA_FP, load the address at that address and stack the variable at that address.

Internal NameOp + BytesStack
QI_INT_ARR_IND$0A2Drops element number, adds the integer from the array
QI_NUM_ARR_IND$0B2Drops element number, adds the floating point number from the array
QI_STR_ARR_IND$0C2Drops element number, adds the string from the array

These operands take the following word, adds it to RTA_FP, loads the address at that address to get the start of the array. The element of the array required is dropped off the stack, it is then checked against the maximum size of the array. The address of the element is then calculated and the variable stacked.

Internal NameOp + BytesAdded to the stack
QI_LS_INT_SIM_FP$0D2The address of the integer + field flag
QI_LS_NUM_SIM_FP$0E2The address of the floating point number + field flag
QI_LS_STR_SIM_FP$0F2The maximum size + the address of the string + field flag
QI_LS_INT_ARR_FP$102The address of the integer from the array + field flag
QI_LS_NUM_ARR_FP$112The address of the floating point number from the array + field flag
QI_LS_STR_ARR_FP$122The maximum size + the address of the string from the array + field flag
QI_LS_NUM_SIM_ABS$132The address of the calculator memory + field flag
QI_LS_INT_SIM_IND$142The address of the integer + field flag
QI_LS_NUM_SIM_IND$152The address of the floating point number + field flag
QI_LS_STR_SIM_IND$162The maximum size + the address of the string + field flag
QI_LS_INT_ARR_IND$172The address of the integer from the array + field flag
QI_LS_NUM_ARR_IND$182The address of the floating point number from the array + field flag
QI_LS_STR_ARR_IND$192the maximum size + the address of the string from the array + field flag

These operands correspond to their right side equivalents. In the case of strings the maximum length is stacked first. Then, in all cases, the address of the variable is stacked. The field flag byte is then stacked, in all these cases it is zero to show that it is not a field reference.

Internal NameOp + BytesStack
QI_INT_FLD$1A1Drops the field name, adds the integer
QI_NUM_FLD$1B1Drops the field name, adds the floating point number
QI_STR_FLD$1C1Drops the field name, adds the string

These operands are followed by a logical file name, 0,1,2 or 3, which says which logical file to use. First it looks for the field name in the Field Name Symbol Table. If it is found the corresponding field is split from the corresponding File Buffer. If it is a string it is immediately placed on the stack. If it is numeric it is converted from ASCII to the relevant format and placed on the stack.

Internal NameOp + BytesStack
QI_LS_INT_FLD$1D1Stacks the logical file name + field flag
QI_LS_NUM_FLD$1E1Stacks the logical file name + field flag
QI_LS_STR_FLD$1F1Stacks the logical file name + field flag

These operands stacks the logical file, the byte following the operand, and the field flag which in this case is non-zero. All the work is done by the assign.

Internal NameOp + BytesAdded to the stack
QI_STK_LIT_BYTE$201The byte
QI_STK_LIT_WORD$212The word

Stacks the following byte or word. QI_STK_LIT_WORD is identical to QI_INT_CON.

Internal NameOp + BytesAdded to the stack
QI_INT_CON$222Integer
QI_NUM_CON$23*Floating point number
QI_STR_CON$24*String

Stacks the constant value following.

OPERATORS

Operators generally do things to the variables already on the stack.

ERRORS, CALLS AND PARAMETERS

In the following section if an operand cannot return an error then no errors are listed.

Any access to a device can result in the following errors. They are no given explicitly as error for that operand/operator:

ER_FL_NP - no pack
ER_PK_IV - unknown pack
ER_DV_CA - bad device name and if the pack was not blank
ER_PK_NB - pack not blank

When writing to a pack the following are always possible:

ER_FL_PF - pack full
ER_PK_RO - read only pack
ER_PK_DE - write error

If the operator calls an operating system then that is listed. If no calls are given then the run time code handles it all itself. In general there is no difference between call with a $ and with an _, the $ calls are called through SWIs whereas the _ calls are made directly. Direct calls are faster, but SWIs can be redirected for the addition of extra features.

If there is more than one parameter they are listed. The values are stacked in order. So para1 is stacked before para2 - when the operator is called the last parameter is the one pointed to by the RTA_SP.

LOGICAL AND ARITHMETIC COMPARE OPERATORS

Internal NameOpStack
QCO_LT_INT$27Drops 2 INTs, returns 0 or -1 as an INT
QCO_LTE_INT$28Drops 2 INTs, returns 0 or -1 as an INT
QCO_GT_INT$29Drops 2 INTs, returns 0 or -1 as an INT
QCO_GTE_INT$2ADrops 2 INTs, returns 0 or -1 as an INT
QCO_NE_INT$2BDrops 2 INTs, returns 0 or -1 as an INT
QCO_EQ_INT$2CDrops 2 INTs, returns 0 or -1 as an INT
QCO_ADD_INT$2DDrops 2 INTs, returns result as an INT
QCO_SUB_INT$2EDrops 2 INTs, returns result as an INT
QCO_MUL_INT$2FDrops 2 INTs, returns result as an INT
QCO_DIV_INT$30Drops 2 INTs, returns result as an INT
QCO_POW_INT$31Drops 2 INTs, returns result as an INT
QCO_UMIN_INT$32Drops an INT, returns result as an INT
QCO_NOT_INT$33Drops an INT, returns result as an INT
QCO_AND_INT$34Drops 2 INTs, returns result as an INT
QCO_OR_INT$35Drops 2 INTs, returns result as an INT
QCO_LT_NUM$36Drops 2 NUMs, returns 0 or -1 as an INT
QCO_LTE_NUM$37Drops 2 NUMs, returns 0 or -1 as an INT
QCO_GT_NUM$38Drops 2 NUMs, returns 0 or -1 as an INT
QCO_GTE_NUM$39Drops 2 NUMs, returns 0 or -1 as an INT
QCO_NE_NUM$3ADrops 2 NUMs, returns 0 or -1 as an INT
QCO_EQ_NUM$3BDrops 2 NUMs, returns 0 or -1 as an INT
QCO_ADD_NUM$3CDrops 2 NUMs, returns result as an NUM
QCO_SUB_NUM$3DDrops 2 NUMs, returns result as an NUM
QCO_MUL_NUM$3EDrops 2 NUMs, returns result as an NUM
QCO_DIV_NUM$3FDrops 2 NUMs, returns result as an NUM
QCO_POW_NUM$40Drops 2 NUMs, returns result as an NUM
QCO_UMIN_NUM$41Drops a NUM, returns result as an NUM
QCO_NOT_NUM$42Drops a NUM, returns 0 or -1 as an INT
QCO_AND_NUM$43Drops 2 NUMs, returns 0 or -1 as an INT
QCO_OR_NUM$44Drops 2 NUMs, returns 0 or -1 as an INT
QCO_LT_STR$45Drops 2 STRs, returns 0 or -1 as an INT
QCO_LTE_STR$46Drops 2 STRs, returns 0 or -1 as an INT
QCO_GT_STR$47Drops 2 STRs, returns 0 or -1 as an INT
QCO_GTE_STR$48Drops 2 STRs, returns 0 or -1 as an INT
QCO_NE_STR$49Drops 2 STRs, returns 0 or -1 as an INT
QCO_EQ_STR$4ADrops 2 STRs, returns 0 or -1 as an INT
QCO_ADD_STR$4BDrops 2 STRs, returns result as a STR

The compares drop whatever is on the stack and return an integer either TRUE(-1) or FALSE(0).

The string compares are case sensitive.

PERCENTAGE OPERATORS

These operators are only available on the LZ model range.

Internal NameOpStack
QCO_LT_PERC$CCDrops 2 FLTs, returns result as a FLT
QCO_GT_PERC$CDDrops 2 FLTs, returns result as a FLT
QCO_ADD_PERC$CEDrops 2 FLTs, returns result as a FLT
QCO_SUB_PERC$D0Drops 2 FLTs, returns result as a FLT
QCO_MUL_PERC$D1Drops 2 FLTs, returns result as a FLT
QCO_DIV_PERC$D2Drops 2 FLTs, returns result as a FLT

COMMAND OPERATORS

QCO_AT

Positions the cursor.

OP:$4C
OPL:AT
Para1:New X position (1 to 16)
Para2:New Y position (1 or 2)
Stack:Drops the two integers on the stack
Calls:DP$STAT
Errors:ER_FN_BA - Bad parameter if either parameter out of range.

Clears RTB_CRFL, the carriage return flag.


QCO_BEEP

Beeps with a frequency of 460800/(39+para2).

OP:$4D
OPL:BEEP
Para1:Integer duration in milliseconds
Para2:Integer period
Stack:Drops the two integers
Calls:BZ$TONE
Bugs:If para1 is negative BEEP returns immediately. Para2 is regarded as an unsigned word.

QCO_BREAK

Break the execution of OPL. Note that this is not equivalent to the OPL word BREAK.

OP:$26
Calls:UT$LEAV

QCO_CLS

Clears the screen. The cursor is homed to the top left.

OP:$4E
OPL:CLS
Stack:No effect
Calls:DP$CLRB

QCO_CURSOR

Set the cursor on or off.

OP:$4F
OPL:CURSOR ON, CURSOR OFF
Stack:No effect
Calls:DP$STAT

Gets byte after operator, sets or clears most significant bit of DPB_CUST.


QCO_ESCAPE

Enables or disables the ON/CLEAR key freeze and quit.

OP:$50
OPL:ESCAPE ON, ESCAPE OFF
Stack:Drops the integer on the stack

Gets byte after operator, sets or clears RTA_ESCF.


QCO_GOTO

Jump RTA_PC to a new location in the same procedure.

OP:$51
OPL:GOTO, BREAK, CONTINUE, ELSE
Stack:No effect

Adds word after the operator to RTA_PC. See QCO_BRA_FALSE.


QCO_OFF

Turns off the machine. Does not terminate language execution.

OP:$52
OPL:OFF
Stack:No effect
Calls:BT$SWOF

This is exactly the same state as when the machine is turned off at the top level. The drain on the battery is minimal.


QCO_OFF_TIM

Turns off the machine for a specified amount of seconds. Only available on the LZ model range.

OP:$D2
OPL:OFF n%
Stack:Drops the integer
Calls:BT$TOFF

Works like QCO_OFF but turns organiser on again after n% seconds. n% must be in the range 2-1600. Organiser wakes prematurely if an alarm is due.


QCO_ONERR

Set up error handling.

OP:$53
OPL:ONERR, ONERR OFF
Stack:No effect

The following word contains the offset to the address to jump to in the event of an error being detected. ONERR OFF is the same operator followed by a zero word. The ONERR address is saved in the procedure header.


QCO_PAUSE

If positive it pauses for that many 50 millisecond units, if negative it pauses for that many 50 millisecond units or until the first key press. If it is zero it waits for the next key press.

OP:$54
OPL:PAUSE
Stack:Drops the integer
Bugs:If a key is pressed it is not removed from the input buffer, so it should be read by a KEY or GET function.

Uses the 'SLP' processor instruction, so less power is used when PAUSEd compared to normal operation. It does however use more power than being switched off.


QCO_POKEB

Pokes a byte into memory.

OP:$55
OPL:POKEB
Para1:Address to write to
Para2:Byte to be written
Stack:Drops the two integers
Errors:ER_FN_BA - Bad parameter

Reports an error if para2 is not a byte. If the address is in the protected range $00 to $3F or $282 to $400 then it does nothing.


QCO_POKEW

Pokes a word into memory.

OP:$56
OPL:POKEW
Para1:Address to write to
Para2:Word to be written
Stack:Drops the two integers on the stack
Errors:ER_FN_BA - Bad parameter

If the address is in the protected range $00 to $3F or $282 to $400 then it does nothing.


QCO_RAISE

Generates an error condition.

OP:$57
OPL:RAISE
Stack:Drops the integer
Errors:ER_FN_BA - Bad parameter

If integer on the stack is not a byte it reports error. Otherwise it has exactly the same effect as if that error was generated. Errors generated by RAISE are handled in the normal way by ONERR.

Using this command and ONERR the programmer can completely take-over the handling and reporting of errors.

If the error is out of the range normally reported by the OS the message "*** ERROR ***" is reported.

RAISE 0 is special as it does not report an error.


QCO_RANDOMIZE

Set the seed of the random number generator. The sequence numbers generated by RND becomes repeatable.

OP:$58
OPL:RANDOMIZE
Stack:Drops the floating point number on the stack
Calls:FN$RAND

QCO_SPECIAL

Special operator used to vector to machine code.

OP:$25
OPL:See below
Stack:No effect

Vectors via the contents of the location RTA_1VCT to machine code. The machine code should return with the carry flag set to report an error.

If the ASCII value 1 is encountered in the OPL source code it is taken to be a SPECIAL call which returns an integer. A 2 is for a floating point return and 3 for a string. It is impossible to get these values into the source code from the editor, it must be generated by another program.


QCO_STOP

Stops executing the language.

OP:$59
OPL:STOP

Resets RTA_SP, zeroes the file buffers by calling AL_ZERO and leaves the language.


QCO_TRAP

Disables the reporting of any error arising from the execution of the following operator. Instead the error number is saved in RTB_EROR which can be read by the function ERR.

OP:$5A
OPL:TRAP
Stack:No effect

Clears RTB_EROR and sets the trap flag RTB_TRAP. The following operators can be used with TRAP:

 APPENDBACKCLOSE
 COPYCREATEDELETE
 ERASEEDITFIRST
 INPUTLASTNEXT
 OPENPOSITIONRENAME
 UPDATEUSE

If no error occurs these operators clear RTB_TRAP.

Most of these are file-related operator. The programmer will frequently either need to report errors arising from the operators himself or handle them in a discriminating way. For example:

                TRAP OPEN "B:XYZ",A,A$
                IF ERR
                  TRAP OPEN "C:XYZ",A,A$
                  IF ERR
                    CLS :PRINT "FILE XYZ NOT" :PRINT "FOUND"
                    BEEP 100,100 :GET :STOP
                  ENDIF
                ENDIF

INPUT and EDIT are different. TRAP changes the conditions under which they exit. "EDIT A$" will not exit on the ON/CLEAR key, "TRAP EDIT A$" will exit with RTB_EROR set to ER_RT_BK. When inputting a number without the TRAP option, the routine will not exit until a valid number is input; however with TRAP any input will be accepted and the corresponding error condition placed in RTB_EROR.

See QCO_INPUT_INT, QCO_INPUT_NUM, QCO_INPUT_STR, QCO_EDIT.

FILE OPERATORS

QCO_APPEND

Adds the current record buffer to the current file as a new record.

OP:$5B
OPL:APPEND
Stack:No effect
Errors:ER_RT_FC - file not open
Calls:FL$SETP, FL$RECT, FL$RSET, FL$WRIT
Bugs:If the current length of the current record is zero, it is automatically made non-zero by adding a TAB, the field delimiter.

The contents of the file buffer are saved at the end of the current device. The first byte of the buffer is the length of the buffer.


QCO_CLOSE

Closes the current file.

If several files are open it is unpredictable which will become current.
OP:$5C
OPL:CLOSE
Stack:No effect
Errors:ER_RT_FC - file not open
Calls:FL$SETP, FL$RECT, FL$RSET, AL$ZCEL
Bugs:After closing the file it looks for another file to make current.

CLOSE has no effect on the file itself, it checks that the file is open, clears the record type in RTT_FIL, and zeroes the two cells.


QCO_COPY

Copies a file from one device to another. If the target already exists the data is appended.

OP:$5D
OPL:COPY
Stack:Drops the names of the two files
Errors:ER_FL_NX - file does not exist
ER_PK_CH - changed pack
Calls:FL$COPY
Bugs:You cannot copy to the same device.

QCO_COPYW

Copies files from one device to another using wildcards. Only available on the LZ model range.

OP:$D3
OPL:COPYW
Stack:Drops the names of the two file specifications
Errors:ER_FL_NX - file does not exist
ER_PK_CH - changed pack
Calls:FL$WCPY
Bugs:You cannot copy to the same device.

QCO_CREATE

Creates a file.

OP:$5E
OPL:CREATE
Stack:Drops the name of the file to be created
Errors:ER_FL_EX - file already exists
ER_AL_NR - out of memory
Calls:FL$CRET, AL$GROW, FL$SETP, FL$RECT, FL$RSET, FL$READ

QCO_DELETE

Deletes a file.

OP:$5F
OPL:DELETE
Stack:Drops the name of the file to be deleted.
Errors:ER_FL_NX - file does not exist
ER_RT_FO - file open
Calls:FL$DELN

Checks that the file is not open. Deletes all records, starting with the first, and finally the file name record of the file.


QCO_DELETEW

Deletes files using wildcards. Only available on the LZ model range.

OP:$D4
OPL:DELETEW
Stack:Drops the specification of the files to be deleted.
Errors:ER_FL_NX - file does not exist
ER_RT_FO - file open
Calls:FL$DELN

See QCO_DELETE.


QCO_ERASE

Erases the current record of the current file.

OP:$60
OPL:ERASE
Stack:No effect
Errors:ER_RT_FC - file not open
ER_FL_EF - end of file
Calls:FL$ERAS, FL$SETP, FL$RECT, FL$RSET, FL$READ
Bugs:The current record becomes the record following the erased record. If, after the erase, FL$READ returns an 'END OF FILE', the length of the current record is set to zero and the current record number set to the number of records (as found by FL$SIZE) plus one.
'END OF FILE' error will be generated if already at the end of the file. This includes the case of a file with no records.

QCO_FIRST

Goes to the first record of the current file.

OP:$61
OPL:FIRST
Stack:No effect
Errors:ER_RT_FC - file not open
Calls:FL$SETP, FL$RECT, FL$RSET, FL$READ
Bugs:No error reported if there are no records.

QCO_LAST

Goes to the last record of the current file.

OP:$62
OPL:LAST
Stack:No effect
Errors:ER_RT_FC - file not open
Calls:FL$SIZE, FL$SETP, FL$RECT, FL$RSET, FL$READ
Bugs:No error reported if there are no records.

QCO_NEXT

Goes to the next record.

OP:$63
OPL:NEXT
Stack:No effect
Errors:ER_RT_FC - file not open
Calls:FL$NEXT, FL$READ
Bugs:No error reported if at the end of file. If FL$READ returns an "END OF FILE" error, the length of the current record is set to zero and the current record number set to the number of records (as found by FL$SIZE) plus one.

QCO_BACK

Steps back one record.

OP:$64
OPL:BACK
Stack:No effect
Errors:ER_RT_FC - file not open
Calls:FL$BACK
Bugs:No error reported if already on the first record.

QCO_OPEN

Open a file.

OP:$65
OPL:OPEN
Stack:Drop the name of the file.
Errors:ER_RT_FO - file open
Calls:FL$OPEN, FL$SETP, FL$RECT, FL$RSET, FL$READ

OPEN has exactly the same form as CREATE.


QCO_POSITION

Position at that record.

OP:$66
OPL:POSITION
Stack:Drops the integer
Errors:ER_RT_FC - file not open
Calls:FL$SETP, FL$RECT, FL$RSET, FL$READ
Bugs:If the FL$READ returns an 'END OF FILE', the length of the current record is set to zero and the current record number set to the number of records (as found by FL$SIZE) plus one.

QCO_RENAME

Renames a file.

OP:$67
OPL:RENAME
Stack:Drops the two file names
Errors:ER_RT_FO - file open
ER_FL_NX - file exists
ER_FL_NX - file does not exist
Calls:FL$RENM

Erases the file name record and writes a new one.


QCO_UDG

Defines an UDG. Only available on the LZ model range.

OP:$D6
OPL:UDG
Stack:Drops 9 integers
Calls:DP$UDG

QCO_UPDATE

Updates a record.

OP:$68
OPL:UPDATE
Stack:No effect
Errors:ER_RT_FC - file not open
Calls:FL$ERAS, FL$WRIT, FL$SETP, FL$RECT, FL$RSET, FL$READ
Bugs:If the APPEND fails, with 'PAK FULL' for example, the original record is already erased.

It deletes the current record in the current file and then APPENDs the contents of the buffer.


QCO_USE

Changes the current file.

OP:$69
OPL:USE
Stack:No effect
Errors:ER_TR_BL - bad logical name (logical name not in use)

Takes the byte following the operator and after checking it makes it the new current logical file. See logical file names.

OTHER OPERATORS

QCO_KSTAT

Set the shift state of the keyboard.

OP:$6A
OPL:KSTAT
Stack:Drops integer
Errors:ER_FN_BA - function argument error
Calls:KB$STAT

Use KSTAT to change the upper/lower alpha/numeric case:

1alpha, upper case (default setting)
2alpha, lower case
3numeric, upper case
4numeric, lower case

QCO_EDIT

Edits a string.

OP:$6B
OPL:EDIT
Stack:Drop the left side reference to string
Errors:ER_RT_BK - ON/CLEAR key pressed
ER_RT_FC - file not open
ER_RT_NF - field not found
ER_RT_RB - record too big
Calls:ED$EDIT

If the string to be edited is a field then the maximum length of the string is 252. Otherwise the maximum length allowed is the length of the string as defined in the LOCAL or GLOBAL statement. The string to be edited is copied into RTT_BUF. Once the string is edited it is assigned to the source. If the EDIT is preceded by TRAP then the edit will exit on the ON/CLEAR key with the error condition ER_RT_BK. The string remains unchanged. Before execution of this operator RTB_CRFL is tested and, if set, a carriage return is sent to the screen and the flag cleared.


QCO_INPUT_INT

Input an integer.

OP:$6C
OPL:INPUT
Stack:Drops the left side integer reference
Errors:ER_RT_BK - ON/CLEAR key pressed
ER_MT_IS - conversion to number failed
ER_RT_IO - integer overflow
ER_RT_FC - file not open
ER_RT_NF - field not found
ER_RT_RB - record too big
Calls:ED$EDIT

If the INPUT is preceded by TRAP then the input will exit on the ON/CLEAR key with the error condition ER_RT_BK. It will also exit if an invalid integer is input, e.g. 99999 or $1. If there is no TRAP then the INPUT will not exit on the ON/CLEAR key and invalid integers generate a '?' on the next line and the INPUT is repeated. Up to 6 characters, including leading spaces, are allowed. Before execution of this operator RTB_CRFL is tested and, if set, a carriage return is sent to the screen and the flag cleared.


QCO_INPUT_NUM

Inputs a floating point number.

OP:$6D
OPL:INPUT
Stack:Drops left side reference to floating point number
Errors:ER_RT_BK - ON/CLEAR key pressed
ER_MT_IS - conversion to number failed
ER_RT_IO - integer overflow
ER_RT_FC - file not open
ER_RT_NF - field not found
ER_RT_RB - record too big
Calls:ED$EDIT

If the INPUT is preceded by TRAP then the input will exit on the ON/CLEAR key with the error condition ER_RT_BK. It will also exit if an invalid floating point number is input, e.g. 999999999999999 or $1. If there is no TRAP then the INPUT will not exit on the ON/CLEAR key and invalid integers generate a '?' on the next line and the INPUT is repeated. Up to 15 characters, including leading spaces, are allowed. Before execution of this operator RTB_CRFL is tested and, if set, a carriage return is sent to the screen and the flag cleared.


QCO_INPUT_STR

Inputs a string.

OP:$6E
OPL:INPUT
Stack:Drops left side reference to string
Errors:ER_RT_FC - file not open
ER_RT_NF - field not found
ER_RT_RB - record too big
Calls:ED$EDIT

QCO_INPUT_STR is exactly equivalent to QCO_EDIT with an initial null string.


QCO_PRINT_INT

Prints an integer to the screen.

OP:$6F
OPL:PRINT
Stack:Drops the integer
Calls:UT$DISP
Bugs:If the number $FFFF is assigned to an integer and then it is printed it will be represented as -1.

Before execution of this operator RTB_CRFL is tested and, if set, a carriage return is sent to the screen and the flag cleared.


QCO_PRINT_NUM

Prints a floating point number to the screen.

OP:$70
OPL:PRINT
Stack:Drops the floating point number
Calls:UT$DISP

Before execution of this operator RTB_CRFL is tested and, if set, a carriage return is sent to the screen and the flag cleared. The format in which a number is displayed is integer, decimal or scientific in that order of precedence.


QCO_PRINT_STR

Print a string to the screen.

OP:$71
OPL:PRINT
Stack:Drops the string
Calls:UT$DISP

Before execution of this operator RTB_CRFL is tested and, if set, a carriage return is sent to the screen and the flag cleared.


QCO_PRINT_SP

Prints a space to the screen.

OP:$72
OPL:PRINT
Stack:No effect
Calls:UT$DISP

This operator is generated by use of the ',' separator in a PRINT statement. Before execution of this operator RTB_CRFL is tested and, if set, a carriage return is sent to the screen and the flag cleared.


QCO_PRINT_CR

Print a carriage return to the screen.

OP:$73
OPL:PRINT
Stack:No effect
Calls:UT$DISP

If a PRINT, INPUT or EDIT statement is not followed by a ';' or ',' then this operator is automatically inserted. It is not acted on immediately; it sets the flag RTB_CRFL. Before execution of this operator RTB_CRFL is tested and, if set, a carriage return is sent to the screen and the flag cleared. Note that if a carriage return results in scrolling the screen there is an automatic delay; the length of this delay is defined by DPW_DELY which is in 50 millisecond units, the default being 10.


QCO_LPRINT_INT

Sends an integer to the RS232.

OP:$74
OPL:LPRINT
Errors:ER_DV_NP - device missing
ER_DV_CS - device load error

Exactly as PRINT_INT, except the CR flag is not tested.


QCO_LPRINT_NUM

Send a floating point number to the RS232.

OP:$75
OPL:LPRINT
Errors:ER_DV_NP - device missing
ER_DV_CS - device load error

Exactly as PRINT_NUM, except the CR flag is not tested.


QCO_LPRINT_STR

Send a string to the RS232.

OP:$76
OPL:LPRINT
Errors:ER_DV_NP - device missing
ER_DV_CS - device load error

Exactly as PRINT_STR, except the CR flag is not tested.


QCO_LPRINT_SP

Send a space character to the RS232.

OP:$77
OPL:LPRINT
Errors:ER_DV_NP - device missing
ER_DV_CS - device load error

Exactly as PRINT_SP, except the CR flag is not tested.


QCO_LPRINT_CR

Send a carriage return to the RS232.

OP:$78
OPL:LPRINT
Errors:ER_DV_NP - device missing
ER_DV_CS - device load error

As PRINT_CR except it is acted on immediately.


QCO_RETURN

Return from a procedure.

OP:$79
OPL:RETURN
Stack:Unwinds the procedure

This operator follows the operator which stacks the return value. All procedures return a value. If no explicit value is returned then it will return integer zero for integer procedures, floating point zero for floating point procedures or a null string for string procedures.


QCO_RETURN_NOUGHT

For an integer procedure this is the default return.

OP:$7A
OPL:RETURN
Stack:Stack the integer zero and then unwind the procedure

Stacks default return value, then exactly the same as QCO_RETURN.


QCO_RETURN_ZERO

For an floating point procedure this is the default return.

OP:$7B
OPL:RETURN
Stack:Stack a floating point zero and then unwind the procedure

Stacks default return value, then exactly the same as QCO_RETURN.


QCO_RETURN_NULL

For a string procedure this is the default return.

OP:$7C
OPL:RETURN
Stack:Adds a null string and the unwinds the procedure

Stacks default return value, on the stack, then exactly the same as QCO_RETURN.


QCO_PROC

Call a procedure.

OP:$7D
OPL:procnam:
Stack:Initialises procedure
Errors:ER_RT_PN - procedure not found
ER_RT_NP - wrong number of parameters
ER_RT_UE - undefined external
ER_EX_TV - parameter type mis-match
ER_AL_NR - out of memory
ER_GN_BL - test explicitly for low battery error
Calls:PK$RBYT, PK$RWRD, PK$READ, DV$LKUP, DV$VECT

First checks to see if a language extension of that name has been booted into memory. If not it searches the 4 devices for an OPL procedure of the right name. It starts with the default device. So if the procedure called was on C: then it searches in the order C:, D:, A: and B:. If a language extension has been found (for example LINPUT) it calls the relevant vector and the device is then responsible for checking the parameters and handling the stack. See language extensions. If it is an OPL procedure the header information is read in and the memory required checked. The external references are then checked and the fixups on the strings and arrays performed. The Q code is then read in, and RTA_PC and RTA_SP are set to their new values.


QCO_BRA_FALSE

Branches if the integer on the stack is false.

OP:$7E
OPL:UNTIL, WHILE, IF, ELSEIF
Stack:Drop the offset

Adds the integer following the operator to RTA_PC if the value on the stack is zero.


QCO_ASS_INT

Assign an integer to a variable.

OP:$7F
OPL:=
Stack:Drops the integer and the integer reference
Errors:ER_RT_RB - field too big
ER_RT_FC - file not open
ER_RT_NF - field not found
ER_RT_RB - record too big

At the start of the operand the stack looks like:

      High memory             Address of integer variable
                              0 (field flag)
      Low memory              Integer
                      or:
      High memory             Field name
                              Logical file name (0,1,2 or 4)
                              1 (field flag)
      Low memory              Integer

If the assign is to a field, it checks that the file is open, checks the field name and saves the value. If not a field it simply saves the integer to the address.


QCO_ASS_NUM

Assigns a floating point number.

OP:$80
OPL:=
Stack:Drops the floating point number and the floating point reference
Errors:ER_RT_RB - field too big
ER_RT_FC - file not open
ER_RT_NF - field not found
ER_RT_RB - record too big

Exactly the same as QCO_ASS_INT except it handles floating point numbers.


QCO_ASS_STR

Assigns a string.

OP:$81
OPL:=
Stack:Drops the string and the string reference
Errors:ER_RT_RT - field too big
ER_LX_ST - string too long

Exactly the same as QCO_ASS_INT except it handles strings.


QCO_DROP_BYTE

Drops a byte off stack.

OP:$82
OPL:-
Stack:Drops byte

QCO_DROP_WORD

Drops a word off the stack.

OP:$83
OPL:-
Stack:Drops word

Used internally to drop unwanted results off the stack, for example a statement "GET" which translates into RTF_GET,QCO_DROP_WORD.


QCO_DROP_NUM

Drops a floating point number off the stack.

OP:$84
OPL:-
Stack:Drops a floating point number

Used internally to OPL when, for example, a floating point procedure returns a value that is not required.


QCO_DROP_STR

Drops a string off the stack.

OP:$85
OPL:-
Stack:Drops a string off the stack

Used internally to OPL when, for example, a string procedure returns a string that is not required.


QCO_INT_TO_NUM

Converts an integer into a floating point number.

OP:$86
OPL:-
Stack:Drops an integer, stacks a float
Calls:MT$BTOF
Bugs:Integers are always taken as signed. To make unsigned:
       A=I% :IF I%<0 :A=A+65536 :ENDIF

Used for automatic type conversion.


QCO_NUM_TO_INT

Converts a floating point number to integer.

OP:$87
OPL:-
Stack:Drops float, stacks integer
Errors:ER_RT_IO - integer overflow
Calls:IM$DINT, IM$FLOI
Bugs:Always rounds down, 3.9 becomes 3 and -3.9 becomes -4.

Used for automatic type conversion.


QCO_END_FIELDS

Indicates where the field names end.

OP:$88
OPL:OPEN, CREATE
Stack:No effect

Only used internally at the end of an OPEN or CREATE command.


QCO_RUN_ASSEM

Runs machine code immediately after operator.

OP:$89
OPL:-
Stack:No effect

Runs the code immediately after the operator as machine code. On return if there are no errors carry must be clear and the B register must be the number of bytes for RTA_PC to jump. If there is an error carry must be set and the B register should contain the number of the error to be reported. This cannot be generated from the editor.

INTEGER FUNCTIONS

These functions return integer values.

RTF_ADDR

Returns the address of a numeric variable.

OP:$8A
OPL:ADDR
Stack:Drops the 'left side' reference, stacks the address.
Bugs:Cannot deal with elements of arrays, though they may be easily calculated.

In the case of arrays ADDR returns the address of the first element which is immediately after the word giving the size of the array. So "PRINT PEEKW(ADDR(A%))" is exactly the same as "PRINT A%" and "PRINT PEEKW(ADDR(A%())) is the same as "PRINT A%(1)".


RTF_ASC

Returns the ASCII value of the first character of the string.

OP:$8B
OPL:ASC
Stack:Drops the string, stacks an integer
Bugs:If the string is zero length it returns zero.

RTF_CLOCK

Turns UDG clock on or off. Only available on the model LZ range.

OP:$D6
OPL:CLOCK
Stack:Drops an integer, stacks an integer
Calls:DP$CSET

RTF_DAY

Returns the current day of the month - in the range 1 to 31.

OP:$8C
OPL:DAY
Stack:Stack an integer

RTF_DAYS

Returns number of days since 1/1/1900 for a specified date. Only available on the model LZ range.

OP:$DD
OPL:DAYS
Stack:Drops 3 integers, stacks an integer
Calls:TM$NDYS

RTF_DISP

Displays a string, a record or the last string displayed, using cursor keys for viewing and waiting for any other key to exit.

OP:$8D
OPL:DISP
Para1:Integer:
 1 - displays para2
 0 - redisplays the last DISPed string (ignores para2)
-1 - displays the current record (ignores para2)
Para2:String to be displayed
Stack:Drops the two parameters, stacks the exit key as an integer.
Calls:UT$DISP
Bugs:In the case para1 is zero it displays the contents of RTT_BUF.
RTT_BUF is used by a number of other operand/operators, for instance by string adds.

The display used is the same as that used by FIND in the top level. Each field, delimited by a TAB character, is on a different line. There is no limit to the number of fields.


RTF_DOW

Returns day of the week of the given date (1...Monday). Only available on LZ model range.

OP:$D5
OPL:DOW
Stack:Drops 3 integers, stacks an integer

RTF_ERR

Returns the current error value.

OP:$8E
OPL:ERR
Stack:Stack the error number as an integer

When the language starts running the value of RTB_EROR is zero. If an error is encountered and handled by a TRAP or ONERR the value remains until the next error or a TRAP command.


RTF_FIND

Finds a string in the current file.

OP:$8F
OPL:FIND
Stack:Drops the search string, stacks the record number.
Calls:FL$FIND
Bugs:FIND does not do an automatic NEXT, the correct loop structure is:
                DO
                  IF FIND "ABC"
                    statement(s)
                  ENDIF
                  NEXT
                UNTIL EOF
If no record is found zero is returned and the current record remains the same as before the FIND.

RTF_FINDW

Finds a string in the current file using wildcards. Only available on LZ model range.

OP:$D8
OPL:FINDW
Stack:Drops the search string, stacks the record number.
Calls:FL$WFND
Bugs:See RTF_FIND.

RTF_FREE

Returns the amount of free memory.

OP:$90
OPL:FREE
Stack:Stack the resulting integer.

Calculates the amount of free memory by subtracting ALA_FREE from RTA_SP and then subtracting $100.


RTF_GET

Get a single character.

OP:$91
OPL:GET
Stack:Stack the character as an integer.
Calls:KB$GETK
Bugs:The ON/CLEAR key returns 1. It can be difficult to break out of a tight loop with a GET using the ON/CLEAR, Q keys. With perseverance it is normally possible.

If there is a key in the buffer it gets that key first. If no key is received the Organiser will turn itself off after the timeout.


RTF_HOUR

Returns the current hour of the day - in the range 0 to 23.

OP:$92
OPL:HOUR
Stack:Stack the number as an integer.

RTF_IABS

Does an ABS on an integer.

OP:$93
OPL:IABS
Stack:Leaves the integer on the stack.

Converts a negative integer to a positive integer. If ABS is used in place of IABS the result would be the same but the function would require two unnecessary type conversions. IABS is significantly faster than ABS.


RTF_INT

Converts a floating point number to an integer.

OP:$94
OPL:INT
Stack:Drops float, stacks integer
Errors:ER_RT_IO - integer overflow
Calls:IM$DINT, IM$FLOI
Bugs:Always rounds down, INT(3.9) is 3 and INT(-3.9) is -4.

Identical to QCO_NUM_TO_INT.


RTF_KEY

Returns any key in the input buffer. Zero if no key is waiting.

OP:$95
OPL:KEY
Stack:Stack the integer
Bugs:Except after an "ESCAPE OFF" statement, KEY cannot pick up the ON/CLEAR key.

RTF_LEN

Returns the length of the string.

OP:$96
OPL:LEN
Stack:Drops string, stacks the length as an integer

RTF_LOC

Locates one string in another, returns zero if not found.

OP:$97
OPL:LOC
Para1:String to be searched
Para2:String to locate
Stack:Drops the two strings, stacks the resulting position as an integer

RTF_MENU

Gives a menu of options.

OP:$98
OPL:MENU
Stack:Drops the string, stacks the exit item as an integer
Calls:MN_DISP
Errors:ER_RT_MU - menu error
ER_FN_BA - bad argument
Bugs:In the input string the menu items are delimited by commas. Before MN_DISP is called the string is converted to individual strings each terminated by a null word. It is possible to have too many items.
Don't have spaces or tabs as part of menu items, they can have unpredictable effects.

The normal input is a string with each menu item delimited by a comma. An item is selected either by a unique first letter or by positioning on that item and pressing the EXE key. If the menu exits by the ON/CLEAR key it returns zero.


RTF_MENUN

Gives a one-line menu of options. Only available on LZ model range.

OP:$D9
OPL:MENUN
Stack:Drops the integer and the string, stacks the exit item as an integer
Calls:MN_1DSP
Errors:ER_RT_MU - menu error
ER_FN_BA - bad argument
Bugs:See RTF_MENU.

RTF_MINUTE

Returns the current minute of the hour - in the range 0 to 59.

OP:$99
OPL:MINUTE
Stack:Stack the number as an integer.

RTF_MONTH

Returns the current month of the year - in the range 0 to 11.

OP:$9A
OPL:MONTH
Stack:Stack the number as an integer.

RTF_PEEKB

Peeks a byte at the given address.

OP:$9B
OPL:PEEKB
Stack:Drops the address, stacks the result as an integer

If the address is in the ranges $00-$3F and $282-$400 then it returns zero. These ranges are the processor registers and the custom chip's control addresses. The informed user may access these addresses via machine code.


RTF_PEEKW

Peeks a word at the given address.

OP:$9C
OPL:PEEKW
Stack:Drops the address, stacks the result as an integer

See the comments after RTF_PEEKB.


RTF_RECSIZE

Returns the size of the current record.

OP:$9D
OPL:RECSIZE
Stack:Stack the size as an integer.
Bugs:The maximum size of a record is 254, this includes the field separators.

See Records and Fields for more details.


RTF_SECOND

Returns the current second of the minute - in the range 0 to 59.

OP:$9E
OPL:SECOND
Stack:Stack the number as an integer.

RTF_WEEK

Returns the week number of a specified date. Only available on LZ model range.

OP:$DA
OPL:WEEK
Stack:Drops 3 integers, stacks the week number as an integer.
Calls:TM$WEEK

RTF_IUSR

Calls machine code.

OP:$9F
OPL:USR
Para1:Address of the machine code
Para2:The value to be passed in the D register
Stack:Drops the parameters, stacks the X register on return

RTF_SADDR

Returns the address of a string.

OP:$C9
OPL:ADDR
Stack:Stack the result

Returns the address of the length byte, the byte after the the maximum length. In the case of an array it returns the address of the length byte of the first element of the array. So "ADDR(A$())-2" is the address of the size the array (a word) and "ADDR(A$())-3" is the address of the maximum string length (a byte).


RTF_VIEW

View a string, or the last string viewed.

OP:$A0
OPL:VIEW
Para1:Line on which to view (1 or 2)
Para2:String to be viewed
Stack:Drops the parameters, stacks the exit character as an integer

If the string is null it re-displays the last string VIEWed (which is held in RTT_BUF).


RTF_YEAR

Returns the current year - in the range 0 to 99.

OP:$A1
OPL:YEAR
Stack:Stack the number as an integer

RTF_COUNT

Returns the number of records in the current file.

OP:$A2
OPL:COUNT
Stack:Stack the result as an integer
Calls:FL$SIZE

RTF_EOF

Returns TRUE if the position in the file is at the end of file. If the current record is the last record of the file, EOF returns FALSE.

OP:$A3
OPL:EOF
Stack:Stack result as an integer
Errors:ER_RT_FC - file not open
Bugs:If there are no records this returns true.

Returns TRUE if the current record buffer is zero. When OPL appends a record with zero length it adds a TAB ($09) character so that it never actually saves a null string.


RTF_EXIST

Returns TRUE is the file exists.

OP:$A4
OPL:EXIST
Stack:Drops string, stacks result
Calls:FL$OPEN

RTF_POS

Returns the current record number in the current file.

OP:$A5
OPL:POS
Stack:Stack the result
Calls:FL$SETP, FL$RECT, FL$RSET
Errors:ER_RT_FC - file not open
Bugs:If no records still return 1.

FLOATING POINT FUNCTIONS

These functions return a floating point value.

RTF_ABS

Does an ABS on a floating point number.

OP:$A6
OPL:ABS
Stack:Leaves the floating point number on the stack.
Calls:FN$ABS

RTF_ACOS

Returns the reverse cosine of the input in radians. Only available on LZ model range.

OP:$DB
OPL:ACOS
Stack:Drops the input floating point number, stacks the result
Calls:FN$ACOS

RTF_ASIN

Returns the reverse sinus of the input in radians. Only available on LZ model range.

OP:$DC
OPL:ASIN
Stack:Drops the input floating point number, stacks the result
Calls:FN$ASIN

RTF_ATAN

Returns the arctangent of the input in radians.

OP:$A7
OPL:ATAN
Stack:Drops the input floating point number, stacks the result
Calls:FN$ATAN
Bugs:Returns values in the range plus or minus pi/2

RTF_COS

Returns the cosine of the input, the input being in radians.

OP:$A8
OPL:COS
Stack:Drops the input floating point number, stacks the result
Calls:FN$COS
Errors:ER_FN_BA - bad argument if the absolute value is greater than 3141590.

RTF_DEG

Converts the input from radians to degrees.

OP:$A9
OPL:DEG
Stack:Drops the input floating point number, stacks the result
Calls:FN$DEG
Bugs:All this does is multiply the input by 57.29...

RTF_EXP

Returns the value of e raise to the specified power.

OP:$AA
OPL:EXP
Stack:Drops the input floating point number, stacks the result
Calls:FN$EXP
Errors:ER_FN_BA - bad argument if the absolute value is greater than 229.

RTF_FLT

Converts an integer to floating point format.

OP:$AB
OPL:FLT
Stack:Drops the input integer, stacks the result
Calls:MT$BTOF
Bugs:Integers are always taken as signed. To make unsigned:
       A=I% :IF I%<0 :A=A+65536 :ENDIF

Exactly the same effect as QCO_INT_TO_NUM.


RTF_INTF

Rounds a floating point number down to a whole number.

OP:$AC
OPL:INTF
Stack:Drops the input floating point number, stacks the result
Calls:IM$DINT, IM$FLOI

Essential to use INTF rather than INT if the number is out of the integer range.


RTF_LN

Returns the natural logarithm of the input.

OP:$AD
OPL:LN
Stack:Drops the input floating point number, stacks the result
Errors:ER_FN_BA - bad argument
Calls:FN$LN
Bugs:The input must be greater than 0.

RTF_LOG

Returns the base 10 logarithm of the input.

OP:$AE
OPL:LOG
Stack:Drops the input floating point number, stacks the result
Errors:ER_FN_BA - bad argument
Calls:FN$LOG
Bugs:The input must be greater than 0.

RTF_PI

Returns the number pi = 3.14159265359.

OP:$AF
OPL:PI
Stack:Stack the result
Calls:FN$PI

RTF_RAD

Converts the input number to radians. The inverse of DEG.

OP:$B0
OPL:RAD
Stack:Drops the input floating point number, stacks the result
Calls:FN$RAD
Bugs:All this does is divide the input by 57.29...

RTF_RND

Returns a pseudo-random number in the range 0(inclusive) to 1(exclusive).

OP:$B1
OPL:RND
Stack:Stack the result
Calls:FN$RND

RTF_SIN

Returns the sine of the input, the input being in radians.

OP:$B2
OPL:SIN
Stack:Drops the input floating point number, stacks the result
Calls:FN$SIN
Errors:ER_FN_BA - bad argument if the absolute value is greater than 3141590.

RTF_SQR

Returns the square root of the input.

OP:$B3
OPL:SQR
Stack:Drops the input floating point number, stacks the result
Calls:FN$SQRT
Errors:ER_FN_BA - bad argument if negative

RTF_TAN

Returns the tangent of the input, the input being in radians.

OP:$B4
OPL:TAN
Stack:Drops the input floating point number, stacks the result
Calls:FN$TAN
Bugs:At the the discontinuities in TAN, pi/2, 3*pi/2, etc, the values returned are either greater than 1E10 or less than -1E10.

RTF_VAL

Returns the input string as a number.

OP:$B5
OPL:VAL
Stack:Drops the input string, stacks the result
Errors:ER_MT_FL - conversion to number failed
Calls:MT$BTOF
Bugs:This routine insists that the whole string is used in the conversion, so VAL("12.34 ") generates an error. The null string also gives an error.

RTF_SPACE

Returns the amount of space on the current device.

OP:$B6
OPL:SPACE
Stack:Stack the result as floating point number
Calls:FL$SIZE
Errors:ER_RT_FC - file not open
Bugs:This may be longer than a word!


The following functions are only available on the LZ model range. They accept either

  • an array and an integer (number of items to inspect)
  • or a list of floats

as parameters.

On execution first the last two bytes are dropped from the stack. If the last byte is $01, the second last byte is the number of array items to be inspected and the array reference is dropped. If it is $00, the second last byte denotes the number of list items. These are dropped as well.

RTF_MAX

Returns the maximum of the specified array items or list.

OP:$DE
OPL:MAX
Stack:Drops the parameters (see above), stacks the result as float
Calls:FN$MAX

RTF_MEAN

Returns the mean of the specified array items or list.

OP:$DF
OPL:MEAN
Stack:Drops the parameters (see above), stacks the result as float
Calls:FN$MEAN

RTF_MIN

Returns the minimum of the specified array items or list.

OP:$E0
OPL:MIN
Stack:Drops the parameters (see above), stacks the result as float
Calls:FN$MIN

RTF_STD

Returns the standard deviation of the specified array items or list.

OP:$E1
OPL:STD
Stack:Drops the parameters (see above), stacks the result as float
Calls:FN$STD

RTF_SUM

Returns the sum of the specified array items or list.

OP:$E2
OPL:SUM
Stack:Drops the parameters (see above), stacks the result as float
Calls:FN$SUM

RTF_VAR

Returns the variance of the specified array items or list.

OP:$E3
OPL:VAR
Stack:Drops the parameters (see above), stacks the result as float
Calls:FN$VAR

STRING FUNCTIONS

RTF_DAYNAME

Converts an integer (0-7) to the day of the week. 1 returns "Mon" etc. Only available on the LZ model range.

OP:$E4
OPL:DAYNAME$
Stack:Drops the input integer, stacks the resulting string
Calls:TM$DNAM

RTF_DIR

Returns the name of the first/next file on a device.

OP:$B7
OPL:DIR$
Stack:Drops the input string, stacks the resulting string
Calls:FL$CATL
Errors:ER_FN_BA - bad argument

If the string is non-null it checks that it is of the form "A:" or "A". It splits out the device name and returns the first file name preceded by the device name. If the string is null it returns the next file name, on the device already specified. When there are no more file it returns a null string.


RTF_DIRW

Returns the name of the first/next file (of any type) on a device using wildcards. Only available on the LZ model range.

OP:$E5
OPL:DIRW$
Stack:Drops the input string, stacks the resulting string
Calls:FL$WCAT
Errors:ER_FN_BA - bad argument

See RTF_DIR.


RTF_CHR

Converts the integer input to a one character string.

OP:$B8
OPL:CHR$
Stack:Drops the input integer, stacks the resulting string
Errors:ER_FN_BA - bad argument if out of the range 0-255

RTF_DATIM

Returns the date-time string in the form: "TUE 04 NOV 1986 10:44:29"

OP:$B9
OPL:DATIM$
Stack:Stacks the resulting string

RTF_SERR

Returns the error string associated with the integer error number.

OP:$BA
OPL:ERR$
Stack:Drops the input integer, stacks the resulting string
Errors:ER_FN_BA - bad argument (if not a byte)
Calls:ER$LKUP
Bugs:Returns "*** ERROR ***" if less than the lowest recognised error number.

RTF_FIX

Returns the floating point number as a string with a fixed number of decimal places.

OP:$BB
OPL:FIX$
Para1:The floating point number
Para2:The require number of decimal places
Para3:The field size
Stack:Drops input parameters, stacks the resulting string
Calls:MT$FBDC
Bugs:If the number does not fit, '*'s are inserted

RTF_GEN

Returns the floating point number as a string. This is the same format as used by QCO_PRINT_NUM.

OP:$BC
OPL:GEN$
Stack:Drops the floating point number
Calls:MT$FBGN
Bugs:If the number does not fit, '*'s are inserted

The format in which the number is displayed is integer, decimal or scientific in that order of precedence.


RTF_SGET

Get a character and return it as a one character string.

OP:$BD
OPL:GET$
Stack:Stack the resulting string
Calls:KB$GETK
Bugs:The ON/CLEAR key returns a valid string. It can be difficult to break out of a tight loop with a GET$ using ON/CLEAR, Q keys. With perseverance it is normally possible.

RTF_HEX

Converts the integer into a hexadecimal string.

OP:$BE
OPL:HEX$
Stack:Drops input integer, stacks resulting string
Calls:UT$XTOB
Bugs:Input must be in the integer range.

RTF_SKEY

Returns any keys in the input buffer as a string. Returns the null string if no key is waiting.

OP:$BF
OPL:KEY$
Stack:Stack the string
Calls:KB$TEST, KB$GETK
Bugs:Except after an "ESCAPE OFF" statement, KEY cannot pick up the ON/CLEAR key. ON/CLEAR key normally suspends OPL execution.

RTF_LEFT

Returns the first n characters of the string.

OP:$C0
OPL:LEFT$
Para1:The string
Para2:Number of characters to keep
Stack:Drops the input parameters, stacks the resulting string
Bugs:If the string is shorter than the number of characters the entire string is returned.

RTF_LOWER

Converts the string to lower case.

OP:$C1
OPL:LOWER$
Stack:Drops the input string, stacks the result

RTF_MID

Returns the middle of a string.

OP:$C2
OPL:MID$
Para1:The string
Para2:The start character
Para3:The number of characters to be kept
Stack:Drops the input parameters, stacks the resulting string
Bugs:If there are insufficient characters the rest of the string is returned.

You can get all the characters after the n'th by the statement: MID$(a$,n,255)


RTF_MONTHNAME

Converts an integer (1-12) to the name of the month. 1 returns "Jan" etc. Only available on the LZ model range.

OP:$E6
OPL:MONTH$
Stack:Drops the input integer, stacks the resulting string
Calls:TM$MNAM
RTF_NUM

Converts a number to an integer string.

OP:$C3
OPL:NUM$
Para1:The floating point number
Para2:The maximum size of the string
Stack:Drops the input parameters, stacks the resulting string.
Calls:MT$FBIN
Bugs:If the number does not fit, '*'s are inserted The number does not have to be in usual integer range.

RTF_RIGHT

Returns the last n characters of a string.

OP:$C4
OPL:RIGHT$
Para1:The string
Para2:The number of characters wanted
Stack:Drops the input parameters, stacks the resulting string
Bugs:If the string is shorter than the number of characters the entire string is returned.

RTF_REPT

Repeats the string n times.

OP:$C5
OPL:REPT$
Para1:The string
Para2:The repeat count
Stack:Drops the integer and input string, stacks the result
Bugs:If the repeat count is zero no error is given.
Errors:ER_MT_FN - function argument error
ER_LX_ST - string too long

RTF_SCI

Returns the floating point number as a string in scientific form.

OP:$C6
OPL:SCI$
Para1:The floating point number
Para2:Number of decimal places required
Para3:Field width
Stack:Drops the floating point number, stacks the result
Calls:MT$FBEX
Bugs:If the number does not fit, '*'s are inserted

RTF_UPPER

Converts the string to upper case.

OP:$C7
OPL:UPPER$
Stack:Drops the input string, stacks the result

RTF_SUSR

Calls machine code.

OP:$C8
OPL:USR$
Para1:Address of the machine code
Para2:The value to be passed in the D register
Stack:Drops the parameters, stacks the string pointed at by the X register

INDEX OF OPERANDS

00    QI_INT_SIM_FP       0D    QI_LS_INT_SIM_FP     1A    QI_INT_FLD
01    QI_NUM_SIM_FP       0E    QI_LS_NUM_SIM_FP     1B    QI_NUM_FLD
02    QI_STR_SIM_FP       0F    QI_LS_STR_SIM_FP     1C    QI_STR_FLD
03    QI_INT_ARR_FP       10    QI_LS_INT_ARR_FP     1D    QI_LS_INT_FLD
04    QI_NUM_ARR_FP       11    QI_LS_NUM_ARR_FP     1E    QI_LS_NUM_FLD
05    QI_STR_ARR_FP       12    QI_LS_STR_ARR_FP     1F    QI_LS_STR_FLD
06    QI_NUM_SIM_ABS      13    QI_LS_NUM_SIM_ABS    20    QI_STK_LIT_BYTE
07    QI_INT_SIM_IND      14    QI_LS_INT_SIM_IND    21    QI_STK_LIT_WORD
08    QI_NUM_SIM_IND      15    QI_LS_NUM_SIM_IND    22    QI_INT_CON
09    QI_STR_SIM_IND      16    QI_LS_STR_SIM_IND    23    QI_NUM_CON
0A    QI_INT_SIM_IND      17    QI_LS_INT_SIM_IND    24    QI_STR_CON
0B    QI_NUM_SIM_IND      18    QI_LS_NUM_SIM_IND
0C    QI_STR_SIM_IND      19    QI_LS_STR_SIM_IND

INDEX OF OPERATORS

Operators that are only available on the LZ model range are marked by an asterisk.

25    QCO_SPECIAL         47    QCO_GT_STR          69    QCO_USE                CC*   QCO_LT_PERC
26    QCO_BREAK           48    QCO_GTE_STR         6A    QCO_KSTAT              CD*   QCO_GT_PERC
27    QCO_LT_INT          49    QCO_NE_STR          6B    QCO_EDIT               CE*   QCO_ADD_PERC
28    QCO_LTE_INT         4A    QCO_EQ_STR          6C    QCO_INPUT_INT          D0*   QCO_SUB_PERC
29    QCO_GT_INT          4B    QCO_ADD_STR         6D    QCO_INPUT_NUM          D1*   QCO_MUL_PERC
2A    QCO_GTE_INT         4C    QCO_AT              6E    QCO_INPUT_STR          D2*   QCO_DIV_PERC
2B    QCO_NE_INT          4D    QCO_BEEP            6F    QCO_PRINT_INT
2C    QCO_EQ_INT          4E    QCO_CLS             70    QCO_PRINT_NUM
2D    QCO_ADD_INT         4F    QCO_CURSOR          71    QCO_PRINT_STR
2E    QCO_SUB_INT         50    QCO_ESCAPE          72    QCO_PRINT_SP
2F    QCO_MUL_INT         51    QCO_GOTO            73    QCO_PRINT_CR
30    QCO_DIV_INT         52    QCO_OFF             74    QCO_LPRINT_INT
31    QCO_POW_INT         53    QCO_ONERR           75    QCO_LPRINT_NUM
32    QCO_UMIN_INT        54    QCO_PAUSE           76    QCO_LPRINT_STR
33    QCO_NOT_INT         55    QCO_POKEB           77    QCO_LPRINT_SP
34    QCO_AND_INT         56    QCO_POKEW           78    QCO_LPRINT_CR
35    QCO_OR_INT          57    QCO_RAISE           79    QCO_RETURN
36    QCO_LT_NUM          58    QCO_RANDOMIZE       7A    QCO_RETURN_NOUGHT
37    QCO_LTE_NUM         59    QCO_STOP            7B    QCO_RETURN_ZERO
38    QCO_GT_NUM          5A    QCO_TRAP            7C    QCO_RETURN_NULL
39    QCO_GTE_NUM         5B    QCO_APPEND          7D    QCO_PROC
3A    QCO_NE_NUM          5C    QCO_CLOSE           7E    QCO_BRA_FALSE
3B    QCO_EQ_NUM          5D    QCO_COPY            7F    QCO_ASS_INT
3C    QCO_ADD_NUM         5E    QCO_CREATE          80    QCO_ASS_NUM
3D    QCO_SUB_NUM         5F    QCO_DELETE          81    QCO_ASS_STR
3E    QCO_MUL_NUM         60    QCO_ERASE           82    QCO_DROP_BYTE
3F    QCO_DIV_NUM         61    QCO_FIRST           83    QCO_DROP_WORD
40    QCO_POW_NUM         62    QCO_LAST            84    QCO_DROP_NUM
41    QCO_UMIN_NUM        63    QCO_NEXT            85    QCO_DROP_STR
42    QCO_NOT_NUM         64    QCO_BACK            86    QCO_INT_TO_NUM
43    QCO_AND_NUM         65    QCO_OPEN            87    QCO_NUM_TO_INT
44    QCO_OR_NUM          66    QCO_POSITION        88    QCO_END_FIELDS
45    QCO_LT_STR          67    QCO_RENAME          89    QCO_RUN_ASSEM
46    QCO_LTE_STR         68    QCO_UPDATE

INDEX OF FUNCTIONS

Functions that are only available on the LZ model range are marked by an asterisk.

8A    RTF_ADDR            A0    RTF_VIEW            B6    RTF_SPACE              D6*    RTF_CLOCK
8B    RTF_ASC             A1    RTF_YEAR            B7    RTF_DIR                D7*    RTF_DOW
8C    RTF_DAY             A2    RTF_COUNT           B8    RTF_CHR                D8*    RTF_FINDW
8D    RTF_DISP            A3    RTF_EOF             B9    RTF_DATIM              D9*    RTF_MENUN
8E    RTF_ERR             A4    RTF_EXIST           BA    RTF_SERR               DA*    RTF_WEEK
8F    RTF_FIND            A5    RTF_POS             BB    RTF_FIX                DB*    RTF_ACOS
90    RTF_FREE            A6    RTF_ABS             BC    RTF_GEN                DC*    RTF_ASIN
91    RTF_GET             A7    RTF_ATAN            BD    RTF_SGET               DD*    RTF_DAYS
92    RTF_HOUR            A8    RTF_COS             BE    RTF_HEX                DE*    RTF_MAX
93    RTF_IABS            A9    RTF_DEG             BF    RTF_SKEY               DF*    RTF_MEAN
94    RTF_INT             AA    RTF_EXP             C0    RTF_LEFT               E0*    RTF_MIN
95    RTF_KEY             AB    RTF_FLT             C1    RTF_LOWER              E1*    RTF_STD
96    RTF_LEN             AC    RTF_INTF            C2    RTF_MID                E2*    RTF_SUM
97    RTF_LOC             AD    RTF_LN              C3    RTF_NUM                E3*    RTF_VAR
98    RTF_MENU            AE    RTF_LOG             C4    RTF_RIGHT              E4*    RTF_DAYNAME
99    RTF_MINUTE          AF    RTF_PI              C5    RTF_REPT               E5*    RTF_DIRW
9A    RTF_MONTH           B0    RTF_RAD             C6    RTF_SCI                E6*    RTF_MONTHNAME
9B    RTF_PEEKB           B1    RTF_RND             C7    RTF_UPPER
9C    RTF_PEEKW           B2    RTF_SIN             C8    RTF_SUSR
9D    RTF_RECSIZE         B3    RTF_SQR             C9    RTF_SADDR
9E    RTF_SECOND          B4    RTF_TAN
9F    RTF_IUSR            B5    RTF_VAL

EXAMPLES

In these examples all values are given in hexadecimal; word values are given as 4 digits, bytes as 2 digits each one separated by a space. If values are undefined they are written as **.

EXAMPLE 1

Source code:

                EX1:
                LOCAL A$(5)
                A$="ABC"

The Q code header is:

High memory     0009            size of the variables on stack
                000A            length of Q code
                00              number of parameters
                                  type of parameter
                0000            size of global area
                                  global name
                                  global type
                                  offset
                0000            size of externals
                                  external name
                                  external type
                0003            bytes of string fix-ups
                FFF7              string fix-up offset (from FP)
                05                max length of string
Low memory      0000            bytes of array fix-ups
                                  array fix-up offset (from FP)
                                  size of array

The Q code is:

                0F FFF8         QI_LS_STR_SIM_FP
                24              QI_STR_CON
                03 41 42 43     "ABC"
                81              QCO_ASS_STR
                7B              QCO_RETURN_ZERO

If this program is run on a CM the stack looks like:

        Initially           Left Side   Constant    Assign      On Return
3EFF    '1'                 '1'         '1'         '1'         '1'
3EFE    'X'                 'X'         'X'         'X'         'X'
3EFD    'E'                 'E'         'E'         'E'         'E'
3EFC    ':'                 ':'         ':'         ':'         ':'
3EFB    'A'                 'A'         'A'         'A'         'A'
3EFA    05                  05          05          05          05
3EF9    00   - Top proc     00          00          00          00
3EF8    00   - No. paras    00          00          00          00
3EF6    3EF9 - Return PC    3EF9        3EF9        3EF9        3EF9
3EF4    0000 - ONERR        0000        0000        0000        0000
3EF2    3EDB - BASE SP      3EDB        3EDB        3EDB        3EDB
3EF0    0000 - FP           0000        0000        0000        0000
3EEE    3EEE - Global table 3EEE        3EEE        3EEE        3EEE
3EED    00                  00          00          00          00
3EEC    00                  00          00          00          00
3EEB    00                  00          'C'         'C'         'C'
3EEA    00                  00          'B'         'B'         'B'
3EE9    00                  00          'A'         'A'         'A'
3EE8    00                  00          03          03          03
3EE7    05                  05          05          05          05
3EE6    **                  **          **          **          **
3EE5    **                  **          **          **          **
3EE4    QCO_RETURN_ZERO    7B           7B          7B          7B
3EE3    QCO_ASS_STR         81          81          81          81
3EE2    'C'                 'C'         'C'         'C'         'C'
3EE1    'B'                 'B'         'B'         'B'         'B'
3EE0    'A'                 'A'         'A'         'A'         'A'
3EDF    03                  03          03          03          03
3EDE    QI_STR_CON          24          24          24          24
3EDC    FFF8                FFF8        FFF8        FFF8        FFF8
3EDB    QI_LS_STR_SIM_FP    0F          0F          0F          0F
3EDA    **                  3EE8        3EE8        **          00
3ED9    **                  05          05          **          00
3ED8    **                  00          00          **          00
3ED7    **                  **          'C'         **          00
3ED6    **                  **          'B'         **          00
3ED5    **                  **          'A'         **          00
3ED4    **                  **          03          **          00
3ED3    **                  **          **          **          00
3ED2    **                  **          **          **          00

FP      3EF0                3EF0        3EF0        3EF0
PC      3EDB                3EDE        3EE3        3EE4
SP      3EDB                3ED8        3ED4        3EDB

EXAMPLE 2

When a file is created the operator QCO_CREATE is followed by the logical name to use and the field type and names. The list is terminated by the operator QCO_END_FIELDS.

For example:

                CREATE "B:ABC",B,AAA$,B%,CC

is translated as the Q code:

                24                      QI_STR_CON
                05 42 3A 41 42 43       "B:ABC"
                5E                      QCO_CREATE
                01                      Logical name B
                02                      Type string
                04 41 41 41 24          "AAA$"
                00                      Type integer
                02 42 25                "B%"
                01                      Type floating point
                02 43 43                "CC"
                88                      QCO_END_FIELDS

EXAMPLE 3

                RECURS:(I%)
                IF I%
                  RECURS:(I%-1)
                ENDIF

Looks like this on the stack:

        Address         Contents        Description

        3D5A            0010            Parameter
        3D59            00              Parameter type
        3D58            01              Number of parameters
        3D57            41              Device A
        3D55            3D6D            Return RTA_PC
        3D53            0000            ONERR address
        3D51            3D29            BASE SP
        3D4F            3D82            Previous FP
        3D4D            3D4D            Globals start address
        3D4B            3D5A            Indirect address to parameter
        3D49            **
        3D48            7B              QCO_RETURN_ZERO
        3D47            84              QCO_DROP_NUM
        3D40            "RECURS"
        3D3F            7D              QCO_PROC
        3D3E            01
        3D3D            20              QCO_STK_LIT_BYTE
        3D3C            00
        3D3B            20              QCO_STK_LIT_BYTE
        3D3A            2E              QCO_SUB_INT
        3D38            0001
        3D37            22              QI_INT_CON
        3D35            FFFC
        3D34            07              QI_INT_SIM_IND
        3D32            001B
        3D31            7E              QCO_BRA_FALSE
        3D2F            FFFC
        3D2E            07              QI_INT_SIM_IND
        3D2C            000F            Parameter for next call
        3D2B            00              parameter type
        3D2A            01              parameter count

Note that the top 4 byte and the bottom 4 bytes are almost identical,  this
is shown at the point where the procedure is about to be invoked:

        RTA_PC          3D3F
        RTA_SP          3D2A
        RTA_FP          3D4F

EXAMPLE 4

Source code:

                EX4:(PPP$)
                LOCAL A$(5)
                GLOBAL B,C%(3),D$(5)
                J$=PPP$

The Q code header is:

                0035            size of the variables on stack
                0008            size of Q code length
                01              number of parameters
                02                type of parameter
                0011            size of global area
                01 42             global name
                01                global type
                FFE1              offset
                02 43 25          global name
                03                global type
                FFD9              offset
                02 44 24          global name
                02                global type
                FFD3              offset
                0004            bytes of externals
                02 4A 24          external name
                02                external type
                0006            bytes of string fix-ups
                FFCB              string fix-up offset (from FP)
                05                max length of string
                FFD2              string fix-up offset (from FP)
                05                max length of string
                0004            bytes of array fix-ups
                FFD9              array fix-up offset (from FP)
                0003              size of array

The Q code is:

                16 FFE9         QI_LS_STR_SIM_IND
                09 FFEB         QI_STR_SIM_IND
                81              QCO_ASS_STR
                7B              QCO_RETURN_ZERO

If this program is run on a CM from the procedure:

                XXX:
                GLOBAL J$(3)
                EX4:("RST")

The stack looks like:

        3EFA            "A:XXX"
        3EF9            00                      Number of parameters
        3EF8            00                      Top procedure
        3EF6            3EF9                    Return PC
        3EF4            0000                    ONERR address
        3EF2            3ED1                    BASE SP
        3EF0            0000                    FP
        3EEE            3EE8                    Start of global table
        3EEC            3EE4                    Address of global
        3EEB            02                      Global type
        3EE8            "J$"                    Global name
        3EE3            03 00 00 00 00          Global J$
        3EE1            **
        3EE0            7B                      QCO_RETURN_ZERO
        3EDF            84                      QCO_DROP_NUM
        3EDB            "EX4"
        3EDA            7D                      QCO_PROC
        3ED8            20 01                   QI_STK_LIT_BYTE
        3ED6            20 02                   QI_STK_LIT_BYTE
        3ED2            "RST"
        3ED1            24                      QI_STR_CON
        3ECD            "RST"                   Parameter
        3ECC            02                      Parameter type
        3ECB            01                      Number of parameters
        3ECA            00                      Device A:
        3EC8            3EDA                    Return PC
        3EC6            0000                    ONERR
        3EC4            3E83                    BASE SP
        3EC2            3EF0                    FP
        3EC0            3EAF                    Start global table
        3EBE            3E95
        3EBD            02
        3EBA            02 44 24                Global D$
        3EB8            3E9B
        3EB7            03
        3EB4            02 43 25                Global C%()
        3EB2            3EA3
        3EB1            01
        3EAF            01 42                   Global B
        3EAD            3ECD                    Indirection to PPP$
        3EAB            3EE4                    Indirection to J$
        3EA3            00 00 00 00 00 00 00 00         GLOBAL B
        3E9B            00 03 00 00 00 00 00 00         GLOBAL C%()
        3E94            05 00 00 00 00 00 00            GLOBAL D$
        3E8D            05 00 00 00 00 00 00            LOCAL A$
        3E8B            **
        3E8A            7B                      QCO_RETURN_ZERO
        3E89            81                      QCO_ASS_STR
        3E87            FFEB
        3E86            09                      QI_STR_SIM_IND
        3E84            FFE9
        3E83            16                      QI_LS_STR_SIM_IND

When running EX4 the offset FFE9 is added to RTA_FP (3EC2) to give 3EAB.
The address at 3EAB is 3EE4 which is the address of the global J$. This address with a non-field flag is stacked. Similarly FFEB is added to RTA_FP to give 3EAD, which contains the address 3ECD, the address of the
parameter PPP$.

EXAMPLE 5

Source code:

                TOP:
                PRINT ABC:(GET)
                GET
                ABC:(N%)
                RETURN(N%*N%)

At the point when ABC: has just been called the stack looks like:

3EFA            "A:TOP"
3EF9            00              NO. of parameters
3EF8            00              Top procedure
3EF6            3EF9            Return PC
3EF4            0000            ONERR address
3EF2            3EDD            BASE SP
3EF0            0000            FP
3EEE            3EEE            Global table
3EEC            **
3EEB            7B              QCO_RETURN_ZERO
3EEA            83              QCO_DROP_WORD
3EE9            91              RTF_GET
3EE8            73              QCO_PRINT_CR
3EE7            70              QCO_PRINT_NUM
3EE3            "ABC"
3EE2            7D              QCO_PROC
3EE0            20 01           QI_STK_LIT_BYTE
3EDE            20 00           QI_STK_LIT_BYTE
3EDD            91              RTF_GET
3EDB            0020
3EDA            00              Integer
3ED9            01              No. parameters
3ED8            41              Device A:
3ED6            3EE2            Return PC
3ED4            0000            ONERR
3ED2            3EC1            BASE SP
3ED0            3EF0            FP
3ECE            3ECE            global table
3ECC            3EE4            Address of N%
3ECA            **
3EC9            79              QCO_RETURN
3EC8            86              QCO_INT_TO_NUM
3EC7            2F              QCO_MUL_INT
3EC4            07 FFF7         QI_INT_SIM_IND
3EC1            07 FFF7         QI_INT_SIM_IND
3EBF            0020                    0400                    0300
3EBD            0020                    **                      1024
3EBB            **                      **                      0000
3EB9            **                      **                      0000

PC              3EC7                    3EC8                    3EC9
 
 
first previous   next top