Tree Classes

This chapter provides an overview of tree classes and discusses the following topics:

• Relationships between different tree classes.

• Collections in the tree classes.

• Error handling with trees.

• Leaves and nodes insert verification.

• Data types for tree objects.

• Scope of the tree objects.

• Tree classes implementation.

• Restrictions on trees when used as a SmartNavigation data source.

• Tree classes reference.

Understanding Tree Classes

Using the tree classes in your PeopleCode, you have access to all the functionality of PeopleSoft Tree Manager. Your application should instantiate the appropriate tree objects when it must work with the tree system database data, call the appropriate methods and properties, then close the objects when it is finished.

Creating or deleting a tree object does not create or delete tree system database information. You must call the method for that tree object directly to create or delete database information, that is, the Create or Delete method.

One instance of a tree or tree structure object can be created to work on multiple database entities. However, only one tree or tree structure can be open at a time. If you open a Tree before closing the one that’s currently open, you receive an error. You must explicitly close a tree or tree structure (using the Close method) before you try to open a second one.

All of the classes, and most of the properties and methods that make up the Tree Classes have a GUI representation in PeopleSoft Tree Manager. This document assumes that the reader is familiar with PeopleSoft Tree Manager.

The following classes make up the tree classes:

• Branch Collection

• Leaf

• Level

• Level Collection

• Node

• Tree

• Tree Structure

With most of the classes of objects in PeopleTools, when you use a Getxxx method, you are fully instantiating an object. However, for the tree class, when you use GetTree (from the Session object), you get a closed tree. A closed tree is a tree object with just the key fields filled in. The rest of the data is not present. To open the tree, you must use the Open method. Working with closed trees can improve your performance. The same applies to a tree structure: it’s closed when you get it from the Session object, and you must open it before you can access its properties or change it.

There aren’t any built-in functions for the tree classes: objects are instantiated from identifiers, from other objects, or from a Session object.

Using the GenerateTree function, you can produce a GUI representation of a tree in the PeopleSoft Pure Internet Architecture.

See Also

TreeDetailInNode

Session Class

Using the GenerateTree Function

Introduction to PeopleSoft Tree Manager

Relationships Between Different Tree Classes

The following diagram shows the tree classes and their relationships. Objects at the tip of the arrowhead are accessed or created from the object at the left of the arrowhead. Squares indicate objects. Ovals indicate collections.

Tree classes and their relationships

• From the session object, you can get identifiers for a tree or a tree structure.

• From the level collection object, you can instantiate a level object.

• From the branch collection object, you can get an identifier for a branch.

• From the tree object, you can instantiate a tree, a tree structure, a branch collection, a leaf, a node, and a level collection.

• From the node object, you can instantiate a leaf object or a node object.

• From the leaf object, you can instantiate a leaf object or a node object.

Collections in the Tree Classes

A collection is a set of similar things, like a group of already existing branches or levels. Like everything else in the tree classes, collections have a GUI representation. For example, when you find an existing branch from PeopleSoft Tree Manager, you get a dialog that lets you select the branches you want. This dialog box data is represented in PeopleCode as the tree level collection.

Example of level collection

The following collections are part of the tree classes:

• Branch collection

• Level collection

Error Handling With Trees

The tree classes log descriptive information regarding errors and warnings to the PSMessages collection, instantiated from a session object.

In your program, use the PSMessages collection to identify and report to the user any errors that are encountered during processing.

The tree classes log errors "interactively", that is, as they happen. For example, suppose you had created a new tree, and were setting the effective date using the effective date property (EffDt). If you used an invalid value for the effective date, the error would be logged in the PSMessages collection as soon as you set the value, not when you saved the tree.

When you want to check for errors depends on your application. However, if you check for errors after every assignment, you may see a performance degradation.

One way to check for errors is to check the number of messages in the PSMessages collection, using the Count property. If the Count is 0, no error or warning messages have been logged to the PSMessages collection.

Local ApiObject &MYSESSION; 
Local ApiObject &ERRORCOL; 
Local ApiObject &TREE, TREELIST; 

&MYSESSION = %Session; 
 
If &MYSESSION Then 
   /* connection is good */ 
 
&MyTree = &Session.GetTree(); 
    /* open a tree */ 
   &TreeReturn = &MyTree.Open("", "", "PERSONAL_DATA", "1999-06-01", "",true); 
    ​/* Do error checking */ 
    
   &ERRORCOL = &MYSESSION.PSMessages; 
   If (&ERRORCOL.Count <> 0) Then 
      /* errors occurred - do processing */ 
   Else 
      /* no errors */ 
   End-If; 
   Else 
   /* do processing for no connection */ 
End-If;

You can also do an error check based on the return value of your API calls

If ALL(&TreeReturn) then
   /* processing errors */
End-if:

See Also

Error Handling

Leaves and Nodes Insert Verification

InsertChildLeaf, InsertSibNode, InsertChildNode, and so on, can return False or a Null object reference, depending upon the type of error encountered. You may want to declare references to new leaves or nodes as type ANY until after you verify they were actually created. You can do this by using the None or All PeopleCode functions to determine whether a valid Leaf or Node Object was created. If a Leaf or Node object was created ALL()returns True and None() returns False.

&NewLeaf = &RootNode.InsertChildLeaf("8000", "8999"); 
If NONE(&NewLeaf) Then 
   /* Leaf not inserted, do error processing */ 
   &Messages = &Session.PSMessages; 
   If &Messages.WarningPending Then 
      /* do error processing */ 
   End-if; 
End-if;

See Also

None

All

Restrictions on Trees When Used as a SmartNavigation Data Source

When a tree is used as a SmartNavigation data source, the values of several tree-specific properties are passed to the SmartNavigation application via URL. Certain characters are inappropriate for use in a URL and must be avoided. When using a tree as a SmartNavigation data source, do not use any of the following characters in the tree name, setID, user key value, and tree branch values:

When using Tree class methods such as Copy, Create, Rename, SaveAs, SaveAsDraft, and others, take care to avoid using these invalid characters in the values for the tree name, setID, user key value, and tree branch.

See Also

Defining SmartNavigation Folders

Data Types for Tree Objects

All tree objects, that is, trees, tree structures, nodes, levels, and so on, are declared as type ApiObject. For example:

Local ApiObject &MYTREE;

Global ApiObject &MYNODE;

All tree objects can be declared as Local, Component or Global.

Scope of the Tree Objects

All tree objects, that is, trees, tree structures, nodes, leaves, and so on, can only be instantiated from PeopleCode.

This object can be used anywhere you have PeopleCode, that is, in an application class, Application Engine PeopleCode, record field PeopleCode, and so on.

You can instantiate a tree or tree structure object only from a session object. You have to instantiate the session object, and connect to the database, before you can instantiate a tree or tree structure.

Local ApiObject &TREELIST; 
Local ApiObject &MYSESSION; 
 
&MYSESSION = %Session; 
 
If &MYSESSION Then 
   /* connection is good */ 
Else 
   /* do error processing */ 
End-if;

Note. Tree Classes are accessible only through PeopleCode.

Tree Classes Implementation

You will often want to create a new tree. The following procedure discusses this action in more detail.

The TreeMover Application Engine program uses the Tree API (and File Layouts) for importing a tree from a flat file or exporting a tree to a flat file.

To create a new tree:

In this example, you are creating a new tree based on an existing tree structure. The following is the complete code sample: the steps explain each line.

Local ApiObject &Session; 
Local ApiObject &TreeList, &MyTree; 
Local ApiObject &LvlColl; 
 
&Session = %Session; 
 
&MyTree = &Session.GetTree();
   /* create new tree */ 

