Main Page   Modules   Data Structures   File List   Data Fields   Globals   Related Pages  

MQe_String.h File Reference

The generic multi-byte String definition header. More...


Functions

MQERETURN mqeString_newChar8 (MQeExceptBlock *pErrStruct, MQeStringHndl *phNewString, MQECONST MQECHAR *pInput)
 Creates a new MQeString and copies/converts the MQECHAR string pInput (each array element represents a Unicode code point) into the created MQeString.

MQERETURN mqeString_newChar16 (MQeExceptBlock *pErrStruct, MQeStringHndl *phNewString, MQECONST MQECHAR16 *pInput)
 Creates a new MQeString and copies/converts the MQECHAR16 string pInput (each array element represents a Unicode code point) into the created MQeString.

MQERETURN mqeString_newChar32 (MQeExceptBlock *pErrStruct, MQeStringHndl *phNewString, MQECONST MQECHAR32 *pInput)
 Creates a new MQeString and copies/converts the MQECHAR32 string pInput (each array element represents a Unicode code point) into the created MQeString.

MQERETURN mqeString_newUtf8 (MQeExceptBlock *pErrStruct, MQeStringHndl *phNewString, MQECONST MQECHAR *pInput)
 Creates a new MQeString and copies/converts the Unicode UTF-8 string pInput into the created MQeString.

MQERETURN mqeString_newUtf16 (MQeExceptBlock *pErrStruct, MQeStringHndl *phNewString, MQECONST MQECHAR16 *pInput)
 Creates a new MQeString and copies the Unicode UTF-16 string pInput (each array element represents a Unicode code point) into the created MQeString.It also supports surrogate pairs.

MQERETURN mqeString_free (MQeStringHndl hString, MQeExceptBlock *pErrStruct)
 Frees the MQeString pointed to by hString.

MQERETURN mqeString_getChar8 (MQeStringHndl hString, MQeExceptBlock *pErrStruct, MQECHAR *pOutputString, MQEINT32 *pSize)
 Copies (converts if the internal storage format is different) the text content of the MQeString hString into the MQECHAR buffer pointed to by pOutputString. The string will be stored in the C single byte string format. An error is raised if the string can not be converted into a single byte C string.

MQERETURN mqeString_getChar16 (MQeStringHndl hString, MQeExceptBlock *pErrStruct, MQECHAR16 *pOutputString, MQEINT32 *pSize)
 Copies (converts if the internal storage format is different) the text content of the MQeString hString into the MQECHAR16 buffer pointed to by pOutputString. The string will be stored in the UNICODE double-byte string format.

MQERETURN mqeString_getChar32 (MQeStringHndl hString, MQeExceptBlock *pErrStruct, MQECHAR32 *pOutputString, MQEINT32 *pSize)
 Copies (converts if the internal storage format is different) the text content of the MQeString hString into the MQECHAR32 buffer pointed to by pOutputString. The string will be stored in the UNICODE quad-byte string format.

MQERETURN mqeString_getUtf8 (MQeStringHndl hString, MQeExceptBlock *pErrStruct, MQECHAR *pOutputString, MQEINT32 *pSize)
 Copies (converts if the internal storage format is different) the text content of the MQeString hString into the buffer pointed to by pOutputString. The string will be stored in the UTF-8 format.

MQERETURN mqeString_getUtf16 (MQeStringHndl hString, MQeExceptBlock *pErrStruct, MQECHAR16 *pOutputString, MQEINT32 *pSize)
 Copies (converts if the internal storage format is different) the text content of the MQeString hString into the buffer pointed to by pOutputString. The string will be stored in the UTF-16 format.

MQERETURN mqeString_equalTo (MQeStringHndl hString, MQeExceptBlock *pErrStruct, MQEBOOL *pIsEqual, MQECONST MQeStringHndl hEqualToString)
 Compare the text content of hString with that of hEqualToString for exact equality (storage format independent).

MQERETURN mqeString_codePointSize (MQeStringHndl hString, MQeExceptBlock *pErrStruct, MQEINT32 *pSize)
 Find the number of bytes required to store the largest code point in the string.

