INFORMIX-GLS Programmer's Guide

INFORMIX-GLS Programmer's Guide
Chapter 4: INFORMIX-GLS Function Descriptions

Home Contents Index Master Index New Book

ifx_gl_mbsmbs()

The ifx_gl_mbsmbs() function searches for a specified substring within a multibyte-character string.

Syntax

#include <ifxgls.h>

...
gl_mchar_t *ifx_gl_mbsmbs(mbs1, mbs1_byte_length, mbs2, mbs2_byte_length)

		gl_mchar_t *mbs1;

		int mbs1_byte_length;

		gl_mchar_t *mbs2;

		int mbs2_byte_length; 


mbs1
is a pointer to the multibyte-character string to search for the substring mbs2. 

mbs1_byte_length
is the integer number of bytes in the mbs1 string. If mbs1_byte_length is the value IFX_GL_NULL, the function assumes that mbs1 is a null-terminated string. For more general information about string lengths, see "Character-String Termination".

mbs2
is a pointer to the string of multibyte characters to search for in mbs1.

mbs2_byte_length
is the integer number of bytes in the mbs2 string. If mbs2_byte_length is the value IFX_GL_NULL, the function assumes that mbs2 is a null-terminated string. For more general information about string lengths, see "Character-String Termination".







 



Valid in Client Application

Valid in DataBlade UDR

Yes
Yes

Usage

The ifx_gl_mbsmbs() function searches for the first occurrence of the multibyte string mbs2 in the multibyte string mbs1.

Return Values

gl_mchar_t *
A pointer to the first byte of the first occurrence of mbs2 in mbs1.

NULL
Either mbs2 was not found in mbs1 (the ifx_gl_lc_errno() error number is set to zero); or the function was not successful, and the error number is set to indicate the cause. See the Errors section.

Errors

If an error occurred, this function returns NULL and sets ifx_gl_lc_errno() to one of the following values.


`IFX_GL_PARAMERR`	Either mbs1_byte_length is not equal to `IFX_GL_NULL` and is not greater than or equal to zero, or mbs2_byte_length is not equal to `IFX_GL_NULL` and is not greater than or equal to zero.
`IFX_GL_TERMMISMAT`	Either mbs1_byte_length is equal to `IFX_GL_NULL`, and mbs2_byte_length is greater than or equal to zero; or mbs1_byte_length is greater than or equal to zero, and mbs2_byte_length is equal to `IFX_GL_NULL.`
`IFX_GL_EILSEQ`	Either mbs1 or mbs2 contains an invalid multibyte character.
`IFX_GL_EINVAL`	Either the function cannot determine whether the last character of mbs1 is a valid multibyte character because it would need to read more than mbs1_byte_length bytes from mbs1, or the function cannot determine whether the last character of mbs2 is a valid multibyte character because it would need to read more than mbs2_byte_length bytes from mbs2. For more information about this error, see "Keeping Multibyte Strings Consistent".

ifx_gl_mbsncat()

The ifx_gl_mbsncat() function concatenates a specified number of multibyte characters in one multibyte string to another.

Syntax

#include <ifxgls.h>

...
int ifx_gl_mbsncat(mbs1, mbs1_byte_length, mbs2, mbs2_byte_length, char_limit)

		gl_mchar_t *mbs1;

		int mbs1_byte_length;

		gl_mchar_t *mbs2;

		int mbs2_byte_length;

		int char_limit; 


mbs1
is a pointer to the multibyte-character string to which the function concatenates mbs2. 

mbs1_byte_length
is the integer number of bytes in the mbs1 string. If mbs1_byte_length is the value IFX_GL_NULL, the function assumes that mbs1 is a null-terminated string. For more general information about string lengths, see "Character-String Termination".

mbs2
is a pointer to the multibyte-character string to concatenate to mbs1.

mbs2_byte_length
is the integer number of bytes in the mbs2 string. If mbs2_byte_length is the value IFX_GL_NULL, the function assumes that mbs2 is a null-terminated string. For more general information about string lengths, see "Character-String Termination".

char_limit
is the maximum number of multibyte characters to read from mbs2.







 



Valid in Client Application

Valid in DataBlade UDR

Yes
Yes

Usage

The ifx_gl_mbsncat() function appends mbs2 to the end of mbs1. The function reads no more than char_limit characters from mbs2 and writes them to mbs1. If mbs1 and mbs2 overlap, the results of this function are undefined.

If mbs1_byte_length is equal to IFX_GL_NULL, the function null-terminates the concatenated string. Any other value of mbs1_byte_length means that the function does not null-terminate the resulting concatenated string.

Return Values

>=0
The number of bytes in the concatenated string, not including any null terminator.

-1
The function was not successful, and the error number is set to indicate the cause. See the Errors section.

Errors

If an error occurred, this function returns -1 and sets the ifx_gl_lc_errno() error number to one of the following values.


`IFX_GL_PARAMERR`	Either mbs1_byte_length is not equal to `IFX_GL_NULL` and is not greater than or equal to zero, or mbs2_byte_length is not equal to `IFX_GL_NULL` and is not greater than or equal to zero.
`IFX_GL_TERMMISMAT`	Either mbs1_byte_length is equal to `IFX_GL_NULL`, and mbs2_byte_length is greater than or equal to zero; or mbs1_byte_length is greater than or equal to zero, and mbs2_byte_length is equal to `IFX_GL_NULL.`
`IFX_GL_EILSEQ`	Either mbs1 or mbs2 contains an invalid multibyte character.
`IFX_GL_EINVAL`	Either the function cannot determine whether the last character of mbs1 is a valid multibyte character because it would need to read more than mbs1_byte_length bytes from mbs1, or the function cannot determine whether the last character of mbs2 is a valid multibyte character because it would need to read more than mbs2_byte_length bytes from mbs2. For more information about this error, see "Keeping Multibyte Strings Consistent".

ifx_gl_mbsncpy()

The ifx_gl_mbsncpy() function copies a specified number of multibyte characters from a multibyte-character string.

Syntax

#include <ifxgls.h>

...
int ifx_gl_mbsncpy(mbs1, mbs2, mbs2_byte_length, char_limit)

		gl_mchar_t *mbs1;

		gl_mchar_t *mbs2;

		int mbs2_byte_length;

		int char_limit; 


mbs1
is a pointer to the location where the function copies mbs2. 

mbs2
is a pointer to the multibyte-character string to copy to mbs1.

mbs2_byte_length
is the integer number of bytes in the mbs2 string. If mbs2_byte_length is the value IFX_GL_NULL, the function assumes that mbs2 is a null-terminated string. For more general information about string lengths, see "Character-String Termination".

char_limit
is the maximum number of multibyte characters to read from mbs2.







 



Valid in Client Application

Valid in DataBlade UDR

Yes
Yes

Usage

The ifx_gl_mbsncpy() function copies mbs2 to the location that mbs1 references. The function reads no more than char_limit characters from mbs2 and writes them to mbs1. If mbs1 and mbs2 overlap, the results of this function are undefined.

If mbs2_byte_length is equal to IFX_GL_NULL, the function null-terminates the concatenated string. Any other value of mbs2_byte_length means that the function does not null-terminate the resulting concatenated string.

Return Values

>=0
The number of bytes in the copied string, not including any null terminator.

-1
The function was not successful, and the error number is set to indicate the cause. See the Errors section.

Errors

If an error occurred, this function returns -1 and sets the ifx_gl_lc_errno() error number to one of the following values.


`IFX_GL_PARAMERR`	The mbs2_byte_length is not equal to `IFX_GL_NULL` and is not greater than or equal to zero.
`IFX_GL_EILSEQ`	The *mbs2 value contains an invalid multibyte character.
`IFX_GL_EINVAL`	The function cannot determine whether the last character of mbs2 is a valid multibyte character because it would need to read more than mbs2_byte_length bytes from mbs2. For more information about this error, see "Keeping Multibyte Strings Consistent".

ifx_gl_mbsnext()

The ifx_gl_mbsnext() function returns the next multibyte character from a multibyte string.

Syntax

#include <ifxgls.h>

...
gl_mchar_t *ifx_gl_mbsnext(mb, mb_byte_limit)

		gl_mchar_t *mb;

		int mb_byte_limit; 


mb
is a pointer to the current multibyte character in the multibyte string.

mb_byte_limit
is the integer number of bytes to read from mb to try to form a complete multibyte character. If mb_byte_limit is IFX_GL_NO_LIMIT, the function reads as many bytes as necessary from mb to form a complete character. For general information about mb_byte_limit, see "Multibyte-Character Termination".







 



Valid in Client Application

Valid in DataBlade UDR

Yes
Yes

Usage

The ifx_gl_mbsnext() function returns a pointer to the next multibyte character after mb in a multibyte-character string. This function is typically used to transform the single-byte forward-traversal loop to a multibyte loop. For example, suppose you have the following single-byte loop:

