INFORMIX
Informix-ESQL/C Programmer's Manual
Chapter 7: Working with INFORMIX-Universal Server Smart Large
Home Contents Index Master Index New Book

The ESQL/C API for Smart Large Objects

 The ESQL/C API for smart large objects allows an application program to access a smart large object much like an operating-system file. A smart large object that does not fit into memory does not have to be read into a file and then accessed from a file; it can be accessed one piece at a time. An ESQL/C application program accesses smart large objects through the ESQL/C library functions in the following table.

(1 of 3)

ESQL/C Function Description

ifx_lo_alter()

Alters the storage characteristics of an existing smart large object

ifx_lo_close()

Closes an open smart large object

ifx_lo_col_info()

Retrieves column-level storage characteristics in an LO-specification structure

ifx_lo_copy_to_file()

Copies a smart large object into an operating-system file

ifx_lo_copy_to_lo()

Copies an operating-system file into an open smart large object

ifx_lo_create()

Creates an LO-pointer structure for a smart large object

ifx_lo_def_create_spec()

Allocates an LO-specification structure and initializes its fields to null values

ifx_lo_filename()

Returns the generated filename, given an LO-pointer structure and a file specification

ifx_lo_from_buffer()

Copies a specified number of bytes from a user-defined buffer into a smart large object

ifx_lo_open()

Opens an existing smart large object

ifx_lo_read()

Reads a specified number of bytes from an open smart large object

ifx_lo_readwithseek()

Seeks to a specified position in an open smart large object and reads a specified number of bytes

ifx_lo_release()

Releases resources committed to a temporary smart large object

ifx_lo_seek()

Sets the seek position for the next read or write on an open smart large object

ifx_lo_spec_free()

Frees the resources allocated to an LO-specification structure

ifx_lo_specget_estbytes()

Gets the estimated size, in bytes, of the smart large object

ifx_lo_specget_extsz()

Gets the allocation extent size for the smart large object

ifx_lo_specget_flags()

Gets the create-time flags for the smart large object

ifx_lo_specget_maxbytes()

Gets the maximum size for the smart large object

ifx_lo_specset_sbspace()

Gets the sbspace name for the smart large object

ifx_lo_specset_estbytes()

Sets the estimated size, in bytes, of the smart large object

ifx_lo_specset_extsz()

Sets the allocation extent size for the smart large object

ifx_lo_specset_flags()

Sets the create-time flags for the smart large object

ifx_lo_specset_maxbytes()

Sets the maximum size for the smart large object

ifx_lo_specset_sbspace()

Sets the sbspace name for the smart large object

ifx_lo_stat()

Obtains status information for an open smart large object

ifx_lo_stat_atime()

Returns the last access time for a smart large object

ifx_lo_stat_cspec()

Returns the storage characteristics for a smart large object

ifx_lo_stat_ctime()

Returns the last change-in-status time for the smart large object

ifx_lo_stat_free()

Frees the resources allocated to an LO-status structure

ifx_lo_stat_mtime_sec()

Returns the last modification time, in seconds, for the smart large object

ifx_lo_stat_refcnt()

Returns the reference count for the smart large object

ifx_lo_stat_size()

Returns the size of the smart large object

ifx_lo_tell()

Returns the current seek position of an open smart large object

ifx_lo_to_buffer()

Copies a specified number of bytes from a smart large object into a user-defined buffer

ifx_lo_truncate()

Truncates a smart large object to a specific offset

ifx_lo_write()

Writes a specified number of bytes to an open smart large object

ifx_lo_writewithseek()

Seeks to a specified position in an open smart large object and writes a specified number of bytes

The following pages describe each of these functions in more detail.

ifx_lo_alter()

The ifx_lo_alter() function alters the storage characteristics of an existing smart large object.

Syntax

Usage

 The ifx_lo_alter() function updates the storage characteristics of an existing smart large object with the characteristics in the LO-specification structure to which LO_spec points. With ifx_lo_alter(), you can change only the following storage characteristics:

    You can set the LO_LOG or LO_NOLOG flag with the ifx_lo_specset_flags() function.

    You can set the LO_KEEP_LASTACCESS_TIME or LO_NOKEEP_LASTACCESS_TIME flag with the ifx_lo_specset_flags() function.

    You can store a new integer value for the allocation extent size with the ifx_lo_specset_extsz() function. The new extent size applies only to extents written after the ifx_lo_alter() function completes.

The function obtains an exclusive lock for the entire smart large object before it proceeds with the update. It holds this lock until the update completes.

Return Values

0

The function was successful.

<0

The function was not successful and the return value indicates the cause of the failure.

Related Functions

 ifx_lo_col_info(), ifx_lo_create(), ifx_lo_def_create_spec(), ifx_lo_specset_extsz(), ifx_lo_specset_flags()

ifx_lo_close()

The ifx_lo_close() function closes an open smart large object.

Syntax

