DSM Template Services Manual

Display-Text Procedures
DSM Template Services Manual—427187-004
2-22
Naming Custom-Formatting Procedures
supplements status on page 2-20. For a list of values, see Supplementary Status
Values on page 2-18.
extra-1
extra-2
extra-3
INT(32):value
are reserved for possible future use and should not be examined.
Naming Custom-Formatting Procedures
Because custom-formatting procedures must reside on the system library, procedure-
name conflicts are a potential problem. To avoid them, adopt a naming convention, as
in these examples for subsystem ABC:
•
abc-ddl-version is the token type that requires custom formatting.
•
abc-tkn-old-version and abc-tkn-new-version are ABC tokens of type abc-ddl-
version.
•
abc_cvt_version is the name of the custom-formatting procedure. An underline
character (_), not a hyphen (-), separates parts of the procedure name (at least for
TAL).
That is, use the name of the subsystem (abc) and the token type (version) to link these
entities.
Context Area
The context parameter of convert-proc points to a context area: an area that
helps custom-formatting procedures resume an interrupted conversion operation. A
context area lets a lengthy external representation be returned in segments on
successive calls to the conversion procedure.
Not all custom-formatting procedures need to use the context parameter. If the
complete external representation always fits in external-value (if its length is
always 100 bytes or less), the procedure logic can ignore the context parameter. The
procedure should just put the formatted value in external-value and return zero as
the function result.
If an occasional external representation exceeds 100 bytes, the system does most of
the work of handling interrupted conversions if the programming logic of the conversion
procedure follows a few conventions. This discussion should help you develop such a
procedure.
First, a zero value in context[0] informs convert-proc that this is the first call to
convert a particular value. When the external representation is not complete in the
current call, convert-proc must set context[0] to some nonzero value before
returning. Then, it must set external-value to the first installment of the
representation and signal more-to-come by returning -16 or -17.