ctFindFirstEx

Performs the same as ctFindFirst, but with an additional new argument. Searches for the first object in the specified table, device, trend, or alarm data which satisfies the filter string. A handle to the found object is returned via pObjHnd. The object handle is used to retrieve the object properties. To find the next object, call the ctFindNext function with the returned search handle.

If you experience server performance problems when using ctFindFirst() refer to CPULoadCount and CpuLoadSleepMS.

If ctFindFirst is called instead of ctFindFirstEx, the szCluster defaults to NULL.Syntax

ctFindFirstEx(hCTAPI, szTableName, szFilter, szCluster, pObjHnd, dwFlags)

hCTAPI

Type: Handle
Input/output: Input
Description: The handle to the CTAPI as returned from ctOpen().

szTableName

Type: LPCTSTR
Input/output: Input
Description: The table, device, trend, or alarm data to be searched. The following tables and fields can be searched using ctGetProperty.

Trend - Trend Tags

CLUSTER, TAG, RAW_ZERO, RAW_FULL, ENG_ZERO, ENG_FULL, ENG_UNITS, COMMENT, SAMPLEPER, TYPE, ACQERROR, HISTORIAN, EQUIPMENT, EXPRESSION, ITEM, FORMAT, STORMETHOD

DigAlm - Digital Alarm Tags

CLUSTER, TAG, NAME, DESC, HELP, CATEGORY, STATE, TIME, DATE, AREA, ALMCOMMENT, EQUIPMENT, ACQERROR, HISTORIAN, ITEM, CUSTOM1, CUSTOM2, CUSTOM3, CUSTOM4, CUSTOM5, CUSTOM6, CUSTOM7, CUSTOM8

AnaAlm - Analog Alarm Tags

CLUSTER, TAG, NAME, DESC, HELP, CATEGORY, STATE, TIME, DATE, AREA, VALUE, HIGH, LOW, HIGHHIGH, LOWLOW, DEADBAND, RATE, DEVIATION, ALMCOMMENT, EQUIPMENT, ACQERROR, HISTORIAN, ITEM, CUSTOM1, CUSTOM2, CUSTOM3, CUSTOM4, CUSTOM5, CUSTOM6, CUSTOM7, CUSTOM8

AdvAlm - Advanced Alarm Tags

CLUSTER, TAG, NAME, DESC, HELP, CATEGORY, STATE, TIME, DATE, AREA, ALMCOMMENT, EQUIPMENT, ACQERROR, HISTORIAN, ITEM, CUSTOM1, CUSTOM2, CUSTOM3, CUSTOM4, CUSTOM5, CUSTOM6, CUSTOM7, CUSTOM8

HResAlm - Time-Stamped Alarm Tags

CLUSTER, TAG, NAME, DESC, HELP, CATEGORY, STATE, TIME, MILLISEC, DATE, AREA, ALMCOMMENT, EQUIPMENT, ACQERROR, HISTORIAN, ITEM, CUSTOM1, CUSTOM2, CUSTOM3, CUSTOM4, CUSTOM5, CUSTOM6, CUSTOM7, CUSTOM8

ArgDigAlm - Argyle Digital (Multi-digital) Alarm Tags

CLUSTER, TAG, NAME, DESC, HELP, CATEGORY, STATE, TIME, DATE, AREA, ALMCOMMENT, PRIORITY, STATE_DESC, OLD_DESC, EQUIPMENT, ACQERROR, HISTORIAN, ITEM, CUSTOM1, CUSTOM2, CUSTOM3, CUSTOM4, CUSTOM5, CUSTOM6, CUSTOM7, CUSTOM8

ArgAnaAlm - Argyle Analog Alarm Tags

CLUSTER, TAG, NAME, HELP, ALMCOMMENT, CATEGORY, STATE, TIME, DATE, AREA, VALUE, PRIORITY, HIGH, LOW, HIGHHIGH, LOWLOW, DEADBAND, RATE, DEVIATION, EQUIPMENT, ACQERROR, ITEM, CUSTOM1, CUSTOM2, CUSTOM3, CUSTOM4, CUSTOM5, CUSTOM6, CUSTOM7, CUSTOM8

TsDigAlm - Time-Stamped Digital Alarm Tags

CLUSTER, TAG, NAME, DESC, HELP, CATEGORY, STATE, TIME, DATE, AREA, ALMCOMMENT, EQUIPMENT, ACQERROR, HISTORIAN, ITEM, CUSTOM1, CUSTOM2, CUSTOM3, CUSTOM4, CUSTOM5, CUSTOM6, CUSTOM7, CUSTOM8

TsAnaAlm - Time-Stamped Analog Alarm Tags

