View source for UniStrToUcs

== UniStrToUcs ==
; UniStrToUcs(uconvObj, inBuffer, inBufferLen, ucsBuffer, ucsBufferLen, nonIdenticalConv) :
Convert a code page string to a UCS string.

=== Parameters ===
; uconvObj - [[OS2 API:DataType:UConvObject|UconvObject]] - input :
The conversion object created from [[OS2_API:UniCreateUconvObject|UniCreateUconvObject]].
; inBuffer - (void **) - input :
The input buffer.
; inBufferLen - (size_t *) - input/output :
The input buffer's length, in bytes.
; ucsBuffer - [[OS2 API:DataType:UniChar|UniChar]] - output :
The ucs buffer.
; ucsBufferLen - (size_t *) - output :
Number of unicode character elements in the ucsBuffer.
; nonIdenticalConv - (size_t *) - output :
Number of non-identical conversions.

=== Constants ===
None

=== Returns ===
An integer with values of:
* [[OS2 API:Unicode:error#ULS_BADOBJECT|ULS_BADOBJECT]]
* [[OS2 API:Unicode:error#ULS_BUFFERFULL|ULS_BUFFERFULL]]
* [[OS2 API:Unicode:error#ULS_ILLEGALSEQUENCE|ULS_ILLEGALSEQUENCE]]
* [[OS2 API:Unicode:error#ULS_INVALID|ULS_INVALID]]
* [[OS2 API:Unicode:error#ULS_SUCCESS|ULS_SUCCESS]]

=== Module ===

=== Define (C/C++) ===
INCL_???

=== Export name/Ordinal ===

=== Calling conversion ===
[[Cdecl32]]

=== Example Code ===
 [[OS2 API:DataType:UconvObject|UconvObject]] uconvObj;
 void**      inBuffer;
 size_t*     inBufferLen;
 [[OS2 API:DataType:UniChar|UniChar]]     ucsBuffer;
 size_t*     ucsBufferLen;
 size_t*     nonIdenticalConv;
 integer     rc;
 ...
 rc = UniStrToUcs(uconvObj, inBuffer, inBufferLen, ucsBuffer, ucsBufferLen, nonIdenticalConv);
 ...

=== Related Functions ===
[[OS2 API:UniUconvFromUcs|UniconvFromUcs]]
[[OS2 API:UniUconvToUcs|UniconvToUcs]]
[[OS2 API:UniStrFromUcs|UniStrFromUcs]]

=== Notes ===
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 [[OS2_API:UniCreateUconvObject|UniCreateUnconvObject]] call in the [[OS2_API:DataType:UconvObject|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