Usage

 The ifx_lo_close() function closes the smart large object that is associated with the LO file descriptor, LO_fd. The ifx_lo_open() or ifx_lo_create() function returns an LO file descriptor for a smart large object when it successfully opens it.

When the ifx_lo_close() function closes a smart large object, the database server attempts to unlock the smart large object. In some cases, the database server does not permit the release of the lock until the end of the transaction. (If you do not perform updates to smart large objects inside a BEGIN WORK transaction block, every update is a separate transaction.) This behavior might occur if the isolation mode is repeatable read or if the lock held is an exclusive lock.

Return Values

0

The function was successful.

<0

The function was not successful and the return value indicates the cause of the failure.

Related Functions

 ifx_lo_create(), ifx_lo_open()

ifx_lo_col_info()

The ifx_lo_col_info() function sets the fields of an LO-specification structure to the column-level storage characteristics for a specified database column.

Syntax

Usage

 The ifx_lo_col_info() function sets the fields of the LO-specification structure to which LO_spec points, to the storage characteristics for the column_name database column. If this specified column does not have column-level storage characteristics defined for it, the database server uses the storage characteristics that are inherited. For more information on the inheritance hierarchy, see "Obtaining Storage Characteristics".

The column_name buffer must specify the column name in the following format:

ANSI
If the column is in a database that is ANSI compliant, you can also include the owner_name, as follows:

Important: You must call the ifx_lo_def_create_spec() function before you call ifx_lo_col_info().

Return Codes

0

The function was successful.

<0

The function was not successful and the return value indicates the cause of the failure.

Related Functions

 ifx_lo_create(), ifx_lo_def_create_spec()

ifx_lo_copy_to_file()

The ifx_lo_copy_to_file() function copies the contains of a smart large object into an operating-system file.

Syntax

Usage

 The ifx_lo_copy_to_file() function can create the target files on either the server or the client computer. The flag values for the flags argument indicate the location of the file to copy. Valid values include the following constants, which the locator.h header file defines.
File-Location Constant Purpose

LO_CLIENT_FILE

The fna5me file is on the client computer.

LO_SERVER_FILE

The fname file is on the server computer.

If you do not specify a value for flags, the default location is the client computer (LO_CLIENT_FILE).

By default, the ifx_lo_copy_to_file() function generates a filename of the form:

In this format, fname is the filename you specify as an argument to ifx_lo_copy_to_file() and hex_id is the unique hexadecimal smart-large-object identifier. The maximum number of digits for a smart-large-object identifier is 17; however most smart large objects would have an identifier with significantly fewer digits.

For example, suppose you specify a pathname value as follows:

If the CLOB column has an identifier of 203b2, the ifx_lo_copy_to_file() function creates the file:

To change this default filename, you can specify the following wildcards in the filename portion of fname:

    The ifx_lo_copy_to_file() function replaces each question mark with a hexadecimal digit from the identifier of the BLOB or CLOB column. For example, suppose you specify a pathname value as follows:

'/tmp/resume??.txt'

/tmp/resumeb2.txt

    For example, suppose you specify a pathname value as follows:

'/tmp/resume.txt!'

/tmp/resume.txt

Tip: These wildcards are also valid in the "fname" argument of the ifx_lo_filename() function. For more information on ifx_lo_filename(), see page 7-50.
Your application must ensure that there is sufficient space to hold the generated file.

Return Values

0

The function was successful.

<0

The function was not successful and the return value indicates the cause of the failure.

Related Functions

 ifx_lo_copy_to_lo(), ifx_lo_filename()

ifx_lo_copy_to_lo()

The ifx_lo_copy_to_lo() function copies the contents of a file into an open smart large object.

Syntax

Usage

 The ifx_lo_copy_to_lo() function can copy the contents of a source file on either the server or the client computer. The flag values for the flags argument indicate the location of the file to copy. Valid values include the following constants, which the locator.h header file defines.

File-Location Constant Purpose

LO_CLIENT_FILE

The fname file is on the client computer.

LO_SERVER_FILE

The fname file is on the server computer.

LO_APPEND

Append the data in fname to the end of the specified smart large object. This flag can be masked with one of the preceding flags.

Return Values

0

The function was successful.

<0

The function was not successful and the return value indicates the cause of the failure.

Related Functions

 ifx_lo_copy_to_file()

ifx_lo_create()

The ifx_lo_create() function creates a new smart large object and opens it for access within an ESQL/C program.

Syntax

Usage

 The ifx_lo_create() function performs the following steps to create a new smart large object:

    1. It creates a new LO-pointer structure and assigns a pointer to this structure to the LO_ptr argument.

    2. It assigns the storage characteristics for the smart large object from the LO-specification structure, LO_spec.

    If the LO-specification structure does not contain storage characteristics (the associated fields are null), ifx_lo_create() uses the storage characteristics from the inheritance hierarchy for the new smart large object. The ifx_lo_create() function also uses the system-specified storage characteristics if the LO_spec pointer is null.

    3. It opens the new smart large object in the access mode that the flags argument specifies.

    4. It returns an LO file descriptor that identifies the open smart large object.

