4 Datatypes

BFILE

The external datatype BFILE allows read-only byte stream access to large files on the file system of the database server. A BFILE is a large binary data object stored in operating system files outside database tablespaces. These files use reference semantics. The Oracle server can access a BFILE provided the underlying server operating system supports stream-mode access to these operating system files.

BDOUBLE

The BDouble interface in OCCI encapsulates the native double data and the NULL information of a column or object attribute of the type binary_double. The OCCI methods in AnyData Class, ResultSet Class and Statement Class, and the global methods that take these class objects as parameters, use the following definition for the BDOUBLE datatype:

struct BDouble 
{ 
  double value; 
  bool isNull; 
 
 BDouble() 
 { 
    isNull = false; 
    value = 0.; 
 } 
}; 

BFLOAT

The BFloat interface in OCCI encapsulates the native float data and the NULL information of a column or object attribute of the type binary_float. The OCCI methods in AnyData Class, ResultSet Class and Statement Class, and the global methods that take these class objects as parameters, use the following definition for the BFLOAT datatype:

struct BFloat 
{ 
  float value; 
  bool isNull; 
 
 BFloat() 
 { 
    isNull = false; 
    value = 0.; 
 } 
}; 

BLOB

The external datatype BLOB stores unstructured binary large objects. A BLOB can be thought of as a bitstream with no character set semantics. BLOBs can store up to 4 gigabytes of binary data.

BLOB datatypes have full transactional support. Changes made through OCCI participate fully in the transaction. BLOB value manipulations can be committed or rolled back. You cannot save a BLOB locator in a variable in one transaction and then use it in another transaction or session.

CHAR

The external datatype CHAR is a string of characters, with a maximum length of 2000 characters. Character strings are compared by using blank-padded comparison semantics.

CHARZ

The external datatype CHARZ is similar to the CHAR datatype, except that the string must be null terminated on input, and Oracle places a null terminator character at the end of the string on output. The null terminator serves only to delimit the string on input or output. It is not part of the data in the table.

CLOB

The external datatype CLOB stores fixed-width or varying-width character data. A CLOB can store up to 4 gigabytes of character data. CLOBs have full transactional support. Changes made through OCCI participate fully in the transaction. CLOB value manipulations can be committed or rolled back. You cannot save a CLOB locator in a variable in one transaction and then use it in another transaction or session.

DATE

The external datatype DATE can update, insert, or retrieve a date value using the Oracle internal seven byte date binary format, as listed in Table 4-3:

FLOAT

The external datatype FLOAT processes numbers with fractional parts. The number is represented in the host system's floating-point format. Normally, the length is 4 or 8 bytes.

The internal format of an Oracle number is decimal. Most floating-point implementations are binary. Oracle, therefore, represents numbers with greater precision than floating-point representations.

INTEGER

The external datatype INTEGER is used for converting numbers. An external integer is a signed binary number. Its size is operating system-dependent. If the number being returned from Oracle is not an integer, then the fractional part is discarded, and no error is returned. If the number returned exceeds the capacity of a signed integer for the system, then Oracle returns an overflow on conversion error.

INTERVAL DAY TO SECOND

The external datatype INTERVAL DAY TO SECOND stores the difference between two datetime values in terms of days, hours, minutes, and seconds. Specify this datatype as follows:

INTERVAL DAY [(day_precision)] 
   TO SECOND [(fractional_seconds_precision)]

This example uses the following placeholders:

• day_precision: Number of digits in the DAY datetime field. Accepted values are 1 to 9. The default is 2.

• fractional_seconds_precision: Number of digits in the fractional part of the SECOND datetime field. Accepted values are 0 to 9. The default is 6.

To specify an INTERVAL DAY TO SECOND literal with nondefault day and second precisions, you must specify the precisions in the literal. For example, you might specify an interval of 100 days, 10 hours, 20 minutes, 42 seconds, and 22 hundredths of a second as follows:

INTERVAL '100 10:20:42.22' DAY(3) TO SECOND(2)

You can also use abbreviated forms of the INTERVAL DAY TO SECOND literal. For example:

• INTERVAL '90' MINUTE maps to INTERVAL '00 00:90:00.00' DAY TO SECOND(2)

• INTERVAL '30:30' HOUR TO MINUTE maps to INTERVAL '00 30:30:00.00' DAY TO SECOND(2)

• INTERVAL '30' SECOND(2,2) maps to INTERVAL '00 00:00:30.00' DAY TO SECOND(2)

INTERVAL YEAR TO MONTH

The external datatype INTERVAL YEAR TO MONTH stores the difference between two datetime values by using the YEAR and MONTH datetime fields. Specify INTERVAL YEAR TO MONTH as follows:

INTERVAL YEAR [(year_precision)] TO MONTH

The placeholder year_precision is the number of digits in the YEAR datetime field. The default value of year_precision is 2. To specify an INTERVAL YEAR TO MONTH literal with a nondefault year_precision, you must specify the precision in the literal. For example, the following INTERVAL YEAR TO MONTH literal indicates an interval of 123 years, 2 months:

