Appendix: Equation Engine Programmer's Guide

This appendix provides an overview of the PeopleSoft Equation Engine and discusses Equation Engine security.

Understanding Equation Engine

Oracle Corporation provides the PeopleSoft Equation Engine as a means for you to specify rules or equations as part of your business process. Equation Engine works best when you can specify an IF-THEN-ELSE validation resulting from a single call to an equation. For example, you may want to specify selection criteria by emplID or obtain a single number, string, or Boolean operator for that emplID.

The new version of the Equation Engine extends the capabilities of the original Equation Processor by adding looping and other constructs. It now can read any table for which you have security access and can perform various arithmetic operations and external call subroutines. In addition, security was added to ensure that control can be allocated based on your need and job function, which determine whether you need the ability to add, use, view, and modify equations, tables, and external routines.

With release 9, we added new syntax to enable you to perform mass actions—such as inserting, deleting, and updating rows in database tables—against the database using a single statement.

This section discusses:

• Online usage

• Architecture

• Language constructs

• Keyword syntax

• Basic language syntax

Online Usage

You use the Equation Editor page to enter information about an equation. You can compile, test, view in XML format, and print equations; the system displays the compile status of the equation. You can also create, edit, and delete the contents of equations. The equation is divided into three main sections: Equation Keyword, Operand Type, and Operand. You use various combinations of these main sections to define and create equations.

Access the Equation Editor page (Select Set Up SACR, Common Definitions, Equation Engine, Equation Editor).

Use the Sel (select) check boxes to select the lines to be affected by the Equation Edit function. Use the Comment fields to enter comments about an equation lines. Comments are information only.

To edit an equation, after you select a Sel check box, select one of the following options from the Equation Edit Function drop-down list box:

• Collapse Statements

• Compile

• Copy and Append to Clipboard

• Copy to Clipboard

• Cut and Append to Clipboard

• Cut to Clipboard

• Deselect All

• Expand Statements

• Paste After row

• Paste Before row

• Print

• Select All

• Select all between checks

• Test

• View in XML Format

Example of the Select All Between Checks Function

On the Equation Editor page, select the Sel check boxes for lines 2 and 12.

From the Equation Edit Function drop-down list box, select Select All Between Checks. When you click the Select All Between Checks option, the following page displays the selected check boxes for lines 2 through 12.

Example of the Cut to Clipboard Function

From the Equation Edit Function drop-down list box, select Cut to Clipboard to copy the contents to the clipboard for later use. The selected lines are removed, as shown in the following example.

Example of the Paste After Row Function

Select line 1 from the Sel check boxes.

From the Equation Edit Function drop-down list box, select Paste After row. Lines 2 through 12 are added from the clipboard, as shown in the following example:

Compile Function

From the Equation Edit Function drop-down list box, select Compile to check the syntax of the equation and to generate pseudo-code for the equation. You do not need to compile an equation; because the system compiles it for you when you run the equation. if you choose to compile an equation, you should compile the equation immediately after modifying it to check for syntax errors.

Example of Using the Expand and Collapse Buttons

The Equation Edit Function drop-down list box contains collapse and expand functions. To use them, you must first select the lines to be collapsed or expanded; then, you perform the function. For example, when you perform the Select All edit function followed by the Collapse Statements edit function, all collapsible statements in the equation are collapsed.

This is an example of the equation after all statements are collapsed:

Example of View In XML Format

When you select the View In XML Format edit function, the equation appears as an XML document in your browser. Because no style is associated with the XML document, the equation is presented as a document tree, in which the statements are indented and collapsible. The equation cannot be edited from the XML view of the equation.

Testing Equations

To test the equation, you may need to set up test data. In the previous example, the function of the equation was to add a few numbers together. No test data was needed because no global variables were needed. However, to test an equation that references keys in the table, passes global variables, or both you must provide the equation with test data.

To define and enter test data, go to the Equation Test Data page and define the name of the variable, its type, and its operand.

Access the Equation Test Data page (Select Set Up SACR, Common Definition, Equation Engine, Equation Test Data).

After you define the necessary variables and enter data on the Equation Test Data page, click the Test button.

Note. You can also run a test from the Equation Editor by selecting Test from the Equation Edit Function drop-down list box.

When you click the Test button, the system displays the Equation Test Results, Process Messages tab:

This tab displays the messages associated with the equation test run.

