VARKON Version 1.15 1997-10-24

get_next_gm - Function

Search for entity in GM


Description

Searches the GM hierarchy for an entity. Four parameters and the set_root_gm() routine can be used to control the search process. get_next_gm() searches (traverses) GM sequentially until a suitable entity is found. Next call continues the search starting in the position of the last entity found. When no more entities can be found an id of #0 is returned.

Syntax

get_next_gm(mode, typemask, name, group)

INT	mode;
INT	typemask;
STRING	name*20;
STRING	group*20;

Principal parameters

None.

Optional parameters

mode	- 0 = Full traversal. If next entity is a part this part will also be traversed. Default.
	1 = Restricted (vertical) search. If next entity is a part it will not be entered.
typemask	- Search can be restricted to only one entity type or a combination of entity types by
	adding their type codes into a single typemask. Default = 65535 = any type.
name	- Restricts the search process to entities with a specific name. Entities with name are part,
	group and coordinate systems. Wildcards (*) may be included in name. Default = * =
	any name.
group	- Restricts the search process to entities that are members of a group with specific name.
	Wildcards (*) may be included in the name. Default = * = any group.

Return value

The REF identity of the entity found or #0 if no more entities are present.

Examples

get_next_gm();

This is the simplest form of usage. Returns the id of the next entity in GM without respect to type, name or group membership.

get_next_gm(0, 655535, "*", "AB*")

Returns the identity of the next entity that is member of a group named "AB" or "AB" followed by any combination of letters.

get_next_gm(1,16384,"WALL")

Returns the identity of the next part on this level with name = "WALL".