Important: You must call the ifx_lo_def_create_spec() function to initialize an LO-specification structure before you call the ifx_lo_create() function.
Universal Server uses the default parameters that the call to ifx_lo_create() establishes to determine whether subsequent operations result in locking and/or logging of the corresponding smart large object. For more information, see "Lightweight I/O".

Each ifx_lo_create() call is implicitly associated with the current connection. When this connection closes, the database server deallocates any smart large objects that are not referenced by any columns (those with a reference count of zero).

If the ifx_lo_create() function is successful, it returns a pointer to a valid LO file descriptor. You can then use this file descriptor, LO_fd, to identify which smart large object to access in subsequent function calls such as ifx_lo_read() and ifx_lo_write(). However, this LO_fd file descriptor is only valid within the current database connection.

Return Values

A valid LO file
descriptor

The function successfully created and opened the new smart large object and returned a valid LO file descriptor.

-1

The function was not successful; examine the error for a detailed error code.

Related Functions

 ifx_lo_close(), ifx_lo_col_info(), ifx_lo_def_create_spec()

ifx_lo_def_create_spec()

The ifx_lo_def_create_spec() function allocates and initializes an LO-specification structure.

Syntax

Usage

 The ifx_lo_def_create_spec() function initializes the fields in the LO-specification structure, to which LO_spec points, to the appropriate null values. The database server later interprets these null values to mean that system-specified defaults should be used for the storage characteristics of the smart large object. For more information, see "The System-Specified Storage Characteristics".

Important: You must call the ifx_lo_def_create_spec() function before you use an LO-specification structure in your ESQL/C program. You can use the ifx_lo_col_info() function to obtain storage characteristics that are associated with a particular column.

Return Codes

0

The function was successful.

<0

The function was not successful and the return value indicates the cause of the failure.

Related Functions

 ifx_lo_col_info(), ifx_lo_create(), ifx_lo_spec_free()

ifx_lo_filename()

The ifx_lo_filename() function returns the pathname that the database server would use if you copied a smart large object to a file.

Syntax

Usage

 The ifx_lo_filename() function generates a filename from the fname argument that you provide. Use the ifx_lo_filename() function to determine the filename that the ifx_lo_copy_to_file() function would create for its fname argument.

By default, the ifx_lo_copy_to_file() function generates a filename of the form:

However, you can specify wildcards in the fname argument that can change this default filename. You can use these wildcards in the fname argument of ifx_lo_filename() to see what filename these wildcards generate. For more information on the wildcards that are valid in the fname argument, see the description of the ifx_lo_copy_to_file() function on page 7-41.

Return Values

0

The function was successful.

<0

The function was not successful and the return value indicates the cause of the failure.

Related Functions

 ifx_lo_copy_to_file()

ifx_lo_from_buffer()

The ifx_lo_from_buffer() function copies a specified number of bytes from a user-defined buffer into a smart large object.

Syntax

Usage

 The ifx_lo_from_buffer() function copies bytes, up to the size specified by size, from the user-defined buffer into the smart large object that the LO_ptr argument identifies. The write operation to the smart large object starts at a zero-byte offset. To use the ifx_lo_from_buffer() function, the smart large object must already exist in an sbspace before you copy the data.

Return Values

0

The function was successful.

-1

The function was not successful.

ifx_lo_open()

 The ifx_lo_open() function opens an existing smart large object for access.

Syntax

Usage

 Your ESQL/C program must call the ifx_lo_open() function for each instance of a smart large object that it needs to access.

The flag values for the flags argument indicate the mode of the smart large object after ifx_lo_open() successfully completes. Valid values include all access-mode constants, which Figure 7-6 shows. For more information on access modes, see "Opening a Smart Large Object".

Universal Server uses the default parameters that the call to ifx_lo_open() (or ifx_lo_create()) has established to determine whether subsequent operations result in locking and/or logging of the corresponding smart large object. For more information, see "Lightweight I/O".

Each ifx_lo_open() call is implicitly associated with the current connection. When this connection closes, the database server deallocates any smart large objects that are not referenced by any columns (those with a reference count of zero).

If the ifx_lo_open() function is successful, it returns a pointer to a valid LO file descriptor. You can then use this file descriptor, LO_fd, to identify which smart large object to access in subsequent function calls such as ifx_lo_read() and ifx_lo_write(). However, this LO_fd file descriptor is only valid within the current database connection.

Once ifx_lo_open() has opened the smart large object, it sets the seek position in the returned LO file descriptor to byte zero (0). It also obtains a lock on the entire smart large object. The type of lock depends on the access mode in which the smart large object is opened, as follows:

The lock that ifx_lo_open() obtains is lost when the current transaction terminates. The database server obtains the lock again, however, when the next function that needs a lock executes. If this behavior is undesirable, use BEGIN WORK transaction blocks and place a COMMIT WORK or ROLLBACK WORK statement after the last statement that needs to use the lock.