The Equation Test Results, Global Variables tab displays the global variables used within the current equation run:

The Print option in the Equation Edit function on the Equation Editor page enables you to print equations in a Crystal report format. When you select the Print option, the Equation Print page displays where you are required to enter a run control ID:

.

Running the subsequent process yields a report that looks like this:

Architecture

The architectural changes in the current version of the Equation Engine are divided into two components: the Compiler and the Interpreter. The Compiler transforms the equation into pseudo-code (a pcode different from PeopleTools pcode), that is a type of platform-independent, low-level assembly code. The Interpreter reads the pcode and executes the equation directly. This method enables you to validate the syntax without running the equation. It also simplifies the logic of the programs.

Technical Notes

The architectural approach is a left-to-right look-ahead parser. Context sensitivity was pushed down to the lexical analyzer to make the parsing algorithm simpler.

Standard compiler design uses the driving routine as the parser. The parser makes calls to the lexical analyzer to retrieve units of logical language, called Tokens. It builds a parse tree, which is an internal representation of the structure of the program. It then reduces the parsing stack using the parse tree. For example, an if-then-else-end-if construct would be reduced to an if statement. Some of the reductions trigger calls to the object code generator, which generates the target language to be emitted. In this instance, the compiler output is the pcode. The design of the interpreter is simplified because the pcode is low-level.

Statement constructs were designed to end with END-XXXX phrases so that the parsing table state transitions are from top to bottom. When the equation is compiled by means of the compile equation edit function, additional up-front syntax checks are performed to provide more compile messages with more clarity about what is syntactically wrong with the equation. Additionally, if one of the more complicated statements has a syntax error, then a message appears showing the language syntax for that statement.

Language Constructs

Equation Editor uses the language constructs discussed in the following topics.

Keywords

Keyword usage is mostly self-explanatory. Complex keywords will be explained later in the context of their syntactical constructs. These are the keywords:

• (

• )

• *

• +

• -

• /

• <

• <=

• <>

• =

• >

• >=

• And

• Assign

• Call

• Call Parms

• Choose

• Delete

• Else

• Else If

• End Assign

• End Call Parms

• End Delete

• End Find

• End If

• End Insert

• End Loop

• End Message

• End Restore

• End Save

• End Update

• Exists

• Exit Loop

• Find First

• Find Next

• From

• Halt

• If

• Insert

• Into

• Loop

• Message

• Not

• Or

• Restore

• Return

• Save

• Set

• Skip

• Then

• Trace

• Update

• Where

Global and Local Variables

Two types of variables are available in the Equation Engine: global and local. Data is passed to the Equation Engine by means of the global variable array or a process instance of the global variable tables that is defined by the Equation Test Data page or a calling program. Global variables are visible and can be referenced by any equation running or called. Local variables are visible only to the currently running equation.

Local and global variables can have a stem qualification. Stems are similar to arrays except that they have more versatility and are unbounded. You can assign a variable a name that ends with a period (.) to a default value (for example, DOGOWNER. = "unknown"), and then reference a subscript of that stem. If the subscript was not initialized with a value, then it will pick up the default value (for example, DOGOWNER.X has the value "unknown").

Stems are more versatile than arrays because the bounds of an array must be declared, but stems have no bounds to be declared and the subscripts do not have to be numeric. Therefore, you can have a subscript value of "Fido" instead of 7 (for example, Assign X = "Fido" and then Assign DOGOWNER.X = "Joe"). This construct not only allows a pseudo array processing capability, it also allows a pseudo pointer capability (for example, NODE.LEFT and NODE.RIGHT).

Read-only (system) variable names always begin with an exclamation mark.

Depending on which application is invoking the equation, different global variables may be assumed to be passed into the equation and different global variables (or none) are expected to be returned from the equation.

Global Variables Always Passed in for All Applications

The following global variables are always passed in:

• !CURRENT-DATE

• !CURRENT-DATE-TIME

• !CURRENT-TIME

• !EQUATION-NAME

• !PROCESS-INSTANCE

• !RUN-CNTL-ID

• OPRID (always read-only, FIND tests are forced to equality)

• PROCESS-INSTANCE (passed in)

• PROCESS_INSTANCE (actually used)

• RUN_CNTL_ID

Global Variables Passed in for the Forms Engine Financial Aid Award Notification Letter (FEFANLTR)

