Representing qualifications with structures

Many tasks in AR System use qualifications. For example, a qualification (or lack thereof) determines which entries to retrieve when creating a query result list (ARGetListEntry) or computing entry statistics (ARGetEntryStatistics).

A qualification also determines which active link or filter actions, if any, are executed and on which entries an escalation acts on.

Every qualification is composed of a set of zero or more conditions that limit the set of entries retrieved. As the following figure shows, ARQualifierStruct uses a tree structure composed of an operation and one or two operands (depending on the type of operation) to represent each individual condition.

The operands can point to other structures of type ARQualifierStruct. This recursion enables you to use a series of nested ARQualifierStruct structures to represent any qualification.

To avoid the complexity of storing a qualification in this structure, use ARLoadARQualifierStruct. This function takes the specified qualification string and loads it into an ARQualifierStruct. If you are comfortable working with the ARQualifierStruct structure or your query is static, you might find that using ARQualifierStruct directly yields improved performance.

Related topics

Developing-an-API-program

Data-structures

Structures that represent any qualification - ARQualifierStruct 
221_DataStruct_ARQualifierStruct.png

Structures that represent any qualification - ARFieldValueOrArithStruct 
221_DataStruct_ARFieldValueOrArithStruct .png

You can also use the following functions to manipulate ARQualifierStruct:

  • ARDecodeARQualifierStruct - Converts information in a serialized qualification string into an ARQualifierStruct structure.
  • AREncodeARQualifierStruct - Converts an ARQualifierStruct structure into a serialized qualifier string.

The ARQualifierStruct structure has the following elements:


If a query has no qualification criteria, you can either set the operation type to zero (AR_COND_OP_NONE) or pass NULL for the qualifier parameter.

Dynamic qualifications

Dynamic qualifications take part of the qualification condition from a field whose contents can change. The part of the qualification in a field uses the AR_COND_OP_FROM_FIELD tag. The value supplied is the ID of the field that contains the qualification.

Qualifications that use conditional operators

Qualifications that use the AND or OR operators require two operands. Qualifications that use the NOT operator require one operand. In both cases, the operands consist of pointers to nested ARQualifierStruct structures.

Qualifications that use relational operators

Qualifications that use a relational operator require one operand consisting of a pointer to an ARRelOpStruct structure. The ARRelOpStruct structure has a tag specifying the operation type and the following operands, which specify the values to compare:


Defining operands for a relational operation

The ARFieldValueOrArithStruct structure represents the values to compare in a relational operation. This structure has the following elements:


Defining an arithmetic result value

ARArithOpStruct represents the result value from an arithmetic operation. Similar to ARRelOpStruct (see Qualifications that use relational operators), this structure has a tag specifying the operation type and two operands specifying the values:


Defining a status history value

The Status History core field is a special selection field that stores user and time stamp information for each of the defined status values. To specify a value for this field, use the ARStatHistoryValue structure. This structure has the following elements:


Defining a currency field part

Currency fields consist of several parts that combine to represent a complete currency value. To specify an individual part from this field type or to reference the entire field, use the ARCurrencyPartStruct structure. This structure has the following elements:


 

Tip: For faster searching, add an asterisk to the end of your partial query. Example: cert*