Return Values

-1

The function was not successful; examine the error for a detailed error code.

A valid LO file
descriptor

The function has successfully opened the smart large object and returned a valid LO file descriptor.

Related Functions

 ifx_lo_close(), ifx_lo_create(), ifx_lo_read(), ifx_lo_write

ifx_lo_read()

The ifx_lo_read() function reads a specified number of bytes of data from an open smart large object.

Syntax

Usage

 The ifx_lo_read() function reads nbytes of data from the open smart large object that the LO_fd file descriptor identifies. The read begins at the current seek position for LO_fd. You can use the ifx_lo_tell() function to obtain the current seek position.

The function reads this data into the user-defined buffer to which buf points. The buf buffer must be less than 2 gigabytes in size. To read smart large objects that are larger than 2 gigabytes, read them in 2-gigabyte chunks.

Return Values

>=0

The number of bytes that the function has read from the smart large object into the buf character buffer.

-1

The function was not successful; examine the error for a detailed error code.

Related Functions

 ifx_lo_open(), ifx_lo_readwithseek(), ifx_lo_seek(), ifx_lo_tell(), ifx_lo_write()

ifx_lo_readwithseek()

The ifx_lo_readwithseek() function performs a seek operation and then reads a specified number of bytes of data from an open smart large object.

Syntax

Usage

 The ifx_lo_readwithseek() function reads nbytes of data from the open smart large object that the LO_fd file descriptor identifies.

The read begins at the seek position of LO_fd that the offset and whence arguments indicate, as follows:

The function reads this data into the user-defined buffer to which buf points. The size of the buf buffer must be less than 2 gigabytes. To read smart large objects that are larger than 2 gigabytes, read them in 2-gigabyte chunks.

Return Values

>=0

The number of bytes that the function has read from the smart large object into the buf character buffer.

-1

The function was not successful; examine the error for a detailed error code.

Related Functions

 ifx_lo_open(), ifx_lo_read(), ifx_lo_seek(), ifx_lo_write()

ifx_lo_release()

The ifx_lo_release() function tells the database server to release the resources associated with a temporary smart large object.

Syntax

Usage

 The ifx_lo_release() function is useful for telling the database server when it is safe to release resources associated with temporary smart large objects. A temporary smart large object is one that has one or more LO handles, none of which have been inserted into a table. Temporary smart large objects can occur in the following ways:

For example, the following query creates one smart large object for each row in the table1 table and sends each one to the client application:

The client application can use the ifx_lo_release() function to indicate to the database server when it finishes processing each of these smart large objects. Once you call this function on a temporary smart large object, the database server can release the resources at any time. Further use of the LO handle and any associated LO file descriptors is not guaranteed to work.

Use of this function on smart large objects that are not temporary does not cause any incorrect behavior. However, the call is expensive and is not needed for permanent smart large objects.

Return Values

0

The function was successful.

< 0

The function was not successful.

ifx_lo_seek()

 The ifx_lo_seek() function sets the file position for the next read or write operation on the open smart large object.

Syntax

Usage

 The function uses the whence and offset arguments to determine the seek position, as follows:

The ifx_lo_tell() function returns the current seek position for an open smart large object.

Return Values

0

The function was successful.

<0

The function was not successful and the return value indicates the cause of the failure.

Related Functions

 ifx_lo_read(), ifx_lo_tell(), ifx_lo_write()

ifx_lo_spec_free()

The ifx_lo_spec_free() function frees the resources of an LO-specification structure.

Syntax

Usage

 The ifx_lo_spec_free() function frees the LO-specification structure to which LO_spec points. This structure was allocated by a call to ifx_lo_def_create_spec(). ESQL/C does not perform memory management for LO-specification structures. You must call ifx_lo_spec_free() for each LO-specification structure that you have allocated with a call to the ifx_lo_def_create_spec() function.

Return Values

0

The function was successful.

<0

The function was not successful and the return value indicates the cause of the failure.

Related Functions

 ifx_lo_def_create_spec()

ifx_lo_specget_estbytes()

The ifx_lo_specget_estbytes() function obtains from an LO-specification structure the estimated size of a smart large object.

Syntax

Usage

 The estbytes value is the estimated final size, in bytes, of the smart large object. This estimate is an optimization hint for the smart-large-object optimizer. For more information on the estimated size, see Figure 7-1.

Important: You must call the ifx_lo_def_create_spec() function to initialize an LO-specification structure before you call ifx_lo_specget_estbytes(). You can use the ifx_lo_col_info() function to store storage characteristics that are associated with a particular column in an LO-specification structure.

Return Values

0

The function was successful.

-1

The function was not successful.

Related Functions

 ifx_lo_def_create_spec(), ifx_lo_spec_free(), ifx_lo_specget_extsz(), ifx_lo_specget_flags(), ifx_lo_specget_maxbytes(), ifx_lo_specget_sbspace(), ifx_lo_specset_estbytes()

