NextCtree

Change to the next registered c-tree Plus instance.

Short Name

NXTCTREE()

Type

Low-level function

Declaration

pTEXT NextCtree()

Description

NextCtree() cycles to the next available c-tree Plus instance.

When multiple instances of c-tree Plus are established with RegisterCtree(), control blocks are connected via a link list. The last control block points back to the first. Therefore, a NextCtree() call when the last instance is current results in the first instance becoming current.

Repeated calls to NextCtree() result in continually looping through all c-tree Plus instances. In the example program ctlxmg, the reference name of the first instance is saved to determine the “end-of-instances”.

Return

A successful NextCtree() call returns the pointer to the instance reference name. Each instance reference name, up to 31 bytes and a NULL terminator in length, is originally registered with c-tree Plus using RegisterCtree(). If there are no active instances, a NULL will be returned.