READ Base {+ Offset}, Variable {, Variable, ...}

Function
Read one or more bytes from a table.

• Base  is the base address of data to be read which may be specified as a DATA or WDATA statement label, or as a string-pointer variable created by the compiler (see below).
• Offset  is an optional variable indicating the relative position (to Base) for the READ operation. This may be specified when Base is a label, or can be created by the compiler when strings are used (see below).
• Variable  is a byte or word variable.

Explanation
The DATA directive can be used to create [read-only] tables for SX/B programs. The READ instruction is used to move one or more table values into the specified byte variable(s).

Start:
  TRIS_B = %00000000                            ' make RB outputs

Main:
  FOR idx = 0 TO 3
    READ Pattern + idx, RB                      ' move pattern to LEDs
    PAUSE 100
  NEXT idx
  FOR idx = 4 TO 1 STEP -1
    READ Pattern + idx, RB
    PAUSE 100
  NEXT idx
  GOTO Main                                     ' do it again

' -------------------------------------------------------------------------

Pattern:                                        ' LED patterns
  DATA  %00000000
  DATA  %00011000
  DATA  %00111100
  DATA  %01111110
  DATA  %11111111

As of version 1.4, SX/B can handle inline strings (of two or more characters) and z-strings (of any length) stored in DATA statements. Using READ, the following subroutine will send a string to a defined serial port:

' Use: TX_STR [ string | label ]
' -- "string" is an embedded literal string
' -- "label" is DATA statement label for stored z-String

TX_STR:
  tmpW1 = __WPARAM12                            ' get offset/base
  DO
    READ tmpW1, tmpW3                           ' read a character
    IF tmpW3 = 0 THEN EXIT                      ' if 0, string complete
    SEROUT SOut, Baud, tmpW3                    ' send the byte
    INC tmpW1                                   ' point to next character
  LOOP
  RETURN

This subroutine expects two parameters: the base address and the character offset of the string. The subroutine uses a word variable to accept the base+offset string pointer that is passed as a parameter. When a literal string or DATA label is specified as the TX_STR parameter, the compiler inserts the appropriate values that form a pointer to the string. Using the subroutine above strings can be transmitted like this:

TX_STR          SUB     2                       ' strings use two parameters

' -------------------------------------------------------------------------

Main:
  TX_STR "Version "                             ' inline string (compiles to z-string) 
  TX_STR VerNum
  END

' -------------------------------------------------------------------------

VerNum:
  DATA "1.0", 0                                 ' defined z-string

Note that when using a label as a subroutine parameter it must be defined before use, and the SX/B compiler adds the terminating zero to inline strings when there are two are more characters. If the following syntax is used:

  TX_STR "X"                                    ' character passed by value

Related instructions: DATA/WDATA and LOOKUP