Convert External Form to Numeric Value (CVTEFN)

Instruction Syntax

Operand 2: Character scalar or data-pointer-defined character scalar.

Operand 3: Character(3) scalar, null, or data-pointer-defined character(3) scalar.

Built-in number for CVTEFN is 136.
CVTEFN (
  receiver              : address of signed binary OR
                          address of unsigned binary OR
                          address of zoned decimal (1 to 63 digits) OR
                          address of packed decimal (1 to 63 digits)
  receiver_attributes   : address
  source                : address
  source_length         : address of unsigned binary(4)
  mask                  : address
)

Description:

This instruction scans a character string for a valid decimal number in display format, removes the display character, and places the results in the receiver operand. The operation begins by scanning the character string value in the source operand to make sure it is a valid decimal number in display format.

Valid types for the receiver are: packed or zoned decimal, signed or unsigned binary.

The character string defined by source consists of the following optional entries:

• Currency symbol - This value is optional and, if present, must precede any sign and digit values. The valid symbol is determined by mask. The currency symbol may be preceded in the field by blank (hex 40) characters.
• Sign symbol - This value is optional and, if present, may precede any digit values (a leading sign) or may follow the digit values (a trailing sign). Valid signs are positive (hex 4E) and negative (hex 60). The sign symbol, if it is a leading sign, may be preceded by blank characters. If the sign symbol is a trailing sign, it must be the rightmost character in the field. Only one sign symbol is allowed.
• Decimal digits - Up to 63 decimal digits may be specified. Valid decimal digits are in the range of hex F0 through hex F9 (0-9). The first decimal digit may be preceded by blank characters (hex 40), but hex 40 values located to the right of the leftmost decimal digit are invalid.

The decimal digits may be divided into two parts by the decimal point symbol: an integer part and a fractional part. Digits to the left of the decimal point are interpreted as integer values. Digits to the right are interpreted as a fractional values. If no decimal point symbol is included, the value is interpreted as an integer value. The valid decimal point symbol is determined by mask. If the decimal point symbol precedes the leftmost decimal digit, the digit value is interpreted as a fractional value, and the leftmost decimal digit must be adjacent to the decimal point symbol. If the decimal point follows the rightmost decimal digit, the digit value is interpreted as an integer value, and the rightmost decimal digit must be adjacent to the decimal point.

Decimal digits in the integer portion may optionally have comma symbols separating groups of three digits. The leftmost group may contain one, two, or three decimal digits, and each succeeding group must be preceded by the comma symbol and contain three digits. The comma symbol must be adjacent to a decimal digit on either side. The valid comma symbol is determined by mask.

Decimal digits in the fractional portion may not be separated by commas and must be adjacent to one another.

Examples of external formats follow. The following symbols are used.

$

currency symbol

.

decimal point

,

comma

D

digit (hex F0-F9)

blank (hex 40)

+

positive sign

-

negative sign

Mask must indicate a 3-byte character scalar. Byte 1 of the string indicates the byte value that is to be used for the currency symbol. Byte 2 of the string indicates the byte value to be used for the comma symbol. Byte 3 of the string indicates the byte value to be used for the decimal point symbol. Unpredictable results can occur if the same value is used for more than one symbol. If mask is null for a non-bound program, the currency symbol (hex 5B), comma (hex 6B), and decimal point (hex 4B) are used.

If the syntax rules are violated, a conversion (hex 0C01) exception is signaled. If not, a zoned decimal value is formed from the digits of the display format character string. This number is placed in the receiver operand following the rules of a normal arithmetic conversion.

If a decimal to binary conversion causes a size (hex 0C0A) exception to be signaled, the binary value contains the correct truncated result only if the decimal value contains 15 or fewer significant nonfractional digits.

A data-pointer-defined receiver with 8 byte binary attributes is not supported and will cause a scalar value invalid (hex 3203) exception to be signaled.

Authorization Required

• None

Lock Enforcement

• None

Exceptions

• 06 Addressing
  • 0601 Space Addressing Violation
  • 0602 Boundary Alignment
  • 0603 Range
• 08 Argument/Parameter
  • 0801 Parameter Reference Violation
• 0C Computation
  • 0C01 Conversion
  • 0C0A Size
• 10 Damage Encountered
  • 1004 System Object Damage State
  • 1044 Partial System Object Damage
• 1C Machine-Dependent
  • 1C03 Machine Storage Limit Exceeded
• 20 Machine Support
  • 2002 Machine Check
  • 2003 Function Check
• 22 Object Access
  • 2201 Object Not Found
  • 2202 Object Destroyed
  • 2203 Object Suspended
  • 2208 Object Compressed
  • 220B Object Not Available
• 24 Pointer Specification
  • 2401 Pointer Does Not Exist
  • 2402 Pointer Type Invalid
• 2E Resource Control Limit
  • 2E01 User Profile Storage Limit Exceeded
• 32 Scalar Specification
  • 3201 Scalar Type Invalid
  • 3202 Scalar Attributes Invalid
  • 3203 Scalar Value Invalid
• 36 Space Management
  • 3601 Space Extension/Truncation
• 44 Protection Violation
  • 4401 Object Domain or Hardware Storage Protection Violation
  • 4402 Literal Values Cannot Be Changed