View source for Programmer Guide/General Descriptions/Format Strings and Rules

{{DISPLAYTITLE:{{SUBPAGENAME}}}}
{{PG_StringCommands}}
==Format Strings and Rules==

A number of {{STX}} commands (e.g. <code>WRITE</code> and <code>FORMAT</code> and the shell table <code>CONFIG</code> command) take a formatting string parameter.

====Standard C String formatting====

Wherever formatting is used, it is defined using a C-like format string. The following standard C-format tags can be used:

{|
|-
|%s
|for strings
|-
|%d
|for integer values
|-
|%f, %g
|for float values (numbers)
|-
|%X, %x
|for unsigned hexadecimal integers in upper (X) and lower (x) case
|-
|%%
|replaced by a single % character
|}

All variations of these tags allowed in C are allowed here (e.g.: %<nowiki>-</nowiki>10.10s, %3.0f, %05d, ...).

====Formatting Extensions====

An additional set of special format tags is also available:

{|
|-
|%t
|replaced by 8 blanks
|-
|%T
|replaced by a tab character
|-
|%h
|to display time values in the format 'hh:mm:ss.ttt'
|-
|%n
|replaced by a linefeed (<code>\n</code>).
|}

Time format variations: %h, %nh, %-nh, %n.h, %-n.h where the following apply:

{|
|-
|<nowiki>-</nowiki>
|suppress output of leading zeros (hours and minutes only)
|-
|.
|show milliseconds (thousands)
|-
|n
|number of characters or 0 for automatic field width; if n is greater than the output string length, the output is right aligned
|}

Note that the input for the time format is a value in seconds.

For each format tag except <code>%t</code>, <code>%T</code> and <code>%%</code>, an argument value must be present in the command line.

If one of the tags (- or .) is used a field width must be also included, use n=0 for automatic field width (no alignment).

A format string used in <code>WRITE</code> and <code>FORMAT</code> commands can contain more than one format tag (which need a value). Format strings used for table configuration, however, need exactly one format tag for the value stored in the table.

====Format Examples====

<pre>
<code>FORMAT '%s%n%s' 'line 1' 'line 2'</code>
<code>// generates the output</code>
<code>line 1</code>
<code>line 2</code>
</pre>