SPI Common Extensions Manual

Extended SPI Concepts

SPI Common Extensions Manual—427508-001

2-5

Retrieving Object Names

To retrieve an object name (ZCOM^TKN^OBJNAME) from a message buffer:

1. Assume that you want to retrieve the first occurrence of ZCOM^TKN^OBJNAME,

which has an index of 1:

INT size;

INT(32) info;

info := ZCOM^TKN^OBJNAME;

Assigning ZCOM^TKN^OBJNAME to info puts the information that is required to

find the object-name value in memory into the info variable. This is required

because the parameter is normally passed by reference and not by value.

Any number of objects controlled by a subsystem can be contained in a message.

The first occurrence has index value 1, the second has index value 2, and so on.

2. Obtain the length of the object-name value (use the special token ZSPI-TKN-LEN):

status := SSGETTKN(message^buffer

,ZSPI^TKN^LEN

,info

,size);

If you try to put a token value into a variable that is too small to hold it, you lose the

excess information, and your application could malfunction.

3. Compare the length of the object name to the maximum acceptable length. If the

length is acceptable, retrieve the value:

IF size > ZCOM^VAL^OBJNAME^LEN

THEN its^too^long

ELSE status := SSGETTKN(message^buffer

,ZCOM^TKN^OBJNAME

,objname

,1);

Hierarchical Naming

Subsystems that define an object-type hierarchy usually reflect that hierarchy in the

names assigned to their objects. Each object-name class provides a delimiter

character for separating the hierarchical levels in an object name. Further, field support

for wild cards in object-name templates is specifically suited to this naming scheme.

Hierarchical names can convey enough information to identify an object on the basis of

its name alone, which is an advantage for someone trying to interpret the name.

For example, FARM, ORCHARD, and TREE are three object types defined by a

subsystem such that objects of type TREE are subordinate to objects of type

ORCHARD, and objects of type ORCHARD are subordinate to objects of type FARM.

$A is the name of a farm, #B is an orchard, and C is a tree. If the delimiter character for