INTERVAL '123-2' YEAR(3) TO MONTH

You can also use abbreviated forms of the INTERVAL YEAR TO MONTH literal. For example,

• INTERVAL '10' MONTH maps to INTERVAL '0-10' YEAR TO MONTH

• INTERVAL '123' YEAR(3) maps to INTERVAL '123-0' YEAR(3) TO MONTH

LONG

The external datatype LONG stores character strings longer than 4000 bytes and up to 2 gigabytes in a column of datatype LONG. Columns of this type are only used for storage and retrieval of long strings. They cannot be used in methods, expressions, or WHERE clauses. LONG column values are generally converted to and from character strings.

LONG RAW

The external datatype LONG RAW is similar to the external datatype RAW, except that it stores up to 2 gigabytes.

LONG VARCHAR

The external datatype LONG VARCHAR stores data from and into an Oracle LONG column. The first four bytes contain the length of the item. The maximum length of a LONG VARCHAR is 2 gigabytes.

LONG VARRAW

The external datatype LONG VARRAW store data from and into an Oracle LONG RAW column. The length is contained in the first four bytes. The maximum length is 2 gigabytes.

NCLOB

The external datatype NCLOB is a national character version of a CLOB. It stores fixed-width, multibyte national character set character (NCHAR), or varying-width character set data. An NCLOB can store up to 4 gigabytes of character text data.

NCLOBs have full transactional support. Changes made through OCCI participate fully in the transaction. NCLOB value manipulations can be committed or rolled back. You cannot save an NCLOB locator in a variable in one transaction and then use it in another transaction or session.

You cannot create an object with NCLOB attributes, but you can specify NCLOB parameters in methods.

NUMBER

You should not need to use NUMBER as an external datatype. If you do use it, Oracle returns numeric values in its internal 21-byte binary format and will expect this format on input. The following discussion is included for completeness only.

Oracle stores values of the NUMBER datatype in a variable-length format. The first byte is the exponent and is followed by 1 to 20 mantissa bytes. The high-order bit of the exponent byte is the sign bit; it is set for positive numbers and it is cleared for negative numbers. The lower 7 bits represent the exponent, which is a base-100 digit with an offset of 65.

To calculate the decimal exponent, add 65 to the base-100 exponent and add another 128 if the number is positive. If the number is negative, you do the same, but subsequently the bits are inverted. For example, -5 has a base-100 exponent = 62 (0x3e). The decimal exponent is thus (~0x3e)-128-65 = 0xc1-128-65 = 193-128-65 = 0.

Each mantissa byte is a base-100 digit, in the range 1 to 100. For positive numbers, the digit has 1 added to it. So, the mantissa digit for the value 5 is 6. For negative numbers, instead of adding 1, the digit is subtracted from 101. So, the mantissa digit for the number -5 is: 101-5 = 96. Negative numbers have a byte containing 102 appended to the data bytes. However, negative numbers that have 20 mantissa bytes do not have the trailing 102 byte. Because the mantissa digits are stored in base-100, each byte can represent two decimal digits. The mantissa is normalized; leading zeroes are not stored.

Up to 20 data bytes can represent the mantissa. However, only 19 are guaranteed to be accurate. The 19 data bytes, each representing a base-100 digit, yield a maximum precision of 38 digits for an internal datatype NUMBER.

Note that this datatype is different from OCCI NUMBER which corresponds to a C++ Number datatype.

OCCI BFILE

OCCI BLOB

OCCI BYTES

OCCI CLOB

OCCI DATE

OCCI INTERVALDS

OCCI INTERVALYM

OCCI NUMBER

OCCI POBJECT

OCCI REF

OCCI REFANY

OCCI STRING

The external datatype OCCI STRING corresponds to an STL string.

OCCI TIMESTAMP

OCCI VECTOR

The external datatype OCCI VECTOR is used to represent collections, for example, a nested table or VARRAY. CREATE TYPE num_type as VARRAY OF NUMBER(10) can be represented in a C++ application as vector<int>, vector<Number>, and so on.

RAW

The external datatype RAW is used for binary data or byte strings that are not to be interpreted or processed by Oracle. RAW could be used, for example, for graphics character sequences. The maximum length of a RAW column is 2000 bytes.

When RAW data in an Oracle table is converted to a character string, the data is represented in hexadecimal code. Each byte of RAW data is represented as two characters that indicate the value of the byte, ranging from 00 to FF. If you input a character string by using RAW, then you must use hexadecimal coding.

REF

The external datatype REF is a reference to a named datatype. To allocate a REF for use in an application, declare a variable as a pointer to a REF.

ROWID

The external datatype ROWID identifies a particular row in a database table. The ROWID is often returned from a query by issuing a statement similar to the following example:

SELECT ROWID, var1, var2 FROM db;