ifx_lo_specget_extsz()

The ifx_lo_specget_extsz() function obtains from an LO-specification structure the allocation extent size of a smart large object.

Syntax

Usage

 The extsz value specifies the size, in bytes, of the allocation extents to be allocated for the smart large object when the database server writes beyond the end of the current extent. This value overrides the estimate that Universal Server generates for how large an extent should be. For more information on the allocation extent, see Figure 7-1.

Important: You must call the ifx_lo_def_create_spec() function to initialize an LO-specification structure before you call ifx_lo_specget_estbytes(). You can use the ifx_lo_col_info() function to store storage characteristics that are associated with a particular column in an LO-specification structure.

Return Values

>=0

The function was successful and the return value indicates the extent size.

-1

The function was not successful.

Related Functions

 ifx_lo_def_create_spec(), ifx_lo_spec_free(), ifx_lo_specget_estbytes(), ifx_lo_specget_flags(), ifx_lo_specget_maxbytes(), ifx_lo_specget_sbspace(), ifx_lo_specset_extsz()

ifx_lo_specget_flags()

The ifx_lo_specget_flags() function obtains from an LO-specification structure the create-time flags of a smart large object.

Syntax

Usage

 The create-time flags provide the following information about a smart large object:

These two indicators are masked together into the single flags value. For more information on the create-time flags, see Figure 7-2.

Important: You must call the ifx_lo_def_create_spec() function to initialize an LO-specification structure before you call ifx_lo_specget_estbytes(). You can use the ifx_lo_col_info() function to store storage characteristics that are associated with a particular column in an LO-specification structure.

Return Values

>=0

The function was successful and the return value is the value of the create-time flags.

-1

The function was not successful.

Related Functions

 ifx_lo_def_create_spec(), ifx_lo_spec_free(), ifx_lo_specget_estbytes(), ifx_lo_specget_extsz(), ifx_lo_specget_maxbytes(), ifx_lo_specget_sbspace(), ifx_lo_specset_flags()

ifx_lo_specget_maxbytes()

The ifx_lo_specget_maxbytes() function obtains from an LO-specification structure the maximum size of a smart large object.

Syntax

Usage

 Universal Server does not allow the size of a smart large object to exceed the maxbytes value. For more information on the maximum size, see Figure 7-1.

Important: You must call the ifx_lo_def_create_spec() function to initialize an LO-specification structure before you call ifx_lo_specget_estbytes(). You can use the ifx_lo_col_info() function to store storage characteristics that are associated with a particular column in an LO-specification structure.

Return Values

0

The function was successful.

-1

The function was not successful.

Related Functions

 ifx_lo_def_create_spec(), ifx_lo_spec_free(), ifx_lo_specget_estbytes(), ifx_lo_specget_extsz(), ifx_lo_specget_flags(), ifx_lo_specget_sbspace(), ifx_lo_specset_maxbytes()

ifx_lo_specget_sbspace()

The ifx_lo_specget_sbspace() function obtains from an LO-specification structure the name of an sbspace where a smart large object is stored.

Syntax

Usage

 The ifx_lo_specget_sbspace() function returns the current setting for the name of the sbspace in which to store the smart large object. The function copies up to (length-1) bytes into the sbspace_name buffer and ensures that it is null terminated. For more information on an sbspace name, see Figure 7-1.

Important: You must call the ifx_lo_def_create_spec() function to initialize an LO-specification structure before you call ifx_lo_specget_estbytes(). You can use the ifx_lo_col_info() function to store storage characteristics that are associated with a particular column in an LO-specification structure.
An sbspace name can be up to 18 characters long. However, you might want to allocate at least 129 bytes for the sbspace_name buffer to accommodate future increases in the length of an sbspace name.

Return Values

0

The function was successful.

-1

The function was not successful.

Related Functions

 ifx_lo_def_create_spec(), ifx_lo_spec_free(), ifx_lo_specget_estbytes(), ifx_lo_specget_extsz(), ifx_lo_specget_flags(), ifx_lo_specget_maxbytes(), ifx_lo_specset_sbspace()

ifx_lo_specset_estbytes()

The ifx_lo_specset_estbytes() function sets the estimated size of a smart large object.

Syntax

Usage

 The estbytes value is the estimated final size, in bytes, of the smart large object. This estimate is an optimization hint for the smart-large-object optimizer. For more information on the estimated byte size, see Figure 7-1.

If you do not specify an estbytes value when you create a new smart large object, Universal Server obtains the value from the inheritance hierarchy of storage characteristics. For more information on the inheritance hierarchy, see "Obtaining Storage Characteristics".

Do not change this system value unless you know the estimated size for the smart large object. If you do set the estimated size for a smart large object, do not specify a value much higher than the final size of the smart large object. Otherwise, the database server might allocated unused storage.

Return Values

0

The function was successful.

-1

The function was not successful.