MQERETURN mqeString_isAsciiOnly (MQeStringHndl hString, MQeExceptBlock *pErrStruct, MQEBOOL *pIsAsciiOnly)
 Check if hString contains Ascii characters only, i.e. 32 <= val < 128 (can be represented in multi-byte form).

MQERETURN mqeString_isNull (MQeStringHndl hString, MQeExceptBlock *pErrStruct, MQEBOOL *pIsNull)
 Check if hString contains a NULL string.


Detailed Description

The MQeString class contains user defined and system strings and is an abstraction of character strings. It allows a string to be created or retrieved in a number of formats such as arrays containing Unicode code points (each code point stored in a 1, 2, or 4 bytes memory space) and UTF-8. The current implementation only supports these external formats. MQeString is used throughout the API where a string is required.


Function Documentation

MQERETURN mqeString_newChar8 MQeExceptBlock   pErrStruct,
MQeStringHndl *    phNewString,
MQECONST MQECHAR *    pInput
 

Parameters:
pErrStruct  [in/out] pointer to a pre-allocated MQeExceptBlock structure.
phNewString  [in/out] pointer to the new MQeString.
pInput  [in] pointer to a NULL terminated C input string.
Precondition:
pErrStruct should point to a pre-allocated MQeExceptBlock structure (no error information will be returned if pErrStruct is null).
Returns :
(*phNewString).
Return values:
MQERETURN_OK 
  • Operation successful
MQERETURN_SESSION_NOT_INITIALIZED 
  • MQeSession_initialize() not yet called
MQERETURN_ALLOCATION_FAILED 
  • Memory allocation failed
MQERETURN_INVALID_ARGUMENT 
  • MQEREASON_STRTYPE_UNKNOWN type unknown
  • MQEREASON_STRTYPE_NOT_SUPPORTED type not supported
  • MQEREASON_API_NULL_POINTER NULL pInput/phNewString
  • MQEREASON_API_VALUE_OUT_OF_RANGE negative length
Warning:
Users are expected to use mqeString_free() to free the object returned by this call after it is no longer needed. This will enable reuse of some system resources and avoid some avoidable system crashes.
The maximum Unicode code point this API call can handle is U+00FF.

MQERETURN mqeString_newChar16 MQeExceptBlock   pErrStruct,
MQeStringHndl *    phNewString,
MQECONST MQECHAR16 *    pInput
 

Parameters:
pErrStruct  [in/out] pointer to a pre-allocated MQeExceptBlock structure.
phNewString  [in/out] pointer to the new MQeString.
pInput  [in] pointer to a 0x0000 terminated UNICODE input string.
Precondition:
pErrStruct should point to a pre-allocated MQeExceptBlock structure (no error information will be returned if pErrStruct is null).
Returns :
(*phNewString).
Return values:
MQERETURN_OK 
  • Operation successful
MQERETURN_SESSION_NOT_INITIALIZED 
  • MQeSession_initialize() not yet called
MQERETURN_ALLOCATION_FAILED 
  • Memory allocation failed
MQERETURN_INVALID_ARGUMENT 
  • MQEREASON_STRTYPE_UNKNOWN type unknown
  • MQEREASON_STRTYPE_NOT_SUPPORTED type not supported
  • MQEREASON_API_NULL_POINTER NULL pInput/phNewString
  • MQEREASON_API_VALUE_OUT_OF_RANGE negative length
Warning:
Users are expected to use mqeString_free() to free the object returned by this call after it is no longer needed. This will enable reuse of some system resources and avoid some avoidable system crashes.
The maximum Unicode code point this API call can handle is U+FFFF.

MQERETURN mqeString_newChar32 MQeExceptBlock   pErrStruct,
MQeStringHndl *    phNewString,
MQECONST MQECHAR32 *    pInput
 

