Informix-ESQL/C Programmer's Manual

Informix-ESQL/C Programmer's Manual
Chapter 10: Working with INFORMIX-Universal Server Opaque

Home Contents Index Master Index New Book

The lvarchar pointer and var binary Library Functions

The following library functions are available in ESQL/C to access the data buffer of an lvarchar pointer or var binary host variable


Function Name	Purpose
ifx_var_alloc()	Allocates memory for the data buffer.
ifx_var_dealloc()	Deallocates memory for the data buffer.
ifx_var_flag()	Determines whether `ESQL/C` or the application handles memory allocation for the data buffer.
ifx_var_getdata()	Returns the contents of the data buffer.
ifx_var_getlen()	Returns the length of the data buffer.
ifx_var_isnull()	Checks whether the data in the data buffer is null.
ifx_var_setdata()	Sets the data for the data buffer.
ifx_var_setlen()	Sets the length of the data buffer.
ifx_var_setnull()	Sets the data in the data buffer to a null value.

These lvarchar pointer and var binary functions are defined in the sqlhdr.h header file so you do not need to include a special header file in your ESQL/C programs that use them. The following pages describe each of these functions.

ifx_var_alloc()

The ifx_var_alloc() function allocates memory for the data buffer of an lvarchar or var binary host variable.

Syntax

var binary

int ifx_var_alloc(var_bin, var_size)

		var binary **var_bin

		long var_size;

lvarchar

int ifx_var_alloc(lvar, var_size)

		lvarchar **lvar

		long var_size; 


var_bin
is the address of the var binary pointer host variable whose data buffer is allocated. 

lvar
is the address of the lvarchar pointer host variable whose data buffer is allocated.

var_size  
is the size, in bytes, of the data buffer to allocate.

Usage

The allocation flag of the ifx_var_flag() function notifies ESQL/C of the allocation method to use for the data buffer. If you set the allocation flag in ifx_var_flag() to 0, you must explicitly allocate memory for the data of a var binary host variable with the ifx_var_alloc() function.

Important: Whether you allocate memory or allow ESQL/C to allocate the memory for you, you must free the allocated memory using the ifx_var_dealloc() function.

Return Codes

0
The function was successful.

<0
The function was not successful and the return value indicates the cause of the error.

Related Functions

ifx_var_dealloc(), ifx_var_flag()

ifx_var_dealloc()

The ifx_var_dealloc() function deallocates the memory that has been allocated for the data buffer of a var binary host variable.

Syntax

var binary

int ifx_var_dealloc(var_bin)

		var binary **var_bin;

lvarchar

int ifx_var_dealloc(lar)

		lvarchar **lvar; 


var_bin  
is the address of the var binary pointer host variable whose data buffer is deallocated. 

lvar
is the address of the lvarchar pointer host variable whose data buffer is allocated.

Usage

The allocation flag of the ifx_var_flag() function tells ESQL/C which allocation method to use for the data buffer. Regardless of whether ESQL/C (allocation flag set to 1) or your application (allocation flag set to 0) allocates the memory, you must explicitly deallocate memory that has been allocated to an lvarchar or var binary host variable.

Return Codes

0
The function was successful.

<0
The function was not successful and the return value indicates the cause of the error.

Related Functions

ifx_var_alloc(), ifx_var_flag()

ifx_var_flag()

The ifx_var_flag() function determines how memory is allocated for the data buffer of an lvarchar or var binary host variable.

Syntax

var binary

int ifx_var_flag(var_bin, flag)

		var binary **var_bin;

		int flag;

lvarchar

int ifx_var_flag(lvar, flag)

		lvarchar **lvar;

		int flag; 


flag
is the integer value of the allocation flag, either 0 or 1.

var_bin  
is the address of the var binary host variable. 

lvar
is the address of the lvarchar pointer host variable.

Usage

The value of the flag argument is the allocation flag. It determines who handles memory allocation for the data of the var_bin host variable, as follows:

When flag is one (1), ESQL/C automatically performs this memory allocation.

flag

1

SELECT

When flag is zero (0), ESQL/C does not automatically perform this memory allocation.

0

lvar

var_bin

ifx_var_alloc()

