| Prev | Next | Start of Chapter | End of Chapter | Contents | Glossary | Index | Comments | (8 out of 11)

Passing an Item as a Network Handle

You can configure your KB to pass an item as a network handle only.

To pass an item as a handle:

where class-name is any system- or user-defined G2 class.

You can pass an item as a handle as one of two or more arguments or return types by entering the item argument in parentheses, followed by a comma if any arguments follow.

To pass an item as a handle with other arguments:

Configuring the KB for Item Passing as a Network Handle
To configure a KB for item passing as a handle:

  1. Create a data interface object and complete it as explained in Creating Data Interface Objects.

  2. Create a procedure on the remote system that declares an integer (for the network handle) as an argument or a return value.

  3. Create a remote procedure declaration with the correct syntax for passing an item as a handle, as described in Value and Item Passing Arguments and Return Types for RPCs.

  4. Start or call the remote procedure from the local G2 across the appropriate interface.

Obtaining Network Handles

 A network handle is an integer used to refer to an item. If you register the item in the local G2, the remote G2 can then refer to it as a reference.

An item can acquire a network handle in three ways. The third way is applicable only to GSI interfaces.

  1. Automatically, by declaring that an item is a handle in the argument specification of a remote procedure declaration.

    During remote procedure invocation, if an item does not have a network handle, G2 registers it automatically, associating the item with the ICP interface object across which the procedure has been invoked. The item's handle is then passed to the remote procedure.

  2. Manually, by using the g2-register-on-network system procedure, described in the next section.

    The system procedure returns a network handle for any item passed to it, associating the item with the specified interface object. The interface object could be either a data interface object, or a GSI interface object, because item passing works through GSI interfaces as well.

  3. Automatically, through the GSI data service. This applies only to items that are a subclasses of GSI-data-service being data served through a GSI interface object.

For more information about data service and item passing in GSI, see the G2 Gateway Bridge Developer's Guide.

Obtaining a Network Handle Using a System Procedure

To obtain a network handle for an item manually, use this system procedure:

Example of Obtaining a Network Handle

 For example, the next procedure accepts any item and any data interface object as its arguments, and returns a handle.


You cannot maintain network handles across interface activations. You must register items each time you activate a data interface object.

You can typically acquire network handles automatically, using the remote procedure argument declarations. If, however, the local process requires information about network handles before they are acquired automatically during a remote procedure call, you can acquire them manually, using the system procedure.

The following system procedures work in conjunction with item passing and network handles:

To do this... Use this system procedure...
Register an item on the network to obtain a network handle associated with the item and the ICP interface object.
g2-register-on-network
Deregister an item from the network handle number assigned it, and from the interface. G2 may use that network handle again to assign to a new item during network registration.
g2-deregister-on-network
Obtain the item associated with a network handle number and its interface.
g2-get-item-from-network-handle
Obtain the network handle associated with an item already registered with an interface, whether through the g2-register-on-network system procedure or through a remote procedure invocation.
g2-get-network-handle-from-item

For more information on the network registering, and other system procedures, see the G2 System Procedures Reference Manual.

Example of Passing an Item as a Handle

The next diagram shows an example of how you declare a remote procedure with a float argument type, followed by a procedure class as a handle (in separate parentheses), with an integer return type value. The extra spaces in the example are for clarity and are not required.


| Prev | Next | Start of Chapter | End of Chapter | Contents | Glossary | Index | Comments | (8 out of 11)

Copyright © 1997 Gensym Corporation, Inc.