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.

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.