Because the text width associated with a history record is not fixed, there can sometimes be difficulty in knowing how to format history text correctly, especially when appending to an existing record. In principle, it would be possible to use the enquiry routine NDF_HINFO to determine the text width and to act accordingly, but in practice this is cumbersome and rarely worth the effort. In addition, if message tokens are present within the text, it becomes difficult to predict the length of each line after token substitution has taken place.
To address this problem, NDF_HPUT provides several formatting options aimed at reconciling the possibly different widths of the text supplied (after message token substitution if appropriate) and the history record into which it must be written. The guiding principle is that no history text should ever be discarded as a result of limited line length, and that as far as possible it should remain legible.
The simplest formatting option is selected by setting both the WRAP and RJUST arguments of NDF_HPUT to .FALSE., in which case input text lines will simply be broken if they exceed the width available and continued on a new line (line breaking will take place at a suitable space if possible). This option is normally most suitable for ``fixed-format'' output of results.
If its WRAP argument is set to .TRUE., NDF_HPUT will instead perform ``paragraph wrapping'' on the text supplied. In this case, the text will be re-formatted so that the maximum number of words appears on each line, with words separated by single spaces. Re-formatting will not occur across ``paragraph boundaries'' marked by blank input lines. This option is most suitable for prose-style continuous text, particularly if it contains elements of unknown length such as message tokens. It also has the advantage of minimising the space needed to store the text.
Finally, if the RJUST argument of NDF_HPUT is set to .TRUE., it will
``right justify'' the text wherever a line is broken for continuation
on the next line (i.e. after first performing either of the
formatting operations described earlier if necessary). This results in
lines of the final text being padded with blanks so as to produce a
uniform right margin occupying the full text width (normally the right
margin would remain ragged). When wrapping text, the final line of
each paragraph, which may naturally be shorter than other lines, is
not padded, and neither are unbroken lines if wrapping is disabled.
This option is largely cosmetic but may improve the readability of
some types of text. It does not affect the amount of space used.