NLFMTNUM

Syntax

            I16V     CA        I16V      CA         I16V
  NLFMTNUM (langnum, instring, inlength, outstring, outlength,
  
    U16A   U16A     U16V     I16V      O-V
    error, numspec, fmtmask, decimals);

Parameters

langnum

16-bit signed integer by value (required)

Contains the language ID number, specifying which format to use.

instring

character array (required)

Contains the NATIVE-3000 formatted ASCII number to be converted (for example, $123,456.78). Leading and trailing blanks are allowed.

inlength

16-bit signed integer by value (required)

Contains the length, in bytes, of instring.

outstring

character array (required)

Contains the returned language-specific formatted number. The decimal separator, thousands separator, and currency symbol/name are replaced (if present), or are inserted (if specified by fmtmask), according to the language definition. The outstring can reference the same address as instring.

outlength

16-bit signed integer by value (required)

Contains the length, in bytes, of outstring. After a successful call, if outstring is returned left-justified (specified by fmtmask), outlength returns the actual length, in characters, of the formatted number.

error

16-bit unsigned integer array (required)

Returns two elements: the first element is the error number; the second element is reserved and always returns 0. The possible error number values are:

Value

Meaning

0

Successful

1

*NLS not installed

2

*Specified language not configured

3

Invalid length specified (inlength or outlength)

4

Invalid number specified (instring)

5

*NLS internal error

6

*NLS internal error

7

Truncation occurred (outstring partially formatted)

8

Invalid numspec parameter

9

Invalid fmtmask parameter

10

Invalid decimals parameter

* Do not apply to calls with a langnum equal to 0 (NATIVE3000/XL).

numspec

16-bit unsigned integer array (optional)

Contains format specifications, returned from NLNUMSPEC, for the specified language (currency/name, decimal separator, and so on). If this parameter is present, langnum is ignored, and performance is improved.

fmtmask

16-bit unsigned integer by value (optional)

Contains formatting specifications for the input. The default value is 0, a simple substitution.

Bits

Value/Meaning

15:1

Thousands separators:

0

Do not insert thousands separators

1

Insert thousands separators

14:1

Decimal separators:

0

Do not insert decimal separators

1

Insert decimal separators

13:1

Currency symbol/name:

0

Do not insert currency symbol/name

1

Insert currency symbol/name

11:2

Output justification:

0

Do not justify output

1

Left-justify output

2

Right-justify output

3

Left-justify output and return the formatted number length in outlength

0:11

Reserved for the operating system

decimals

16-bit signed integer by value (optional)

Specifies where to insert the decimal separator. The value is ignored if bit 14 of fmtmask is zero or if a decimal separator is present in the number.

Operation Notes

Substitution mode

If fmtmask is omitted or has all bits set to zero, the substitution mode substitutes the native equivalent for "." and ","; for ARABIC, it substitutes the alternative set of digits for ASCII digits. The input is not validated as a number and can contain several numbers. No justification takes place, and the output is left-truncated if outstring is shorter than instring (for example, 1,234.56 becomes ,234.56).

Formatting mode

If any bit 10-15 in fmtmask is set to one, the formatting performs the substitution and formats the input according to fmtmask. In this mode, input is validated as a number, and only ASCII digits and ".", ",", "-", "+", and "$" are allowed. Only one sign and one "$" are allowed. They must be the character(s) in instring. Even if insertion (of the separators) is specified in fmtmask, the thousands and decimal separators are still valid characters in the input. In this case, they are substituted. If no justification is specified, the output is right-justified with the same number of trailing spaces as the input. If the output is truncated, it is left-truncated.

NOTE: For languages written right-to-left, trailing spaces in the input are preserved as leading spaces in the output.

Related Information

Intrinsics

NLCONVNUM, NLNUMSPEC

Manual

Native Language Programmer's Guide