Related Functions

 ifx_lo_def_create_spec(), ifx_lo_specget_estbytes(), ifx_lo_specset_extsz(), ifx_lo_specset_flags(), ifx_lo_specset_maxbytes(), ifx_lo_specset_sbspace(), ifx_lo_spec_free()

ifx_lo_specset_extsz()

The ifx_lo_specset_extsz() function sets the allocation extent size for a smart large object.

Syntax

Usage

 The extsz value specifies the size of the allocation extents to be allocated for the smart large object when the database server writes beyond the end of the current extent. This value overrides the estimate that Universal Server generates for how large an extent should be. For more information on the allocation extent, see Figure 7-1.

If you do not specify an extsz value when you create a new smart large object, Universal Server attempts to optimize the extent size based on past operations on the smart large object and other storage characteristics (such as maximum bytes) that it obtains from the inheritance hierarchy of storage characteristics. For more information on the inheritance hierarchy, see "Obtaining Storage Characteristics".

Do not change this system value unless you know the allocation extent size for the smart large object. Only applications that encounter severe storage fragmentation should ever set the allocation extent size. For such applications, make sure you know exactly the number of bytes by which to extend the smart large object.

Return Values

0

The function was successful.

-1

The function was not successful.

ifx_lo_specset_flags()

 The ifx_lo_specset_flags() function sets the create-time flags of a smart large object.

Syntax

Usage

 The create-time flags provide the following information about a smart large object:

These two indicators are masked together into the single flags value. For more information on the create-time flags, see Figure 7-2.

If you do not specify a flags value when you create a new smart large object, Universal Server obtains the value from the inheritance hierarchy of storage characteristics. For more information on the inheritance hierarchy, see "Obtaining Storage Characteristics".

Return Values

0

The function was successful.

-1

The function was not successful.

Related Functions

 ifx_lo_def_create_spec(), ifx_lo_spec_free(), ifx_lo_specget_flags(), ifx_lo_specset_extsz(), ifx_lo_specset_flags(), ifx_lo_specset_maxbytes(), ifx_lo_specset_sbspace()

ifx_lo_specset_maxbytes()

The ifx_lo_specset_maxbytes() function sets the maximum size for a smart large object.

Syntax

Usage

 Universal Server does not allow the size of a smart large object to exceed the maxbytes value. The database server does not obtain the value from the inheritance hierarchy of storage characteristics. For more information on the maximum size, see Figure 7-1.

Return Values

0

The function was successful.

-1

The function was not successful.

Related Functions

 ifx_lo_def_create_spec(), ifx_lo_specget_maxbytes(), ifx_lo_specset_estbytes(), ifx_lo_specset_extsz(), ifx_lo_specset_flags(), ifx_lo_specset_sbspace(), ifx_lo_spec_free()

ifx_lo_specset_sbspace()

The ifx_lo_specset_sbspace() function sets the name of the sbspace for a smart large object.

Syntax

Usage

 The name of the sbspace can be at most 18 characters long. It must also be null terminated.

If you do not specify an sbspace_name when you create a new smart large object, Universal Server obtains the sbspace name from either the column information or from the SBSPACENAME parameter of the ONCONFIG file. For more information, see "Obtaining Storage Characteristics".

Return Values

0

The function was successful.

-1

The function was not successful.

Related Functions

 ifx_lo_def_create_spec(), ifx_lo_specget_sbspace(), ifx_lo_specset_estbytes(), ifx_lo_specset_extsz(), ifx_lo_specset_flags(), ifx_lo_specset_maxbytes(), ifx_lo_spec_free()

ifx_lo_stat()

The ifx_lo_stat() function returns information about the current status of an open smart large object.

Syntax

Usage

 The ifx_lo_stat() function allocates an LO-status structure, ifx_lo_stat_t, and initializes it with the status information for the smart large object that the LO_fd file descriptor identifies. To access the status information, use the ESQL/C accessor functions for the LO-status structure. For more information on the status information and the corresponding accessor functions, see Figure 7-7.

Use the ifx_lo_stat_free() function to deallocate an LO-status structure.

Return Values

0

The function was successful.

<0

The function was not successful and the return value indicates the cause of the failure.

Related Functions

 ifx_lo_create(), ifx_lo_open(), ifx_lo_stat_atime(), ifx_lo_stat_cspec(), ifx_lo_stat_ctime(), ifx_lo_stat_free(), ifx_lo_stat_mtime_sec(), ifx_lo_stat_refcnt(), ifx_lo_stat_size()

ifx_lo_stat_atime()

The ifx_lo_stat_atime() function returns the time of last access for a smart large object.

Syntax

Usage

 The time of last access is only guaranteed to be maintained if the smart large object has the LO_KEEP_LASTACCESS_TIME flag set. If you do not set this flag, the database server does not write this access-time value to disk. The resolution of the time that the ifx_lo_stat_atime() function returns is seconds.

