6Fh UT$DISP write to display
Input On machine stack - variables to display.
Output - none -
Description Displays literal text and variables according to the format control string which is inserted in-line directly after the operating system call to UT$DISP. The LCD display is not cleared and the text is displayed from the current cursor position.

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

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.

On the LZ an additional control code has been added to centre text: ASCII 31. When this is used, the next string to be displayed will be centred on the current line, with the line cleared on either side.

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 display "A simple string" after clearing the screen.
        OS      UT$DISP
        DB      D_FF            ; clear display - control character 12
        DB      "A simple string"
        DB      0               ; string termination byte
To display an unsigned word variable. If WORD_VAR contains 43210 for instance, "WORD_VAR=43210" will be displayed.
        LDX     WORD_VAR
        PSHX                    ; push word variable value
        OS      UT$DISP
        ASCIZ   "WORD_VAR=%u"   ; the format control string
To display a signed word variable, right justified in a field width of 9. If WORD_VAR contains -3210 for instance, "WORD_VAR= -3210" will be displayed.
        LDX     WORD_VAR
        PSHX                    ; push word variable value
        OS      UT$DISP
        ASCIZ   "WORD_VAR=- 9i"

To display the date and time in the form

TUE 18 NOV 1986
   17:40:35

where the order of the system variables in memory are:
TMB_YEAR,TMB_MONS,TMB_DAYS,TMB_HOUR,TMB_MINS,TMB_SECS

MONTH_NAME_TABLE:
        DB      "JANFEBMARAPRMAYJUNJULAUGSEPOCTNOVDEC"

DISPLAY_DATE_TIME:
        LDX     #TMB_YEAR       ; point to 6-byte date/time buffer
        LDD     4,X             ; minutes into A, seconds into B
        PSHB
        PSHA
        LDAA    3,X             ; hour into A
        PSHA
        LDD     0,X             ; year into A, month into B
        PSHA
        LDAA    #3              ; month names are 3 characters long
        PSHA                    ; buffer length pushed before address
        MUL                     ; multiply index into table by 3
        LDX     #MONTH_NAME_TABLE
        ABX                     ; point to month name
        PSHX                    ; push address of month buffer
        LDX     #TMB_YEAR
        LDAA    2,X             ; day of month into A
        INCA                    ; day 0 means 1st of month
        PSHA
        LDAA    #3
        PSHA                    ; day (of week) name length
                                ; X still points to 6-byte date buffer
        OS      TM$DAYV         ; puts address of day name into X
        PSHX
        OS      UT$DISP
        DB      D_HM            ; HOME the cursor - control character 11
        ASCII   "%b - 2v %b 19}"
        ASCIZ   "%5f}:}:}%4f"   ; must fill display as not cleared
        RTS
Errors - none -