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

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);