A numeric conversion item is used to convert and reformat data between decimal and hex numeric format (using DX or XD commands), or to modify the format of a decimal or hex number without converting it (using DD or XX commands). A decimal number is considered to be a span of characters in the range of 0-9; a hex number is considered to be a span of characters in the range of 0-9, A-F or a-f. Note that numeric conversions are designed for processing integer values only; if used on a floating-point number, it may not work or may only process the part to the left of the decimal point.

When you specify a “simple” conversion item, the complete column range is expected to contain valid digits of the type indicated; otherwise an error is reported.

However, sometimes numeric data may not be in precise locations. For instance, you may have a comma-separated list of values of varying numbers of digits, and it may be necessary to “scan” your data to determine where the number is located. Your data may have leading or trailing spaces. You might need to find it using a left-to-right scan, or possibly a right-to-left scan. You may need to control how the converted number is formatted. To do these things, you can use a “formatted” conversion item.

When you use these commands, the numeric value is first converted internally to a 64-bit integer; this limits the values to 16 hex digits or 19 decimal digits. Note that no check is made for numeric overflow, so do not exceed these limits. If your command includes a calculation-operand, the integer value is passed to the calculator function, which can be used to calculate a derived value from your original number. Finally, this integer is converted to a decimal or hex string value.

Syntax of a numeric conversion item:

 {  fixed-location-command  |  floating-location-command    }   [  format  ]  [  sign-code  ]  

[  calculation-operand  ]  column-reference

 Fixed-location-command :   DD | DX | XD | XX

Defines the type of numeric conversion to be done. The columns selected may optionally contain leading and trailing spaces, and may optionally contain a leading + or  sign, but otherwise must be entirely numeric. The selected field must contain one and only one numeric value.

  • DX converts selected columns of data from decimal characters to hex characters. When the resulting value contains hex digits greater than 9, by default, these digits will be rendered as upper-case A-F. If a case conversion code of > (convert to upper case) or < (convert to lower case) is in effect prior to the DX code, those case conversions will be respected, and hex-digit characters will be rendered accordingly. Otherwise, you can use a case alteration code of UC, LC, SC, TC or IC afterwards, to alter the contents of the result string once it has been formed.

  • XD converts selected columns of data from hex characters to decimal characters.

  • DD recognizes selected columns of decimal characters, allowing them to be reformatted while remaining as a decimal number.

  • XX recognizes selected columns of hex characters, allowing them to be reformatted while remaining as a hex number.

Floating-location-command :

Floating DD , DX, XD and XX items have a special alternate syntax, as follows:

       nDD  |  DnD

       nDX  |  DnX

       nXD  |  XnD

       nXX  |  XnX


The number n is a relative field location when a numeric field is “floating” rather than being in fixed column positions. If n is used, it must be a single decimal digit in the range of 1-9 (a digit of 0 should not be used). See Handling of “floating” values below.

Format:    [  w  ]   t

t :    {  F  |   |  V  }

Provides a means of describing the resulting format of the numeric value:

  • w  is a width field, specified as a numeric value of one or more decimal digits. The w value is optional. If omitted for type V, the w value is assumed to be 1. If omitted for types F and Z, the width of the output made the same as the input. For example, if you use a command of DXF, and the original decimal number had 3 digits, the hex value will have 3 digits, as if you had specified DX3F. A w value of 0 is treated the same as 1.

  • t  is a format type code letter.  Type F causes the converted value to be held in a fixed number of columns, as specified by the w value, with non-significant positions on the left filled with “0” characters. Type Z causes the converted value to be held in a fixed number of columns, as specified by the w value, with non-significant positions on the left filled with blank characters. Type V causes the converted value to be rendered in a variable number of columns. For type V, the w value specifies the minimum number of digits to be rendered; if the numeric value does not need the full width w to hold the value, the result is padded with “0” characters sufficient to make the field at least w characters wide; if the value needs more than w characters to represent it, no padding characters are used.

Sign-code:  [   |  C  ]

If sign code S is present, any leading + or  sign found during processing will be retained and copied to result string. If sign code S is absent, any leading + or  signs are ignored. Any spaces after the leading + or  sign are considered to be part of the sign.

