Lookdown

searches for a key value in a table and returns its position number.

Lookdown is useful for interpreting data that is not organized in any particular pattern. For example, say you were constructing an instrument that could be controlled by one-letter commands received over a serial connection, and your commands were A, G, Q and X. You could use Lookdown to convert these letters to the values 0 through 3 for processing by your program, or to jump into a Branch table.

Lookdown takes two inputs, a table to search and a variable key to search for. On return, key is unchanged, the variable index holds the position number of key in the table (if it was found), and w holds an error code. The error codes returned in w are as follows:

0 = No error.
1 = Key is not in the table.

The table that Lookdown searches must be set up so that its first element is the number of entries. For instance, if a table had 3 searchable entries, element 0 would be 3; element 0 itself is not included in the count. Duplicate entries must be avoided, since Lookdown returns only one answer.

The position number that Lookdown reports is adjusted so that 0 = the first searchable entry, 1 = the second, and so on. This makes it compatible with PBASIC. If you want Lookdown to number entries starting with 1 instead of 0, remove the instruction dec index from the end of the routine. If you make this change, move the label :done next to the ret instruction.

Demonstrating Lookdown.

To see Lookdown in operation, either run the program with the PSIM simulator, or connect the circuit below to an erasable PIC or PIC emulator, such as the Parallax downloader. Assemble and run LOOKDOWN.SRC. When you apply power to the PIC, the LEDs will light in the pattern 0110, representing the number 6, the position of G in the table.


; LOOKDOWN key, table
; Searches a table for an element that matches key. If a match 
; is found, Lookdown returns its position in the table in the 
; variable index and a 0 in the w register. If no element matches key, 
; Lookdown returns a 1 in the w register as an error code. 

        org     8
key     ds      1       ; Element to find. 
index   ds      1       ; Position of key in table. 

; Device data and reset vector
        device  pic16c55,xt_osc,wdt_off,protect_off
        reset   start
        org     0

start   mov     !rb,#0  ; Output to show index on LEDs.
        mov     key,#'G'        ; Search for byte corresponding to 
        call    Lookdown        ; ASCII G and return index no. 
        mov     rb,index        ; Show index on LEDs hooked to RB.
        jmp     $       ; Endless loop. 

; The table to be searched must include the number of searchable elements 
; as element no. 0 (the very first element in the table). 
Table   jmp     pc+w
        retw    10      ; No. of searchable elements. 
        retw    'ABCDEFGHIJ'    ; Table of ASCII characters. 

; Locate table element corresponding to key. 
; Return with the corresponding element number in index. Key is not
; altered by Lookdown. Note that when the element is found, :done
; decrements index so that the first element = 0, second = 1...
; just as with the PBASIC instruction. 

Lookdown        clr     w       ; Retrieve element 0. 
        call    Table
        mov     index,w ; Copy table length to index. 
:loop   call    Table   ; Retrieve element. 
        subwf   key,0   ; W = key - W
        snz             
        jmp     :done   ; If w = 0, we have a match. 
        dec     index   ; If not, try next lower element.
        mov     w,index ; Put index into w for table. 
        sz              ; If zero, element is not in table. 
        jmp     :loop   ; Try next lower element
        retw    1       ; Error code: element not in table. 
:done   dec     index   ; index=index-1 to match PBASIC.
        ret             ; Element found: return a 0 in w.