From EDM2
(Redirected from OS2 API:UniStrToUcs)
Jump to: navigation, search

Convert a code page string to a UCS string.


UniStrToUcs(uconvObj, ucsBuffer, inBuffer, ucsBufferLen);


uconvObj - UconvObject - input 
The conversion object created from UniCreateUconvObject.
ucsBuffer - UniChar - output 
The ucs buffer.
inBuffer - (character) - input 
The input buffer that is null terminated.
ucsBufferLen - (integer) - input 
Number of unicode character elements in the ucsBuffer.


An integer with values of:

Calling Convention


Example Code

 character   inBuffer = "C:\SOMEPATH\FILE.TXT";
 size_t      unicodeBuffLen = 12;
 ULONG       codePage;
 ULONG       cpLen;       // length set by [[OS2 API:DosQueryCp|DosQueryCp]]
 UniChar     unicodeBuff, // length of unicodeBuffLen
             ucsBuffer;   // 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, unicodeBuff, unicodeBuffLen);
 rc = UniCreateUconvObject(unicodeBuff, uconvObj);
 rc = UniStrToUcs(uconvObj, ucsBuffer, inBuffer, 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, ucsBuffer, CCHMAXPATH);
 rc = UniFreeUconvObject(uconvObj);

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


The sequence of the code page characters in inBuffer is converted into a sequence of Unicode characters in ucsBuffer. The code page was set by UniCreateUconvObject call in the UconvObject.

Conversion is only on bytes that convert. The process stops converting on the first non-valid byte. If the ucsBuffer isn't large enough, conversion ends on the byte previous to any buffer overflow. inBuffer is updated truncating the point of failure to the end and updating the ucsBufferLen to indicate the number of successfully converted elements.

OS Version Introduced

OS/2 Warp

Related Functions