If sign code C is present, it is treated like sign code S is, with the following addition:  If a number contains a 0x or 0X prefix (as used in C, Java, and similar languages), that prefix is considered to be part of the sign, and not part of a number. The reason code C is needed is that without it, a value like 0x12 might be misinterpreted to be two numbers, 0 and 12, separated by a delimiter of “x”. When converting from hex to decimal and a sign code C is present, any 0x or 0X prefix is dropped. When converting from decimal to hex and a sign code C is present, a 0x prefix is added.


Allows arithmetic operations to be performed on the base numeric value before it is formatted. For a complete description of mapping string calculation operations, see Calculation Operands.

For example, to perform a decimal-to-decimal reformatting with 4 fixed digits, and have the value multiplied by 2 and then having 3 added to it, you would specify a command of  DD4F'X*2+3' or  DD4F'*2+3.


Selects the columns of data in the source string that are to be converted (unless dot notation is used to select column of data from the result string). The syntax of this field are the same as an ordinary column reference. A single column, remaining-columns, forward column-range or reverse column range may be requested. No spaces or other characters not part of the syntax may appear between the conversion codes of DX , XD, DD or XX (or their formatted counterparts), and the column-reference specification. (It is possible to select columns in such a way as to reverse the order of the original digit characters, but this would not generally be very useful.)

Commands DX and XD involve a change of radix between decimal and hex. Commands DD and XX do not involve a change of radix between decimal and hex. For all commands, decimal or hex numeric strings are scanned for and recognized, and then reformatted using the width and format types. DD may be thought of as “decimal-to-decimal” and XX as “hex-to-hex”.

Handling of “floating” values

When a floating-location-command with the n parameter is used, SPFLite will perform a “scan” of the selected value, looking for “spans” of digits. A “span” of digits is a contiguous span of characters that are valid for the type of number being converted.

The idea is that the value you are interested in is present somewhere in the columns of data you have selected, but the precise location where that numeric field is may vary, or “float” from one particular instance of found data to the next. That is, if you repeatedly execute your CHANGE command with a mapping string, between one execution of CHANGE to the next, the exact place where your numeric data happens to be located may vary. So, trying to “grab” such numeric data with a fixed column range won’t work.

For DX-type and DD-type conversions, spans of digit characters must be in the range 09, and for XD-type and XX-type conversions, spans of digits must be in the range 09, AF or af. A “span” of digits is delimited by (a) the beginning and/or end of the selected value, or (b) any character outside the range of valid digits. After SPFLite performs such a scan, it is an error if a valid numeric value cannot be found. Bear in mind that “any” character that could act as a delimiter may be one you did not expect, such as a letter like R. You should understand your data to determine if these rules meet your requirements. Most numeric data you deal with will be delimited by commas or blanks, which will work fine. These commands cannot analyze your data any more precisely than determining if a character “is a digit” or “is not a digit” when looking for numbers.

You are free to scan the same original columns of data multiple times, selectively extracting more than one numeric value, by using a different n value to determine the relative location where the desired numeric value is to be taken from.

A “floating” command can be directed to perform its scanning process either in a left-to-right manner, or in a right-to-left manner. The way this is indicated is in the positioning of the n parameter.

    • When the n value appears to the left of the command code, like 3DX or 3XD, it causes the scan to be done in a left-to-right manner. Here, 3DX means to look for the third span of decimal digits (the third decimal number) going left-to-right. 3XD means to look for the third span of hex digits (the third hex number) going left-to-right.

    • When the n value appears to the right of the first letter of the command code, like D3X or X3D, it causes the scan to be done in a right-to-left manner. Here, D3X means to look for the third span of decimal digits going right-to-left. X3D means to look for the third span of hex digits going right-to-left.

    • The same rules apply to commands of types DD and XX, when an n value is used, except that no radix conversion takes place.

Caution regarding the processing of floating-point (“real”) values

Be mindful that the numeric conversion items are designed to operate on integer values, not on floating-point (“real”) values that contain decimal points. For instance, if your data looks like “123.456  654.321”, and you attempt to use a “floating” version of the numeric conversion commands, this string will appear to have four numbers; namely, 123, 456, 654 and 321. The decimal points will not be treated as part of the numeric values, but as delimiters. Using a “floating” command, the value 654 is the third value from the left, not part of a second value.

See the Quick Reference for examples on how to use numeric conversion items.


Created with the Personal Edition of HelpNDoc: Easy to use tool to create HTML Help files and Help web sites