The following global variables are passed in:

FANLTR_SEQ

These global variables enable the equation to read the table RUNCNTL_FAN_SEQ, which provides these fields:

• INSTITUTION

• AID_YEAR

• PKG_AWARD_PERIOD

The equation can then assign global or local variables to these fields in order to loop through reading the table FAN_AWD_SEL_VW to determine whether or not to select an EMPLID. If the EMPLID is to be selected, the equation calls the SQL FANLTR_SELECT_STUDENT, passing in the EMPLID.

Note. No global variables are returned for FEFANLTR.

Global Variables Passed in for Financial Aid Packaging

The following global variables are passed in:

• EMPLID

• INSTITUTION

• AID_YEAR

• ACAD_CAREER

• AWARD_PERIOD

• I_TRGT_FED_RMNEED

• I_TRGT_INST_RMNEED

• I_TRUE_FED_RMNEED

• I_INST_RMNEED

• I_LAST_AWD_ATM

• I_TOTAL_AWD_AMT

• WORK_FIELD_CHAR_01 through 05 (These global variables retain their values between equation calls. Initially, they are blank.)

• WORK_FIELD_NUM_01 through 05 (These global variables retain their values between equation calls. Initially, they are zero.)

• A_SELECT (initially blank)

• A_AMOUNT (initially zero)

The following global variables are examined upon return from the equation:

• A_SELECT (either "T" or "F", where "T" causes the student to be selected only for equations with the application prompt type of "Fin Aid Packaging Select Eqtns")

• A_AMOUNT (numeric dollar amount to be returned only for equations with the application prompt type of "Fin Aid Packaging Amount Eqtns")

Global Variables Passed in for Student Financials Tuition Calculation

The following global variables are passed in:

• EMPLID

• INSTITUTION

• ACAD_CAREER

• STRM

• BUSINESS_UNIT

• BILLING_CAREER

• STDNT_CAR_NBR

• A_SELECT (initially blank)

• A_AMOUNT (initially zero)

These global variables are examined upon return from the equation:

• A_SELECT (either "Y" or "N"; only the first character of the string is examined, but only for equations with the application prompt type of "Stdnt Fin Tuition Select Eqtns")

• A_AMOUNT (dollar amount to be returned, but only for equations with the application prompt type of "Stdnt Fin Tuition Amount Eqtns")

Global Variable Passed in for CommonLine and Common Record CommonLine Loan Validation

The global variable LN_ACTION_STATUS (initially "O" for OK) is passed in.

The following records are already fetched, and you can reference their fields:

• LN_EDIT_RUN_VW (for CL4 only)

• SFA_CRCEDRUN_VW (for CRC only)

• LOAN_ORIGNATN

• LN_TYPE_TBL

• LN_CL_PNOTE_VW (for CL4 only)

• SFA_CRC_PNOTE (for CRC only)

• LN_DEST_CATG_VW (for CL4 only)

• SFA_CRC_DCAT_VW (for CRC only)

The edit equation should set this global variable:

LN_ACTION_STATUS (looks for "O" for OK, or for "F" for Failed to pass the edit)

Every edit calls FA_EDGETDEST (CL4) or FACEDGETDEST (CRC), which sets the global DEST_ACTV. Next, the equation must test if the value is "Y" and if not, then return; otherwise, if the edit finds an error, it calls equation FA_EDLOGERR (CL4) or FACEDLOGERR (CRC), passing it the EQUATION_NAME local variable.

Global Variables Passed in for CommonLine and Common Record CommonLine Loan Hold/Release Processing

The following global variables are passed in:

• AID_YEAR

• EMPLID

• INSTITUTION

• STRM

• TABLE_ID (always "1")

• LOAN_TYPE

• LN_APPL_SEQ

• DISBURSEMENT_ID

• ITEM_TYPE

• RESULT (initially blank)

• HR_MSG_SET_NBR

• HR_MSG_NBR

These global variables are examined upon return from the equation:

• RESULT (either "PASS" or "FAILED")

• HR_MSG_SET_NBR and HR_MSG_NBR (string numeric Hold/Release message set number and message number are examined only if RESULT is "FAILED")

Global Variable Passed in for Population Selection

This global variable is passed in:

!CALLING-PROCESS-INSTANCE

No global variables are expected upon return; however, rows may be inserted into the target table.

