Error: Invalid spaceKey on retrieving a related space config.

ARSetActiveLink

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.

Updates the active link with the indicated name on the specified server. The changes are 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 updated definition until they reconnect to the form (thus reloading the form from the server).

If you perform a set operation on an overlay and you provide values for an inherited grain, the values are ignored. Only values for extended or overwritten grains of the overlay are set.

BMC Remedy AR System administrator.

#include "ar.h"
#include "arerrno.h"
#include "arextern.h"
#include "arstruct.h"

int ARSetActiveLink(
   ARControlStruct *control,
   ARNameType name,
   ARNameType newName,
   unsigned int *order,
   ARWorkflowConnectStruct *workflowConnect,
   ARInternalIdList *groupList,
   unsigned int *executeMask,
   ARInternalId *controlField,
   ARInternalId *focusField,
   unsigned int *enable,
   ARQualifierStruct *query,
   ARActiveLinkActionList *actionList,
   ARActiveLinkActionList *elseList,
   char *helpText,
   ARAccessNameType owner,
   char *changeDiary,
   ARPropList *objPropList,
   unsigned int *errorActlinkOptions,
   ARNameType errorActlinkName,
   char *objectModificationLogLabel,
   ARStatusList *status)

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 ARSet* function operates on the object that belongs to that group. If no group is specified, the function operates on the origin object. To specify whether to use an object's real or resolved name in an operation and whether to perform the operation only on objects in a specified overlay group, use the AR_SESS_CONTROL_PROP_DESIGN_OVERLAYGROUP variable of the ARSetSessionConfiguration function (see ARSetSessionConfiguration).

The name of the active link to update.

The new name for the active link. The names of all active links on a given server must be unique. Specify NULL for this parameter if you do not want to change the name of the active link.

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). Specify NULL for this parameter if you do not want to change the order.

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. Specify NULL for this parameter if you do not want to change the list of forms. If the object is locked, you can append a form name to the list but you cannot remove a form name from the list.

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 by users with administrator capability. Specify group ID 0 (Public) to provides access to all users. The group list that you specify replaces all existing group permissions. Specify NULL for this parameter if you do not want to change the group list.

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

Bit 0:

Execute the active link when a user selects a button, toolbar button, or menu item specified by the controlField parameter (AR_EXECUTE_ON_BUTTON).

Bit 1:

Execute the active link when a user presses Return in the field specified by the focusField parameter (AR_EXECUTE_ON_RETURN).

Bit 2:

Execute the active link when a user submits an entry (before data is sent to the BMC Remedy AR System server) (AR_EXECUTE_ON_SUBMIT).

Bit 3:

Execute the active link when a user modifies an individual entry (before data is sent to the BMC Remedy AR System server) (AR_EXECUTE_ON_MODIFY).

Bit 4:

Execute the active link when a user displays an entry (after data is retrieved from the BMC Remedy AR System server) (AR_EXECUTE_ON_DISPLAY).

Bit 7:

Execute the active link when a user selects an item from a character menu associated with the field specified by the focusField parameter or selects a row in the table field specified by the focusField parameter (AR_EXECUTE_ON_MENU_CHOICE).

Bit 8:

Execute the active link when a user moves out of a field (either manually or though workflow) (AR_EXECUTE_ON_LOSE_FOCUS).

Bit 9:

Execute the active link when a user sets default values (either manually or with preference settings) (AR_EXECUTE_ON_SET_DEFAULT).

Bit 10:

Execute the active link when a user retrieves one or more entries (before the query is sent to the BMC Remedy AR System server) (AR_EXECUTE_ON_QUERY).

Bit 11:

Execute the active link when a user modifies an individual entry (after data is committed to the database) (AR_EXECUTE_ON_AFTER_MODIFY).

Bit 12:

Execute the active link when a user submits an entry (after data is committed to the database) (AR_EXECUTE_ON_AFTER_SUBMIT).

Bit 13:

Execute the active link when a user moves into a field (either manually or through workflow) (AR_EXECUTE_ON_GAIN_FOCUS).

Bit 14:

Execute the active link when a user opens any form window (AR_EXECUTE_ON_WINDOW_OPEN).

Bit 15:

Execute the active link when a user closes any form window (AR_EXECUTE_ON_WINDOW_CLOSE).

Bit 16:

Execute the active link when a user moves off an entry (that is, when a record is removed from the server) (AR_EXECUTE_ON_UNDISPLAY).

Bit 17:

Execute the active link when a user performs a Copy to Submit operation (AR_EXECUTE_ON_COPY_SUBMIT).

 

Specify NULL for this parameter if you do not want to change the execute mask.

The ID of the field that represents the button, toolbar button, or menu item associated with executing the active link. The AR_EXECUTE_ON_BUTTON condition (see executeMask) is ignored unless you specify this parameter. This parameter is ignored if you do not specify AR_EXECUTE_ON_BUTTON. Specify NULL for this parameter if you do not want to change the control field.

The ID of the field associated with executing the active link by pressing Return or selecting a character menu item. The AR_EXECUTE_ON_RETURN or AR_EXECUTE_ON_MENU_CHOICE conditions (see executeMask) are ignored unless you specify this parameter (you must create another active link to specify a different field for each condition). This parameter is ignored if you do not specify either condition. Specify NULL for this parameter if you do not want to change the focus field.

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. Specify NULL for this parameter if you do not want to change this flag.

A qualification that determines whether the active link is executed. Assign an operation value of 0 (AR_COND_OP_NONE) to execute the active link unconditionally. Specify NULL for this parameter if you do not want to change the query.

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). Specify NULL for this parameter if you do not want to change the action list.

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 a list with zero items to define no else actions. Specify NULL for this parameter if you do not want to change the else list.

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 change the help text.

The owning user for the active link. Specify NULL for this parameter if you do not want to change the owner.

The additional change diary text to associate with the active link. This text can be of any length and is appended at the end of any existing text. Existing change diary text cannot be deleted or changed. 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 add to the change diary.

A list of server object properties. If this parameter is set to NULL, no properties are set. See Server object properties.

Reserved for future use. Set to NULL.

Reserved for future use. Set to NULL.

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

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.

ARCreateAlertEvent, ARDeleteActiveLink, ARGetActiveLink, ARGetListActiveLink, ARGetMultipleActiveLinks. See FreeAR for: FreeARActiveLinkActionList, FreeARInternalIdList, FreeARPropList, FreeARQualifierStruct, FreeARStatusList.

Was this page helpful? Yes No Submitting... Thank you

Comments