rtl::Server

rtl::Server Class Reference

Server is the main class in RTL, representing a session with an AR System Server. More...

#include <Server.h>

List of all members.

Public Types

enum  FieldProperties
 Set of field properties to retrieve or update. More...

Public Member Functions

 Server (const std::string &server, const std::string &user, const std::string &password)
 Construct a session to the specified server, using the user name and password specified.
virtual ~Server ()
 Destructor. Will call ARTermination.
StatusList getStatusList ()
 Get the status list, if any resulting from the previous call.
ARControlStruct & getControlStruct ()
 Get the ARControlStruct representing this session.
void setServerPort (const std::string &name, int portNum, int rpcNum)
 Set the port and/or RPC program number for the AR System Server.
void lockToAdminRPC (const std::string &name)
 Lock to the RPC Program number of the admin server.
void getListSchema (AssignableT< ARNameList > &out, unsigned int flags=AR_LIST_SCHEMA_ALL|AR_HIDDEN_INCREMENT, ARTimestamp timeStamp=0)
 Get a list of schemas (forms) on the AR System server.
void getListSchema (AssignableT< ARNameList > &out, const IdList &idList, const std::string &name, unsigned int flags=AR_LIST_SCHEMA_ALL|AR_HIDDEN_INCREMENT, ARTimestamp timeStamp=0)
 Get a list of schemas (forms) that contain the specified fields and/or have a specific relationship to another form.
void getListActiveLink (AssignableT< ARNameList > &out, const std::string &form, unsigned int timeStamp=0)
 Get a list of active links on the server.
void getListFilter (AssignableT< ARNameList > &out, const std::string &form, unsigned int timeStamp=0)
 Get a list of filters on the server.
void getListEscalation (AssignableT< ARNameList > &out, const std::string &form, unsigned int timeStamp=0)
 Get a list of escalations on the server.
void getListCharMenu (AssignableT< ARNameList > &out, unsigned int timeStamp=0)
 Get a list of menus on the server.
void getListCharMenu (AssignableT< ARNameList > &out, const NameList &formList, const NameList &activeLinkList, unsigned int timeStamp=0)
 Get a list of menus on the server.
void getListField (AssignableT< ARInternalIdList > &out, const std::string &form)
 Get a list of fields on a form.
void getListVUI (AssignableT< ARInternalIdList > &out, const std::string &form)
 Get a list of vuis (views) on a form.
void getField (AssignableT< ARFieldInfoStruct > &out, const std::string &form, ARInternalId id, FieldProperties propertiesMask=fieldCommonUserProperties)
 get the definition of a field on a form.
void getMultipleFields (AssignableT< ARFieldInfoList > &out, const std::string &form, const IdList &idList, FieldProperties propertiesMask=fieldCommonUserProperties)
 get the definition of fields on a form.
Id createField (const std::string &form, const Field &field, bool reservedIdOk=true)
 create a field from a form.
void setField (const std::string &form, const Field &field, unsigned int propertiesMask)
 update the definition of a field on a form.
void deleteField (const std::string &form, ARInternalId id, unsigned int option=AR_FIELD_DATA_DELETE)
 delete a field from a form.
void createEntry (EntryId &out, const std::string &form, const AssignableT< ARFieldValueList > &values)
 Create an entry in a form.
void deleteEntry (const std::string &form, const EntryIdList &entryId, unsigned int option=AR_JOIN_DELOPTION_NONE)
 Delete an entry.
void deleteEntry (const std::string &form, const EntryId &entryId, unsigned int option=0)
 Delete an entry.
void getEntry (AssignableT< ARFieldValueList > &out, const std::string &form, const EntryIdList &entryId, const IdList &idList)
 Retrieve an entry.
void getEntry (AssignableT< ARFieldValueList > &out, const std::string &form, const EntryIdList &entryId)
 Retrieve an entry.
void mergeEntry (EntryId &out, const std::string &form, const AssignableT< ARFieldValueList > &values, unsigned int mergeType=AR_MERGE_ENTRY_DUP_MERGE)
 Import an entry.
void setEntry (const std::string &form, const EntryIdList &entryId, const AssignableT< ARFieldValueList > &values, ARTimestamp getTime=0, unsigned int joinOption=AR_JOIN_SETOPTION_NONE)
 Update an entry.
void getMultipleEntries (AssignableT< ARFieldValueListList > &out, const std::string &form, const EntryIdListList &entryIdList, const IdList &fields)
 Retrieve multiple entries.
