List/Query Methods

This article contains the following topics:
casm171
This article contains the following topics:
Two paradigms are available for working with lists. One paradigm uses a list handle for referring to and making queries on a server-side list and the other simply performs a SQL-like select.
If you need to maintain reference to a static list, use the methods that return list handles. These methods are especially useful when working with very large lists. For example, your application may need to perform operations using the entire table of 10,000 Contacts. Downloading values for all 10,000 at once could result in an unacceptable performance lag (this condition is actually prevented by the system -- see Where Clauses). With a list handle, however, you can select a range of rows upon which to query.
The primary drawback to using a list handle is the extra method calls it requires. At least two or three calls are necessary, as indicated by the following:
  • One to get the handle
  • A second (or third) to retrieve values
  • A final call to free the list
You need to balance the amount of remote method calls versus the expected amount of data returned.
CA SDM restricts the amount of data that can be returned from any one list. For more information, see Where Clauses.
doSelect
The following parameters apply to the doSelect method:
Parameter
Type
Description
SID
Integer
Identifies the session retrieved from logging in.
objectType
String
Identifies the object type (factory) to query.
whereClause
String
(Optional) Identifies the where clause for the query.
maxRows
Integer
Indicates the maximum number of rows to return. Specify -1 to return all rows.
Note:
Regardless of the integer specified, CA SDM will return a maximum of 250 rows per call.
attributes
String[]
Identifies the attribute list for which to fetch values. Dotted-attributes are permitted. If this field is blank, all value-based attributes are returned. These attributes cannot be defined as LOCAL in the majic definition file. LOCAL attributes are temporal; they have no database storage.
Description
Performs an SQL-like select on a specified object table. Supply one or more attributes you want fetched from the objects that match the supplied where clause.
Returns
A sequence of <UDSObject> elements. The following format applies:
<UDSObjectList> <UDSObject> <Handle> <Attributes> <AttributeNameA> <AttributeValueA0> <AttributeValueA1> <AttributeNameB> <AttributeValueB0> ...
XML Element
Type
Description
N/A
Specifies the standard UDSObject element containing the handle and requested attribute values.
<UDSObjectList>
Sequence
Contains a <Handle> element and an <Attributes> sequence.
For example, if the method used is the following:
String[] myArray = ["last_name", "first_name"] doSelect(mySID, "cnt", "last_name LIKE 'J%'", 2, myArray)
The return could be the following:
<UDSObjectList> <UDSObject> <Handle>cnt:555A043EDDB36D4F97524F2496B35E75</Handle> <Attributes> <AttributeName>last_name</AttributeName> <AttributeValue>Johnson</AttributeValue> <AttributeName>first_name</AttributeName> <AttributeValue>Carol</AttributeValue> </Attributes> </UDSObject> <UDSObject> <Handle>cnt:555A043EDDB36D4F97524F2496B35E76</Handle> <Attributes> <AttributeName>last_name</AttributeName> <AttributeValue>Jones</AttributeValue> <AttributeName>first_name</AttributeName> <AttributeValue>Ron</AttributeValue> </Attributes> </UDSObject> </UDSObjectList>
doQuery
The following parameters apply to the doQuery method:
Parameter
Type
Description
SID
Integer
Identifies the session retrieved from logging in.
ObjectType
String
Identifies the object type (factory) to query.
WhereClause
String
(Optional) Identifies the where clause for the query.
Description
Performs an SQL-like select for the specified object type. It also returns a
list handle
that
points to a list of the rows returned from the query, where each row represents a CA SDM object that matched the supplied where clause. The caller can fetch values for the list rows using getListValues ().
For more information about where clauses, see Where Clauses.
The object list is stored on the CA SDM server and consumes system resources. The caller is responsible for freeing the list with freeListHandles(). Leaving a list in memory may increase memory for the process beyond the 2GB limit, resulting in memory leaks and can cause system failure.
Lists created with this function are homogenous, meaning the objects are all the same type, and they are static, meaning the list never changes even if a data change to an object excludes it from the initial where clause.
Returns
A list handle that must be freed with freeListHandle().
XML Element
Type
Description
<listHandle>
Integer
Identifies the list handle.
<listLength>
Integer
Identifies the length of the list generated.
 
getListValues
The following parameters apply to the getListValues method:
Parameter
Type
Description
SID
Integer
Identifies the session retrieved from logging in.
ListHandle
Integer
Identifies the list handle obtained with a previous call.
StartIndex
Integer
Identifies the position in the list from which to begin fetching.
EndIndex
Integer
Identifies the last list position from which to fetch. Specify -1 to fetch all rows from StartIndex.
Note:
Regardless of the integer specified, Web Services will return a maximum of 250 rows per call.
AttributeNames
String[]
Identifies an array of one or more attribute names for which you want to fetch values.
Description
Returns attribute values for a range of objects in a list. For example:
< UDSObjectList > <UDSObject> <Handle> <Attributes> <AttributeName0> <AttributeName1>
Returns
This method has the following returns:
XML Element
Type
Description
<UDSObjectList>
Sequence
Identifies the outer Element, which contains a sequence of <UDSObject> elements.
N/A
Contains a <Handle> element and <Attributes> sequence.
 
