6.50 LceRequestSelect

This function is used to identify one or more records matching the search criteria, from a file on a host.

BOOL	LceRequestSelect	(int	iSession,
		char far *	strFieldList,
		char far *	strFileName,
		char far *	strKeyList,
		BOOL	fGeneric )

  

Parameters

iSession	The session identifier returned by LceGetSessionId.
strFieldList	A list of fields to be retrieved from the file. Each field listed must have been declared using an LceUseField function.
strFileName	The name of the file to be used. This file must have been declared using an LceUseFile function
strKeyList	A list of the key field names in the sequence in which they are used in the file. These fields must have been declared using the LceUseField function. The values for the keys are set using the LceSetFieldValue/LceSetFieldValueU function. Refer to Notes for key and generic search considerations. Key fields must not be specified if the *BLOCKBYKEY option was used in the preceding LceSetSelectOptions.
fGeneric	Refer to notes for further information. True = apply a generic search. False = do not apply a generic search.

  

Return Values

TRUE is returned if the session has selected records.

FALSE is returned if an error occurs.

Notes

Key and Generic search considerations:

• You must know the specific key fields to the file. The key fields listed can be a subset of the actual keys to the file, but the sequence in which the keys are listed must match the sequence of the keys in the file. This is very important. The sequence of the keys must match the file. If you need the keys in a different sequence you must use a logical file.

• The fGeneric flag determines whether the keys must match exactly or whether a generic key search should apply. If a generic search is used on a file with more than one key field, then the search will apply only to the last non-blank key field specified. Any blank key field will be considered generic.

• The fGeneric flag is ignored for fields of type Date, Time, DateTime, Integer, and Float.

• You do not have to use the complete key list. You could use the first two fields in a file with three key fields. If you use a subset of the key fields, you are implicitly using a generic search on the unspecified keys, i.e. match key1 and key2 while key3 can have any value. In this case, you do not use the fGeneric search. If you did use the generic search in this situation, you will get a generic search based on key2 and key3.

This LceRequestSelect function is used with a number of other select processing functions. The general pattern of these functions is as follows:

• LceSetSelectOptions sets the selection search characteristics.

• LceRequestSelect selects records on the host.

• LceReceiveSelect transfers the records from the host to the PC.

• LceGetRecordCount determines how many records were transferred.

• LceGetSelect retrieves a single record from the group of records transferred.

• This function may only be executed after a session has been opened.

Tip

For a better performance when retrieving records, use the LceRequestSelect and LceReceiveNextX functions with the select option set to *RECEIVEIMMED.

Related Functions

6.64 LceSetSelectOptions

6.50 LceRequestSelect

6.51 LceRequestSelectWhere

6.48 LceReceiveNextX

6.37 LceGetRecordCount

6.38 LceGetSelect

6.53 LceSelect

6.11 LceDeleteSelect