There are several SGS routines for creating and plotting strings of characters. The most general, low level routines will be described first, although in many instances it will be more convenient to use the higher level routines SGS_TX, SGS_TXI and SGS_TXR, which allow single strings and formatted numbers to be plotted; these will be described later.
A text string can be plotted by means of the routines SGS_BTEXT, SGS_ATEXT and SGS_OTEXT. SGS_BTEXT begins a new text string:
where X,Y is the ‘position’ of the string (more about that shortly). ATEXT appends more text onto the string:
(TEXT is a character string). SGS_OTEXT outputs a completed string:
The call to SGS_OTEXT can usually be omitted; any existing string is output automatically when SGS_BTEXT or SGS_CLOSE is called (and at various other critical places within SGS). (n.b. The maximum length of string that can be plotted is set by an internal workspace. Unreasonably long strings will suffer truncation to this maximum.)
There are several higher level append routines. The routine SGS_ATXL appends a field to the text string after stripping any trailing blanks; thus if:
the two calls:
produce identical results.
The routine SGS_ATXB, in contrast, appends a right justified field to the text string, but replaces any leading blanks with a specified number of blanks. Thus, if:
the two calls:
produce identical results.
Routines are provided for conveniently plotting numbers; SGS_ATXI formats and appends an integer, and SGS_ATXR does the same for a real.
Integers may be plotted by means of:
where I is the number and NFI controls the formatting. If the number is to be left justified (for example within a message), an NFI value equal to the number of leading spaces should be specified. For example:
would produce the string ‘THERE WERE 25 SAMPLES’. If, on the other hand, right alignment is required (if a scale were to be marked on the left of a vertical axis, for example) an NFI value of minus the required field width should be specified.
Similarly, real numbers can be plotted with the routine SGS_ATXR:
where R is the number and NFI is as for the ATXI routine. NDP is the number of decimal places to be plotted. −1 (or any other negative value) causes only the integer part of the number to appear; if 0 is specified the decimal point appears as well; positive values result in the specified number of decimal places being plotted. (N.B. Both SGS_ATXI and SGS_ATXR are limited in the width of fields they can handle, and only sensible values should be used.)
Details of the text string under construction can be inquired through the routine SGS_ITXB:
For the current zone, the SSG_ITXB routine returns the reference position (X, Y), the number of characters in the string (N) and the string extent DX, DY is such that X+DX, Y+DY is the concatenation point for subsequent strings. In the common case where the strings are being drawn left justified, a new string drawn at the concatenation point will follow on from the old one. If, however, right justification has been specified, each successive string will appear right justified against the previous one. This may not be what was expected; for example, to draw ‘aBc’ where ‘B’ is in a different font or requires a different pen and thus causes the string to be flushed before and after, it will be necessary if using right justification to plot the ‘c’ first, then to change font or pen and plot the ‘B’, and finally to plot the ‘a’. In the case of text which is centred horizontally (viewing the string in the normal orientation), concatenation is not appropriate, and zero DX and DY are returned.
When the string to be output has already been formatted, or where a single number is to be plotted, it is convenient to use the routines SGS_TX, SGS_TXI and SGS_TXR:
In each case X, Y is the position of the string. STRING is the character string to be output; I and NFI are the integer to be formatted and the format indicator (exactly as for the ATXI routine); R, NFI and NDP are the real number to be formatted, the format indicator, and the number of decimal places (likewise exactly as for the SGS_ATXR routine).
These routines merely open a new text string and append the requested field to it; immediate output is not implied and more fields can be appended if desired.
Notes: