This documentation applies to the 8.0 version of Remedy Action Request System, which is in "End of Version Support." You will not be able to leave comments.

To view the latest version, select the version from the Product version menu.

Set Fields action and structures

The Set Fields action is one of the most complex of the filter, escalation, or active link actions. The ARFieldAssignList structure (see the following figure) is a list of ARFieldAssignStruct items, each identifying a field/value pair to update. Each ARFieldAssignStruct structure contains the internal ID of the field to update and the value to assign, specified in ARAssignStruct, which is one of the more complex structures in the API.

Structures used to define Set Fields action 

 

The ARAssignStruct structure contains the following elements:

Assign Type

Integer that specifies the type of value to assign (see the following table).

Value

Value to assign (represented by data types or structures appropriate to the type of value).


1

AR_ASSIGN_TYPE_VALUE

Constant or keyword value represented by the structure (see Group information). The data type of the value must match the data type of the specified field.

2

AR_ASSIGN_TYPE_FIELD

Schema field value represented by the structure (see Assigning a schema field value).

3

AR_ASSIGN_TYPE_PROCESS

Output value from successful execution of an operating system process or command. The system generates an error if the process return code is not zero. This option is unavailable for active links on Windows.

4

AR_ASSIGN_TYPE_ARITH

Result value from an arithmetic operation represented by the structure (see Assigning an arithmetic result value).

5

AR_ASSIGN_TYPE_FUNCTION

Return value from a function represented by the structure (see Assigning a function return value).

6

AR_ASSIGN_TYPE_DDE

Result value from a DDE request to another application represented by the structure (see Assigning a DDE result value). This option is available only for active links on Windows clients.

7

AR_ASSIGN_TYPE_SQL

Result value from an SQL command represented by the structure (see Assigning an SQL result value).

8

AR_ASSIGN_TYPE_FILTER_API

Result value from a Filter API command represented by the structure (see Assigning a filter API result value).

Assigning a schema field value

The ARAssignStruct structure contains an ARAssignFieldStruct structure that identifies a schema field value to assign in a Set Fields or Push Fields action. You can specify a value from any entry in any schema on a particular server.

In a Push Fields action, an independent ARAssignFieldStruct structure (see Structures used to define a Push Fields action) identifies the schema field set by the operation. You can specify a field from any entry in any schema on a particular server. To set or push all matching field values from one schema to the other, use AR_LIKE_ID in the field.

The ARAssignFieldStruct structure has the following elements:

Server

String that specifies the name of the server where the schema is located. The function retrieves a list of available servers (see BMC Remedy AR System C API functions). For filters and escalations, specify the server where the filter or escalation is located (either by name or by passing). For active links, specify *** to retrieve the value from the current window.

Schema

Name of the schema containing the field value to assign. For filters and escalations, specify @ to retrieve or set the value from the current transaction. For active links, specify *** to retrieve or set the value from the current window.

Search Criteria

Qualification that identifies the entries to retrieve or set (optional). Specify the search criteria by using ARQualifierStruct (see Structures that represent any qualification--ARQualifierStruct and Structures that represent any qualification--ARFieldValueOrArithStruct).

Tag

Integer that specifies the type of field value to retrieve or set. The following table lists the valid integers.

Field ID/Stat History/Currency

Field containing the value to assign or set. Specify the field by using the field ID, the ARStatHistoryValue structure, or the ARCurrencyPartStruct structure. Use the field identification to set or push matching field values between two schemas. For more information, see Mapping fields to values.

No Match Option

Integer that specifies the action to take if no entries match the search criteria. The following table lists the valid integers.

Multiple Match Option

Integer that specifies the action to take if multiple entries match the search criteria (Set Fields) or if any entry matches the search criteria (Push Fields). The following table lists the valid integers.



Tag values for ARAssignFieldStruct

1

AR_FIELD

Value from a regular schema field.

4

AR_STAT_HISTORY

Value from the Status History core field.

6

AR_CURRENCY_FLD

Value from a currency field.



No Match Option values for ARAssignFieldStruct

1

AR_NO_MATCH_ERROR

Return an error.

2

AR_NO_MATCH_SET_NULL

Assign (Set Fields action only).

3

AR_NO_MATCH_NO_ACTION

Do nothing (Push Fields action only).

4

AR_NO_MATCH_SUBMIT

Submit a new entry (Push Fields action only).



