DTW_FORMAT

AIX HP-UX Linux OS/2 OS/390 OS/400 PTX SUN Win NT
X X X X X X X X X

Purpose

Customizes the formatting for a number.

Format

@DTW_FORMAT(number, before, after, expp, expt, precision, result)

@DTW_FORMAT(number, before, after, expp, expt, result)

@DTW_FORMAT(number, before, after, expp, result)

@DTW_FORMAT(number, before, after, result)

@DTW_FORMAT(number, before, result)

@DTW_FORMAT(number, result)

@DTW_rFORMAT(number, before, after, expp, expt, precision)

@DTW_rFORMAT(number, before, after, expp, expt)

@DTW_rFORMAT(number, before, after, expp)

@DTW_rFORMAT(number, before, after)

@DTW_rFORMAT(number, before)

@DTW_rFORMAT(number)

Parameters

Table 64. DTW_FORMAT Parameters
Data Type Parameter Use Description
float number IN A variable or literal string representing a number.
integer before IN A variable or literal string representing a positive whole number. This is an optional parameter. You must enter a null string ("") to have additional parameters.
integer after IN A variable or literal string representing a positive whole number. This is an optional parameter. You must enter a null string ("") to specify additional parameters.
integer expp IN A variable or literal string representing a positive whole number. You must specify a null string ("") to specify additional parameters.
integer expt IN A variable or literal string representing a positive whole number. You must enter a null string ("") to specify additional parameters.
integer precision IN A variable or literal string representing a positive whole number that specifies the precision of the result. The default is 9.
float result OUT A variable that contains the number with the specified rounding and formatting.

Return Codes

Table 65. DTW_FORMAT Return Codes
Return Code Explanation
-1001 The server could not process a Net.Data request to allocate memory.
1001 An input parameter contained a NULL value.
1002 An input parameter contained a string value which consisted of the null-terminating character.
1003 An incorrect number of parameters were passed on a function call.
1005 A parameter passed on a function call, required to be a string variable, was of a different variable type.
1006 A literal string was passed on a function call for a parameter which was required to be an output parameter.
4000 A parameter contains an invalid whole number value.
4001 A parameter contains an invalid number value.

Usage Notes

  1. If number is the only parameter is specified, the result is formatted as if @DTW_rADD(number,"0") was executed.
  2. The before and after parameters describe how many characters are used for the integer and decimal parts of the result parameter, respectively. If you omit either or both of these parameters, the number of characters used for that part is as many as is needed.
  3. If the before parameter is not large enough to contain the integer part of the number (plus the sign for a negative number), an error results. If the before parameter is larger than needed for that part, the number parameter value is padded on the left with blanks. If the after parameter is not the same size as the decimal part of the number parameter, the number is rounded (or extended with zeros) to fit. Specifying 0 causes the number to be rounded to an integer.
  4. The expp and expt parameters control the exponent part of the result. The expp parameter sets the number of places for the exponent part; the default is to use as many as is needed (which may be zero). The expt parameter sets the trigger point for use of exponential notation. The default is the default value of the precision parameter.
  5. If expp is 0, no exponent is supplied and the number is expressed in simple form with added zeros as necessary. If expp is not large enough to contain the exponent, an error results.
  6. If the number of places needed for the integer or decimal part exceeds expt or twice expt, respectively, use the exponential notation. If expt is 0, exponential notation is always used unless the exponent is 0. (If expp is 0, this overrides a 0 value of expt.) If the exponent is 0 when a nonzero expp is specified, then expp+2 blanks are supplied for the exponent part of the result. If the exponent is 0 and expp is not specified, the simple form is used.

Examples

Example 1:

@DTW_FORMAT(NUM, BEFORE, result)

Example 2:

@DTW_FORMAT("1.73", "4", "0", result)

Example 3:

@DTW_FORMAT("1.73", "4", "3", result)

Example 4:

@DTW_FORMAT(" - 12.73", "", "4", result)

Example 5:

@DTW_FORMAT("12345.73", "", "", "2", "2", result)

Example 6:

@DTW_FORMAT("1.234573", "", "3", "", "0", result)

Example 7:

@DTW_rFORMAT(" - 12.73")

Example 8:

@DTW_rFORMAT("0.000")

Example 9:

@DTW_rFORMAT("12345.73", "", "", "3", "6")

Example 10:

@DTW_rFORMAT("1234567e5", "", "3", "0")

Example 11:

@DTW_rFORMAT("12345.73", "", "3", "", "0")


[ Top of Page | Previous Page | Next Page | Index ]