Understanding Process Request APIs

PeopleSoft Process Scheduler requires that all API-aware process requests (such as COBOL programs, and SQR reports) communicate with Process Scheduler and Process Monitor by properly integrating calls to the provided API modules. This informs Process Monitor about the current status of a request when the PeopleSoft Process Scheduler client or PeopleSoft Process Scheduler Server Agent initiates it.

PeopleTools provides two standard APIs for PeopleSoft Process Scheduler:

  • COBOL API to support COBOL processes.

  • Structured Query Report (SQR) API to support SQR processes.

The API interfaces for COBOL and SQR enable the process request to update:

  • Run status

  • Completion code

  • Message set

  • Message number

These API interfaces also enable you to pass up to five free-form parameters, which you can use with MsgGet (Message Get) and MsgGetText (Message Get Text) PeopleCode to display messages while the process is running.

To ensure that the request is physically updated, the API-aware process must perform the API call just before it commits processing.

Note: Because Application Engine, and nVision requests are managed through an internal API, they are already API-aware and do not require API interface calls.

The following table shows the PeopleTools-based APIs that are provided, including the module name for referencing how to implement the API.

Generic Process Type

API module

Reference

COBOL

PTPUSTAT.CBL

PTPTEDIT.CBL

SQR

PRCSAPI.SQC

XRFWIN.SQR

Workflow

PSDBA.CPP

NA

Application Engine

PSAE.CPP

NA

Application development teams that are working with PeopleSoft applications should ensure that:

  • The preceding APIs are properly included in the batch program code.

  • Normal program exits are coded to manage API run status updates, for example, Success.

  • Program exceptions are trapped and the run status is updated correctly before program termination, for example, No Success or Error.

If a process that updates the database reaches an exception that requires abnormal termination and rollback of prior updates, your code should:

  1. Perform the rollback.

  2. Use the API to update the run status to No Success.

  3. Commit this update, and then terminate.

Note: Indicate that a process is API-aware when you create the process definition.

PeopleSoft Process Scheduler Server Agent updates all requested tasks that are selected from Queued status to Initiated status before submitting the request to run. If the requested task fails before loading successfully—as can be the case with SQR, which must compile successfully before running—the run status remains Initiated and must be reset to Cancel through Process Monitor.

Tasks that terminate for any reason, leaving the run status of Initiated or Processing, automatically have their status reset by the PeopleSoft Process Scheduler Server Agent to Error. Because the PeopleSoft Process Scheduler Server Agent performs this function, it must be actively polling for requests.

You need to understand the differences between API-aware and API-unaware processes.

API-Aware

An API-aware process is a process that properly updates its process status through the type-specific API that is provided, such as COBOL. The application process has the responsibility of updating the Process Request table (PSPRCSRQST) with status information.

As the processes within a job must notify the server of the run status when they finish, the processes in the job definitions must be API-aware. This is how the system decides to continue with the next job process.

API-Unaware

API-unaware processes are programs that have no defined program interface to PeopleSoft Process Scheduler, such as CLOCK.EXE or WINWORD.EXE. Because API-unaware processes do not have the program interface to update the Process Request table in PeopleSoft Process Scheduler, the PeopleSoft system cannot determine whether the process finished successfully. Consequently, all API-unaware processes have a run status of Success to indicate that they were started successfully.

Note: A status of Success with an API-unaware process does not necessarily indicate that the process finished successfully.

API-unaware processes that are logged or monitored require manual clean up. That is, you must manually cancel or delete initiated requests that have failed.

If the API-aware option is selected for any process that is not API-aware, PeopleSoft Process Scheduler includes this process in the concurrent task count. This can result in improper server load balancing.

Setting this field for custom processes is not sufficient. You must include the code in your process to update the Process Request table to the appropriate run status.