void parseQualification (Qualifier &out, const std::string &qualification, const std::string &form, const std::string &displayTag)
 Parse a qualification string and return a structure that can be used for getListEntry and getListEntryWithFields.
void getListEntryWithFields (AssignableT< AREntryListFieldValueList > &out, const std::string &form, const Qualifier &qualifier, const IdList &idList, const SortList &sortList, unsigned int firstRetrieve=0, unsigned int maxRetrieve=0, unsigned int *numMatches=NULL)
 retrieve the entry id and field values for entries that match qualification criteria
void getListSQL (AssignableT< ARValueListList > &out, const std::string &sqlCommand, unsigned int maxRetrieve=0, unsigned int *numMatches=NULL)
 retrieve values from execution of a SQL statement
void getServerInfo (AssignableT< ARServerInfoList > &out, const ServerInfoRequestList &requestList)
 retrieve server information, such as host name, database type, etc.
void setServerInfo (const AssignableT< ARServerInfoList > &infoList)
 update server information.
void decodeStatusHistory (AssignableT< ARStatusHistoryList > &out, const std::string &statHistory)
 decode the character value for field 15 (status history) into a list of status history entries
void decodeDiary (AssignableT< ARDiaryList > &out, const std::string &diaryValue)
 decode the diary value for a diary field int a list of diary entries

Detailed Description

Server is the main class in RTL, representing a session with an AR System Server.

ar::Server is the main class in RTL for communicating with AR System Servers. It represents an active user session, including the active server name and authentication information. For multi-threaded applications, one ar::Server instance should be created per thread.

Should you need to access the AR System C API directly, you can use the getControlStruct() method to retrieve a control structure directly. This can then be passed to any AR API function.

All calls will throw an Exception if there is an error. If you wish to check the result of any operation for warnings or notes, you can call getStatusList() to retrieve the status from the last API call made.

Member Enumeration Documentation

enum rtl::Server::FieldProperties
 

Set of field properties to retrieve or update.

This is an enum because we can't declare static const members completely inline here, as we might in Java. You can actual combine values into a bitmask if fieldCommonUserProperties or fieldAllProperties do not suffice for your needs.

Constructor & Destructor Documentation

rtl::Server::Server (  const std::string &  server,
const std::string &  user,
const std::string &  password
)  [inline]
 

Construct a session to the specified server, using the user name and password specified.

Initiates a session. This will call ARInitialization. If you need to connect to a specific port or rpc program number, call setServerPort immediately after constructing the server object.

Parameters:
server host name of the Action Request System Server
user login name
password password
Returns:
none
Exceptions:
Exception 
See also:
setServerPort

virtual rtl::Server::~Server (   )  [inline, virtual]
 

Destructor. Will call ARTermination.

Parameters:
none 
Returns:
none
Exceptions:
Exception 

Member Function Documentation

void rtl::Server::createEntry (  EntryId &  out,
const std::string &  form,
const AssignableT< ARFieldValueList > &  values
)  [inline]
 

Create an entry in a form.

Create an entry in a form, equivalent to ARCreateEntry.

Example: 


 try {
   Server server("localhost", "Demo", "");
   FieldValueMap fieldValues; // could use a FieldValueList and call add instead of set, passing a FieldValue(id, value)
   fieldValues.set(8, "Short Description");
   fieldValues.set(536870913, Value::IntegerValueImpl(2)); // integer value
   EntryId entryId;
   server.createEntry(entryId, "My Form", fieldValues);
 } catch (Exception &err) {
   cerr << err.toString().c_str();
 }

Parameters:
out (out) will contain the EntryId of the entry that was created
form form name in which to create entry
value collection of field/value pairs containing entry data. Typically a FieldValueMap, but a FieldValueList would also work.
Returns:
none
Exceptions:
Exception 

Id rtl::Server::createField (  const std::string &  form,
const Field &  field,
bool  reservedIdOk = true
)  [inline]
 

create a field from a form.

Creates a field on a form, equivalent to ARCreateField. If the field id of the Field object is 0, the server will generate a new id for you. The id of the new field is returned (note that the Field object is is not updated with the new id automatically).

Example: 


 try {
   Server server("localhost", "Demo", "");
   Field field;
   server.getField(field, "My Form", 8, fieldAllProperties);
   // copy the field and create a new one
   Field newField = field;
   newField.setId(0);
   newField.setName("Copy of Short Description");
   Id newId = server.createField("User", newField);
   cout << "New field id is " << newId.getId() << "\n";
 } catch (Exception &err) {
   cerr << err.toString().c_str();
 }

