ARDBCSetEntry

Description

This function modifies the contents of a single entry or Binary Large Object (BLOB). The plug-in server calls this function when:

The AR System server receives a call to ARSetEntry or ARMergeEntry from the client.
Users enter information to create or merge entries into an external form.
A Push Fields filter or an escalation action modifies an entry.

If the specified entry does not exist, the plug-in creates it. An ARDBCSetEntry operation on a nonexistent entry can occur when the AR System server receives a call to ARMergeEntry from a client.

Important

If you do not define this function, the AR System server receives an error message and the entry is not modified.

Synopsis

#include "ardbc.h"

int ARDBCSetEntry(
  void *object,
  char *tableName,
  ARVendorFieldList *vendorFieldList,
  ARInternalId transId,
  AREntryIdList *entryId,
  ARFieldValueList *fieldValueList,
  ARTimestamp getTimestamp,
  ARStatusList *status)

Input arguments

object

Pointer to the plug-in instance that the call to ARPluginCreateInstance returned.

tableName

Name of the external table on which the plug-in sets this entry.

vendorFieldList

List of external form fields.

The plug-in uses this list to map the AR Systemfield identification numbers (field IDs) to the corresponding external form field names. All other input arguments and return values must use the AR Systemfield IDs.

transId

Transaction identification number (transaction ID) that the plug-in server designates for each transaction.

The transaction ID is unique to the thread that the AR System server uses to access the AR System Database Connectivity (ARDBC) plug-in. There is only one open transaction per server thread.

entryId

Unique identifier for the entry to set.

The entry ID must correspond to a value in the external data source and must be unique, non-NULL, and either character or numeric data. For an external data source, the entry ID can be longer than 15 characters. Therefore, the entry ID can consist of one or more values of type AREntryIdType and is represented by the AREntryIdList structure.

fieldValueList

List of the data in a new entry.

The list consists of one or more field and value pairs that the server specifies in a random order.

getTimestamp

Time stamp that specifies when the client last retrieved the entry. The ARDBC plug-in provides a functionality similar to the AR System server. The ARDBC plug-in returns an error if the entry is modified by other client after the entry is retrieved by the calling client.

For example: The plug-in can store a modification time stamp and compare this value with it to determine whether the entry changed since the last retrieval. If the value of this parameter is 0, ignore it.

For a description of the AR System functionality, see ARSetEntry.

Return values

status

List of zero or more notes, warnings, or errors generated from a call made to this function. For a description of all possible values, see Error-checking.