Initializing an LO-Status Structure

Home | Previous Page | Next Page Data Manipulation > Using Smart Large Objects > Obtaining Status Information for a Smart Large Object >

Initializing an LO-Status Structure

The mi_lo_stat( ) function performs the following tasks:

It obtains either a new or existing LO-status structure.
It fills 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.

Obtaining a Valid LO-Status Structure

The mi_lo_stat( ) function is the constructor for the LO-status structure. The third argument to the mi_lo_stat( ) function indicates whether to create a new LO-status structure:

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

This LO-status structure has the current memory duration.

End of Server Only
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, the code fragment in Figure 31 uses the mi_lo_stat( ) function to allocate memory for the LO-status structure only when the first_time flag is true.

Figure 31. Sample mi_lo_stat( ) Call

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

Filling the LO-Status Structure

Once mi_lo_stat( ) has a pointer to a valid LO-status structure, it fills this structure with the status information for the open smart large object. You pass an LO file descriptor of the open smart large object as an argument to the mi_lo_stat( ) function.

After the execution of mi_lo_stat( ) in Figure 31, 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 initialize this pointer with a previous call to mi_lo_stat( ).

For more information, see Table 42. For the syntax of the mi_lo_stat( ) function, see the IBM Informix: DataBlade API Function Reference.