1. Home /
2. Psion II /
3. QCodes

Translated Procedures and QCodes

This document contains a description of a translated OPL procedure. A procedure is translated (i.e. compiled) into QCode, which is a byte code that can be executed by the Psion Organiser.

1. Variables 2. Language Stack 3. The procedure file format 4. Example QCode Header 5. QCode 6. QCode Examples 7. LNO files

1. Variables

Format of variables

Integer Variable

Float Variable

String Variable

Integer Array Variable

Float Array Variable

String Array Variable

2. Language Stack

When a procedure is run, it is copied from whatever pack it is on into memory (even if it is on pack A:). It is placed on the language stack, which is an area of memory that grows downwards from the address given in the bta_sbas system variable ($2065/66). The lowest address currently in use by the stack is given by the language stack pointer rta_sp ($A5/A6).

When a procedure is placed on the language stack, it will have the following format:

The global variable name table contains all the information about the global variables declared in this procedure. If, later on, some procedure is called and loaded that uses global variables declared elsewhere, then the stack is examined to see if those variables have been declared in previously loaded procedures.

The parameters and externals (those global variables declared in other procedures) only need 2 bytes of storage space, which contains the memory address of the location somewhere highter up the language stack where the value of the variable is actually stored. Global variables (declared in this procedure) and local variables are given the amount of space listed in the previous section.

3. The procedure file format

A procedure file is a binary file of type $83, as described in the file formats document. Its binary data block has the following format:

When a procedure is loaded, VVVV bytes are reserved on the stack. This is partially filled by a copy of the global variable name table (after checking that these names have not been defined in the name table of any previous procedure on the stack). Below that is the space reserved for variables. The addresses of parameters and externals are filled in (the latter by looking through the global variable name tables of previous procedures). The rest of the variable storage is filled with zeroes, except for the array lengths and maximum string lengths. These are filled in by using the data in the two fixup tables.

The addresses in the fixup tables and the addresses of variables in the global variable name table and in the QCode block are all relative to the top of the part of the stack reserved for the variables of the procedure. The variables are referred to by their offset from the top of this variable storage space. If no globals were defined (so the global variable name table would just consist of the length word 0000) then the first variable would have the offset address $0000-2-x where x is the space needed by the variable. An integer would therefore have offset address $FFFC.

4. Example QCode Header

The following example procedure uses all possible types of variable.

TEST:(P1,P2%,P3$) LOCAL L1,L2%,L3$(5) LOCAL L4(4),L5%(5),L6$(6,12),L7% GLOBAL G1,G2%,G3$(13) GLOBAL G4(4),G5%(5),G6$(6,14),G7% REM rest of code, including use of the following externals PRINT E1;E2%;E3$ PRINT E4(4);E5%(5);E6$(6)

The translated procedure will have the following header data:

The variable storage area used by the program will look as follows:

FFFE-FF Global variable name table length (will contain 002F) FFCF-FD Global variable name table, of length 002F, exact copy of the above. FFCD-CE P1 Parameters and externals use 2 bytes each FFCB-CC P2% FFC9-CA P3$ FFC7-C8 E1 FFC5-C6 E2% FFC3-C4 E3$ FFC1-C2 E4() FFBF-C0 E5%() FFBD-BE E6$() FFBB-BC L5%() FFB3-BA G1 Float uses 8 bytes FFB1-B2 G2% Integer uses 2 bytes FFA3-B0 G3$ String uses 2+maxStrLen bytes, but maxStrLen value stored in preceding byte FFA2 Maximum string length of G3$ FF80-A1 G4() float array uses 2+8*arrLen bytes FF74-7F G5%() integer array uses 2+2*arrLen bytes FF18-73 G6$() String array uses 3 + (1+maxStrLen)*arrLen, but maxStrLen value stored in preceding byte FF17 Maximum string length of G6$() elements FF15-16 G7% FF0D-14 L1 FF0B-0C L2% FF05-0A L3$ FF04 Maximum string length of L3$ FEE2-03 L4() FED6-E1 L5%() FE86-D5 L6$() FE85 Maximum string length of L6$() elements

5. QCode

The instructions in the procedure are translated into qcode. Almost every keyword in OPL (functions and statements) is translated into a single code byte. When such a qcode byte is executed it will gather its input by popping whatever arguments it needs from the stack, and possibly read some data bytes that immediately follow the qcode instruction byte. After its work is done, it may push a single resulting value back onto the stack.

Abbreviation for bytes following the QCode byte:

Abbreviation for stack pushes/pops:

For example, PRINT "O"; is translated into QCode consisting of a code to push a string literal onto the stack, immediately followed by the string literal "O", followed by the code for a print instruction.

PRINT "O"; 24 01 4F 71

The expression A%+1, where A% is a locally declared variable (local or global), is translated into QCode consisting of a code to push a locally declared integer variable to the stack, followed by the address of that variable (as an offset into the variable storage area), a code to push an integer followed by the literal integer 1, and finally a code to add two integers.

A%+1 00 FFFC 22 0001 2D

The address of the variable will be different if the procedure declares any global variables, parameters, uses any external variables, or declares any other variables before it declares A%.

If A% were an external variable, i.e. a parameter or a global variable declared in a previous procedure, then the expression A%+1 would be translated almost the same, except that the code to push an external integer variable to the stack is used instead. The rest is the same.

A%+1 07 FFFC 22 0001 2D

If a function is used as a statement, then its return value is explicitly removed from the stack afterwards. For example, if GET is used as a statement, then it is translated to the code for the GET function, followed by the code to drop an integer from the stack.

