Numeric conversion items – DD / DX / XD / XX


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.






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:




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.


Calculation-operand:


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.


Column-reference:


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.






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: Full-featured EPub generator