for ( sb = sbs; *sb != '\0'; sb++ )
	{
	/* Process single-byte character */

The following code fragment traverses the string with the ifx_gl_mbsnext() function instead of incrementing the pointer of the single-byte loop:

for ( mb = mbs; *mb != '\0'; )
	{
	/* Process multibyte character; increment pointer through string */
	if ( (mb = ifx_gl_mbsnext(mb, IFX_GL_NO_LIMIT)) == NULL )
		 /* Handle error */
	}

Return Values

gl_mchar_t *
A pointer to the byte that immediately follows mb.

NULL
The function was not successful, and the error number is set to indicate the cause. See the Errors section.

Errors

If an error occurred, this function returns NULL and sets the ifx_gl_lc_errno() error number to one of the following values


`IFX_GL_EILSEQ`	The *mb value is not a valid multibyte character.
`IFX_GL_EINVAL`	The function cannot determine whether mb is a valid multibyte character because it would need to read more than mb_byte_limit bytes from mb. If mb_byte_limit is less than or equal to zero, this function always returns this error. For more information about this error, see "Keeping Multibyte Strings Consistent".

ifx_gl_mbsntsbytes()

The ifx_gl_mbsntsbytes() function determines the number of bytes in a multibyte string. It ignores trailing spaces.

Syntax

#include <ifxgls.h>

...
int ifx_gl_mbsntsbytes(mbs, mbs_byte_length)

		gl_mchar_t *mbs;

		int mbs_byte_length; 


mbs
is a pointer to the multibyte-character string whose length the function determines. 

mbs_byte_length
is the integer number of bytes in the mbs string. If mbs_byte_length is the value IFX_GL_NULL, the function assumes that mbs is a null-terminated string. For more general information about string lengths, see "Character-String Termination".







 



Valid in Client Application

Valid in DataBlade UDR

Yes
Yes

Usage

The ifx_gl_mbsntsbytes() function returns the number of bytes in mbs, not including the trailing-space characters. The trailing-space characters are all characters that the blank character class of the current locale defines. For more information on the blank class, see "Character Classification".

Space characters that are embedded in the string at any place except the end of the string are included in the count. For example, the following call to ifx_gl_mbsntsbytes() returns a value of 10 (the number of bytes in the string "A1A2B1B2B3 cd E1", where A1A2, B1B2B3, and E1 are multibyte characters of 2, 3, and 1 bytes, respectively, and s is a single-byte blank space):

    ifx_gl_mbsntsbytes("A1A2B1B2B3scdsE1ssssss")

Return Values

>=0
The number of bytes in the mbs string, not including any trailing space.

-1
The function was not successful, and the error number is set to indicate the cause. See the Errors section.

Errors

If an error occurred, this function returns -1 and sets the ifx_gl_lc_errno() error number to one of the following value.


`IFX_GL_PARAMERR`	The mbs_byte_length is not equal to `IFX_GL_NULL` and is not greater than or equal to zero.
`IFX_GL_EILSEQ`	The *mbs value contains an invalid multibyte character.
`IFX_GL_EINVAL`	The function cannot determine whether the last character of mbs is a valid multibyte character because it would need to read more than mbs_byte_length bytes from mbs. For more information about this error, see "Keeping Multibyte Strings Consistent".

ifx_gl_mbsntslen()

The ifx_gl_mbsntslen() function determines number of characters in a multibyte string. It ignores trailing spaces.

Syntax

#include <ifxgls.h>

...
int ifx_gl_mbsntslen(mbs, mbs_byte_length)

		gl_mchar_t *mbs;

		int mbs_byte_length; 


mbs
is a pointer to the multibyte-character string whose length the function determines. 

mbs_byte_length
is the integer number of bytes in the mbs string. If mbs_byte_length is the value IFX_GL_NULL, the function assumes that mbs is a null-terminated string. For more general information about string lengths, see "Character-String Termination".







 



Valid in Client Application

Valid in DataBlade UDR

Yes
Yes

Usage

The ifx_gl_mbsntslen() function returns the number of characters in mbs, not including any trailing-space characters. The trailing-space characters are all characters that the blank character class of the current locale defines. For more information on the blank class, see "Character Classification".

Space characters that are embedded in the string at any place except the end of the string are included in the count. For example, the following call to ifx_gl_mbsntslen() returns a value of 7 (the number of bytes in the string "A1A2B1B2B3 cd E1", where A1A2, B1B2B3, and E1 are multibyte characters of 2, 3, and 1 bytes, respectively, and s is a single-byte blank space):

    ifx_gl_mbsntslen("A1A2B1B2B3scdsE1ssssss")

Use the ifx_gl_mbslen() function if you want the length to include trailing white space.

Return Values

>=0
The number of characters in the mbs string, not including any trailing space.

-1
The function was not successful, and the error number is set to indicate the cause. See the Errors section.

Errors

If an error occurred, this function returns -1 and sets the ifx_gl_lc_errno() error number to one of the following values.


`IFX_GL_PARAMERR`	The mbs_byte_length is not equal to `IFX_GL_NULL` and is not greater than or equal to zero.
`IFX_GL_EILSEQ`	The *mbs value contains an invalid multibyte character.
`IFX_GL_EINVAL`	The function cannot determine whether the last character of mbs is a valid multibyte character because it would need to read more than mbs_byte_length bytes from mbs. For more information about this error, see "Keeping Multibyte Strings Consistent".

ifx_gl_mbspbrk()

The ifx_gl_mbspbrk() function searches for any multibyte character from one multibyte string in another multibyte-character string.

Syntax

#include <ifxgls.h>

..
gl_mchar_t *ifx_gl_mbspbrk(mbs1, mbs1_byte_length, mbs2, mbs2_byte_length)

		gl_mchar_t *mbs1;

		int mbs1_byte_length;

		gl_mchar_t *mbs2;

		int mbs2_byte_length; 


mbs1
is a pointer to the string of multibyte characters to search for the characters in mbs2.

mbs1_byte_length
is the integer number of bytes in the mbs1 string. If mbs1_byte_length is the value IFX_GL_NULL, the function assumes that mbs1 is a null-terminated string. For more general information about string lengths, see "Character-String Termination".

mbs2
is a pointer to the multibyte-character string whose characters the function searches for in mbs1. 

mbs2_byte_length
is the integer number of bytes in the mbs2 string. If mbs2_byte_length is the value IFX_GL_NULL, the function assumes that mbs2 is a null-terminated string. For more general information about string lengths, see "Character-String Termination".







 



Valid in Client Application

Valid in DataBlade UDR

Yes
Yes

Usage

The ifx_gl_mbspbrk() function searches for the first occurrence of any multibyte character from the string mbs2 in the multibyte string mbs1.

Return Values

gl_mchar_t *
A pointer to the first byte of the first occurrence in mbs1 of any character from mbs2.

NULL
Either no character in mbs2 was found in mbs1 (the ifx_gl_lc_errno() error number is set to zero); or the function was not successful, and the error number is set to indicate the cause. See the Errors section.

Errors

If an error occurred, this function returns NULL and sets the ifx_gl_lc_errno() error number to one of the following values.


`IFX_GL_PARAMERR`	Either mbs1_byte_length is not equal to `IFX_GL_NULL` and is not greater than or equal to zero, or mbs2_byte_length is not equal to `IFX_GL_NULL` and is not greater than or equal to zero.
`IFX_GL_TERMMISMAT`	Either mbs1_byte_length is equal to `IFX_GL_NULL`, and mbs2_byte_length is greater than or equal to zero; or mbs1_byte_length is greater than or equal to zero, and mbs2_byte_length is equal to `IFX_GL_NULL.`
`IFX_GL_EILSEQ`	Either mbs1 or mbs2 contains an invalid multibyte character.
`IFX_GL_EINVAL`	Either the function cannot determine whether the last character of mbs1 is a valid multibyte character because it would need to read more than mbs1_byte_length bytes from mbs1, or the function cannot determine whether the last character of mbs2 is a valid multibyte character because it would need to read more than mbs2_byte_length bytes from mbs2. For more information about this error, see "Keeping Multibyte Strings Consistent".

ifx_gl_mbsprev()

The ifx_gl_mbsprev() function returns the previous multibyte character in a multibyte string.

Syntax

#include <ifxgls.h>

...
gl_mchar_t *ifx_gl_mbsprev(mbs_start, mb)

		gl_mchar_t *mbs_start;

		gl_mchar_t *mb; 


mbs_start
is a pointer to beginning of the multibyte string.

mb
is a pointer to the current multibyte character in the multibyte string.







 



Valid in Client Application

Valid in DataBlade UDR

Yes
Yes

Usage

The ifx_gl_mbsprev() function returns a pointer to the multibyte character before mb in a multibyte-character string. This function is typically used to transform the single-byte reverse-traversal loop to a multibyte loop. For example, suppose you have the following single-byte loop:

sb = sb0 + strlen(sb0);
for ( sb--; sb >= sb0; sb-- )
	/* Process single-byte character */

The following code fragment traverses the string with the ifx_gl_mbsprev() function instead of decrementing the pointer of the single-byte loop:

mb = mbs_start + strlen(mbs_start);
for ( mb = ifx_gl_mbsprev(mbs_start, mb) ; mb >= mbs_start; 

	mb = ifx_gl_mbsprev(mbs_start, mb) )
    /* Process multibyte character */

Return Values

gl_mchar_t *
A pointer to the first byte of the multibyte character immediately before mb.

NULL
The function was not successful, and the error number is set to indicate the cause. See the Errors section.

Errors

If an error occurred, this function returns NULL and sets the ifx_gl_lc_errno() error number to one of the following values.


`IFX_GL_EILSEQ`	The mb character or a character between mbs_start* and mb is not a valid multibyte character.
`IFX_GL_EINVPTR`	The mb value is less than or equal to mbs_start.
`IFX_GL_EINVAL`	The function cannot determine whether the character before mb is a valid multibyte character because it would need to read beyond mb. For more information about this error, see "Keeping Multibyte Strings Consistent".

ifx_gl_mbsrchr()

The ifx_gl_mbsrchr() function searches for the last occurrence of a character in a multibyte-character string.

Syntax

#include <ifxgls.h>

...
gl_mchar_t *ifx_gl_mbsrchr(mbs, mbs_byte_length, mb, mb_byte_limit)

		gl_mchar_t *mbs;

		int mbs_byte_length;

		gl_mchar_t *mb;

		int mb_byte_limit; 


mbs
is a pointer to the multibyte-character string in which the function searches for mb. 

mbs_byte_length
is the integer number of bytes in the mbs string. If mbs_byte_length is the value IFX_GL_NULL, the function assumes that mbs1 is a null-terminated string. For more general information about string lengths, see "Character-String Termination".

mb
is a pointer to the multibyte character to search for in mbs.

mb_byte_limit

is the number of bytes to read from the mb character to try to form a complete multibyte character. If mb_byte_limit is IFX_GL_NO_LIMIT, this function reads as many bytes as necessary from mb to form a complete character. For general information about mb_byte_limit, see "Multibyte-Character Termination".







 



Valid in Client Application

Valid in DataBlade UDR

Yes
Yes

Usage

The ifx_gl_mbsrchr() function locates the last occurrence of mb in the multibyte string mbs.

Return Values

gl_mchar_t *
A pointer to the last occurrence of mb in mbs.

NULL
Either mb was not found in mbs (the ifx_gl_lc_errno() error number is set to zero); or the function was not successful, and the error number is set to indicate the cause. See the Errors section.

Errors

If an error occurred, this function returns NULL and sets the ifx_gl_lc_errno() error number to one of the following values.


`IFX_GL_EILSEQ`	The mb value is an invalid multibyte character, or mbs* contains an invalid multibyte character.
`IFX_GL_EINVAL`	The function cannot determine whether mb is a valid multibyte character because it would need to read more than mb_byte_limit bytes from mb, or the function cannot determine whether the last character of mbs is a valid multibyte character because it would need to read more than mbs_byte_length bytes from mbs. If mb_byte_limit is less than or equal to zero, this function always returns this error. For more information about this error, see "Keeping Multibyte Strings Consistent".
`IFX_GL_PARAMERR`	The mbs_byte_length is not equal to `IFX_GL_NULL` and is not greater than or equal to zero.

ifx_gl_mbsspn()

The ifx_gl_mbsspn() function determines the length of a multibyte substring for a specified multibyte-character string.

Syntax

#include <ifxgls.h>

...
int ifx_gl_mbsspn(mbs1, mbs1_byte_length, mbs2, mbs2_byte_length)

		gl_mchar_t *mbs1;

		int mbs1_byte_length;

		gl_mchar_t *mbs2;

		int mbs2_byte_length; 


mbs1
is a pointer to the multibyte string to check for a substring of characters found in mbs2. 

mbs1_byte_length
is the integer number of bytes in the mbs1 string. If mbs1_byte_length is the value IFX_GL_NULL, the function assumes that mbs1 is a null-terminated string. For more general information about string lengths, see "Character-String Termination".

mbs2
is a pointer to the multibyte-character substring whose characters the functions searches for in mbs1.

mbs2_byte_length
is the integer number of bytes in the mbs2 string. If mbs2_byte_length is the value IFX_GL_NULL, the function assumes that mbs2 is a null-terminated string. For more general information about string lengths, see "Character-String Termination".







 



Valid in Client Application

Valid in DataBlade UDR

Yes
Yes

Usage

The ifx_gl_mbsspn() function returns the size of the initial substring of mbs1 that contains only characters that match characters in mbs2. The initial substring begins at the first character of mbs1. Therefore, this size is the number of characters in mbs1 before the first character that is not found in mbs2. For example, suppose you have the following two multibyte-characters strings, mbs1 and mbs2:

mbs1 = "A1A2B1B2B3C1C2D1D2D3A1A2E1F1F2A1A2G1D1D2D3";
mbs2 = "B1B2B3D1D2D3A1A2C1C2";

With these multibyte strings, the following call to the ifx_gl_mbsspn() function returns 5:

ifx_gl_mbsspn(mbs1, bytelen1, mbs2, bytelen2)

The first five characters of mbs1 are in mbs2. The sixth character in mbs1 is E1, which is not a character that matches one of the characters in mbs2.

Return Values

>=0
The number of characters in mbs1 before the first character that mbs1 and mbs2 differ.

-1
The function was not successful, and the error number is set to indicate the cause. See the Errors section.

Errors

If an error occurred, this function returns -1 and sets ifx_gl_lc_errno() to one of the following values.


`IFX_GL_PARAMERR`	Either mbs1_byte_length is not equal to `IFX_GL_NULL` and is not greater than or equal to zero, or mbs2_byte_length is not equal to `IFX_GL_NULL` and is not greater than or equal to zero.
`IFX_GL_TERMMISMAT`	Either mbs1_byte_length is equal to `IFX_GL_NULL`, and mbs2_byte_length is greater than or equal to zero; or mbs1_byte_length is greater than or equal to zero, and mbs2_byte_length is equal to `IFX_GL_NULL.`
`IFX_GL_EILSEQ`	Either mbs1 or mbs2 contains an invalid multibyte character.
`IFX_GL_EINVAL`	Either the function cannot determine whether the last character of mbs1 is a valid multibyte character because it would need to read more than mbs1_byte_length bytes from mbs1, or the function cannot determine whether the last character of mbs2 is a valid multibyte character because it would need to read more than mbs2_byte_length bytes from mbs2. For more information about this error, see "Keeping Multibyte Strings Consistent".

ifx_gl_mbstowcs()

The ifx_gl_mbstowcs() function converts a multibyte character string to its wide-character representation.

Syntax

#include <ifxgls.h>

...
int ifx_gl_mbstowcs(wcs, mbs, mbs_byte_length, char_limit)

		gl_wchar_t *wcs;

		gl_mchar_t *mbs;

		int mbs_byte_length;

		int char_limit; 


wcs
is a pointer to the wide-character string that contains the wide-character equivalent of mbs.

mbs
is a pointer to the multibyte-character string to convert to the wcs wide-character string.

mbs_byte_length
is the integer number of bytes in the mbs string. If mbs_byte_length is the value IFX_GL_NULL, the function assumes that mbs is a null-terminated string. For more general information about string lengths, see "Character-String Termination".

char_limit
is the maximum number of multibyte characters to read from mbs.







 



Valid in Client Application

Valid in DataBlade UDR

Yes
Yes

Usage

The ifx_gl_mbstowcs() function converts mbs into its wide-character representation and stores the result in the location that wcs references. The function reads no more than char_limit characters from mbs and writes them to wcs.

If mbs_byte_length is equal to IFX_GL_NULL, the function null-terminates the string in wcs. Any other value of mbs_byte_length means that the function does not null-terminate the resulting wide-character string.

Return Values

>=0
The number of characters read from mbs and written to wcs, not counting any null terminator.

-1
The function was not successful, and the error number is set to indicate the cause. See the Errors section.

Errors

If an error occurred, this function returns -1 and sets the ifx_gl_lc_errno() error number to one of the following values.


`IFX_GL_PARAMERR`	The mbs_byte_length is not equal to `IFX_GL_NULL` and is not greater than or equal to zero.
`IFX_GL_EILSEQ`	The *mbs value contains an invalid multibyte character.
`IFX_GL_EINVAL`	The function cannot determine whether the last character of mbs is a valid multibyte character because it would need to read more than mbs_byte_length bytes from mbs. For more information about this error, see "Keeping Multibyte Strings Consistent".

ifx_gl_mbtowc()

The ifx_gl_mbtowc() function converts one multibyte character to its wide-character representation.

Syntax

#include <ifxgls.h>

...
int ifx_gl_mbtowc(wc, mb, mb_byte_limit)

		gl_wchar_t *wc;

		gl_mchar_t *mb;

		int mb_byte_limit; 


wc
is a pointer to the wide character that contains the wide-character equivalent for mb.

mb
is a pointer to the multibyte character to convert to the wc wide character.

mb_byte_limit
is the integer number of bytes to read from mb to try to form a complete multibyte character. If mb_byte_limit is IFX_GL_NO_LIMIT, the function reads as many bytes as necessary from mb to form a complete character. For general information about mb_byte_limit, see "Multibyte-Character Termination".







 



Valid in Client Application

Valid in DataBlade UDR

Yes
Yes

Usage

The ifx_gl_mbtowc() function converts the multibyte character mb into its wide-character representation and stores the result in the wide character that wc references.

Return Values

>=0
The number of bytes read from mb.

-1
The function was not successful, and the error number is set to indicate the cause. See the Errors section.

Errors

If an error occurred, this function returns -1 and sets the ifx_gl_lc_errno() error number to one of the following values.


`IFX_GL_EILSEQ`	The *mb value is not a valid multibyte character.
`IFX_GL_EINVAL`	The function cannot determine whether mb is a valid multibyte character because it would need to read more than mb_byte_limit bytes from mb. If mb_byte_limit is less than or equal to zero, this function always returns this error. For more information about this error, see "Keeping Multibyte Strings Consistent".

ifx_gl_putmb()

The ifx_gl_putmb() function puts a single multibyte character in a user-defined location.

Syntax

#include <ifxgls.h>

...
int ifx_gl_putmb(mb, mb_byte_limit, funcp, v, bytes_put)

		gl_mchar_t *mb;

		int mb_byte_limit;

		int (*funcp)(gl_mchar_t byte, void *v);

		void *v;

		int *bytes_put; 


mb
is a pointer to the multibyte character whose bytes the funcp function writes to a specified location.

mb_byte_limit
is the number of bytes in mb that the ifx_gl_putmb() function reads when it tries to form a complete multibyte character. If mb_byte_limit is IFX_GL_NO_LIMIT, this function reads as many bytes as necessary from mb to form a complete character. For general information about mb_byte_limit, see "Multibyte-Character Termination".

funcp
is the funcp argument is a pointer to a function that you define to specify the location at which to write the multibyte character.

bytes_put
is a pointer to an integer that ifx_gl_putmb() sets to indicate the number of bytes that the funcp function has successfully written.







 



Valid in Client Application

Valid in DataBlade UDR

Yes
Yes

Usage

The ifx_gl_putmb() function calls a function that you define to put the bytes that form one multibyte character in a specified location. This multibyte character is read from the mb buffer.

The funcp argument is a pointer to a function that you must define as follows:

int funcp(gl_mchar_t byte, void *v)

On success, funcp must return zero (0). On failure, funcp must return -1. The number of bytes that funcp successfully puts is returned in bytes_put (even when failure is returned).

Return Values

0
The function was successful.

-1
The function was not successful, and the error number is set to indicate the cause. See the Errors section.

Errors

If an error occurred, this function returns -1 and sets the ifx_gl_lc_errno() error number to one of the following values.


`IFX_GL_EILSEQ`	The *mb value is not a valid multibyte character.
`IFX_GL_EINVAL`	The funcp function cannot determine whether mb is a valid multibyte character because it would need to read more than mb_byte_limit bytes from mb. If mb_byte_limit is less than or equal to zero, this function always returns this error. For more information about this error, see "Keeping Multibyte Strings Consistent".
`IFX_GL_EIO`	The funcp function returned -1 when first called.

ifx_gl_tomlower()

The ifx_gl_tomlower() function converts an uppercase multibyte character to its lowercase equivalent.

Syntax

#include <ifxgls.h>

...
unsigned short ifx_gl_tomlower(dst_mb, src_mb, src_mb_byte_limit)

		gl_mchar_t *dst_mb;

		gl_mchar_t *src_mb;

		int src_mb_byte_limit; 


dst_mb
is a pointer to the destination character, which holds the case conversion for the src_mb character.

src_mb
is a pointer to the source multibyte character that you want to convert to its lowercase equivalent.

src_mb_byte_limit
is the integer number of bytes to read from src_mb to try to form a complete multibyte character. If src_mb_byte_limit is IFX_GL_NO_LIMIT, this function reads as many bytes as necessary from src_mb to form a complete multibyte character. For general information about src_mb_byte_limit, see "Multibyte-Character Termination".







 



Valid in Client Application

Valid in DataBlade UDR

Yes
Yes

Usage

The ifx_gl_tomlower() function obtains the lowercase equivalent of the src_mb source multibyte character and stores it in the dst_mb destination buffer. If the locale does not define a lowercase equivalent for src_mb, ifx_gl_tomlower() copies src_mb to dst_mb unchanged.

For a multibyte-character string, the size of the lowercase multibyte string might not equal the size of the uppercase string. Therefore, to perform case conversion on multibyte characters, you must take the following special processing steps:

Determine whether you need to allocate a separate destination buffer

If a destination buffer is needed, determine its size

Determine the number of bytes that have been read and written in the case-conversion process

For more information on these steps, see "Case Conversion for Multibyte Characters".

The ifx_gl_tomlower() function returns an unsigned short integer that encodes the number of bytes read from src_mb and the number of bytes written to dst_mb. The INFORMIX-GLS library provides the following macros to obtain this information from the return value.

INFORMIX-GLS Macro Information Obtained
IFX_GL_CASE_CONV_SRC_BYTES()
The number of bytes read from the source string

IFX_GL_CASE_CONV_DST_BYTES()
The number of bytes written to the destination buffer

Return Values

>0
An unsigned short integer that encodes the number of bytes read from src_mb and the number of bytes written to dst_mb.

0
The function was not successful, and the error number is set to indicate the cause. See the Errors section.

Errors

This function does not return a unique value to indicate an error. If an error occurred, the function returns zero (0) and sets the ifx_gl_lc_errno() error number to one of the following values.


`IFX_GL_EILSEQ`	The *src_mb value is not a valid multibyte character.
`IFX_GL_EINVAL`	The function cannot determine whether src_mb is a valid multibyte character because it would need to read more than src_mb_byte_limit bytes from src_mb. If src_mb_byte_limit is less than or equal to zero, this function always returns this error. For more information about this error, see "Keeping Multibyte Strings Consistent".

ifx_gl_tomupper()

The ifx_gl_tomupper() function converts a lowercase multibyte character to its uppercase equivalent.

Syntax

#include <ifxgls.h>

...
unsigned short ifx_gl_tomupper(dst_mb, src_mb, src_mb_byte_limit)

		gl_mchar_t *dst_mb;

		gl_mchar_t *src_mb;

		int src_mb_byte_limit; 


dst_mb
is a pointer to the destination character, which holds the case conversion for the src_mb character.

src_mb
is a pointer to the source multibyte character that you want to convert to its uppercase equivalent.

src_mb_byte_limit
is the integer number of bytes to read from src_mb to try to form a complete multibyte character. If src_mb_byte_limit is IFX_GL_NO_LIMIT, this function reads as many bytes as necessary from src_mb to form a complete multibyte character. For general information about src_mb_byte_limit, see "Multibyte-Character Termination".







 



Valid in Client Application

Valid in DataBlade UDR

Yes
Yes

Usage

The ifx_gl_tomupper() function obtains the uppercase equivalent of the src_mb source multibyte character and stores it in the dst_mb destination buffer. If the locale does not define an uppercase equivalent for src_mb, ifx_gl_tomupper() copies src_mb to dst_mb unchanged.

For a multibyte-character string, the size of the uppercase multibyte string might not equal the size of the lowercase string. Therefore, to perform case conversion on multibyte characters, you must take the following special processing steps:

Determine whether you need to allocate a separate destination buffer.

If a destination buffer is needed, determine its size.

Determine the number of bytes that have been read and written in the case-conversion process.

For more information on these steps, see "Case Conversion for Multibyte Characters".

The ifx_gl_tomupper() function returns an unsigned short integer that encodes the number of bytes read from src_mb and the number of bytes written to dst_mb. The INFORMIX-GLS library provides the following macros to obtain this information from the return value.

INFORMIX-GLS Macro Information Obtained
IFX_GL_CASE_CONV_SRC_BYTES()
The number of bytes read from the source string

IFX_GL_CASE_CONV_DST_BYTES()
The number of bytes written to the destination buffer

Return Values

>0
An unsigned short integer that encodes the number of bytes read from src_mb and the number of bytes written to dst_mb.

0
The function was not successful, and the error number is set to indicate the cause. See the Errors section.

Errors


`IFX_GL_EILSEQ`	The *src_mb value is not a valid multibyte character.
`IFX_GL_EINVAL`	The function cannot determine whether src_mb is a valid multibyte character because it would need to read more than src_mb_byte_limit bytes from src_mb. If src_mb_byte_limit is less than or equal to zero, this function always returns this error. For more information about this error, see "Keeping Multibyte Strings Consistent".

ifx_gl_towlower()

The ifx_gl_towlower() function converts an uppercase wide character to its lowercase equivalent.

Syntax

#include <ifxgls.h>

...
unsigned short ifx_gl_towlower(src_wc)

		gl_mchar_t *src_wc; 


src_wc
is a pointer to the source wide character that you want to convert to its lowercase equivalent.







 



Valid in Client Application

Valid in DataBlade UDR

Yes
Yes

Usage

The ifx_gl_towlower() function returns the lowercase equivalent of the src_wc source wide character. If the locale does not define a lowercase equivalent for src_wc, ifx_gl_towlower() returns src_wc unchanged.

Return Values

>0
An unsigned short integer that represents the lowercase equivalent of src_wc.

0
The function was not successful, and the error number is set to indicate the cause. See the Errors section.

Errors

This function does not return a unique value to indicate an error. If an error occurred, the function returns zero (0) and sets the ifx_gl_lc_errno() error number to the following value.


`IFX_GL_EILSEQ`	The *src_wc value is not a valid wide character.

ifx_gl_towupper()

The ifx_gl_towupper() function converts a lowercase wide character to its uppercase equivalent.

Syntax

#include <ifxgls.h>

...
unsigned short ifx_gl_towupper(src_wc)

		gl_mchar_t *src_wc; 


src_wc
is a pointer to the source wide character that you want to convert to its uppercase equivalent.







 



Valid in Client Application

Valid in DataBlade UDR

Yes
Yes

Usage

The ifx_gl_towupper() function returns the uppercase equivalent of the src_wc source wide character. If the locale does not define a uppercase equivalent for src_wc, ifx_gl_towupper() returns src_wc unchanged.

Return Values

>0
An unsigned short integer that represents the uppercase equivalent of src_wc.

0
The function was not successful, and the error number is set to indicate the cause. See the Errors section.

Errors

This function does not return a unique value to indicate an error. If an error occurred, the function returns zero (0) and sets the ifx_gl_lc_errno() error number to the following value.


`IFX_GL_EILSEQ`	The *src_wc value is not a valid wide character.

ifx_gl_wcscat()

The ifx_gl_wcscat() function concatenates two wide-character strings.

Syntax

#include <ifxgls.h>

...
int ifx_gl_wcscat(wcs1, wcs1_char_length, wcs2, wcs2_char_length)

		gl_wchar_t *wcs1;

		int wcs1_char_length;

		gl_wchar_t *wcs2;

		int wcs2_char_length; 


wcs1
is a pointer to the wide-character string to which the function concatenates wcs2. 

wcs1_char_length
is the integer number of characters in the wcs1 string. If wcs1_char_length is the value IFX_GL_NULL, the function assumes that wcs1 is a null-terminated string. For more information about wide-character lengths, see "Character-String Termination".

wcs2
is a pointer to the wide-character string to concatenate onto wcs1.

wcs2_char_length
is the integer number of characters in the wcs2 string. If wcs2_char_length is the value IFX_GL_NULL, the function assumes that wcs2 is a null-terminated string. For more information about wide-character lengths, see "Character-String Termination".







 



Valid in Client Application

Valid in DataBlade UDR

Yes
Yes

Usage

The ifx_gl_wcscat() function appends a copy of wcs2 to the end of wcs1. If wcs1 and wcs2 overlap, the results of this function are undefined.

Return Values

>=0
The number of characters in the concatenated string, not including any null terminator.

-1
The function was not successful, and the error number is set to indicate the cause. See the Errors section.

Errors

If an error occurred, this function returns -1 and sets the ifx_gl_lc_errno() error number to one of the following values.


`IFX_GL_PARAMERR`	Either wcs1_char_length is not equal to `IFX_GL_NULL` and is not greater than or equal to zero, or wcs2_char_length is not equal to `IFX_GL_NULL` and is not greater than or equal to zero.
`IFX_GL_TERMMISMAT`	Either wcs1_char_length is equal to `IFX_GL_NULL`, and wcs2_char_length is greater than or equal to zero; or wcs1_char_length is greater than or equal to zero, and wcs2_char_length is equal to `IFX_GL_NULL.`

ifx_gl_wcschr()

The ifx_gl_wcschr() function searches for the first occurrence of a character in a wide-character string.

Syntax

#include <ifxgls.h>

...
gl_wchar_t *ifx_gl_wcschr(wcs, wcs_char_length, wc)

		gl_wchar_t *wcs;

		int wcs_char_length;

		gl_wchar_t wc; 


wcs
is a pointer to the wide-character string in which the function searches for wc. 

wcs_char_length
is the integer number of characters in the wcs string. If wcs_char_length is the value IFX_GL_NULL, the function assumes that wcs is a null-terminated string. For more information about wide-character lengths, see "Character-String Termination".

wc
is a pointer to the wide character to search for in wcs.







 



Valid in Client Application

Valid in DataBlade UDR

Yes
Yes

Usage

The ifx_gl_wcschr() function locates the first occurrence of wc in the wide-character string wcs.

Return Values

gl_wchar_t *
A pointer to the first occurrence of wc in wcs.

NULL
Either wc was not found in wcs (the ifx_gl_lc_errno() error number is set to zero); or the function was not successful, and the error number is set to indicate the cause. See the Errors section.

Errors

If an error occurred, this function returns NULL and sets the ifx_gl_lc_errno() error number to the following value.


`IFX_GL_PARAMERR`	The wcs_char_length is not equal to `IFX_GL_NULL` and is not greater than or equal to zero.

ifx_gl_wcscoll()

The ifx_gl_wcscoll() function uses localized collation order to compare two wide-character strings.

Syntax

#include <ifxgls.h>

...
int ifx_gl_wcscoll(wcs1, wcs1_char_length, wcs2, wcs2_char_length)

		gl_wchar_t *wcs1;

		int wcs1_char_length;

		gl_wchar_t *wcs2;

		int wcs2_char_length; 


wcs1
is a pointer to the wide-character string to compare with wcs2. 

wcs1_char_length
is the integer number of characters in the wcs1 string. If wcs1_char_length is the value IFX_GL_NULL, the function assumes that wcs1 is a null-terminated string. For more information about wide-character lengths, see "Character-String Termination".

wcs2
is a pointer to the wide-character string to compare with wcs1.

wcs2_char_length
is the integer number of characters in the wcs2 string. If wcs2_char_length is the value IFX_GL_NULL, the function assumes that wcs2 is a null-terminated string. For more information about wide-character lengths, see "Character-String Termination".







 



Valid in Client Application

Valid in DataBlade UDR

Yes
Yes

Usage

The ifx_gl_wcscoll() function uses localized collation order to compare the wide-character strings wcs1 and wcs2.

Locale Information

The LC_COLLATE category of the current locale affects the behavior of this function because it defines the localized collation order. For more information, see "Character/String Comparison and Sorting".

Return Values

<0
The wcs1 string is less than the wcs2 string (wcs1 < wcs2), or the function was not successful, and the error number is set to indicate the cause. See the Errors section.

=0
The wcs1 string is equal to the wcs2 string (wcs1 = wcs2).

>0
The wcs1 string is greater than the wcs2 string (wcs1 > wcs2).

Errors

This function does not return a unique value to indicate an error. If an error occurred, this function returns -1 and sets the ifx_gl_lc_errno() error number to one of the following values.


`IFX_GL_PARAMERR`	Either wcs1_char_length is not equal to `IFX_GL_NULL` and is not greater than or equal to zero, or wcs2_char_length is not equal to `IFX_GL_NULL` and is not greater than or equal to zero.
`IFX_GL_TERMMISMAT`	Either wcs1_char_length is equal to `IFX_GL_NULL`, and wcs2_char_length is greater than or equal to zero; or wcs1_char_length is greater than or equal to zero, and wcs2_char_length is equal to `IFX_GL_NULL`.
`IFX_GL_EILSEQ`	Either wcs1 or wcs2 contains an invalid wide character.
`IFX_GL_ENOMEM`	Not enough memory exists to complete the operation.

ifx_gl_wcscpy()

The ifx_gl_wcscpy() function copies a wide-character string.

Syntax

#include <ifxgls.h>

...
int ifx_gl_wcscpy(wcs1, wcs2, wcs2_char_length)

		gl_wchar_t *wcs1;

		gl_wchar_t *wcs2;

		int wcs2_char_length; 


wcs1
is a pointer to the location where the function copies wcs2. 

wcs2
is a pointer to the wide-character string to copy to wcs1.

wcs2_char_length
is the integer number of characters in the wcs2 string. If wcs2_char_length is the value IFX_GL_NULL, the function assumes that wcs2 is a null-terminated string. For more information about wide-character lengths, see "Character-String Termination".







 



Valid in Client Application

Valid in DataBlade UDR

Yes
Yes

Usage

The ifx_gl_wcscpy() function copies the wide-character string wcs2 to the location that wcs1 references. If wcs1 and wcs2 overlap, the results of this function are undefined.

Return Values

>=0
The number of bytes in the copied string, not including any null terminator.

-1
The function was not successful, and the error number is set to indicate the cause. See the Errors section.

Errors

If an error occurred, this function returns -1 and sets the ifx_gl_lc_errno() error number to the following value.


`IFX_GL_PARAMERR`	The wcs2_char_length is not equal to `IFX_GL_NULL` and is not greater than or equal to zero.

ifx_gl_wcscspn()

The ifx_gl_wcscspn() function determines the length of a complementary wide-character substring for a wide-character string.

Syntax

#include <ifxgls.h>

...
int ifx_gl_wcscspn(wcs1, wcs1_char_length, wcs2, wcs2_char_length)

		gl_wchar_t *wcs1;

		int wcs1_char_length;

		gl_wchar_t *wcs2;

		int wcs2_char_length; 


wcs1
is a pointer to the wide-character string to check for the complementary substring of characters in wcs2. 

wcs1_char_length
is the integer number of characters in the wcs1 string. If wcs1_char_length is the value IFX_GL_NULL, the function assumes that wcs1 is a null-terminated string. For more information about wide-character lengths, see "Character-String Termination".

wcs2
is a pointer to the string of wide-characters to search in wcs1.

wcs2_char_length
is the integer number of characters in the wcs2 string. If wcs2_char_length is the value IFX_GL_NULL, the function assumes that wcs2 is a null-terminated string. For more information about wide-character lengths, see "Character-String Termination".







 



Valid in Client Application

Valid in DataBlade UDR

Yes
Yes

Usage

The ifx_gl_wcscspn() function returns the size of the initial substring of wcs1 that does not contain any characters that match characters in wcs2. The initial substring begins at the first character of wcs1. Therefore, this size is the number of characters in wcs1 before the first character that the wcs1 and wcs2 strings have in common. The string of unmatched characters is called the complementary string.

For example, suppose you have the following two wide-character strings, wcs1 and wcs2:

wcs1 = "A1A2B1B2C1C2D1D2A1A2E1E2F1F2A1A2G1G2D1D2";
wcs2 = "F1F2G1D1D2";

With these wide-character strings, the following call to the ifx_gl_wcscspn() function returns 3:

ifx_gl_wcscspn(wcs1, charlen1, wcs2, charlen2)

The first three characters of wcs1 are not in wcs2. The fourth character in wcs1 is D1D2, which is in wcs2 also.

Return Values

>=0
The number of characters in the initial substring of wcs1 that consist entirely of wide characters not in the string wcs2.

-1
The function was not successful, and the error number is set to indicate the cause. See the Errors section.

Errors

If an error occurred, this function returns NULL and sets the ifx_gl_lc_errno() error number to one of the following values.


`IFX_GL_PARAMERR`	Either wcs1_char_length is not equal to `IFX_GL_NULL`, and is not greater than or equal to zero; or wcs2_char_length is not equal to `IFX_GL_NULL`, and is not greater than or equal to zero.
`IFX_GL_TERMMISMAT`	Either wcs1_char_length is equal to `IFX_GL_NULL`, and wcs2_char_length is greater than or equal to zero; or wcs1_char_length is greater than or equal to zero, and wcs2_char_length is equal to `IFX_GL_NULL`.

ifx_gl_wcslen()

The ifx_gl_wcslen() function determines the number of characters in a wide-character string.

Syntax

#include <ifxgls.h>

...
int ifx_gl_wcslen(wcs)

		gl_wchar_t *wcs; 


wcs
is a pointer to the wide-character string whose length the function determines. 







 



Valid in Client Application

Valid in DataBlade UDR

Yes
Yes

Usage

The ifx_gl_wcslen() function computes the number of wide characters in the wide character string to which wcs points, not including the null-terminating wide-character code. The length that ifx_gl_wcslen() returns includes any trailing white space. The trailing-space characters are all characters that the blank character class of the current locale defines. For more information on the blank class, see "Character Classification".

For example, the following call to ifx_gl_wcslen() return a value of 7
(where A1A2, B1B2, and C1C2 are wide characters of 2 bytes each, and s1s2 is the wide-character blank space):

    ifx_gl_wcslen("A1A2B1B2s1s2C1C2s1s2s1s2s1s2")

Use the ifx_gl_wcntslen() function if you want the length without trailing white space.

Return Values

>=0
The number of characters in the wcs string, not including any null terminator but including any trailing white space.

-1
The function was not successful, and the error number is set to indicate the cause. See the Errors section.

Errors

If an error occurred, this function returns -1 and sets the ifx_gl_lc_errno() error number to the following value.


`IFX_GL_EILSEQ`	The *wcs value contains an invalid wide character.

ifx_gl_wcsncat()

The ifx_gl_wcsncat() function concatenates a specified number of wide characters in one wide-character string to another.

Syntax

#include <ifxgls.h>

...
int ifx_gl_wcsncat(wcs1, wcs1_char_length, wcs2, wcs2_char_length, char_limit)

		gl_wchar_t *wcs1;

		int wcs1_char_length;

		gl_wchar_t *wcs2;

		int wcs2_char_length;

		int char_limit; 


wcs1
is a pointer to the wide-character string to which the function concatenates wcs2. 

wcs1_char_length
is the integer number of characters in the wcs1 string. If wcs1_char_length is the value IFX_GL_NULL, the function assumes that wcs1 is a null-terminated string. For more general information about wide-character lengths, see "Character-String Termination".

wcs2
is a pointer to the wide-character string to concatenate to wcs1.

wcs2_char_length
is the integer number of characters in the wcs2 string. If wcs2_char_length is the value IFX_GL_NULL, the function assumes that wcs2 is a null-terminated string. For more general information about wide-character lengths, see "Character-String Termination".

char_limit
is the maximum number of wide characters to read from wcs2.







 



Valid in Client Application

Valid in DataBlade UDR

Yes
Yes

Usage

The ifx_gl_wcsncat() function appends wcs2 to the end of wcs1. If wcs1 and wcs2 overlap, the results of this function are undefined. The function reads no more than char_limit characters from wcs2 and writes them to wcs1.

Return Values

>=0
The number of bytes in the concatenated string, not including any null terminator.

-1
The function was not successful, and the error number is set to indicate the cause. See the Errors section.

Errors

If an error occurred, this function returns -1 and sets the ifx_gl_lc_errno() error number to the following value.


`IFX_GL_PARAMERR`	Either wcs1_char_length is not equal to `IFX_GL_NULL`, and is not greater than or equal to zero; or wcs2_char_length is not equal to `IFX_GL_NULL`, and is not greater than or equal to zero.
`IFX_GL_TERMMISMAT`	Either wcs1_char_length is equal to `IFX_GL_NULL`, and wcs2_char_length is greater than or equal to zero; or wcs1_char_length is greater than or equal to zero, and wcs2_char_length is equal to `IFX_GL_NULL`.

ifx_gl_wcsncpy()

The ifx_gl_wcsncpy() function copies a specified number of wide characters from a wide-character string.

Syntax

#include <ifxgls.h>

...
int ifx_gl_wcsncpy(wcs1, wcs2, wcs2_char_length, char_limit)

		gl_wchar_t *wcs1;

		gl_wchar_t *wcs2;

		int wcs2_char_length;

		int char_limit; 


wcs1
is a pointer to the location where the function copies wcs2. 

wcs2
is a pointer to the wide-character string to copy to wcs1.

wcs2_char_length
is the integer number of characters in the wcs2 string. If wcs2_char_length is the value IFX_GL_NULL, the function assumes that wcs2 is a null-terminated string. For more general information about wide-character lengths, see "Character-String Termination".

char_limit
is the maximum number of wide characters to read from wcs2.







 



Valid in Client Application

Valid in DataBlade UDR

Yes
Yes

Usage

The ifx_gl_wcsncpy() function copies wcs2 to the location that wcs1 references. The function reads no more than char_limit characters from wcs2 and writes them to wcs1. If wcs1 and wcs2 overlap, the results of this function are undefined.

Return Values

>=0
The number of characters in the copied string, not including any null terminator.

-1
The function was not successful, and the error number is set to indicate the cause. See the Errors section.

Errors

If an error occurred, this function returns -1 and sets the ifx_gl_lc_errno() error number to the following value.


`IFX_GL_PARAMERR`	The wcs2_char_length is not equal to `IFX_GL_NULL` and is not greater than or equal to zero.

ifx_gl_wcsntslen()

The ifx_gl_wcsntslen() function determines the number of characters in a wide-character string. It ignores trailing spaces.

Syntax

#include <ifxgls.h>

...
int ifx_gl_wcsntslen(wcs, wcs_char_length)

		gl_wchar_t *wcs;

		int wcs_char_length; 


wcs
is a pointer to the wide-character string whose length the function determines. 

wcs_char_length
is the integer number of characters in the wcs string. If wcs_char_length is the value IFX_GL_NULL, the function assumes that wcs is a null-terminated string. For more information about wide-character lengths, see "Character-String Termination".







 



Valid in Client Application

Valid in DataBlade UDR

Yes
Yes

Usage

The ifx_gl_wcsntslen() function returns the number of characters in wcs, not including the trailing-space characters. The trailing-space characters are all characters that the blank character class of the current locale defines. For more information on the blank class, see "Character Classification".

Space characters that are embedded in the string at any place except the end of the string are included in the count. For example, the following call to ifx_gl_wcsntslen() returns a value of 4 (the number of wide characters in the string "A1A2B1B2s1s2C1C2", where A1A2, B1B2, and C1C2 are wide characters of 2 bytes each, and s1s2 is the wide-character blank space):

    ifx_gl_wcsntslen("A1A2B1B2s1s2C1C2s1s2s1s2s1s2")

Use the ifx_gl_wcslen() function if you want the length to include trailing white space.

Return Values

>=0
The number of characters in the wcs string, not including any trailing space.

-1
The function was not successful, and the error number is set to indicate the cause. See the Errors section.

Errors

If an error occurred, this function returns -1 and sets the ifx_gl_lc_errno() error number to the following value.


`IFX_GL_PARAMERR`	The wcs_char_length is not equal to `IFX_GL_NULL` and is not greater than or equal to zero.

ifx_gl_wcspbrk()

The ifx_gl_wcspbrk() function searches for any wide character from one wide-character string in another wide-character string.

Syntax

#include <ifxgls.h>

...
gl_wchar_t *ifx_gl_wcspbrk(wcs1, wcs1_char_length, wcs2, wcs2_char_length)

		gl_wchar_t *wcs1;

		int wcs1_char_length;

		gl_wchar_t *wcs2;

		int wcs2_char_length; 


wcs1
is a pointer to the wide-character string to search for any character in wcs2. 

wcs1_char_length
is the integer number of characters in the wcs1 string. If wcs1_char_length is the value IFX_GL_NULL, the function assumes that wcs1 is a null-terminated string. For more information about wide-character lengths, see "Character-String Termination".

wcs2
is a pointer to the wide-character string whose characters the function searches for in wcs1.

wcs2_char_length
is the integer number of characters in the wcs2 string. If wcs2_char_length is the value IFX_GL_NULL, the function assumes that wcs2 is a null-terminated string. For more information about wide-character lengths, see "Character-String Termination".







 



Valid in Client Application

Valid in DataBlade UDR

Yes
Yes

Usage

The ifx_gl_wcspbrk() function searches for the first occurrence of any wide character from the string wcs2 in the wide-character string wcs1.

Return Values

gl_wchar_t *
A pointer to the first byte of the first occurrence in wcs1 of any character from wcs2.

NULL
Either no character in wcs2 was found in wcs1 (the ifx_gl_lc_errno() error number is set to zero); or the function was not successful, and the error number is set to indicate the cause. See the Errors section.

Errors

If an error occurred, this function returns NULL and sets the ifx_gl_lc_errno() error number to one of the following values.


`IFX_GL_PARAMERR`	Either wcs1_char_length is not equal to `IFX_GL_NULL` and is not greater than or equal to zero, or wcs2_char_length is not equal to `IFX_GL_NULL` and is not greater than or equal to zero.
`IFX_GL_TERMMISMAT`	Either wcs1_char_length is equal to `IFX_GL_NULL`, and wcs2_char_length is greater than or equal to zero; or wcs1_char_length is greater than or equal to zero, and wcs2_char_length is equal to `IFX_GL_NULL`.

ifx_gl_wcsrchr()

The ifx_gl_wcsrchr() function searches for the last occurrence of a character in a wide-character string.

Syntax

#include <ifxgls.h>

...
gl_wchar_t *ifx_gl_wcsrchr(wcs, wcs_char_length, wc)

		gl_wchar_t *wcs;

		int wcs_char_length;

		gl_wchar_t wc; 


wcs
is a pointer to the wide-character string in which the function searches for wc. 

wcs_char_length
is the integer number of characters in the wcs string. If wcs_char_length is the value IFX_GL_NULL, the function assumes that wcs is a null-terminated string. For more information about wide-character lengths, see "Character-String Termination".

wc
is a pointer to the wide character to search for in wcs.







 



Valid in Client Application

Valid in DataBlade UDR

Yes
Yes

Usage

The ifx_gl_wcsrchr() function locates the last occurrence of wc in the wide character string wcs.

Return Values

gl_wchar_t *
A pointer to the last occurrence of wc in wcs.

NULL
Either wc was not found in wcs (the ifx_gl_lc_errno() error number is set to zero); or the function was not successful, and the error number is set to indicate the cause. See the Errors section.

Errors

If an error occurred, this function returns NULL and sets the ifx_gl_lc_errno() error number to the following value.


`IFX_GL_PARAMERR`	The wcs_char_length is not equal to `IFX_GL_NULL` and is not greater than or equal to zero.

ifx_gl_wcsspn()

The ifx_gl_wcsspn() function determines the length of a wide-character sub-string for a specified wide-character string.

Syntax

#include <ifxgls.h>

...
int ifx_gl_wcsspn(wcs1, wcs1_char_length, wcs2, wcs2_char_length)

		l_wchar_t *wcs1;

		int wcs1_char_length;

		gl_wchar_t *wcs2;

		int wcs2_char_length; 


wcs1
is a pointer to the wide-character string to check for a substring of characters found in wcs2. 

wcs1_char_length
is the integer number of characters in the wcs1 string. If wcs1_char_length is the value IFX_GL_NULL, the function assumes that wcs1 is a null-terminated string. For more information about wide-character lengths, see "Character-String Termination".

wcs2
is a pointer to the wide-character string whose characters the function searches for in wcs1.

wcs2_char_length
is the integer number of characters in the wcs2 string. If wcs2_char_length is the value IFX_GL_NULL, the function assumes that wcs2 is a null-terminated string. For more information about wide-character lengths, see "Character-String Termination".







 



Valid in Client Application

Valid in DataBlade UDR

Yes
Yes

Usage

The ifx_gl_wcsspn() function returns the size of the initial substring of wcs1 that contains only characters that match characters in wcs2. The initial substring begins at the first character of wcs1. Therefore, this size is the number of characters in wcs1 before the first character that is not found in wcs2.

For example, suppose you have the following two wide-character strings, wcs1 and wcs2:

wcs1 = "A1A2B1B2C1C2D1D2A1A2E1E2F1F2A1A2G1G2D1D2";
wcs2 = "B1B2D1D2A1A2C1C2";

With these multibyte strings, the following call to the ifx_gl_wcsspn() function returns 5:

ifx_gl_wcsspn(wcs1, charlen1, wcs2, charlen2)

The first five characters of wcs1 are in wcs2. The sixth character in wcs1 is E1E2, which is not a character that matches one of the characters in wcs2.

Return Values

>=0
The number of characters in the initial substring of wcs1 that consist entirely of wide characters in the string wcs2.

-1
The function was not successful, and the error number is set to indicate the cause. See the Errors section.

Errors

If an error occurred, this function returns -1 and sets the ifx_gl_lc_errno() error number to one of the following values.


`IFX_GL_PARAMERR`	Either wcs1_char_length is not equal to `IFX_GL_NULL` and is not greater than or equal to zero, or wcs2_char_length is not equal to `IFX_GL_NULL` and is not greater than or equal to zero.
`IFX_GL_TERMMISMAT`	Either wcs1_char_length is equal to `IFX_GL_NULL`, and wcs2_char_length is greater than or equal to zero; or wcs1_char_length is greater than or equal to zero, and wcs2_char_length is equal to `IFX_GL_NULL`.

ifx_gl_wcstombs()

The ifx_gl_wcstombs() function converts a wide-character string to its multibyte representation.

Syntax

#include <ifxgls.h>

...
int ifx_gl_wcstombs(mbs, wcs, wcs_char_length, mbs_byte_limit)

		gl_mchar_t *mbs;

		gl_wchar_t *wcs;

		int wcs_char_length;

		int mbs_byte_limit; 


mbs
is a pointer to the multibyte-character string that contains the multibyte equivalent for wcs. 

wcs
is a pointer to the wide-character string to convert to the mbs multibyte string.

wcs_char_length
is the integer number of characters in the wcs string. If wcs_char_length is the value IFX_GL_NULL, the function assumes that wcs is a null-terminated string. For more general information about wide-character lengths, see "Character-String Termination".

mbs_byte_limit
is the integer number of bytes to read from mbs.







 



Valid in Client Application

Valid in DataBlade UDR

Yes
Yes

Usage

The ifx_gl_wcstombs() function converts the wide-character string wcs to its multibyte representation and stores the result in the location that mbs references.

The function writes at most mbs_byte_limit bytes to mbs. If a particular character would cause more than mbs_byte_limit bytes to be written to mbs, no part of that character is written to mbs. In this case, fewer than mbs_byte_limit bytes are written to mbs, but mbs is still considered full.

If wcs_char_length is equal to IFX_GL_NULL, the function null-terminates mbs. Any other value of wcs_char_length means that the function does not null-terminate the resulting string.

Return Values

>=0
The number of characters that were written to mbs, not including any null terminator.

-1
The function was not successful, and the error number is set to indicate the cause. See the Errors section.

Errors

If an error occurred, this function returns -1 and sets the ifx_gl_lc_errno() error number to one of the following values.


`IFX_GL_PARAMERR`	The wcs_char_length is not equal to `IFX_GL_NULL` and is not greater than or equal to zero.
`IFX_GL_EILSEQ`	The *wcs value contains an invalid wide character.

ifx_gl_wcswcs()

The ifx_gl_wcswcs() function searches for a specified substring within a wide-character string.

Syntax

#include <ifxgls.h>

...
gl_wchar_t *ifx_gl_wcswcs(wcs1, wcs1_char_length, wcs2, wcs2_char_length)

		gl_wchar_t *wcs1;

		int wcs1_char_length;

		gl_wchar_t *wcs2;

		int wcs2_char_length; 


wcs1
is a pointer to the wide-character string to search for the substring wcs2. 

wcs1_char_length
is the integer number of characters in the wcs1 string. If wcs1_char_length is the value IFX_GL_NULL, the function assumes that wcs1 is a null-terminated string. For more information about wide-character lengths, see "Character-String Termination".

wcs2
is a pointer to the wide-character substring to search for in wcs1.

wcs2_char_length
is the integer number of characters in the wcs2 string. If wcs2_char_length is the value IFX_GL_NULL, the function assumes that wcs2 is a null-terminated string. For more information about wide-character lengths, see "Character-String Termination".







 



Valid in Client Application

Valid in DataBlade UDR

Yes
Yes

Usage

The ifx_gl_wcswcs() function searches for the first occurrence of the wide-character string wcs2 in the wide-character string wcs1.

Return Values

gl_wchar_t *
A pointer to the first byte of the first occurrence of wcs2 in wcs1.

NULL
Either wcs2 was not found in wcs1 (the ifx_gl_lc_errno() error number is set to zero); or the function was not successful, and the error number is set to indicate the cause. See the Errors section.

Errors

If an error occurred, this function returns NULL and sets the ifx_gl_lc_errno() error number to one of the following values.


`IFX_GL_PARAMERR`	Either wcs1_char_length is not equal to `IFX_GL_NULL` and is not greater than or equal to zero, or wcs2_char_length is not equal to `IFX_GL_NULL` and is not greater than or equal to zero.
`IFX_GL_TERMMISMAT`	Either wcs1_char_length is equal to `IFX_GL_NULL`, and wcs2_char_length is greater than or equal to zero; or wcs1_char_length is greater than or equal to zero, and wcs2_char_length is equal to `IFX_GL_NULL`.

ifx_gl_wctomb()

The ifx_gl_wctomb() function converts one wide character to its multibyte representation.

Syntax

#include <ifxgls.h>

...
int ifx_gl_wctomb(mb, wc)

		gl_mchar_t *mb;

		gl_wchar_t wc; 


mb
is a pointer to the multibyte character that contains the multibyte equivalent for wc. 

wc
is a pointer to the wide character to convert to the mb multibyte character.







 



Valid in Client Application

Valid in DataBlade UDR

Yes
Yes

Usage

The ifx_gl_wctomb() function converts the wide character in wc to its multibyte representation and stores the result in consecutive bytes that start at mb. This function assumes that mb contains enough space to hold the multibyte representation of wc. You can use either of the following methods to determine the number of bytes that will be written to mb:

The function ifx_gl_mb_loc_max() calculates the maximum number of bytes in the multibyte representation for any wide character for the current locale.
The macro IFX_GL_MB_MAX is the maximum number of bytes in the multibyte representation for any wide character in any locale.

ifx_gl_mb_loc_max()

Of the two options, the macro IFX_GL_MB_MAX is the faster and the only one that you can use to initialize static buffers. The function ifx_gl_mb_loc_max() is slower, but it is more precise.

Return Values

>=0
The number of bytes written to mb.

-1
The function was not successful, and the error number is set to indicate the cause. See the Errors section.

Errors

If an error occurred, this function returns -1 and sets the ifx_gl_lc_errno() error number to the following value.


`IFX_GL_EILSEQ`	The *wc value is not a valid wide character. In this case, some bytes might be written to mb, but the contents of mb are undefined.

INFORMIX-GLS Programmer's GuideChapter 4: INFORMIX-GLS Function Descriptions Home Contents Index Master Index New Book

ifx_gl_mbsmbs()

Usage

Return Values gl_mchar_t * A pointer to the first byte of the first occurrence of mbs2 in mbs1. NULL Either mbs2 was not found in mbs1 (the ifx_gl_lc_errno() error number is set to zero); or the function was not successful, and the error number is set to indicate the cause. See the Errors section.

Errors

Usage

Return Values >=0 The number of bytes in the concatenated string, not including any null terminator. -1 The function was not successful, and the error number is set to indicate the cause. See the Errors section.

Errors

Usage

Return Values >=0 The number of bytes in the copied string, not including any null terminator. -1 The function was not successful, and the error number is set to indicate the cause. See the Errors section.

Errors

Return Values gl_mchar_t * A pointer to the byte that immediately follows mb. NULL The function was not successful, and the error number is set to indicate the cause. See the Errors section.

Errors

Return Values >=0 The number of bytes in the mbs string, not including any trailing space. -1 The function was not successful, and the error number is set to indicate the cause. See the Errors section.

Errors

Usage

Return Values >=0 The number of characters in the mbs string, not including any trailing space. -1 The function was not successful, and the error number is set to indicate the cause. See the Errors section.

Errors

Errors

Usage

Return Values gl_mchar_t * A pointer to the first byte of the multibyte character immediately before mb. NULL The function was not successful, and the error number is set to indicate the cause. See the Errors section.

Errors

Usage

Return Values gl_mchar_t * A pointer to the last occurrence of mb in mbs. NULL Either mb was not found in mbs (the ifx_gl_lc_errno() error number is set to zero); or the function was not successful, and the error number is set to indicate the cause. See the Errors section.

Errors

Usage

Return Values >=0 The number of characters in mbs1 before the first character that mbs1 and mbs2 differ. -1 The function was not successful, and the error number is set to indicate the cause. See the Errors section.

Errors

Usage

Return Values >=0 The number of characters read from mbs and written to wcs, not counting any null terminator. -1 The function was not successful, and the error number is set to indicate the cause. See the Errors section.

Errors

Usage

Return Values >=0 The number of bytes read from mb. -1 The function was not successful, and the error number is set to indicate the cause. See the Errors section.

Errors

Usage

Return Values 0 The function was successful. -1 The function was not successful, and the error number is set to indicate the cause. See the Errors section.

Errors

Usage

Return Values >0 An unsigned short integer that encodes the number of bytes read from src_mb and the number of bytes written to dst_mb. 0 The function was not successful, and the error number is set to indicate the cause. See the Errors section.

Errors

Usage

Return Values >0 An unsigned short integer that encodes the number of bytes read from src_mb and the number of bytes written to dst_mb. 0 The function was not successful, and the error number is set to indicate the cause. See the Errors section.

Errors

Usage

Return Values >0 An unsigned short integer that represents the lowercase equivalent of src_wc. 0 The function was not successful, and the error number is set to indicate the cause. See the Errors section.

Errors

Usage

Return Values >0 An unsigned short integer that represents the uppercase equivalent of src_wc. 0 The function was not successful, and the error number is set to indicate the cause. See the Errors section.

Errors

Usage

Return Values >=0 The number of characters in the concatenated string, not including any null terminator. -1 The function was not successful, and the error number is set to indicate the cause. See the Errors section.

Errors

Usage

Return Values gl_wchar_t * A pointer to the first occurrence of wc in wcs. NULL Either wc was not found in wcs (the ifx_gl_lc_errno() error number is set to zero); or the function was not successful, and the error number is set to indicate the cause. See the Errors section.

Errors

Usage

Errors

Usage

Return Values >=0 The number of bytes in the copied string, not including any null terminator. -1 The function was not successful, and the error number is set to indicate the cause. See the Errors section.

Errors

Usage

Return Values >=0 The number of characters in the initial substring of wcs1 that consist entirely of wide characters not in the string wcs2. -1 The function was not successful, and the error number is set to indicate the cause. See the Errors section.

Errors

Usage

Return Values >=0 The number of characters in the wcs string, not including any null terminator but including any trailing white space. -1 The function was not successful, and the error number is set to indicate the cause. See the Errors section.

Errors

Usage

Return Values >=0 The number of bytes in the concatenated string, not including any null terminator. -1 The function was not successful, and the error number is set to indicate the cause. See the Errors section.

Errors

Usage

Return Values >=0 The number of characters in the copied string, not including any null terminator. -1 The function was not successful, and the error number is set to indicate the cause. See the Errors section.

Errors

Usage

Return Values >=0 The number of characters in the wcs string, not including any trailing space. -1 The function was not successful, and the error number is set to indicate the cause. See the Errors section.

Errors

INFORMIX-GLS Programmer's Guide
Chapter 4: INFORMIX-GLS Function Descriptions

Home Contents Index Master Index New Book

Return Values

>=0
The number of bytes in the concatenated string, not including any null terminator.

-1
The function was not successful, and the error number is set to indicate the cause. See the Errors section.

Return Values

>=0
The number of bytes in the copied string, not including any null terminator.

-1
The function was not successful, and the error number is set to indicate the cause. See the Errors section.

Return Values

gl_mchar_t *
A pointer to the byte that immediately follows mb.

NULL
The function was not successful, and the error number is set to indicate the cause. See the Errors section.

Return Values

>=0
The number of bytes in the mbs string, not including any trailing space.

-1
The function was not successful, and the error number is set to indicate the cause. See the Errors section.

Return Values

>=0
The number of characters in the mbs string, not including any trailing space.

-1
The function was not successful, and the error number is set to indicate the cause. See the Errors section.

Return Values

gl_mchar_t *
A pointer to the first byte of the multibyte character immediately before mb.

NULL
The function was not successful, and the error number is set to indicate the cause. See the Errors section.

Return Values

gl_mchar_t *
A pointer to the last occurrence of mb in mbs.

NULL
Either mb was not found in mbs (the ifx_gl_lc_errno() error number is set to zero); or the function was not successful, and the error number is set to indicate the cause. See the Errors section.

Return Values

>=0
The number of characters in mbs1 before the first character that mbs1 and mbs2 differ.

-1
The function was not successful, and the error number is set to indicate the cause. See the Errors section.

Return Values

>=0
The number of characters read from mbs and written to wcs, not counting any null terminator.

-1
The function was not successful, and the error number is set to indicate the cause. See the Errors section.

Return Values

>=0
The number of bytes read from mb.

-1
The function was not successful, and the error number is set to indicate the cause. See the Errors section.

Return Values

0
The function was successful.

-1
The function was not successful, and the error number is set to indicate the cause. See the Errors section.

Return Values

>0
An unsigned short integer that encodes the number of bytes read from src_mb and the number of bytes written to dst_mb.

0
The function was not successful, and the error number is set to indicate the cause. See the Errors section.

Return Values

>0
An unsigned short integer that encodes the number of bytes read from src_mb and the number of bytes written to dst_mb.

0
The function was not successful, and the error number is set to indicate the cause. See the Errors section.

Return Values

>0
An unsigned short integer that represents the lowercase equivalent of src_wc.

0
The function was not successful, and the error number is set to indicate the cause. See the Errors section.

Return Values

>0
An unsigned short integer that represents the uppercase equivalent of src_wc.

0
The function was not successful, and the error number is set to indicate the cause. See the Errors section.

Return Values

>=0
The number of characters in the concatenated string, not including any null terminator.

-1
The function was not successful, and the error number is set to indicate the cause. See the Errors section.

Return Values

gl_wchar_t *
A pointer to the first occurrence of wc in wcs.

NULL
Either wc was not found in wcs (the ifx_gl_lc_errno() error number is set to zero); or the function was not successful, and the error number is set to indicate the cause. See the Errors section.

Return Values

>=0
The number of bytes in the copied string, not including any null terminator.

-1
The function was not successful, and the error number is set to indicate the cause. See the Errors section.

Return Values

>=0
The number of characters in the initial substring of wcs1 that consist entirely of wide characters not in the string wcs2.

-1
The function was not successful, and the error number is set to indicate the cause. See the Errors section.

Return Values

>=0
The number of characters in the wcs string, not including any null terminator but including any trailing white space.

-1
The function was not successful, and the error number is set to indicate the cause. See the Errors section.

Return Values

>=0
The number of bytes in the concatenated string, not including any null terminator.

-1
The function was not successful, and the error number is set to indicate the cause. See the Errors section.

Return Values

>=0
The number of characters in the copied string, not including any null terminator.

-1
The function was not successful, and the error number is set to indicate the cause. See the Errors section.

Return Values

>=0
The number of characters in the wcs string, not including any trailing space.

-1
The function was not successful, and the error number is set to indicate the cause. See the Errors section.