DSM Template Services Manual

Display-Text Procedures
DSM Template Services Manual—427187-004
2-8
SPI_BUFFER_FORMATNEXT_
status-2
INT .EXT:ref:1
supplements status on page 2-6. For a list of values, see Supplementary Status
Values on page 2-18.
Overall Procedure Logic
SPI_BUFFER_FORMATNEXT_ treats the text buffer, which is size bytes long, as a
series of fixed-length lines. Because the number of lines is given by the parameter n,
each line is allotted m bytes, where m is size/n. The lengths array returns the
number of bytes actually used for each line (m minus the number of trailing blanks).
The procedure checks the SPI_BUFFER_FORMATNEXT_ parameters to ensure they
are individually correct, work with each other, and work with the parameters passed to
SPI_BUFFER_FORMATSTART_. Values m and n must divide evenly into size, and m
must be at least (token-label-len) + (field-label-len) + 15. If parameter
errors occur, the procedure returns -2 (illegal parameter value) without changing the
text buffer.
Before generating display text, the procedure clears the text buffer to spaces and the
lengths array to -1 values. This provides trailing spaces for unfilled display-text lines
and -1 values for the lengths of unused lines. The procedure then generates the
display text.
The procedure represents each token (and each field of a structured token) in display
text in the order of its occurrence in SPI-buffer. It places the display-text
representation in text-buffer.
As it completes a logical line in text-buffer, the procedure computes the line’s
length: the number of characters transferred to text-buffer, which excludes trailing
blanks. It places this length in the appropriate element of the lengths array.
Display-text generation continues until the procedure runs out of logical lines or
reaches the end of SPI-buffer. On return to the application, lengths[0] ...
lengths[n-1] contain the number of significant characters in logical lines 1, 2, ... n.
Depending on your needs, you can print text-buffer as a whole because all
positions are either used or contain spaces. Or you can print text-buffer line by
line, using the lengths array to print only significant characters.
Display-Text Appearance
This subsection describes how simple and structured tokens are represented. Simple
means represented as one elementary type, not as a number of fields. The letter x, as
in xxx(label-1)xxxx, is meant to be part of label-1 and is included to show the way
labels (and values) are aligned.