CLUSTER, TAG, NAME, DESC, HELP, CATEGORY, STATE, TIME, DATE, AREA, VALUE, HIGH, LOW, HIGHHIGH, LOWLOW, DEADBAND, RATE, DEVIATION, ALMCOMMENT, EQUIPMENT, ACQERROR, HISTORIAN, ITEM, CUSTOM1, CUSTOM2, CUSTOM3, CUSTOM4, CUSTOM5, CUSTOM6, CUSTOM7, CUSTOM8

ArgDigAlmStateDesc - Argyle Digital (Multi-digital) Alarm Tag State Descriptions

CLUSTER, TAG, STATE_DESC0, STATE_DESC1, STATE_DESC2, STATE_DESC3, STATE_DESC4, STATE_DESC5, STATE_DESC6, STATE_DESC7, EQUIPMENT, HISTORIAN, ITEM, CUSTOM1, CUSTOM2, CUSTOM3, CUSTOM4, CUSTOM5, CUSTOM6, CUSTOM7, CUSTOM8

DoublePointAlarm - Double Point Status Alarm

CLUSTER, TAG, NAME, DESC, HELP, CATEGORY, STATE, TIME, DATE, AREA, ALMCOMMENT, PRIORITY, STATE_DESC, OLD_DESC, EQUIPMENT, ACQERROR, HISTORIAN, ITEM, CUSTOM1, CUSTOM2, CUSTOM3, CUSTOM4, CUSTOM5, CUSTOM6, CUSTOM7, CUSTOM8

DoublePointAlarmStateName - Double Point Status Alarm State Name

CLUSTER, TAG, STATE_DESC0, STATE_DESC1, STATE_DESC2, STATE_DESC3, STATE_DESC4, STATE_DESC5, STATE_DESC6, STATE_DESC7, EQUIPMENT, HISTORIAN, ITEM, CUSTOM1, CUSTOM2, CUSTOM3, CUSTOM4, CUSTOM5, CUSTOM6, CUSTOM7, CUSTOM8

Alarm - Alarm Tags

CLUSTER, TAG, NAME, DESC, HELP, CATEGORY, STATE, TIME, DATE, AREA, ALMCOMMENT, VALUE, HIGH, LOW, HIGHHIGH, LOWLOW, DEADBAND, RATE, DEVIATION, PRIORITY, STATE_DESC, OLD_DESC, ALARMTYPE, EQUIPMENT, ACQERROR, HISTORIAN, ITEM, CUSTOM1, CUSTOM2, CUSTOM3, CUSTOM4, CUSTOM5, CUSTOM6, CUSTOM7, CUSTOM8

AlarmSummary - Alarm Summary

CLUSTER, TAG, NAME, DESC, HELP, CATEGORY, TIME, DATE, AREA, VALUE, HIGH, LOW, HIGHHIGH, LOWLOW, DEADBAND, RATE, DEVIATION, PRIORITY, ALARMTYPE, ONDATE, ONDATEEXT, ONTIME, ONMILLI, OFFDATE, OFFDATEEXT, OFFTIME, OFFMILLI, DELTATIME, ACKDATE, ACKDATEEXT, ACKTIME, ALMCOMMENT, USERNAME, FULLNAME, USERDESC, SUMSTATE, SUMDESC, NATIVE_SUMDESC, COMMENT, NATIVE_COMMENT, EQUIPMENT, HISTORIAN, ITEM, CUSTOM1, CUSTOM2, CUSTOM3, CUSTOM4, CUSTOM5, CUSTOM6, CUSTOM7, CUSTOM8

AlarmSOE - Alarm Sequence Of Events

CLUSTER, TAG, NAME, DESC, HELP, CATEGORY, TIME, DATE, AREA, HIGH, LOW, HIGHHIGH, LOWLOW, DEADBAND, RATE, DEVIATION, PRIORITY, ALARMTYPE, ALMCOMMENT, FULLNAME, SUMSTATE, SUMDESC, NATIVE_SUMDESC, EQUIPMENT, HISTORIAN, ITEM, CUSTOM1, CUSTOM2, CUSTOM3, CUSTOM4, CUSTOM5, CUSTOM6, CUSTOM7, CUSTOM8, USERNAME, USERLOCATION

Accum - Accumulators

PRIV, AREA, CLUSTER, NAME, TRIGGER, VALUE, RUNNING, STARTS, TOTALISER

Equip – Equipment

CLUSTER, NAME, IODEVICE, AREA, LOCATION, SCHEDULED, DEFSTATE, COMMENT, CUSTOM1, CUSTOM2, CUSTOM3, CUSTOM4, CUSTOM5, CUSTOM6, CUSTOM7, CUSTOM8, COMPOSITE, PARENT, PAGE, HELP, REFERENCE, DEVSCHED, SCHEDID