Parameters:
form the Form name which contains the field being saved
field the Field to create on the form
reservedIdOk whether it is okay to create the field with an id in the reserved range
Returns:
Id the id of the new field
Exceptions:
Exception 
See also:
getField

setField

deleteField

getMultipleFields

Field

void rtl::Server::decodeDiary (  AssignableT< ARDiaryList > &  out,
const std::string &  diaryValue
)  [inline]
 

decode the diary value for a diary field int a list of diary entries

Parameters:
out (out) will contain the list of diary entries
diaryValue the value of the diary field
Returns:
none
Exceptions:
Exception 

void rtl::Server::decodeStatusHistory (  AssignableT< ARStatusHistoryList > &  out,
const std::string &  statHistory
)  [inline]
 

decode the character value for field 15 (status history) into a list of status history entries

Parameters:
out (out) will contain the list of status history entries
statHistory the character value of field 15 (from getEntry, getMultipleEntries)
Returns:
none
Exceptions:
Exception 

void rtl::Server::deleteEntry (  const std::string &  form,
const EntryId &  entryId,
unsigned int  option = 0
)  [inline]
 

Delete an entry.

Delete an entry, equivalent to ARDeleteEntry.

Parameters:
form the form that contains the entry
entryId the id of the entry to delete.
option delete option - either AR_JOIN_DELOPTION_NONE or AR_JOIN_DELOPTION_FORCE. See ar.h for documentation.
Returns:
none
Exceptions:
Exception 

void rtl::Server::deleteEntry (  const std::string &  form,
const EntryIdList &  entryId,
unsigned int  option = AR_JOIN_DELOPTION_NONE
)  [inline]
 

Delete an entry.

Delete an entry, equivalent to ARDeleteEntry.

Example: 


 try {
   Server server("localhost", "Demo", "");
   EntryListFieldValueList entries;
   Qualifier qualifier;
   server.parseQualification(qualifier, "'Assigned to' = $USER", "My Form", "");
   server.getListEntryWithFields(entries, "My Form", qualifier, IdList().add(1)); // retrieve all rows assigned to $USER$
   EntryListFieldValueList::iterator iter = entries.begin();
   for (; iter != entries.end(); iter++) {
      server.deleteEntry("My Form", (*iter).getEntryIdList()); // delete this entry
   }
 } catch (Exception &err) {
   cerr << err.toString().c_str();
 }

Parameters:
form the form that contains the entry
entryId the id of the entry to delete.
option delete option - either AR_JOIN_DELOPTION_NONE or AR_JOIN_DELOPTION_FORCE. See ar.h for documentation.
Returns:
none
Exceptions:
Exception 

void rtl::Server::deleteField (  const std::string &  form,
ARInternalId  id,
unsigned int  option = AR_FIELD_DATA_DELETE
)  [inline]
 

delete a field from a form.

Deletes a field on a form, equivalent to ARDeleteField.

Example: 


 try {
   Server server("localhost", "Demo", "");
   server.deleteField("My Form", 536870913);
 } catch (Exception &err) {
   cerr << err.toString().c_str();
 }

Parameters:
form the Form name which contains the field being saved
id the id of the field to delete
option the delete option - defaults to AR_FIELD_DATA_DELETE. See values in ar.h.
Returns:
none
Exceptions:
Exception 
See also:
getField

createField

setField

getMultipleFields

Field

ARControlStruct& rtl::Server::getControlStruct (   )  [inline]
 

Get the ARControlStruct representing this session.

This is useful if you need to call an AR API function directly (perhaps one that is not implemented here in RTL yet).

Parameters:
none 
Returns:
ARControlStruct control structure for this session

void rtl::Server::getEntry (  AssignableT< ARFieldValueList > &  out,
const std::string &  form,
const EntryIdList &  entryId
)  [inline]
 

Retrieve an entry.

Retrieve all field values for an entry.

Example: 


 try {
   Server server("localhost", "Demo", "");
   FieldValueMap fieldValueMap;
   server.getEntry(fieldValueMap, "My Form", entryId);
   cout << "Value for field 8 is " << fieldValueMap.get(8).toString().c_str() << "\n";
 } catch (Exception &err) {
   cerr << err.toString().c_str();
 }