If All(&MyTree) Then 
  &TreeReturn = &MyTree.Create("", "", "PERSONAL_DATA2", "1999-06-01", "PERSONAL_⇒
DATA"); 
 
   If &TreeReturn <> 0 then
      /* check PSMessages collection */
   End-if;

   &MyTree.description = "test tree"; 
    
   /* add level */ 
   &LvlColl = &MyTree.levels; 
   &Level = &LvlColl.add("FIRST LVL"); 
   &Level.description = "First Level"; 
 
   /* add root node */ 
   &RootNode= &MyTree.insertroot("00001");
 
If ALL(&RootNode) Then 
 /* insert a leaf */
       &NewLeaf = &RootNode.InsertChildLeaf("8000", "8999"); 
 
   /* save new tree */ 
   &RSLT = &MyTree.Save(); 
 
   /* Do error checking */ 
   If &RSLT <> 0 Then 
      /* errors occurred = do error checking */ 
      &ERRORCOL = &Session.PSMessages; 
      For &I = 1 To &ERRORCOL.count 
         /* do error processing */ 
      End-For; 
   Else 
      /* no errors - saved correctly - do other processing */ 
   End-If;
End-if;

End-if;

1. Get a session object.

   Before you can get a tree, you have to get a session object. The session controls access to the tree, provides error tracing, enables you to set the runtime environment, and so on. Use the %Session system variable to return a reference to the current PeopleSoft session.

   &Session = %Session;

2. Get a tree object.

   Use the GetTree method specifying a null value (" ") to return a closed tree object.

   &MyTree = &Session.GetTree();

3. Create the Tree.

   The Create method creates a new tree with the name PERSONAL_DATA2. To ensure that you have a valid tree, use the All built-in function. Description is a required property (if you don’t specify something for Description you cannot save the tree.)

   &TreeReturn = &MyTree.Create("", "", "PERSONAL_DATA2", "1999-06-01", "PERSONAL_⇒
   DATA"); 
    
   &MyTree.description = "test tree";

4. Add a level.

   To add a level, you have to instantiate a level collection. Although there aren’t any levels in the tree, you can still access this collection. Use the Add method with the level collection to add a new level. Remember, the level name must be 8 characters or less. Description is a required property (if you don’t specify something for Description you cannot save the tree.)

   &LvlColl = &MyTree.levels; 
   &Level = &LvlColl.add("FIRST LVL"); 
   &Level.description = "First Level";

5. Add the root node.

   Because this is a new tree, you must first add the root node.

   &RootNode = &MyTree.insertroot("00001");

6. Add a leaf.

   To add a new leaf, you must have a reference to the parent node object. Using the All built-in function ensures that there is a root node before you try to insert the leaf with the InsertChildLeaf method.

   If ALL(&RootNode) Then 
      &NewLeaf = &RootNode.InsertChildLeaf("8000", "8999");

7. Save the tree.

   When you execute the Save method, the new tree is saved to the database.

   &RSLT = &MyTree.Save();

   Note. If you’re running the tree API from an Application Engine program, the data won’t actually be committed to the database until the Application Engine program performs a COMMIT.

8. Check for errors.

   You can check if there were any errors using the PSMessages property on the session object.

   If All (&RSLT) Then 
      /* errors occurred = do error checking */ 
      &ERRORCOL = &Session.PSMessages; 
      For &I = 1 To &ERRORCOL.count 
         /* do error processing */ 
      End-For; 
   Else 
      /* no errors - saved correctly - do other processing */ 
   End-If;

   If there are multiple errors, all errors are logged to the PSMessages collection, not just the first occurrence of an error.

Note. If you’ve called the Tree API from an Application Engine program, all errors are also logged in the application engine error log tables.

See Also

Using TreeMover

Tree Classes Reference

This section provides a reference to the following topics:

• Session class methods in the tree API.

• Branch collection.

• Leaf class.

• Level collection.

• Level class.

• Node class.

• Tree class.

• Tree structure class.

Session Class Methods

Tree Classes don't have any built-in functions. Instead, they're instantiated from the Session Class.

In this section, we discuss the Session class methods. The methods are discussed in alphabetical order.

GetTree

Syntax

GetTree()

Description

The GetTree method returns a closed tree object. Before you can use some of the methods or any of the properties, you must use the Open method to open a tree object.

Parameters

None.

Returns

A reference to a closed tree object.

Example

To create a new tree, use the following:

&MYTREE = %Session.GetTree(); 
&MYTREE.Create("","","PERSONAL_NEW", "05-05-1997", "PERSONAL_DATA");

To determine if a tree already exists in the database, use the following code:

&MYTREE = %Session.GetTree(); 
If &MYTREE.Exists("","","PERSONAL_OLD", "05-05-1997", "PERSONAL_DATA") = 0 then 
     /* Do processing */ 
End-If;

To open an existing tree, use the following code:

&MYTREE = %Session.GetTree(); 
&MYTREE.Open("","","PERSONAL_OLD", "05-05-1997", "PERSONAL_DATA", True);

GetTreeStructure

Syntax

GetTreeStructure() 

Description

The GetTreeStructure method returns a closed tree structure object. Before you can use some of the methods or any of the properties, you must use the Open method to open the tree structure object.

Branch Collection

A branch collection is returned from the Branches property, used with an open tree object.

&MYBRANCHCOLL = &MYTREE.Branches;

&MYTREE must be a branched tree. To verify whether a tree is branched, you can check the value of the IsBranched property of a tree object (Boolean value: True or False.)

See Tree class: Branches property.

Branch Collection Property

In this section, we discuss the Branch collection properties. The properties are discussed in alphabetical order.

Count

Description

Returns the number of branches for the branch collection object.

Leaf Class

Leaf objects are instantiated from other tree classes as follows:

• From a tree object with the FindLeaf method.

• From a node object with the FirstChildLeaf property.

• From another leaf object with the NextSib and PrevSib properties.

See FindLeaf, FirstChildLeaf, NextSib, PrevSib.

Leaf Class Methods

In this section, we discuss the Leaf class methods. The methods are discussed in alphabetical order.

Cut

Syntax

Cut()

Description

The Cut method cuts the leaf and puts it into a buffer (the clipboard.) You can then use the PasteSib method to add the leaf back as a sibling of a different leaf. You can also use the PasteChild node method to add the leaf back as a child of a different node.

You can only have one object at a time on the clipboard. If you cut another leaf or node, the leaf in the clipboard is overwritten.

Parameters

None.

Returns

A number; 0 if the cut is successful.

See Also

Cut, PasteSib, PasteChild.

Delete

Syntax

Delete()

Description

The Delete method deletes the leaf object executing the method from the database.

Returns

A number; 0 if the delete is successful.

Example

&MYLEAF = &MYTREE.FindLeaf("8200", "8300"); 
&MYLEAF.Delete();

DeleteByRange

Syntax

DeleteByRange(RangeFrom, RangeTo)

Description

The DeleteByRange method deletes the specified leaf object from the database. The leaf specified by the parameters does not have to match the leaf executing the method. That is, if &MYLEAF is associated with a range 8200-8300, you can specify a different range with the DeleteByRange method. For example:

&MYLEAF = &MYTREE.FindLeaf("8200", "8300"); 
/* some processing */ 
&RET_VALUE = &MYLEAF.DeleteByRange("8400", "8500");

Parameters

Returns

A number; 0 if the delete is successful.

Example

&RET_VALUE= &MYLEAF.DeleteByRange("8400", "8500");

GenABNMenuElement

Syntax

GenABNMenuElement()

Description

Use this method to generate a single <li> element for this tree leaf.

The <li> element from this leaf and the <li> elements from its sibling leaves and nodes are concatenated to form an HTML code fragment to be consumed by the portal.

Parameters

None.

Returns

A string representing the <li> element for this tree leaf.

Example

&LI_list = &LI_list | &ChildLeaf.GenABNMenuElement();

InsertDynSib

Syntax

InsertDynSib()

Description

The InsertDynSib method inserts a dynamic leaf as a sibling leaf to the leaf object executing the method. The leaf is a newnode.

A leaf object associated with the new leaf is returned. The new leaf is inserted as the next sibling leaf. If the new leaf isn’t inserted successfully, the method returns Null.

Note. To insert a sibling leaf with a specific range, use the InsertSib method.

Parameters

None.

Returns

A reference to the new leaf. If this method fails, it returns either False or a Null object reference, depending upon the type of error encountered. The best way to test whether the object was inserted is to test the result using either the All or None functions.

Example

&NEWLEAF = &MYLEAF.InsertDynSib();

See Also

Leaf class: InsertSib method.

All, None.

InsertSib

Syntax

InsertSib(RangeFrom, RangeTo)

Description

The InsertSib method inserts a new leaf as a sibling leaf under the leaf currently executing the method. The leaf specified by the range parameters must be a new leaf. You receive an error if the leaf already exists.

A leaf object associated with the new leaf is returned. The new leaf is inserted as the next sibling leaf, although there is no explicit ordering of leaves: leaves take the order of the alphanumeric database sort on their range fields.

Note. To insert a dynamic sibling leaf (that is, without specifying a range) use the InsertDynSib method.

Parameters

Returns

A leaf object associated with the new leaf. If this method fails, it returns either False or a Null object reference, depending upon the type of error encountered. The best way to test whether the object was inserted is to test the result using either the All or None functions.

Example

&NEWLEAF = &MYLEAF.InsertSib("10090", "10100");

See Also

Leaf class: InsertDynSib method.

All, None.

LoadABNChart

Syntax

LoadABNChart(&chart_rowset, &relactions_rowset)

Description

Use this method to load a child leaf of the current tree node into the SmartNavigation chart rowset and the component buffer.

Parameters

Returns

None.

Example

&ChildLeaf.LoadABNChart(&chart_rs, &ra_rs);

See Also

LoadABNChartOrdered

GetABNChartRowSet, GetABNRelActnRowSet.

LoadABNChartOrdered

Syntax

LoadABNChartOrdered(&chart_rowset, &relactions_rowset, order)

Description

Use this method to load a child leaf of the current tree node into the SmartNavigation chart rowset and the component buffer. The order for the leaf within its chart level is specified by this method.

Parameters

Returns

None.

Example

&ChildLeaf.LoadABNChartOrdered(&chart_rs, &ra_rs, 5);

See Also

LoadABNChart

GetABNChartRowSet, GetABNRelActnRowSet.

MoveAsChild

Syntax

MoveAsChild(Node)

Description

The MoveAsChild method moves the leaf executing the method to a different node in the tree. The leaf becomes the first child leaf under the node, even though there is no explicit ordering of leaves: leaves take the order of the alphanumeric database sort on their range fields. The specified node becomes the new parent to the leaf.

Parameters

Note. To specify a node name, not a node object, use the MoveAsChildByName method.

Returns

A number; 0 if the move is successful.

Example

The following example moves leaf 8001 from node 10100 (old parent) to node 00001 (new parent)

&MY_LEAF = &MY_TREE.FindLeaf("8001", "8001"); 
&NEW_PARENT = &MY_TREE.FindNode("00001", ""); 
If &NEW_PARENT <> Null Then 
   &RET_VALUE = &MY_LEAF.MoveAsChild(&NEW_PARENT); 
End-If;

See Also

Leaf class: MoveAsChildByName method.

MoveAsChildByName

Syntax

MoveAsChildByName(NodeName)

Description

The MoveAsChildByName method moves the leaf executing the method to a different node in the tree. The leaf becomes the first child leaf under the node, although there is no explicit ordering of leaves: leaves take the order of the alphanumeric database sort on their range fields. The specified node becomes the new parent to the leaf. The node specified by NodeName must be a valid node name.

Parameters

Note. To specify a node object, not a node name, use the MoveAsChild method.

Returns

A number; 0 if the move is successful.

Example

The following example moves leaf 8001 from node 10100 (old parent) to node 00001 (new parent)

&MY_LEAF = &MY_TREE.FindLeaf("8001", "8001"); 
If &MY_LEAF <> Null Then 
   &RET_VALUE = &MY_LEAF.MoveAsChildByName("00001"); 
End-If;

See Also

Leaf class: MoveAsChild method.

MoveAsSib

Syntax

MoveAsSib(Leaf)

Description

The MoveAsSib method moves the leaf executing the method to a new place in the tree. The current leaf becomes the next sibling leaf under the specified leaf object, although there is no explicit ordering of leaves: leaves take the order of the alphanumeric database sort on their range fields.

Parameters

Note. To specify a range, not a leaf object, use the MoveAsSibByRange method.

Returns

A number; 0 if the move is successful.

Example

&MYLEAF = &MYTREE.FindLeaf("8000", "8000"); 
&MYLEAF2 = &MYTREE.FindLeaf("9000", "9000"); 
&RET_VALUE = &MYLEAF.MoveAsSib(&MYLEAF2);

See Also

Leaf class: MoveAsSibByRange method.

MoveAsSibByRange

Syntax

MoveAsSibByRange(RangeFrom, RangeTo)

Description

The MoveAsSibByRange method moves the leaf executing the method to a new place in the tree. The current leaf becomes the next sibling leaf under the specified leaf object.

Parameters

Note. To specify a leaf object, not a range, use the MoveAsSib method.

Returns

A number; 0 if the move is successful.

Example

&MYLEAF = &MYTREE.FindLeaf("8000", "8000"); 
&RET_VALUE = &MYLEAF.MoveAsSibByRange("9000", "9000");

See Also

Leaf class: MoveAsSib method.

PasteSib

Syntax

PasteSib()

Description

The PasteSib method makes the leaf from the buffer (clipboard) a sibling to the leaf executing the method. You must use the Cut leaf method before you can paste a leaf.

You can have only one object at a time on the clipboard. If you cut another leaf or node, the leaf in the clipboard is overwritten.

Parameters

None.

Returns

A number; 0 if the paste is successful.

See Also

Cut, PasteChild, Cut.

RefreshDescription

Syntax

RefreshDescription(expand_range)

Description

Use this method to reload the tree leaf’s description from the database.

Note. This method is currently supported for what is known as a single detail leaf. Do not use this method with ranged or dynamic leaves.

Parameters

Returns

A number: 0 if the refresh was successful.

See Also

Leaf class: Description property.

UpdateRanges

Syntax

UpdateRanges(RangeFrom, RangeTo)

Description

The UpdateRanges method performs validation of edited ranges, updating as necessary.

Parameters

Returns

A number; 0 if the update is successful.

Leaf Class Properties

In this section, we discuss the Leaf class properties. The properties are discussed in alphabetical order.

Description

Description

Use this property to return the tree leaf’s description as a string.

Note. This property is currently supported for what is known as a single detail leaf. Do not use this property with ranged or dynamic leaves.

This property is read-only.

See Also

Leaf class: RefreshDescription method.

DisplayLevelNumber

Description

When using the Tree API to create a graphic representation of the tree (such as for HTML Tree Manager or other application pages) use this property to indicate the display level, that is, tell the user how many levels deep the leaf is. This is generally used for trees where levels aren't used and the LevelNumber property always returns 0. This property always returns a number.

This property is read-only.

See Also

Node class: LevelNumber property.

Dynamic

Description

This property specifies whether the leaf has a dynamic range or a specified range. If you set this property to True, the leaf has a dynamic range. If this is a new leaf, and you do not set this property, the value is automatically set is False.

This property is read-write.

See Also

Creating Trees.

HasNextSib

Description

This property returns True if the leaf has a next sibling, that is, it isn’t the last leaf listed under the parent node.

This property is read-only.

HasPrevSib

Description

This property returns True if the leaf has a previous sibling, that is, it isn’t the first leaf listed under the parent node.

This property is read-only.

ImageName

Description

This property sets the which image is used to display the leaf. This property takes a string value for the image name of the leaf.

This property is read-write.

IsChanged

Description

This property returns True if the leaf has been edited or changed.

This property is read-only.

Example

If &MYLEAF.IsChanged Then 
   &MYTREE.Save(); 
End-If;

IsCut

Description

This property returns True if the leaf has been cut from the displayed tree. This property is generally used with the HTML Tree Manager.

This property is read-only.

IsDeleted

Description

This property returns True if the leaf has been deleted from the tree but the tree hasn’t been saved.

This property is read-only.

IsInserted

Description

This property returns True if the leaf has been inserted as a new leaf in the tree but the tree hasn’t been saved.

This property is read-only.

NextSib

Description

This property returns a leaf object associated with the next sibling leaf. The next sibling of a leaf is the leaf appearing under the current leaf. If there is no next sibling and you try to assign it to a variable, you receive a runtime error.

This property is read-only.

Example

The following code traversed the leaves from top to bottom.

While &MYLEAF.HasNextSib 
   &MYLEAF = &MYLEAF.NextSib; 
   /* do some processing */ 
End-While;

Parent

Description

This property returns a node object associated with the parent node for the leaf.

This property is read-only.

Example

&PARENTNODE = &MYLEAF.Parent; 
/* do node processing with node object */

PrevSib

Description

This property returns a leaf object associated with the previous sibling leaf. The previous sibling of a leaf is the leaf appearing above the current leaf. If there is no previous sibling and you try to assign it to a variable, you receive a runtime error.

This property is read-only.

Example

The following code traverses the leaves from bottom to top.

While &MYLEAF.HasPrevSib 
   &MYLEAF = &MYLEAF.PrevSib; 
   /* do some processing */ 
End-While;

RangeFrom

Description

This property returns the starting range, as a string, of the leaf.

This property is read-write.

RangeTo

Description

This property returns the ending range, as a string, of the leaf.

This property is read-write.

TreeBranchName

Description

This property returns the branch name of the tree as a string if the tree is branched. If not branched, this property returns a blank string.

This property is read-only.

TreeEffDt

Description

This property returns the effective date of the tree as a string if the tree is effective-dated. If not effective-dated, this property returns a blank string.

This property is read-only.

TreeName

Description

This property returns the name of the tree as a string.

This property is read-only.

TreeSetId

Description

This property returns the SetID of the tree as a string if the tree has a SetID. If the tree doesn’t have a SetID, this property returns a blank string.

This property is read-only.

TreeUserKeyValue

Description

This property returns the UserKeyValue of the tree as a string if the tree has a UserKeyValue. If the tree doesn’t have a UserKeyValue, this property returns a blank string.

This property is read-only.

Level Collection

Level collection is instantiated from a tree object with the Levels property.

See Tree class: Levels property.

Level Collection Methods

In this section, we discuss the Level Collection methods. The methods are discussed in alphabetical order.

Add

Syntax

Add(LevelName)

Description

The Add method adds a new level called LevelName to the database. The specified level must be a new level, that is, it cannot exist in the database. LevelName takes a string value.

Note. LevelName must be 8 characters or less.

If no levels currently exist in the tree, the level is added at the top level. If levels already exist in the tree, the new level is added as the last level. You can change the level number of a level using the Number property.

If the new level is the first level, the AllValuesAudit property is automatically set to True.

The new level is notadded to the database until the tree is explicitly saved.

This method returns a reference to the new level object.

See Also

Level class: Number property, AllValuesAudit property.

Item

Syntax

Item(LevelName, LevelNumber)

Description

The Item method returns a reference to the specified level in the level collection executing the method as an object. The LevelName parameter specifies the name of the level to access. This parameter takes a string value. The LevelNumber parameter specifies the number at which the level exists. This parameter takes a number value. For example, suppose your level collection contains the following levels, in this order:

1. CORPORATE

2. COMPANY

3. DIVISION

4. DEPARTMENT

5. BRANCH

You want to access the fourth level, DEPARTMENT. You would use the following code:

&MYLEVEL = &LVLCOLLECTION.Item("DEPARTMENT", 4);

Remove

Syntax

Remove()

Description

The Remove method deletes the current level from the database. You can use this method only after you have used the First, Next, or Item properties: otherwise the system doesn’t know which level to delete from the tree. If no level has been indicated yet system tries to remove the last level. If the level to remove has nodes associated with it, the system doesn't remove the level. The rest of the levels in the collection after the deleted level are moved up in the list and renumbered so that the levels remain consecutively numbered.

Returns

A number; 0 if the level is successfully removed.

Level Collection Properties

In this section, we discuss the Level collection properties. The properties are discussed in alphabetical order.

Count

Description

Returns the number of levels for the level collection object.

First

Description

The First property returns a reference to the first level in the level collection executing the method as an open object.

Last

Description

The Last property returns a reference to the last level in the level collection executing the method as an open object.

Next

Description

The Next property returns a reference to the next level in the level collection executing the method as an open object. You can use this method only after you have used either the First or Item properties: otherwise the system doesn’t know where to start in the tree.

Level Class

Level objects are instantiated from the level class collection object with the Item method or one of the following properties:

• First

• Last

• Next

See Level collection: Item method, First property, Last property, Next property.

Level Class Methods

In this section, we discuss the Leaf class properties. The properties are discussed in alphabetical order.

Create

Syntax

Create(LevelName, LevelNumber)

Description

Note. This method has been deprecated. If you create a level using this method, there is no way of saving the level to the database. Use the Add level collection method instead.

Level Class Properties

In this section, we discuss the Level class properties. The properties are discussed in alphabetical order.

AllValuesAudit

Description

This property specifies whether PeopleSoft Tree Manager permits nodes to skip over this level. To allow nodes to skip this level, specify this parameter as True. If you are creating a new level, and this level is the first level in a tree, this property is automatically set to True. If the level isn’t the first level, this property is set to False by default..

This property is read-write.

See Also

Modifying Tree Definitions.

Description

Description

This property returns the description of the level.

This property is read-write.

Name

Description

This property returns the name of the level.

This property is read-write.

Number

Description

This property returns the number of the level.

Note. Though you can use this property to set the level of the number, you should not do so, as level numbers are automatically assigned when the level is inserted to the level collection using the Add method.

This property is read-write.

TreeBranchName

Description

This property returns the branch name of the tree as a string if the tree is branched. If not branched, this property returns a blank string.

This property is read-only.

TreeEffDt

Description

This property returns the effective date of the tree as a string if the tree is effective-dated. If not-effective dated, this property returns a blank string.

This property is read-only.

TreeName

Description

This property returns the name of the tree as a string.

This property is read-only.

TreeSetId

Description

This property returns the SetID of the tree as a string if the tree has a SetID. If the tree doesn’t have a SetID, this property returns a blank string.

This property is read-only.

TreeUserKeyValue

Description

This property returns the UserKeyValue of the tree as a string if the tree has a UserKeyValue. If the tree doesn’t have a UserKeyValue, this property returns a blank string.

Node Class

Node objects are instantiated from other tree classes, as follows:

• From a tree object with the FindNode method.

• From a leaf object with the Parent property.

• From another node object with the FirstChildNode, NextSib, PrevSib, and Parent properties.

See FindNode, FirstChildNode, NextSib, PrevSib.

See Leaf class: Parent property.

See Node class: Parent property.

Node Class Methods

In this section, we discuss the Node class methods. The methods are discussed in alphabetical order.

Branch

Syntax

Branch()

Description

The Branch method branches the node executing this method, identifying all of its child nodes and leaves as part of that branch. Branching means taking a limb of a tree and creating another subtree to hold that limb. (Technically is it not creating a real tree.) The subtree is accessed through the Branches collection.

After you use the Branch method, you can no longer access the child nodes and leaves of the node that executed the method until you close the current tree, open the new branched tree, and find the node again. To unbranch the tree, use the Unbranch method.

Returns

A number; 0 if method is successful.

Example

&MYNODE = &MYTREE.FindNode("10900", ""); 
&MYNODE.Branch();

See Also

Working with Tree Branches.

Cut

Syntax

Cut()

Description

The Cut method cuts the node executing the method and puts it into a buffer (the clipboard). You can then use the PasteSib method to add the node back as a sibling of a different node. You can also use the PasteChild node method to add the node back as a child of a different node.

You can have only one object at a time on the clipboard. If you cut another leaf or node, the node on the clipboard is overwritten.

Parameters

None.

Returns

A number; 0 if method is successful.

See Also

PasteSib, PasteChild, Cut.

Delete

Syntax

Delete()

Description

The Delete method deletes the node object executing the method from the database.

Returns

A number; 0 if method is successful.

DeleteByName

Syntax

DeleteByName(NodeName)

Description

The DeleteByName method deletes the specified node from the database. The NodeName parameter takes a string value. The node specified by NodeName does not have to match the node executing the method. That is, if &MYNODE is associated with node 100200, you can specify a different node with the DeleteByName method. For example:

&MYNODE = &MYTREE.FindNode("100200", ""); 
/* some processing */ 
&MYNODE.DeleteByName("100300");

The node name specified by NodeName must be a valid node in the existing open tree object. If NodeName doesn’t exist, you receive a runtime error.

Returns

A number; 0 if method is successful.

Expand

Syntax

Expand(ExpandType)

Description

The Expand method gets the next level of nodes or leaves into memory from the selected node. What leaves or nodes get expanded depends on the ExpandType.

Parameters

Returns

A number; 0 if method is successful.

Example

If (&MYNODE.State = 2 AND &MYNODE.HasChildren); 
   /* if node is collapsed */ 
   &MYNODE.Expand(2); 
End-if; 

GenABNMenuElement

Syntax

GenABNMenuElement(initial_node)

Description

Use this method to generate a single <li> element for this tree node.

The <li> element from this node and any sibling nodes and leaves are concatenated to form an HTML code fragment to be consumed by the portal.

Parameters

Returns

A string representing the <li> element for this tree node.

Example

&LI_list = &LI_list | &ChildNode.GenABNMenuElement(GetABNInitialNode(&reqParams));

GenBreadCrumbs

Syntax

GenBreadCrumbs(list)

Description

Call the GenBreadCrumbs method from the requested node to generate an HTML code fragment that will be rendered in the browser as breadcrumbs.

The <li> elements in the input string are created by the GenRelatedActions and GenABNMenuElement methods of the Node class, and the GenABNMenuElement method of the Leaf class.

Parameters

Returns

A string with the <li> elements for the bread crumbs for this tree node appended.

Example

The following example shows how the list of <li> elements is created for a node. In this example, <li> elements are generated for related actions, the first child node, and child leaves. This list is then passed to the GenHTMLMenu function.

&LI_lis = &MyNode.GenBreadCrumbs(&LI_list);

See Also

GenABNMenuElement

GenABNMenuElement, GenRelatedActions.

GenRelatedActions

Syntax

GenRelatedActions()

Description

Use this method to generate the list of <li> elements for the related actions menu for the current tree node. Call this function before calling GenABNMenuElement for the same node. The <li> elements from this function, from this node, from any child nodes and leaves traversed, and from the parent tree nodes are concatenated to form an HTML code fragment to be consumed by the portal.

Parameters

None.

Returns

A string representing the <li> elements for the related actions for this tree node.

Example

&LI_list = &LI_list | &MyNode.GenRelatedActions();

See Also

GenABNMenuElement, GenBreadCrumbs.

InsertChildLeaf

Syntax

InsertChildLeaf(RangeFrom, RangeTo)

Description

The InsertChildLeaf method inserts a new leaf (as specified by the range parameters) under the node object executing the method.

A leaf object associated with the new leaf is returned.

The new leaf is inserted as the child of the current node, although there is no explicit ordering of leaves: leaves take the order of the alphanumeric database sort on their range fields.

Note. You must specify a range with this method. To insert a dynamic range leaf (that is, one with no range) use the InsertDynChildLeaf method.

Parameters

Returns

A leaf object associated with the new leaf. If this method fails, it returns either False or a Null object reference, depending upon the type of error encountered. The best way to test whether the object was inserted is to test the result using either the All or None functions.

Example

&NEWLEAF = &MYLNODE.InsertChildLeaf("10090", "10100");
                
If None(&NEWLEAF) Then 
   /* Error Processing */ 
End-If;

See Also

Node class: InsertDynChildLeaf method.

All, None.

InsertChildNode

Syntax

InsertChildNode(NodeName)

Description

The InsertChildNode method inserts a new node (as specified by NodeName) as a child node under the node object executing the method. The node specified by NodeName must be a new node. You receive an error if the node already exists.

A node object associated with the new node is returned. If the new node isn’t inserted successfully, the method returns False or Null.

Parameters

Returns

A reference to the new node. If this method fails, it returns either False or a Null object reference, depending upon the type of error encountered. The best way to test whether the object was inserted is to test the result using either the All or None functions.

Example

&NEWNODE = &MYNODE.InsertChildNode("100500");
                
If None(&NEWNODE) Then 
   /* Do error processing */ 
End-If;

See Also

All, None.

InsertChildRecord

Syntax

InsertChildRecord(NodeName)

Description

The InsertChildRecord method inserts a new record (as specified by NodeName) as a node under the parent node executing this method. This method works only on trees that are Query Access Trees.

A node object associated with the new node is returned, otherwise this method returns False or Null.

Parameters

Returns

A reference to the new node. If this method fails, it returns either False or a Null object reference, depending upon the type of error encountered. The best way to test whether the object was inserted is to test the result using either the All or None functions.

Example

&NEWNODE = &MYNODE.InsertChildRecord("PERSONAL_DATA");
                
If None(&NEWNODE) Then 
   /* Do error processing */ 
End-if;

See Also

All, None.

InsertDynChildLeaf

Syntax

InsertDynChildLeaf()

Description

The InsertDynChildLeaf method inserts a dynamic leaf under the node object executing the method.

A leaf object associated with the new leaf is returned.

The new leaf is inserted as the child of the current node, although there is no explicit ordering of leaves.

Note. To insert a leaf with a specific range, use the InsertChildLeaf method.

Parameters

None.

Returns

A leaf object associated with the new leaf. If this method fails, it returns either False or a Null object reference, depending upon the type of error encountered. The best way to test whether the object was inserted is to test the result using either the All or None functions.

Example

&NEWLEAF = &MYLNODE.InsertDynChildLeaf();
                
If None(&NEWLEAF) Then 
   /* Do error processing */ 
End-If;

See Also

Node class: InsertChildLeaf method.

All, None.

InsertSib

Syntax

InsertSib(NodeName)

Description

The InsertSib method inserts a new node (as specified by NodeName) as a sibling node to the node object executing the method. The node specified by NodeName must be a new node. You receive an error if the node already exists.

A node object associated with the new node is returned. If the new node isn’t inserted successfully, the method returns Null.

Parameters

Returns

A reference to the new node. If this method fails, it returns False.

Example

&NEWNODE = &MYNODE.InsertSib("100500");

InsertSibRecord

Syntax

InsertSibRecord(NodeName)

Description

The InsertSibRecord method inserts a new record (as specified by NodeName) as a sibling node of the parent node executing this method. This method works only on trees that are Query Access Trees.

A node object associated with the new node is returned, otherwise this method returns Null.

Parameters

Returns

A reference to the new node. If this method fails, it returns False.

Example

&NEWNODE = &MYNODE.InsertSibRecord("PERSONAL_DATA");

LoadABNChart

Syntax

LoadABNChart(&chart_rowset, &relactions_rowset, requested_node, initial_node)

Description

Use this method to load the requested tree node into the SmartNavigation chart rowset and the component buffer.

Parameters

Returns

None.

Example

&MyNode.LoadABNChart(&chart_rs, &ra_rs, True, GetABNInitialNode(&reqParams));
&ChildNode.LoadABNChart(&chart_rs, &ra_rs, False, GetABNInitialNode(&reqParams));

See Also

LoadABNChartOrdered

GetABNChartRowSet, GetABNInitialNode, GetABNRelActnRowSet.

LoadABNChartOrdered

Syntax

LoadABNChartOrdered(&chart_rowset, &relactions_rowset, requested_node, initial_node, order)

Description

Use this method to load the requested tree node into the SmartNavigation chart rowset and the component buffer. The order for this node within its chart level is specified by this method.

Parameters

Returns

None.

Example

&MyNode.LoadABNChartOrdered(&chart_rs, &ra_rs, True, ⇒
GetABNInitialNode(&reqParams), 5);
&ChildNode.LoadABNChartOrdered(&chart_rs, &ra_rs, False, ⇒
GetABNInitialNode(&reqParams), 5);

See Also

LoadABNChart

GetABNChartRowSet, GetABNInitialNode, GetABNRelActnRowSet.

MoveAsChild

Syntax

MoveAsChild(Node)

Description

The MoveAsChild method moves the node executing the method to a different node in the tree. The node becomes the first child node under the named node. The specified node becomes the new parent to the child node. The node specified by Node must be an existing node in the current tree. All child nodes and details are also moved with the node.

Parameters

Note. To specify a node name, not a node object, use the MoveAsChildByName method.

Returns

A number; 0 if method is successful.

Example

The following example moves node 10200 from node 10100 (old parent) to node 00001 (new parent).

   &MY_NODE = &MY_TREE.FindNode("10200", ""); 
   &NEW_PARENT = &MY_TREE.FindNode("00001", ""); 
   If &NEW_PARENT <> Null Then 
      &MY_NODE.MoveAsChild(&NEW_PARENT); 
   End-If;

See Also

Node class: MoveAsChildByName method.

MoveAsChildByName

Syntax

MoveAsChildByName(NodeName)

Description

The MoveAsChildByName method moves the node executing the method to a different node in the tree. The node becomes the first child node under the parent node. The specified node becomes the new parent to the node. The node specified by NodeName must be a valid node name. All child nodes and details are also moved with the node.

Parameters

Note. To specify a node object, not a node name, use the MoveAsChild method.

Returns

A number; 0 if method is successful.

Example

The following moves node 10200 from node 10100 (old parent) to node 00001 (new parent)

   &MY_NODE = &MY_TREE.FindNode("10200", ""); 
   If &MY_NODE <> Null Then 
      &MY_NODE.MoveAsChildByName("00001"); 
   End-If;

See Also

Node class: MoveAsChild method.

MoveAsSib

Syntax

MoveAsSib(Node)

Description

The MoveAsSib method moves the node executing the method to a new place in the tree. The current node becomes the next sibling node under the specified node. All child nodes and details are also moved with the node.

Parameters

Note. To specify a node name, not a node object, use the MoveAsSibByName method.

Returns

A number; 0 if method is successful.

Example

&MYNODE = &MYTREE.FindNode("20000", ""); 
&MYNODE2 = &MYTREE.FindNode("20100", ""); 
&MYNODE.MoveAsSib(&MYNODE2);

See Also

Node class: MoveAsSibByName method.

MoveAsSibByName

Syntax

MoveAsSibByName(NodeName)

Description

The MoveAsSibByName method moves the node executing the method to a new place in the tree. The current node becomes the next sibling node under the specified node. All child nodes and details are also moved with the node.

Parameters

Note. To specify a node object, not a node name, use the MoveAsSib method.

Returns

A number; 0 if method is successful.

Example

&MYNODE = &MYTREE.FindNode("20000", ""); 
&MYNODE.MoveAsSibByName("10100");

See Also

Node class: MoveAsSib method.

PasteChild

Syntax

PasteChild()

Description

The PasteChild method makes the node or leaf from the buffer (clipboard) a child to the node executing the method. You must use the Cut node or leaf method before you can paste a node or leaf.

You can have only one object at a time on the clipboard. If you cut another node or leaf, the node or leaf on the clipboard is overwritten.

Parameters

None.

Returns

A number; 0 if method is successful.

See Also

Cut, PasteSib, Cut.

PasteSib

Syntax

PasteSib()

Description

The PasteSib method makes the node from the buffer (clipboard) a sibling to the node executing the method. You must use the Cut node method before you can paste a node.

You can have only one object at a time on the clipboard. If you cut another leaf or node, the node on the clipboard is overwritten.

Parameters

None.

Returns

A number; 0 if method is successful.

See Also

Cut, PasteChild, Cut.

RefreshDescription

Syntax

RefreshDescription()

Description

The RefreshDescription method enables you to change the description of a node on a page and have the update be displayed immediately. If you don't use RefreshDescription, you must save the tree and reopen it for the change to be displayed.

Parameters

None.

Returns

A zero (0) if description is refreshed successfully, a different error number otherwise.

Example

&result= &NodeObj.refreshdescription();

Rename

Syntax

Rename(NodeName)

Description

The Rename method renames the node object executing the method without changing any other properties. The parameter NodeName takes a string value. The node specified by NodeName must be a new node. You receive an error if the node already exists.

Note. The Rename method does not rename the node in a user node component. Your application needs to do that.

Returns

A number; 0 if method is successful.

Example

&MYNODE = &MYTREE.FindNode("10900", ""); 
&MYNODE.Rename("10200");

SwitchLevel

Syntax

SwitchLevel(NewLevelNumber)

Description

The SwitchLevel methods enables you to move a node down from one level to another.

NewLevelNumber must specify a valid level number. For trees in which the Level Use parameter is set to Strictly Enforce Levels, the new level must be at least one level lower than the node’s parent level.

If the level specified by NewLevelNumber doesn't exist, it's automatically generated and added to the tree.

Parameters

Returns

A zero (0) if node is moved successfully, a different error number otherwise.

Unbranch

Syntax

Unbranch()

Description

The Unbranch method is the opposite of the Branch method: that is, it unbranches the node executing the method if it is branched. All of the child node and leaves of the node become part of the current open tree and accessible in that tree. You can’t unbranch the Root Node in a branched tree.

If the node executing the method isn’t branched, you receive a runtime error. Use the IsBranched property to make sure a node is branched.

Returns

A number; 0 if method is successful.

Example

&MYNODE = &MYTREE.FindNode("10900", ""); 
&MYNODE.Unbranch();

See Also

Working with Tree Branches.

Node Class Properties

In this section, we discuss the Node class properties. The properties are discussed in alphabetical order.

AllChildCount

Description

This property returns the number of all the child nodes and leaves of the node, that is, all the nodes and leaves below this node.

This property is read-only.

AllChildNodeCount

Description

This property returns the number of child nodes of the node, that is, all the nodes below this node.

To determine all the leaves below a node, subtract the AllChildNodeCount from the AllChildCount

This property is read-only.

Example

To determine all the leaves below a node, use the AllChildNodeCount with the AllChildCount property.

&AllCount = (&MyNode.AllChildCount - &MyNode.AllChildNodeCount);

ChildLeafCount

Description

This property returns the number of immediate child leaves below this node.

This property is read-only.

ChildNodeCount

Description

This property returns the number of immediate child nodes below this node.

This property is read-only.

ColImageName

Description

This property enables you to specify the image name for a collapsed node.

This property is read-write.

Description

Description

This property returns the description of the node.

This property is read-only.

DisplayLevelNumber

Description

When using the Tree API to create a graphic representation of the tree (such as for HTML Tree Manager or other application pages) use this property to indicate the display level, that is, tell the user how many levels deep the node is. This is generally used for trees where levels aren't used and the LevelNumber property always returns 0.

This property is read-only.

See Also

Node class: LevelNumber property.

ExpImageName

Description

This property enables you to specify the expanded image name for a node.

This property is read-write.

FirstChildLeaf

Description

This property returns a reference to the first child leaf of the node. This is the leaf that appears highest in the list of children of the node in PeopleSoft Tree Manager.

This property is read-only.

Example

&NEWLEAF = &MYNODE.FirstChildLeaf;

FirstChildNode

Description

This property returns a reference to the first child node of the node. This is the node that appears highest in the list of children of the node in PeopleSoft Tree Manager.

This property is read-only.

Example

&CHILDNODE = &MYNODE.FirstChildNode;

HasChildLeaves

Description

This property returns True if the node has immediate child leaves, False otherwise.

This property is read-only.

HasChildNodes

Description

This property returns True if the node has immediate child nodes, False otherwise.

This property is read-only.

HasChildren

Description

This property returns True if the node has either child leaves or child nodes anywhere in the subtree, not just immediately under the node.

This property is read-only.

HasNextSib

Description

This property returns True if the node has a next sibling, that is, if it isn’t the last node.

This property is read-only.

Example

While &MYNODE.HasNextSib    
   &MYNODE = &MYNODE.NextSib; 
   /* do some processing */ 
End-While;

HasPrevSib

Description

This property returns True if the node has a previous sibling, that is, if it isn’t the first node.

This property is read-only.

IsBranched

Description

This property returns True if the node is branched, False otherwise.

This property is read-only.

IsChanged

Description

This property returns True if the node has been edited or changed but the current tree hasn’t been saved.

This property is read-only.

IsCut

Description

This property returns True if the node has been cut from the displayed tree. This property is generally used with the HTML Tree Manager.

This property is read-only.

IsDeleted

Description

This property returns True if the node has been deleted but the current tree hasn’t been saved.

This property is read-only.

IsInserted

Description

This property returns True if the node was inserted as a new node into the tree but the tree hasn’t been saved.

This property is read-only.

Example

If &MYNODE.IsInserted Then 
   &MYTREE.Save(); 
End-if;

IsRoot

Description

This property returns True for both of the following:

• the node is the root node of an unbranched tree.

• the node is the top node of an opened tree branch.

Otherwise, the property returns False.

This property is read-only.

LastChildLeaf

Description

This property returns a reference to the last child leaf of the node. This is the leaf that appears lowest in the list of children of the node in PeopleSoft Tree Manager.

This property is read-only.

Example

&NEWLEAF = &MYNODE.LastChildLeaf;

LastChildNode

Description

This property returns a reference to the last child node of the node. This is the node that appears lowest in the list of children of the node in PeopleSoft Tree Manager.

This property is read-only.

Example

&CHILDNODE = &MYNODE.LastChildNode;

LevelNumber

Description

This property returns the level number of the node. Values are 1-99 for Strict or Loose level trees. This property returns 0 for trees that don’t have levels.

Note. PeopleSoft does not recommend using this property to set the level of the node. Instead, use the SwitchLevel method.

This property is read-write.

See Also

Node class: SwitchLevel method.

Name

Description

This property returns the name of the node (as a string.) You must set this property to a valid value if you are creating a new node.

Note. Do not use this property to change the name of an existing node. The change will not be reflected in the database. You must use the Rename method to change the name of an existing node.

This property is read-write.

See Also

Node class: Rename method.

NextSib

Description

This property returns a reference to the next sibling node. If there isn’t a next sibling node, Null is returned.

This property is read-only.

Example

While &MYNODE.HasNextSib 
   &MYNODE = &MYNODE.NextSib; 
   /* do some processing */ 
End-While;

Parent

Description

This property returns a reference to the node that is the parent of the node executing the property. If the current node has no parent (is a root node) False is returned.

This property is read-only.

Example

&PARENT = &MYNODE.Parent;

PrevSib

Description

This property returns a reference to the node that is the previous sibling node to the node executing the property. If there isn’t a previous sibling, Null is returned.

This property is read-only.

Example

If &MYNODE.PrevSib Then 
   /* do processing */ 
End-if;

State

Description

This property returns the state of the node, that is, does it have children, and are they expanded or collapsed.

See Node class: Expand method.

The values for this property are:

This property is read-only.

Example

&VALUE = &MYNODE.State; 
If &VALUE = 2 Then  
   &MYNODE.Expand(0); 
End-if;

TreeBranchName

Description

This property returns the branch name of the tree as a string if the tree is branched. If not branched, this property returns a blank string.

This property is read-only.

TreeEffDt

Description

This property returns the effective date of the tree as a string if the tree is effective-dated. If not effective-dated, this property returns a blank string.

This property is read-only.

TreeName

Description

This property returns the name of the tree as a string.

This property is read-only.

TreeSetId

Description

This property returns the SetID of the tree as a string if the tree has a SetID. If the tree doesn’t have a SetID, this property returns a blank string.

This property is read-only.

TreeUserKeyValue

Description

This property returns the UserKeyValue of the tree as a string if the tree has a UserKeyValue. If the tree doesn’t have a UserKeyValue, this property returns a blank string.

Type

Description

This property returns the type of the node. This property takes a string value. Values are:

• "G" (Group): normal unbranched node or record group

• "B" (Branched nodes)

• "R" (Query Record): used for Query Access Trees only

This property is read-only.

Tree Class

Tree objects are instantiated from a session object with the GetTree method.

The following code sample gets a tree, then opens the tree structure associated with that tree:

Local string &TREE_NAME; 
Local string &TREE_DT; 
Local ApiObject &MYSESSION, &VC_TREE, &STRUCT; 
 
 
/* Get and Open the Tree using the Tree API */ 
&MYSESSION = %Session; 
 
/* Get the Tree Name and Effective Date from the level 0 record */ 
&TREE_NAME = "CUSTOMER"; 
&TREE_DT = "1900-01-01"; 
 
/* Get and Open the Tree  */ 
 
&VC_TREE = &MYSESSION.GetTree(); 

/* open the tree with read access only */

&VC_TREE.OPEN("BKINV", "", &TREE_NAME, &TREE_DT, "", False); 
 
/* Get and Open Tree Structure */ 
 
&STRUCT = VC_TREE.Structure;

See Session class: GetTree method.

Tree Class Methods

In this section, we discuss the Tree class methods. The methods are discussed in alphabetical order.

Audit

Syntax

Audit()

Description

The Audit method audits the tree object executing the method to determine its validity.

The Audit method can be used only on an open tree, not on a closed tree. This means you must have opened the tree with the Open method before you can audit it.

Returns

A number: 0 if the tree passes all audits. If Audit returns a value not equal to 0, an error is logged.

See Also

Tree class: Open method.

Auditing and Repairing Trees

AuditByName

Syntax

AuditByName(SetID, UserKeyValue, TreeName, EffDt, BranchName)

Description

The AuditByName method audits the tree specified by the parameters passed to it. The AuditByName method can be used only with a tree identifier, it cannot be used on a fully instantiated, open tree. Before you use the AuditByName method, you must explicitly close any open tree objects (with the Close method.) You receive an error if there are any open trees.

Parameters

Returns

A number: 0 if the tree passes all audits. If this method returns a value not equal to 0, an error is logged.

Example

&ISVALID = &MYTREE.AuditByName("", "", "PERSONAL_DATA", "05-05-1997", "");

See Also

Close, IndirectionMethod.

Auditing and Repairing Trees

Close

Syntax

Close()

Description

The Close method closes the tree, freeing the memory associated with that object, and discarding any changes made to the tree since the last save. The Close method can be used only on an open tree, not a closed tree. This means you must have opened the tree with the Open method before you can close it. To save any changes, you must use the Save method before using Close.

Returns

A number: 0 if the method completed successfully.

See Also

Tree class: Open method.

Copy

Syntax

Copy(FromSetId, FromUserKeyValue, FromTreeName, FromEffDt, FromBranchName, ToSetId, ToUserKeyValue, ToTreeName, ToEffDt, ToBranchName)

Description

The Copy method copies from the tree identified by the From parameters and copies it to the tree identified with the To parameters. The tree specified by the To parameters must be a new tree. You receive an error if the tree already exists. The tree specified by the From parameters does not have to match the tree identifier executing the method.

The Copy method can be used only with a closed tree, it cannot be used on an open tree. Before you use the Copy method, you must explicitly close any open tree objects (with the Close method.) You receive an error if there are any open trees.

To access the new tree, you must use the Open method.

Parameters

Returns

An integer: 0 if copied successfully.

Example

&MYTREE.Copy("","","PERSONAL_DATA", "05-05-1997", "", "","","PERSONAL_EDIT1", "05-⇒
05-1997", "");

See Also

Tree class: Close method, Open method, IndirectionMethod property.

Create

Syntax

Create(SetID, UserKeyValue, TreeName, EffDt, StructureName)

Description

The Create method creates a new tree, based on the parameters passed with the method. The specified tree must be a new tree. You receive an error if the tree already exists.

The Create method can be used only with a closed tree, it cannot be used on an open tree. Before you use the Create method, you must explicitly close any open tree objects (with the Close method.) You receive an error if there are any open trees.

After you create a new tree, you don't have to open it with the Open method. The existing tree object points to the new tree.

The tree structure specified with StructureName determines what database fields the new tree is based on, what pages you can use to create tree nodes and detail values, and what record definitions PeopleSoft Tree Manager saves tree-related data in. The tree structure must already exist.

The new tree must be saved (Save, SaveAs, and so on) for this tree to be saved to the database.

Parameters

Returns

An integer: 0 if created successfully.

Example

&MYTREE.Create("","","PERSONAL_NEW", "05-05-1997", "PERSONAL_DATA");

See Also

Close, IndirectionMethod, Creating Trees.

Delete

Syntax

Delete(SetID, UserKeyValue, TreeName, EffDt, BranchName)

Description

The Delete method deletes the specified tree from the database. The Delete method can be used only with a closed tree, it cannot be used on an open tree. Before you use the Delete method, you must explicitly close any open tree objects (with the Close method.) You receive an error if there are any open trees.

The specified tree does not have to match the tree identifier executing the method.

Parameters

Returns

An integer: 0 if deleted successfully.

Example

&MYTREE=&Session.GetTree();

If ALL(&MYTREE) Then
   &RETVALUE = &MYTREE.Delete("","","PERSONAL_REN2", "05-05-1997", "");
End-If;

See Also

Close, IndirectionMethod.

Exists

Syntax

Exists(SetID, UserKeyValue, TreeName, EffDt, BranchName)

Description

The Exists method finds an existing tree, as specified by the parameters. The parameters must specify a unique tree. If a tree matching the parameters is found, the method returns 0. This method works with either open or closed trees.

Parameters

Returns

An integer: 0 if tree exists.

Example

&RSLT = &MYTREE.Exists("", "", "VENDOR_PER_DATA", "05-03-1998", ""); 
 
If &RSLT = 0 Then 
   /* tree exists, do processing */ 
Else 
   /* tree doesn't exist, do error processing */ 
End-if;

See Also

Tree Structure class: IndirectionMethod property.

FindLeaf

Syntax

FindLeaf(RangeFrom, RangeTo)

Description

The FindLeaf method finds an existing leaf (specified by the range parameters) in the tree executing this method. If the leaf is found, a leaf object is returned. If the leaf isn’t found, a Null is returned.

You can use wildcards with the range parameters. Use an asterisk (*) in place of a number of characters. Use a question mark (?) in place of one character. You can also provide one of the ranges, and specify a Null string for the other.

Suppose you wanted to find the leaf with the range 81005 to 82000. The following would be valid:

&MyLeaf = &MyTree.FindLeaf("81*", "82000");

This would also be valid:

&MyLeaf = &MyTree.FindLeaf("8100?", "82000");

You could also specify this:

&MYLEAF = &MYTREE.FindLeaf("81000", "");

If you specify the exact same value for both RangeFrom and RangeTo, the RangeTo parameter is ignored.

Parameters

Returns

A reference to a leaf object.

Example

&MYLEAF = &MYTREE.FindLeaf("81000", "");

FindNode

Syntax

FindNode(NodeName, Description)

Description

The FindNode method returns a reference to the node object specified by the parameters passed to the method. If the node is found, a node object is returned. If the node isn’t found, a Null is returned.

Note. If you've only specified a node name, and the node you're searching for is in an unexpanded portion of the tree, this method expands the tree down to that node. If you've only specified a node description the search, occurs only in the memory. If the node isn't found, the tree is not expanded.

You should specify either the node name other description, not both. You should specify a Null string for the other. If both are provided, only the node name is used and the description is ignored.

You can use wildcards with the parameters. Use an asterisk (*) in place of a number of characters. Use a question mark (?) in place of one character.

Suppose you wanted to find the node called 10200, with a description of "Human Resources". The following would be valid:

&MyNode = &MyTree.FindNode("", "Human*");

This would also be valid:

&MyNode = &MyTree.FindNode("1020?", "");

You could also use the following:

&MYNODE = &MYTREE.FindNode("10200", "");

Note. If you're searching using wildcared characters and more than one node matches the search conditions, only the first occurence of the node is returned

Parameters

Returns

A reference to a node object.

Example

&MYNODE = &MYTREE.FindNode("10200", "");

FindRoot

Syntax

FindRoot()

Description

The FindRoot method returns a reference to the root node object of the tree object executing the method. This method can be used only on an open tree, not on a closed tree. This means you must have opened the tree with the Open method before you can find the root node.

This method returns an error if the tree has no nodes associated with it.

Returns

A reference to a node object.

Example

&MYNODE = &MYTREE.FindRoot();

See Also

Tree class: Open method.

InsertRoot

Syntax

InsertRoot(NodeName)

Description

The InsertRoot method inserts a node at the top of the tree object executing the method. NodeName is the name of the node you are creating. This parameter takes a string value. The InsertRoot method can be used only on an open tree, not on a closed tree. This means you must have opened the tree with the Open method before you can insert any nodes.

You can insert the root node only in a new tree, that is, a tree that was just created with the Create method. Also, after you create a new tree, you must insert the root node before you can insert any other nodes.

In a strict level tree, the first level must be defined before you can insert the root node.

This method returns an error if the tree already has nodes in it.

Returns

A reference to a node object.

Example

&MyRootNode = &MYTREE.InsertRoot("000001");

See Also

Tree class: Open method.

LeafExists

Syntax

LeafExists(RangeFrom, RangeTo)

Description

The LeafExists method enables you to verify if the leaf specified by the parameters exists in the current tree.

Suppose you wanted to check the leaf with the range 81005 to 82000 exists. The following would be valid:

&MyResult = &MyTree.LeafExists("81005", "82000");

This would also be valid, and would check on leaves up to 82000:

&MyResult = &MyTree.LeafExists("", "82000");

If you specify the exact same value for both RangeFrom and RangeTo, the RangeTo parameter is ignored.

Parameters

Returns

An integer: 0 if the leaf exists.

See Also

Tree class: NodeExists method, FindLeaf method.

LockTree

Syntax

LockTree()

Description

Use the LockTree method to check out a tree for editing. Use this method to prevent saving conflicts when you have multiple users accessing the same tree, using both the Tree API and PeopleSoft Tree Manager. To release a tree, use the UnlockTree method.

Note. In order to use this method, you must have Tree multi-user environment enabled. You can check if it is enabled by using UseUpdateReservation Tree property.

To verify if a tree is already locked, use the LockStatus property.

This method can be used only on an open tree, not on a closed tree. This means you must have opened the tree with the Open method.

Parameters

None.

Returns

An integer: 0 if locked successfully.

See Also

TreeLocksNumber, UnlockTree, HasLockedBranches, LockStatus, UseUpdateReservation.

Open

Syntax

Open(SetID, UserKeyValue, TreeName, EffDt, BranchName, Update)

Description

The Open method opens the tree object specified by the parameters. The Open method can be used only with a closed tree, it cannot be used on an open tree. You cannot read or set any properties of a tree until after you open it. When you open a tree, you can specify whether you want to open it for update, or in read-only mode, with the Update parameter. If you try updating or writing to a tree opened in read-only mode, you receive an error.

Note. Because EFFDT is a key field for a tree definition, an exact match is required to open a tree with the Open method. A less restrictive method, OpenAsOfDate, provides an alternative to Open by specifying an AsOfDate parameter instead of the EffDt parameter.

Parameters

Returns

An integer: 0 if opened successfully.

Example

The following example opens a tree object, then tests to see if the tree was actually opened:

&RSLT = &MYTREE.Open("","","PERSONAL_DATA", "05-05-1997", "", True);

If &RSLT = 0 Then 
   /* normal processing */ 
Else 
   /* error processing tree isn't open */ 
End-if;

See Also

Close, OpenAsOfDate.

IndirectionMethod

OpenAsOfDate

Syntax

OpenAsOfDate(SetID, UserKeyValue, TreeName, AsOfDate, BranchName, Update)

Description

The OpenAsOfDate method operates similarly to the Open method and uses the same parameters except that instead of requiring the EffDt parameter, OpenAsOfDate uses a less restrictive AsOfDate parameter. The OpenAsOfDate method opens the most recent tree based on AsOfDate. If AsOfDate is not supplied, the current date is used.

Note. Because EFFDT is a key field for a tree definition, an exact match is required to open a tree with the Open method.

The OpenAsOfDate method can be used only with a closed tree; it cannot be used on an open tree. You cannot read or set any properties of a tree until after you open it. When you open a tree, you can specify whether you want to open it for update, or in read-only mode, with the Update parameter. If you try updating or writing to a tree opened in read-only mode, you receive an error.

Parameters

Returns

An integer: 0 if opened successfully.

Example

The following example opens a tree object with most recent effective date matching the other tree criteria. Then, the program tests to see if the tree was actually opened:

&ret = &MyTree.OpenAsOfDate("QEDM1","","PERSONAL_DATA", "", "", True);

If &ret = 0 Then 
   /* normal processing */ 
Else 
   /* error processing tree isn't open */ 
End-if;

See Also

Open

OpenForExport

Syntax

OpenForExport(SetID, UserKeyValue, TreeNameEffDt)

Description

Use the OpenForExport method to open a tree for export processes (using TreeMover.)

Parameters

Returns

An integer: 0 if opened successfully.

Example

If &TREE.OpenForExport(&SETID, &USERKEYVALUE, &TREE_NAME, &TREE_EFFDT) <> 0 Then 

/* processing */

End-if;

See Also

File Layout Details.

OpenWholeTree

Syntax

OpenWholeTree(SetID, UserKeyValue, TreeName, EffDt)

Description

The OpenWholeTree method enables you to open a tree as if it were an unbranched tree. With this kind of tree, branched nodes cannot be distinguished from unbranched nodes. This means you can traverse the entire tree. It also means that branches have a node icon, not a branch icon. This method can be used only with a closed tree, it cannot be used on an open tree. You cannot read any properties of a tree until after you open it. This tree is always opened as read-only.

Note. You can't open a tree using this method and update it. The tree is opened in read-only mode.

Parameters

Returns

An integer: 0 if opened successfully.

Example

&pSession = %Session; 
    
&pTreeObj = &pSession.GetTree(); 
&status = &pTreeObj.OpenWholeTree(&Setid, &SetCntrlValue, &TreeName, String(&Eff⇒
Dt));

See Also

Close, IndirectionMethod.

NodeExists

Syntax

NodeExists(NodeName)

Description

The NodeExists method enables you to verify if the node specified by NodeName exists in the current tree.

Note. If the node you're searching for is in an unexpanded portion of the tree, this method expands the tree down to that node.

Parameters

Returns

An integer: 0 if the node exists.

See Also

Tree class: FindLeaf method, FindNode method, LeafExists method.

Rename

Syntax

Rename(FromSetId, FromUserKeyValue, FromTreeName, FromEffDt, FromBranchName, ToTreeName)

Description

The Rename method renames a tree specified with the From parameters to the tree specified with ToTreeName. The tree specified by ToTreeName must be a new tree. You receive an error if the tree already exists. The tree specified by the From parameters does not have to match the tree executing the method.

The Rename method can be used only with a closed tree, it cannot be used on an open tree. Before you use the Rename method, you must explicitly close any open tree objects (with the Close method.) You receive an error if there are any open trees.

To access the new tree, you must use the Open method.

Parameters

Returns

An integer: 0 if renamed successfully.

Example

&MYTREE.Rename("","","PERSONAL_DATA3", "05-05-1997","", "PERSONAL_REN2");

See Also

Tree class: Close method, Open method, Close method, IndirectionMethod property.

Save

Syntax

Save()

Description

The Save method writes any changes to the tree executing the method to the database. It also performs audits.

The Save method can be used only on an open tree, not on a closed tree. This means you must have opened the tree with the Open method before you can save it.

The tree object remains open after executing Save. You must execute the Close method on the object before it is closed and the memory freed.

This method returns an optional Boolean value: True if the tree was saved with no errors, False if there are one or more errors.

Note. If you’re calling the Tree API from an Application Engine program, the data won’t actually be committed to the database until the Application Engine program performs a COMMIT.

See Also

Auditing and Repairing Trees.

Parameters

None.

Returns

An integer: 0 if save successfully.

SaveAs

Syntax

SaveAs(SetID, UserKeyValue, TreeName, EffDt, BranchName)

Description

The SaveAs method writes any changes to the tree executing the method to the new tree specified with the parameters. It also performs audits.

The tree specified with the parameters must be a new tree. You receive an error if the tree already exists. The new tree must have at least one different key field from the original tree.

The SaveAs method automatically closes the tree that is associated with the tree object executing the method, and associates that tree object with the new tree. Any changes made to the original tree since the last time the tree was saved are discarded. For example, suppose you opened a tree named DEPENDENT_BENEF and associated it with the variable &MYTREE. If you executed the SaveAs method with &MYTREE, changing the name to DEPENDENT_BENEF2, &MYTREE would now be associated with DEPENDENT_BENEF2, and the original tree, DEPENDENT_BENEF, would be closed.

&MYTREE.Open("", "", "DEPENDENT_BENEF", "02-02-1999", "", False); 
/* do some processing */ 
&MYTREE.SaveAs("", "", "DEPENDENT_BENEF2", "02-05-1999", "");

&MYTREE is now associated with DEPENDENT_BENEF2, not with the original open tree.

Note. If you’re calling the Tree API from an Application Engine program, the data won’t actually be committed to the database until the Application Engine program performs a COMMIT.

Parameters

Returns

This method returns an integer: 0 if saved successfully, a number greater than 0 otherwise.

Example

&MYTREE.SaveAs("", "", "DEPENDENT_BENEF2", "02-05-1999", "");

See Also

Auditing and Repairing Trees.

SaveAsDraft

Syntax

SaveAsDraft(SetID, UserKeyValue, TreeName, EffDt, Branch`Name)

Description

The SaveAsDraft method writes any changes to the tree executing the method to the new tree specified with the parameters. However, it does not perform audits. Trees that are saved in this way are marked as "draft" and will not be valid (that is, cannot be used with other PeopleTools) until the tree audit is passed during Save, SaveAs, or the Tree Audits Application Engine Tree Utility program..

The tree specified with the parameters must be a new tree. You receive an error if the tree already exists. The new tree must have at least one different key field from the original tree.

The SaveAsDraft method automatically closes the tree that is associated with the tree object executing the method, and associates that tree object with the new tree. Any changes made to the original tree since the last time the tree was saved are discarded.

See SaveAs for more details.

Note. If you’re calling the Tree API from an Application Engine program, the data won’t actually be committed to the database until the Application Engine program performs a Commit.

Parameters

Returns

This method returns an integer: 0 if saved successfully, a number greater than 0 otherwise.

Example

&MYTREE.  SaveAsDraft("","","PERSONAL_EDIT2", "05-05-1997", "");

See Also

Auditing and Repairing Trees.

SaveDraft

Syntax

SaveDraft()

Description

The SaveDraft method writes any changes to the tree executing the method to the database. However, it does not perform audits. Trees that are saved in this way are marked as "draft" and will not be valid (that is, cannot be used with other PeopleTools) until the tree audit is passed.

The SaveDraft method can be used only on an open tree, not on a closed tree. This means you must have opened the tree with the Open method before you can save it.

The tree object remains open after executing SaveDraft. You must execute the Close method on the object before it is closed and the memory freed.

Note. If you’re calling the Tree API from an Application Engine program, the data won’t actually be committed to the database until the Application Engine program performs a Commit.

Parameters

None.

Returns

This method returns an integer: 0 if saved successfully, a number greater than 0 otherwise.

See Also

Tree class: Close method, Open method.

Auditing and Repairing Trees

SetImportMode

Syntax

SetImportMode(Nodes_NumberLeaves_Number)

Description

Use the SetImportMode method to set up special memory allocation and simplified processing rules when running Tree Import.

This special mode also cuts back on the number of SQL calls by not getting node descriptions. This mode also blocks internal validation while inserting new node or leaf from an input file. All validation occurs during saving.

Parameters

Returns

An integer: 0 if set successfully.

See Also

File Layout Details.

TreeLocksNumber

Syntax

TreeLocksNumber(setID, UserKeyValue, TreeName, EffDt)

Description

Use the TreeLocksNumber method to determine how many users have checked out any branches of a current tree. This method should be used to check if a tree definition could be changed without affecting other users working in different branches of a tree.

Note. In order to use this method, you must have Tree multi-user environment enabled. You can check if it is enabled by using UseUpdateReservation Tree property.

You can use the TreeLocksNumber method with a both an open as well as a closed tree.

Parameters

Returns

The number of locked branches. If the tree is not branched, but is checked out, the return value is 1.

See Also

LockTree, UnlockTree, UnlockTree, UseUpdateReservation.

UnlockTree

Syntax

UnlockTree()

Description

Use the UnlockTree method to release a tree after editing. Use this method to prevent saving conflicts when you have multiple users accessing the same tree, using both the Tree API and PeopleSoft Tree Manager. To checkout a tree, use the LockTree method.

Note. In order to use this method, you must have Tree multi-user environment enabled. You can check if it is enabled by using UseUpdateReservation Tree property.

To verify if a tree is checked out, use the LockStatus property.

This method can be used only on an open tree, not on a closed tree. This means you must have opened the tree with the Open method.

Parameters

None.

Returns

An integer: 0 if the tree is released successfully.

See Also

LockTree, LockStatus, UseUpdateReservation.

UpdateLock

Syntax

UpdateLock()

Description

Use the UpdateLock method to update the timestamp representing time when the user who has the tree checked out performed the last action on a tree.

Note. In order to use this method, you must have Tree multi-user environment enabled. You can check if it is enabled by using UseUpdateReservation Tree property.

Use this method to indicate that user who has the tree checked out is still working with it. The tree won't be released unless the Tree Inactivity Period specified on the People Tools Options page is expired.

This method should be called from PeopleCode in a response to any user action happened on a Tree Manager page.

This method can be used only on an open tree, not on a closed tree. This means you must have opened the tree with the Open method.

Parameters

None.

Returns

An integer: 0 if activity time was updated successfully.

See Also

LockTree, UnlockTree, UseUpdateReservation.

Tree Class Properties

In this section, we discuss the Tree class properties. The properties are discussed in alphabetical order.

AllValues

Description

When the tree is audited, the AllValues property specifies whether the audit should verify that the tree includes all user data detail values. This property returns a Boolean value: True, check all values, False, do not check all values.

If this is a new tree, and you do not set this property, a default value of False is automatically set.

This property can be used only with an open tree, that is, you must use the Open method on the tree before you can use this property.

This property is read-write.

Example

&MyTree.AllValues = False;

AuditDetails

Description

Set this property to False in cases when you do not want to perform Detail Audit. It could happend if you are reusing existing structure that contains Detail information for tree that does not use details('Winter' tree).

The default value for this property is True.

This property is read-write.

Branches

Description

This property returns a reference to a branch collection object. This property is used only with branched trees: it returns Null for trees that aren’t branched.

This property can be used only with an open tree, that is, you must use the open the tree using the Open method before you can use this property.

This property is read-only.

BranchImageName

Description

Use this property to specify the image used to display branches on a page. This property takes a string value.

This property is read-write.

BranchLevel

Description

This property returns the level number (as a number) where this branch occurs in the tree. This property is used only with trees with levels: it returns zero for trees that don’t have levels.

This property can be used only with an open tree, that is, you must open the tree using the Open method before you can use this property.

This property is read-only.

Example

&LevelNumber = &MyTree.BranchLevel;

BranchName

Description

This property returns the name of the specific branch for the tree, as a string. This property is used only with branched trees: it returns an empty string for trees that aren’t branched.

This property can be used only with an open tree, that is, you must open the tree using the Open method before you can use this property.

This property is read-only.

Example

&BranchName = &MyTree.BranchName;

Category

Description

This property returns the category name for the tree, as a string. The category is a high-level grouping under which you can organize your tree structures and tree definitions. If you are creating a new tree, this property is required.

This property can be used only with an open tree, that is, you must open the tree using the Open method before you can use this property.

This property is read-write.

Example

&MyTree.Category = "PurchaseOrders";

Description

Description

This property returns the description of the tree, as a string. If you are creating a new tree, this property is required.

This property can be used only with an open tree, that is, you must open the tree using the Open method before you can use this property.

This property is read-write.

Example

&MyTree.Description = "Departmental Security";

DuplicateLeaves

Description

In most trees, you want each detail value to appear only once in the tree. To permit duplicate values, set this property to True.

If this is a new tree, and you do not set this property, a default value of False is automatically set.

This property can be used only with an open tree, that is, you must open the tree using the Open method before you can use this property.

This property is read-write.

EffDt

Description

This property returns the effective date of the tree, as a date.

Note. PeopleSoft does not recommnd using this property to change data, as changes are not stored in the database.

If this is a new tree, and you do not set this property, a default value of the current date is automatically set.

This property can be used only with an open tree, that is, you must open the tree using the Open method before you can use this property.

This property is read-write.

Example

&TreeEffDt = &MYTREE.EffDt;

HasDetailRanges

Description

This property returns True if the tree has any detail ranges.

This property can be used only with an open tree, that is, you must open the tree using the Open method before you can use this property.

This property is read-only.

HasLockedBranches

Description

This property indicates whether any user other then current one has checked out any branch in a tree. This property returns a Boolean value: true if the tree has checked out branches, false otherwise.

Note. In order to use this method, you must have Tree multi-user environment enabled. You can check if it is enabled by using UseUpdateReservation Tree property.

This property can be used only with an open tree, that is, you must open the tree using the Open method before you can use this property.

This property is read-only.

IsBranched

Description

This property indicates whether the tree is branched. Possible values for this property are True and False: True if the tree is branched, False if it isn’t.

This property can be used only with an open tree, that is, you must open the tree using the Open method before you can use this property.

This property is read-only.

Example

If &MyTree.IsBranched Then 
   /* Do branched processing */ 
Else 
   /*Do unbranched processing */ 
End-If;

IsChanged

Description

This property returns True if the tree has been changed but not saved, False if the tree is unchanged.

This property can be used only with an open tree, that is, you must open the tree using the Open method before you can use this property.

This property is read-only.

Example

If &MyTree.IsChanged Then 
   &MyTree.Save(); 
End-if;
&MyTree.Close();

IsOpen

Description

This property returns True if the tree is open, False if the tree is closed.

This property is read-only.

Example

If Not &MyTree.IsOpen Then 
   &MyTree.Open("","","PERSONAL_DATA", &Date, "", True); 
End-If;

IsQueryTree

Description

This property returns True if the tree is a Query access tree. It returns False if the tree is not a Query Access Tree.

This property can be used only with an open tree, that is, you must open the tree using the Open method before you can use this property.

This property is read-only.

IsValid

Description

This property returns True if the tree is a valid tree that has passed all audits. It returns False otherwise.

This property can be used only with an open tree, that is, you must open the tree using the Open method before you can use this property.

This property is read-only.

See Also

Auditing and Repairing Trees.

IsVersionChanged

Description

This property indicates if a tree version has been changed in the database. This property returns a Boolean value, true if the version was changed, false otherwise.

Use this function in a multi-user environment to check if a tree loaded in a read-only mode by User1 should be reloaded. A possible reason why it needs to be reloaded could be triggered by tree version change after User2, who had this tree checked out, released it.

This property can be used only with an open tree, that is, you must open the tree using the Open method before you can use this property.

This property is read-only.

IsWholeTree

Description

This property indicates whether the entire tree is accessible. This property is set to True if a tree was opened using OpenWholeTree method. The OpenWholeTree method opens a tree in read-only mode without paying attention to the existing tree branches.

This property can be used only with an open tree, that is, you must open the tree using the Open method before you can use this property.

This property is read-only.

Example

If &MyTree.IsWholeTree Then 
   /* Do processing */ 
Else 
   /* close tree and reopen using OpenWholeTree method */ 
End-If;

KeyBranchName

Description

This property returns the branch name of the tree as a string if the tree is branched. If not branched, this property returns a blank string.

This property can be used with a closed tree, that is, before you use the Open method.

If the tree has already been opened, you can use the KeyBranchName property to get the tree branch name

This property is read-only.

KeyEffDt

Description

This property returns the effective date of the tree as a string if the tree is effective-dated. If not effective-dated, this property returns a blank string.

This property can be used with a closed tree, that is, before you use the Open method.

If the tree has already been opened, you can use the KeyEffDt property to get the tree effective date

This property is read-only.

KeyName

Description

This property returns the name of the tree as a string.

This property can be used with a closed tree, that is, before you use the Open method.

If the tree has already been opened, you can use the Name property to get the tree name.

This property is read-only.

KeySetId

Description

This property returns the SetID of the tree as a string if the tree has a SetID. If the tree doesn’t have a SetID, this property returns a blank string.

This property can be used with a closed tree, that is, before you use the Open method.

If the tree has already been opened, you can use the KeySetId to get the tree Set Id.

This property is read-only.

KeyUserKeyValue

Description

This property returns the UserKeyValue of the tree as a string if the tree has a UserKeyValue. If the tree doesn’t have a UserKeyValue, this property returns a blank string.

This property can be used with a closed tree, that is, before you use the Open method.

If the tree has already been opened, you can use the KeyUserKeyValue to get the tree UserKeyValue.

This property is read-only.

LeafCount

Description

This property returns the number of leaves in the tree.

This property can be used only with an open tree, that is, you must use the Open method on the tree before you can use this property.

This property is read-only.

LeafImageName

Description

Use this property to specify the image used to display leaves on a page. This property takes a string name.

This property is read-write.

LeafOnClipboard

Description

Use this property to determine if a leaf has been cut and is available to be 'pasted' into tree. This property returns a Boolean value: True if a leaf object exists on the clipboard, False otherwise.

This property is read-only.

LevelCount

Description

This property returns the number of levels defined for the tree. If the tree doesn’t have any levels, this property returns zero (0).

See the LevelUse property.

Valid value range is a number between 0 and 99.

This property can only be used with an open tree, that is, you must use the Open method on the tree before you can use this property.

This property is read-only.

See Also

Tree class: LevelUse property.

Levels

Description

This property returns a reference to a level collection object. This property is used only with trees that have levels: it returns Null for trees that don’t have levels.

This property can be used only with an open tree, that is, you must open the tree using the Open method before you can use this property.

This property is read-only.

See Also

Level Collection Methods.

LevelUse

Description

This property returns the level use of the tree. The values are:

If this is a new tree, and you do not set this property, the default value is Strict Levels.

This property can be used only with an open tree, that is, you must open the tree using the Open method before you can use this property.

This property is read-write.

Example

If &MyTree.LevelUse = "S" Then 
/* add levels */ 
End-If;

LockOwner

Description

This property returns the user ID of the user who has checked out a specific tree or a tree branch, as a string.

Note. In order to use this method, you must have Tree multi-user environment enabled. You can check if it is enabled by using UseUpdateReservation Tree property.

This property can be used only with an open tree, that is, you must open the tree using the Open method before you can use this property.

This property is read-only.

LockStatus

Description

This property indicates if an opened tree is checked out.

Note. In order to use this method, you must have Tree multi-user environment enabled. You can check if it is enabled by using UseUpdateReservation Tree property.

Possible values are:

This property is read-only.

See Also

LockTree, TreeLocksNumber, UnlockTree, LockOwner.

Name

Description

This property returns the name of the tree, as a string.

Note. Do not use this property to change the name of an existing tree. The change will not be reflected in the database. You must use the Rename method to change the name of an existing tree.

This property can be used only with an open tree, that is, you must open the tree using the Open method before you can use this property.

This property is read-write.

Example

&TreeName = &MyTree.Name;

See Also

Tree class: Rename method.

NodeColImageName

Description

Use this property to specify the image displayed for a collapsed node. This property takes a string value.

This property is read-write.

NodeCount

Description

This property returns the number of nodes for the tree. A valid tree must have at least one node.

This property can be used only with an open tree, that is, you must open the tree using the Open method before you can use this property.

This property is read-only.

NodeExpImageName

Description

Use this property to specify the displayed image of an expanded node. This property takes a string value.

This property is read-write.

NodeOnClipboard

Description

Use this property to determine if a node has been cut and is available to be 'pasted' into a tree. This property returns a Boolean value: True if a node object exists on the clipboard, False otherwise.

This property is read-only.

ParentLevel

Description

This property returns the number of the parent branch level in a branched tree. If the tree does not have levels or is an unbranched tree, zero (0) is returned. Valid value range is a number between 0 and 100.

This property can be used only with an open tree, that is, you must open the tree using the Open method before you can use this property.

This property is read-only.

ParentName

Description

This property returns the name of the parent branch in a branched tree, as a string. If the tree does not have levels, is an unbranched tree, or if the tree is the root level, Null is returned.

This property can be used only with an open tree, that is, you must open the tree using the Open method before you can use this property.

This property is read-only.

PerformanceMethod

Description

This property sets the method to use for select and join statements used to generate SQL with the tree. This property is used with nVision layouts and Query.

The values for this property are:

If this is a new tree, and you do not set this property, the default value "D" is automatically set.

This property can be used only with an open tree, that is, you must open the tree using the Open method before you can use this property.

This property is read-write.

See Also

Introduction to PeopleSoft Tree Manager, Understanding PS/nVision.

PerformanceSelector

Description

This property selects the tree selectors for nVision for the tree. This property is used with nVision layouts and Query.

The values for this property are:

If this is a new tree, and you do not set this property, the default value "S" is automatically set.

This property can be used only with an open tree, that is, you must open the tree using the Open method before you can use this property.

This property is read-write.

See Also

Understanding PS/nVision.

PerformanceSelectorOption

Description

This property selects the tree selector options for nVision for the tree. This property is used with nVision layouts and Query.

The values for this property are:

If this is a new tree, and you do not set this property, the default value "R" is automatically set.

This property can be used only with an open tree, that is, you must open the tree using the Open method before you can use this property.

This property is read-write.

See Also

Understanding PS/nVision.

SetID

Description

This property returns the SetID for the tree, as a string. This property is used only when the IndirectionMethod property for the tree structure the tree is based on has been set to "S". Otherwise, this property returns Null.

This property can be used only with an open tree, that is, you must open the tree using the Open method before you can use this property.

This property is read-write.

Note. PeopleSoft does not recommend setting the SetID for a tree, as there is no way to save this value to the database.

See Also

Tree Structure class: IndirectionMethod property.

Status

Description

This property returns the effective status of the tree. The values are:

This property can be used only with an open tree, that is, you must open the tree using the Open method before you can use this property.

This property is read-write.

Structure

Description

This property returns a reference to the tree structure of the tree. Before you can use some of the methods or any of the properties of a tree structure, you must use the Open method to open the tree structure.

This property can be used only with an open tree, that is, you must open the tree using the Open method before you can use this property.

This property is read-only.

StructureName

Description

This property returns the name (structure ID) of the tree structure the tree is based on, as a string. This property can be set only with a new tree.

Note. Even though this is a writable property, you will receive an error if you try to change the tree structure for an existing tree.

This property can be used only with an open tree, that is, you must open the tree using the Open method before you can use this property.

This property is read-write.

See Also

Tree class: SetID property.

TreeImageName

Description

Use this property to specify the displayed image for a tree. This property takes a string value.

This property is read-write.

UserKeyValue

Description

Use this property to read the key field value for the Node User Key Field specified from the NodeRecord on the associated tree structure.

This property is used only when the IndirectionMethod property for the tree structure has been set to "U" or "B". Otherwise, this property returns Null.

This property is read-write.

Note. PeopleSoft does not recommend setting the UserKeyValue for a tree, as there is no way to save this value to the database.

See Also

Tree Structure class: NodeRecord property, IndirectionMethod property.

UseUpdateReservation

Description

This property indicates if multi-user environment features are used. This property returns a Boolean value, true if multi-user environments features are used, false otherwise.

This property can be used with either an open or a closed tree.

This property is read-only.

Tree Structure Class

Tree structure objects are instantiated from the following:

• From a session object with the GetTreeStructure method.

• From a tree object with the Structure property.

See GetTreeStructure, Structure.

Tree Structure Class Methods

In this section, we discuss the Tree Structure class methods. The methods are discussed in alphabetical order.

Close

Syntax

Close()

Description

The Close method closes the tree structure object executing the method, freeing the memory associated with that object, and discarding any changes made to the tree structure. The Close method can be used only on an open tree structure, not on a closed tree structure. This means you must have opened the tree structure with the Open method before you can save it. To save any changes, you must use the Save method before using Close.

Returns

A number; 0 if the method completed successfully.

Copy

Syntax

Copy(FromStructId, ToStructId)

Description

The Copy method copies the tree structure specified with FromStructId to the tree structure specified with ToStructId. Both parameters take string values. The tree structure specified by ToStructId must be a new tree structure. You receive an error if the tree structure already exists.

The Copy method can only be used with a closed tree structure, it cannot be used on an open tree structure. Before you use the Copy method, you must explicitly close any open tree structure objects (with the Close method.) You receive an error if there are any open tree structures.

To access the new tree structure, you must use the Open method.

Returns

A number; 0 if the method completed successfully.

Example

&MyTreeStruct = &MySession.GetTreeStructure(); 
&RetValue = &MyTreeStruct.Copy(PERSONAL_DATA, PERSONAL_DATA2);

Create

Syntax

Create(StructId, Type)

Description

The Create method creates a tree structure with the name StructId, and of the type Type. Both parameters take a string value.

Note. If the tree structure already exists, it is overwritten with the newly created tree structure.

The Create method can be used only with a closed tree structure, it cannot be used on an open tree structure. Before you use the Create method, you must explicitly close any open tree structure objects (with the Close method.) You receive an error if there are any open tree structures.

The new tree structure must be saved (using the Save method) for this structure to be saved to the database.

After you create a new tree structure, you can open it with the Open method.

The values for Type are:

• "D": create a detail tree structure.

• "S": create a summary tree structure.

Currently, only the value of "D" is supported for the Type parameter. You can specify an empty string for Type. If you need to create a summary structure follow the example below:

&MYSTRUCT=&SESSION.GETSTRUCTURE();
IF ALL( &MYSTRUCT) THEN
   &RETVALUE=&MYSTRUCT.CREATE('DEPARTMENT_SUM',' ');
     IF NONE(&RETVALUE) THEN
        &MYSTRUCT.TYPE = 'S';
     END-IF;
   &RETVALUE=&MYSTRUCT.SAVE();
   &RETVALUE=&MYSTRUCT.CLOSE();
END-IF;

Delete

Syntax

Delete(StructId)

Description

The Delete method deletes the tree structure specified by StructId from the database. The Delete method can be used only with a tree structure identifier, it cannot be used on a fully instantiated, open tree structure. Before you use the Delete method, you must explicitly close any open tree structure objects (with the Close method.) You receive an error if there are any open tree structures.

The tree structure specified by StructId does not have to match the tree structure identifier executing the method.

Returns

A number: 0 if the method completed successfully.

Open

Syntax

Open(StructId, Update)

Description

The Open method opens the tree structure specified by StructId. StructId takes a string value. You cannot read or set any properties of a tree structure until after you open it.

When you open a tree structure, you can specify whether you want to open it for update, or in read-only mode, with the Update parameter. Update takes a Boolean value. Values for Update are:

• "True": open tree structure in update mode (read-write).

• "False": open tree structure in read-only mode.

If you try updating or writing to a tree structure opened in read-only mode, your changes are ignored.

Returns

A number: 0 if the method completes successfully.

Example

&MyTreeStruct = &MySession.GetTreeStructure(); 
&REtValue = &MyTreeStruct.Open("ACCESS_GROUP", True);

Rename

Syntax

Rename(FromStructId, ToStructId)

Description

The Rename method renames the tree structure specified with FromStructId to the new name specified by ToStructId. Both parameters take a string value. The tree structure specified by ToStructId must be a new tree structure. You receive an error if the tree structure already exists. The change is automatically reflected in the database.

The Rename method can only be used with a closed tree structure, it cannot be used on an open tree structure. Before you use the Rename method, you must explicitly close any open tree structure objects (with the Close method.) You receive an error if there are any open tree structures.

Returns

A number: 0 if the method completes successfully.

Save

Syntax

Save()

Description

The Save method writes any changes to the tree structure executing the method to the database.

The Save method can be used only on an open tree structure, not on a closed tree structure. This means you must have opened the tree structure with the Open method before you can save it.

The tree structure object remains open after executing Save. You must execute the Close method on the object before it is closed and the memory freed.

Note. If you’re calling the Tree API from an Application Engine program, the data won’t actually be committed to the database until the Application Engine program performs a Commit.

Returns

A number: 0 if the method completes successfully.

Tree Structure Class Properties

In this section, we discuss the Tree Structure class properties. The properties are discussed in alphabetical order.

Description

Description

This property returns the description for the tree structure, as a string. The description is the text that displays in list boxes or reports.

This property can be used only with an open tree structure, that is, you must use the Open method on the tree structure before you can use this property.

This property is read-write.

Example

&MYTREESTRUCT.Description = "Department Security Chart";

DetailComponent

Description

This property returns the name of the detail component for the tree structure as a string.

This property can be used only with an open tree structure, that is, you must use the Open method on the tree structure before you can use this property.

This property is read-write.

DetailField

Description

This property returns the name of the detail field for the tree structure, as a string. This property is valid only if you define a detail tree structure. If you create a node-oriented tree structure, this property is not required. This field must exist on the specified DetailRecord.

This property can be used only with an open tree structure, that is, you must use the Open method on the tree structure before you can use this property.

This property is read-write.

Example

The following example sets the DetailPage, DetailRecord, and DetailField properties for a tree structure. Note that the names of the page, record, and field are all capitalized: this is required for all PeopleSoft page, record, and field names.

&MYTREESTRUCT.DetailPage = "BUS_UNIT_TREE_INV"; 
&MYTREESTRUCT.DetailRecord = "BUS_UNIT_TBL_IN"; 
&MYTREESTRUCT.DetailField = "BUSINESS_UNIT";

See Also

Tree Structure class: DetailRecord property.

DetailMenu

Description

This property returns the name of the detail menu for the tree structure, as a string. If the page you use for detail values (DetailPage property) is part of a component, and you want to have access to the other pages in that group when you edit a node value, enter the name of the menu and menu bar for the component in the DetailMenu and DetailMenuBar properties.

This property is valid only if you define a detail tree structure. If you create a node-oriented tree structure, this property isn’t required.

This property can be used only with an open tree structure, that is, you must use the Open method on the tree structure before you can use this property.

This property is read-write.

DetailMenuBar

Description

This property returns the name of the detail menu bar for the tree structure, as a string. If the page you use for detail values (DetailPage property) is part of a component, and you want to have access to the other pages in that group when you edit a node value, enter the name of the menu and menu bar for the component in the DetailMenu and DetailMenuBar properties.

This property is valid only if you’re define a detail tree structure. If you create a node-oriented tree structure, this property isn’t required.

This property can be used only with an open tree structure, that is, you must use the Open method on the tree structure before you can use this property.

This property is read-write.

DetailMenuItem

Description

This property returns the name of the detail menu item for the tree structure as a string.

This property can be used only with an open tree, that is, you must open the tree using the Open method before you can use this property.

This property is read-write.

DetailMultiNavigate

Description

This property sets or returns a Boolean value indicating whether the detail mulit-navigation tree structure navigation option has been selected or not: True, the Detail Multi-Navigation check box has been selected, False otherwise.

This property is read-write.

See Also

NodeMultiNavigate, Setting Multinavigation Paths.

DetailPage

Description

This property returns the name of the detail page for the tree structure as a string. If the page you use for detail values (DetailPage property) is part of a component, and you want to have access to the other pages in that group when you edit a node value, enter the name of the menu and menu bar for the component in the DetailMenu and DetailMenuBar properties.

This property is valid only if you’re defining a detail tree structure. If you’re creating a node-oriented tree structure, this property isn’t required.

This property can be used only with an open tree structure, that is, you must open the tree structure with the Open method before you can use this property.

This property is read-write.

Example

The following example sets the DetailPage, DetailRecord, and DetailField properties for a tree structure. Note that the names of the page, record, and field are all capitalized: this is required for all PeopleSoft page, record, and field names.

&MYTREESTRUCT.DetailPage = "BUS_UNIT_TREE_INV"; 
&MYTREESTRUCT.DetailRecord = "BUS_UNIT_TBL_IN"; 
&MYTREESTRUCT.DetailField = "BUSINESS_UNIT";

DetailRecord

Description

This property returns the name of the detail record for the tree structure as a string. This property is valid only if you define a detail tree structure. If you create a node-oriented tree structure, this property isn’t required.

This property can be used only with an open tree structure, that is, you must open the tree structure with the Open method before you can use this property.

This property is read-write.

Example

The following example sets the DetailPage, DetailRecord, and DetailField properties for a tree structure. Note that the names of the page, record, and field are all capitalized: this is required for all PeopleSoft page, record, and field names.

&MYTREESTRUCT.DetailPage = "BUS_UNIT_TREE_INV"; 
&MYTREESTRUCT.DetailRecord = "BUS_UNIT_TBL_IN"; 
&MYTREESTRUCT.DetailField = "BUSINESS_UNIT";

IndirectionMethod

Description

When you set up a tree structure, you can set the indirection at the bottom of the Structure tab, with the radio buttons in the Additional Key Field.

Structure tab for Tree Structure setup

In the Tree Classes API, you set these same values with the IndirectionMethod property. The values are:

• "S": SetID Indirection.

• "B": Business Unit.

• "U": User Defined Node Key.

• "N": None.

Both the User Defined Node Key and the Business Unit are the key field set with the NodeRecord property for this tree structure. If Business Unit is set, the key field set with the NodeRecord property is a business unit.

If you are creating a new tree structure, and you do not explicitly set this property, None ("N") is the default value, and is automatically set.

This property can be used only with an open tree structure, that is, you must open the tree structure with the Open method before you can use this property.

This property is read-write.

See Also

Tree Structure class: IndirectionMethod property, NodeRecord property.

KeyName

Description

This property returns the name of the tree structure as a string.

This property can be used with a closed tree structure.

This property is read-only.

LevelComponent

Description

This property returns the name of the level component for the tree structure as a string.

This property can be used only with an open tree structure, that is, you must open the tree structure with the Open method before you can use this property.

This property is read-write.

LevelMenu

Description

This property returns the name of the level menu for the tree structure as a string. If the page you use for level values (LevelPage property) is part of a component, and you want to have access to the other pages in that group when you edit a node value, enter the name of the menu and menu bar for the component in the LevelMenu and LevelMenuBar properties.

This property can be used only with an open tree structure, that is, you must open the tree structure with the Open method before you can use this property.

This property is read-write.

LevelMenuBar

Description

This property returns the name of the level menu bar for the tree structure as a string. If the page you use for level values (LevelPage property) is part of a component, and you want to have access to the other pages in that group when you edit a node value, enter the name of the menu and menu bar for the component in the LevelMenu and LevelMenuBar properties.

This property can be used only with an open tree structure, that is, you must open the tree structure with the Open method before you can use this property.

This property is read-write.

LevelMenuItem

Description

This property returns the name of the level menu item for the tree structure as a string.

This property can be used only with an open tree structure, that is, you must open the tree structure with the Open method before you can use this property.

This property is read-write.

LevelPage

Description

This property returns the name of the level page for the tree structure object as a string. If you create a new tree structure, and you do not explicitly set this property, TREE_LEVEL is the default value, and is automatically set.

This property can be used only with an open tree structure, that is, you must open the tree structure with the Open method before you can use this property.

This property is read-write.

LevelRecord

Description

This property returns the name of the level record for the tree structure object as a string. If you create a new tree structure, and you do not explicitly set this property, TREE_LEVEL_TBL is the default value, and is automatically set.

This property can be used only with an open tree structure, that is, you must open the tree structure with the Open method before you can use this property.

This property is read-write.

Name

Description

This property returns the name of the tree structure as a string. This is also called the structure ID. Use this property to set the name (structure ID) of a tree structure. This property is required if you are creating a new tree structure.

Note. Do not use this property to change the name of an existing tree structure. The change will not be reflected in the database. You must use the Rename method to change the name of an existing tree structure.

This property can be used only with an open tree structure, that is, you must open the tree structure with the Open method before you can use this property.

This property is read-write.

Example

&Name = &MYTREESTRUCT.Name;

See Also

Tree Structure class: Rename method.

NodeComponent

Description

This property returns the name of the node component for the tree structure as a string.

This property can be used only with an open tree structure, that is, you must open the tree structure with the Open method before you can use this property.

This property is read-write.

NodeField

Description

This returns the name of the field used for storing information about nodes for the tree structure as a string. If you create a new tree structure, and you do not explicitly set this property, TREE_NODE is the default value, and is automatically set. This field must exist on the specified NodeRecord.

This property can be used only with an open tree structure, that is, you must open the tree structure with the Open method before you can use this property.

This property is read-write.

Example

&MYTREESTRUCT.NodeField = "DEPT_ID";

NodeMenu

Description

This property returns the name of the node menu for the tree structure as a string. If the page you use for node values (NodePage property) is part of a component, and you want to have access to the other pages in that group when you edit a node value, enter the name of the menu and menu bar for the component in the NodeMenu and NodeMenuBar properties.

If you create a new tree structure, and you do not explicitly set this property, TREE_MANAGER is the default value, and is automatically set.

This property can be used only with an open tree structure, that is, you must open the tree structure with the Open method before you can use this property.

This property is read-write.

NodeMenuBar

Description

This property returns the name of the node menu bar for the tree structure as a string. If the page you use for node values (NodePage property) is part of a component, and you want to have access to the other pages in that group when you edit a node value, enter the name of the menu and menu bar for the component in the NodeMenu and NodeMenuBar properties.

This property can be used only with an open tree structure, that is, you must open the tree structure with the Open method before you can use this property.

This property is read-write.

NodeMenuItem

Description

This property returns the name of the node menu item for the tree structure as a string.

This property can be used only with an open tree structure, that is, you must open the tree structure with the Open method before you can use this property.

This property is read-write.

NodeMultiNavigate

Description

This property sets or returns a Boolean value indicating whether the node mulit-navigation tree structure navigation option has been selected: True, the Node Multi-Navigation check box has been selected, False otherwise.

This property is read-write.

See Also

DetailMultiNavigate, Setting Multinavigation Paths.

NodePage

Description

This returns the name of the page used for storing information about nodes for the tree structure as a string. If you create a new tree structure, and you do not explicitly set this property, TREE_NODE is the default value, and is automatically set.

This property can be used only with an open tree structure, that is, you must open the tree structure with the Open method before you can use this property.

This property is read-write.

NodeRecord

Description

This returns the name of the record used for storing information about nodes for the tree structure as a string. If you create a new tree structure, and you do not explicitly set this property, TREE_NODE_TBL is the default value, and is automatically set.

If the IndirectionMethod property of this tree structure has been set to "U" or "B", use this property to specify the record that the NodeUserKeyField property will use.

This property can be used only with an open tree structure, that is, you must open the tree structure with the Open method before you can use this property.

This property is read-write.

See Also

Tree Structure class: IndirectionMethod property.

NodeUserKeyField

Description

Use this property to set the key field from the record specified with NodeRecord for use with the IndirectionMethod. This property is identical to the UserKeyValue property for a tree.

This property is used only when the IndirectionMethod property for the tree structure has been set to "U" or "B". Otherwise, this property returns Null.

This property can be used only with an open tree structure, that is, you must open the tree structure with the Open method before you can use this property.

This property is read-write.

See Also

IndirectionMethod, UserKeyValue.

SummarySetId

Description

This property returns the SetID for the detail tree whose detail values the summary tree structure as a string summarizes. This property is valid only for Summary tree structures. Otherwise, this property returns Null.

This property can be used only with an open tree structure, that is, you must open the tree structure with the Open method before you can use this property.

This property is read-write.

SummaryLevelNumber

Description

This property returns the level number for the detail tree whose detail values the summary tree structure summarizes. The level number indicates the level in the detail tree whose nodes the summary tree will use as detail values. The top level in the detail tree is 1, the next is level two, and so on. Valid values are numbers between 1 and 99.

This property is only valid for Summary tree structures. Otherwise, this property returns Null.

This property can be used only with an open tree structure, that is, you must open the tree structure with the Open method before you can use this property.

This property is read-write.

SummaryTreeName

Description

This property returns the name of the detail tree whose detail values the summary tree structure summarizes, as a string. This property is valid only for Summary tree structures. Otherwise, this property returns Null.

This property can be used only with an open tree structure, that is, you must open the tree structure with the Open method before you can use this property.

This property is read-write.

SummaryUserKeyValue

Description

This property returns the name of the tree that the node records the tree structure is summarized to, as a string. This property is valid only for Summary tree structures. This property is used only when the IndirectionMethod property for the tree structure has been set to "U" for User Defined Keys or "B" for Business Unit. Otherwise, this property returns Null.

This property can be used only with an open tree structure, that is, you must open the tree structure with the Open method before you can use this property.

This property is read-write.

See Also

Tree Structure class: IndirectionMethod property.

Type

Description

This property returns the type of the tree structure as a string, whether it is a detail or summary tree structure. The values are:

• "D": detail tree structure.

• "S": summary tree structure.

This property can be used only with an open tree structure, that is, you must open the tree structure with the Open method before you can use this property.

This property is read-write.

Traverse Tree Hierarchy Example

The following is an example to transverse a tree hierarchy and write the information to a file.

Local ApiObject &TreeObj, &RootNodeObj; 
Local number &Res; 
Local string &sSetId, &sSetCntrlValue, &sTreeName, &sBranchName; 
Local File &MyFile; 
 
Function ProcessNodeChildren(&ParentNodeObj As ApiObject) 
    
   Local ApiObject &ChildNodeObj, &ChildLeafObj; 
   Local boolean &First; 
    
   If &ParentNodeObj.HasChildren Then 
       
      &ChildLeafObj = &ParentNodeObj.FirstChildLeaf; 
      While All(&ChildLeafObj) 
         &MyFile.WriteLine("Process Leaf Range From : " | &ChildLeafObj.Range⇒
From); 
         &ChildLeafObj = &ChildLeafObj.NextSib; 
      End-While; 
       
      If &ParentNodeObj.HasChildNodes Then 
         &First = True; 
         &ChildNodeObj = &ParentNodeObj.FirstChildNode; 
         While &First Or 
               &ChildNodeObj.HasNextSib 
             
            If &First Then 
               &First = False; 
            Else 
               &ChildNodeObj = &ChildNodeObj.NextSib; 
            End-If; 
            &MyFile.WriteLine("Process Node : " | &ChildNodeObj.Name); 
            ProcessNodeChildren(&ChildNodeObj); 
             
         End-While; 
      End-If; 
   End-If; 
End-Function; 
 
&TreeObj = %Session.GetTree(); 

If None(&TreeObj) then
   Error("Cannot get a tree");
End-if;

&sSetId = ""; 
&sSetCntrlValue = ""; 
&sTreeName = "QE_JOBCODES"; 
&TreeEffDt = Date("1999-01-01"); 
&sBranchName = ""; 
 
&Res = &TreeObj.OPEN(&sSetId, &sSetCntrlValue, &sTreeName, &TreeEffDt, &sBranch⇒
Name, False); 
If All(&Res) Then 
   Error("Cannot open a tree");
End-If; 
 
&MyFile = GetFile("TreeDump.txt", "A"); 
&RootNodeObj = &TreeObj.FindRoot(); 

&MyFile.WriteLine("Process Root Node : " | &RootNodeObj.Name);

ProcessNodeChildren(&RootNodeObj); 
&MyFile.Close();