S_BLD

Construct a formatted string

WTSupported in traditional Synergy on Windows
WNSupported in Synergy .NET on Windows
USupported on UNIX
VSupported on OpenVMS
xcall S_BLD(destination, [length], control[, argument, ...])

Arguments

destination

The variable that will be loaded with the formatted string. (a or StringBuilder)

length

(optional) The variable that will be loaded with the length of the formatted string. (n)

control

The processing control string for the build. The format of the control argument is explained in the Discussion below. (a)

argument

(optional) A list of up to nine arguments as required by the control string. (a or n)

Discussion

The S_BLD subroutine constructs a formatted string.

If destination is an alpha field, it is “emptied” to blanks and loaded with the new text starting at the first position. (The blank fill does not happen when S_BLD is called as a function.) If destination is a StringBuilder object, the generated string is appended to the end of the text already in the StringBuilder object. Here's an example with a StringBuilder object:

xcall s_bld(sb,,"%%+07.03=d  => {%+07.03=d}", f2)

The control string consists of one or more text and/or format segments. A text segment is all of the characters between format segments. Text segments are copied directly into the destination field. If the first two characters of control are “%&,” Synergy DBL assumes destination already contains the number of characters in length, and the output string is appended to the existing contents. Otherwise, destination is replaced with the new text, blank filled, as described above.

If you use ^VARARGARRAY, note that control is the last declared argument for this routine.

Tip

To achieve results equivalent to a Synergy decimal to alpha conversion (format string of the type ZZZZZX.XX), use a control string of “%0.0nd” where n is the desired precision.

A format segment uses the next argument from the S_BLD call and formats it into the destination field. A format segment has the following syntax:

%[justification size[.precision]][=]type

justification

(optional) A justification code. It must have one of the following values:

= Left-justified within the specified size (default when type is A)

+ = Right-justified within the specified size (default when type is D)

size

(optional) The minimum width of the formatted result field. If size is omitted, or if it is present, nonzero, and smaller than the size of the consumed argument, the size of the result field is determined by the contents of the consumed argument. If size is present and contains a leading zero, leading zeros are appended to the result. If size is 0, the result is determined by the contents of the consumed argument. Otherwise, all leading zeros are set to blanks.

precision

(optional) The fractional precision that is displayed. If precision is omitted, no fractional precision is displayed for a decimal field, and the number of significant digits in the fractional part of an implied-decimal field is the fractional precision in the format. If type is A and you specify a precision value, the fractional precision is ignored.

A number of fractional zeros equal to the value in ­precision are logically added to the decimal field if the following conditions are true:

Trailing zeros are placed in the formatted result if the following condition is true:

Finally, the passed argument is logically rounded to the place number stored in precision if the following conditions are true:

=

(optional) The strip-processing flag. If the “=” is present, no leading strip processing occurs. If the “=” is not present, leading, nonsignificant zeros are stripped from numeric fields; trailing blanks are stripped from alpha fields; and trailing, nonsignificant zeros (except the first nonsignificant zero) are stripped from implied-decimal or implied-packed fields.

type

The type of the next argument to consume. It must have one of the following values:

A = The consumed argument is accessed as an alpha type.

D = The consumed argument is accessed as a numeric type.

A numeric type can be decimal, implied-decimal, integer, packed, or implied-packed, while an alpha argument accessed as numeric is considered decimal.

Note

In Synergy .NET, if any input arguments overlap, an error is generated.

Examples

In the example below, line contains the following

“Page #27    8/16/1992”

Linelen is returned with a value of 49. The %& causes “8/16/1992” to be appended to the existing contents of line, beginning at position linelen + 1.

.define TTCHN           ,1
record
    line                ,a80
    linelen             ,d2
    pagenum             ,d3,    27
    day                 ,d2,    16
    mo                  ,d2,    8
    yr                  ,d4,    1992
proc
    open(TTCHN, o, "tt:")
    xcall s_bld(line, linelen, "Page #%d", pagnum)
    linelen = 40
    xcall s_bld(line, linelen, "%&%d/%d/%d", mo, day, yr)
    writes(TTCHN, line(1:linelen))
    close TTCHN
    stop
end

The following table contains examples of the various output based on variable type (decimal or implied-decimal), given the following:

ivar,   d9.2,   1502.20
var,    d9,     1502

Mask

ivar value

var value

%09.2d

0001502.2

0001502.0

%09.02d

001502.20

001502.00

%0.02d

1502.20

1502.00

%09.2=d

0001502.20

000001502.0

%09.02=d

0001502.20

000001502.00

%0.02=d

0001502.20

000001502.00