If you do not call the ifx_var_flag() function for an lvarchar or var binary host variable, ESQL/C allocates memory for its data buffer. Whether you allocate memory for the lvarchar or var binary variable, or allow ESQL/C to do it for you, you must free the memory with the ifx_var_dealloc() function.

Return Codes

0
The function was successful.

<0
The function was not successful and the return value indicates the cause of the error.

Related Functions

ifx_var_alloc(), ifx_var_dealloc()

ifx_var_getdata()

The ifx_var_getdata() function returns the data from an lvarchar or var binary host variable.

Syntax

var binary

void *ifx_var_getdata(var_bin)

		var binary **var_bin;

lvarchar

void *ifx_var_getdata(lvar)

		lvarchar **lvar; 


var_bin  
is the address of the var binary host variable whose data is retrieved. 

lvar
is the address of the lvarchar pointer host variable whose data is retrieved.

Usage

The ifx_var_getdata() function returns the data as a void * pointer. Your ESQL/C application must cast this pointer to the correct data type. When you use ifx_var_getdata() on an lvarchar pointer, you must cast the returned (void) pointer to a C-language character pointer (char *).

Return Codes

Null pointer
The function was not successful.

Valid pointer to
the data buffer
The function was successful.

Related Functions

ifx_var_getlen(), ifx_var_setdata()

ifx_var_getlen()

The ifx_var_getlen() function returns the length of the data in an lvarchar pointer or var binary host variable.

Syntax

var binary

int ifx_var_getlen(var_bin)

		var binary **var_bin;

lvarchar

int ifx_var_getlen(lvar)

		lvarchar **lvar; 


var_bin  
is the address of the var binary host variable whose length is returned. 

lvar
is the address of the lvarchar pointer host variable whose length is returned.

Usage

The length that the ifx_var_getlen() function returns is the number of bytes that have been allocated for the data buffer of the lvar or var_bin host variable.

Return Codes

>=0
The length of the data buffer for the var_bin host variable.

<0
The function was not successful.

Related Functions

ifx_var_getdata(), ifx_var_setlen()

ifx_var_isnull()

The ifx_var_isnull() function checks whether an lvarchar or var binary host variable contains a null value.

Syntax

var binary

int ifx_var_isnull(var_bin)

		var binary **var_bin;

lvarchar

nt ifx_var_isnull(lvar)

		lvarchar **lvar; 


var_bin  
is the address of the var binary host variable. 

lvar
is the address of the lvarchar pointer host variable.

Usage

The ifx_var_isnull() function checks for a null value in an lvarchar or var binary host variable. To determine whether an ESQL/C host variable of any other data type contains null, use the risnull() library function. For more information, see page 2-24.

Return Codes

0
The opaque-type data is not a null value.

1
The opaque-type data is a null value.

Related Functions

ifx_var_setnull()

ifx_var_setdata()

The ifx_var_setdata() function stores data in an lvarchar or var binary host variable.

Syntax

var binary

int ifx_var_setdata(var_bin, buffer, buf_len)

		var binary **var_bin;

		char *buffer;

		int buf_len;

lvarchar

int ifx_var_setdata(lvar, buffer, buf_len)

		lvarchar **lvar;

		char *buffer;

		int buf_len; 


buffer
is a character buffer that contains the data to store in the lvar or var_bin host variable.

buf_len
is the length, in bytes, of the buffer.

var_bin  
is the address of the var binary host variable. 

lvar
is the address of the lvarchar pointer host variable.

Usage

The ifx_var_setdata() function stores the data in buffer in the data buffer of the lvar or var_bin host variable. For an lvarchar pointer host variable, ESQL/C expects the data inside buffer to be null-terminated ASCII data.

Return Codes

0
The function was successful.

<0
The function was not successful and the return value indicates the cause of the error.

Related Functions

ifx_var_getdata(), ifx_var_setlen()

ifx_var_setlen()

The ifx_var_setlen() function stores the length of the data buffer for an lvarchar or var binary host variable.

Syntax

var binary

int ifx_var_setlen(var_bin, length)

		var binary **var_bin;

		int length

lvarchar

