uaddhit

Adds an entry to the Uniface hitlist, or updates an existing one.

void uaddhit(uc, pra, pralen, pk, pklen, ord, ordlen)

struct uctrl *uc;

unsigned char *pra, *pk, *ord;

short pralen, pklen, ordlen;

Parameters

  • uc—address of the current control block.
  • pra—address of a buffer containing the physical row address.
  • pralen—length of the physical row address pointed to by pra. Zero means no physical row address is available.
  • pk—address of a buffer containing the concatenated primary key.
  • pklen—length of the primary key pointed to by pk. Zero means that the primary key is not available, or not yet available.
  • ord—address of a buffer containing the sort data. This parameter only needs to be supplied with a field-level DBMS which is not capable of sorting the data itself, and only when ordering is requested in the Select request. The sort data must be concatenated according to the sort specification in the ordlst structure.
  • ordlen—length of the sort data pointed to by ord. Zero means that no sort data is supplied to Uniface in the Select connector request.

    In other connector requests, ordlen must be -1.

Note:  pralen and pklen cannot both be zero.

Description

Adds an entry to the Uniface hitlist, or updates an existing one. Only the primary key fields or the physical row address, or both, are added to the hitlist.

If the connector sets uctrl->uonum to 0 in the Select mode 0 request to indicate that the DBMS can sort records itself, the connector must add hits in the requested order.

The ubldprm or ubldprim service functions can be used to build the concatenated primary key.

The ord and ordlen parameters are not usually supplied to Uniface. Most field-level DBMSs are capable of sorting the data. With record-level DBMSs there is no need to use ord and ordlen, since Uniface uses the record data in the general I/O buffer to construct the sort data when necessary.

This example fetches records from an SQL-based DBMS using a descriptor area (SQLDA). When no select cache is used, the uaddhit service function is used to return the primary key, or the PRA, or both to UNIFACE.

The following functions are called in the example:

  • EmbeddedFetch—Fetch the next record from the specified (open) cursor and update the values in SQLDA.
  • NoRecordCache—Determine whether the select cache needs to be used.
  • BindKeys—Update the control block with lengths of actual fetched data for key fields.
  • BindAllFields—Update the control block with lengths of actual fetched data for all fields.

This example uses the CursorIdType and SQLDA data structures, depending on the API of the DBMS used. The DrvAdminType data structure is created for this example, and holds the PRA in its PRA field. Such a structure would usually be stored in the connector workspace (uctrl->udrv). 

FetchRecordsAndReturnThemToUNIFACE
( struct uctrl *ControlBlock,
CursorIdType CursorId,
DrvAdminType *ConnectorAdministration )
{
BooleanType ReturnValue;
SQLDA *Sqlda;
short StepsToDo = ControlBlock->umaxhits;
do
{
/* Fetch record from cursor. */
ReturnValue = EmbeddedFetch ( CursorId, Sqlda );
if ( ReturnValue )
{
if ( NoRecordCache ( ControlBlock ) )
/* ControlBlock->ucache == 0 */
{
/* Update UNIFACE"s knowledge of actual fetched */
/* primary keys and PRAs. */
BindKeys ( ControlBlock, Sqlda );
ubldprm ( ControlBlock, ( short ) 0 );
uaddhit ( ControlBlock,
DrvAdministration->PRA,
ControlBlock->uralen,
&ControlBlock->sqlbuf[ 1000 ],
ControlBlock->uprimlen,
( unsigned char * ) 0,
( short ) 0 );
}
else
{
/* Update UNIFACE"s knowledge of all actual fetched */
/* fields, because record cache is turned on. */
BindAllFields ( ControlBlock, Sqlda );
ubldprm ( ControlBlock, ( short ) 0 );
uaddrec ( ControlBlock,
DrvAdministration->PRA,
ControlBlock->uralen,
&ControlBlock->sqlbuf[ 1000 ],
ControlBlock->uprimlen,
( unsigned char * ) 0,
( short ) 0 );
}
}
StepsToDo--;
}
while ( ReturnValue && StepsToDo );
}