ARSetSchema

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

Updates the definition for the form with the indicated name on the specified server. If the schema is locked, only the indexList and the defaultVui can be set.

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.

Privileges

BMC Remedy AR System administrator.

Synopsis

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

int ARSetSchema(
  ARControlStruct *control,
  ARNameType name,
  ARNameType newName,
  ARCompoundSchema *schema,
  ARSchemaInterheritanceList *schemaInheritanceList,
  ARPermissionList *groupList,
  ARInternalIdList *admingrpList,
  AREntryListFieldList *getListFields,
  ARSortList *sortList,
  ARIndexList *indexList,
  ARArchiveInfoStruct *archiveInfo,
  ARAuditInfoStruct *auditInfo,
  ARAssociationsToFollowInfoStruct *assocToFollowInfo,
   ARNameType defaultVui,
  char *helpText,
  ARAccessNameType owner,
  char *changeDiary,
  ARPropList *objPropList,
  unsigned int setOption,
  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 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).

name

The name of the form to update.

newName

The new name for the form. The names of all forms on a given server must be unique. The system automatically updates all workflow references to the form if you rename it. Specify NULL for this parameter if you do not want to change the name of the form.

schema

The form type (base form or join form). See ARCreateSchema for a description of the possible values. You cannot change a join form to a base form or vice versa. You can, however, modify the join criteria for a join form. Specify NULL for this parameter if you do not want to change the form information.

schemaInheritanceList

This is reserved for future use. Specify NULL.

groupList

A list of zero or more groups who can access this form. Specify an empty group list to define a form accessible only by users with administrator capability. Specify group ID 0 (Public) to provide access to all users. The permission value that you assign for each group determines whether users in that group see the form in the form list.

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.

admingrpList

A list of zero or more groups who can administer this form (and the associated filters, escalations, and active links). Users must belong to both a specified group and the Subadministrator group to obtain these privileges. Specify an empty administrator group list to define a form that can be administered only by users with administrator capability. Specify group ID 0 (Public) to provide administrator capability to all members of the Subadministrator group. The group list that you specify replaces all existing group permissions. Specify NULL for this parameter if you do not want to change the administrator group list.

getListFields

A list of zero or more fields that identifies the default query list data for retrieving form entries. The combined length of all specified fields, including separator characters, can be as many as 128 bytes (limited by AR_MAX_SDESC_SIZE). Specify zero fields to assign the Short-Description core field as the default query list data. Specifying a getListFields argument when calling the ARGetListEntry function overrides the default query list data. Specify NULL for this parameter if you do not want to change the default query list fields.

sortList

A list of zero or more fields that identifies the default sort order for retrieving form entries. Specifying a sortList argument when calling the ARGetListEntry function overrides the default sort order. Specify NULL for this parameter if you do not want to change the default sort fields.

indexList

The set of zero or more indexes to create for the form. You can specify from 1 to 16 fields for each index (limited by AR_MAX_INDEX_FIELDS). Diary fields and character fields larger than 255 bytes cannot be indexed. Specify NULL for this parameter if you do not want to change the index list.

archiveInfo

If a form is to be archived, this is the archive information for the form. Specify NULL for this parameter if you do not want to create or set the archive information. These are the values for archive type:

In addition to the archive type, archiveInfo also stores the form name (if archive type is AR_ARCHIVE_FORM), time to trigger the archive, and the archive qualification criteria. For an archive form, only the name of the source form is maintained, and none of this archive information can be set.

auditInfo

If a form is to be audited, this is the audit information for the form. Specify NULL for this parameter if you do not want to create or set the audit information. These are the values for audit type:

In addition to the audit type, auditInfo also stores the form name (if audit type is AR_AUDIT_COPY or AR_AUDIT_LOG) and the audit qualification criteria.

assocToFollowInfo

During the data archiving process, if the you want to specify the list of associations to be followed, use this schema. Specify NULL for this parameter if you do not want to retrieve the AssociationsToFollowForArchive information. The following are the values for AssociationSelectionType:

In addition to the Association selection Type, assocToFollowInfo also stores, association name list. This will be applied when association selection type is SPECIFIC_ONLY or ALL_ENFORCED.

defaultVui

The label of the default view. Specify NULL for this parameter if you do not want to set this value.

helpText

The help text associated with the form. This text can be of any length. Specify NULL for this parameter if you do not want to change the help text.

owner

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

changeDiary

The additional change diary text associated with the form. 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.

objPropList

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

setOption

Reserved for future use.

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.