The mi_lo_stat() function

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

Syntax

mi_integer mi_lo_stat(conn, LO_fd, LOstat_dptr)
   MI_CONNECTION *conn;
   MI_LO_FD LO_fd;
   MI_LO_STAT **LOstat_dptr;
conn
This value is one of the following connection values:

A pointer to a connection descriptor established by a previous call to mi_open(), mi_server_connect(), or mi_server_reconnect().

A NULL-valued pointer (database server only)

LO_fd
An LO file descriptor for the open smart large object whose status information you want to obtain.
LOstat_dptr
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

Usage

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 about the status information and the corresponding accessor functions, see the Informix® DataBlade® API Programmer's Guide.

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

Server only: 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.

Server only: The mi_lo_stat() function does not need a connection descriptor to execute. If your UDR does not need a valid connection for other operations, you can specify a NULL-valued pointer for the conn parameter to establish a NULL connection. For information about the advantages of a NULL connection, see the Informix® DataBlade® API Programmer's Guide.

Return values

MI_OK
The function was successful.
MI_ERROR
The function was not successful.