ARCreateActiveLink

Description

Creates a new active link with the indicated name on the specified server. The active link is added to the server immediately and returned to users who request information about active links. Because active links operate on clients, individual clients do not receive the new definition until they reconnect to the form (thus reloading the form from the server).

Privileges

BMC Remedy AR System administrator.

Synopsis

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 active link to create. The names of all active links on a given server must be unique.

order

A value between 0 and 1000 (inclusive) that determines the active link execution order. When multiple active links are associated with a form, the value associated with each active link determines the order in which they are processed (from lowest to highest).

schemaList

The list of form names the active link is linked to. The active link must be associated with a single form or a list of forms that currently exists on the server.

groupList

A list of zero or more groups who can access this active link. Users can execute an active link if they belong to a group that has access to it. Specify an empty group list to define an active link accessible only by users with administrator capability. Specify group ID 0 (Public) to provide access to all users.

executeMask

A bitmask that indicates the form operations that trigger the active link.

 controlField

The ID of the field that represents the button, toolbar button, or menu item associated with executing the active link. This parameter is ignored if you do not specify the AR_EXECUTE_ON_BUTTON condition (see the executeMask parameter on executeMask).

focusField

The ID of the field associated with executing the active link by pressing Return, selecting a character menu item, or gaining or losing focus. You must create another active link to specify a different field for each condition. This parameter is ignored if you do not specify one of the following conditions: AR_EXECUTE_ON_RETURN, AR_EXECUTE_ON_MENU_CHOICE, AR_EXECUTE_ON_LOSE_FOCUS, or AR_EXECUTE_ON_GAIN_FOCUS (see the executeMask parameter on executeMask).

enable

A flag to enable or disable this active link. A value of 0 disables the active link, causing it to be invisible to the user and unavailable for use. A value of 1 enables the active link, causing it to be visible and available for use.

query

A qualification that determines whether the active link is executed. Specify NULL or assign an operation value of 0 (AR_COND_OP_NONE) to execute the active link 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 active link. 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 active link. The owner defaults to the user performing the operation if you specify NULL for this parameter.

changeDiary

The initial change diary associated with the active link. 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 zero properties are returned when an ARGetActiveLink is performed. See Server object properties.

errorActlinkOptions

Reserved for future use. Set to NULL.

errorActlinkName

Reserved for future use. Set to NULL.

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

ARDeleteActiveLink, ARDeleteField, ARGetActiveLink, ARGetField, ARGetListActiveLink, ARGetListField, ARGetMultipleActiveLinks, ARSetActiveLink, ARSetField. See FreeAR for: FreeARActiveLinkActionList, FreeARInternalIdList, FreeARQualifierStruct, FreeAR, FreeARPropList, FreeARWorkflowConnectStruct.