ctFindScroll

Scrolls to the necessary object in the search initiated by ctFindFirst.

To find the current scroll pointer, you can scroll relative (dwMode = CT_FIND_SCROLL_RELATIVE) with an offset of 0. To find the number of records returned in a search, scroll to the end of the search.

Syntax

ctFindScroll(hnd, dwMode, dwOffset, pObjHnd)

hnd

Type: Handle
Input/output: Input
Description: Handle to the search, as returned by ctFindFirst().

dwMode

Type: DWORD
Input/output:
Description: Mode of the scroll. The following modes are supported:

CT_FIND_SCROLL_NEXT: Scroll to the next record. The dwOffset parameter is ignored.

CT_FIND_SCROLL_PREV: Scroll to the previous record. The dwOffset parameter is ignored.

CT_FIND_SCROLL_FIRST: Scroll to the first record. The dwOffset parameter is ignored.

CT_FIND_SCROLL_LAST: Scroll to the last record. The dwOffset parameter is ignored.

CT_FIND_SCROLL_ABSOLUTE: Scroll to absolute record number. The record number is specified in the dwOffset parameter. The record number is from 1 to the maximum number of records returned in the search.

CT_FIND_SCROLL_RELATIVE: Scroll relative records. The number of records to scroll is specified by the dwOffset parameter. If the offset is positive, this function will scroll to the next record, if negative, it will scroll to the previous record. If 0 (zero), no scrolling occurs.

dwOffset

Type: LONG
Input/output: Input
Description: Offset of the scroll. The meaning of this parameter depends on the dwMode of the scrolling operation.

pObjHnd

Type: HANDLE
Input/output: Output
Description: The pointer to the found object handle. This is used to retrieve the properties.

pObjHnd

Type: HANDLE
Input/output: Output
Description: The pointer to the found object handle. This is used to retrieve the properties.

Return Value

If the function succeeds, the return value is non-zero. If the function does not succeed, the return value is zero. To get extended error information, call GetLastError(). If no matching objects can be found, the GetLastError() function returns CT_ERROR_NOT_FOUND. The return value is the current record number in the search. Record numbers start at 1 (for the first record) and increment until the end of the search has been reached. Remember, 0 (zero) is not a valid record number - it signifies that the function was not successful.

Related Functions

ctOpen, ctFindFirst, ctFindNext, ctFindPrev, ctFindClose, ctGetProperty

Example

HANDLE	hSearch;

HANDLE	hObject;

DWORD	dwNoRecords;

// Search the Tag table

hSearch = ctFindFirst(hCTAPI, "Tag", NULL, &hObject, 0);

// Count number of records

dwNoRecords = ctFindScroll(hSearch, CT_FIND_SCROLL_LAST, 0, &hObject);

// scroll back to beginning

ctFindScroll(hSearch, CT_FIND_SCROLL_FIRST, 0, &hObject);

do {

		char	sName[32];

		// Get the tag name
		ctGetProperty(hObject, "Tag", sName, sizeof(sName), NULL, DBTYPE_STR);

} while (ctFindScroll(hSearch, CT_FIND_SCROLL_NEXT, 0, &hObject));

ctFindClose(hSearch);