USING

USING operator specifies a character-string format for a number, MONEY, or DATE operand and returns the formatted value.

Usage

With a number or MONEY operand, 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.  USING can also convert a DATE operand to a variety of formats.

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 in "The USING Formatting Symbols for Number Values" section and the "Formatting DATE Values" section of this volume for number values and DATE values respectively.

Formatting Number Expressions

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:

• GL displays the leading currency symbol (as set by DBFORMAT or DBMONEY) for MONEY values. (But if the FORMAT attribute also specifies a leading currency symbol, 4GL displays that symbol for other data types.)

• 4GL omits the thousands separators, unless they are specified by a FORMAT attribute or by the USING operator.

• 4GL displays the decimal separator, except for INT or SMALLINT values.

• 4GL displays the trailing currency symbol (as set by DBFORMAT or DBMONEY) for MONEY values unless you specify a FORMAT attribute or the USING operator. In this case, the user cannot enter a trailing currency symbol, and 4GL does not display it.

USING Formatting Symbols for Number Values

The format-string value can include the following characters.

The minus sign ( - ), plus sign ( + ), parentheses, and dollar sign ( $ ) float, meaning that when you specify multiple leading occurrences of one of these characters, 4GL displays only a single character immediately to the left of the number that is being displayed. Any other character in format-string is interpreted as a literal.

These characters are not identical to the formatting characters that you can specify in the format-strings of the FORMAT or PICTURE field attributes.

For examples of using format strings for number expressions, see "Examples of the USING Operator" further on in this section.  Because format strings interact with data to produce visual effects, you might find that the examples are easier to follow than the descriptions on the previous page of USING format string characters.

The following example prints a MONEY value using a format string that allows values up to $9,999,999.99 to be formatted correctly.

MAIN

DEFINE mon_val1, mon_val2 MONEY(8,2)

      LET mon_val1 = 43243.18

      LET mon_val2 = -18589.57

      DISPLAY "*** USING Example 1 ***" AT 1,5

      DISPLAY "43243.18 -  $#,###,##&.&& -   The current balance is  :", mon_val1 USING "$#,###,##&.&&" at 3,5

      DISPLAY "43243.18 -  +$#,###,##&.&& -  The current balance is  :", mon_val1 USING "+$#,###,##&.&&" at 4,5

      DISPLAY "-18589.57 - -$#,###,##&.&& -  The current balance is  :", mon_val2 USING "-$#,###,##&.&&" at 5,5

      DISPLAY "-18589.57 - $#,###,##&.&& -   The current balance is  :", mon_val2 USING "$#,###,##&.&&" at 6,5

      DISPLAY "-18589.57 - $(#,###,##&.&&) - The current balance is  :", mon_val2 USING "$(#,###,##&.&&)" at 7,5

      DISPLAY "-18589.57 - €(#'###'##&,&&) - The current balance is  :", mon_val2 USING "€(#'###'##&,&&)" at 8,5

      DISPLAY "43243.18 -  $<<,<<<,<<&.&& -  The current balance is  :", mon_val1 USING "€<<,<<<,<<&.&&" at 9,5

      CALL fgl_winmessage("Exit","Press any key to close this demo application","info")

END MAIN

The above examples also use the # and & fill characters. The # character provides blank fill for unused character positions, while the & character provides zero filling. This format ensures that even if the number is zero, any positions marked with & appear as zero, not blank.

Dollar signs can be used instead of # characters, as in the following statement:

DISPLAY "Total amount due:  ",inv_total

      USING "$$,$$$,$$&.&&"

In this example, the currency symbol floats with the size of the number so that it appears immediately to the left of the most significant digit in the display. This example would produce the following formatted output, if the value of the inv_total  variable were 14187.00:

Total amount due: $14,187.00

By default, 4GL displays numbers right aligned. You can use the < symbol in a USING format string to override this default. For example, specifying

DISPLAY "

Total amount due: ", inv_total

USING "$<<,<<<,<<&.&&"

produces the following output when the value of inv_total is 14187.00:

The current balance is $14,187.00

Formatting DATE Values

When you use it to format a DATE value, USING takes precedence over any DBDATE or GL_DATE environment variable settings. The format-string value for a date can be a combination of the characters m, d, and y.

In these instances lowercase letters must be used; uppercase will not be recognized.

Any other characters within a USING formatting mask for DATE values are interpreted as literals.

The following examples show valid format-string masks for December 25, 1999, and the resulting display for the default U.S. English locale.

This example programs demonstrates all different date formats:

MAIN

  DEFINE my_date DATE, inp_char char(1)

  LET my_date = today

  DISPLAY "*** USING Example 2 ***" AT 3,5

  DISPLAY "using mmddyy:              ", my_date USING "mmddyy" at 5,5

  DISPLAY "using ddmmyy:              ", my_date USING "ddmmyy" at 6,5

  DISPLAY "using mmddyy:              ", my_date USING "yymmdd" at 7,5

  DISPLAY "using yy/mm/dd:            ", my_date USING "yy/mm/dd" at 8,5

  DISPLAY "using yy mm dd:            ", my_date USING "yy mm dd" at 9,5

  DISPLAY "using yy-mm-dd:            ", my_date USING "yy-mm-dd" at 10,5

  DISPLAY "using mmm. dd, yyyy:       ", my_date USING "mmm. dd, yyyy" at 11,5

  DISPLAY "using mmm dd yyy:          ", my_date USING "mmm dd yyy" at 12,5

  DISPLAY "using yyyy dd mm:          ", my_date USING "yyyy dd mm" at 13,5

  DISPLAY "using mmm dd yyyy:         ", my_date USING "mmm dd yyyy" at 14,5

  DISPLAY "using ddd, mmm. dd, yyyy:  ", my_date USING "ddd, mmm. dd, yyyy" at 15,5

  DISPLAY "using mmm dd yyyy:         ", my_date USING "mmm dd yyyy" at 16,5

  Prompt "Press any key to close this demo application" FOR inp_char

END MAIN

Using 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 format string, the period ( . ) is not a literal character but a placeholder for the decimal separator specified by environment variables.  Likewise, the comma is a placeholder for the thousands separator specified by environment variables.  The dollar sign ( $ ) is a placeholder for the leading currency symbol.  The @ symbol is a placeholder for the trailing currency symbol.  Thus, the format string $#,###.## formats the value 1234.56 as £1,234.56 in a U.K. English locale, but as €1.234,56 in a French locale.  Setting either DBFORMAT or DBMONEY overrides these locale settings.

The mmm and ddd specifiers in a format string can display language-specific month-name and day-name abbreviations.  This needs the LANG environment variable to be set, and the appropriate locale to be installed on your local operating system.

Examples of the USING Operator

Tables that follow illustrate some of the capabilities of the USING operator with number or currency operands (for the default U.S. English locale).  Each table has the following format:

• The first column shows a format string (the left-hand operand).

• The second column shows a data value (the right-hand operand).

• The third column shows the resulting formatted display.

• The fourth column provides a comment (for some rows).

In the following table, the character b in the Formatted Result column represents a blank space.

In the following table the character b in the Formatted Result column represents a blank space.

Here the character b in the Formatted Result column represents a blank space.

A third sample code example has been prepared to show how various values would be displayed using the USING operator to define different output formats.  This can be found within the ‘functions’ demonstration application packaged with your Lycia installation.  It is the program called "using3_operator.exe".  If you want to see the program working, or the code in the .4gl file please look at the demonstration application using Lycia.