Tree Structure Class Methods

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

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.

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);

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;

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.

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);

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.

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.