The lld_open_client() function
This function opens a client file.
Syntax
LLD_IO* lld_open_client(conn, path, flags, error);
MI_CONNECTION* conn
mi_string* path;
mi_integer flags;
mi_integer* error;LLD_IO* lld_open_client(MI_CONNECTION* conn,mi_string* path,
mi_integer flags,mi_integer* error);- conn
- 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 and SQL versions of this function, you must already be connected to a server.
- path
- A pointer to the path name of the client file.
- flags
- 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 client file for reading only. You cannot use the lld_write function to write to the specified client file when this flag is set.
- LLD_WRONLY
- Opens the client file for writing only. You cannot use the lld_read() function to read from the specified client file when this flag is set.
- LLD_RDWR
- Opens the client file for both reading and writing.
- LLD_TRUNC
- Clears the contents of the client file 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 client file for sequential access only. You cannot use the lld_seek() function with the specified client file when this flag is set.
- error
- An output parameter in which the function returns an error code.
Usage
This function opens an existing client file. After the file is open, you can use any of the Large Object Locator functions, such as lld_read(), lld_write(), and so on, that operate on open large objects.
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_client() 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 Large object requirements for more information about transaction rollback and concurrency control.
Return codes
On success, this function returns a pointer to an LLD_IO structure that it allocates. The LLD_IO structure is private, and you should not directly access it or modify its contents. Instead, you should pass its pointer to Large Object Locator routines such as lld_write(), lld_read(), and so on, that access open client files.
A client file remains open until you explicitly close it with the lld_close() function. Therefore, if you encounter error conditions after opening a client file, you are responsible for reclaiming resources by closing it.
On
failure, this function returns NULL.