You can then use the returned ROWID in further DELETE statements.

If you are performing a SELECT for an UPDATE operation, then the ROWID is implicitly returned.

STRING

The external datatype STRING behaves like the external datatype VARCHAR2 (datatype code 1), except that the external datatype STRING must be null-terminated.

Note that this datatype is different from OCCI STRING which corresponds to a C++ STL string datatype.

TIMESTAMP

The external datatype TIMESTAMP is an extension of the DATE datatype. It stores the year, month, and day of the DATE datatype, plus hour, minute, and second values. Specify the TIMESTAMP datatype as follows:

TIMESTAMP [(fractional_seconds_precision)] 

The placeholder fractional_seconds_precision optionally specifies the number of digits in the fractional part of the SECOND datetime field and can be a number in the range 0 to 9. The default is 6. For example, you specify TIMESTAMP(2) as a literal as follows:

TIMESTAMP '1997-01-31 09:26:50.10'

Note that this datatype is different from OCCI TIMESTAMP.

TIMESTAMP WITH LOCAL TIME ZONE

The external datatype TIMESTAMP WITH TIME ZONE (TSTZ) is a variant of TIMESTAMP that includes an explicit time zone displacement in its value. The time zone displacement is the difference (in hours and minutes) between local time and Coordinated Universal Time (UTC), formerly Greenwich Mean Time. Specify the TIMESTAMP WITH TIME ZONE datatype as follows:

TIMESTAMP(fractional_seconds_precision) WITH TIME ZONE

The placeholder fractional_seconds_precision optionally specifies the number of digits in the fractional part of the SECOND datetime field and can be a number in the range 0 to 9. The default is 6.

Two TIMESTAMP WITH TIME ZONE values are considered identical if they represent the same instant in UTC, regardless of the TIME ZONE offsets stored in the data.

TIMESTAMP WITH TIME ZONE

The external datatype TIMESTAMP WITH TIME ZONE is a variant of TIMESTAMP that includes a time zone displacement in its value. The time zone displacement is the difference (in hours and minutes) between local time and Coordinated Universal Time (UTC), formerly Greenwich Mean Time. Specify the TIMESTAMP WITH TIME ZONE datatype as follows:

TIMESTAMP [(fractional_seconds_precision)] WITH TIME ZONE

The placeholder fractional_seconds_precision optionally specifies the number of digits in the fractional part of the SECOND datetime field and can be a number in the range 0 to 9. The default is 6. For example, you might specify TIMESTAMP(0) WITH TIME ZONE as a literal as follows:

TIMESTAMP '1997-01-31 09:26:50+02.00'

UNSIGNED INT

The external datatype UNSIGNED INT is used for unsigned binary integers. The size in bytes is operating system dependent. The host system architecture determines the order of the bytes in a word. If the number being output from Oracle is not an integer, the fractional part is discarded, and no error is returned. If the number to be returned exceeds the capacity of an unsigned integer for the operating system, Oracle returns an overflow on conversion error.

VARCHAR

The external datatype VARCHAR store character strings of varying length. The first two bytes contain the length of the character string, and the remaining bytes contain the actual string. The specified length of the string in a bind or a define call must include the two length bytes, meaning the largest VARCHAR string is 65533 bytes long, not 65535. For converting longer strings, use the LONG VARCHAR external datatype.

VARCHAR2

The external datatype VARCHAR2 is a variable-length string of characters up to 4000 bytes.

VARNUM

The external datatype VARNUM is similar to the external datatype NUMBER, except that the first byte contains the length of the number representation. This length value does not include the length byte itself. Reserve 22 bytes to receive the longest possible VARNUM. You must set the length byte when you send a VARNUM value to the database.

VARRAW

The external datatype VARRAW is similar to the external datatype RAW, except that the first two bytes contain the length of the data. The specified length of the string in a bind or a define call must include the two length bytes. So the largest VARRAW string that can be received or sent is 65533 bytes, not 65535. For converting longer strings, use the LONG VARRAW datatype.

NATIVE DOUBLE

This external datatype implements the IEEE 754 standard double-precision floating point datatype. It is represented in the host system's native floating point format. The datatype is stored in the Oracle Server in a byte comparable canonical format, and requires 8 bytes for storage, including the length byte. It is an alternative to Oracle NUMBER and has the following advantages over NUMBER:

• Fewer bytes used in storage

• Matches datatypes used by RDBMS Clients

• Supports a wider range of values used in scientific calculations.

NATIVE FLOAT

This external datatype implements the IEEE 754 single-precision floating point datatype. It is represented in the host system's native floating point format. The datatype is stored in the Oracle Server in a byte comparable canonical format, and requires 4 bytes for storage, including the length byte. It is an alternative to Oracle NUMBER and has the following advantages over NUMBER:

• Fewer bytes used in storage

• Matches datatypes used by RDBMS Clients

• Supports a wider range of values used in scientific calculations