lld_open()

API

LLD_IO* lld_open(conn, lob, flags, error)
   MI_CONNECTION*               conn;
   MI_ROW*                      lob;
   mi_integer                   flags,
   mi_integer*                  error);

ESQL/C

LLD_IO* lld_open(lob, flags, error);
   EXEC SQL BEGIN DECLARE SECTION;
      PARAMETER ROW lob;
   EXEC SQL END DECLARE SECTION;
      int flags;int* error;

conn

is the connection descriptor established by a previous call to the mi_open() or mi_server_connect() functions. This parameter is for the API interface only. In the ESQL/C version of this function, you must already be connected to a server.

lob

is a pointer to an lld_locator row, identifying the object to open.

flags

is a set of flags that you can set to specify attributes of the large object after it is opened. The flags are as follows:

LLD_RDONLY: opens the large object for reading only. You cannot use the lld_write function to write to the specified large object when this flag is set.
LLD_WRONLY: opens the large object for writing only. You cannot use the lld_read() function to read from the specified large object when this flag is set.
LLD_RDWR: opens the large object for both reading and writing.
LLD_TRUNC: clears the contents of the large object after opening.
LLD_APPEND: seeks to the end of the large object for writing. When the object is opened, the file pointer is positioned at the beginning of the object. If you have opened the object for reading or reading and writing, you can seek anywhere in the file and read. However, any time you call lld_write() to write to the object, the pointer moves to the end of the object to guarantee that you do not overwrite any data.
LLD_SEQ: opens the large object for sequential access only. You cannot use the lld_seek() function with the specified large object when this flag is set.

error

is an output parameter in which the function returns an error code.

Usage

In the lob parameter, you pass an lld_locator row to identify the large object to open. In the lo_protocol field of this row, you specify the type of the large object to open. The lld_open() function calls an appropriate open routine based on the type you specify. For example, for a file, lld_open() uses an operating system file function to open the file, whereas, for a smart large object, it calls the server's mi_lo_open() routine.

Large Object Locator does not directly support two fundamental database features, transaction rollback and concurrency control. Therefore, if the transaction in which you call lld_open() is aborted, you should call lld_close() to close the object and reclaim any allocated resources.

Your application should also provide some means, such as locking a row, to guarantee that multiple users cannot write to a large object simultaneously.

See Limitations for more information about transaction rollback and concurrency control.

Return Codes

On success, this function returns a pointer to an LLD_IO structure it allocates. The LLD_IO structure is private, and you should not directly access it or modify its contents. Instead, you can pass the LLD_IO structure's pointer to Large Object Locator routines such as lld_write(), lld_read(), and so on, that access open large objects.

A large object remains open until you explicitly close it with the lld_close() function. Therefore, if you encounter error conditions after opening a large object, you are responsible for reclaiming resources by closing it.

On failure, this function returns NULL.

lld_open()

Syntax

Usage

Return Codes

Context