Formatting Transformation Functions

To simplify the process of formatting transformation functions, a set of routines is provided which allows numerical or textual values to be inserted into ``template'' character strings. These routines largely eliminate the need to use Fortran WRITE statements to construct transformation functions containing numerical values.

The routines have names of the form TRN_STOK[x], where x is either I, R or D according to whether the type of value to be inserted is integer, real or double precision respectively. The routine TRN_STOK (i.e. with x omitted altogether) is used for making textual (rather than numerical) insertions but otherwise functions in the same way. These routines rely on the concept of a token,⁵which is placed in a character string at the point where an insertion is to be made and which is subsequently replaced by the value to be inserted. For example, if the character variable TEXT had the value:

'magnitude = - 2.5 * log10( count ) + zero_point'

then TRN_STOKR (substitute a real token value) could be used to substitute a numerical value for the `zero_point' token, as follows:

CALL TRN_STOKR( 'zero_point', 17.7, TEXT, NSUBS, STATUS )

This causes all occurrences of the `zero_point' token to be replaced with the formatted real number `17.7', while NSUBS returns the number of substitutions made (in this case there will only be one). The value of TEXT then becomes:

'magnitude = - 2.5 * log10( count ) + 17.7'

Note that the TRN_STOKx routines will respect the syntax of transformation functions, so that negative numerical values will be enclosed in parentheses before a substitution is made. For instance, if the call to TRN_STOKR had been:

CALL TRN_STOKR( 'zero_point', -17.7, TEXT, NSUBS, STATUS )

then the `zero_point' token would be replaced by `(-17.7)' to prevent the illegal expression `...+ -17.7' from being produced. The need for two extra characters to accommodate these parentheses must be remembered when declaring the size of character strings.