If at any point a float is needed but there is instead an integer on the stack (or vice versa), a code that does that conversion is is used. For example the expression ATAN(1) is translated to QCode consisting of a code to push a literal integer onto the stack followed by the integer 0001, then a code to convert an integer to a float, and finally the code for the ATAN function.

ATAN(1) 22 0001 86 A7

The only QCodes for flow control commands are branch-if-false (code 7E) and goto (code 51). There are no QCodes specific to the keywords, IF/ELSEIF/ELSE/ENDIF, WHILE/ENDWH, DO/UNTIL, or BREAK/CONTINUE, as these can all be expressed using only goto and branch-if-false. The distance to jump is given by the two bytes after the instruction. This distance is measured relative to the start of those two bytes, so a distance of 0002 would jump to the immediately following instruction, effectively doing nothing at all, whereas a distance of 0003 would skip over one byte. The distance can be negative, so a jump of distance FFFF is an infinite loop.

If the procedure does not end in an explicit RETURN statement, then it will be compiled just as if there were a bare RETURN statement there. The qcode will therefore always end with one of the qcode instructions 7A, 7B, or 7C, depending on the name of the procedure.

Procedures that have been translated for use on the 4-line LZ model have QCode that starts with the bytes 59 B2. The first byte is the code for the STOP command, so that if it is executed on a 2-line machine it will stop. The second byte is the code for the SIN function. No valid source program could ever produce these two codes after each other, so if the LZ encounters them at the start of the program, it can safely assume that it is a procedure meant for the LZ model and start execution at the next byte. Note that the two bytes form a neat pun for Stop Sign.

6. QCode Examples

This somewhat bogus example shows how flow control structures are translated into qcode.

TEST: IF 1 PRINT ENDIF IF 2. PRINT ELSE PRINT ENDIF IF 3 PRINT ELSEIF 4 PRINT ENDIF IF 5 PRINT ELSEIF 6 PRINT ELSE PRINT ENDIF WHILE 7 PRINT BREAK PRINT CONTINUE PRINT ENDWH DO PRINT BREAK PRINT CONTINUE PRINT UNTIL 8

This example shows how all the different types of variable are handled.

TEST2:(P1,P2%,P3$) LOCAL L1,L2%,L3$(5) LOCAL L4(4),L5%(5),L6$(6,12),L7% GLOBAL G1,G2%,G3$(13) GLOBAL G4(4),G5%(5),G6$(6,14),G7% PRINT "PPP";P1;P2%;P3$ PRINT "LLL";L1;L2%;L3$ PRINT "LL";L4(4);L5%(5);L6$(6) PRINT "GGG";G1;G2%;G3$ PRINT "GG";G4(4);G5%(5);G6$(6) PRINT "EEE";E1;E2%;E3$ PRINT "EE";E4(4);E5%(5);E6$(6) L1=234 L2%=345 L3$="BCD" L4(2)=345 L5%(3)=456 L6$(4)="CDE" G1=12 G2%=23 G3$="DEF" G4(3)=34 G5%(4)=4 G6$(5)="EFG" E1=45 E2%=56 E3$="FGH" E4(4)=67 E5%(5)=78 E6$(6)="GHI"

7. LNO files

The Organiser Developer kit contains an emulator ORG2.EXE. This emulator allows you to translate, run, and debug OPL procedures. When it translates a procedure, it produces a file with the file extension .LNO, which contains the translated result, similar to an object-only .OB3 file.

If the procedure is translated in the emulator while its DEBUG mode is OFF, then the LNO file is virtually the same as an OB3 file of the same program would be. It differs only in the following aspects:

• The file type is FE instead of 83, i.e. the last byte of the 6-byte file header is FE rather than 83.
• It has no source code block.
• The length word of the file (the fourth and fifth byte of the 6-byte file header) is two less than the length of the OB3 file would be, because it has no source code block at all instead of merely an empty one.
• Every two-byte integer within the qcode and the qcode header is stored little-endian, i.e. low byte followed by high byte.
• It may have some padding at the end, such as FFFF in the place where the empty source code block would be.

Consider for example, the following small test procedure:

TEST: LOCAL A% A%=1234 AT 4,1 :PRINT A% GET

Here are the OB3 and non-debug LNO files produced by translating the procedure.

An LNO file that is created while DEBUG mode is ON will have extra debugging information incorporated into the file, such as the names of all the local variables and parameters, as well as the line number of each statement.

The QCodes CA and CB are used to encode some of this information. The first QCode after the QCode header (or after the stop sign if present) is CA, which is followed by a string literal containing the procedure name, followed by a length word which is 4 plus the length of the remaining QCode. Every section of QCode that represents a single source code statement is preceded by 5 bytes - the CB QCode, a word containing the source line number of the statement (where the top line containing the procedure name is line 1) and the column number of the statement (where column 0 means the start of the line).

Information about the variables is stored after the QCode block, where in an OB3 file the source code block would be. It starts with a word containing the number of variables that follow, and then data for each variable in turn. That data consists of:

1. A string containing the variable's name.
2. A word containing the address of the variable (the usual offset into the variable space)
3. A byte which is 00 for external variables, 01 for parameter variables, 02 for global variables, and 03 for local variables.
4. A variable type byte - which is the usual 00 for an integer, 01 for a floating point, 02 for a string, 03 for an integer array, 04 for a floating point array, and 05 for a string array.

The previous TEST program translated in DEBUG mode is as follows: