ARSetGetEntry

Description

Bundles the following API calls into one call:

• ARSetEntry — Updates the form entry with the indicated ID on the specified server.
• ARGetEntry — Retrieves the form entry with the indicated ID from the specified server. You can retrieve data for specific fields, all (accessible) fields, or no fields (which is useful to verify whether a form has any entries). This function returns only the name, size, and compressed size of attachment fields. Use ARGetEntryBLOB to retrieve the contents of the attachment.

After issuing an ARSetEntry call to enter a value into a field, AR System clients always issue an ARGetEntry call to ensure that they have the current value for the field (server-side workflow might have modified the value after it was set).

These multiple calls can degrade a client's performance, especially on Wide Area Networks (WANs). To improve performance, use ARSetGetEntry, which requires only one call from the client to execute the combined functionality of ARSetEntry and ARGetEntry.

Because ARSetGetEntry includes a query, it cannot be used in bulk API calls.

If you perform a set operation on an overlay and you provide values for an inherited grain, the values are ignored. Only values for extended or overwritten grains of the overlay are set.

Privileges

The system updates and returns data based on the access privileges of the user that you specify for the control parameter. 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.

The system returns values for accessible fields and warning messages for fields the user cannot access.

Backward compatibility

When an AR System 7.6.02 or later client issues this call to an AR System 7.5.00 or earlier server, the client replaces the ARSetGetEntry call with two separate calls: ARSetEntry and ARGetEntry. In this situation, the client's performance is not improved, but the correct SetEntry operation takes place, followed by the correct GetEntry operation.

Synopsis

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 containing the entry to update and retrieve.

entryId

The ID of the entry to update and retrieve.

fieldList

For ARSetEntry functionality, a list of one or more field/value pairs (specified in any order) that identifies the new data for the entry. 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. 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.

getTime

For ARSetEntry functionality, a time stamp that specifies when the entry was last retrieved. The system compares this value with the value in the Modified Date core field to determine whether the entry has been changed since the last retrieval. The system updates the entry if the value that you specify is greater than Modified Date. If not, the system returns an error. You can either retrieve the entry again and determine whether to apply your changes or specify 0 for this parameter to bypass the time stamp comparison.

option

For ARSetEntry functionality, a value that indicates whether users can update fields specified in the join qualification (only applicable to join forms).

idList

For ARGetEntry functionality, a list of zero or more internal IDs that specify the fields to retrieve. Specify NULL for this parameter (or zero fields) to retrieve all (accessible) fields. Specify NULL for both this parameter and the fieldList parameter if you do not want to retrieve any fields. To minimize network traffic, specify only the fields that you need if you do not require the data for all fields. If an attachment field is specified in the list, only its name, size, and compressed size are returned. Use ARGetEntryBLOB to retrieve the contents of the attachment.

Return values

fieldList

For ARGetEntry functionality, a list of zero or more field/value pairs that identifies the data for the specified entry. The fields are returned in the order specified by idList. If the user does not have permission for a specified field or the field does not exist, the system does not return a value for the field/value pair. Specify NULL for this parameter if you do not want to retrieve any field data.

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.

This function returns two statuses:

• seStatus — Status list from the ARSetEntry operation.
• geStatus — Status list from the ARGetEntry operation.

If ARSetEntry fails, the server does not perform the following ARGetEntry call.

See also

ARGetEntry, ARSetEntry.