Mobile RPG Double Byte Support

This topic describes Mobile RPG's support for languages which use the Double Byte Character Set (DBCS).

The DBCS is the IBM i's support for languages requiring more than 256 characters. In it, each character is represented by 2 bytes (hence Double-Byte).

The DBCS supports four languages:

• Simplified Chinese
• Traditional Chinese
• Japanese
• Korean

There are multiple CCSIDs that can be used for each of the above languages; these have been introduced and updated over time to include additional characters like the Euro. IBM i and Wings both support Unicode as a special case (support for Unicode was added with Wings 6.0, release 6.1 completed the Double-Byte support).

A great deal of information on the topic can be found in at http://www-03.ibm.com/systems/i.software/globalization/codepages.html in PDF form. It covers the current IBM code pages, many of which are supported by IBM i servers.

DBCS Types

There are 4 "types" of DBCS fields in DDS. For more detail on the types, check here: (http://pic.dhe.ibm.com/infocenter/iseries/v6r1m0/index.jsp?topic=/rzakc/dbcdtype.htm):

• J (Only) – accepts only DBCS characters. The Field Length must be an even number (of bytes). The display station automatically inserts shift-control characters in fields specified with this data type.
• E (Either) – accepts either DBCS or alphanumeric (single byte) characters. The field length must be an even number (of bytes)
  DBCS or alphanumeric characters can be typed into the field. The type of data entered into the field's first position determines the type of data that the rest of the field will accept. If blank, the system assumes alphanumeric data will be entered Positioning the cursor on the field and putting the keyboard in DBCS mode readies the field to accept DBCS data.
• O (Open) – accepts a mixture of single- and double-byte characters. The length must be a multiple of 1 (bytes).
  If the field contains DBCS data, the system does not ensure that the data is enclosed between shift-control characters.
• G (Graphic) — accepts exclusively DBCS data. The length specifies the number of characters, not of bytes.
  Data typed in this field does not contain shift-control characters.

A unicode field is considered type "G" with an explicit CSID value of 1200 for UTF-16 and 13488 for UCS-2.

For more information on Unicode fields in IBM i, check here http://pic.dhe.ibm.com/infocenter/iseries/v6r1m0/topic/rzakc/dspfil.htm

In Mobile RPG the special case for Unicode has been promoted as a separate DBCS type.

DdsCharField and DBCS

The Mobile RPG control for a character field (DdsCharField) is designated DBCS capable by the following properties:

Property	Value
DbcdType	None — Not a DBCS type Unicode – Special version of Graphic with CCSID 13488 or 1200 Open Mixed — single byte/double byte (with shift-controls) Only — Double byte only (with shift-controls) Either — Double byte (with shift-controls or single byte) Graphic — Double byte only (no shift-controls)
Length	Length in characters
DbcsByteLen	Length in Bytes on the RPG program
DisplayPositions	Maximum number of characters to display and accept on the screen

The Mobile RPG Handler converts any DBCS data to Unicode at the RPG program border and keeps it like this in its internal buffer and as the transmission format shown below:

For these conversions to be handled correctly it is imperative that the DbcsByteLen and Length properties be set correctly. DDS provided a single Length attribute for the data; it denotes bytes for types J, E and O, and characters (actually Code Units one unit for the character and potentially another unit for the surrogate) for G.

Importing DDS Definitions

The process of importing DDS into an ASPX has the challenge of determining how many characters are allowed based on the Length found in the DDS source. In the case of Graphic, and Only, the relation is functional, however for Either and Open, it is not deterministic. This is what Mobile RPG does for each type:

DbcsType	Length (characters)	DbcsByteLen	Notes
Unicode Graphic	DD_Len	DDS_Len * 2	None
Only	(DD_Len -2)/2	DDS_Len	Account for 2 shift controls.
Either	(DD_Len -2)/2	DDS_Len	Notice that this is correct if the data is DBCS, however if the data were single byte, then Length should have been set to DDS_Len.
Open	(DD_Len -2)/2	DDS_Len	The hardest case: On one extreme you could have all single byte chars which would mean that Length should be set to DDS_Len, on the other extreme you could have alternating single and double byte chars which would need to set Length=DDS_Len/2.5

Since the developer knows the actual usage of the field, he can reset the value of Length to accommodate the application's needs.

At runtime, it's expected that Length and DbcsByteLen will be available; if DbcsByteLen is missing it will be computed as follows:

DbcsType	DbcsByteLen
Unicode Graphic	Length *2
Only Either Open	Length *2 +2

Sample Data

The following image shows the Traditional Chinese DBCS characters 顯示 whose hex values in CCSID 937 are 686F and 4D9D respectively.

The file MISUCH (library ERCHINA) has multiple fields. The First two are a packed number and a DBCS field of type Open that starts at position 8 called CTRUCK.

The second record of the data file MISUCH includes the '顯示' characters on the CTRUCK field. The byte sequence 0E 686F4F9F 0F include the DBCS characters plus the necessary Shift-Out/Shift-In.

Displaying the two fields in a Mobile RPG/Wings application would look like this:

The CTRUCK field is defined as follows:

<mdef:DdsCharField ID="DdsCharField1" runat="server" Alias="CTRUCK" CssClass="DdsCharField" 
DbcsByteLen="35" DbcsType="Open" Length="17" Lower="True"

In order for the application to work correctly a DG connection must be established, with a user profile that sets the Job's CCSID to a value 'compatible' with the DBCS data that will be manipulated by the program. The sample above was created while running a CCSID of 937 (Mixed Traditional Chinese, NO Euro).

In order to deal with the single byte characters, Mobile RPG uses the translators provided by Windows: The GetEncoding method of the Encoding class. The Translators are not used for the actual DBCS translations, so because there are many CCSIDs that are not recognized by Microsoft, Mobile RPG maps some of the CCSIDs used for Mixed sets to the corresponding CCSID of the single byte portion of the whole set. For example, the CCSID 937 (mixed traditional Chinese NO Euro) is mapped to 37 and the DBCS 1371 (mixed taditional Chinese with Euro) is mapped to 1149. There are even several single byte CCSIDs like 28709 that are mapped, in this case to 1140.

ASNA will continue to map these sets as they become relevant to our products. Also remember that Mobile RPG provides a mechanism that enables the user to provide a custom encoding alternative via the ASNA.Monarch.Wings.ICodePageConverter interface.