ARDBCGetListEntryWithFields

Description

This function retrieves a list of qualified entries with field data. The plug-in server calls this function when the AR System server receives an ARGetListEntryWithFields or an ARGetListEntry request from a client.

Important

If you do not define this function and the plug-in server receives a get list entry with fields request, the AR System server returns a list of zero entries.

Synopsis

#include "ardbc.h"

int ARDBCGetListEntryWithFields(
  void *object,
  char *tableName,
  ARVendorFieldList *vendorFieldList,
  ARInternalId transId,
  ARQualifierStruct *qualifier,
  ARSortList *sortList,
  AREntryListFieldList *getListFields,
  unsigned int firstRetrieved,
  unsigned int maxRetrieve,
  AREntryListFieldValueList *entryList,
  unsigned int *numMatches,
  ArStatusList *status)

Input arguments

object

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

tableName

Name of the external table from which the plug-in retrieves the entry.

vendorFieldList

A list of external form fields.

The plug-in uses this list to map the AR System field identification numbers (field IDs) to the corresponding external form field names. All other input arguments and return values must use the AR System field 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 accesses the AR System Database Connectivity (ARDBC) plug-in. There is only one open transaction per server thread.

qualifier

Query that determines the set of entries that this function must retrieve.

Values for this argument might include one or more fields and any combination of conditional, relational, and arithmetic operations (for numeric data types only).

sortList

List of zero or more fields that identifies the order in which the function sorts the entries.

getListFields

List of zero or more fields that the function must retrieve with each entry.

firstRetrieved

The first entry that the function must retrieve.

The function ignores entries that occur before the entry that this argument specifies.

maxRetrieve

Maximum number of entries that the function must retrieve.

You can configure this option at both the AR System client and AR System server levels. The value that the AR System server passes when it calls this function is the lower of the two values.

Return values

entryList

List of zero or more entries retrieved by the function.

numMatches

Total number of entries that match the criteria in the qualifier argument.

This value is same as the number of entries that the function returns if the number of matching entries is less than or equal to the value in the maxRetrieve argument.

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.