Tree Class Methods
In this section, we discuss the Tree class methods. The methods are discussed in alphabetical order.
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.
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
|
Field or Control |
Definition |
|---|---|
| SetID |
Specify the table indirection key for the tree. This parameter takes a string value. If the tree structure the tree is based on has its IndirectionMethod specified as "S", you must specify a SetID. If the tree structure doesn’t have its IndirectionMethod specified as "S", you must enter a Null string (that is, two quotation marks with no blank space between them ("")) for this parameter. |
| UserKeyValue |
Specify the User Key Value for the tree. This parameter takes a string value. If the tree structure the tree is based on has its IndirectionMethod specified as "U" or "B", you must specify a User Key Value. If the tree structure doesn’t have its IndirectionMethod specified as "U" or "B", you must enter a Null string (that is, two quotation marks with no blank space between them ("")) for this parameter. |
| TreeName |
Specify the name for this tree. This parameter takes a string value. |
| EffDt |
Specify the effective date for this tree. This parameter takes a string value. |
| BranchName |
This parameter is required, but it is unused in this release. You must enter a Null string (that is, two quotation marks with no blank space between them ("")) for this parameter. |
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", "");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.
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
|
Field or Control |
Definition |
|---|---|
| FromSetId |
Specify the table indirection key for the tree to be copied from. This parameter takes a string value. If the tree structure the tree is based on has its IndirectionMethod specified as "S", you must specify a SetID. If the tree structure doesn’t have its IndirectionMethod specified as "S", you must enter a Null string (that is, two quotation marks with no blank space between them ("")) for this parameter. |
| FromUserKeyValue |
Specify the User Key Value for the tree to be copied from. This parameter takes a string value. If the tree structure the tree is based on has its IndirectionMethod specified as "U" or "B", you must specify a User Key Value. If the tree structure doesn’t have its IndirectionMethod specified as "U" or "B", you must enter a Null string (that is, two quotation marks with no blank space between them ("")) for this parameter. |
| FromTreeName |
Specify the name for the tree to be copied from. This parameter takes a string value. |
| FromEffDt |
Specify the effective date for the tree to be copied from. This parameter takes a string value. |
| FromBranchName |
This parameter is required, but it is unused in this release. You must enter a Null string (that is, two quotation marks with no blank space between them ("")) for this parameter. |
| ToSetId |
Specify the table indirection key for the tree to be copied to. This parameter takes a string value. If the tree structure the tree is based on has its IndirectionMethod specified as "S", you must specify a SetID. If the tree structure doesn’t have its IndirectionMethod specified as "S", you must enter a Null string (that is, two quotation marks with no blank space between them ("")) for this parameter. |
| ToUserKeyValue |
Specify the User Key Value for the tree to be copied to. This parameter takes a string value. If the tree structure the tree is based on has its IndirectionMethod specified as "U" or "B", you must specify a User Key Value. If the tree structure doesn’t have its IndirectionMethod specified as "U" or "B" you must enter a Null string (that is, two quotation marks with no blank space between them ("")) for this parameter. |
| ToTreeName |
Specify the name for the tree to be copied to. This parameter takes a string value. |
| ToEffDt |
Specify the effective date for the tree to be copied to. This parameter takes a string value. |
| ToBranchName |
This parameter is required, but it is unused in this release. You must enter a Null string (that is, two quotation marks with no blank space between them ("")) for this parameter. |
Returns
An integer: 0 if copied successfully.
Example
&MYTREE.Copy("","","PERSONAL_DATA", "05-05-1997", "", "","","PERSONAL_EDIT1", "05-05-1997", "");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
|
Field or Control |
Definition |
|---|---|
| SetID |
Specify the table indirection key for the tree. This parameter takes a string value. If the tree structure the tree is based on has its IndirectionMethod specified as "S", you must specify a SetID. If the tree structure doesn’t have its IndirectionMethod specified as "S", you must enter a Null string (that is, two quotation marks with no blank space between them ("")) for this parameter. |
| UserKeyValue |
Specify the User Key Value for the tree. This parameter takes a string value. If the tree structure the tree is based on has its IndirectionMethod specified as "U" or "B", you must specify a User Key Value. If the tree structure doesn’t have its IndirectionMethod specified as "U" or "B", you must enter a Null string (that is, two quotation marks with no blank space between them ("")) for this parameter. |
| TreeName |
Specify the name for this tree. This parameter takes a string value. |
| EffDt |
Specify the effective date for this tree. This parameter takes a string value. |
| StructureID |
Specify the name of the tree structure to use for this tree. This parameter takes a string value. |
Returns
An integer: 0 if created successfully.
Example
&MYTREE.Create("","","PERSONAL_NEW", "05-05-1997", "PERSONAL_DATA");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
|
Field or Control |
Definition |
|---|---|
| SetID |
Specify the table indirection key for the tree. This parameter takes a string value. If the tree structure the tree is based on has its IndirectionMethod specified as "S", you must specify a SetID. If the tree structure doesn’t have its IndirectionMethod specified as "S", you must enter a Null string (that is, two quotation marks with no blank space between them ("")) for this parameter. |
| UserKeyValue |
Specify the User Key Value for the tree. This parameter takes a string value. If the tree structure the tree is based on has its IndirectionMethod specified as "U" or "B", you must specify a User Key Value. If the tree structure doesn’t have its IndirectionMethod specified as "U" or "B", you must enter a Null string (that is, two quotation marks with no blank space between them ("")) for this parameter. |
| TreeName |
Specify the name for this tree. This parameter takes a string value. |
| EffDt |
Specify the effective date for this tree. This parameter takes a string value. |
| BranchName |
Specify the name of the branch for the tree. This parameter takes a string value. If the tree is unbranched, you must enter a Null string (that is, two quotation marks with no blank space between them ("")) for this parameter. |
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;
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
|
Field or Control |
Definition |
|---|---|
| SetID |
Specify the table indirection key for the tree. This parameter takes a string value. If the tree structure the tree is based on has its IndirectionMethod specified as "S", you must specify a SetID. If the tree structure doesn’t have its IndirectionMethod specified as "S", you must enter a Null string (that is, two quotation marks with no blank space between them ("")) for this parameter. |
| UserKeyValue |
Specify the User Key Value for the tree. This parameter takes a string value. If the tree structure the tree is based on has its IndirectionMethod specified as "U" or "B", you must specify a User Key Value. If the tree structure doesn’t have its IndirectionMethod specified as "U" or "B", you must enter a Null string (that is, two quotation marks with no blank space between them ("")) for this parameter. |
| TreeName |
Specify the name for this tree. This parameter takes a string value. |
| EffDt |
Specify the effective date for this tree. This parameter takes a string value. |
| BranchName |
This parameter is required, but it is unused in this release. You must enter a Null string (that is, two quotation marks with no blank space between them ("")) for this parameter. |
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;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
|
Field or Control |
Definition |
|---|---|
| RangeFrom |
Specify the starting range of the leaf to be found. This parameter takes a string value. |
| RangeTo |
Specify the ending range of the leaf to be found. This parameter takes a string value. |
Returns
A reference to a leaf object.
Example
&MYLEAF = &MYTREE.FindLeaf("81000", "");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
|
Field or Control |
Definition |
|---|---|
| NodeName |
Specify the name of the node that you want to find. This parameter takes a string value. Specify either the node name or the description. |
| Description |
Specify the description of the node that you want to find. This parameter takes a string value. Specify either the node name or the description. |
Returns
A reference to a node object.
Example
&MYNODE = &MYTREE.FindNode("10200", "");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();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");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
|
Field or Control |
Definition |
|---|---|
| RangeFrom |
Specify the starting range of the leaf you're verifying. This parameter takes a string value. |
| RangeTo |
Specify the ending range of the leaf you're verifying. This parameter takes a string value. |
Returns
An integer: 0 if the leaf exists.
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.
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
|
Field or Control |
Definition |
|---|---|
| SetID |
Specify the table indirection key for the tree. This parameter takes a string value. If the tree structure the tree is based on has its IndirectionMethod specified as "S", you must specify a SetID. If the tree structure doesn’t have its IndirectionMethod specified as "S", you must enter a Null string (that is, two quotation marks with no blank space between them ("")) for this parameter. |
| UserKeyValue |
Specify the User Key value for the tree. This parameter takes a string value. If the tree structure the tree is based on has its IndirectionMethod specified as "U" or "B", you must specify a User Key Value. If the tree structure doesn’t have its IndirectionMethod specified as "U" or "B", you must enter a Null string (that is, two quotation marks with no blank space between them ("")) for this parameter. |
| TreeName |
Specify the name for the tree. This parameter takes a string value. |
| EffDt |
Specify the effective date for the tree. This parameter takes a string value. The format must be in the correct format for the database platform the code is executing on. |
| BranchName |
This parameter is required, but it is unused in this release. You must enter a Null string (that is, two quotation marks with no blank space between them ("")) for this parameter. |
| Update |
Specify if you want to open the tree for update or in read-only mode. This parameter takes a Boolean value. Values for Update are:
If you try updating or writing to a tree structure opened in read-only mode, you receive an error. |
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;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
|
Field or Control |
Definition |
|---|---|
| SetID |
Specify the table indirection key for the tree. This parameter takes a string value. If the tree structure the tree is based on has its IndirectionMethod specified as "S", you must specify a SetID. If the tree structure doesn’t have its IndirectionMethod specified as "S", you must enter a Null string (that is, two quotation marks with no blank space between them ("")) for this parameter. |
| UserKeyValue |
Specify the User Key value for the tree. This parameter takes a string value. If the tree structure the tree is based on has its IndirectionMethod specified as "U" or "B", you must specify a User Key Value. If the tree structure doesn’t have its IndirectionMethod specified as "U" or "B", you must enter a Null string (that is, two quotation marks with no blank space between them ("")) for this parameter. |
| TreeName |
Specify the name for the tree. This parameter takes a string value. |
| AsOfDate |
Specify the “as-of-date” for the tree as a string. The format must be in the correct format for the database platform the code is executing on. If this parameter is not supplied, then the current date is used. If more than one tree matches the SetID, UserKeyValue, TreeName, and BranchName parameters, the tree with most recent effective date less than or equal to the as-of-date is opened. |
| BranchName |
This parameter is required, but it is unused in this release. You must enter a Null string (that is, two quotation marks with no blank space between them ("")) for this parameter. |
| Update |
Specify if you want to open the tree for update or in read-only mode. This parameter takes a Boolean value. Values for Update are:
If you try updating or writing to a tree structure opened in read-only mode, you receive an error. |
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;Syntax
OpenForExport(SetID, UserKeyValue, TreeNameEffDt)
Description
Use the OpenForExport method to open a tree for export processes (using TreeMover.)
Parameters
|
Field or Control |
Definition |
|---|---|
| SetID |
Specify the table indirection key for the tree. This parameter takes a string value. If the tree structure the tree is based on has its IndirectionMethod specified as "S", you must specify a SetID. If the tree structure doesn’t have its IndirectionMethod specified as "S", you must enter a Null string (that is, two quotation marks with no blank space between them ("")) for this parameter. |
| UserKeyValue |
Specify the User Key value for the tree. This parameter takes a string value. If the tree structure the tree is based on has its IndirectionMethod specified as "U" or "B", you must specify a User Key Value. If the tree structure doesn’t have its IndirectionMethod specified as "U" or "B", you must enter a Null string (that is, two quotation marks with no blank space between them ("")) for this parameter. |
| TreeName |
Specify the name for the tree. This parameter takes a string value. |
| EffDt |
Specify the effective date for the tree. This parameter takes a string value. The format must be in the correct format for the database platform the code is executing on. |
Returns
An integer: 0 if opened successfully.
Example
If &TREE.OpenForExport(&SETID, &USERKEYVALUE, &TREE_NAME, &TREE_EFFDT) <> 0 Then
/* processing */
End-if;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
|
Field or Control |
Definition |
|---|---|
| SetID |
Specify the table indirection key for the tree. This parameter takes a string value. If the tree structure the tree is based on has its IndirectionMethod specified as "S", you must specify a SetID. If the tree structure doesn’t have its IndirectionMethod specified as "S", you must enter a Null string (that is, two quotation marks with no blank space between them ("")) for this parameter. |
| UserKeyValue |
Specify the User Key value for the tree. This parameter takes a string value. If the tree structure the tree is based on has its IndirectionMethod specified as "U" or "B", you must specify a User Key Value. If the tree structure doesn’t have its IndirectionMethod specified as "U" or "B", you must enter a Null string (that is, two quotation marks with no blank space between them ("")) for this parameter. |
| TreeName |
Specify the name for the tree. This parameter takes a string value. |
| EffDt |
Specify the effective date for the tree. This parameter takes a string value. The format must be in the correct format for the database platform the code is executing on. |
Returns
An integer: 0 if opened successfully.
Example
&pSession = %Session;
&pTreeObj = &pSession.GetTree();
&status = &pTreeObj.OpenWholeTree(&Setid, &SetCntrlValue, &TreeName, String(&EffDt));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
|
Field or Control |
Definition |
|---|---|
| NodeName |
Specify the name of the node that you want to find. This parameter takes a string value. |
Returns
An integer: 0 if the node exists.
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
|
Field or Control |
Definition |
|---|---|
| FromSetId |
Specify the table indirection key for the tree to be copied from. This parameter takes a string value. If the tree structure the tree is based on has its IndirectionMethod specified as "S", you must specify a SetID. If the tree structure doesn’t have its IndirectionMethod specified as "S", you must enter a Null string (that is, two quotation marks with no blank space between them ("")) for this parameter. |
| FromUserKeyValue |
Specify the User Key Value for the tree to be copied from. This parameter takes a string value. If the tree structure the tree is based on has its IndirectionMethod specified as "U" or "B", you must specify a User Key Value. If the tree structure doesn’t have its IndirectionMethod specified as "U" or "B" you must enter a Null string (that is, two quotation marks with no blank space between them ("")) for this parameter. |
| FromTreeName |
Specify the name for the tree to be copied from. This parameter takes a string value. |
| FromEffDt |
Specify the effective date for the tree to be copied from. This parameter takes a string value. |
| FromBranchName |
This parameter is required, but it is unused in this release. You must enter a Null string (that is, two quotation marks with no blank space between them ("")) for this parameter. |
| ToTreeName |
Specify the new name of the tree. This parameter takes a string value. |
Returns
An integer: 0 if renamed successfully.
Example
&MYTREE.Rename("","","PERSONAL_DATA3", "05-05-1997","", "PERSONAL_REN2");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.
Related Links
Parameters
None.
Returns
An integer: 0 if save successfully.
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
|
Field or Control |
Definition |
|---|---|
| SetID |
Specify the table indirection key for the tree. This parameter takes a string value. If the tree structure the tree is based on has its IndirectionMethod specified as "S", you must specify a SetID. If the tree structure doesn’t have its IndirectionMethod specified as "S", you must enter a Null string (that is, two quotation marks with no blank space between them ("")) for this parameter. |
| UserKeyValue |
Specify the User Key Value for the tree. This parameter takes a string value. If the tree structure the tree is based on has its specified as "U" or "B", you must specify a User Key Value. If the tree structure doesn’t have its IndirectionMethod specified as "U" or "B", you must enter a Null string (that is, two quotation marks with no blank space between them ("")) for this parameter. |
| TreeName |
Specify the name for this tree. This parameter takes a string value. |
| EffDt |
Specify the effective date for this tree. This parameter takes a string value. |
| BranchName |
This parameter is required, but it is unused in this release. You must enter a Null string (that is, two quotation marks with no blank space between them ("")) for this parameter. |
Returns
This method returns an integer: 0 if saved successfully, a number greater than 0 otherwise.
Example
&MYTREE.SaveAs("", "", "DEPENDENT_BENEF2", "02-05-1999", "");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
|
Field or Control |
Definition |
|---|---|
| SetID |
Specify the table indirection key for the tree. This parameter takes a string value. If the tree structure the tree is based on has its IndirectionMethod specified as "S", you must specify a SetID. If the tree structure doesn’t have its IndirectionMethod specified as "S", you must enter a Null string (that is, two quotation marks with no blank space between them ("")) for this parameter. |
| UserKeyValue |
Specify the User Key Value for the tree. This parameter takes a string value. If the tree structure the tree is based on has its IndirectionMethod specified as "U" or "B", you must specify a User Key Value. If the tree structure doesn’t have its IndirectionMethod specified as "U" or "B", you must enter a Null string (that is, two quotation marks with no blank space between them ("")) for this parameter. |
| TreeName |
Specify the name for this tree. This parameter takes a string value. |
| EffDt |
Specify the effective date for this tree. This parameter takes a string value. |
| BranchName |
This parameter is required, but it is unused in this release. You must enter a Null string (that is, two quotation marks with no blank space between them ("")) for this parameter. |
Returns
This method returns an integer: 0 if saved successfully, a number greater than 0 otherwise.
Example
&MYTREE. SaveAsDraft("","","PERSONAL_EDIT2", "05-05-1997", "");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.
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
|
Field or Control |
Definition |
|---|---|
| Nodes_Number |
Specify the number of nodes. |
| Leaves_Number |
Specify the number of leaves. |
Returns
An integer: 0 if set successfully.
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
|
Field or Control |
Definition |
|---|---|
| SetID |
Specify the table indirection key for the tree. This parameter takes a string value. If the tree structure the tree is based on has its IndirectionMethod specified as "S", you must specify a SetID. If the tree structure doesn’t have its IndirectionMethod specified as "S", you must enter a Null string (that is, two quotation marks with no blank space between them ("")) for this parameter. |
| UserKeyValue |
Specify the User Key Value for the tree. This parameter takes a string value. If the tree structure the tree is based on has its IndirectionMethod specified as "U" or "B", you must specify a User Key Value. If the tree structure doesn’t have its IndirectionMethod specified as "U" or "B", you must enter a Null string (that is, two quotation marks with no blank space between them ("")) for this parameter. |
| TreeName |
Specify the name for this tree. This parameter takes a string value. |
| EffDt |
Specify the effective date for this tree. This parameter takes a string value. |
Returns
The number of locked branches. If the tree is not branched, but is checked out, the return value is 1.
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.
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.