Character conversion items – AX / XA / EX / XE

A character conversion item is used to convert data to and from character mode and ASCII or EBCDIC encoding.  This conversion is applied to a specified column range of original data.  To perform this operation on the current contents of the result string, specify a . dot symbol instead of, or in addition to, a standard column-range operand.

Note that when dealing with EBCDIC conversions, special considerations apply:

    1. Character conversion items in mapping strings do not know or respect the data type of the underlying file.  You must know this, and apply the correct conversion for the data you are working with.  That is your responsibility.

    1. The facility for the EX and XE codes is described here supports EBCDIC.  When you do this, SPFLite will supply a default EBCDIC translation table corresponding to code page 1140.   This is identical to the supplied EBCDIC.SOURCE code page that comes with SPFLite.  There is no way to override this default.

    1. You must bear in mind that, internally, SPFLite only processes data as ASCII (Ansi) characters.  In an EBCDIC-encoded file, when you see a character like '1' displayed in an edit session, SPFLite sees it as an ASCII value of X'31', but in your data file, it exists as X'F1'.  The way editing works for EBCDIC files is that your EBCDIC data is brought into an edit session and temporarily converted to ASCII as you edit.  When the file is saved, it is converted back to EBCDIC.

    1. When character conversion items are introduced into this environment, if you have original EBCDIC data like X'F1', it is first converted to X'31' to make it an ASCII character '1' that you recognize, when the file is opened.  If you then ask for this '1' to be converted to hex using EX, the '1' which is internally held as X'31' is first converted to a byte value of X'F1', and then that is converted to the two ASCII characters "F1".  Likewise, if you ask for the two characters "F1" to be converted using XE, they are first converted a single byte with the value X'F1'.  This byte value is then converted from EBCDIC to ASCII, which is X'31'.  That byte value becomes the result, which appears as the ASCII character '1' in your edit session.  When your EBCDIC file is saved, that ASCII '1' will get translated (again) back to EBCDIC, resulting your file containing an EBCDIC '1' value of X'F1'.  

This may all seem rather complex, but the underlying goal is to help you “maintain the illusion” that this Ansi-based editor is really editing EBCDIC, as if you were actually running on a mainframe.  SPFLite is able to maintain this illusion by very carefully translating your data at precisely the right time, and by requiring its translation tables to conform to “lossless” conversion in both directions.  SPFLite’s default EBCDIC table meets that requirement.

Syntax of a character conversion item:

       { AX | XA | EX | XE }  [ bypass-string ]  column-reference

AX | XA | EX | XE:

Defines the type of character conversion to be done:


Defines an optional string containing one or more characters to be bypassed.  The idea behind the bypass string is that you might have several spans of normal characters, or hex-digit characters, separated by blanks, commas, etc. and you want to convert the “real” data, but not the “delimiter” data.  Any spans of characters contained within the bypass string are ignored for conversion purposes and are copied as-is to the result string in their relative locations, and the conversion process applies only to the remaining (non-bypassed) data.  Bear in mind that, for XA and XE conversions, each span of characters that may be delimited by these bypass characters must individually be of even length and contain only hex-digit characters.


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 AX, XA, EX or XE, and the column-reference specification.

For codes XA and XE, the column reference field must result in a selection of an even number of characters, which must consist of valid hex-digit characters.   For this reason, care must be taken when using a remaining columns reference, such as XA22+.  If the source data value was obtained using a Regular Expression, it is possible that the number of characters in it is variable and unpredictable, and could unexpectedly be of odd length.  In those cases, it may not be possible to perform XA or XE conversions on your data.  You may have to ‘normalize’ your data to ensure it only contains an even number of hex-digit characters.

For conversion codes AX and EX, 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 AX or EX 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.

Created with the Personal Edition of HelpNDoc: Easy EPub and documentation editor