Appendix: Using Process Request APIs

This appendix provides an overview of process request application programming interfaces (APIs) and discusses how to:

• Use the COBOL API (PTPUSTAT).

• Use the Structured Query Reports (SQR) API (PRCSAPI).

• Schedule processes from outside of the PeopleSoft system.

• Schedule requests from an Application Engine program.

• Use the PeopleCode ProcessRequest class.

Understanding Process Request APIs

PeopleSoft Process Scheduler requires that all API-aware process requests (such as COBOL programs, SQR reports, and Crystal 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.

This section discusses:

• Process request APIs.

• Run status updates.

• API-aware versus API-unaware tasks.

Process Request APIs

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, Crystal, 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.

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.

Run Status Updates

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.

API-Aware vs. API-Unaware Tasks

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 or Crystal. 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.

Using the COBOL API (PTPUSTAT)

This section contains the information that you need in order to incorporate the COBOL API into your PeopleSoft Process Scheduler development.

This section discusses how to:

• Use COBOL requests.

• Use the Process Scheduler Update COBOL API (PTPUSTAT).

Using COBOL Requests

All variables in the copy member PTCUSTAT.CBL should be set (or to be supplied by default, if appropriate) by the application COBOL program before any call to PTPUSTAT. The only exception is PRUNSTATUS-RC, which is set by PTPUSTAT to reflect the success of your call.

Set CONTINUE-JOB-YES to TRUE if a process is part of a job definition and you want the next process request to run despite the run status that is set by the current request. Normally, subsequent job requests are selected to run only if the prior request finishes with a status of Successful.

Note. All Crystal and Workflow processes have internal APIs that do not require specific hooks from application modules. See the PeopleTools-based source member PTPTEDIT.CBL for an example of how to enable COBOL-based members to interact with PTPUSTAT.

Using the Process Scheduler Update COBOL API (PTPUSTAT)

Application programs that are written in COBOL can update selected process request fields at runtime using an API that is provided by PeopleSoft. This API includes the following fields.

The name of the copy member that contains the COBOL API table description is PTCUSTAT.CBL. The API call to use to call the PTPUSTAT subroutine is similar to this code:

IF  PROCESS-INSTANCE OF SQLRT  > ZERO
    IF  STATUS-OK OF SQLRT
        SET  RUN-STATUS-SUCCESSFUL OF PRUNSTATUS  TO  TRUE
    ELSE
        SET  RUN-STATUS-UNSUCCESSFUL OF PRUNSTATUS  TO  TRUE
    END-IF
    IF  PROCESS-INSTANCE OF PRUNSTATUS  > ZERO
        CALL  'PTPUSTAT'  USING  SQLRT
                                 PRUNSTATUS
    END-IF
    PERFORM  ZC000-COMMIT-WORK
END-IF

An API-aware COBOL program in PeopleSoft Process Scheduler must update the run status of a request to:

• Processing upon a successful connect.

• Successful or Error upon completion.

If this process runs as part of a multiprocess job, then the CONTINUE-JOB field can be set to 0 to prevent the next process from being initiated or 1 to initiate the next job process, regardless of the status of this request. If one process fails, you don’t jeopardize the entire job. If you set CONTINUE-JOB to 1, make sure that none of the jobs rely on a previous job’s successful completion.

To determine whether a process is running as defined within a job, use:

IF JOB-INSTANCE OF SQLRT > 0

A value that is greater than zero is part of a multiprocess job. You must do a COMMIT immediately following this call so that you are not holding locks.

All PeopleSoft COBOL application programs that use SQL should be defined in the Process Definition table with the following parameters:

DbType/%%DBNAME%%/%%OPRID%%/%%OPRPSWD%%/%%RUNCNTLID%%/%%INSTANCE%%

Note. A forward slash (/) is between each of the preceding parameters. The slash is easy to overlook between the pairs of percent signs. The batch run control ID is the only data item that must be supplied by the application. A field that is named PROCESS—INSTANCE in the SQLRT data structure contains the current process instance (key to the Process Request table).

Each API-aware COBOL process must include copy member PTCUSTAT, and all variables that are used to initialize column data in the update to table PSPRCSRQST must be properly set before this update request.

Using the SQR API (PRCSAPI)

This section contains the information that you need to incorporate the SQR API into your PeopleSoft Process Scheduler development.

This section discusses how to:

• Use SQR requests.

• Use Process Scheduler SQR API (PRCSAPI).

Using SQR Requests

All variables that are defined in PRCSDEF.SQC should be set (or left as the default) by the application SQR program before you call Update-Process-Status (PRCSAPI.SQC).

Set #prcs_continuejob to 1 if this process is part of a job definition and you want the next process request to run despite the run status that is set by the current request. Normally, subsequent job requests are selected to run only if the prior request finishes with a status of Successful.

Note. All Crystal and Workflow processes have internal APIs that do not require specific hooks from application modules. For SQR-based members, see XRFWIN.SQR.

Each API-aware SQR must include member PRCSDEF.SQC, and all PSPRCSRQST column-based variables must be properly set by application SQR code. Failure to manage these variables properly in the API can result in SQL update errors based on invalid data for the definition type.

Using the Process Scheduler SQR API

Application programs that are written in SQR can update selected process request fields at runtime using a PeopleSoft-provided API. This is to be used for SQR reports.

Include Files

SQRs should be defined to accept the following parameters from the command line.

All SQRs use the procedure Get-Run-Control-Parms, which is defined in PRCSAPI.SQC. For example:

Begin-Procedure Get-Run-Control-Parms
    input $prcs_process_instance 
					 ‘Please press ENTER (Do not input a value)’
    if not isnull($prcs_process_instance)
        let #prcs_process_instance = to_number
				($prcs_process_instance)
        input $prcs_oprid 
							‘Please press ENTER (Do not input a value)’
        let $prcs_oprid = upper($prcs_oprid)
        input $prcs_run_cntl_id 
							‘Please press ENTER (Do not input a value)’
    else
        let #prcs_process_instance = 0
    end-if
    if #prcs_process_instance > 0
        let #prcs_run_status = #prcs_run_status_processing
        do Update-Prcs-Run-Status
        let #prcs_run_status = #prcs_run_status_successful
    end-if
end-procedure

The three input commands correspond to the three values in the command line:

%%INSTANCE%% %%OPRID%% %%RUNCNTLID%%

When you run the SQR through SQR Windows (SQRW) and don’t enter any input values, the SQR interprets this as having been run outside PeopleSoft Process Scheduler. Therefore, it prompts for other input parameters that otherwise come from Run Control tables.

An API-aware SQR program in PeopleSoft Process Scheduler must update the run status of the request to:

• Processing upon receiving control.

• Success or No Success upon completion.

Note. All other SQR runtime parameters should reside in a run control record that is keyed by user ID and run control ID.

Scheduling Processes from Outside the PeopleSoft System

The PROCESSREQUEST component interface provides an API to create or update a process request from outside the PeopleSoft system. It returns the process instance of the process request that is created.

Successfully developing the functionality to schedule a process or job to run from outside PeopleSoft requires expertise in:

• PeopleSoft Process Scheduler definitions.

• PeopleCode.

• Component interfaces.

This section provides an overview of the component interface details and discusses how to schedule a process using a component interface in Visual Basic.

See Also

Accessing PeopleCode and Events

Component Interface Architecture

Securing Passwords When Scheduling from Outside PeopleSoft

Understanding Component Interface Details

The following topics provide the properties and methods that are associated with the component interface that is used to schedule processes from outside of PeopleSoft.

Component Interface Name

ProcessRequest

Properties

The following properties are associated with the component interface:

• RUNCONTROLID

• PROCESSTYPE

• PROCESSNAME

• JOBNAME

• RUNLOCATION

• RUNDATE

• RUNTIME

• RUNRECURRANCE

• OUTDESTTYPE

• OUTDESTFORMAT

• OUTDEST

• RUNSTATUS

• PROCESSINSTANCE

• REQUESTTYPE

Methods

The following methods are associated with the component interface:

• Standard:

  • Cancel

  • Find

  • Get

  • Save

  • Update

  • GetPropertyByName

  • SetPropertyByName

  • GetPropertyInfoByName

• User-Defined:

  • Create

  • Update

Scheduling a Process Using a Component Interface in Visual Basic

The following example shows how you might schedule a process from outside of PeopleSoft using Visual Basic.

Initializing the component interface:

Dim oSession As New PeopleSoft_PeopleSoft.Session
Dim oBC As ProcessRequest
oSession.Connect(1, "TCHURY072198:7000", "PTDMO", "PTDMO", 0)
'get component from server
Set oBC = oSession.GetComponent("PROCESSREQUEST")
Status = oBC.Get()

Creating a process request:

• Properties:

  oBC.REQUESTTYPE = "Create"
  oBC.RUNCONTROLID = "Test"
  oBC.PROCESSTYPE = "SQR Report"
  oBC.PROCESSNAME = "XRFWIN"
  oBC.RUNLOCATION = "PSNT"
  oBC.RUNDATE = "01/01/2000"
  oBC.RUNTIME = "09:00:00"
  oBC.OUTDESTTYPE = "FILE"
  oBC.OUTDESTFORMAT = "SPF"
  oBC.OUTDEST = "C:\temp\"

• Method:

  ProcessInstance = oBC.Create

Updating a process request:

• Properties:

  oBC.REQUESTTYPE = "Update"
  oBC.PROCESSINSTANCE = 10
  oBC.RUNSTATUS = "2"

• Method:

  oBC.Update

Scheduling Requests from an Application Engine Program

A known limitation exists when you schedule requests from an Application Engine program in which the process that is associated with the request contains in-line bind variables in the parameter list. An in-line bind variable is a field that is characterized in a parameter field like this:

:<Record>.<Field>

For example:

-ORIENTP :PYCYCL_STAT_VW2.PAY_CYCLE :PYCYCL_RPT_VW.BANK_CD

The ProcessRequest PeopleCode class resolves in-line variables in a parameter list by searching the values for these fields in the component buffer of a PeopleSoft Pure Internet Architecture page. However, this becomes a problem when ProcessRequest class is used within an Application Engine program. In an Application Engine program, concept of component buffer doesn’t exist. As a repercussion, the ProcessRequest class cannot resolve any in-line bind variables that are found in a parameter list.

Using a Component Interface to Schedule a Request

The instructions in this section describe how you can code a component interface in an Application Engine program to schedule a request using the ProcessRequest class.

Creating Definitions to Submit Requests That Contain In-line Bind Variables

To create the Component Interface to submit requests with in-line bind variables, you need to copy or reference the following Process Scheduler definitions:

The following steps use the definitions that are delivered with PeopleTools. Any definitions requiring modification are copied into a new definition to eliminate any problems with future PeopleTools upgrades.

1. Create a new page based on the PRCSRQSTBC page.

   1. Copy the page PRCSRQSTBC into a new definition.

      When Application Designer prompts you to copy the associated PeopleCode, reply yes.

   2. Insert a new edit box for the field that is referenced in the Parameter List.

      Select Insert, Edit box. When the cursor icon changes, click the mouse where you want to position the new field in the page. Double-click the new field to open the box to select the field for this new box. Perform this step for each field that is found in the parameter list.

   3. Save the new definition.

2. Create a new component based on the PRCSRQSTBC component.

   1. Make a copy of the component PRCSRQSTBC.

      When Application Designer prompts you to copy the associated PeopleCode, reply Yes.

   2. Insert the new page that you created from the previous step by selecting Insert, Page Into Component from the menu.

   3. Remove the page PRCSRQSTBC from the component so that the only page that is referenced in this component is the new page.

   4. Save the component.

3. Create a new Component Interface from the Application Designer by selecting File, New.

   When prompted for the new component, provide the component that was created from the previous step. Save the new component interface.

   Do not close the definition of the new component interface because additional edits will be done in subsequent steps.

4. Copy the existing PeopleCode that is found in the component interface PROCESSREQUEST.

   1. From the Application Designer, open the definition for the component interface PROCESSREQUEST.

   2. In the METHODS section of the component interface, move your mouse cursor to the Create method and right-click to select the View PeopleCode option.

   3. Highlight the PeopleCode, and then right-click to select the Copy option.

   4. In the new component interface, highlight the method Create and right-click your mouse to select the View PeopleCode.

   5. Paste the PeopleCode by right-clicking your mouse and select the Paste option.

   6. Save the component interface.

      After saving, you should see two additional methods, Schedule() and Update(), inserted in the METHODS section.

5. In the new component interface, add the new fields that were added in the new page from step 1.

   1. Click the Scroll – Level 0 folder to display all the records.

   2. Expand the record folder for the field that was added in the new page.

      Highlight the field with your mouse and drag the field to the PROPERTIES section of the component interface.

   3. Perform this step for any additional fields that were added to the page.

   4. Save the component interface definition.

6. Modify the Application Engine program to include the PeopleCode to schedule the request using the new component interface.

   The PeopleCode will be copied from the sample PRCSMULTI component.

   1. Open the Component PRCSMULTI from Application Designer.

   2. View the PeopleCode that is found in RUNCNTLCOMPINTF.FieldChange.

   3. Copy the entire PeopleCode that is found in FieldChange by highlighting the PeopleCode and right-clicking your mouse to select Copy.

   4. Open the Application Engine program where the request will be scheduled.

      In the step where the request will be copied, paste the PeopleCode that was copied from the PRCSMULTI component.

   5. In the pasted PeopleCode, perform the following edits:

      1. Remove the DoSave() function.

      This function is not allowed within an Application Engine program.

      2. In the function GetCompIntfc(), replace the component interface PROCESSREQUEST with the new component interface that was created in step 2.

      3. In all attributes of ProcessRequest class, modify these fields for the process request that you will schedule.

      For additional information pertaining to these attributes, please refer to the discussion of ProcessRequest class found in the PeopleCode manual.

      4. For the new fields that were added to the Properties of the component interface, modify the code to assign values to these fields.

      This is the value that will be assigned to the parameter list.

      5. Save your changes.

Using the PeopleCode ProcessRequest Class

The ProcessRequest class is the primary PeopleCode construct that you use for invoking processes through PeopleSoft Process Scheduler using PeopleCode. The ProcessRequest PeopleCode can be called from a:

• Push button.

• Save page.

• Field change event.

The ProcessRequest class provides properties and a method for scheduling a process or job that you have already defined using Process Scheduler Manager.

The properties of this class contain the same values as those that appear in Process Scheduler Manager for scheduling a process or job. Values that you provide for these properties may override the equivalent values set in Process Scheduler Manager, depending on the override settings that you make in PeopleSoft Process Scheduler pages.

Developers of PeopleSoft applications can simplify certain tasks for users by scheduling processes using PeopleCode. How you use the ProcessRequest construct depends on the nature of the task. You might want to segregate processes into specific categories, for example:

• Processes that are initiated by an action, such as calculations.

  Selecting a check box or clicking a button might call this PeopleCode.

• Reports that are associated with a function or set of tasks.

  A Print button might call this PeopleCode.

The ProcessRequest PeopleCode validates user input and writes a row to the Process Request table, providing the system with the information to run the process automatically, without user interaction. The Process Request table acts as the queue that the PeopleSoft Process Scheduler Server Agent uses to determine what jobs must be run and when.

Note. The PeopleSoft-delivered ProcessRequest PeopleCode can be used only for processes that do not pass in extra parameters. This means that reports that require extra parameters can be run only from the Run Control page.

You can schedule processes or jobs (groups of one or more processes) to run immediately or in the future. Recurring processes and jobs can be scheduled to run automatically at specific, user-defined intervals.

Note. The Window output type is not available if the user does not have REN server Report Window permission or if no active REN server cluster is available for reporting. The process would run using the Web output type and the following message would appear:

You do not have the permission required to run window option.