Note. If a local or global variable does not have an assigned value when it is referenced, then the Equation Engine gives a runtime error. See the EXISTS keyword for more details.

Tables and Fields

You can read and use the table and fields by defining the tables to be used in the Equation Data Tables page.

Access the Equation Data Tables page (Select Set Up SACR, Common Definition, Equation Engine, Equation Data Tables).

If you reference a table-field but that table has not been read, then an implicit read will be performed with the assumption that the global variables are defined the same as the key to that table (for example, EMPLID, INSTITUTION, STRM, and so on). After the table is read, the first value of the read will be placed in that field.

Runtime Errors

If a variable is referenced but it has not been assigned a value, then a runtime error will occur. Also, if a table field is referenced and the fetch count is zero (no rows found), then a runtime error will also occur. One way of avoiding this error is to use the EXISTS keyword to determine whether the field or variable had a value and to either set a default value or issue a modified message and halt. This situation might occur if you call another equation that expects a local variable to be passed.

Keyword Syntax

The maximum number of lines in an equation is 10,000.

Note. A truth value has an arithmetic value of zero for FALSE, and any other value is TRUE.

Logical Operators

Logical operators AND, OR, and NOT are used within an IF statement.

Syntax

<Condition1> <Logical Operator> <Condition2>

Syntax

NOT <Condition>

Relational Operators

Relational operators: <, <=, =, >=, >, <>

Relational operators compare two expressions and yield a truth value. Use parentheses to group expressions and to enhance readability.

Syntax

<Expression1> <Relational Operator> <Expression2>

Arithmetic Operators

Arithmetic operators: +, -, *, /

Arithmetic operators apply to two expressions and yield an arithmetic result. Use parentheses to group expressions and to enhance readability.

Syntax

<Expression1> <Arithmetic Operator> <Expression2>

If rounding or truncation to an integer is necessary, then a call must be made to an external subroutine or equation (for example, the "ROUND" equation) that handles the task.

ASSIGN

Keywords: ASSIGN and END ASSIGN

The ASSIGN statement enables you to assign a value to either a local or a global variable. Every ASSIGN statement must be concluded with an END ASSIGN keyword.

Syntax

ASSIGN <Local or Global> <Variable Name> <Expression> END ASSIGN

Note. Local variables exist and can be referenced only within the context of the current equation, but global variables exist for the duration of the Equation Engine run. A global variable set in one equation can be referenced within a called equation and vice versa.

CALL

Keywords: CALL, CALL PARMS, and END CALL PARMS

The CALL statement enables an equation to call another equation, a callable SQL, or an external subroutine.

Syntax

This table lists examples of syntax for the keywords CALL, CALL PARMS, and END CALL PARMS:

The CALL PARMS statement applies only to calling other equations or calling SQL. The types of routines are defined as equations, external subroutines, and SQL. You do not pass call parameters to external subroutines. To pass parameters to and from external subroutines, you must use global variables.

To use the Application Engine, you must call the Equation Engine from the Application Engine because the COBOL call to Application Engine is not supported.

For equation calls, the list of local variable names in the parameter list and their values are copied as separate local variables into the called equation. Local variables changed within the called equation are not changed upon the return to the calling equation. To pass a value back to a calling equation, the value must be returned by means of a global variable. Any returned global variable name should begin with the called equation name. If only one value is returned, the name should be <equation name>_RESULT. If you are returning a set of values, you can set the values into a global stem to encapsulate the result.

Equations can call themselves recursively; however, the maximum depth of equation call nesting is set at 1,000 calls. If your design requirements exceed the set amount, you must use a loop.

For SQL calls, the SQLID must exist in the Equation SQL setup table.

Access the Equation Callable SQL page (Select Set Up SACR, Common Definitions, Equation Engine, Equation SQL Routines).

The security for SQL calls is controlled through the operator alias type of EQS.

Note. You can use CALL SQL for updates, inserts, deletes, or small row retrieval selects (<1000), but use FIND statements instead of calling SQL with selects whenever possible.

CALL parameter order

The call parameter requires this order when calling a SQL:

Return code,

SQL row count,

Bind variable 1,

Bind variable 2,

.

Bind variable n,

Select variable 1,

Select variable 2,

.

Select variable n,

This is an example of a Call SQL Setup:

