Informix DataBlade API Programmer's Manual Using Smart Large Objects

To obtain the status information for an existing smart large object, take the following steps.

Figure 6-21 shows the first three of these steps that a DataBlade API module uses to obtain status information for the smart large object data in the emp_picture column of the employee table (Figure 6-3 on page 6-16).

Figure 6-21 Obtaining Status Information

You can obtain status information for any smart large object for which you have a valid LO file descriptor. To obtain an LO file descriptor, you can perform any of the following steps:

• Select an existing smart large object from a column in a database and open it.

For more information, see Accessing an Existing Smart Large Object.

• Create a new smart large object.

For more information, see Creating a Smart Large Object.

• Receive the LO handle as an argument

A DataBlade API module can receive an argument that might provide the LO handle directly or it might provide an opaque data type in which the smart large object is embedded.

The mi_lo_stat() function is the constructor for the LO-status structure. It performs the following tasks:

1. It obtains either a new or existing LO-status structure.
2. It initializes the LO-status structure with all status information for the smart large object that the specified LO file descriptor identifies.

Important: Do not handle memory allocation for an LO-status structure with system memory-allocation routines (such as malloc() or mi_alloc()) or by direct declaration. You must use the LO-status constructor, mi_lo_stat(), to allocate a new LO-status structure.

The third argument to the mi_lo_stat() function indicates whether to allocate a new LO-status structure:

• When you pass a NULL-valued pointer, the mi_lo_stat() function allocates a new LO-status structure.

This LO-status structure has the current memory duration.

• When you pass a pointer that does not point to NULL, the mi_lo_stat() function assumes that the pointer references an existing LO-status structure that a previous call to mi_lo_stat() has allocated.

An LO-status pointer that does not point to NULL allows a DataBlade API module to reuse an LO-status structure.

For example, in the following code fragment, the mi_lo_stat() function allocates memory for the LO-status structure only when the first_time flag is true:

MI_CONNECTION *conn;

MI_LO_HANDLE *LO_hdl;

MI_LO_STAT *LO_stat;

MI_LO_FD LO_fd;

mi_integer first_time;


LO_fd = mi_lo_open(conn, LO_hdl, MI_LO_RDONLY);
if ( first_time )

	{

	...

	LO_stat = NULL; /* tell interface to allocate memory */

	first_time = 0; /* set "first_time" flag to false */
	

	}
err = mi_lo_stat(conn, LO_fd, &LO_stat);

After the execution of mi_lo_stat() in the preceding code fragment, the LO_stat variable points to an allocated LO-status structure that contains status information for the smart large object that the LO file descriptor, LO_fd, identifies.

Important: Before you use an LO-status structure, make sure that you either call mi_lo_stat() with the LO-status pointer set to NULL or that you initialized this pointer with a previous call to mi_lo_stat().

For more information, see Figure 6-22 on page 6-82. For the syntax of the mi_lo_stat() function, see its description in Chapter 15, DataBlade API Function Descriptions.

Once you have a valid LO-status structure, you can use the accessor functions to obtain the status information from this structure. Figure 6-22 shows the status information that an LO-status structure contains and the corresponding LO-status accessor functions.

Important: The LO-status structure, MI_LO_STAT, is an opaque structure to DataBlade API modules. Do not access its internal structure directly. Informix does not guarantee that the internal structure of MI_LO_STAT will not change in future releases. Therefore, to create portable code, always use the LO-status accessor functions for this structure.

The following code fragment obtains the reference count from an LO-status structure that the LO_stat variable references:

MI_CONNECTION *conn;

MI_LO_HANDLE *LO_hdl;

MI_LO_FD LO_fd;

MI_LO_STAT *LO_stat = NULL; /* DataBlade API allocates */

mi_integer ref_count, err;



/* Open the selected large object */
LO_fd = mi_lo_open(conn, LO_hdl, MI_LO_RDONLY);
if ( LO_fd == MI_ERROR )

	/* handle error */

/* Allocate LO-specification structure and get status

**  information for the opened smart large object   */
if ( mi_lo_stat(conn, LO_fd, &LO_stat) != MI_OK )

	/* handle error */
else
	{
	/* get reference count for this smart large object */
	ref_count = mi_lo_stat_refcnt(LO_stat);

	/* free the LO-status structure */

	err = mi_lo_stat_free(LO_stat);
	}

The mi_lo_open() function opens the smart large object that the LO handle, LO_hdl, identifies. The mi_lo_stat() function then obtains the status information for this open smart large object. The mi_lo_stat() function performs the following tasks:

1. Allocates a new LO-status structure because the value of *LO_stat is NULL.

The mi_lo_stat() function assigns a pointer to this new LO-status structure to the LO_stat variable.

2. Initializes the LO_stat structure with the status information for the open smart large object that the LO file descriptor, LO_fd, identifies.

Once the LO-status structure contains the status information, the mi_lo_stat_refcnt() accessor function obtains the reference count from the LO-status structure and returns it into the ref_count variable. When the code no longer needs the LO-status structure, it frees this structure with the mi_lo_stat_free() function.

The mi_lo_stat() function allocates an LO-status structure in the current memory duration. Therefore, if an LO-status structure has a memory duration of PER_ROUTINE, the database server automatically frees it when the user-defined routine completes.

To explicitly free the resources assigned to an LO-status structure, use the mi_lo_stat_free() function. The mi_lo_stat_free() function is the destructor function for an LO-status structure. When the resources are freed, they can be reallocated to other structures that your program needs.