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

Passing User- and System-Defined Classes

Item passing lets you copy an item from one G2 to another. The item may be a user-defined class, or any system-defined class, including definitions.

Most user-defined classes have user-defined attributes, and all classes have system-defined attributes, such as Notes, Item-configuration, and Names. Item passing lets you determine which user- or system-defined attributes to pass from one G2 to another.

G2 supports item passing in several ways:

Passing an item either as a handle or with an handle, means passing any item with an integer value network handle. Obtaining Network Handles describes how to get and use handles.

Note: User-accessible system-defined attributes are those that are available through the attribute access facility, and which appear in the G2 Class Reference Manual.

Configuring the KB for Passing an Item with Attributes

To configure a KB for item passing using a remote procedure declaration:

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

  2. For items of user-defined classes, ensure that both G2 systems have compatible definitions for the class or classes being passed as discussed in Creating Compatible Definitions.

  3. In the remote G2, create a procedure that declares one or more items or values as its arguments and/or return type. The remote procedure can also include an integer argument if you wish to optionally include a handle for the item you are passing.

  4. In the local G2, create a remote procedure declaration with the correct syntax for passing an item with user- and/or system-defined attributes, as described in Value and Item Passing Arguments and Return Types for RPCs.

  5. In the local G2, start or call the remote procedure across the appropriate data interface object.

Passing an Entire Item or a Specific Attribute Set

By default, passing an item automatically includes all of its user-defined attributes and none of its system-defined attributes. You can include or exclude user-defined attributes explicitly. Including one or more user-defined attributes excludes the remainder. Excluding one or more user-defined attributes includes the remainder.

You can include all system attributes or those that you declare explicitly, but you cannot exclude system attributes as you can user attributes.

You can specify one or more of these possibilities as part of the remote procedure declaration syntax.

Item-passing Examples in this Chapter

You use a remote procedure declaration to specify which attributes to pass to or from a remote G2.

The including or excluding of user- or system-defined attributes is specified through the grammar of a remote procedure declaration. Though a remote procedure declaration can include multiple variations of its grammar, this section describes the grammatical options separately. You can combine these options in any syntactically meaningful way. For example, two topics discussed are:

Within a remote procedure declaration, you can combine such statements, along with others, to include some attributes and to exclude others.

Passing A Copy of Any Item

By default, an item is passed as a copy, with no handle, with all of its user-defined attributes, and none of its system attributes.

To pass an item with all user-defined attributes:

You can pass an item with one or more of its user attributes, by specifying what to include. Explicitly including one or more user-defined attributes excludes the remainder.

Including and Excluding Attributes

The next few sections describe the various ways in which you declare a remote procedure call to include or exclude user- and system-defined attributes through the item passing argument grammar.

An important point to note is that including or excluding any user- or system-defined attributes can be declared only once for each argument. Making such inclusions and exclusions can, therefore, be applicable to multiple items. As an example, an argument for a remote procedure xproc consists of a sequence. The sequence being passed to xproc consists of several instances of the same class:

While the item passing argument grammar permits you to declare which attributes of the items in an item, sequence, or structure you wish to include or exclude, the specification applies to all items in the same argument. Thus, in the example given here, if the MY-OBJECT class included attributes temperature and volume, and you specified the remote procedure declaration to include only the temperature attribute:

all four objects would be passed with the temperature attribute, and none could include the volume attribute.

Passing An Item Including User-Defined Attributes

You can pass an item by explicitly including one or more of its user-defined attributes. Using the including only the user attributes grammar excludes all remaining user-defined attributes by default.

To pass an item including certain user-defined attributes:

When specifying more than one attribute, a colon (:) is required after the attributes statement, and the attributes themselves are separated with a comma (,).

Example of Passing an Item Including User-Defined Attributes

If you specify more than one class in the list of procedure arguments, separate the class and its attribute specifications within parenthesis, as in this example, passing a user-defined subclass of PROCEDURE as a procedure argument:


Passing An Item Excluding User-Defined Attributes

You can pass an item with all of its user-defined attributes, except for those you exclude. Explicitly excluding one or more user-defined attributes includes the remainder. By default, passing any item includes all of its user-defined attributes and none of its system-defined attributes.

To pass an item excluding certain user-defined attributes:

When specifying more than one attribute, a colon (:) is required after the attributes statement, and the attributes themselves are separated with a comma (,).

Passing Attributes With Object Values

User-defined classes can include attributes whose value is an object. An attribute with an object value can be:

Further, the object that is the value of an attribute can itself have attributes with object values.

When passing object values, keep in mind that:

To pass the value of one or more object attributes given by a variable or a parameter, you must explicitly include the statement:

in addition to any other statements about which user- or system-defined attributes to pass. In the absence of this statement, G2 passes the object, but any attributes whose values are given by a variable or parameter do not have values.

Example of Passing an Attribute With an Object Value

In this example, the local G2 defines an AUTO class that includes a tire-pressure attribute, which is given by a float-variable. The purpose of the RPC is to pass:

To do this, use a remote procedure declaration such as:


Passing An Item With System-Defined Attributes

You can pass one or more user-accessible system-defined attributes, or those that you include explicitly. The system attributes that you can pass are those that are accessible through the attribute access facility and that appear in the G2 Class Reference Manual.

While many system attributes are user-accessible, not all attributes for every item are available. For example, you can access most attributes of a workspace, but not the data structure that represents the items that reside upon a workspace. Thus, passing a workspace from one G2 to another results in a new workspace on the remote system, but without any of its associated items. Similarly, you can pass an item, but if the item has a subworkspace, its subworkspace is not passed to the remote system.

To determine which system attributes are accessible for each G2 item, see the G2 Class Reference Manual.

You can pass an item with one or more of its system-defined attributes. By default, passing any item excludes all of its system-defined attributes.

To pass an item including one or more system-defined attributes:

If an item has more than one name and you specify:

only the first name is passed.

Specifying a system attribute that is not applicable for the class, such as entering current value of variable-or-parameter when the item is not a variable or parameter subclass, passes the item to the remote G2 process with only its appropriate user- or system-attributes.

Note: Using the special grammar for passing the name of an item, the current value of a variable or parameter, or the history of a variable or parameter, is the recommended way of passing each of these three system attributes.

Examples of Passing System-Defined Attributes

The next example specifies two arguments of a user-defined subclass of PROCEDURE. It passes all system-defined attributes with the first argument, and includes only two attributes with the second:


This example shows the remote procedure declaration passing the current value and the history of an integer variable, and the name of a TANK item:


Passing Both User- and System-Defined Attributes

You can specify both user- and system-defined attributes for a single remote procedure argument, using any combination of values. Here is an example of how to pass history values along with a user-defined attribute.


Passing An Item With Attributes and A Handle

The ability to pass an item handle, in addition to any user or system attributes, has been implemented for use in G2 Gateway. While the grammar to support this functionality exists, using the optional [with handle] statement is not applicable to G2-to-G2 item passing.

Specifying One or More Remaining Arguments

After declaring the specific arguments of a procedure, you can optionally specify zero or more remaining arguments of one type using the all remaining statement as the last part of the remote procedure declaration.

To specify a remaining number of arguments:

Example of Passing Remaining Arguments

This example declares a procedure with the first three arguments as:

The remaining arguments are declared as all remaining item-or-value:


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

Copyright © 1997 Gensym Corporation, Inc.