All of the call parameters for SQL must be local variables. Global variables are not permitted. The select variables, if any, are updated by the call and are passed back to the calling equation, which differs from the effect of calling another equation and passing the local variables. If an equation modifies a passed local variable, that change is not reflected upon return to the calling program. However, when you call an SQL, the return code, SQL row count, and all of the select variables are modified by the call upon return from that called SQL.

Select variables are mapped to call parameters after the bind variables are mapped. The select variables must be stems to handle multiple rows of output (for example, EMPLID.1, EMPLID.2, and so on). Remember that a stem variable ends with a period and behaves similarly to an array.

DELETE

Keywords: DELETE, CHOOSE, WHERE, and END DELETE

Syntax

The following table shows examples of syntax for the keywords DELETE, CHOOSE, WHERE, and END DELETE:

This statement deletes rows from the specified table, limited to the <where expression> evaluating to true (if it is supplied), and also limited to the choose equation (if it is supplied) returning a true value for each row.

<table name> is the name of a table to which the user has Equation Engine (EE) write authority.

<statement block> is any set of equation statements, except not DELETE, INSERT, nor UPDATE. Typically, if any statements exist , they are ASSIGN statements setting global variables that will be used within the CHOOSE equation, if it is specified.

<where expression> is passed to the database when you select which rows to delete. The database returns the resultant rowset to the delete statement. If no where clause is specified, then all rows in the table are processed. The where clause may mention table-fields from the table operand of the delete keyword as well as any other table to which the user has EE read authority. The other tables, if mentioned, do not get rows delete, but rather may be used to limit which rows will be deleted by joining to the table in which rows are being deleted.

CHOOSE clause is optional and if specified will cause EE to call the choose equation once for each row in the rowset to be processed. Typically, any necessary global variables needed by the choose equation to do its function were set within the aforementioned <statement block>. After calling the choose equation, the choose clause will first look to see if there is a global variable with the same name as the choose equation name. If there is, then it will inspect it for a value of the number zero, which it will interpret as a false condition. Any other value is a true condition. If a true condition is returned, then the row is selected for processing. If it does not find the global variable with the same name as the choose equation name, then it will look for the global variable named A_SELECT. If a value is set for A_SELECT, it can have one the following values, which will indicate a true condition: T, TRUE, t, true, Y, YES, y, or yes. Any other value is considered to be a false condition.

EXISTS

Keyword: EXISTS

The EXISTS statement tests to determine whether a variable exists or whether any rows were returned when the EXISTS statement is applied against a table. It cannot be used to validate field names.

Syntax

This table shows example syntax for the keyword EXISTS:

<object type> is a local variable, global variable, or table name.

It returns a truth value and is typically used within an IF statement. It is commonly used to validate variables or tables prior to its usage to avoid runtime errors. If the variable has not been initialized, then the calling program must set default values to variables.

Example:

If you establish an equation (COMPUTE_ANGLE) that will be called by other equations, it requires the following parameters to be passed:

• XROW

• YROW

• DISTANCE

The COMPUTE_ANGLE tests to make sure XROW, YROW, and DISTANCE exist. If they do not, then variables can be set to default values or you can return a message to the calling equation.

When referencing table fields, the EXISTS statement determines whether a row has been selected for a given table name using either an implicit or explicit FIND statement.

FIND

Keywords: FIND FIRST, FIND NEXT, and END FIND

The FIND FIRST keyword positions the equation in the first row of the specified table for the given key values and key relational operators. The FIND NEXT keyword moves to the next row within that previously specified set of key values and key relational operators. If you need to process multiple rows of data within a single call to an equation, you should use a FIND FIRST followed by a LOOP statement that contains a FIND NEXT near the end of the statement. Test the find success variable to determine when to exit the loop.

Note. An implicit FIND is performed when a field of a table is referenced and no FIND FIRST was previously issued. In the implicit FIND, all relational operators are considered equal. The key values are obtained from the global variables defined within the equation and from where the global variable names match the key field names of the table.

Syntax

This table shows examples of syntax for the keywords FIND FIRST, END FIND, and FIND NEXT:

The find success variable can be a local or global variable containing a truth value that indicates whether a row was found.

The find condition operators (EQUAL, GREATER-THAN, and GREATER-THAN-OR-EQUAL-TO) compare the assign variable against the table. The variables must have the same names as the fields of the table.