Parameters:
pErrStruct  [in/out] pointer to a pre-allocated MQeExceptBlock structure.
phNewString  [in/out] pointer to the new MQeString.
pInput  [in] pointer to a 0x00000000 terminated UNICODE input string.
Precondition:
pErrStruct should point to a pre-allocated MQeExceptBlock structure (no error information will be returned if pErrStruct is null).
Returns :
(*phNewString).
Return values:
MQERETURN_OK 
  • Operation successful
MQERETURN_SESSION_NOT_INITIALIZED 
  • MQeSession_initialize() not yet called
MQERETURN_ALLOCATION_FAILED 
  • Memory allocation failed
MQERETURN_INVALID_ARGUMENT 
  • MQEREASON_STRTYPE_UNKNOWN type unknown
  • MQEREASON_STRTYPE_NOT_SUPPORTED type not supported
  • MQEREASON_API_NULL_POINTER NULL pInput/phNewString
  • MQEREASON_API_VALUE_OUT_OF_RANGE negative length
Warning:
Users are expected to use mqeString_free() to free the object returned by this call after it is no longer needed. This will enable reuse of some system resources and avoid some avoidable system crashes.

MQERETURN mqeString_newUtf8 MQeExceptBlock   pErrStruct,
MQeStringHndl *    phNewString,
MQECONST MQECHAR *    pInput
 

Parameters:
pErrStruct  [in/out] pointer to a pre-allocated MQeExceptBlock structure.
phNewString  [in/out] pointer to the new MQeString.
pInput  [in] pointer to a NULL terminated UTF-8 input string.
Precondition:
pErrStruct should point to a pre-allocated MQeExceptBlock structure (no error information will be returned if pErrStruct is null).
Returns :
(*phNewString).
Return values:
MQERETURN_OK 
  • Operation successful
MQERETURN_SESSION_NOT_INITIALIZED 
  • MQeSession_initialize() not yet called
MQERETURN_ALLOCATION_FAILED 
  • Memory allocation failed
MQERETURN_INVALID_ARGUMENT 
  • MQEREASON_STRTYPE_UNKNOWN type unknown
  • MQEREASON_STRTYPE_NOT_SUPPORTED type not supported
  • MQEREASON_API_NULL_POINTER NULL pInput/phNewString
  • MQEREASON_API_VALUE_OUT_OF_RANGE negative length
Warning:
Users are expected to use mqeString_free() to free the object returned by this call after it is no longer needed. This will enable reuse of some system resources and avoid some avoidable system crashes.

MQERETURN mqeString_newUtf16 MQeExceptBlock   pErrStruct,
MQeStringHndl *    phNewString,
MQECONST MQECHAR16 *    pInput
 

Parameters:
pErrStruct  [in/out] pointer to a pre-allocated MQeExceptBlock structure.
phNewString  [in/out] pointer to the new MQeString.
pInput  [in] pointer to a 0x0000 terminated UNICODE input string.
Precondition:
pErrStruct should point to a pre-allocated MQeExceptBlock structure (no error information will be returned if pErrStruct is null).
Returns :
(*phNewString).
Return values:
MQERETURN_OK 
  • Operation successful
MQERETURN_SESSION_NOT_INITIALIZED 
  • MQeSession_initialize() not yet called
MQERETURN_ALLOCATION_FAILED 
  • Memory allocation failed
MQERETURN_INVALID_ARGUMENT 
  • MQEREASON_STRTYPE_UNKNOWN type unknown
  • MQEREASON_STRTYPE_NOT_SUPPORTED type not supported
  • MQEREASON_API_NULL_POINTER NULL pInput/phNewString
  • MQEREASON_API_VALUE_OUT_OF_RANGE negative length
Warning:
Users are expected to use mqeString_free() to free the object returned by this call after it is no longer needed. This will enable reuse of some system resources and avoid some avoidable system crashes.
The maximum Unicode code point this API call can handle is U+10FFFF.

MQERETURN mqeString_free MQeStringHndl    hString,
MQeExceptBlock   pErrStruct
 

