Merges an existing database entry into the indicated form on the specified server.
When operating on join forms, this function simply triggers workflow. You must create workflow to propagate data to the join form's underlying forms. For more information, see Performing distributed operations on join forms.
The system merges data based on the access privileges of the user that you specify for the
control parameter and the createMode setting for each field (see ARCreateField). User permissions are verified for each specified field. The system generates an error if the user does not have write permission for a field or a field does not exist.
#include "ar.h" #include "arerrno.h" #include "arextern.h" #include "arstruct.h" int ARMergeEntry( ARControlStruct *control, ARNameType schema, ARFieldValueList *fieldList, unsigned int mergeType, ARQualifierStruct *query, unsigned int multimatchOption, AREntryIdType *entryId, 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.
The name of the form to merge the entry into.
A list of one or more field/value pairs (specified in any order) that identifies the data for the new entry. You must specify values for all required fields that do not have defined defaults. Values must be of the data type defined for the field or have a data type of
NULL values can be specified only for optional fields, and assigning
NULL overrides any defined field default. An error is generated if a field does not exist or the user specified by the control parameter does not have write permission for a field.
You must specify a formatted diary string (such as that returned by
ARGetEntry) for any diary fields that you want to merge. In addition, unlike creating a new entry, you can specify values for the Entry ID, Create Date, Last Modified By, Modified Date, and Status History fields when merging an existing entry.
This argument is not applicable to join forms.
A value that indicates the action to take if
fieldList includes the Entry ID field and the ID specified already exists in the target form. This parameter is ignored if you do not specify the Entry ID field or the ID specified does not conflict with existing entry IDs.
Generate an error (
Create a new entry with a new ID (
Delete the existing entry and create a new one in its place (
Update the fields specified in
Always generate a new entry ID for the record, even if there is no conflicting entry ID (
|(Starting from Service Pack 1) Generates an error for records with existing unique field (|
To omit some field validation steps, add the appropriate increments to the merge type.
Allow NULL in required fields (not applicable to the Submitter, Status, or Short-Description core fields) (
Skip field pattern checking (including $MENU$ ) (
Ignore filter processing (
Disable association enforcement for this entry.
Note: Server will disable association enforcement for this entry only and will enforce associations on other entries affected by workflow triggered on merge entry.
A query that determines the set of entries to retrieve. The qualification can include one or more fields and any combination of conditional, relational, and arithmetic (numeric data types only) operations. The system generates an error if the user does not have read permission for a field or a field does not exist.
A flag that determines the action to be taken when there are multiple matching entries for a given query. This parameter is valid only if a query is specified, else the server ignores the parameter.
Valid values are:
0: Error on multi-match (
1: Use first match for the MergeEntry operation (
The ID of the merged entry. If you do not specify the Entry ID field in
fieldList, the system generates and returns a new ID. If you do specify the Entry ID field and the ID specified is unique in the target form, the system returns that ID. If the ID specified is not unique and you specify
AR_MERGE_ENTRY_DUP_NEW_ID for the
mergeType parameter, the system generates and returns a new ID.
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.