Every FIND statement must end with an END FIND keyword.

Example of Find Setup

This table shows example syntax for the keyword FIND FIRST:

An alternative to looping through successive FIND NEXT statements is to issue a single CALL SQL statement, where the called SQL is a select statement. The values returned are placed into local stem variables, of which there is an upper limit of one thousand. If you exceed the limit, the equation engine will halt with a runtime error. For a large number of returned rows, it is best to process them with successive FIND NEXT statements and handle the data one row at a time. If you need to do changes en masse, you can call SQL to update temporary tables and avoid row-by- row processing, this technique is preferred.

HALT

Keyword: HALT

The HALT statement stops the execution run of all equations. The Equation Engine immediately returns control to its calling program; control is not returned to a calling equation. This keyword is typically used in the event of a catastrophic error. For example, a test is performed to determine whether a row exists for an emplID. If it does not, you issue a customized message to stop the equations.

IF

Keywords: IF, THEN, ELSE IF, ELSE, and END IF

The IF statement executes different statements depending on truth values within its conditions. Each IF statement block must conclude with an END IF keyword.

Syntax

IF

<condition-1>

THEN

<statement block-1>

[ELSE IF

<condition-n>

THEN

<statement block-n>] …

[ELSE

<statement block-n+1>]

END IF

The ELSE IF and ELSE expressions are optional. The ELSE IF expression enables you to create a case control structure so a single END IF can be used instead of nesting IF's. You can have zero, one, or several "ELSEIF … THEN …" constructs within a single IF statement.

Nested IF statements are allowed within the equation. A statement block can contain any other statements, including an IF statement.

INSERT

Keywords: INSERT, INTO, FROM, CHOOSE, WHERE, and END INSERT

Syntax

This table shows examples of syntax for the keywords INSERT, INTO, FROM CHOOSE, WHERE and END INSERT:

This statement inserts rows into the specified table, limited to the <where expression> evaluating to true (if it is supplied), and then also limited to the choose equation (if it is supplied) returning a true value for each row.

<table name> is the name of a table to which the user has Equation Engine (EE) write authority.

See the DELETE statement for details on the <statement block>, CHOOSE, and WHERE clauses.

INTO specifies a field that is to have a value when the row is inserted. Its value is set from the result of the <expression> in the FROM clause. If a field is marked as being 'required' within the Application Designer definition for that record, then that field must have an INTO clause associated with it. If the FROM <expression> specifies a global stem, in the format of <recname>.<fieldname>.<anyname>, then the <anyname> qualified is assumed to be an index into the global stem with the name <recname>.<fieldname>, and the ending limit of that index will be assumed to be the <recname>.!COUNT global value. (See alternate insert syntax.)

Alternate Syntax

This table shows examples of syntax for the keywords INSERT, CHOOSE, WHERE, and END DELETE:

This statement acts like the INSERT statement, except that the recname is followed by a dot, which makes the target of the insert a global stem. The value of <recname>.!COUNT will contain the number of rows in the global stem. If X is a global number holding a row number, then <recname>.<fieldname>.X will contain the value of the field <fieldname> in the table <recname> at row number X.

LOOP

Keywords: LOOP, EXIT LOOP, and END LOOP

The LOOP statement permits a block of statements to be run repetitively. Each LOOP statement block must end with an END LOOP statement.

Syntax

LOOP

<statement block>

END LOOP

Every loop block should include an EXIT LOOP keyword to stop the loop when the desired condition is reached. A RETURN or HALT statement can also be substituted, though it is discouraged because it makes your equations more difficult to maintain.

MESSAGE

Keywords: MESSAGE and END MESSAGE

The MESSAGE statement writes a message to the message log file (PS_MESSAGE_LOG) under the current process instance. It can contain up to 10 values, each of which can be a constant string, constant number, local or global variable, or table-field.

Syntax

This table shows an example of syntax for the keyword MESSAGE:

<data type> : STRING, DATE, NUMBER, LOCAL, GLOBAL, or TABLE xxx FIELD yyy

Note. Writing a message triggers a commit to be performed.

RESTORE

Keyword: RESTORE

Syntax

This table shows example syntax for the keyword RESTORE:

The RESTORE statement restores the specified global variable names from the previously created equation global space that is specified. If no global variable names are listed, then all global variables are restored, excluding read-only system variables.

RETURN

Keyword: RETURN

