GetFieldChunk Method

Applies To

ODynaset

Description

This method fetches a piece of a long or long raw field.

Usage

oresult GetFieldChunk(int index, void *chunkp, long offset, unsigned short numbytes) const

oresult GetFieldChunk(const char *fieldname, void *chunkp, long offset, unsigned short numbytes) const

Arguments	Description
index	The 0-based index of the field. The index is the position of the field in the SQL query that created the current record set.
fieldname	The name of the field as expressed in the SQL query.
chunkp	Pointer to buffer to be filled with data.
offset	Offset into the long field.
numbytes	The number of bytes to get out of the long field.

Remarks

Long and long raw fields in an Oracle database can hold a very large amount of information. You may not want to download all of the data from such a field to your client workstation. It is more efficient to get the piece that you need (if you only need a piece). GetFieldChunk enables you to fetch only a portion of a long field.

The data is read into a memory buffer that is provided by the caller. The caller is responsible for ensuring that the buffer is long enough to hold the number of bytes that is asked for. GetFieldChunk does not null-terminate the returned data (it is possible that the data is not text).

This method is valid only on fields whose server type is OTYPE_LONG or OTYPE_LONGRAW.

Return Value

An oresult indicating whether the operation succeeded (OSUCCESS) or not (OFAILURE).

Example

Consider an application where large documents are stored in long fields in an Oracle database. The documents may have excerpts marked on them that are interesting. This example retrieves a single clause from a contract that is stored in a long field.

// open the contracts database

ODatabase contrdb("p:legalserver", "solicitor", "murbles");

// get a dynaset on the clause information for clause "a1"

ODynaset clausedyn; // construct unopened dynaset

// now open it

clausedyn.Open(contrdb, "select * from clauses where cname = "a1");

// what's the contract number for that?

int contractnum;

clausedyn.GetFieldValue("cnumber", &contractnum);

/*

Set up a parameter on the database. Give it the value of the contract number we want. (In a real application this parameter would already be around).

*/

contrdb.GetParameters().Add("cnum", contractnum,

OPARAMETER_INVAR, OTYPE_NUMBER);

// get a dynaset on the contracts, selecting the contract we want

ODynaset cdyn(contrdb, "select * from contracts where cnumber = :cnum");

// and an OField on the contract text field

OField contractf = cdyn.GetField("ctext");

// what's the offset and length of that contract clause?

long clauseoffset;

long clauselen;

clausedyn.GetFieldValue("coffset", &clauseoffset);

claysedyn.GetFieldValue("clen", &clauselen);

// get the text

const char *clausetext;

contractf.GetChunk(&clausetext, clauseoffset, clauselen);