Parameters:
out (out) will contain the field values for the entry. Typically a FieldValueMap, but a FieldValueList will also work.
form name of form that contains the entry
entryId id of the entry to retrieve
Returns:
none
Exceptions:
Exception 
See also:
FieldValueMap

FieldValueList

void rtl::Server::getEntry (  AssignableT< ARFieldValueList > &  out,
const std::string &  form,
const EntryIdList &  entryId,
const IdList &  idList
)  [inline]
 

Retrieve an entry.

Retrieve an entry, specifying specific fields for which values will be retrieved.

Example: 


 try {
   Server server("localhost", "Demo", "");
   FieldValueMap fieldValueMap;
   server.getEntry(fieldValueMap, "My Form", entryId, IdList().add(2).add(8));
   cout << "Value for field 8 is " << fieldValueMap.get(8).toString().c_str() << "\n";
 } catch (Exception &err) {
   cerr << err.toString().c_str();
 }

Parameters:
out (out) will contain the field values for the entry. Typically a FieldValueMap, but a FieldValueList will also work.
form name of form that contains the entry
entryId id of the entry to retrieve
idList list of field ids for which to retrieve values
Returns:
none
Exceptions:
Exception 
See also:
FieldValueMap

FieldValueList

void rtl::Server::getField (  AssignableT< ARFieldInfoStruct > &  out,
const std::string &  form,
ARInternalId  id,
FieldProperties  propertiesMask = fieldCommonUserProperties
)  [inline]
 

get the definition of a field on a form.

Retrieves the definition of a field on a form, equivalent to ARGetField. You can specify which field properties should be returned by passing propertiesMask. (Note: propertiesMask is an enum, but a bitmask will be accepted if you combine values and cast it. An enum is used because static const unsigned int members cannot be declared inline using on header files in C++, unlike Java or .NET). If a property is not retrieved, that property will be empty in the returned Field object.

Example: 


 try {
   Server server("localhost", "Demo", "");
   Field field;
   server.getField(field, "User", AR_CORE_SHORT_DESCRIPTION);
   cout << "Field label is " << field.getDisplayInstanceList().get(536870912).get(AR_DPROP_LABEL).toString().c_str() << "\n";
 } catch (Exception &err) {
   cerr << err.toString().c_str();
 }

Parameters:
out (out) the Field object containing the definition of the requested field.
form the Form name which contains the field being requested
id the id of the field being requested
propertiesMask which field properties to retrieve.
Returns:
none
Exceptions:
Exception 
See also:
setField

createField

deleteField

getMultipleFields

Field

void rtl::Server::getListActiveLink (  AssignableT< ARNameList > &  out,
const std::string &  form,
unsigned int  timeStamp = 0
)  [inline]
 

Get a list of active links on the server.

Example: 


 try {
   Server server("localhost", "Demo", "");
   NameList names;
   server.getListActiveLinks(names);
   NameList::iterator iter = names.begin();
   for (; iter != names.end(); iter++) {
       cout << (*iter).getName().c_str() << "\n"s;
   }
 } catch (Exception &err) {
   cerr << err.toString().c_str();
 }

Parameters:

  

    
out the list will be stored here.  Pass a NameList.


    
form the form for which to retrieve active links.


    
timeStamp pass a non-zero timestamp to retrieve only objects modified after that time.


  




Returns:
none
 


Exceptions:

  

    
Exception 

void rtl::Server::getListCharMenu (  AssignableT< ARNameList > &  out,
const NameList &  formList,
const NameList &  activeLinkList,
unsigned int  timeStamp = 0
)  [inline]
 

Get a list of menus on the server.

Example: 


 try {
   Server server("localhost", "Demo", "");
   NameList names;
   server.getListCharMenu(names, NameList().add("User").add("Group"), NameList());
   NameList::iterator iter = names.begin();
   for (; iter != names.end(); iter++) {
       cout << (*iter).getName().c_str() << "\n"s;
   }
 } catch (Exception &err) {
   cerr << err.toString().c_str();
 }

Parameters:

  

    
out the list will be stored here.  Pass a NameList.


    
formList a list of for names.  Only menus attached to fields on these forms will be returned.


    
activeLinkList a list of active links.  Only menus used in change field actions by these active links will be returned.


    
timeStamp pass a non-zero timestamp to retrieve only objects modified after that time.


  




Returns:
none
 


Exceptions:

  

    
Exception 

void rtl::Server::getListCharMenu (  AssignableT< ARNameList > &  out,
unsigned int  timeStamp = 0
)  [inline]
 

Get a list of menus on the server.