The RETURN statement causes the equation currently executing to stop processing, and it returns control to the calling equation. If no calling equation exists, then control returns to the program that called the Equation Engine. HALT and RETURN act the same if the Equation Engine calls only one equation and that equation does not call any others. An implicit RETURN statement is appended to the end of every equation if one was not placed there explicitly. The RETURN statement has no parameters. If you want to pass a parameter back to a calling equation, you must use global variables.

SAVE

Keyword: SAVE

Syntax

This table shows example syntax for the keyword SAVE:

The SAVE statement saves the specified global variable names to the specified equation global space. If no global variable names are listed, then all global variables are saved into the global space.

SKIP

Keyword: SKIP

The SKIP statements are used to make a program more readable. It allows you to break up the program statements, and it can simplify your IF logic.

Note. A SKIP statement does not affect your program.

TRACE

Keyword: TRACE

The TRACE statement causes the equation currently executing to start or stop displaying the type of trace information specified by the operand type.

Syntax

This table shows example syntax for the keyword TRACE:

<trace type>: SOURCE, PCODE or SQL.

<trace status>: ON or OFF

Tracing SOURCE causes the line numbers of the source equation to appear to the COBOL log file as they are run; intermediate values also appear. Tracing PCODE causes the pseudo-code functions, their parameters, and their line numbers to appear as they are run; intermediate values and function results also appear. Tracing SQL causes the actual SQL that is run to appear; bind variables and values, if any, as well as the return code and row count or dml count for the SQL also appear. Retrieved table and-field values do not appear. To enable more than one trace type at the same time, issue more that one trace statement. Tracing remains in effect globally until disabled. Therefore, a trace enabled in a called equation will continue tracing when control returns to the calling equation, and vice versa.

UPDATE

Keywords: UPDATE, SET, CHOOSE, WHERE, and END UPDATE

Syntax

The table shows example syntax for the keyword UPDATE:

This statement updates rows in the specified table, limited to the <where expression> evaluating to true. See the DELETE statement for details on the <statement block>, CHOOSE, and WHERE clauses.

SET clause sets the specified <field name> in the <table name> to the value of the <expression>.

Basic Language Syntax

This table lists the parse objects used in the Equation Editor:

Equation Engine Security

This section discusses the components of PeopleSoft Equation Engine security and how to implement them at your site.

Components of Equation Engine Security and Their Implementation

The following topics describe the components involved in Equation Engine security and how to implement Equation Engine security at your site.

Security Features

Equation Engine security features:

• Provide different levels of access (authorizations) to the equation objects based indirectly on the user identification (user ID). The three levels of access are:

  • Execute.

  • Read (contains Execute).

  • Write (contains Execute and Read).

• Provide a hierarchy (tree) of classes (user profile values) that are associated with the user ID.

• Associate different authorizations with different user profile values.

• Maintain the authorizations using the equation security trees.

User IDs and User Profiles

A user signs on to the database with a user ID. The ID is associated with zero or more user profile types, each of which is associated with exactly one user profile value. The types are:

Each user profile type has a controlling tree that determines the hierarchy of user profile values. For example, the highest root access would be PUBLIC, under which could be FIN AID ADMINS. User ID PS could be associated with FIN AID ADMINS under user profile type EQN.

Another user ID might be associated with PUBLIC. The hierarchy for EQN does not have to be the same as the hierarchy for EQS, EQD, or EQX. Each hierarchy can be different.

You might add a DEVELOPER class for EQN under FIN AID ADMINS in which only one FIN AID ADMINS user is included. You can set this user's access to WRITE, whereas all other FIN AID ADMINS have READ access to equations. Note that read-only access to an equation means that it cannot be viewed or modified from the Equation Engine component. Instead, it can be viewed only from the Equation View component.

You should not modify the user profile types. However, you must modify the user profile values using the tree structures and assign those values to various user IDs as appropriate.

User Profile Values

Just as each user ID in the system is associated with a Permission List (for example, ALLPANLS), each user profile type for each user can have one value associated with it (for example, PUBLIC). Initially, one is provided: PUBLIC. However, you are strongly encouraged to create your own new user profile values using the equation security trees. If a user ID does not have a user profile type and value set for it, then Equation Engine assumes a user profile value of PUBLIC by default.

Equation Security Trees

Use Tree Manager to maintain the equation security trees.

