7Eh UT$CDSP clear and write to display
Input On machine stack - variables to display.
Output - none -
Description Clears the display and displays literal text and variables according to the format control string which is inserted in-line directly after the operating system call to UT$CDSP. Does exactly the same as UT$DISP except that the screen is cleared first.

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.

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%
Required format control string
"70%% %+ 3%% %- 1%%"

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.

Only available on versions 2.5 and above.

Example To display "A simple string" after clearing the screen.
        OS      UT$CDSP
        ASCIZ   "A simple string"
For more examples, see UT$DISP.
Errors - none -