uwhrlst

Contains the preferred index information or the physical row address.

Description

In previous versions, Uniface supported an array of uwhrlst structures (that is, the where structure). Only the first uwhrlst structure is supported, as described below.

With some connector requests, Uniface identifies a record or a set of records to which the request applies. If the DBMS is capable of making the selection, the connector must use the if list. This is typically the case with SQL-like databases. The if list is described in the uiflst structure. If the DBMS is not capable of making the selection, the connector must use the where structure. This specifies a PRA or the preferred index and the key value to start with. The connector must then select records using this index, and call the service requests uhitchk and uready. This technique is typically used with refcor-level DBMSs.

The connector can access the where structure by means of the address in uctrl->uwlist.

Members

uwhrlst Members
Member Description
short ufnr If zero, the uwhrlst structure identifies exactly one record by means of the physical row address which is available at the position indicated by the field uwdat. In this case, the connector can call uaddhit or uaddrec without performing a uhitchk.

If less than zero, ufnr is the negated index number of the preferred index (it is negated for downward compatibility reasons).

short uwdat Offset in bytes from uctrl->uwlist to the key value or physical row address.

If uwhrlst->uqual is 0 (‘like’ operator), two character values have a special meaning in the data. The value 1 represents the wildcard ‘*’ (any pattern of any number of characters). The value 2 represents the wildcard ‘?’ (any character).

The values that represent the wildcards can be redefined by setting uinfo->profil[] to nonzero values in the Info connector request.

Note:   Since uctrl->uwlist is of type (struct uwhrlst *), the correct expression in ‘C’ for the address of the data is:

( (char *)(uctrl->uwlist) + uctrl->uwlist->uwdat )

If ufnr is less than zero, the data indicated by uwdat is a concatenated (compound) index key value. The connector can use the index list and field list to access the separate field values in the concatenated key.

short uwlen Actual length of the data or physical row address indicated by the field uwdat.

By definition, a length of zero indicates that the data is the NULL value (missing value). Uniface does not distinguish between the empty field and the NULL value for fields with connector-level packing codes pC, pU and pR. When such a field allows the NULL value (see mask 64 of field ufldlst->ufbits), a length of zero must be interpreted as the NULL value. Otherwise it must be interpreted as an empty field.

unsigned char uqual Comparison operator that limits the set of records to be selected. The value to compare against is indicated by the uwdat element. ufnr identifies the index to compare. Note that the field uquals can modify the comparison.

See the Table A comparison operator.

When the ‘like’ operator is specified, Uniface does not provide a start value in the preferred index and uready does not signal the stop value. In this case, select either the full table, or implement an algorithm to calculate the start and stop values in an index.

unsigned char uquals Modifies the comparison specified in the field uqual. The modifiers are bitmapped. A modifier is applicable if the bitwise AND of the corresponding mask and the value of uquals is nonzero. See the table Examples of Modifiers.
A comparison operator
Value Comparison operator
0 Like (match data with wildcard pattern)
1 <
2 <=
3 =
4 >=
5 >
Examples of modifiers
Mask Modifier
1 Logical not
2 Obsolete
4 Obsolete
8 Compare with NULL value instead of data indicated by uwdat

Related Topics