UniCreateUconvObject

UniCreateUconvObject

UniCreateUconvObject(cpName, uconvObj)

Creates and initializes the conversion object.

Parameters

cpName - UniChar - input

Name of the UCS conversion.

uconvObj - UconvObject - output

The conversion object returned.

Constants

None

Returns

An integer with values of:

• ULS_INVALID
• ULS_MAXFILESPERPROC
• ULS_MAXFILES
• ULS_NOMEMORY
• ULS_SUCCESS

Calling conversion

Cdecl32

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 */

Related Functions

• UniFreeUconvObject
• UniQueryUconvObject
• UniSetUconvObject

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