6Eh UT$DDSP write to display
Input D register - address of format control string.
On machine stack - variables to be displayed.
Output - none -
Description Displays literal text and variables according to the format control string the address of which is in the D register. The LCD display is not cleared and the text is displayed from the current cursor position.

This is identical to UT$DISP except that the format control string is not inserted in-line.

Format descriptors interspersed between literal text in the format control string, allow the display of variables formatted in the specified way. In the simplest case, these descriptors are prefixed by a '%' character followed by the type-specifier, in which case the text is displayed left justified at the cursor position. The type-specifiers must be in lower-case.

  descriptor  
%a
%i
%j
%u
%v
%x
%y
%s
%b
%f

type to be displayed
ASCII coded character
signed integer word value
signed integer byte value
unsigned integer word value
unsigned integer byte value
unsigned integer word value in HEX
unsigned integer byte value in HEX
string that has a leading byte count
text buffer (address and length byte given)
fill field (for this type a field width must be included)

Optionally, the programmer can justify the text within a field of chosen width, where the field is filled with a specified character. A number after the '%' signifies the field width within which the text is to be left justified with the SPACE fill character. Instead of '%', '+' can be used for left and '-' for right justification, followed by the mandatory fill character and field width.

The maximum field width is 99 and vertical scrolling will begin after the text fills the whole LCD display. If the field is not wide enough, the text is truncated on the side opposite to the justification specified (eg. right justification causes truncation on the left).

For convenience, '}' has been defined as equivalent to the commonly used descriptor "-02v". This shows the last two digits of a single unsigned byte, including a leading 0 if necessary. The LZ has an extra control character available, ascii 31 which will centralize the next string on the current line, clearing the left and right sides of the line.

The required format for a descriptor field is therefore

  • %[<field width>]<type specifier> or
  • +<fill character><field width><type specifier> or
  • -<fill character><field width><type specifier>.

Some examples:

"%x" left justified HEX representation of word integer.
"%6x" left justified HEX representation of word integer, filling to the right with spaces in field width of 6.
"-06x" right justified HEX representation of word integer, filling to the left with zeroes.
"-*14i" right justification of a signed word integer parameter in a 14-byte field, filled to the left with stars.
"%18f" 18 spaces.
"+*18f" 18 stars ('+' needed only to specify the star).

All display is done through the service routine DP$EMIT, so that control characters (such as 16 for beep) can be used in the format control string.

The characters '%', '+', '-' and '}' themselves can be displayed by preceding them by an extra '%' character. E.g.

Sequence to be displayed  
  70% + 3% - 1%
  %%
  ++
  --
  {2/{3*4}}
Required format control string
"70%% %+ 3%% %- 1%%"
"%%%%"
"%+%+"
"%-%-"
"{2/{3*4%}%}"

Variable parameters must be pushed onto the machine stack in reverse order to that in which they will be displayed. For a buffer parameter, the length byte must be pushed before the address. They must correspond in number and in type to thespecification of the format control string.

On multilingual machines, the characters $60 to $FF are used to denote various system messages, which will then be displayed in the current language.

Example To clear the display and then display "A simple string".
CONTROL_STRING:
        DB     D_FF        ; clear display - control character 12
        DB     "A simple string"
        DB     0           ; string termination byte

DISP:   LDD    #CONTROL_STRING ; D points to format control string
        OS     UT$DDSP
See UT$DISP for further relevant examples, where the only difference is that in that routine the format control string is inserted in-line.
Errors - none -