This documentation supports the 9.1 version of Remedy Action Request System.

To view the latest version, select the version from the Product version menu.

ARSetGetEntry

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

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, BMC Remedy 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

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

int ARSetGetEntry(
   ARControlStruct *control,
   ARNameType schema,
   AREntryIdList *entryId,
   ARFieldValueList *fieldList,
   ARTimestamp getTime,
   unsigned int option,
   ARInternalIdList *idList,
   ARFieldValueList *getFieldList,
   ARStatusList *seStatus
   ARStatusList *geStatus

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.

Note

The system identifies entries in join forms by concatenating the entry IDs from the member forms. As a result, an entry ID can consist of one or more values of type AREntryIdType and, therefore, is represented by the AREntryIdList structure.

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

0:

Update fields used in the join criteria (thereby causing the entry to no longer appear in the join form) (AR_JOIN_SETOPTION_NONE).

1:

Prevent update of fields used in the join criteria (AR_JOIN_SETOPTION_REF).

 

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.

Was this page helpful? Yes No Submitting... Thank you

Comments