ARMergeEntry

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

Merges an existing database entry into the indicated form on the specified server.

Note

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.

Privileges

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.

Synopsis

#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)

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.

schema

The name of the form to merge the entry into.

fieldList

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 0 (AR_DATA_TYPE_NULL). 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.

Note

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.

mergeType

Note

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.

To omit some field validation steps, add the appropriate increments to the merge type.

query

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.

multimatchOption

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 (AR_MERGE_ENTRY_MULT_MATCH_ERROR)
  • 1: Use first match for the MergeEntry operation (AR_MERGE_ENTRY_MULT_MATCH_USE_FIRST)

Return values

entryId

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.

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.

See also

ARCreateEntry. See FreeAR for: FreeARFieldValueList, FreeARStatusList.

 

Tip: For faster searching, add an asterisk to the end of your partial query. Example: cert*