ARSetContainer

Privileges

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 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 container to be updated.

newName

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

groupList

A list of zero or more groups who can access this container.

Specify an empty group list to define a container 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 container in the container 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 container (and the referenced objects).

If ownerObj is not NULL, this parameter is ignored and the Subadministrator group list of the owning form is used instead. 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 container 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.

ownerObjList

A list of schemas that own this container.

Specify ARCONOWNER_NONE for this parameter if you want the container to exist globally.

Specify NULL for this parameter if you do not want to change the container's owning object. If the object is locked, you can add owners but you cannot delete them.

label

The label for this container. It can be as many as 255 characters long.

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

description

The description for this container. It can be as many as 2000 characters long.

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

type

The type for this container, either ARCON_GUIDE or ARCON_APP.

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

references

Pointers to the objects (for example, forms or filters) referenced by this container.

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

removeFlag

A flag that specifies how invalid object references are removed. If FALSE, references to nonexistent AR System objects are removed with no error generated. If TRUE, an error is generated.

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

helpText

The help text associated with the container. 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 container.

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

changeDiary

The additional change diary text to associate with the container. 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 you set this parameter to NULL, no properties are set. See Server-object-properties-and-structures.

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 such situation, the last API call in the sequence applies the version control label to the object. Thus, clients that create forms (like Developer Studio) 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.