UniCreateUconvObject
Creates and initializes the conversion object.
Syntax
UniCreateUconvObject(cpName, uconvObj)
Parameters
- cpName - UniChar - input
- Name of the UCS conversion.
- uconvObj - UconvObject - output
- The conversion object returned.
Constants
None
Returns
An integer with values of:
Calling Convention
Example Code
character in = "C:\SOMEPATH\FILE.TXT";
size_t cpNameLen = 12;
ULONG codePage;
ULONG cpLen; // length set by DosQueryCp
UniChar cpName, // length of cpNameLen
tempPath; // length of CCHMAXPATH
UconvObject uconvObj;
character out; // allocate to CCHMAXPATH
integer rc;
rc = DosQueryCp(size of ULONG, codePage, cpLen);
/* determine string for the conversion of codePage */
rc = UniMapCpToUcsCp(codePage, cpName, cpNameLen);
rc = UniCreateUconvObject(cpName, uconvObj);
rc = UniStrToUcs(uconv, tempPath, in, CCHMAXPATH);
rc = UniFreeUconvObject(uconvObj);
/* conversion for current codepage that can be used for paths */
rc = UniCreateUconvObject((UniChar pointer)L"@path=yes", uconvObj);
rc = UniStrFromUcs(uconvObj, out, tempPath, CCHMAXPATH);
rc = UniFreeUconvObject(uconvObj);
/* use out - don't forget to de-allocate out when finished with it. */
/* error checking left out for brevity */
Format
- include <uconv.h>
int UniCreateUconvObject (
UniChar *cpname, /* I - UCS conversion specifier */
UconvObject *uconv_object /* O - Conversion object handle */
)
Related Functions
Notes
UniCreateUconvObject returns a conversion object that describes a UCS-2 conversion between the code page specified by cpName and UCS.
A conversion object remains valid until it is freed with UniFreeUconvObject.
The cpName field is normally the Unicode string IBM- followed by the decimal number of the code page. Other names may be used. UCONV tables are kept in the \language\codepage directory on the boot drive.
If the cpName parameter contains an empty string, UniCreateUconvObject will create a conversion object based upon the value of the process codepage setting.
UniCreateUconvObject allows modifiers to be concatenated onto cpName, these modifiers change the default behavior of conversion objects. The caller can concatenate the following modifiers onto cpName.
Modifiers are separated from the conversion object name by an at sign (@), and multiple modifiers are separated by a comma (,).
displaymask
@map=data All characters less than space are controls.
(default)
@map=display All characters less than space are glyphs.
@map=cdra Use IBM standard control conversion.
@map=clrf CR and LF are controls, others are glyphs.
converttype
@path=yes When performing Unicode conversions strings
are assumed to contain pathnames. This
setting is only applicable when converting
to or from DBCS codepages.
(default)
@path=no When performing Unicode conversions strings
are assumed to contain non path data. This
setting is only applicable when converting
to or from DBCS codepages.
endian
@endian=Source:Target
@endian=Both
Source applies to UniUconvFromUcs; Target applies to
UniUconvToUcs. If only one endian is given, it applies
to both source and target.
The endian type can be one of the following:
system Use system endian.
big Use big endian.
little Use little endian.
(default)
For example @endian=little
@endian=big:system
options
@sub=yes Perform substitutions when converting to and
from Unicode.
@sub=no Do not perform substitutions when converting
to and from Unicode.
@sub=to-ucs Only perform substitutions when converting to
Unicode.
@sub=from-ucs Only perform substitutions when converting from
Unicode.
(default)
@subchar=\xXX Where XX is a hex number
@subchar=\DD Where DD is a decimal number
The substitution character attribute specifies
which character the conversion object should
use when there is no identical character for
a given code element while converting from
Unicode.
@subuni=\xXX\xXX Where XX is a hex number
@subuni=\xXXXX Where XXXX is a hex number
The substitution character attribute specifies
which character the conversion object should
use when there is no identical character for
a given code element while converting to
Unicode.
Examples of typical usage:
IBM-942@path=yes,map=display
This example creates a conversion object based upon an IBM-942
encoding. When conversions are performed all strings will be treated
as pathnames and all characters less than space will be considered
to be glyphs.
@path=yes,sub=no
This example creates a conversion object based upon the current
process codepage setting. When conversions are performed all
strings will be treated as pathnames and no substitutions will
occur.
IBM-850@path=no,sub=yes
This example creates a conversion object based upon an IBM-850
encoding. When conversions are performed all strings will be
treated as non pathnames and substitutions will occur when
converting to and from Unicode if necessary.
UniCreateUconvObject returns a conversion object in uconvObj for use in subsequent calls to either UniUconvFromUcs or UniUconvToUcs.
OS Version Introduced
OS/2 Warp