GetChunk Method

Applies To

OField

Description

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

Usage

oresult GetChunk(const char **chunkp, long offset, unsigned short numbytes)

oresult GetChunk(const char **chunkp, long offset, unsigned short numbytes,

unsigned short *bytesread) const;

oresult GetChunk(const void **chunkp, long offset, unsigned short numbytes,

unsigned short *bytesread) 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 simply get the piece that you need (if you only need a piece). GetChunk allows you to fetch only a portion of a long field.

The data is read into a memory buffer that is owned by the OField object. Chunkp is set to point at that memory buffer. The caller should not free what chunkp is pointing at; OField manages the memory. The memory will be freed when the OField object is destroyed, when another GetChunk call is made to the same OField object, or when a character string is returned by way of a (const char *) cast of the OField object.

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