oms_pr_process_discover()
Abstract
Discovers a process(es) from the set of registered processes in the registry by matching the specified attributes.
Syntax
oms_pr_process_discover (neighbor_objid, pr_handle_lptr, attr0_name, attr0_type, attr0_value,...., OPC_NIL)
| Argument | Type | Description |
|---|---|---|
neighbor_objid |
Objid |
object identifier of the module whose neighbors should only be considered for discovering processes [Processes from all the modules are considered if this is specified as OPC_OBJID_INVALID.] |
pr_handle_lptr |
List * |
pointer to a list to store the result of the discovery procedure (see Details). |
attr0_name |
char * |
name of the attribute to be matched. |
attr0_type |
int |
data type of the attribute to be matched (see Details). |
attr0_value |
Vartype |
value of the attribute to be matched. |
OPC_NIL |
sequence terminator. |
Return Type
Compcode
Completion code indicating whether the process discovery procedure matched any processes.
[This return code can be compared to constants OPC_COMPCODE_SUCCESS and OPC_COMPCODE_FAILURE to determine the outcome.]
Example
/* Allocate (and initialize) the list. */
pr_handle_lptr = prg_list_create ();
/* Obtain the process handles that match our query. */
result = oms_pr_process_discover (neighbor_objid, pr_handle_lptr,
name, type, value,
name, type, value,
...
OPC_NIL);
if (result == OPC_COMPCODE_SUCCESS)
{
/* Query but do not modify the elements of the pr_handle_lptr */
/* Remove the elements from the list when you are done, to avoid leaking linked
list cells. */
num_prs = op_prg_list_size (pr_handle_lptr);
for (i = 0; i < num_prs; i++)
{
op_prg_list_remove (pr_handle_lptr, OPC_LISTPOS_TAIL);
}
}
/* Now free the empty list as it is no longer going to be used. */
prg_mem_free (pr_handle_lptr);
Details
This function obtains a process registry process handle for a process matching specific attribute values. The arguments to this procedure are grouped in name-type-value triplets, and all attribute values must match those in the registry record for a match to be returned. A failure status is returned to indicate that no registered processes match the specified attributes.
The arguments to this procedure form a variable length sequence of name-type-value triplets terminated by the symbolic constant OPC_NIL.
The list passed via pr_handle_lptr should be allocated, but empty (containing no elements). The elements returned in pr_handle_lptr must not be freed by the caller, because they are intended as read-only copies of the process handles. However, the elements can be removed from the list via op_prg_list_remove(); the resulting empty list structure can be freed, if necessary.
The following attribute types can be specified:
- OMSC_PR_OBJID
- OMSC_PR_STRING
- OMSC_PR_NUMBER
- OMSC_PR_STRINGLIST
- OMSC_PR_PROHANDLE
- OMSC_PR_ADDRESS
For more details on these attribute types, see Additional Attributes.