ARCreateAssociation

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

Creates a new association with the indicated name on the specified server. The association takes effect immediately and remains in effect until changed or deleted.

Privileges

AR System administrator.

Synopsis

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

int ARCreateAssociation(
     ARControlStruct   *control,
     ARNameType                          name,
     ARNameType                          primaryFormName,
     ARNameType                          secondaryFormName,
     ARQualifierStruct                   *primaryFormQual,
     ARQualifierStruct                   *secondaryFormQual,
     ARInternalId                        associationType,
     ARAssociationMappingInfoStruct      *keyMapping,
     ARBoolean                           enable,
     ARInternalId                        enforcement,
     ARInternalId                        cardinality,
     char                                *description,
     char                                *helpText,
     ARAccessNameType                    owner,
     char                                *changeDiary,
     ARPropList                          *objPropList,
     char                                *objectModificationLog,
     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 ARSetSessionConfiguration).

name

The name of the association to create. The names of all associations on a given server must be unique.

primaryFormName

The name of the form to be used as the primary form in an association. A form object with this form name should exist in the server; otherwise, the server does not allow the association to be created.

secondaryFormName

The name of the form to be used as the secondary form in the association. A form object with this form name should exist in the server; otherwise, server does not allow the association to be created.

primaryFormQual

Qualification associated with specified primary form. Specify NULL or assign an operation code as 0 (AR_COND_OP_NONE) to refer records unconditionally. For more information about qualifications, see Associations Qualifications.

secondaryFormQual

Qualification associated with specified secondary form. Specify NULL or assign an operation code as 0 (AR_COND_OP_NONE) to refer records unconditionally. For more information about qualifications, see Associations Qualifications.

AssociationType

The type of association you want to create. (AR_ASSOCIATION_TYPE_INDIRECT or AR_ASSOCIATION_TYPE_DIRECT).

keyMapping

For Direct Association, this structure contains pkFkMappingInfoList, which represents field mapping used between the primary form and the secondary form.
For Indirect Association, this structure contains associationFormMapping, to specify associationFormName and associationFormQual along with field mapping between the primary form and the association form and the secondary form and the association form.

enable

A flag to enable or disable this association. A value of 0 disables the association and a value of 1 enables the association.

enforcement

Specifies association’s enforcement value. Association with enforcement value as ENFORCE_YES (AR_ASSOCIATION_ENFORCE_YES) signifies that this association is enforced and the association with enforcement value as ENFORCE_NO (AR_ASSOCIATION_ENFORCE_NO)signifies that this association is not enforced. For more information, see Enforced and unenforced relationships.

cardinality

It can have one of the following values:

OneToOne (AR_ASSOCIATION_CARDINALITY_ONE_TO_ONE)
OneToMany (AR_ASSOCIATION_CARDINALITY_ONE_TO_MANY)
ManyToMany (AR_ASSOCIATION_CARDINALITY_MANY_TO_MANY)

ManyTOMany cardinality is not applicable for direct types of associations.

description

The description associated with the association. This text can be of any length. Specify NULL for this parameter if you do not want to associate description with this object.

helpText

The help text associated with the association. 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 association. The owner defaults to the user performing the operation if you specify NULL for this parameter.

changeDiary

The initial change diary associated with the association. 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 ARGetAssociation is performed.

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.

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.