Oracle® Call Interface Programmer's Guide, 10g Release 2 (10.2) Part Number B14250-02 |
|
|
View PDF |
This section describes the OCI string functions.
Table 18-17 String Functions
Function/Page | Purpose |
---|---|
|
Get allocated size of string memory in bytes |
|
Assign string to string |
|
Assign text string to string |
|
Get string pointer |
|
Resize string memory |
|
Get string size |
Purpose
Gets allocated size of string memory in codepoints (Unicode) or in bytes.
Syntax
sword OCIStringAllocSize ( OCIEnv *env, OCIError *err, CONST OCIString *vs, ub4 *allocsize );
Parameters
The OCI environment handle initialized in object mode.
The OCI error handle. If there is an error, it is recorded in err
and this function returns OCI_ERROR
. Obtain diagnostic information by calling OCIErrorGet()
.
String whose allocated size in bytes is returned. vs
must be a non-NULL
pointer.
The allocated size of string memory in bytes is returned.
Comments
The allocated size is greater than or equal to the actual string size.
Related Functions
OCIErrorGet(), OCIStringResize(), OCIStringSize()
Purpose
Assigns one string to another string.
Syntax
sword OCIStringAssign ( OCIEnv *env, OCIError *err, CONST OCIString *rhs, OCIString **lhs );
Parameters
The OCI environment handle initialized in object mode.
The OCI error handle. If there is an error, it is recorded in err
and this function returns OCI_ERROR
. Obtain diagnostic information by calling OCIErrorGet()
.
Right-hand side (source) of the assignment. Can be in UTF-16.
Left-hand side (target) of the assignment. Its buffer is UTF-16 if rhs
is UTF-16.
Comments
Assigns rhs
string to lhs
string. The lhs
string may be resized depending upon the size of the rhs
. The assigned string is NULL
-terminated. The length field will not include the extra codepoint or byte needed for NULL
-termination.
This function returns an error if the assignment operation runs out of space.
Related Functions
OCIErrorGet(), OCIStringAssignText()
Purpose
Assigns the source text string to the target string.
Syntax
sword OCIStringAssignText ( OCIEnv *env, OCIError *err, CONST OraText *rhs, ub2 rhs_len, OCIString **lhs );
Parameters
The OCI environment handle initialized in object mode.
The OCI error handle. If there is an error, it is recorded in err
and this function returns OCI_ERROR
. Obtain diagnostic information by calling OCIErrorGet()
.
Right-hand side (source) of the assignment, a text or UTF-16 Unicode string.
Length of the rhs
string in bytes.
Left-hand side (target) of the assignment. Its buffer is Unicode if rhs
is Unicode.
Comments
Assigns rhs
string to lhs
string. The lhs
string may be resized depending upon the size of the rhs
. The assigned string is NULL
-terminated. The length field will not include the extra byte or codepoint needed for NULL
-termination.
Related Functions
OCIErrorGet(), OCIStringAssign()
Purpose
Gets a pointer to the text of a given string.
Syntax
text *OCIStringPtr ( OCIEnv *env, CONST OCIString *vs );
Parameters
The OCI environment handle initialized in object mode.
Pointer to the OCIString
object whose character string will be returned. If vs
is in UTF-16, the returned buffer will also be UTF-16. If you want to know the encoding of the returned buffer, check the UTF-16 information in the OCIString
vs
itself, since it is not guaranteed that a particular OCIString
must have the same setting as env
does. The function to check should be some object OCI function designed to check member fields in objects.
Comments
None.
Related Functions
OCIErrorGet(), OCIStringAssign()
Purpose
Resizes the memory of a given string.
Syntax
sword OCIStringResize ( OCIEnv *env, OCIError *err, ub4 new_size, OCIString **str );
Parameters
The OCI environment handle initialized in object mode.
The OCI error handle. If there is an error, it is recorded in err
and this function returns OCI_ERROR
. Obtain diagnostic information by calling OCIErrorGet()
.
New memory size of the string in bytes. new_size
must include space for the NULL
character as the string terminator.
Allocated memory for the string which is freed from the OCI object cache.
Comments
This function resizes the memory of the given variable-length string in the object cache. Contents of the string are not preserved. This function may allocate the string in a new memory region, in which case the original memory occupied by the given string is freed. If str
is NULL
, this function allocates memory for the string. If new_size
is 0, this function frees the memory occupied by str
and a NULL
pointer value is returned.
Related Functions
OCIErrorGet(), OCIStringAllocSize(), OCIStringSize()
Purpose
Gets the size of the given string vs
.
Syntax
ub4 OCIStringSize ( OCIEnv *env, CONST OCIString *vs );
Parameters
The OCI environment handle initialized in object mode.
String whose size is returned, in number of bytes.
Comments
The returned size does not include an extra byte for NULL
termination.
Related Functions