Parameters:
hString  [in] the MQeString to be freed.
pErrStruct  [in/out] pointer to a pre-allocated MQeExceptBlock structure.
Precondition:
pErrStruct should point to a pre-allocated MQeExceptBlock structure (no error information will be returned if pErrStruct is null).
Return values:
MQERETURN_OK 
  • Operation successful

MQERETURN mqeString_getChar8 MQeStringHndl    hString,
MQeExceptBlock   pErrStruct,
MQECHAR *    pOutputString,
MQEINT32 *    pSize
 

Parameters:
hString  [in] source MQeString.
pErrStruct  [in/out] pointer to a pre-allocated MQeExceptBlock structure.
pOutputString  [in/out] a pre-allocated MQECHAR buffer.
pSize  [in/out] pointer to the size of buffer pointed to by pOutputString.
Precondition:
hString must be an MQeString created by mqeString_new().
pErrStruct should point to a pre-allocated MQeExceptBlock structure (no error information will be returned if pErrStruct is null).
Returns :
(*pOutputString) and (*pSize).
 * ----------------- ---------------------- ------------------------------- -------------------------
 * initial (*pSize)  initial pOutputString  returned (*pSize)               returned pOutputString
 * ----------------- ---------------------- ------------------------------- -------------------------
 * <= 0              any                    buffer size (in bytes) required not defined
 *                                          (including storage for
 *                                           termination character)
 * any               NULL                   ditto                           ditto
 * > 0               != NULL                buffer space used (in bytes)    points to the result
 * 
Return values:
MQERETURN_OK 
  • Operation successful
MQERETURN_SESSION_NOT_INITIALIZED 
  • MQeSession_initialize() not yet called
MQERETURN_INVALID_ARGUMENT 
  • MQEREASON_API_NULL_POINTER NULL pSize
  • MQEREASON_API_INVALID_SIGNATURE (*hString) not an MQeString
MQERETURN_BUFFER_OVERFLOW 
  • Supplied buffer not bigger enough
Warning:
The maximum Unicode code point this API call can handle is U+00FF.

MQERETURN mqeString_getChar16 MQeStringHndl    hString,
MQeExceptBlock   pErrStruct,
MQECHAR16 *    pOutputString,
MQEINT32 *    pSize
 

Parameters:
hString  [in] source MQeString.
pErrStruct  [in/out] pointer to a pre-allocated MQeExceptBlock structure.
pOutputString  [in/out] a pre-allocated MQECHAR16 buffer.
pSize  [in/out] pointer to the size (number of characters) of buffer pointed to by pOutputString.
Precondition:
hString must be an MQeString created by mqeString_new().
pErrStruct should point to a pre-allocated MQeExceptBlock structure (no error information will be returned if pErrStruct is null).
Returns :
(*pOutputString) and (*pSize).
 * ----------------- ---------------------- ------------------------------- -------------------------
 * initial (*pSize)  initial pOutputString  returned (*pSize)               returned pOutputString
 * ----------------- ---------------------- ------------------------------- -------------------------
 * <= 0              any                    buffer size (number of          not defined
 *                                          characters) required
 *                                          (including storage for
 *                                           termination char (0x0000))
 * any               NULL                   ditto                           ditto
 * > 0               != NULL                buffer space used (number of    points to the result
 *                                          characters)
 * 
Return values:
MQERETURN_OK 
  • Operation successful
MQERETURN_SESSION_NOT_INITIALIZED 
  • MQeSession_initialize() not yet called
MQERETURN_INVALID_ARGUMENT 
  • MQEREASON_API_NULL_POINTER NULL pSize
  • MQEREASON_API_INVALID_SIGNATURE (*hString) not an MQeString
MQERETURN_BUFFER_OVERFLOW 
  • Supplied buffer not bigger enough
Warning:
The maximum Unicode code point this API call can handle is U+FFFF.

MQERETURN mqeString_getChar32 MQeStringHndl    hString,
MQeExceptBlock   pErrStruct,
MQECHAR32 *    pOutputString,
MQEINT32 *    pSize
 

