ARCreateContainer

Important

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 container with the indicated name on the specified server. Use this function to create applications, active links, active link guides, filter guide, packing lists, guides, and AR System-defined container types. A container can also be a custom type that you define.

Synopsis

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

int ARCreateContainer(
ARControlStruct *control,
ARNameType name,
ARPermissionList *groupList,
ARInternalIdList *admingrpList,
ARContainerOwnerObjList *ownerObjList,
char *label,
char *description,
unsigned int *type,
ARReferenceList *references,
ARBoolean removeFlag,
char *helpText,
ARAccessNameType owner,
char *changeDiary,
ARPropList *objPropList,
char *objectModificationLogLabel,
char *taskName,
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 container. The names of all containers on a given server must be unique.

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.

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 only be administered by users with administrator capability.

Specify group ID 0 (Public) to provide administrator capability to all members of the Subadministrator group.

ownerObjList

A list of schemas that own this container. This parameter can be NULL if the container exists globally.

label

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

description

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

type

The type for this container. It can be either guide (ARCON_GUIDE), application (ARCON_APP), or a custom type that you have defined.

references

A list of pointers to the objects referenced by this container.

References can be to internal AR System objects (For example: Guides reference active links and applications reference forms) or to external objects such as URLs or file names.

Specify NULL for this parameter if you do not want to associate any objects with this container.

removeFlag

A flag that specifies how invalid object references are removed when the container is created.

If set to FALSE, references to nonexistent AR System objects are removed with no error.

If set to TRUE, an error is generated.

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 associate help text with this object.

owner

The owner for the container. The owner defaults to the user performing the operation if you specify NULL for this parameter.

changeDiary

The initial change diary associated with the container. 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 container, and a list of zero properties is returned when an ARGetContainer is performed. See Server object properties.

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 does) should provide the label only to the last call.

For exampl: When a form is created, a client might issue the following 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.