CUBRID PHP APIs to work with LOB object

The following twelve CUBRID PHP API functions are now implemented in CUBRID PHP API version 8.4.1.004 in addition to five existing functions to allow PHP developers to perform various operations on Large Object (LOB) data.

1. cubrid_lob2_new

Create a lob object.

Description

resource cubrid_lob2_new( [resource $conn_identifier [, string $type = "BLOB"]] )

The cubrid_lob2_new() function is used to create a lob object (both BLOB and CLOB). This function should be used before you bind a lob object.

Parameters

conn_identifier

Connection identifier. If the connection identifier is not specified, the last connection opened by cubrid_connect() or cubrid_connect_with_url() is assumed.

type

It may be "BLOB" or "CLOB", it won't be case-sensitive. The default value is "BLOB".

Return values

Lob identifier when it is successful.

FALSE on failure.

2. cubrid_lob2_bind

Bind a lob object or a string as a lob object to a prepared statement as parameters.

Description

bool cubrid_lob2_bind( resource $req_identifier, int $bind_index ,mixed $bind_value[, string $bind_value_type]

cubrid_lob2_bind() is used to bind BLOB/CLOB datas to a corresponding question mark placeholder in the SQL statement that was passed to cubrid_prepare(). If $bind_value_type is not given, string will be BLOB as the default. But if you use cubrid_lob2_new() before, $bind_value_type will be consistent with $type in cubrid_lob2_new() as the default.

Parameters

req_identifier

Request identifier as a result of cubrid_prepare().

bind_index

Location of binding parameters. It starts with 1.

bind_value

Actual value for binding.

bind_value_type

It must be "BLOB" or "CLOB" and it won't be case-sensitive. If it not be given, the default value is "BLOB"

Return values

TRUE, when process is successful.

FALSE, when process is unsuccessful.

Example

<?php
// Table: test_lob (id INT, contents CLOB)

$conn = cubrid_connect("localhost", 33000, "demodb", "public", "");

$req = cubrid_prepare($conn, "INSERT INTO test_lob VALUES (?, ?)");

cubrid_bind($req,1, 3);

$lob = cubrid_lob2_new($conn, 'CLOB');

cubrid_lob2_bind($req, 2, $lob);

cubrid_execute($req);

cubrid_bind($req, 1, 4);
cubrid_lob2_bind($req, 2, 'CUBRID LOB2 TEST', 'CLOB');

cubrid_execute($req);

cubrid_disconnect($conn);
?>

3. cubrid_lob2_export

Export the lob object to a file.

Description

bool cubrid_lob2_export ( resource $lob_identifier, string $file_name )

cubrid_lob2_export() is used to save the contents of BLOB/CLOB data to a file. To use this function, you must use cubrid_lob2_new() or fetch a lob object from CUBRID database first. If the file has existed, it will fail. This function will not influence the cursor position of the lob object. It operates the entire lob object.

Parameters

lob_identifier

Lob identifier as a result of cubrid_lob2_new() or get from the result set.

filename

File name you want to store BLOB/CLOB data. It also supports the path of the file.

Return values

True if the process is successful and false for failure.

Example

<?php
// Table: test_lob (id INT, contents CLOB)

$conn = cubrid_connect("localhost", 33000, "demodb", "public", "");

$req = cubrid_execute($conn, "select * from test_lob");

cubrid_move_cursor($req, 3, CUBRID_CURSOR_FIRST);
$row = cubrid_fetch($req, CUBRID_NUM | CUBRID_LOB);

$lob = $row[1];

cubrid_lob2_export($lob, “doc_3.txt”);

cubrid_disconnect($conn);
?>

4. cubrid_lob2_import

Import BLOB/CLOB data from a file.

Description

bool cubrid_lob2_import ( resource $lob_identifier, string $file_name )

cubrid_lob2_import() is used to save the contents of BLOB/CLOB data from a file. To use this function, you must use cubrid_lob2_new() or fetch a LOB object from CUBRID database first. This function will not influence the cursor position of the lob object. It operates the entire lob object.

Parameters

lob_identifier

Lob identifier as a result of cubrid_lob2_new() or get from the result set.

filename

File name you want to import BLOB/CLOB data. It also supports the path of the file.

Return values

True if the process is successful and false for failure.

Example

<?php
$conn = cubrid_connect("localhost", 33000, "demodb", "public", "");

cubrid_execute($conn, "CREATE TABLE test_lob (id INT, contents CLOB)");

$req = cubrid_prepare($conn, "INSERT INTO test_lob (?, ?)");
cubrid_bind($req, 1, 1);

$lob = cubrid_lob2_new($conn, "clob");
cubrid_lob2_import($lob, "doc_1.txt");
cubrid_lob2_bind($req, 2, $lob, ‘CLOB’); // or cubrid_lob2_bind($req, 2 $lob);

cubrid_execute($req);

cubrid_disconnect($conn);
?>

5. cubrid_lob2_read

Read from BLOB/CLOB data.

Description

string cubrid_lob2_read ( resource $lob_identifier, int $len )

cubrid_lob2_read() reads $len bytes from the LOB data, then return it.

Parameters

lob_identifier

Lob identifier as a result of cubrid_lob2_new() or get from the result set.

len

Length from buffer you want to read from the lob data.

Return values

Returns the contents as a string.

FALSE when there is no more data.

NULL on failure.

Example 1

<?php
// test_lob (id INT, contents CLOB)

$conn = cubrid_connect("localhost", 33000, "demodb", "public", "");

$req = cubrid_execute($conn, "select * from test_lob");

$row = cubrid_fetch($req, CUBRID_NUM | CUBRID_LOB);
$lob = $row[1];
cubrid_lob2_seek($lob, 10, CUBRID_CURSOR_FIRST);
$data = cubrid_lob2_read($lob, 12);

print $data . "\n";

cubrid_disconnect($conn);
?>

Example 2

<?php
// test_lob (id INT, contents CLOB)

$conn = cubrid_connect("localhost", 33000, "demodb", "public", "");

$req = cubrid_execute($conn, "select * from test_lob");

$row = cubrid_fetch($req, CUBRID_NUM | CUBRID_LOB);
$lob = $row[1];

while (true) {
  if ($data = cubrid_lob2_read($lob, 1024)) {
    print $data . "\n";
  }
  elseif ($data === FALSE) {
    print "There is no more data\n";
    break;
  }
  else {
    print "There must be some errors.\n";
  }
}

cubrid_disconnect($conn);
?>

6. cubrid_lob2_write

Write to a lob object.

Description

bool cubrid_lob2_write ( resource $lob_identifier, string $buf )

cubrid_lob2_write() reads as much as data from buf and stores it to the LOB object. Note that this function can only append characters now.

Parameters

lob_identifier

Lob identifier as a result of cubrid_lob2_new() or get from the result set.

buf

Data that need to be written to the lob object.

Return values

True if the process is successful and false for failure.

Example 1

<?php
// test_lob (id INT, contents CLOB)

$conn = cubrid_connect("localhost", 33000, "demodb", "public", "");

$req = cubrid_prepare($conn, "INSERT INTO test_lob (2, ?)");

$lob = cubrid_lob2_new($conn, 'CLOB');
$len = cubrid_lob2_write($lob, "Hello world");

cubrid_lob2_bind($req, 1, $lob);
cubrid_execute($req);

cubrid_disconnect($conn);
?>

Example 2

<?php
// test_lob (id INT, contents CLOB)

$conn = cubrid_connect("localhost", 33000, "demodb", "public", "");

$req = cubrid_execute($conn, "select * from test_lob");

$row = cubrid_fetch($req, CUBRID_NUM | CUBRID_LOB);
$lob = $row[1];
cubrid_lob2_seek($lob, 0, CUBRID_CURSOR_LAST);
cubrid_lob2_write($lob, "Hello world");

cubrid_disconnect($conn);
?>

7. cubrid_lob2_tell

Tell the cursor position of the LOB object.

Description

int cubrid_lob2_tell ( resource $lob_identifier )

cubrid_lob2_tell() is used to tell the cursor position of the LOB object.

Parameters

lob_identifier

Lob identifier as a result of cubrid_lob2_new() or get from the result set.

Return values

It will return the cursor position on the LOB object when it processes successfully.

FALSE on failure.

8. cubrid_lob2_tell64

Tell the cursor position of the LOB object.

Description

string cubrid_lob2_tell64 ( resource $lob_identifier )

cubrid_lob2_tell64() is used to tell the cursor position of the LOB object. If the size of a lob object is larger than an integer data can be stored, you can use this function and it will return the position information as a string.

Parameters

lob_identifier

Lob identifier as a result of cubrid_lob2_new() or get from the result set.

Return values

It will return the cursor position on the LOB object as a string when it processes successfully.

FALSE on failure.

9. cubrid_lob2_seek

Move the cursor of a lob object.

Description

bool cubrid_lob2_seek ( resource $lob_identifier, int $offset, [ int $origin = CUBRID_CURSOR_CURRENT] )

cubrid_lob2_seek() is used to move the cursor position of a lob object by the value set in the offset argument, to the direction set in the origin argument.

To set the origin argument, you can use CUBRID_CURSOR_FIRST to set the cursor position moving forward offset units from the first beginning. In this case, offset must be a positive value.

If you use CUBRID_CURSOR_CURRENT for origin, you can move forward or backward. and offset can be positive or negative.

If you use CUBRID_CURSOR_LAST for origin, you can move backward offset units from the end of LOB object and offset only can be positive.

Parameters

lob_identifier

Lob identifier as a result of cubrid_lob2_new() or get from the result set.

offset

Number of units you want to move the cursor.

origin

This parameter can be the following values:

CUBRID_CURSOR_FIRST: move forward from the first beginning.

CUBRID_CURSOR_CURRENT: move forward or backward from the current position.

CUBRID_CURSOR_LAST: move backward at the end of LOB object.

Return values

True if the process is successful and false for failure.

Example

<?php
// test_lob (id INT, contents CLOB)

$conn = cubrid_connect("localhost", 33000, "demodb", "public", "");

$req = cubrid_execute($conn, "INSERT INTO test_lob (2, ?)");

$lob = cubrid_lob2_new($conn, 'CLOB');
$len = cubrid_lob2_write($lob, "Hello world");

cubrid_lob2_seek($lob, 6, CUBRID_CURSOR_FIRST);
$cubrid_lob2_write($lob, "beautifull");

cubrid_bind($req, 1, $lob);
cubrid_execute($req);

cubrid_disconnect($conn);
?>

10. cubrid_lob2_seek64

Move the cursor of a lob object.

Description

bool cubrid_lob2_seek64 ( resource $lob_identifier, string $offset, [ int $origin = CUBRID_CURSOR_CURRENT] )

cubrid_lob2_seek64() is used to move the cursor position of a lob object by the value set in the offset argument, to the direction set in the origin argument. If the $offset you want to move is larger than an integer data can be stored, you can use this function.

To set the origin argument, you can use CUBRID_CURSOR_FIRST to set the cursor position moving forward offset units from the first beginning. In this case, offset must be a positive value.

If you use CUBRID_CURSOR_CURRENT for origin, you can move forward or backward. and offset can be positive or negative.

If you use CUBRID_CURSOR_LAST for origin, you can move backward offset units from the end of LOB object and offset only can be positive.

NOTE:

If you use this function to move the cursor position of the lob object, you should pass $offset as a string.

Parameters

lob_identifier

Lob identifier as a result of cubrid_lob2_new() or get from the result set.

offset

Number of units you want to move the cursor.

origin

This parameter can be the following values:

CUBRID_CURSOR_FIRST: move forward from the first beginning.

CUBRID_CURSOR_CURRENT: move forward or backward from the current position.

CUBRID_CURSOR_LAST: move backward at the end of LOB object.

Return values

True if the process is successful and false for failure.

Example

<?php
// test_lob (id INT, contents CLOB)

$conn = cubrid_connect("localhost", 33000, "demodb", "public", "");

$req = cubrid_execute($conn, "select * from test_lob");
$row = cubrid_fetch_row($req, CUBRID_LOB);
$lob = $row1;

cubrid_lob2_seek($lob, "20101029056306120215", CUBRID_CURSOR_FIRST);
$data = cubrid_lob2_read($lob, 20);

cubrid_disconnect($conn);
?>

11. cubrid_lob2_size

Get a lob object's size.

Description

int cubrid_lob2_size  ( resource $lob_identifier )

cubrid_lob2_size() is used to get the size of a lob object.

Parameters

lob_identifier

Lob identifier as a result of cubrid_lob2_new() or get from the result set.

Return values

It will return the size of the LOB object when it processes successfully.

FALSE on failure.

12. cubrid_lob2_size64

Get a lob object's size.

Description

string cubrid_lob2_size64 ( resource $lob_identifier )

cubrid_lob2_size64() is used to get the size of a LOB object. If the size of a lob object is larger than an integer data can be stored, you can use this function and it will return the size as a string.

Parameters

lob_identifier

Lob identifier as a result of cubrid_lob2_new() or get from the result set.

Return values

It will return the size of the LOB object as a string when it processes successfully.

FALSE on failure.

13. cubrid_lob2_close

Close LOB object.

Description

bool cubrid_lob2_close ( resource $lob_identifier )

cubrid_lob2_close() is used to close LOB object returned from cubrid_lob2_new() or get from the result set.

Parameters

lob_identifier

Lob identifier as a result of cubrid_lob2_new() or get from the result set.

Return values

TRUE, on success.

FALSE, on failure.

Complete PHP example

<?php
// The following code will show you how to handle lob object in PHP Driver.
// Table : test_lob(id INT, contents CLOB)

$conn = cubrid_connect("localhost", 33000, "demodb", "public", "");

$request = cubrid_execute($conn, "select * from test_lob");

cubrid_data_seek($request, 3, CUBRID_CURSOR_FIRST); // You can also use cubrid_move_cursor()
$row = cubrid_fetch($req, CUBRID_NUM | CUBRID_LOB);
$lob = $row[1];

$data = cubrid_lob2_read($lob, 100);
print $data . "\n";

cubrid_lob2_export($lob, “/home/xdbms/doc_3.txt”);

$req = cubrid_prepare($conn, “INSERT INTO test_lob(?, ?)”);

cubrid_bind($req, 1, 5);

$lob = cubrid_lob2_new($conn, ‘CLOB’);
cubrid_lob2_import($lob, "/home/xdbms/doc_5.txt");
cubrid_lob2_seek($lob, 1, CUBRID_CURSOR_FIRST);
cubrid_lob2_write($lob, "http://www.cubrid.org");

cubrid_bind($req, 2, $lob);
cubrid_execute($req);

cubrid_disconnect($conn);
?>