Parameters:
hString  [in] source MQeString.
pErrStruct  [in/out] pointer to a pre-allocated MQeExceptBlock structure.
pOutputString  [in/out] a pre-allocated MQECHAR32 buffer.
pSize  [in/out] pointer to the size (number of characters) of buffer pointed to by pOutputString.
Precondition:
hString must be an MQeString created by mqeString_new().
pErrStruct should point to a pre-allocated MQeExceptBlock structure (no error information will be returned if pErrStruct is null).
Returns :
(*pOutputString) and (*pSize).
 * ----------------- ---------------------- ------------------------------- -------------------------
 * initial (*pSize)  initial pOutputString  returned (*pSize)               returned pOutputString
 * ----------------- ---------------------- ------------------------------- -------------------------
 * <= 0              any                    buffer size (number of          not defined
 *                                          characters) required
 *                                          (including storage for
 *                                           termination char (0x00000000))
 * any               NULL                   ditto                           ditto
 * > 0               != NULL                buffer space used (number of    points to the result
 *                                          characters)
 * 
Return values:
MQERETURN_OK 
  • Operation successful
MQERETURN_SESSION_NOT_INITIALIZED 
  • MQeSession_initialize() not yet called
MQERETURN_INVALID_ARGUMENT 
  • MQEREASON_API_NULL_POINTER NULL pSize
  • MQEREASON_API_INVALID_SIGNATURE (*hString) not an MQeString
MQERETURN_BUFFER_OVERFLOW 
  • Supplied buffer not bigger enough

MQERETURN mqeString_getUtf8 MQeStringHndl    hString,
MQeExceptBlock   pErrStruct,
MQECHAR *    pOutputString,
MQEINT32 *    pSize
 

Parameters:
hString  [in] source MQeString.
pErrStruct  [in/out] pointer to a pre-allocated MQeExceptBlock structure.
pOutputString  [in/out] a pre-allocated MQECHAR buffer.
pSize  [in/out] pointer to the size (number of bytes) of buffer pointed to by pOutputString.
Precondition:
hString must be an MQeString created by mqeString_new().
pErrStruct should point to a pre-allocated MQeExceptBlock structure (no error information will be returned if pErrStruct is null).
Returns :
(*pOutputString) and (*pSize).
 * ----------------- ---------------------- ------------------------------- -------------------------
 * initial (*pSize)  initial pOutputString  returned (*pSize)               returned pOutputString
 * ----------------- ---------------------- ------------------------------- -------------------------
 * <= 0              any                    buffer size (number of          not defined
 *                                          bytes) required
 *                                          (including storage for
 *                                           termination char ('\0'))
 * any               NULL                   ditto                           ditto
 * > 0               != NULL                buffer space used (number of    points to the result
 *                                          bytes)
 * 
Return values:
MQERETURN_OK 
  • Operation successful
MQERETURN_SESSION_NOT_INITIALIZED 
  • MQeSession_initialize() not yet called
MQERETURN_INVALID_ARGUMENT 
  • MQEREASON_API_NULL_POINTER NULL pSize
  • MQEREASON_API_INVALID_SIGNATURE (*hString) not an MQeString
MQERETURN_BUFFER_OVERFLOW 
  • Supplied buffer not bigger enough

MQERETURN mqeString_getUtf16 MQeStringHndl    hString,
MQeExceptBlock   pErrStruct,
MQECHAR16 *    pOutputString,
MQEINT32 *    pSize
 

Parameters:
hString  [in] source MQeString.
pErrStruct  [in/out] pointer to a pre-allocated MQeExceptBlock structure.
pOutputString  [in/out] a pre-allocated MQECHAR16 buffer.
pSize  [in/out] pointer to the size (number of characters) of buffer pointed to by pOutputString.
Precondition:
hString must be an MQeString created by mqeString_new().
pErrStruct should point to a pre-allocated MQeExceptBlock structure (no error information will be returned if pErrStruct is null).
Returns :
(*pOutputString) and (*pSize).
 * ----------------- ---------------------- ------------------------------- -------------------------
 * initial (*pSize)  initial pOutputString  returned (*pSize)               returned pOutputString
 * ----------------- ---------------------- ------------------------------- -------------------------
 * <= 0              any                    buffer size (number of          not defined
 *                                          characters) required
 *                                          (including storage for
 *                                           termination char (0x0000))
 * any               NULL                   ditto                           ditto
 * > 0               != NULL                buffer space used (number of    points to the result
 *                                          characters)
 * 
