Informix DataBlade API Programmer's Manual DataBlade API Function Descriptions

The mi_lo_stat() function puts information about the current status of an open smart large object into an LO-status structure.

mi_integer mi_lo_stat(conn, LO_fd, LOstat_dptr)

MI_CONNECTION *conn;

MI_LO_FD LO_fd;

MI_LO_STAT **LOstat_dptr;

conn	is a pointer to the connection descriptor that a previous call to mi_open(), mi_server_connect(), or mi_server_reconnect() has established.
LO_fd	is an LO file descriptor for the open smart large object whose status information you want to obtain.
LOstat_dptr	is a doubly indirected pointer to the LO-status structure for the smart large object.

Valid in Client LIBMI Application?	Valid in User-Defined Routine?
Yes	Yes

The mi_lo_stat() function performs the following steps to obtain an LO-status structure:

1. It handles memory allocation if it creates a new LO-status structure.

When the *LOstat_dptr value (a single indirect pointer to an LO-status structure) is NULL, the mi_lo_stat() function allocates an LO-status structure. Before you use an LO-status structure, set *LOstat_dptr to NULL so that mi_lo_stat() allocates space for the LO-status structure. When *LOstat_dptr does not point to NULL, the mi_lo_stat() function assumes that the LO-status structure has already been allocated by a previous call to mi_lo_stat().

2. It initializes the fields in the LO-status structure with the status information for the smart large object that the LO_fd file descriptor identifies.

To access the status information, use the LO-status accessor functions. For more information on the status information and the corresponding accessor functions, see Accessing Status Information.

The mi_lo_stat() function is the constructor for the LO-status structure.

The mi_lo_stat() function allocates a new LO-status structure in the current memory duration.

Important: You must call the mi_lo_stat() function before you use an LO-status structure in a DataBlade API module.

Do not use system memory-allocation calls (such as malloc() or mi_alloc()) to perform memory management for LO-status structures. Use the mi_lo_stat() function to create a new LO-specification structure and the mi_lo_stat_free() function to free an LO-specification structure.

Tip: The mi_lo_stat() function replaces the mi_large_object_stat() function, which Informix supports for backward compatibility only. Use mi_lo_stat() for all new DataBlade API modules.

Return Values

MI_OK	indicates that the function was successful.
MI_ERROR	indicates that the function was not successful.

See the descriptions of the following functions: mi_lo_stat_atime(), mi_lo_stat_cspec(), mi_lo_stat_ctime(), mi_lo_stat_free(), mi_lo_stat_mtime_sec(), mi_lo_stat_mtime_usec(), mi_lo_stat_refcnt(), and mi_lo_stat_size().

For more information, see Status Information, The LO-Status Structure, and Obtaining the Status of a Smart Large Object.