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.

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

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.

COBOL Field Name

COBOL Picture

Description

PROCESS-INSTANCE

9(8) COMP

Key of the process request record to update.

RUN-STATUS

X(1)

Values are:

7: Processing.

9: Successful.

10: Unsuccessful.

RUN-STATUS-MSGSET

9(4) COMP

Message set number.

RUN-STATUS-MSGID

9(4) COMP

Message number.

RC

9(4) COMP

Application level return code.

MESSAGE-PARM1

X(30)

First message log parameter that can be used with the PeopleCode MsgGet and MsgText functions.

MESSAGE-PARM2

X(30)

Second parameter that can be used with the PeopleCode MsgGet and MsgText functions.

MESSAGE-PARM3

X(30)

Third parameter that can be used with the PeopleCode MsgGet and MsgText functions.

MESSAGE-PARM4

X(30)

Fourth parameter that can be used with the PeopleCode MsgGet and MsgText functions.

MESSAGE-PARM5

X(30)

Fifth parameter that can be used with the PeopleCode MsgGet and MsgText functions.

CONTINUE-JOB

9(4) COMP

1: Continue job.

0: Terminate job.

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.