Example: 


 try {
   Server server("localhost", "Demo", "");
   NameList names;
   server.getListCharMenu(names);
   NameList::iterator iter = names.begin();
   for (; iter != names.end(); iter++) {
       cout << (*iter).getName().c_str() << "\n"s;
   }
 } catch (Exception &err) {
   cerr << err.toString().c_str();
 }

Parameters:

  

    
out the list will be stored here.  Pass a NameList.


    
timeStamp pass a non-zero timestamp to retrieve only objects modified after that time.


  




Returns:
none
 


Exceptions:

  

    
Exception 

void rtl::Server::getListEntryWithFields (  AssignableT< AREntryListFieldValueList > &  out,
const std::string &  form,
const Qualifier &  qualifier,
const IdList &  idList,
const SortList &  sortList,
unsigned int  firstRetrieve = 0,
unsigned int  maxRetrieve = 0,
unsigned int *  numMatches = NULL
)  [inline]
 

retrieve the entry id and field values for entries that match qualification criteria

Retrieves the entry id and field values for matching entries, equivalent to ARGetListEntryWithFields.

Example: 


 try {
   Server server("localhost", "Demo", "");
   EntryListFieldValueList entries;
   Qualifier qualifier;
   server.parseQualification(qualifier, "'Assigned to' = $USER", "My Form", "");
   server.getListEntryWithFields(entries, "My Form", qualifier, IdList().add(1).add(2).add(4).add(8)); // retrieve all rows assigned to $USER$
   EntryListFieldValueList::iterator iter = entries.begin();
   for (; iter != entries.end(); iter++) {
      EntryListFieldValue &entry = *iter;
      cout << "Entry " << entry.getValues().get(1).toString().c_str() << ": " << entry.getValues().get(8).toString().c_str() << "\n";
   }
 } catch (Exception &err) {
   cerr << err.toString().c_str();
 }

Parameters:
out (out) will contain the matching entries and field values. Pass an EntryListFieldValueList.
form the form name containing the entries
qualifier the qualification criteria
idList the list of field ids for which to retrieve values
sortList a list of field ids and sort order
firstRetrieve the index of the first row to retrieve
maxRetrieve the maximum number of rows to retrieve
numMatches (out) the number of matches. Pass NULL if you do not require this value to be returned (retrieving it does have negative performance impact).
Returns:
none
Exceptions:
Exception 
See also:
parseQualification

Qualification

EntryListFieldValueList

void rtl::Server::getListEscalation (  AssignableT< ARNameList > &  out,
const std::string &  form,
unsigned int  timeStamp = 0
)  [inline]
 

Get a list of escalations on the server.

Example: 


 try {
   Server server("localhost", "Demo", "");
   NameList names;
   server.getListEscalation(names);
   NameList::iterator iter = names.begin();
   for (; iter != names.end(); iter++) {
       cout << (*iter).getName().c_str() << "\n";
   }
 } catch (Exception &err) {
   cerr << err.toString().c_str();
 }

Parameters:

  

    
out the list will be stored here.  Pass a NameList.


    
form the form for which to retrieve escalations.


    
timeStamp pass a non-zero timestamp to retrieve only objects modified after that time.


  




Returns:
none
 


Exceptions:

  

    
Exception 

void rtl::Server::getListField (  AssignableT< ARInternalIdList > &  out,
const std::string &  form
)  [inline]
 

Get a list of fields on a form.

Example: 


 try {
   Server server("localhost", "Demo", "");
   IdList ids;
   server.getListField(ids);
   NameList::iterator iter = ids.begin();
   for (; iter != ids.end(); iter++) {
       cout << (*iter).getId() << "\n"s;
   }
 } catch (Exception &err) {
   cerr << err.toString().c_str();
 }

Parameters:

  

    
out the list will be stored here.  Pass an IdList.


    
form the name of the form containing the fields.


  




Returns:
none
 


Exceptions:

  

    
Exception 

void rtl::Server::getListFilter (  AssignableT< ARNameList > &  out,
const std::string &  form,
unsigned int  timeStamp = 0
)  [inline]
 

Get a list of filters on the server.

Example: 


 try {
   Server server("localhost", "Demo", "");
   NameList names;
   server.getListFilters(names);
   NameList::iterator iter = names.begin();
   for (; iter != names.end(); iter++) {
       cout << (*iter).getName().c_str() << "\n";
   }
 } catch (Exception &err) {
   cerr << err.toString().c_str();
 }