The status information for the smart large object is in the LO-status structure to which LO_stat points. The ifx_lo_stat() function allocates this structure and fills it with the status information for a particular smart large object. Therefore, you must precede a call to ifx_lo_stat_atime() with a call to ifx_lo_stat().

Return Values

>=0

The last-access time for the smart large object that LO_stat identifies.

-1

The function was not successful.

Related Functions

 ifx_lo_stat(), ifx_lo_stat_cspec(), ifx_lo_stat_ctime(), ifx_lo_stat_free(), ifx_lo_stat_mtime_sec(), ifx_lo_stat_refcnt(), ifx_lo_stat_size()

ifx_lo_stat_cspec()

The ifx_lo_stat_cspec() function returns the LO-specification structure for a smart large object.

Syntax

Usage

 The ifx_lo_stat_cspec() function returns a pointer to an LO-specification structure that contains the storage characteristics for the specified smart large object. You can use this LO-specification structure to create another smart large object with the same storage characteristics. To access storage characteristics from this structure, use the ESQL/C accessor functions for the LO-specification structure. For more information, see page 7-7.

The status information for the smart large object is in the LO-status structure to which LO_stat points. The ifx_lo_stat() function allocates this structure and fills it with the status information for a particular smart large object. Therefore, you must precede a call to ifx_lo_stat_cspec() with a call to ifx_lo_stat().

Return Values

A valid pointer to an LO-specification
(ifx_lo_create_spec_t) structure

The function was successful.

-1

The function was not successful.

Related Functions

 ifx_lo_stat(), ifx_lo_stat_atime(), ifx_lo_stat_ctime(), ifx_lo_stat_free(), ifx_lo_stat_mtime_sec(), ifx_lo_stat_refcnt(), ifx_lo_stat_size()

ifx_lo_stat_ctime()

The ifx_lo_stat_ctime() function returns the time of last change in status for a smart large object.

Syntax

Usage

 The last change in status includes modification of storage characteristics, including a change in the number of references and writes to the smart large object. The resolution of the time that the ifx_lo_stat_ctime() function returns is seconds.

The status information for the smart large object is in the LO-status structure to which LO_stat points. The ifx_lo_stat() function allocates this structure and fills it with the status information for a particular smart large object. Therefore, you must precede a call to ifx_lo_stat_ctime() with a call to ifx_lo_stat().

Return Values

>=0

The last-change time for the smart large object that LO_stat identifies.

-1

The function was not successful.

Related Functions

 ifx_lo_stat(), ifx_lo_stat_atime(), ifx_lo_stat_cspec(), ifx_lo_stat_free(), ifx_lo_stat_mtime_sec(), ifx_lo_stat_refcnt(), ifx_lo_stat_size()

ifx_lo_stat_free()

The ifx_lo_stat_free() function frees an LO-status structure.

Syntax

Usage

 The ifx_lo_stat() function returns status information about an open smart large object in an LO-status structure. When your application no longer needs this status information, use the ifx_lo_stat_free() function to deallocate the LO-status structure.

Return Values

0

The function was successful.

-1

The function was not successful.

Related Functions

 ifx_lo_stat()

ifx_lo_stat_mtime_sec()

The ifx_lo_stat_mtime_sec() function returns the time of last modification for a smart large object.

Syntax

Usage

 The resolution of the time that the ifx_lo_stat_mtime_sec() function returns is seconds.

The status information for the smart large object is in the LO-status structure to which LO_stat points. The ifx_lo_stat() function allocates this structure and fills it with the status information for a particular smart large object. Therefore, you must precede a call to ifx_lo_stat_mtime_sec() with a call to ifx_lo_stat().

Return Values

>=0

The last-modification time for the smart large object that LO_stat identifies.

-1

The function was not successful.

Related Functions

 ifx_lo_stat(), ifx_lo_stat_atime(), ifx_lo_stat_cspec(), ifx_lo_stat_ctime(), ifx_lo_stat_free(), ifx_lo_stat_refcnt(), ifx_lo_stat_size()

ifx_lo_stat_refcnt()

The ifx_lo_stat_refcnt() function returns the number of references to a smart large object.

Syntax

Usage

 The refcnt argument is the reference count for a smart large object. This count indicates the number of persistently stored LO-pointer (ifx_lo_t) structures that currently exist for the smart large object. The database server assumes that it can safely remove the smart large object and reuse any resources that are allocated to it when the reference count is zero (0) and any of the following conditions exist:

    The database server increments a reference counter when it stores the LO-pointer structure for a smart large object in a row.

The status information for the smart large object is in the LO-status structure to which LO_stat points. The ifx_lo_stat() function allocates this structure and fills it with the status information for a particular smart large object. Therefore, you must precede a call to ifx_lo_stat_refcnt() with a call to ifx_lo_stat().

Return Values

>=0

The reference count for the smart large object that LO_stat identifies.

-1

The function was not successful.

Related Functions

 ifx_lo_stat(), ifx_lo_stat_atime(), ifx_lo_stat_cspec(), ifx_lo_stat_ctime(), ifx_lo_stat_free(), ifx_lo_stat_mtime_sec(), ifx_lo_stat_size()

