UniStrFromUcs

Convert a UCS string to a code page string.

Syntax

UniStrFromUcs(uconvObj, outBuffer, ucsString, outBufferLen);

Parameters

uconvObj - UconvObject - input 

The conversion object created from UniCreateUconvObject.

outBuffer - CHAR - output 

The output buffer to hold code page.

ucsString - UniChar - input 

Null terminated Unicode string.

outBufferLen - (int) - input/output 

The output buffer's length, in bytes.

Returns

An integer with values of:

• ULS_BADOBJECT
• ULS_BUFFERFULL
• ULS_ILLEGALSEQUENCE
• ULS_SUCCESS

Calling Convention

Cdecl32

Example Code

 character   in = "C:\SOMEPATH\FILE.TXT";
 
 size_t      unicodeBuffLen = 12;
 [[ULONG]]   codePage;
 ULONG       cpLen;       // length set by [[DosQueryCp]]
 [[UniChar]] unicodeBuff, // length of unicodeBuffLen
             ucsString;   // length of CCHMAXPATH
 [[UconvObject]] uconv;
 character   outBuffer;   // allocate to CCHMAXPATH
 integer     rc;

 rc = DosQueryCp(size of ULONG, codePage, cpLen);

 /* determine string for the conversion of codePage */
 rc = UniMapCpToUcsCp(codePage, unicodeBuff, unicodeBuffLen);
 rc = UniCreateUconvObject(unicodeBuff, uconvObj);
 rc = UniStrToUcs(uconvObj, ucsString, 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, outBuffer, ucsString, CCHMAXPATH);
 rc = UniFreeUconvObject(uconvObj);

 /* use outBuffer - don't forget to de-allocate outBuffer when finished with it. */
 /* error checking left out for brevity */

Notes

The sequence of code elements in ucsString is converted into a sequence of code page characters to outBuffer. The code page was set by UniCreateUconvObject call in the UconvObject.

If the outBuffer isn't large enough, conversion ends on the byte previous to any buffer overflow. outBuffer is updated truncating the point of failure to the end and updating the outBufferLen to indicate the number of successfully converted bytes.

If UniStrFromUcs contains a code sequence in ucsString that is legal with no corresponding character in the target codepage this function will replace it with a predefined substituted character.

OS Version Introduced

• OS/2 Warp

Related Functions

• UniConvFromUcs
• UniConvToUcs
• UniStrToUcs