The GetObjectsByName method is the implementation behind the QFind Client API that is exposed through the Client. There is a single object version (GetObjectByName) that you can use as a shortcut when you know that only one object will be returned.
The following version accepts a name specification (including wildcards) and an InterfaceDefUID as parameters and returns an IObject.
Public Function GetObjectByName(ByVal pstrName As String, ByVal pstrInterfaceDefUID As String) As IObject
Public Function GetObjectByName(ByVal pstrName As String, ByVal pstrInterfaceDefUID As String, ByVal pobjContainer As ContainerObjectDictionary) As IObject
An example of using this is as follows:
Dim lobjStandardCalendar As IObject = Me.SPFSession.GetObjectByName("Standard Calendar", "ISPFCalendar")
You should only call this method if you are certain the search will product only
one result. Otherwise, the single object that you get back from the query is indeterminate.
The following variants all accept a name specification, an InterfaceDefUID, and a mixture of other parameters and all return an IObjectDictionary.
All methods are overridden so that you can pass in a container, then all the items are retrieved into the container rather than into the master cache collection.
It is recommended to use your own container where possible.
Public Function GetObjectsByName(ByVal pstrName As String,
ByVal pstrInterfaceDefUID As String) As IObjectDictionary
Public Function GetObjectsByName(ByVal pstrName As String,
ByVal pstrInterfaceDefUID As String,
ByVal pobjContainer As ContainerObjectDictionary)
As IObjectDictionary
Once the objects are retrieved, you can iterate through the collection to visit each result. An example of using the first variant is as follows.
Dim lcolMethods As IObjectDictionary = Me.SPFSession.GetObjectsByName("SPC*", "ISPFMethod")
With lcolMethods.GetEnumerator()
Do While .MoveNext()
Dim lobjMethod As IObject = .Value
Loop
End With
The IObjectDictionary uses the .NET dictionaries internally (as opposed to the simple collections), which means that the entries to the collections are DictionaryEntries. For this reason, you cannot use the For Each syntax on the collection. You will notice, however, that .Value is returned as an IObject so you do not need to cast.
In the example below we can specify the UID or Name of the column set we want to use to display the results of the query. Column sets can be configured to show properties on related objects and these related objects will be returned with the query results from the server.
Don't assume that all the objects returned will contain the interface you specified.
There may be objects that will be used when displaying the object.
We pass down MethodUID so that the server knows the original method that invoked the form/API we are making this call from. This allows the server to write conditional code around this.
Public Function GetObjectsByName(ByVal pstrName As String,
ByVal pstrInterfaceDefUID As String, _
ByVal pstrColumnSetName As String,
ByVal pstrMethodUID As String) As IObjectDictionary
Public Function GetObjectsByName(ByVal pstrName As String,
ByVal pstrInterfaceDefUID As String, _
ByVal pstrColumnSetName As String,
ByVal pstrMethodUID As String,
ByVal pobjContainer As ContainerObjectDictionary)
As IObjectDictionary
The next two methods allow a property comparison to be sent with the query. An example of this is:
ISPFBusinessFile~SPFViewInd~=~True|False
This will only return objects where the SPFViewInd property on ISPFBusinessFile is True or False. Another example is to only send back documents whose Revision status is Working or Current.
ISPFDocumentRevision~SPFRevState~=~e1WORKING|e1CURRENT
The final parameter indicates whether to apply the maximum query limit or not, so honor the user's maximum rows to retrieve limit.
Public Function GetObjectsByName(ByVal pstrName As String,
ByVal pstrInterfaceDefUID As String, _
ByVal pstrColumnSetName As String,
ByVal pstrMethodUID As String, _
ByVal pstrQueryPropComparison As String,
ByVal pblnRestrictToMaxLimit As Boolean)
As IObjectDictionary
Public Function GetObjectsByName(ByVal pstrName As String,
ByVal pstrInterfaceDefUID As String, _
ByVal pstrColumnSetName As String,
ByVal pstrMethodUID As String, _
ByVal pstrQueryPropComparison As String,
ByVal pblnRestrictToMaxLimit As Boolean, _
ByVal pobjContainer As ContainerObjectDictionary)
As IObjectDictionary