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`