EquipState – Equipment State

CLUSTER, NAME, EQUIPMENT, PERIOD, DELAY, PRIORITY, DESCRIPTION, DRMODE

EquipRef – Equipment Reference

CLUSTER, EQUIP, REFCLUST, REFEQUIP, REFITEM, CATEGORY, ORDER, COMMENT, CUSTOM1, CUSTOM2, CUSTOM3, CUSTOM4, CUSTOM5, CUSTOM6, CUSTOM7, CUSTOM8

Tag - Variable Tags

TAG, RAW_ZERO, RAW_FULL, ENG_ZERO, ENG_FULL, ENG_UNITS, COMMENT, TYPE, CLUSTER, FULLNAME, IODEV, ADDR, DEADBAND, LOG_UNIT, NET_UNIT, EQUIPMENT, ITEM, HISTORIAN, OVR_MODE, CTRL_MODE, NUM_SUBS, CUSTOM1, CUSTOM2, CUSTOM3, CUSTOM4, CUSTOM5, CUSTOM6, CUSTOM7, CUSTOM8, ARR_SIZE, BIT_WIDTH, FORMAT

Cluster - Clusters

NAME, COMMENT, ACTIVE

Server

NAME, TYPE, COMMENT, CLUSTER, MODE, NETADDR, PORT, LEGACYPORT

Schedule_Config - Schedule Configuration

ID, EQUIPMENT, STATE, START, OCCURRENCESTART, END, OCCURRENCEEND, DESC, MODIFIEDTIME, FREQ, INTERVAL, WEEKDAY, WEEKDAYMASK, MAXREC, RECUNTIL, DAYORD, DAY, MONTH, SPECIALINC, GROUPIDS, RESOURCETYPE, SOURCEVALUE, SOURCEID

Schedule_Runtime - Schedule Runtime

EQUIPMENT, STATE, START, END, INHERITED, DESC, RESOURCETYPE, SOURCEVALUE, SOURCEID

Schedule_Special_Group - Schedule Special Group

NAME, ID, RESOURCE, CHILDRESOURCES

Schedule_SpecialItem - Schedule Special Item

ID, NAME, DAY, GROUPNAME, GROUPID

Note: The migration tool in Plant SCADA 2023 converts memory PLC variables to local variable tags which are in a separate table to the variable tags. Calling ctFindFirst with szTableName "Tag" will not return the local variable tags. In order to return the local variable tags you need to call ctFindFirst with the szTableName of "LocalTag". Local variables do not have clusters and have only one pair of zero/full scales (as opposed to raw and engineering scales for variable tags).

LocalTag - The field names for local variable tags are:

NAME, TYPE, ASIZE (array size), ZERO, FULL, UNITS, COMMENT, FORMAT.

The array size field is only available for local tags.

szFilter

Type: LPCTSTR
Input/output: Input
Description: Filter criteria. This is a string based on the following format:

"PropertyName1=FilterCriteria1;PropertyName2=FilterCriteria2"\.

The wildcard * may be used as part of the filter criteria to match multiple entries. Use an empty string, or "*" as the filter string to match every entry.

You can use this parameter to reduce the amount of data being retrieved if system performance is impacted. For example, you can filter on the DATE field using the following:

DATE > 1750644330

The date should be provided as a UTC epoch timestamp (the number of seconds since UTC midnight, 1 January 1970).

szCluster

Type: LPCTSTR
Input/output: Input
Description: Specifies on which cluster the ctFindFirst function will be performed. This can be left empty (null) for a single cluster system. In this case, ctFindFirst will be performed on the active cluster. In a system with multiple clusters, you need to specify a cluster.

pObjHnd

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

dwFlags

This argument is no longer used, pass in a value of 0 for this argument.

To search a table:

• In szTableName specify the name of the table.

To search a device:

• In szTableName specify the name as defined in the Plant SCADA Devices form, for example "RECIPES" for the Example project.

To search trend data:

• In szTableName specify the trend using the following format (including the quotation marks):

  'TRNQUERY,Endtime,EndtimeMs,Period,NumSamples,Tagname,Displaymode,Datamode'

  See TrnQuery for syntax details.

To search alarm data:

• In szTableName specify the alarm data using the following format (including the quotation marks):

  'ALMQUERY,Database,TagName,Starttime,StarttimeMs,Endtime,EndtimeMs,Period'

  See AlmQuery for syntax details.

Return Value

If the function succeeds, the return value is a search handle used in a subsequent call to ctFindNext() or ctFindClose(). If the function does not succeed, the return value is NULL. To get extended error information, call GetLastError().

Related Functions

ctOpen, ctFindNext, ctFindClose, ctGetProperty, ctFindFirst