Skip to content
SparkyaiPeopleSoft

describe_app_engine

describe_app_engine turns an Application Engine program into a readable outline: its sections, the steps in each section, and the actions in each step, with the SQL each action runs. The LLM uses it to explain what a batch program does, or to find where a table gets updated.

Use it for

Section titled “Use it for”
  • “Explain what ZZ_TRN_LOAD does, section by section.”
  • “Which steps in this program update PS_ZZ_TRAIN_REQ?”
  • “Which sections does this program call, and in what order?”

Input

Section titled “Input”
Argument Type Required Description
program string Yes The program name, such as ZZ_TRN_LOAD. Up to 12 characters.
section string No Describe only this section, which helps with large programs
market string No The market. Default: GBL.
include_sql boolean No Include the text of each SQL statement. Default: true.
include_peoplecode boolean No Include the text of each PeopleCode action. Default: false, which lists PeopleCode actions with a path for get_peoplecode instead.
Input schema
{
  "type": "object",
  "properties": {
    "program": {
      "type": "string",
      "pattern": "^[A-Za-z][A-Za-z0-9_]{0,11}$",
      "description": "Program name, for example ZZ_TRN_LOAD"
    },
    "section": {
      "type": "string",
      "pattern": "^[A-Za-z0-9_]{1,8}$",
      "description": "Describe only this section"
    },
    "market": {
      "type": "string",
      "pattern": "^[A-Za-z0-9]{3}$",
      "default": "GBL"
    },
    "include_sql": { "type": "boolean", "default": true },
    "include_peoplecode": { "type": "boolean", "default": false }
  },
  "required": ["program"],
  "additionalProperties": false
}

Output

Section titled “Output”
Field Description
program, description The program and its description
sections The sections, starting with MAIN, where every program begins
sections[].name The section name
sections[].platform, effectiveDate Which version of the section this is: its database platform (null for generic) and date
sections[].steps The steps, in sequence
steps[].name, sequence The step name and its position in the section
steps[].description The step’s description
steps[].inactive Present and true when the step is inactive
steps[].actions The step’s actions, in execution order
actions[].type The action type, such as Do Select or SQL
actions[].sql The statement, for SQL-based actions, when include_sql is true
actions[].sqlId The statement’s ID, which get_sql accepts
actions[].calledSection For a Call Section action, the section it calls, with the program when it’s in another program
actions[].path, peoplecode For a PeopleCode action, its get_peoplecode path, and its text when requested
truncated true when the program was too large to describe in one call

Within a step, Application Engine always runs actions in the same order: Do When, Do While, Do Select, PeopleCode, SQL or Call Section, Log Message, XSLT, and Do Until. The tool lists them in that order. A step can have a SQL action or a Call Section action, but not both.

Example: program 'zz_trn_load' (abbreviated)
{
  "program": "ZZ_TRN_LOAD",
  "description": "Load training requests",
  "sections": [
    {
      "name": "MAIN",
      "platform": null,
      "effectiveDate": "1900-01-01",
      "steps": [
        {
          "name": "Step01",
          "sequence": 1,
          "description": "Process approved requests",
          "actions": [
            {
              "type": "Do Select",
              "sql": "%Select(EMPLID, COURSE) SELECT EMPLID, COURSE FROM PS_ZZ_TRAIN_REQ WHERE ZZ_TRAIN_STATUS = 'A'"
            },
            { "type": "Call Section", "calledSection": "LOAD_ROW" }
          ]
        }
      ]
    }
  ]
}

How it works

Section titled “How it works”

An Application Engine program is spread across four tables, and the tool reads them in turn:

Table Holds
PSAEAPPLDEFN The program and its description
PSAESECTDEFN Its sections, with versions by market, database platform, and effective date
PSAESTEPDEFN The steps, ordered by AE_SEQ_NUM, with AE_ACTIVE_STATUS
PSAESTMTDEFN The actions, with their type and, for SQL-based actions, a SQLID

For each section, the server picks the version that Application Engine itself would run: your market and database platform if such a version exists, otherwise the GBL and generic versions, with the latest effective date on or before today. It then reads the steps and actions of that version of each section:

Steps and actions of one section version (Oracle Database)
SELECT S.AE_STEP, S.AE_SEQ_NUM, S.DESCR, S.AE_ACTIVE_STATUS,
       A.AE_STMT_TYPE, A.SQLID
  FROM PSAESTEPDEFN S
  JOIN PSAESTMTDEFN A
    ON A.AE_APPLID = S.AE_APPLID
   AND A.AE_SECTION = S.AE_SECTION
   AND A.MARKET = S.MARKET
   AND A.DBTYPE = S.DBTYPE
   AND A.EFFDT = S.EFFDT
   AND A.AE_STEP = S.AE_STEP
 WHERE S.AE_APPLID = :program
   AND S.AE_SECTION = :section
   AND S.MARKET = :market
   AND S.DBTYPE = :dbtype
   AND S.EFFDT = :effdt
 ORDER BY S.AE_SEQ_NUM

SQL-based actions keep their statements in PSSQLTEXTDEFN with SQLTYPE '1', split across rows by SEQNUM:

The statement of a SQL-based action (Oracle Database)
SELECT DBTYPE, EFFDT, SEQNUM, SQLTEXT
  FROM PSSQLTEXTDEFN
 WHERE SQLID = :sql_id
   AND SQLTYPE = '1'
 ORDER BY DBTYPE DESC, EFFDT DESC, SEQNUM

PeopleCode actions are stored in PSPCMPROG and PSPCMTXT under the Application Engine key path: program (66), section (77), market (39), database type (20), effective date (21), step (78), and event (12).

Limits and errors

Section titled “Limits and errors”
  • A call describes at most 500 steps. For larger programs, the result is truncated, and the LLM can describe one section at a time with section.
  • The tool doesn’t follow Call Section actions into other programs. It reports the program and section that are called, so the LLM can describe that program next.
  • A program that doesn’t exist returns a tool execution error that lists the closest program names.
Section titled “Related tools”