AESection Class

This chapter provides an overview of AESection class and discusses the following topics:

• How an AESection is accessed.

• AESection example.

• Data type of an AESection object.

• Scope of an AESection object.

• AESection Class built-in function.

• AESection Class reference.

Understanding AESection Class

Before PeopleTools 8, users could perform SQL directly on the Application Engine tables, thereby changing their SQL and Application Engine "flow" in a dynamic manner, prior to running their applications. Some applications, for example, let the user input their "rules" in a user-friendly application, then convert these rules, at save time, into Application Engine constructs.

With PeopleTools 8, Application Engine programs should not perform SQL directly on the Application Engine tables, as they are system tables, and are cached. SQL on the Application Engine tables may not be accurately reflected when the applications are executed, because of the caching mechanism.

To overcome this problem, developers have two basic operations that let them modify their Application Engine programs from their online pages:

• Ability to modify SQL definitions, which are referenced within Application Engine SQL using the PeopleCode SQL class and the meta-SQL function %SQL.

• Ability to dynamically change the execution flow of a given Application Engine section.

Use the AESection class to do the latter. This section object is used to modify the steps and SQL associated with a given section by using PeopleCode.

Before describing the specifics of the AESection class, the following are some general terms to understand:

• base section

  The base section represents the Application Engine section you are working on. This is the section that you are changing in PeopleCode. In other words, it’s the target section.

• template section

  The template section represents the Application Engine section that is the source, or "model" for the section you're building. You copy from the template section to the base section.

The template must exist in the database before you can use it.

If the base section you specify doesn’t exist, a new base section is created. This enables you to dynamically create sections as needed.

You can copy steps (and their attributes) from the template to the base. The only attribute of the step you can modify is the SQL statement that gets executed.

Warning! When you open or get an AESection object, (that is, the base section) any existing steps in the section are deleted. You must add a new step to the section before you can modify it.

The main assumption for this class is that your rules are dynamic primarily in the SQL that they execute, but that the structure of the rules are static, or at least defined well enough that a standard template can be applied.

Note that you can't update the Application Engine actions that are not SQL-related (that is, PeopleCode, Call Section, or Log Message). In other words, you can’t change the PeopleCode associated with a PeopleCode action within a step. You can add a step containing a PeopleCode action to your new section, but you can't change the PeopleCode dynamically.

See Also

SQL Class

%SQL

Adding Steps

How an AESection is Accessed

When an AESection is opened (or accessed), the system first checks if it exists with the given input parameters.

If the base section you specify doesn’t exist, a new base section is created. This enables you to dynamically create sections as needed. In addition, if the target section doesn't exist, all section-level attributes are copied from the template to the target section. If the target exists, it retains its attribute settings.

If an effective date is specified (with EffDt), but there is no match using that effective date, the AESection is opened using the base effective date of ‘1900-01-01’.

The market defined for the current component is used for the section to be open. If no section with this market exists, the default GBL is used.

If you open an AESection object from within a running Application Engine program, the market value is set to the value of the current process.

The database platform you’re currently running is used as the database platform for the section to be opened. If no section with this database platform exists, the default "none" is used.

To find the correct section to open, the precedence is:

1. Market

2. Database platform

3. Effective date

When a section is closed and its changes are saved, the market and database platform from the system that performed the changes is used as the market and database platform for the modified section.

Let’s take an example. Assume that you’re running on DB2 UDB for OS/390 and z/OS, and your current market is set to ‘MKT’. Assume that you want to open a section called Sect1 in an Application Engine program called TestAppl, and that your data looks something like this:

If you use:

&SECTION.Open("TestAppl", "Sect1", "1998-12-14");

Then the third section in the previous list is used, because the market takes highest precedence. When the section is saved, the values for market and platform are updated to the current system values.

Warning! When you open or get an AESection object, (that is, any base section) any existing steps in the section are deleted. You must add a new step to the section before you can modify it.

The other attributes of the section, however, are retained, with the exceptions noted previously.

AESection Example

Assume that you have a template section called TEMPLATE in the Application Engine program called MY_APPL. The template looks like this:

Also, assume that you have a base section called DYN_SECT in the Application Engine program called RULES. When you start, this section looks like this:

Here’s the PeopleCode:

Local AESection &Section;
&Section = GetAESection("RULES", "DYN_SECT"); 
/* Open the base section */
&Section.SetTemplate("MY_APPL", "TEMPLATE");    
/* Set the template section */
&Section.AddStep("NewStep2");                      
/* Insert NewStep2     */
/* Do some SQL stuff here  */
&Section.SetSQL("DO_SELECT", &MySql);    
/* Modify the SQL in the added step */
&Section.Save();
&Section.Close();                               
/* Save and close   */

The base section looks like this after execution:

Note. The existing steps in the base section have been overwritten by the new step from the template section.