Parameters:

  

    
out the list will be stored here.  Pass a NameList.


    
form the form for which to retrieve filters.


    
timeStamp pass a non-zero timestamp to retrieve only objects modified after that time.


  




Returns:
none
 


Exceptions:

  

    
Exception 

void rtl::Server::getListSchema (  AssignableT< ARNameList > &  out,
const IdList &  idList,
const std::string &  name,
unsigned int  flags = AR_LIST_SCHEMA_ALL | AR_HIDDEN_INCREMENT,
ARTimestamp  timeStamp = 0
)  [inline]
 

Get a list of schemas (forms) that contain the specified fields and/or have a specific relationship to another form.

Example: 


 try {
   Server server("localhost", "Demo", "");
   NameList names;
   server.getListSchema(names, IdList().add(AR_RESERV_PASSWORD); // retrieve all forms containing the password field
   NameList::iterator iter = names.begin();
   for (; iter != names.end(); iter++) {
       cout << (*iter).getName().c_str() << "\n";
   }
 } catch (Exception &err) {
   cerr << err.toString().c_str();
 }

Parameters:

  

    
out the list will be stored here . Pass a NameList.


    
idList a list of field ids.  Forms containing all of the fields will be returned.  Pass an empty list to return forms regardless of fields.


    
name form name.  Only used if flags contains AR_SCHEMA_UPLINK or AR_SCHEMA_DOWNLINK.


    
flags flags identifying which forms to retrieve.  Default is all forms, including hidden forms.


    
timeStamp pass a non-zero timestamp to retrieve only objects modified after that time.


  




Returns:
none
 


Exceptions:

  

    
Exception 

void rtl::Server::getListSchema (  AssignableT< ARNameList > &  out,
unsigned int  flags = AR_LIST_SCHEMA_ALL | AR_HIDDEN_INCREMENT,
ARTimestamp  timeStamp = 0
)  [inline]
 

Get a list of schemas (forms) on the AR System server.

Example: 


 try {
   Server server("localhost", "Demo", "");
   NameList names;
   server.getListSchema(names);
   NameList::iterator iter = names.begin();
   for (; iter != names.end(); iter++) {
       cout << (*iter).getName().c_str() << "\n";
   }
 } catch (Exception &err) {
   cerr << err.toString().c_str();
 }

Parameters:

  

    
out the list will be stored here.  Typically this is an instance of NameList.


    
flags flags identifying which forms to retrieve.  Default is all forms, including hidden forms.


    
timeStamp pass a non-zero timestamp to retrieve only objects modified after that time.


  




Returns:
none
 


Exceptions:

  

    
Exception 

  




See also:
NameList

void rtl::Server::getListSQL (  AssignableT< ARValueListList > &  out,
const std::string &  sqlCommand,
unsigned int  maxRetrieve = 0,
unsigned int *  numMatches = NULL
)  [inline]
 

retrieve values from execution of a SQL statement

Retrieves the values from execution of a SQL statement.

Parameters:
out (out) will contain the rows and values from the SQL execution. Pass a ValueListList.
sqlCommand the SQL command to run
maxRetrieve The maximum number of rows to retrieve
numMatches (out) the number of matches. Pass NULL if you do not require this value to be returned (retrieving it does have negative performance impact).
Returns:
none
Exceptions:
Exception 

void rtl::Server::getListVUI (  AssignableT< ARInternalIdList > &  out,
const std::string &  form
)  [inline]
 

Get a list of vuis (views) on a form.

Example: 


 try {
   Server server("localhost", "Demo", "");
   IdList ids;
   server.getListVUI(ids);
   NameList::iterator iter = names.begin();
   for (; iter != ids.end(); iter++) {
       cout << (*iter).getId() << "\n"s;
   }
 } catch (Exception &err) {
   cerr << err.toString().c_str();
 }

Parameters:

  

    
out the list will be stored here.  Pass an IdList.


    
form the name of the form containing the vuis (views).


  




Returns:
none
 


Exceptions:

  

    
Exception 

void rtl::Server::getMultipleEntries (  AssignableT< ARFieldValueListList > &  out,
const std::string &  form,
const EntryIdListList &  entryIdList,
const IdList &  fields
)  [inline]
 

Retrieve multiple entries.

Retrieve multiple entries, specifying which field values to return. Equivalent to ARGetMultipleEntries.

Parameters:
out (out) will contain the field values for the entries. Pass an EntryListFieldValueList.
form name of form that contains the entry
entryIdList ids of the entries to retrieve
fields ids of the fields for which to retrieve values
Returns:
none
Exceptions:
Exception 
See also:
FieldValueMap

FieldValueList

void rtl::Server::getMultipleFields (  AssignableT< ARFieldInfoList > &  out,
const std::string &  form,
const IdList &  idList,
FieldProperties  propertiesMask = fieldCommonUserProperties
)  [inline]
 

get the definition of fields on a form.

Retrieves the definition of fields on a form, equivalent to ARGetMultipleFields. You can specify which field properties should be returned by passing propertiesMask. (Note: propertiesMask is an enum, but a bitmask will be accepted if you combine values and cast it. An enum is used because static const unsigned int members cannot be declared inline using on header files in C++, unlike Java or .NET). If a property is not retrieved, that property will be empty in the returned Field object.

Example: 


 try {
   Server server("localhost", "Demo", "");
   FieldMap fieldMap;
   server.getMultipleFields(fieldMap, "User", IdList().add(2).add(8).add(4));
   cout << "Field 8 label is " << fields.get(8).getDisplayInstanceList().get(536870912).get(AR_DPROP_LABEL).toString().c_str() << "\n";
   cout << "Field 2 label is " << fields.get(2).getDisplayInstanceList().get(536870912).get(AR_DPROP_LABEL).toString().c_str() << "\n";
 } catch (Exception &err) {
   cerr << err.toString().c_str();
 }

Parameters:
out (out) the Field collection that will containthe definitions of the requested fields. Typically a FieldMap, but a FieldList will work too.
form the Form name which contains the fields being requested
idList the ids of the fields being requested
propertiesMask which field properties to retrieve.
Returns:
none
Exceptions:
Exception 
See also:
getField

setField

createField

deleteField

Field

FieldMap

void rtl::Server::getServerInfo (  AssignableT< ARServerInfoList > &  out,
const ServerInfoRequestList &  requestList
)  [inline]
 

retrieve server information, such as host name, database type, etc.

Retrieve server information, equivalent to ARGetServerInfo. See ar.h for AR_SERVER_INFO_* values.

Example: 


 try {
   Server server("localhost", "Demo", "");
   ServerInfoMap serverInfo;
   server.getServerInfo(serverInfo, ServerInfoRequestList().add(AR_SERVER_INFO_DB_TYPE));
   cout << "Database type: " + serverInfo.get(AR_SERVER_INFO_DB_TYPE).getValue().toString().c_str() << "\n";
 } catch (Exception &err) {
   cerr << err.toString().c_str();
 }

Parameters:
out (out) will contain the collection of server information. Typically a ServerInfoMap, but a ServerInfoList will work.
requestList the list of requested server information
Returns:
none
Exceptions:
Exception 
See also:
setServerInfo

ServerInfoMap

ServerInfoList

ServerInfoRequestList

StatusList rtl::Server::getStatusList (   )  [inline]
 

Get the status list, if any resulting from the previous call.

Parameters:
none 
Returns:
StatusList

void rtl::Server::lockToAdminRPC (  const std::string &  name  )  [inline]
 

Lock to the RPC Program number of the admin server.

This is a shorthand for setServerPort(0, 390600). Call this is you are updating definitions on the server; it will force all calls to go to the admin server and will therefore always work against a current cache.

Example: 


 try {
   Server server("localhost", "Demo", "");
   server.lockToAdminRPC();
 } catch (Exception &err) {
   cerr << err.toString().c_str();
 }

Parameters:

  

    
name Name of server


  




Returns:
none
 


Exceptions:

  

    
Exception 

void rtl::Server::mergeEntry (  EntryId &  out,
const std::string &  form,
const AssignableT< ARFieldValueList > &  values,
unsigned int  mergeType = AR_MERGE_ENTRY_DUP_MERGE
)  [inline]
 

Import an entry.

Imports an entry, equivalent to ARMergeEntry. This may created an entry, overwrite an entry, or merge new fields values, depending on the data and options.

Parameters:
out (out) will contain the entry id of the updated or created entry.
form name of form to import entry into
values field values for entry. If a value is passed for field 1, it will be used as the entry id.
mergeType one of AR_MERGE_ENTRY_DUP_*, controlling what action to take if an entry with the id already exists. See documentation in ar.h
Returns:
none
Exceptions:
Exception 
See also:
FieldValueMap

FieldValueList

void rtl::Server::parseQualification (  Qualifier &  out,
const std::string &  qualification,
const std::string &  form,
const std::string &  displayTag
)  [inline]
 

Parse a qualification string and return a structure that can be used for getListEntry and getListEntryWithFields.

Parse a qualification string (such as 'Assigned To' = $USER$) into a Qualification object, which is required for getListEntry and getListEntryWithFields. The Qualification object can be reused across any number of calls to getListEntry or getListEntryWithFields. Unfortunately, the API routine that is used to parse the qualification (ARLoadARQualifierStruct) is incredibly expensive, so wherever possible it is a good idea to pre-parse queries into Qualification objects so they are only parsed once.

Example: 


 try {
   Server server("localhost", "Demo", "");
   Qualification qualification;
   server.parseQualification(qualification, "'Assigned To' = $USER$", "My Form", "");
 } catch (Exception &err) {
   cerr << err.toString().c_str();
 }

Parameters:
out Qualification object containing parsed qualification
qualification string containing qualification texts to parse
form name of form to bind qualification to when parsing
displayTag name of view on form to use when resolving field labels, or empty for the default view
See also:
getListEntry

getListEntryWithFields

void rtl::Server::setEntry (  const std::string &  form,
const EntryIdList &  entryId,
const AssignableT< ARFieldValueList > &  values,
ARTimestamp  getTime = 0,
unsigned int  joinOption = AR_JOIN_SETOPTION_NONE
)  [inline]
 

Update an entry.

Updates an entry, equivalent to ARSetEntry.

Parameters:
form name of form to update entry in
entryId entry id of entry to update
values field values to update for the entry.
getTime time the entry was retrieved, or 0 to force an update regardless of other potential users updating the record
joinOption either AR_JOIN_SETOPTION_NONE, or AR_JOIN_SETOPION_REF
Returns:
none
Exceptions:
Exception 
See also:
FieldValueMap

FieldValueList

void rtl::Server::setField (  const std::string &  form,
const Field &  field,
unsigned int  propertiesMask
)  [inline]
 

update the definition of a field on a form.

Updates the definition of a field on a form, equivalent to ARSetField. You can specify which field properties should be saved by passing propertiesMask. (Note: propertiesMask is an enum, but a bitmask will be accepted if you combine values and cast it. An enum is used because static const unsigned int members cannot be declared inline using on header files in C++, unlike Java or .NET).

Example: 


 try {
   Server server("localhost", "Demo", "");
   Field field;
   server.getField(field, "My Form", 8, fieldAllProperties);
   // change the field label
   field.getDisplayInstanceList().get(536870912).set(AR_DPROP_LABEL, "New field label");
   server.setField("My Form", field, fieldDisplayInstanceList);
 } catch (Exception &err) {
   cerr << err.toString().c_str();
 }
Parameters:
form the Form name which contains the field being saved
field the Field to update
propertiesMask which field properties to update
Returns:
none
Exceptions:
Exception 
See also:
getField

createField

deleteField

getMultipleFields

Field

void rtl::Server::setServerInfo (  const AssignableT< ARServerInfoList > &  infoList  )  [inline]
 

update server information.

Update server information, equivalent to ARSetServerInfo. See ar.h for AR_SERVER_INFO_* values.

Example: 


 try {
   Server server("localhost", "Demo", "");
   ServerInfoMap serverInfo;
   serverInfo.set(AR_SERVER_INFO_MAX_F_DAEMONS, Value::IntegerValueImpl(10));
   server.setServerInfo(serverInfo);
 } catch (Exception &err) {
   cerr << err.toString().c_str();
 }

Parameters:
infoList collection of server information values to updates. Either a ServerInfoMap or ServerInfoList.
Returns:
none
Exceptions:
Exception 
See also:
getServerInfo

ServerInfoMap

ServerInfoList

void rtl::Server::setServerPort (  const std::string &  name,
int  portNum,
int  rpcNum
)  [inline]
 

Set the port and/or RPC program number for the AR System Server.

Call this immediately after constructing the Server object, if you need to connect to an AR System Server on a specific port or rpc program number.

Example: 


 try {
   Server server("localhost", "Demo", "");
   server.setServerPort(0, 390600); // 390600 is admin port
 } catch (Exception &err) {
   cerr << err.toString().c_str();
 }

Parameters:
name Name of server
portName port number
rpcNum rpc program number
Returns:
none
Exceptions:
Exception 

The documentation for this class was generated from the following file:
Generated on Thu Dec 29 16:20:28 2005 for RTL by  doxygen 1.4.5