Multiple-Match Option values for ARAssignFieldStruct

1

AR_MULTI_MATCH_ERROR

Return an error

2

AR_MULTI_MATCH_SET_NULL

Assign (Set Fields action only).

3

AR_MULTI_MATCH_USE_FIRST

Assign a value from the first matching entry.

4

AR_MULTI_MATCH_PICKLIST

Display a selection list (Active Links only).

5

AR_MULTI_MATCH_MODIFY_ALL

Modify all matching entries (Push Fields action only).

6

AR_MULTI_MATCH_NO_ACTION

Do nothing (Push Fields action only).

7

AR_MULTI_MATCH_USE_LOCALE

Assign a value from the first matching entry based on the locale (Set Fields action or Active Links only).

Assigning an arithmetic result value

The ARArithOpAssignStruct structure defines an arithmetic result value to assign in a Set Fields action. This structure is similar to the ARArithOpStruct structure and uses the same set of operation values (see Defining an arithmetic result value). Like ARArithOpStruct, ARArithOpAssignStruct has a tag specifying the type of arithmetic operation and two operands specifying the values. In this case, however, the operands are represented by ARAssignStruct instead of ARFieldValueOrArithStruct.

Assigning a function return value

The ARFunctionAssignStruct structure specifies a function return value to assign in a Set Fields action. This structure has the following elements:

Function Type

Integer that specifies the type of function to perform (see the following table).

Number of Parameters

Integer that specifies the number of function input parameters.

Parameter List

Pointer to the parameter values to use (represented in a structure).

For more information about the function type values, see Functions.

Function type values for ARFunctionAssignStruct

Number

Function Type

Input

Return

Value

1

AR_FUNCTION_DATE

timestamp

char

Date

2

AR_FUNCTION_TIME

timestamp

char

Time

3

AR_FUNCTION_MONTH

timestamp

long

Month (1-12)

4

AR_FUNCTION_DAY

timestamp

long

Day (1-31)

5

AR_FUNCTION_YEAR

timestamp

long

Year

6

AR_FUNCTION_WEEKDAY

timestamp

long

Weekday (1-7)

7

AR_FUNCTION_HOUR

timestamp

long

Hour (0-23)

8

AR_FUNCTION_MINUTE

timestamp

long

Minute (0-59)

9

AR_FUNCTION_SECOND

timestamp

long

Second (0-59)

10

AR_FUNCTION_TRUNC

real

long

Truncated value

11

AR_FUNCTION_ROUND

real

long

Rounded value

13

AR_FUNCTION_LENGTH

char

long

Length of string in bytes

14

AR_FUNCTION_UPPER

char

char

Uppercase string

15

AR_FUNCTION_LOWER

char

char

Lowercase string

16

AR_FUNCTION_SUBSTR

char, long [, long]

char

Substring from long1 to long2 (inclusive) in bytes

17

AR_FUNCTION_LEFT

char, long

char

Leftmost n bytes

18

AR_FUNCTION_RIGHT

char, long

char

Rightmost n bytes

19

AR_FUNCTION_LTRIM

char

char

Leading blanks removed

20

AR_FUNCTION_RTRIM

char

char

Trailing blanks removed

21

AR_FUNCTION_LPAD

char, long, char

char

char1 left-padded with char2 to n bytes

22

AR_FUNCTION_RPAD

char, long, char

char

char1 right-padded with char2 to n bytes

23

AR_FUNCTION_REPLACE

char, char, char

char

char1 with char2 replaced by char3

24

AR_FUNCTION_STRSTR

char, char

int

Position of char2 in char1 in bytes (-1 = not found)

25

AR_FUNCTION_MIN

x, x, [, x ] ...

x

Minimum value

26

AR_FUNCTION_MAX

x, x, [, x ] ...

x

Maximum value

27

AR_FUNCTION_COLSUM

Sum a table column

28

AR_FUNCTION_COLCOUNT

int

Number of non-null values in a table column

29

AR_FUNCTION_COLAVG

Average of non-null values in a table column

30

AR_FUNCTION_COLMIN

Minimum of non-null values in a table column

31

AR_FUNCTION_COLMAX

Maximum of non-null values in a table column

32

AR_FUNCTION_DATEADD

char, int, date

date

Number of days, weeks, months, or years to add to date

33

AR_FUNCTION_DATEDIFF

