Using BASIC String/Arrays in Machine Code Programs

You said that you needed to locate a specific variable in the BASIC VARS area of memory in order to use the data in a machine code program. The following procedure will allow the transfer of the location and size of a simple variable to a BASIC program. If you want to locate a variable which has not been fixed in size by a DIM statement, insert the following lines at appropriate line numbers in your program:

1000 POKE 23728, CODE"W"
1010 LET X=USR 23296: REM This is the start of printer buffer
1020 LET SIZE=PEEK (X+1)+256*PEEK (X+2)
1030 LET START=X+3

Line 1000 puts the letter code for the variable into a convenient storage location, in this case into an unused slot in the normal system variables table. Line 1010 accesses the machine code to locate the variable address in memory. In this case I have put the 28 byte routine into the printer buffer, but any convenient location could be used since the code is completely relocatable. On return from the MC routine, the variable X contains the address of the identifier for the W$ variable. Line 1020 reads out the current length of the W$ variable and line 1030 gets the starting address of the actual characters in the variable. If desired, these values may be POKEd into a convenient memory location for subsequent access by whatever MC routine you intend to use to manipulate the data. Here is the machine code which locates the starting address of the W$ (or any other) simple variable:

ADDRESS         OPCODE  INSTRUCTION    COMMENTS

5B00            3AB05C  LD A,(5CB0)    Get character code
5B03            CBAF    RES 5,A        Insure upper case char.
5B05            2A4B5C  LD HL,(5C4B)   Get VARS area address
5B08    LOOP:   BE      CP A,(HL)      Test variable identity
5B09            280E    JR Z, FOUND    Jump if right variable
5B0B            FE80    CP A, 80       Is this end of VARS ?
5B0D            2002    JR NZ, CONT    Continue if not end
5B0F            CF      RST 08         Error return otherwise
5B10            01                     VARIABLE NOT FOUND message ident.
------------------------------------------------------------------------
5B11    CONT:   23      INC HL         Point to size of field
5B12            5E      LD E,(HL)      Get size of variable
5B13            23      INC HL           field size into DE
5B14            56      LD D,(HL)
5B15            23      INC HL         Point to next location
5B16            19      ADD HL,DE      Point to next variable
5B17            18EF    JR LOOP        Test this variable
------------------------------------------------------------------------
5B19    FOUND:  E5      PUSH HL        Get the address into BC
5B1A            C1      POP BC
5B1B            C9      RET            Done

This routine scans the entire VARS area of memory until the starting address of the specific variable storage area is located or until the end of the VARS area is reached, at which time there will be an error type return. This will happen if the variable W$ (or any other simple string variable which is being searched for) has not been previously assigned. If the variable has been located, then the address is returned in the BC register pair. Line 1010 in the BASIC code above will assign this value to the variable X on the return from the machine code.

If a search for a fixed dimension string array is desired, it will be necessary to insert the following assembly code bytes between the addresses 5B04 and 5B05 in the routine listed above:

C680            ADD A,80H      Converts to proper type
                               of dimensioned array
                               identifier

It will be necessary to modify the lines of BASIC code to determine the actual size of the stored character field in the array due to the extra data bytes stored in the data field for this type of variable (see page 258 of the TIMEX 2068 users manual for the details). Since the array has been previously dimensioned in the program [e.g. DIM W$(40,256)], we can determine the correct offset by taking the number of array dimensions (2 in this case) and doubling it, then adding 1 for the number of dimensions byte in the variable’s data field and subtracting the result from the data obtained in line 1020 above.

For the example of W$(40,256) the changes to the BASIC lines is as follows:

1020 LET SIZE= PEEK(X+1)+256* PEEK(X+2)-(1+2* PEEK(X+3))
1030 LET START=X+3+(1+2* PEEK(X+3))

Obviously the terms can be combined to shorten the lines but I left all the terms separate to clarify (I hope) the procedure to locate the actual starting address for the character data stored in the array along with the actual length. The size of the actual character data field could be determined in this case by simply multiplying the terms in the DIM statement. It is better to determine the size on the fly for the cases where the array dimensions may be determined by another variable instead of a fixed value [e.g. DIM(256,Z)].

I hope that this brief explanation will give you an idea of how to operate on data stored in the VARS area by either BASIC or machine code routines. To summarize, the transfer of data from the BASIC program to the machine code requires the POKEing of the data into memory locations where it can be accessed by the machine code. Transferring of a single character or numeric (integer) value from the machine code to the BASIC program may be accomplished by loading the data into the BC register pair prior to the return from the machine code.