lcs_intro(PCI) 6 January 1993 lcs_intro(PCI) Name lcs_intro - introduction to language character set routines Description This section describes all of the language character set library rou- tines. The lcs routines translate from one code set or code page to another so that a viewable character (glyph) under one code page or code set is viewable under another code page or code set. Certain glyphs cannot be translated exactly. However, they can be represented by multiple glyphs. Other glyphs may have no possible representation, in which case a user default character or a best single character is used (if nothing better is available, the best single char- acter is an asterisk). The order of precedence during glyph translation is given below: Exact The glyph is translated to the exact same glyph in the dif- ferent character set. Multiglyph The glyph is translated to a multiglyph output that is a best translation possible. For example, in some code sets there is a three-quarters glyph (3/4). It may not be possible to translate that glyph exactly, but it is possible to display the '3' glyph, the '/' glyph, and the '4' glyph, in sequence, to convey the same meaning. User char There was no exact translation possible, so a user-supplied character was used instead. Best single The best single glyph translation was used. There was no user character defined. If nothing better is available, the default is an asterisk (*). Most of these routines return one or more error conditions. An error con- dition is indicated by an otherwise impossible returned value, such as -1 or the NULL pointer; the individual manual pages specify the details. An error number is also made available in the external variable lcserrno. lcserrno is not always cleared on successful calls, so you should test it only after an error has been indicated. The following errors are returned: LCSERRNOTFOUND The translation table was not found. LCSERRBADTABLE The translation table is invalid. LCSERRNOTABLE Translation tables are not set. LCSERRNOSPACE There is insufficient space in the output buffer. LCSERRSTOPXLAT An untranslatable character was seen, and the stop- translation option mode bit was set. LCSERRINPUTSPLIT The translation routines encountered a byte that could be part of a multibyte character in the input buffer. The portion of the block prior to this character was correctly translated. The remaining byte should be added to the next block for transla- tion. This normally occurs in packet network situa- tions where a block of text could be sent as several discrete packets requiring some reassembly. Additionally, the following six global variables provide translation statistics: int lcsexacttranslations; This variable contains the number of characters that were translated exactly. Exact translation means that the same glyph exists in both the input translation table and the output translation table. int lcsmultipletranslations; This variable contains the number of characters that generated mul- tiple output glyphs for a single input glyph. This form of transla- tion does not happen if the LCSMODENOMULTIPLE option bit is set. int lcsbestsingletranslations; This variable contains the number of characters for which there was no exact translation and no multiple glyph translation. The option bits LCSMODESTOPXLAT and LCSMODEUSERCHAR must both be reset for this form of translation to occur. int lcsuserdefaulttranslations; This variable contains the number of user-specified default charac- ter translations. This form of translation happens when there is no exact translation, no multiple translation, the LCSMODESTOPXLAT option bit is reset, and the LCSMODEUSERCHAR option bit is set. int lcsinputbytesprocessed; This variable contains the number of bytes processed from the input buffer. It is valid regardless of whether the translate function succeeded or not. int lcsoutputbytesprocessed; This variable contains the number of bytes placed into the output buffer. It is valid regardless of whether the translate function succeeded or not. These six variables are reset with each lcstranslatestring() and lcstranslateblock() library call.