Data Type of an AESection Object

You should declare an AESection object as type AESection. For example:

Local AESection &SECTION;

Scope of an AESection Object

An AESection object can only be instantiated from PeopleCode.

The AESection Object is designed for use within online pages. Typically, dynamic sections should be constructed in response to an end-user action.

Note. Do not call an AESection object from an Application Engine PeopleCode Action. If you need to access another section, use CallSection Actions instead.

See Also

Specifying Call Section Actions

AESection Class Built-in Function

GetAESection

AESection Class Methods

In this section, we discuss each AESection class method, in alphabetical order.

AddStep

Syntax

AddStep(ae_step_name [, NewStepName])

Description

The given step name from the template section is added as the next step into the base section, and named the existing step name.

Note. When you open or get a section, all the existing steps are deleted. The first time you execute AddStep, you add the first step. The second time you execute AddStep, you add the second step, and so on.

All attributes of the step are copied, including all of its actions. The only changeable attribute of a step are its SQL statements, which can be modified using the SetSQL method. SetSQL is run on the current step, that is, the step most recently added.

You can also change the name of the step by using the optional parameter NewStepName.

If the step named does not exist in the template, an error occurs. Likewise, if you have not opened or set the template for the section, you receive an error.

Parameters

Returns

None.

Example

See AESection Example.

See Also

AESection class: SetSQL method.

Close

Syntax

Close()

Description

Close closes the AESection object. Any unsaved changes to the section are discarded.

Parameters

None.

Returns

None.

Example

See AESection Example.

See Also

AESection class: Save method, Open method.

GetAESection

Open

Syntax

Open(ae_applid, ae_section, [effdt])

Description

The Open method associates the AESection object with the given Application Engine section, based on the ae_applid and ae_section. If the effdt is specified, this is also used to get the section object. In other words, the Open method sets the base section.

Warning! When you open or get an AESection object, (that is, the base section) any existing steps in the section are deleted.

Note. If the base section you specify doesn’t exist, a new base section is created. This enables you to dynamically create sections as needed. In addition, if the target section doesn't exist, all section-level attributes are copied from the template to the target section. If the target exists, it retains its attribute settings.

If the AESection is still open when you issue the Open method, the previously opened object is discarded and none of the changes saved. To prevent accidentally discarding your changes, you can use the IsOpen property to verify if a section is already open.

The AESection is open based on the Market and database type of your current system.

Parameters

Returns

An AESection object.

Example

Local AESection &SECTION;
                
&SECTION = GetAESection("RULES1", "DYN_SECT");
                
/* do some processing */
                
&SECTION.Close();
                
&SECTION.Open("RULES2", "DYN_SECT");
                
/* do additional processing */

See Also

AESection class: IsOpen property.

GetAESection

Save

Syntax

Save()

Description

The Save method saves the section to the database. The AESection object remains open after you use this method. To close the object, you must use the Close method.

You must commit all database changes prior to using this method. This is to avoid locking critical Tools tables and hence freezing all other users. You receive a runtime error message if you try to use this method when there are pending database updates, and your PeopleCode program terminates. You need to commit any database updates prior to using this method. Use the CommitWork function to commit database updates.

Parameters

None.

Returns

None.

Example

See AESection Example.

See Also

AESection class: Close method, Open method.

CommitWork

SetSQL

Syntax

SetSQL(action_type_string, string)

Description

The SetSQL method replaces the SQL associated with the given action type in the current step in the base section with the SQL in string. The current step is the latest step that was added using AddStep. The action types are:

• DO_WHEN

• DO_WHILE

• DO_SELECT

• SQL

• DO_UNTIL

Note. All action types must be passed in as strings with quotation marks.

If the action specified does not exist in the current step, an error occurs.

You can use a SQL object as string.

&SECTION.SetSQL("SQL", &SQL);

Parameters

Returns

None.

Example

See AESection Example.

See Also

AESection class: AddStep method.

SQL Class

SetTemplate

Syntax

SetTemplate(ae_applid, ae_section)

Description

The SetTemplate method sets the template to be used with an AESection object, as identified by ae_applid and ae_section.

The rules for assigning a template section are similar to the rules for selecting a base section. The selection of market and database platform are done exactly the same. However, the effective date of the template is always set based on the effective date of ‘1900-01-01’.

You must set the template before you can use any of the other methods.

Parameters

Returns

None.

Example

See AESection Example.

See Also

AESection class: Open method.

How an AESection is Accessed

GetAESection

AESection Class Property

In this section, we discuss the IsOpen AESection property.

IsOpen

Description

If this property is True, the section object is already open. If you try to open a section object that is already open, the open section object is closed and all the changes that haven’t been saved are discarded before the object is re-opened.

Example

If Not(&MYSECTION.IsOpen) Then
   &MYSECTION.Open(MYAPPLID, SECTION2);
End-If;