int ifx_var_setlen(lvar, length)

		lvarchar **lvar;

		int length 


length
is the length, in bytes, of the data buffer to allocate for the var binary data.

var_bin  
is the address of the var binary host variable. 

lvar
is the address of the lvarchar pointer host variable.

Usage

The length that the ifx_var_setlen() function sets is the number of bytes to allocate for the data buffer of the lvar or var_bin host variable. Call this function to change the size of the data buffer that the ifx_var_alloc() function allocated for the lvar or var_bin host variable.

Return Codes

0
The function was successful.

<0
The function was not successful and the return value indicates the cause of the error.

Related Functions

ifx_var_getlen(), ifx_var_setdata()

ifx_var_setnull()

The ifx_var_setnull() function sets an lvarchar or var binary host variable to a null value.

Syntax

var binary

int ifx_var_setnull(var_bin,  flag)

		var binary **var_bin;

		int  flag

lvarchar

nt ifx_var_setnull(var_bin,  flag)

		var binary **var_bin;

		int  flag; 


var_bin  
is the address of the var binary host variable. 

lvar
is the address of the lvarchar pointer host variable.

flag 
is the value 0 to indicate a non-null value or 1 to indicate a null value. 







Reviewers: which value of flag sets a var binary variable 
to NULL, 0 or 1?

Usage

The ifx_var_setnull() function sets a host variable of type lvarchar or var binary to a null value. To set an ESQL/C host variable of any other data type to null, use the rsetnull() library function. For more information, see page 2-27.

Return Codes

0
The function was successful.

<0
The function was not successful and the return value indicates the cause of the error.

Related Functions

ifx_var_isnull()

Informix-ESQL/C Programmer's ManualChapter 10: Working with INFORMIX-Universal Server Opaque Home Contents Index Master Index New Book

The lvarchar pointer and var binary Library Functions

var binary

lvarchar

Usage

Return Codes 0 The function was successful. <0 The function was not successful and the return value indicates the cause of the error.

Related Functions

var binary

lvarchar

Usage

Return Codes 0 The function was successful. <0 The function was not successful and the return value indicates the cause of the error.

Related Functions

var binary

lvarchar

Usage

Return Codes 0 The function was successful. <0 The function was not successful and the return value indicates the cause of the error.

Related Functions

var binary

lvarchar

Usage

Return Codes Null pointer The function was not successful. Valid pointer to the data buffer The function was successful.

Related Functions

var binary

lvarchar

Usage

Return Codes >=0 The length of the data buffer for the var_bin host variable. <0 The function was not successful.

Related Functions

var binary

lvarchar

Usage

Return Codes 0 The opaque-type data is not a null value. 1 The opaque-type data is a null value.

Related Functions

var binary

lvarchar

Usage

Return Codes 0 The function was successful. <0 The function was not successful and the return value indicates the cause of the error.

Related Functions

var binary

lvarchar

Usage

Return Codes 0 The function was successful. <0 The function was not successful and the return value indicates the cause of the error.

Related Functions

var binary

lvarchar

Usage

Return Codes 0 The function was successful. <0 The function was not successful and the return value indicates the cause of the error.

Related Functions

Informix-ESQL/C Programmer's Manual
Chapter 10: Working with INFORMIX-Universal Server Opaque

Home Contents Index Master Index New Book

Return Codes

0
The function was successful.

<0
The function was not successful and the return value indicates the cause of the error.

Return Codes

0
The function was successful.

<0
The function was not successful and the return value indicates the cause of the error.

Return Codes

0
The function was successful.

<0
The function was not successful and the return value indicates the cause of the error.

Return Codes

Null pointer
The function was not successful.

Valid pointer to
the data buffer
The function was successful.

Return Codes

>=0
The length of the data buffer for the var_bin host variable.

<0
The function was not successful.

Return Codes

0
The opaque-type data is not a null value.

1
The opaque-type data is a null value.

Return Codes

0
The function was successful.

<0
The function was not successful and the return value indicates the cause of the error.

Return Codes

0
The function was successful.

<0
The function was not successful and the return value indicates the cause of the error.

Return Codes

0
The function was successful.

<0
The function was not successful and the return value indicates the cause of the error.