freeListHandles
The following parameters apply to the freeListHandles method:
Parameter
Type
Description
SID
Integer
Identifies the session retrieved from logging in.
Handles
Integer[]
Identifies an array of list handles to free.
Description
Frees the server-side resources for a list and invalidates the list handles. This method should be called whenever a list reference is no longer needed.
Returns
Nothing.
getRelatedList
The following parameters apply to the getRelatedList method:
Parameter
Type
Description
SID
Integer
Identifies the session retrieved from logging in.
ObjectHandle
String
Identifies the object handle.
ListName
String
Identifies a list-type attribute name of the object.
Description
Returns a list handle for list (QREL or BREL) attribute of an object. For example, the request object has a related list named “children”, which is a list of its child requests. The Request’s Activity Log (“act_log” or “act_log_all”) is another example.
To retrieve information about an object’s list attributes, refer to the object schema (majic) documentation or use getObjectTypeInformation().
Returns
The following:
XML Element
Type
Description
<listHandle>
Integer
Identifies the list handle.
<listLength>
Integer
Identifies the length of the list generated.
 
getRelatedListValues
The following parameters apply to the getRelatedListValues method:
Parameter
Type
Description
SID
Integer
Identifies the session retrieved from logging in.
objectHandle
String
Identifies the object handle.
listName
String
Identifies a list-type attribute name for the object.
numToFetch
Integer
Signifies the maximum number of rows to return.
Cannot be zero
Specify -1 to return all rows
Note:
Regardless of the integer specified, Web Services can return a maximum of 250 rows per call.
attributes
String[]
Identifies an array of one or more attribute names for which to fetch values. Dotted names are permitted.
getRelatedListValuesResult
String Holder
Identifies the String Holder object for capturing returned data.
numRowsFound
Integer Holder
Identifies the Integer Holder object for capturing returned data.
Description
Returns values for lists related to a specific object. The lists must be defined as a QREL or BREL. Use the LREL methods to query LREL types.
For example, the request object has a related list named “children”, that is a list of its child requests. This method is a list handle-free alternative to getRelatedList(). The return format is similar to getListValues(), as indicated by the following:
<numRowsFound> < UDSObjectList > <UDSObject> <Handle> <AttributeName0> <AttributeName1>
You can retrieve information for object list attributes using object schema (majic). An alternative method is to use getObjectTypeInformation().
Returns
This method has the following returns:
XML Element
Type
Description
<getRelatedListValuesResult>
N/A
Identifies the outer element, <UDSObjectList>, that contains a sequence of <UDSObject> elements. Each <UDSObject> element contains a <Handle> element and zero or more <AttributeNameX> elements.
<numRowsFound>
Integer
Indicates the total number of rows in the queried list.
Note:
The total number of rows is not necessarily the number of rows returned.
 
getPendingChangeTaskListForContact
The following parameters apply to the getPendingChangeTaskListForContact method:
Parameter
Type
Description
SID
Integer
Identifies the session retrieved from logging in.
contactHandle
String
Identifies the contact handle.
Description
Returns a list handle representing all the “pending” change order workflow tasks assigned to a contact. A “pending” task is an active workflow task with a status that permits task updates.
Returns
The following:
XML Element
Type
Description
<listHandle>
Integer
Identifies the list handle.
<listLength>
Integer
Identifies the length of the list generated.
 
getPendingIssueTaskListForContact
The following parameters apply to the getPendingIssueTaskListForContact method:
Parameter
Type
Description
SID
Integer
Identifies the session retrieved from logging in.
contactHandle
String
Identifies the contact handle.
Description
Returns a list handle representing all the “pending” Issue tasks assigned to a contact. A “pending” task is an active task with a status that permits task updates.
Returns
The following:
XML Element
Type
Description
<listHandle>
Integer
Identifies the list handle.
<listLength>
Integer
Identifies the length of list generated.
 
getNotificationsForContact
The following parameters apply to the getNotificationsForContact method:
Parameter
Type
Description
SID
Integer
Identifies the session retrieved from logging in.
contactHandle
String
Identifies the contact handle.
queryStatus
Integer
(Optional) Identifies the target of the notifications.
Description
Returns a list of notifications (‘lr’ objects) for a contact.
You can query on a specific status for the notifications with the
queryStatus
field, which is useful for returning, for example, only non-cleared messages. The possible
queryStatus
values are as follows:
  • -1
    -- Fetch all notifications
  • 0
    -- Fetch non-cleared notifications (those with a status value of less than 7)
  • 1
    -- Fetch cleared notifications (those with a status value of 7, 8 or 9)
Returns
The following:
XML Element
Type
Description
<listHandle>
Integer
Identifies the list handle.
<listLength>
Integer
Identifies the length of the list generated.