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:

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 Push-Fields-action-and-structures) 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:

Tag values for ARAssignFieldStruct

No Match Option values for ARAssignFieldStruct

Multiple-Match Option values for ARAssignFieldStruct

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 Representing-qualifications-with-structures). 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:

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

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:

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:

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:

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