ARCreateFilter
Note
You can continue to use C APIs to customize your application, but C APIs are not enhanced to support new capabilities provided by Java APIs and REST APIs.
Description
Creates a new filter with the indicated name on the specified server. The filter takes effect immediately and remains in effect until changed or deleted.
Privileges
BMC Remedy AR System administrator.
Synopsis
#include "ar.h"
#include "arerrno.h"
#include "arextern.h"
#include "arstruct.h"
int ARCreateFilter(
ARControlStruct *control,
ARNameType name,
unsigned int order,
ARWorkflowConnectStruct *schemaList,
unsigned int opSet,
unsigned int enable,
ARQualifierStruct *query,
ARFilterActionList *actionList,
ARFilterActionList *elseList,
char *helpText,
ARAccessNameType owner,
char *changeDiary,
ARPropList *objPropList,
unsigned int errorFilterOptions
ARNameType errorFilterName
char *objectModificationLogLabel,
ARStatusList *status)
Input arguments
control
The control record for the operation. It contains information about the user requesting the operation, where that operation is to be performed, and which session is used to perform it. The user and server fields are required.
If a valid overlay group is specified in the control record, the ARCreate*
function creates a custom object that belongs to that group. If no group is specified, the function creates an origin object. To specify an overlay group, use the AR_SESS_CONTROL_PROP_DESIGN_OVERLAYGROUP
variable of the ARSetSessionConfiguration
function (see ARGetSessionConfiguration).
name
The name of the filter to create. The names of all filters on a given server must be unique.
order
A value between 0
and 1000
(inclusive) that determines the filter execution order. When multiple filters are associated with a form, the value associated with each filter determines the order in which they are processed (from lowest to highest).
schemaList
The list of form names the filter is linked to. The filter must be associated with a single form or a list of forms that currently exist on the server.
opSet
A bitmask that indicates the operations that trigger the filter.
Bit 0: | Execute the filter on get form operations ( |
Bit 1: | Execute the filter on set form operations ( |
Bit 2: | Execute the filter on create form operations ( |
Bit 3: | Execute the filter on delete form operations ( |
Bit 4: | Execute the filter on merge form operations ( |
Bit 5: | Execute the filter from a filter guide ( |
Bit 6: | Execute the filter on a Service active link action operation ( |
enable
A flag to enable or disable this filter. A value of 0
disables the filter, causing its condition checks and associated actions to not be performed. A value of 1
enables the filter, causing its conditions to be checked for each form operation specified by the opSet
parameter.
query
A qualification that determines whether the filter is executed. Specify NULL
or assign an operation value of 0
(AR_COND_OP_NONE
) to execute the filter unconditionally.
actionList
The set of actions performed if the condition defined by the query
parameter is satisfied. You can specify from 1
to 25
actions in this list (limited by AR_MAX_ACTIONS
).
elseList
The set of actions performed if the condition defined by the query
parameter is not satisfied. You can specify from 0
to 25
actions in this list (limited by AR_MAX_ACTIONS
). Specify NULL
for this parameter (or zero actions) if you do not want to define any else actions.
helpText
The help text associated with the filter. This text can be of any length. Specify NULL
for this parameter if you do not want to associate help text with this object.
owner
The owner for the filter. The owner defaults to the user performing the operation if you specify NULL
for this parameter.
changeDiary
The initial change diary associated with the filter. This text can be of any length. The server adds the user making the change and a time stamp when it saves the change diary. Specify NULL
for this parameter if you do not want to associate change diary text with this object.
objPropList
A list of server object properties. If this parameter is set to NULL
, a properties list with zero properties is associated with the object, and when the filter definition is retrieved, zero properties are returned. See Server object properties.
errorFilterOptions
The error handler options for the filter. Set to AR_FILTER_ERRHANDLER_ENABLE
to enable an error handler filter. Set to zero to disable.
errorFilterName
The name of error handler filter for this filter; NULL
if none. See Error processing for a description of error handlers.
objectModificationLogLabel
The version control label that the API function must apply to the object. If the label name does not exist on the server, the function creates it.
Ripple actions
Rename
and Delete
operations typically change multiple objects in addition to their primary target object. The Rename
or Delete
function must apply the version control label to all the objects that it affects.
Multiple API calls for a single user action
Some user actions trigger a sequence of API calls. In that situation, the last API call in the sequence applies the version control label to the object. Thus, clients that create forms (like BMC Remedy Developer Studio does) should provide the label only to the last call. For example, when a form is created, a client might issue these calls:
ARCreateSchema
ARCreateMultipleFields
ARSetVUI
ARSetVUI
ARSetSchema
In this case, the objectModificationLogLabel
value should be passed only to the last call, ARSetSchema
, even though the user provides the label during the ARCreateSchema
operation.
Operations on label-related forms
Version control labels cannot be applied to these forms:
- AR System Version Control: Label
- AR System Version Control: Labeled Object
- AR System Version Control: Object Modification Log
Return values
status
A list of zero or more notes, warnings, or errors generated from a call to this function. For a description of all possible values, see Error checking.
See also
ARDeleteFilter, ARGetFilter, ARGetListFilter, ARSetFilter. See FreeAR for: FreeARFilterActionList
, FreeARPropList
, FreeARQualifierStruct
, FreeARStatusList
.
Comments
Log in or register to comment.