char, date, date

int

Number of days or weeks between the start date and end date

34

AR_FUNCTION_DATENAME

char, date

char

Name of the day or month corresponding to date

35

AR_FUNCTION_DATENUM

char, date

int

Depending on the value of char (year, month, week, day, or weekday), returns the numeric value of the year, month ( 1 to 12 ), week ( 1 to 52 ), day ( 1 to 31 ) or weekday ( 1 =Sunday, 2 =Monday, and so on)

36

AR_FUNCTION_CURRCONVERT

currency, char, timestamp

Currency values to convert, based on timestamp

37

AR_FUNCTION_CURRSETDATE

currency, timestamp

Date of currency and functional currency values

38

AR_FUNCTION_CURRSETTYPE

currency, char

Type of currency and functional currency values

39

AR_FUNCTION_CURRSETVALUE

currency, char

Value of currency and functional currency values

40

AR_FUNCTION_LENGTHC

char

long

Length of string in characters

41

AR_FUNCTION_LEFTC

char, long

char

Leftmost n characters

42

AR_FUNCTION_RIGHTC

char, long

char

Rightmost n characters

43

AR_FUNCTION_LPADC

char, long, char

char

char1 left-padded with char2 to n characters

44

AR_FUNCTION_RPADC

char, long, char

char

char1 right-padded with char2 to n characters

45

AR_FUNCTION_STRSTRC

char, char

int

Position of char2 in char1 in characters (-1 = not found)

46

AR_FUNCTION_SUBSTRC

char, long [,long]

char

Substring from long1 to long2 (inclusive) in characters

47

AR_FUNCTION_ENCRYPT

(plaintext, key)

cypher-text

Encrypted value of a text string ( plaintext ), using the encryption key ( key )

48

AR_FUNCTION_DECRYPT

(cypher-text, key)

plaintext

Unencrypted text value of the encrypted text ( cyphertext ), using the encryption key ( key )

49

AR_FUNCTION_HOVER

int

char

Depending on the type of object hovered over (table column, table, attachment pool) returns a column value of a row, a row value, or an attachment file name; for all other fields, returns an empty string; the input value is a field ID

50

AR_FUNCTION_TEMPLATE

char, char, char [, char, char ...]

char

Number of arguments is variable; the first argument is the template name; the second argument is a parameter name; the third argument is the corresponding parameter value; subsequent arguments are parameter name-value pairs; therefore, this function always requires an odd number of arguments

Note

If necessary, the system automatically converts all input parameters to the correct data type.

Assigning a DDE result value

The ARDDEStruct structure defines a DDE result value to assign in a SetFields action. This option is available only for active links on Windows clients. The ARDDEStruct structure has the following elements:

Service Name

String that specifies the service to use.

Topic

String that specifies the topic to use.

Item

String that specifies the item to retrieve.

Action

Integer that specifies the type of DDE action. Specify AR_DDE_REQUEST for this item.

Path

String that specifies the path to the application.

Command

String that specifies the command to execute. Specify NULL for this item.

Assigning an SQL result value

The ARAssignSQLStruct structure specifies an SQL result value to assign in a SetFields action. Use this option to assign a value from any SQL database. The ARAssignSQLStruct structure has the following elements:

Server

String that specifies the name of the server where the database is located. The ARGetListServer function retrieves a list of available servers (see BMC Remedy AR System C API functions).

SQL Command

String that specifies the SQL query to execute.

Value Index

Integer that specifies which of the selected columns contains the value to assign.

No Match Option

Integer that specifies the action to take if no rows match the selection criteria. The following table lists the valid integers.

Multiple Match Option

Integer that specifies the action to take if multiple rows match the selection criteria. The following table lists the valid integers.

Assigning a filter API result value

The ARAssignFilterApiStruct structure specifies the name of the plug-in, the input values for the operation, and a pointer to the output values. The ARAssignFilterApiStruct structure has the following elements:

Service Name

String that specifies the name of the plug-in.

Input Values

List of values provided as input to the BMC Remedy AR System filter (AR Filter) API plug-in.

Return Index

Index into the returned list of values used in the set field assignment.

Note

You can assign AR Filter API result values for escalation Set Field actions, but you cannot assign AR Filter API result values for active link Set Field actions.

This version of the documentation is no longer supported. However, the documentation is available for your convenience. You will not be able to leave comments.

Comments