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:

• ULS_INVALID
• ULS_MAXFILESPERPROC
• ULS_MAXFILES
• ULS_NOMEMORY
• ULS_SUCCESS

Calling Convention

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

Format

#include <uconv.h>

int UniCreateUconvObject (
    UniChar     *cpname,         /* I  - UCS conversion specifier */
    UconvObject *uconv_object    /* O  - Conversion object handle */
)

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