CNV TEXT

The CNV TEXT statement is bidirectional (data may be converted and then converted back to the original format) and reformats, or converts, data from one data type to another. The CNV TEXT statement sets the destination field equal to the sending field, but in the format of the destination field, including all display mask specifications. CNV TEXT also converts an entire APPX record to an alpha field consisting of a string of the original APPX fields converted to simple alpha fields, or vice-versa.

    ••••• CNV TEXT ••• •••••••••••••••••••••• ••• =  ••• •••••••••••••••••••••• •••
    (1)            (2) (3)                    (4)    (5) (6)                    (7)

Sets True/False Status Indicator

If the conversion is successful, the next true/false status indicator is set to T; otherwise, it is set to F.

Using the Statement

When converting fields, both fields can be specified as either a field name or a predefined field. One of the fields (either the destination or source) must be of a simplified alpha type. A simplified alpha type is one that is not compressed, tokenized, word-wrapped, or masked.

When converting files, a file name must be entered as either the destination or source, and an alpha field name must be entered as the other. If needed, use Option 88 to save the statement.

Source Field Considerations

Either the source field or destination field can be any of the basic data types: alpha, date/time, logic, or numeric. The other field must be simplified alpha.

Converting to/from Alpha Fields

Alpha fields require no data conversion. The data is copied from the source field to the destination field or vice-versa. If the size of the data to be copied is larger than the destination area can contain, the excess is truncated. If the amount of data to be copied is smaller than the destination can contain, blank padding is added. The formatting characteristics of the destination field, such as justification, are imposed upon the converted destination data.

Converting to/from Date/Time Fields

Date/time fields are converted from their specific date/time types into an alpha date form during the conversion operation or vice-versa. This alpha form is either Gregorian or Julian (based on the source field’s data type), and it uses the source field’s display mask.

Converting to/from Logic Fields

If the sending field is a “logical Yes” (a value of 1), the destination field is set to a value of the uppercase Y (in the English language version), followed by pad spaces. If the value of the sending field is “logical No,” the destination field is set to N, followed by pad spaces. If the value of the sending field is blank, the destination field is set to a value of blank. The conversion fails if the value of the sending field is something other than 1, 0, or “ ”. Note these rules also work in reverse.

Converting to/from Numeric Fields

Numeric sending fields are converted from their packed or binary numeric types into an alpha form during the conversion operation. The alpha form is based on the source field’s display mask. If the sending field is null-valued, the alpha form is set to blank. This conversion can also be performed in reverse.

When converting numeric fields to alpha, remember that a display mask on the numeric field can be used to control the format of the result. For example, a display mask can prevent producing negative trailing signs or integer results which may be undesirable in Excel.

Restrictions

When all occurrences of the sending field are selected as the CNV TEXT data (by entering occurrence number 000), all occurrences are treated as a single, rectangular alpha field. When the data is copied from the sending field, a check is made to ensure that soft spaces are compressed, ensuring that the next “word” is separated from the previous one by just one space.

Compilation Errors

If either the source or destination field is not a simplified alpha type, a compilation error occurs. Attempting to convert invalid data is an unrecoverable error.

Invalid dates cannot be converted and cause CNV TEXT to fail.

Execution Errors

Numeric values that cannot be represented by their display masks cannot be converted, and cause the digit placeholders of the mask to be set to ? to indicate a failed conversion.

Example

The following example moves the current date into an alpha field then converts an entire record into an alpha field:

          SET DATE TAR ORDER DATE FIELD
          CNV TEXT TAR WORK ALPHA FIELD           =  TAR ORDER DATE FIELD
          CNV TEXT TAR WORK RECORD                =  TAR TERMS

The alpha fields will include all display formatting characters.