Return the specified format as a character string to a destination.

Syntax

sprintf(format)

Parameter

Description

The sprintf() function is identical to the printf() function except that it returns the created string rather than outputting it to the PATROL Console. If there is an error in format, sprintf sets the PSL errno variable and returns the NULL string. 

The formats, conversions, and values of errno for the various errors are identical to those described for the printf() function. 

C programmers should be careful to use the PSL style: 

destination=sprintf(format)

rather than the C-style: 

sprintf(destination,format)

The latter style will often cause a compilation warning about a null-effect statement.

C Conventions Not Supported by the PSL sprintf Function

The sprintf() function does not support the C convention of using the asterisk (*) as a field width or precision indicator. The sprintf() function does not support the %p and %n conversion characters. 

The length modifiers h, l (ell), and L are not valid and are ignored by the sprintf() function. 

The sprintf() function format conversions are passed directly to the C library sprintf() routine on each platform. The output for obscure formatting features may differ across platforms, especially on platforms with libraries that do not conform to ANSI C requirements.

Conversion Differences between the C sprintf Routine and PSL sprintf Function

The format conversions have the same meaning between standard C and PSL, but the concept of variable types differs between the two. 

PSL supports only string types for its variables, and thus string arguments to the sprintf() function are converted in a manner appropriate for the format conversion:

• Integral formats, such as %d, convert the string to signed integers.
• Noninteger numeric formats, such as %f, convert to floating point values.
• %c prints the ASCII equivalent of its integer argument, or for nonnumeric arguments, the first character of its argument. (Applying %c to "65" will print 'A' and to "AB" will print 'A'.)
• %s causes no conversion.
• %% requires no argument.

The %N Format Conversion

The sprintf() function provides one nonstandard C extension--the %N conversion. The %N conversion preprocesses a numeric string so that commas separate each group of three digits beginning at the right side of the string. 

For example, the %N conversion causes the following conversions: 

1234 ⇒ 1,234 12345 ⇒ 12,345 123456 ⇒ 123,456 

The %N conversions ignores initial minus signs and blanks while searching for the first sequence of digits so that %N can be applied to negative values. If no digits are found after the skipped characters, the printed argument is unchanged. 

The %N conversion only modifies the first sequence of digits. For example, the %N conversion changes floating point numbers like 1234.1234 to become 1,234.1234 without changing to the digit sequence to the right of the decimal point. 

As part of the %N conversion, the sprintf() function performs a %s conversion using the field width and precision specifiers supplied in format. The sprintf() function prints the string resulting from the combined %N and %s conversions. Because of the embedded %s conversion, field width and precision under %N conversion have the same effect as with %s.

Note

Currently, no localization is supported by %N, and so the formatting achieved by %N does not change in different locales. 

Example

The following PSL script uses the sprintf() statement to recursively build a formatted decimal/octal/hexadecimal conversion table before printing it.

function main() {
i = 0;
string = sprintf(" n Oct Hex\n");
string = sprintf("%s--- ---- ----\n",string);
while (i++ <= 25) {
string = sprintf("%s%3d %4o %4X\n",string,i,i,i);
}
print(string);
return;
}

The example produces the following output:

n Oct Hex
--- ---- ----
1 1 1
2 2 2
3 3 3
4 4 4
5 5 5
6 6 6
7 7 7
8 10 8
9 11 9
10 12 A
11 13 B
12 14 C
13 15 D
14 16 E
15 17 F
16 20 10
17 21 11
18 22 12
19 23 13
20 24 14
21 25 15
22 26 16
23 27 17
24 30 18
25 31 19