|
WSupported on Windows
|
USupported on Unix
|
VSupported on OpenVMS
|
NSupported in Synergy .NET
|
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)
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.
|
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:
- Precision is present.
- The type is D.
- The passed argument is not implied or integer.
Trailing zeros are placed in the formatted result if the following condition is true:
- Precision is present and contains a leading zero.
Finally, the passed argument is logically rounded to the place number stored in precision if the following conditions are true:
- Precision is present.
- The type is D.
- The passed argument is implied-decimal or implied-packed.
- The size of the fractional part of the argument is greater than precision.
=
(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.
|
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 |
