Please title this page. (lookdown.htm)

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.

;
; ***************************************************************************
; ***  Bubble Software Parallax to PIC Source Converter. Copyright 1999.  ***
; ***  http://www.bubblesoftonline.com                 email: sales@picnpoke.com  ***
; ***************************************************************************
;
; 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. 

; Device data and reset vector
	P = pic16c55
	#include <16c55.inc>   ; processor assembler definitions
	_CONFIG _xt_osc & _wdt_off & _protect_off
        reset   start

        org     8
key     Res      d'1' ; Element to find. 
index   Res      d'1' ; Position of key in table. 

        org     0

start        MOVLW d'0'                 ; Output to show index on LEDs.
             TRIS 6h
             MOVLW 'G'                  ; Search for byte corresponding to 
             MOVWF key
             CALL Lookdown              ; ASCII G and return index no. 
             MOVF index,w               ; Show index on LEDs hooked to RB.
             MOVWF 6h
             GOTO $                     ; 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        ADDWF pcl                  
             RETLW d'10'                ; No. of searchable elements. 
             RETLW 'A'                  ; Table of ASCII characters. 
             RETLW 'B'
             RETLW 'C'
             RETLW 'D'
             RETLW 'E'
             RETLW 'F'
             RETLW 'G'
             RETLW 'H'
             RETLW 'I'
             RETLW 'J'

; 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     CLRW                       ; Retrieve element 0. 
             CALL Table                 
             MOVWF index                ; Copy table length to index. 
Lookdown_loop
             CALL Table                 ; Retrieve element. 
             SUBWF key,0                ; W = key - W <Microchip instruction>
             BTFSC status,z             
             GOTO Lookdown_done         ; If w = 0, we have a match. 
             DECF index                 ; If not, try next lower element.
             MOVF index,w               ; Put index into w for table. 
             BTFSS status,z             ; If zero, element is not in table. 
             GOTO Lookdown_loop         ; Try next lower element
             RETLW d'1'                 ; Error code: element not in table. 
Lookdown_done
             DECF index                 ; index=index-1 to match PBASIC.
             RETLW 0h                   ; Element found: return a 0 in w.

             
             
             end

; 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.