Return values:
MQERETURN_OK 
  • Operation successful
MQERETURN_SESSION_NOT_INITIALIZED 
  • MQeSession_initialize() not yet called
MQERETURN_INVALID_ARGUMENT 
  • MQEREASON_API_NULL_POINTER NULL pSize
  • MQEREASON_API_INVALID_SIGNATURE (*hString) not an MQeString
MQERETURN_BUFFER_OVERFLOW 
  • Supplied buffer not bigger enough
Warning:
The maximum Unicode code point this API call can handle is U+10FFFF.

MQERETURN mqeString_equalTo MQeStringHndl    hString,
MQeExceptBlock   pErrStruct,
MQEBOOL *    pIsEqual,
MQECONST MQeStringHndl    hEqualToString
 

Parameters:
hString  [in] source string.
pErrStruct  [in/out] pointer to a pre-allocated MQeExceptBlock structure.
pIsEqual  [in/out] pointer to the result variable.
hEqualToString  [in/out] pointer to the MQeString to be compared with.
Precondition:
hString and pEqualToString must be MQeStrings created using mqeString_new().
pErrStruct should point to a pre-allocated MQeExceptBlock structure (no error information will be returned if pErrStruct is null).
pIsEqual must point to an existing variable.
Returns :
(*pIsEqual).
Return values:
MQERETURN_OK 
  • Operation successful
Warning:
This function assumes that codes which represent characters in a language stored in the strings are unique. This may not be true for certain languages.

MQERETURN mqeString_codePointSize MQeStringHndl    hString,
MQeExceptBlock   pErrStruct,
MQEINT32 *    pSize
 

Parameters:
hString  [in] source string.
pErrStruct  [in/out] pointer to a pre-allocated MQeExceptBlock structure.
pSize  [in/out] pointer to the result variable.
Precondition:
hString must be an MQeString created by mqeString_new().
pErrStruct should point to a pre-allocated MQeExceptBlock structure (no error information will be returned if pErrStruct is null).
pSize must point to an existing variable.
Returns :
(*pSize).
Return values:
MQERETURN_OK 
  • Operation successful

MQERETURN mqeString_isAsciiOnly MQeStringHndl    hString,
MQeExceptBlock   pErrStruct,
MQEBOOL *    pIsAsciiOnly
 

Parameters:
hString  [in] source string.
pErrStruct  [in/out] pointer to a pre-allocated MQeExceptBlock structure.
pIsAsciiOnly  [in/out] pointer to the result variable.
Precondition:
hString must be an MQeString created by mqeString_new().
pErrStruct should point to a pre-allocated MQeExceptBlock structure (no error information will be returned if pErrStruct is null).
pIsAsciiOnly must point to an existing variable.
Returns :
(*pIsAsciiOnly).
Return values:
MQERETURN_OK 
  • Operation successful

MQERETURN mqeString_isNull MQeStringHndl    hString,
MQeExceptBlock   pErrStruct,
MQEBOOL *    pIsNull
 

Parameters:
hString  [in] source string handle.
pErrStruct  [in/out] pointer to a pre-allocated MQeExceptBlock structure.
pIsNull  [in/out] pointer to the result variable.
Precondition:
hString must be an MQeString created by mqeString_new().
pErrStruct should point to a pre-allocated MQeExceptBlock structure (no error information will be returned if pErrStruct is null).
pIsNull must point to an existing variable.
Returns :
(*pIsNull).
Return values:
MQERETURN_OK 
  • Operation successful


Generated Thu Aug 11 23:41:23 2005 for Websphere MQ Everyplace for Multiplatforms C Bindings Reference