Select Tree Manager, Use, Tree Manager, Tree Manager. The following page shows the Tree Name in Tree Manager.

The following page is an example of a view of Public Access in the equation security tree.

If you click the Insert Child Node icon to the right of PUBLIC and add a new node underneath it, this is the result:

You click a tree node to select it, and then you click the red pencil icon (Edit Data) to view or modify the access settings for the selected tree node.

If you add new nodes here, then these new node names within the tree are added to the list of valid values that can be selectable as user profile type values for the user profile type associated with the tree structure being modified. Design your security tree structure to reflect the security needs within your organization based upon who needs what kind of access to which kinds of equation objects. Only the security administrator should have update access to edit these equation security tree structures and their associated lists of equation objects.

If a table has read authorization, then it can be used in FIND statements and table field references in expressions. If a table has write authorization, then it can also be referenced in the DELETE, INSERT, and UPDATE mass action statements.

To simplify access maintenance, select an Authorization Propagation type from the Authorization Propagation Type drop-down list box.

This table describes the Authorization Propagation Type values:

If you delete or rename an equation node from the tree manager, the underlying authorizations should be deleted automatically. If they are not, complete these steps to correct the error and to begin an analysis of the problem.

To correct the error, run the Application Engine process named SCC_EQAUTPUR.

1. Navigate to PeopleTools > Application Engine > Request AE.

2. Add a run control for SCC_EQAUTPUR, select process frequency Always, and click RUN.

3. Select your process server, select the process named SCC_EQAUTPUR, and click the OK button.

4. Navigate to the process monitor and verify that the process ran successfully.

This process purges the authorizations that are no longer associated with any tree nodes.

To analyze the cause of the problem, navigate to PeopleTools > Integration Broker > Service Operations Monitor > Monitoring > Asynchronous Services and complete these steps:

1. Look in the TREE_MAINT queue.

2. Verify that all the transactions in the TREE_MAINT queue are at Done status.

3. Select the Subscription Contracts tab.

4. Change the Node Name value to the default local node.

5. Change the Service Operation value to TREE_CHANGE.

6. Change the Queue Name value to TREE_MAINT.

7. Select the Done status.

8. Click the Refresh button.

9. Click the Details link of the most recent transaction.

The Asynchronous Details page for that transaction appears. The Action Name value should be Equation_Auth_Change_Handler and the status should be Done.

If so, then the orphan equation authorization node leaves should have been automatically purged when the equation authorization node was deleted or renamed in tree manager. If the status of the transaction is not Done, then correct your Application Messaging environment.

Authorization Levels

EQN (user profile type) authorizations of type WRITE permit a user to update an equation. Therefore, the authorization class is used in the search record for the Equations page.

Select Set Up SACR, Common Definitions, Equation Engine, Equation Editor.

The authorization class pertaining to equation names for the logged-in user ID (in this case, PUBLIC) is already supplied on the search page. When you click the Search button, the system displays a list of equations and equation descriptions that any user with PUBLIC access can update.

Select Set Up SACR, Common Definitions, Equation Engine, Review Equations.

In the Equation View search page, only equations that the user ID has write or read access appear.

In a similar way, the EQD user profile type provides a control point for access to tables and views that you are allowed to read when you create an equation. The EQS user profile type provides controls for determining which callable SQL you can invoke, and the EQX user profile type establishes a control point for determining which external subroutines you can call when you create an equation.

User Profiles

Equation Security is based on the user profile tools construct that comes with tools.

You will probably not modify the user profile type because it is tied to a program logic. However, you are required to change the profile type values within each type, assigning a value for each type for each user ID. The valid type values are the names of the tree nodes associated with the type.

User Profile Types

Each user profile type represents an entire set of user profile values; each user profile type is used for a particular application purpose. Normally, when a user signs on, he or she is assigned to roles and permissions lists, which determine the user's menu access. To assign users to different user profile values that do not necessarily correspond to roles and permission lists, you must use user profile types.

Select PeopleTools, Security, Security Objects, User Profile Types.

Although you would not change the user profile types, this page shows the profile types for Equation Engine:

Access the User Profiles, ID tab (PeopleTools, Security, User Profiles, User Profiles).

When you select the User Profile ID, the system displays the descriptions shown on the previous page.

On this page, you can add equation user profile types and select a user profile value for each one that you add.