ifx_lo_stat_size()

The ifx_lo_stat_size() function returns the size, in bytes, of a smart large object.

Syntax

Usage

 The status information for the smart large object is in the LO-status structure to which LO_stat points. The ifx_lo_stat() function allocates this structure and fills it with the status information for a particular smart large object. Therefore, you must precede a call to ifx_lo_stat_size() with a call to ifx_lo_stat().

Return Values

0

The function was successful.

-1

The function was not successful.

Related Functions

 ifx_lo_stat(), ifx_lo_stat_atime(), ifx_lo_stat_cspec(), ifx_lo_stat_ctime(), ifx_lo_stat_free(), ifx_lo_stat_mtime_sec(), ifx_lo_stat_refcnt()

ifx_lo_tell()

The ifx_lo_tell() function returns the current file or seek position for an open smart large object.

Syntax

Usage

 The seek position is the offset for the next read or write operation on the smart large object that is associated with the LO file descriptor, LO_fd. The ifx_lo_tell() function returns this seek position in the user-defined int8 variable, seek_pos.

Return Values

0

The function was successful.

<0

The function was not successful and the return value indicates the cause of the failure.

Related Functions

 ifx_lo_readwithseek(), ifx_lo_seek(), ifx_lo_writewithseek()

ifx_lo_to_buffer()

The ifx_lo_to_buffer() function copies a specified number of bytes from a smart large object into a user-defined buffer.

Syntax

Usage

 The ifx_lo_to_buffer() function copies bytes, up to the size that the size argument specifies from the smart large object that the LO_ptr argument identifies. The read operation from the smart large object starts at a zero-byte offset. If the smart large object is smaller than the size value, ifx_lo_to_buffer() copies only the number of bytes in the smart large object. If the smart large object contains more than size bytes, the ifx_lo_to_buffer() function only copies up to size bytes into the user-defined buffer.

When buf_ptr is NULL, ifx _lo_to_buffer() allocates the memory for the user-defined buffer. Otherwise, the function assumes that you have allocated memory that buf_ptr identifies.

Return Values

0

The number of bytes copied from the smart large object to the user-defined buffer that buf_ptr identifies.

-1

The function was not successful.

ifx_lo_truncate()

 The ifx_lo_truncate() function truncates a smart large object at a specified byte position.

Syntax

Usage

 The ifx_lo_truncate() function sets the last valid byte of a smart large object to the specified offset value. If this offset value is beyond the current end of the smart large object, you actually extend the smart large object. If this offset value is less than the current end of the smart large object, the database server reclaims all storage, from the position that offset indicates to the end of the smart large object.

Return Values

0

The function was successful.

<0

The function was not successful and the return value indicates the cause of the failure.

ifx_lo_write()

 The ifx_lo_write() function writes a specified number of bytes of data to an open smart large object.

Syntax

Usage

 The ifx_lo_write() function writes nbytes of data to the smart large object that the LO_fd file descriptor identifies. The write begins at the current seek position for LO_fd. You can use the ifx_lo_tell() function to obtain the current seek position.

The function obtains the data from the user-defined buffer to which buf points. The buf buffer must be less than 2 gigabytes in size.

If the database server writes less than nbytes of data to the smart large object, the ifx_lo_write() function returns the number of bytes that it wrote and sets the error value to point to a value that indicates the reason for the incomplete write operation. This condition can occur when the sbspace runs out of space.

Return Values

>=0

The number of bytes that the function has written from the buf character buffer to open the smart large object.

-1

The function was not successful; examine the error for a detailed error code.

Related Functions

 ifx_lo_open(), ifx_lo_read(), ifx_lo_seek(), ifx_lo_tell(), ifx_lo_writewithseek()

ifx_lo_writewithseek()

The ifx_lo_writewithseek() function performs a seek operation and then writes a specified number of bytes of data to an open smart large object.

Syntax

Usage

 The ifx_lo_writewithseek() function writes nbytes of data to the smart large object that the LO_fd file descriptor identifies. The function obtains the data to write from the user-defined buffer to which buf points. The buffer must be less than 2 gigabytes in size.

The write begins at the seek position of LO_fd that the offset and whence arguments indicate, as follows:

If the database server writes less than nbytes of data to the smart large object, the ifx_lo_writewithseek() function returns the number of bytes that it wrote and sets the error value to point to a value that indicates the reason for the incomplete write operation. This condition can occur when the sbspace runs out of space.

Return Values

>=0

The number of bytes that the function has written from the buf character buffer to the smart large object.

-1

The function was not successful; examine the error for a detailed error code.

Related Functions

 ifx_lo_open(), ifx_lo_readwithseek(), ifx_lo_seek(), ifx_lo_write()



Informix-ESQL/C Programmer's Manual, version 9.1
Copyright © 1998, Informix Software, Inc. All rights reserved.