Exchanging data with Host software

Because MVS, VM, DOS/VSE and OS/400 use the EBCDIC code scheme and OS/2 uses the ASCII code scheme, character-data exchange between a host system and a PC requires translation of strings from/to EBCDIC codes to/from ASCII codes. DBCS-unique considerations on the code-conversion are:

• Change in length of a string

  A host system requires that DBCS portions of a mixed string be surrounded by Shift-out(SO) and Shift-in(SI) control characters, while a PC doesn't require such control characters to denote a mixed string. Because each of the SO or SI characters occupies one-byte in a record, the code conversion of a mixed string causes change in length of a string. That is, length of a mixed string becomes shorter when it is downloaded from a host to a PC and becomes longer when uploaded from a PC to a host. This change may result in unintentional truncation or overflow of data at up-loading.

  ┌──────────────────────────────────────────────────────────────────────┐
  │ES_MIXED is the entry field style to prevent unintentional truncation │
  │or overflow of data at up-loading.                                    │
  └──────────────────────────────────────────────────────────────────────┘
  

  The Presentation Manager has an enhanced entry-field control to prevent unintentional truncation or overflow from happening. ES_MIXED is the entry-field control to limit user's input at a PC in order to confine a length of a record at a Host to a pre-defined one. If an entry field is defined as ES_MIXED, the Presentation Manager automatically includes the number of would-be-inserted SO/SI into record-length calculation and prevents a user from typing a string longer than the one specified by EM_SETTEXTLIMIT.

  SBCS OS/2 ignores ES_MIXED. It doesn't cause any errors on SBCS OS/2, if you include it in your program source. That is, ES_DBCS, ES_SBCS and ES_DBCS have no meaning on SBCS OS/2.

• Choosing a function to perform the code conversion

  Two different functions, WinCpTranslateString and TrnsDt, to perform the code conversion are supported at the PC side. The WinCpTranslateString and TrnsDt shows differences between the two functions.

  CONVERT, a Communication Manager common service verb, and WinCpTranslateChar only serve for SBCS.

┌──────────────────────────────────────────────────────────────────────┐│WinCpTranslateString and TrnsDt are for converting from/to ASCII      │
│strings to/from EBCDIC strings.                                       │
└──────────────────────────────────────────────────────────────────────┘

The most noticeable difference between the two conversion services is that WinCpTranslateString is a common API across SBCS and DBCS OS/2, while TrnsDt is packaged in DBCS OS/2 only. interface on DBCS OS/2. When calling TrnsDt from 32-bit code, you need to take problems on linkage conventions, 16-bit pointer declaration and structure alignment. We are going to show a sample program in Example of TrnsDt usage from 32-bit code (source: MISCWIN.C).

┌─────────────────────────┬──────────────────────────────┬──────────────────────────────┐
│                         │WinCpTranslateString          │TrnsDt                        │
├─────────────────────────┼──────────────────────────────┼──────────────────────────────┤
│Supported code pages     │between any code pages        │between PC combined code pages│
│                         │                              │and Host SBCS, DBCS or        │
│                         │                              │combined code pages           │
├─────────────────────────┼──────────────────────────────┼──────────────────────────────┤
│Availability             │a common API across SBCS and  │available only at DBCS OS/2   │
│                         │DBCS OS/2                     │                              │
├─────────────────────────┼──────────────────────────────┼──────────────────────────────┤
│Usage of program types   │PM applications               │any type of OS/2 programs     │
├─────────────────────────┼──────────────────────────────┼──────────────────────────────┤
│Control code conversion  │converts to substitution      │maps control codes            │
│                         │characters                    │                              │
├─────────────────────────┼──────────────────────────────┼──────────────────────────────┤
│Round-trip conversion    │Not supported                 │Supported                     │
├─────────────────────────┼──────────────────────────────┼──────────────────────────────┤
│Substitution characters  │x'7F' or x'FF'                │x'7F' or x'3F'                │
│at SBCS code pages       │                              │                              │
├─────────────────────────┼──────────────────────────────┼──────────────────────────────┤
│Returned value when a    │no error codes ( A string is  │error code 111                │
│string overflows at a    │truncated carefully so as to  │                              │
│target code page         │keep DBCS string validity)    │                              │
├─────────────────────────┼──────────────────────────────┼──────────────────────────────┤
│Options                  │no options                    │option to produce pseudo SO/SI│
│                         │                              │code in PC, option to specify │
│                         │                              │a conversion table            │
└─────────────────────────┴──────────────────────────────┴──────────────────────────────┘