Representing qualifications with structures
Many tasks in BMC Remedy 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 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.
Structures that represent any qualification--ARQualifierStruct
Structures that represent any qualification--ARFieldValueOrArithStruct
You can also use the following functions to manipulate ARQualifierStruct
:
ARDecodeARQualifierStruct
— Converts information in a serialized qualification string into anARQualifierStruct
structure.AREncodeARQualifierStruct
— Converts anARQualifierStruct
structure into a serialized qualifier string.
The ARQualifierStruct
structure has the following elements:
Operation |
Integer that specifies the type of conditional operation to perform (see the following table). |
Operands |
Components of the operation (represented by structures appropriate to the type of value). |
0 |
AR_COND_OP_NONE |
No qualification. |
1 |
AR_COND_OP_AND |
A qualification using the AND operator. |
2 |
AR_COND_OP_OR |
A qualification using the OR operator. |
3 |
AR_COND_OP_NOT |
A qualification using the NOT operator. |
4 |
AR_COND_OP_REL_OP |
A qualification using a relational operator. |
5 |
AR_COND_OP_FROM_FIELD |
A qualification located in a field on the schema. |
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:
Operation |
Integer that specifies the type of relational operation to perform (see the following table). |
Operands |
Components of the operation (represented by |
1 |
AR_REL_OP_EQUAL |
Tests whether the left operand is equal to the right operand. |
2 |
AR_REL_OP_GREATER |
Tests whether the left operand is greater than the right operand. |
3 |
AR_REL_OP_GREATER_EQUAL |
Tests whether the left operand is greater than or equal to the right operand. |
4 |
AR_REL_OP_LESS |
Tests whether the left operand is less than the right operand. |
5 |
AR_REL_OP_LESS_EQUAL |
Tests whether the left operand is less than or equal to the right operand. |
6 |
AR_REL_OP_NOT_EQUAL |
Tests whether the left operand is not equal to the right operand. |
7 |
AR_REL_OP_LIKE |
Tests whether the left operand is LIKE the pattern defined by the right operand. |
Defining operands for a relational operation
The ARFieldValueOrArithStruct
structure represents the values to compare in a relational operation. This structure has the following elements:
Tag |
Integer that specifies the type of value (see the following table). |
Value |
Value to compare (represented by data types or structures appropriate to the type of value). |
1 |
AR_FIELD |
Schema field value. |
2 |
AR_VALUE |
Constant or keyword value represented by |
3 |
AR_ARITHMETIC |
Result value from an arithmetic operation represented by |
4 |
AR_STAT_HISTORY |
Value from the Status-History core field represented by |
5 |
AR_VALUE_SET |
List of values to set. |
6 |
AR_CURRENCY_FLD |
Schema currency field value represented by |
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:
Operation |
Integer that specifies the type of arithmetic operation to perform (see the following table). |
Operands |
Components of the operation (represented by |
1 |
AR_ARITH_OP_ADD |
Add the left and right operands. |
2 |
AR_ARITH_OP_SUBTRACT |
Subtract the right operand from the left operand. |
3 |
AR_ARITH_OP_MULTIPLY |
Multiply the left and right operands. |
4 |
AR_ARITH_OP_DIVIDE |
Divide the left operand by the right operand. |
5 |
AR_ARITH_OP_MODULO |
Find the remainder after dividing the left operand by the right operand. |
6 |
AR_ARITH_OP_NEGATE |
Change the sign of the right operand (left operand is ignored). |
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:
|
Enumerated value that specifies the status value to use in the operation. |
|
Integer that specifies which information about the specified status to use (see the following table). |
1 |
AR_STAT_HISTORY_USER |
User who assigned the specified status. |
2 |
AR_STAT_HISTORY_TIME |
Time that the status was assigned. |
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:
|
Internal ID of the currency field (for information about field IDs, see Finding fields by label, name, or ID). |
|
Integer that specifies the type of currency part (see the following table). |
|
Character string containing the currency code if the Part Tag element is set to |
0 |
AR_CURRENCY_PART_FIELD |
Entire currency field. |
1 |
AR_CURRENCY_PART_VALUE |
Numeric currency value. |
2 |
AR_CURRENCY_PART_TYPE |
Currency code associated with the currency value. |
3 |
AR_CURRENCY_PART_DATE |
Currency conversion date. |
4 |
AR_CURRENCY_PART_FUNCTIONAL |
One of the defined functional currencies. |
Comments
Log in or register to comment.