Cicode Programming Reference > Cicode Function Categories > Alarm Functions Introduction > AlarmSetQuery

AlarmSetQuery

Allows you to choose which alarms display on a page, by calling a user-defined query function to filter the alarms on specific criteria. The query function is called for each alarm, and only alarms matching the criteria are displayed on the page. AlarmSetQuery() only runs on the alarm server and returns to the display client. If you call a query function inAlarmSetQuer from a display then this function needs to exist in the project on the alarm server.

There are two steps involved in using a query to display alarms:

  1. Write the Cicode function that will be used as the query function.
  2. Specify the query function and its arguments in a call to AlarmSetQuery().

  3. Note: You can also use AlarmSetQuery() to remove filtering from an alarm list. AlarmSetQuery( -1, "", "" ) stops the query function filtering the display of alarms.

Syntax

AlarmSetQuery(AN, QueryFunction [, sArgs] [, iAlways] )

AN:

The AN where the alarm list originally commenced. (AN alarm page can contain more than one alarm list). You can also specify:

-1 - Change the display parameters of every alarm list displayed on the page.

0 - Change the display parameters of the alarm list where the cursor is positioned.

QueryFunction:

The name of the Cicode query function written by the user. Once this function has been specified, it is called for each alarm, and determines whether or not the alarm should be displayed.

The QueryFunction returns an INT value of 1 (TRUE) or 0 (FALSE). If a value of TRUE is returned, the alarm will be displayed. If the query function returns FALSE, the alarm will be ignored and not displayed.

The query function's first parameter needs to be an INT. This parameter is initialized with the record ID of the current alarm, providing the query function with information about the alarm.

The query function's second parameter needs to also be an INT. It represents the instance or event of an alarm, and is used in filtering the alarms for display.

sArgs:

A list of arguments to be passed to the Cicode query function. The arguments are enclosed by double quotes ("") and separated by commas. This parameter is optional. If the query function does not require parameters other than the default INT parameter, then the list of arguments may be left out as follows:

AlarmSetQuery(0, "AlarmQueryDate");

In this case, the default value of an empty string will be used for the third parameter.

If the query function requires values to be passed in by the user, the following rules apply to determine the types of arguments:

For example, to pass an INT of 23, a string of "23/12/1999", and a REAL value of 23.45 to the query function MyQueryDate(), AlarmSetQuery() should be invoked in the following way:

AlarmSetQuery(0, "MyQueryDate", "23, ^"23/12/1999^", 23.45");

The query function MyQueryDate() would be defined as follows:

INT

FUNCTION

MyQueryDate(INT nRID, INT nVer, INT iOne, STRING sOne, REAL rOne)

   ..

		..

END

The types of the arguments listed in AlarmSetQuery() should match the types of the arguments defined in the query function.

iAlways:

Set to TRUE to so that the query is performed whenever it is called (no optimization). Default value is 0 (FALSE).

Return Value

0 (zero) if successful, otherwise an error is returned.

Related Functions

AlarmGetFieldRec, AlarmSetInfo, QueryFunction

Example

!Sets MyQueryDate() as the query function and provides the
arguments 23, 23/12/1999, and 23.45

AlarmSetQuery(0, "MyQueryDate", "23, ^"23/12/1999^", 23.45");

!Removes filtering by the current query function from all alarm
lists on the page

AlarmSetQuery(-1, "", "");

See Also

Alarm Functions