USING

USING operator formats a numeric or DATE operand according to the specified pattern:

where format-string is a character string that sets the pattern for formatting the operand.

For example,

DISPLAY v_integer USING "---,---,---,--&.&&"

DISPLAY v_date USING "ddd"

USING is typically used in DISPLAY and PRINT statements but you can also use it with LET to assign the formatted value to a character variable.

If a value is too large for the field, 4gl fills it with asterisks (*) to indicate an overflow.

Symbols that the USING operator recognizes in format-string are described below.

Formatting numeric expressions

With numeric or MONEY operands, you can use the USING operator

• to align decimal points or currency symbols,
• to right- or left-align numbers,
• to put negative numbers in parentheses, and
• to perform other formatting tasks. 

The USING operator takes precedence over the DBMONEY or DBFORMAT environment variables and is required to display the thousands separator of DBFORMAT.

When 4gl displays a number value, it follows these rules:

1. 4gl displays the leading currency symbol for MONEY values as set by DBFORMAT or DBMONEY or as specified by the FORMAT attribute (for .per forms).
2. 4gl omits thousands separators unless they are specified by the FORMAT attribute or by the USING operator.
3. 4gl displays the decimal separator, except for INT or SMALLINT values.
4. 4gl displays the trailing currency symbol for MONEY values as set by DBFORMAT or DBMONEY or as specified by the USING operator or the FORMAT attribute (for .per forms). In this case, the user cannot enter a trailing currency symbol, and 4gl does not display it.

Symbols that can be used in formatting patterns

format-string can include these characters:

* (asterisk)	fills any spaces in the display field that would normally be blank with asterisks
& (ampersand)	fills any spaces in the display field that would normally be blank with zeros
# (hash)	can be used to specify the maximum width of a field (does not have any effect on blank spaces)
<	left-aligns all numbers in a field
, (comma)	is a literal character – USING displays it as a comma when there is a number to the left of it
. (period)	is a literal character – USING displays it as a period. Only one period can appear in a number format string where it is used as the decimal point.
– (minus)	is a literal character – USING displays it as a minus sign but only with negative numeric expressions. When several hyphens are placed in a row, only one is displayed. This floats one character space to the left of the printed number.
+ (plus)	is a literal character – USING displays it as a plus sign when the expression is positive or equal to zero. When the expression is negative, it automatically displays as a minus sign.  When several plus signs are placed in a row, only one is displayed. This floats one character space to the left of the number being printed.
$ (dollar)	is a literal character – USING displays it as such. When several dollar signs are placed in a row, only one is displayed. This floats one character space to the left of the number being printed.
(	is displayed before a negative number. Is known as the accounting parenthesis because in accounting negative numbers are displayed within parentheses rather than preceded by a minus sign.
)	is displayed after a negative number when the left parenthesis was displayed before it.

 

The minus sign (–), plus sign (+), parentheses, and dollar sign ($) float: This means that when you put several of them in front of the expression (= multiple leading occurrences) 4GL displays only one single character instead of many.

Any other character in format-string is interpreted as a literal.

 

This example program prints a MONEY value using a formatting pattern that allows values upto $9,999,999.99 to be formatted correctly.

This example uses #, &, +, and < characters:

• # provides blank fill for unused character positions
• & provides zero filling. This format ensures that even if the number is zero, any positions marked with & will appear as zero, not blank
• + means that the expression is positive or equal to zero
• < left-aligns all numbers in a field

Dollar signs can be used instead of # characters as here:

In the above piece of code, the currency symbol floats with the size of the number so that it appears immediately to the left of the most significant digit in display – like this:

Total amount due: $14,187.00

By default, 4GL displays numbers right-aligned. You can use the < symbol in your USING formatting pattern to override this default.

For example, this piece of code

produces this output:

Total amount due: $14,187.00

Formatting DATE values

USING can also convert a DATE operand to a variety of formats.

When you use it to format DATE value, USING takes precedence over any DBDATE environment variable settings.

 

The format-string value for a date can be a combination of these characters – m, d, and y:

dd	day of the month from 01 up to 31 (depends on the month)
ddd	day of the week as a three letter abbreviation (Mon, Tue, etc.)
mm	month of the year from 01 to 12
mmm	month of the year as a three letter abbreviation (Jan, Feb, etc.)
yy	year of the century in the two-digit representation (from 00 to 99)
yyyy	year in the four-digit representation (from 0001 to 9999)

Any other characters within the formatting pattern for DATE values are interpreted as literals.

 

Here are some examples of formatting patterns and the results returned by USING. The pattern was applied to this date – December 25, 2020.

"mmddyy"	122520
"ddmmyy"	251220
"yymmdd"	201225
"yy/mm/dd"	20/12/25
"yy mm dd"	20 12 25
"yy-mm-dd"	20-12-25
"mmm. dd, yyyy"	Dec. 25, 2020
"mmm dd yy"	Dec 25 2020
"yyyy dd mm"	2020 25 12
"mmm dd yyyy"	Dec 25 2020
"ddd, mmm. dd, yyyy"	Sat, Dec. 25, 2020
"(ddd) mmm. dd, yyyy"	(Sat) Dec. 25, 2020

These examples show valid resulting displays for the default U.S. English locale.

 

This example programs demonstrates how to use the USING operator for DATE values:

When you use non-default locales, the NUMERIC and MONETARY categories in the locale files affect how the format string of the USING operator is interpreted for formatting number and currency data values.

In the formatting pattern, period (.) is not a literal character but a placeholder for the decimal separator. Likewise,

• comma (,) is a placeholder for the thousands separator
• dollar sign ($) is a placeholder for the leading currency symbol
• @ is a placeholder for the trailing currency symbol.

Thus, the formatting pattern $#,###.## formats the value 1234.56 as £1,234.56 in a U.K. English locale, but as €1.234,56 in a French locale. To override these locale settings, you must set either DBMONEY or DBFORMAT .

mmm and ddd specifiers display language-specific abbreviations for the names of months and days. To get the correct abbreviations, you must set the LANG environment variable and install the appropriate locale on your local operating system.

Simple examples for the USING operator

In the tables below, you will find many simple examples of formatting patterns and returned values.

All the examples are provided for the default U.S. English locale.