DataBlade API Programmer's Manual

DataBlade API Programmer's Manual
Chapter 3: Handling Smart Large Objects

Home Contents Index Master Index New Book

Obtaining the Status of a Smart Large Object

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


Step	Task	Smart-Large-Object Function	For More Information
1.	Obtain a valid `LO` file descriptor for the smart large object whose status information you need.	mi_lo_create(), mi_lo_copy(), mi_lo_expand(), mi_lo_from_file() mi_lo_open()	page 3-75
2.	Allocate and fill an `LO`-status structure.	mi_lo_stat()	page 3-76
3.	Use the appropriate `LO`-status accessor function to obtain the status information that you need.	Figure 3-21	page 3-77
4.	Deallocate resources.	mi_lo_stat_free()	page 3-80

Figure 3-20 shows the first three of these steps that a DataBlade routine uses to obtain status information for the smart large object data in the emp_picture column of the employee table (Figure 3-3).

Figure 3-20
Obtaining Status Information

#include "milo.h"

...

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 have initialized this pointer with a previous call to mi_lo_stat().

For more information, see Figure 3-21. For the syntax of the mi_lo_stat() function, see its description in Chapter 12, "DataBlade API Function Descriptions."

Accessing Status Information

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

Figure 3-21
Status Information in the LO-Status Structure

Status Information LO-Status Accessor Function
Last-access time
This value is available only if the last-access time attribute (MI_LO_ATTR_KEEP_LASTACCESS_TIME) is set for this smart large object.
mi_lo_stat_atime()

Storage characteristics
These characteristics are stored in an LO-
specification structure. Use the LO-specification accessor functions (see "Defining User-Specified Storage Characteristics") to obtain information from this structure.
mi_lo_stat_cspec()

Last-change time
mi_lo_stat_ctime()

Last-modification time
mi_lo_stat_mtime_sec()

Reference count
mi_lo_stat_refcnt()

Size
mi_lo_stat_size()

Important: The LO-status structure, MI_LO_STAT, is an opaque structure to DataBlade routines. 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:

#include "milo.h";
...

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);

	/* deallocate 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 deallocates this structure with the mi_lo_stat_free() function.

Deallocating an LO-Status Structure

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

To explicitly deallocate the resources assigned to an LO-status structure, use the mi_lo_stat_free() function. When the resources are freed, they can be reallocated to other structures that your program needs. For more information on the syntax of the mi_lo_stat_free() function, see its description in Chapter 12, "DataBlade API Function Descriptions."

DataBlade API Programmer's ManualChapter 3: Handling Smart Large Objects Home Contents Index Master Index New Book

Obtaining the Status of a Smart Large Object

Obtaining a Valid LO File Descriptor

Obtaining an LO-Status Structure

Allocating Memory for an LO-Status Structure

Accessing Status Information

Deallocating an LO-Status Structure

DataBlade API Programmer's Manual
Chapter 3: Handling Smart Large Objects

Home Contents Index Master Index New Book