Format Specifications

Format Specifications

Top  Previous  Next

 

Format specifications appear in field 5 of C-type, D-type and I-type dictionary items to determine the default format of output from the LIST and SORT query processor commands. They are also used in the QMBasic FMT() function and with the query processor FMT keyword.

 

The full form of a format code is

 

{field.width} {fill.char} justification {n{m}} {conv} {mask}

 

where

 

field.widthis the width of the field into which the data is to be formatted. If field.width is omitted, mask must be specified.

 

fill.charis the character to be used to expand the string to field.width characters. If omitted, a space is used by default. Where fill.char is a digit, it must be enclosed in single or double quotes.

 

justificationindicates the justification mode to be applied. It takes one of the following values:

 

Cspecifies centered justification. The data is centered in a field of field.width characters, additional fill.char characters being added to either side if the data is shorter than field.width. If the data is longer than field.width, text marks are inserted at intervals of field.width from the start of the data.

 

Lspecifies left justification. The data is left aligned in a field of field.width characters, additional fill.char characters being appended if the data is shorter than field.width. If the data is longer than field.width, text marks are inserted at intervals of field.width from the start of the data.

 

Rspecifies right justification. The data is right aligned in a field of field.width characters, additional fill.char characters being inserted at the start if the data is shorter than field.width. If the data is longer than field.width, text marks are inserted at intervals of field.width from the start of the data.

 

Tspecifies text justification. Text marks are inserted to break the data into fragments of no more than field.width characters, aligning breaks onto the positions of spaces in the data. Where there is no suitable space at which to break the data, the text mark is inserted field.width characters after the last break position. The final fragment is padded using fill.char to be field.width characters in length.

 

When the data is displayed, output moves to a new line where a text mark is present in the formatted data.

 

Uspecifies left justification and is treated identically to the L code by the QMBasic FMT() function. Within the query processor, data formatted with this code that is wider than field.width is not wrapped over multiple lines but extends into the space to its right, possibly overwriting whitespace in later columns.

 

nspecifies the number of decimal places to appear in the result when formatting numeric data. The value is rounded in the normal manner. If n is zero, the value is rounded to an integer.

 

mspecifies the scaling factor to be applied. The value being formatted is scaled by moving the decimal point m - p places to the left, where p is the current precision value.

 

convis any meaningful combination of the following codes:
$specifies that the national currency symbol should be used as a prefix to the converted data on output conversion and may be present on input conversion. The default currency symbol is a dollar sign but this may be changed by use of the NLS command or the SETNLS QMBasic statement.

 

,indicates that the national language convention thousands delimiter is to be inserted every third digit to the left of the decimal point when converting numeric data. This delimiter defaults to a comma.

 

Bappends db to negative numbers, two spaces to positive numbers. Use the CRDB.UPCASE keyword of the OPTIONcommand to change this to DB.

 

Cappends cr to negative numbers, two spaces to positive numbers. Use the CRDB.UPCASE keyword of the OPTIONcommand to change this to CR.

 

Dappends db to positive numbers, two spaces to negative numbers. Use the CRDB.UPCASE keyword of the OPTIONcommand to change this to DB.

 

Eencloses negative number in angle brackets (<…>). Positive numbers are followed by a single space.

 

Mappends a minus sign to negative numbers.

 

Nsuppresses any sign indicator.

 

Zindicates that a value of zero should be represented by a null string.

 

maskspecifies a mask to be used to format the data. If omitted, field.width must be specified. Both can be used together.

 

The mask consists of a character string containing #, * or % characters and other characters. Each #, * or % is substituted by one character from the source data. Other characters are copied directly to the result string. Multiple #, * or % characters may be represented by a single #, * or % followed by a number indicating the number of characters to be inserted. Characters having special meaning within the format string may be prefixed by a backslash (\) to indicate that they are to be treated as text.

 

The value 1234567 with a format specification of 9L#2-#3-#2 would return 12-345-67.

 

Where the mask specifies more characters than in the data being converted, positions corresponding to # characters in the mask are replaced by the fill.char, positions corresponding to * characters in the mask are replaced by asterisks and positions corresponding to % characters in the mask are replaced by zeros. If the data is left aligned, the padding is inserted in the rightmost positions. If the data is right aligned, the padding is inserted in the leftmost positions.

 

If the mask specifies fewer characters than in the data being converted, part of the source data will be lost. A left aligned format will truncate the source data and a right aligned format will lose data from the start of the source.

 

Data formatting attempts to handle the data as a number if the decimal places, currency symbol, comma insertion or null zero features are included in the format specification. If these features are all absent, or if the data cannot be converted to a number, it is handled as a string. The difference in handling is relevant when processing data such as a string with leading zeros.

 

 

 

Special Case

 

For compatibility with other multivalue products, QM supports a special case of a format code that is just a number. If this is a single digit, it is treated as being the number of decimal  places (n from the descriptions above). If it is two digits, the first is the number of decimal places and the second is the scale factor (m above). No other formatting is applied.

 

 

Format Code Examples

 

The following table shows some uses of format codes.

 

Value

Format code

Result

'ABCDE'

'8L'

'ABCDE   '

'ABCDE'

'8R'

'   ABCDE'

'ABCDE'

'8'*'L'

'ABCDE***'

'0012345'

'8R'

' 0012345'

'0012345'

'8RZ'

'   12345'

'0000000'

'84RZ'

''

'12345'

'8"0"R'

'00012345'

'1234567'

'15R2'

'     1234567.00'

'1234567'

'15R2$,'

'  $1,234,567.00'

'12345.67'

'15*R2$,'

'*****$12,345.67'

'1234567'

'14L2'

'1234567.00    '

'43'

'L###m'

'43 m'

'43'

'R###m'

' 43m'

'43'

'"0"R###m'

'043m'

'1234567890'

'L###-#######'

'123-4567890'

'123456789'

'L#3-#3-#3'

'123-456-789'

'12345'

'L#'

'1'

'12345'

'R#'

'5'

'123456789'

'L#5'

'12345'

'123456789'

'R#5'

'56789'

'12345'

'L#6'

'12345 '

'12345'

'R#6'

' 12345'

'A LONG LINE'

'6T'

'A LONGTMLINE  '

'A LONG LINE'

'7T'

'A LONGTMLINE   '

'A LONG LINE'

'8T'

'A LONGTMLINE    '

'A LONG LINE'

'8R'

'A LONG LTMINE'

'BANANAS'

'3T'

'BANTMANATMS  '

'1.236'

'2'

'1.24'