Name

omni_group_variables − The omni_group_variables procedure allows a user to read or write multiple variables. 

To use this procedure, do the following:

1Set the context variable to be used to zero. 

2Call the omni_group_variables with the pointer to the context, variable handle, alternate access handle, pointer to data, modifier handle and pointer to iosb for one variable. 

3Repeat step 2  as many times as necessary for different variables, using the same context. 

4Call the omni_get_value[_a] or omni_put_value[_a], substituting the context value for the variable handle, and omitting the object handle, method handle, pointer to data, and modifier handle. 

5The group context is in effect until an omni_end_list with the context specified is done. 

The iosb that is passed in each time to the omni_group_variables function indicates whether the transaction was successful on the variable. 

If variables are grouped together and the user passes to omni_get_value[_a] or omni_put_value[_a] a pointer to an iosb, that iosb represents the general transaction completion. 

Syntax

extern unsigned long int omni_group_variables (
       omni_l_context       ∗context,
       omni_l_handle        object_handle,
       omni_l_handle        method_handle,
       void                 ∗pdata,
       unsigned long int    pdata_length,
       omni_l_handle        modifier_object,
       omni_r_iosb          ∗iosb);

Arguments

contextaccess: read only mechanism: by reference A variable for use by DEComni. 

object_handleaccess: read only mechanism: by value In a client call, the identifier of a loaded variable definition. 

In a server call, the contect value returned by the omni_get_indications procedure call that delivered the write indication. 

method_handleaccess: read only mechanism: by value optional argument Method_handle modifies the default presentation of a variable. 

pdataaccess: read only mechanism: by reference Pdata is a pointer to a data structure that receives the value of the object or to a data structure that contains the value of the object. 

pdata_lengthaccess: read only mechanism: by value The size of the pdata to receive data. 

modifier_objectaccess: read only mechanism: by reference optional argument Modifier_object is reserved for future use. 

iosbaccess: read only mechanism: by reference optional argument The DEComni I/O status block.  The iosb parameter is the address of the status block. 

Usage Notes

Do not use an omni_end_list call on a group variable that has an outstanding operation.  If an omni_end_list call is made while an outstanding operation exists, the group context will not be valid. 

In the following example segment code, variables A, B and C are grouped together using IosbA, IosbB and IosbC for the variable iosb’s. The general transaction iosb used is TransIosb. 

    omni_l_context context = 0;
    omni_r_iosb IosbA, IosbB, IosbC, TransIosb;
    /∗ group variable ’A’ ∗/
    status = omni_group_variables(
                &context,
                objecthandleA,
                altAccesshandleA,
                pdataA,
                modifierhandleA,
                &iosbA );
    /∗ group variable ’B’ ∗/
    status = omni_group_variables(
                &context,
                objecthandleB,
                altAccesshandleB,
                pdataB,
                modifierhandleB,
                &iosbB );
    /∗ group variable ’C’ ∗/
    status = omni_group_variables(
                &context,
                objecthandleC,
                altAccesshandleC,
                pdataC,
                modifierhandleC,
                &iosbC );
    /∗ issue the get value request for ’A’, ’B’ and ’C’ ∗/
    status = omni_get_value(
                &invokeid,
                context,
                NULL,
                NULL,
                NULL,
                &transiosb,
                &ctrlblock );
    status = omni_end_list(
                context
                          );

If transiosb returns with a general error then the get value request did not complete properly.  If the request completed properly, iosbA, iosbB and iosbC indicates whether the read of each of those variables completed successfully.  If variable "A" was read properly, the data returned will be in pdataA. If variable "B" was read properly, the data returned is pdataB; and if variable "C" was read properly, the data returned is pdataC.