

  


  IBM Tivoli Workload Scheduler                                   IBM
  for Applications fix pack 2 for
  version 8.1.1

------------------------------------------------------------------------

Date:                      October 31, 2003

Patch:                     8.1.1-WSE-FP02

Component:                 IBM Tivoli Workload Scheduler for
                           Applications Version 8.1.1

General Description:       IBM Tivoli Workload Scheduler for
                           Applications Fix Pack for Version 8.1.1

Important Notes:           None

Architecture(s):           WIN32 (Intel)

Patches Superseded by this patch:
                           8.1.1-WSE-FP01

Dependencies:              TWS 8.1.1 GA

Files Replaced by this Patch:
                           All IBM Tivoli Workload Scheduler for
                           Applications for PeopleSoft files (complete
                           update)  Patch Contents:
*  Fix Pack Contents:
   
   *  PSAGENT_I386NT  
      *  8.1.1-WSE-FP02.exe
   *  8.1.1-WSE-FP02.README (this file)
   *  8.1.1-WSE-FP02.vsr

*  Applying the patch:

   Refer to the New Feature section of this document.

This document provides the following information:
*  New features
*  Installation
*  Configuration
*  Special Considerations and Known limitations
*  Troubleshooting

New Features

The aim of this fix pack is to supply a complement to base PeopleSoft
APIs in order to enable current IBM Tivoli Workload Scheduler for
Applications for PeopleSoft to schedule jobs containing in-line bind
variable parameters in their job definitions. Due to limitations in the
PeopleSoft APIs when invoked from a batch environment, it is not
possible to schedule such jobs. With current PeopleSoft APIs, data that
is stored in the PeopleSoft Database referred to by a "runcontrolid
parameter" used to retrieve a "runcontrol data record" needs to be
loaded into the "Component Buffer" before scheduling the API invocation.
This cannot be done from a batch environment. Therefore, when invoking
the PeopleSoft scheduling APIs from a batch interface the data related
to the runcontrol ID is not available for the submission of a job, even
though it is available in the database. When unresolved data is present
in the submitted job, the PeopleSoft system refuses submission and ends
with an error.

The Fix Pack provides the ability to use the data already present in the
database to resolve in-line variable values by taking data from the
database and substituting it with variable definitions. It then allows
job submission regardless of the use of in-line variable definitions in
the jobs. The submission activity from the Tivoli Workload Scheduler
perspective does not depend on the types of jobs that are being
submitted. There are limitations, when the data used for PeopleSoft jobs
is volatile (never stored in the database). In these cases the data ends
its life when a PeopleSoft GUI transaction is complete. When these types
of process are used, the "runcontrol data record" is referred to as the
"Work record". The resolution of the work record data used in in-line
bind variables is not possible, as it is for other kinds of control
records, and requires special management. This case is currently out of
the scope of this fix pack.

When you submit Tivoli Workload Scheduler using a process that has in
line bind variables, the process type in the PeopleSoft GUI will be
called ITWS_<process type> For example, ITWS_PROCESSREQUEST instead of
PROCESSREQUEST.

Installation

Before installing this fix pack, the existing PeopleSoft method must be
uninstalled. This fix pack installs the PeopleSoft project directories
related to PeopleTools versions 8.1x and 8.4x, as shown in the following
structure:

TWS_HOME\methods\
\---PeopleSoft
    \---PT81x
    |   \---ITWS_PSXA
    |           BCM.DAT
    |           BCM.KEY
    |           CLM.DAT
    |           CLM.KEY
    |           ITWS_PSXA.ini
    |           MSG.DAT
    |           MSG.KEY
    |           PCM.DAT
    |           PCM.KEY
    |           PJM.DAT
    |           PJM.KEY
    |           SMDL.DAT
    |           SMDL.KEY
    |    
    |
    \---PT84x
        \---ITWS_PSXA
                ITWS_PSXA.ini
                ITWS_PSXA.XML

Configuration

The backend shipped with the new package invokes by default the new
Component Interface (CI) ITWS_PROCESSREQUEST. It is possible to force
the invocation of the original CI (or any compatible CI) by defining the
following new configuration options. A new configuration option may be
used to invoke the original component interface (PROCESSREQUEST). The
new options are as follows:

TWSXA_INLINE_CI=<CI name> 
TWSXA_SCHED_METH=<methname> 
TWSXA_SKEDM_TYPE= [ i | f | b ]

Where:

<CI name>=Component Interface Name.

If this is not set the default value will be set as: ITWS_PROCESSREQUEST

<methname>=name of the PeopleSoft method invoked by the Component
Interface.

Make sure that the TWSXA_SCHED_METH  method is used by the
TWSXA_INLINE_CI Component Interface (for example: ITWS_PROCESSREQUEST
uses Schedule).

If you want to use the PeopleSoft component interface PROCESSREQUEST to
submit processes without in-line bind variables, you must set
TWSXA_INLINE_CI=PROCESSREQUEST.

TWSXA_SKEDM_TYPE is the return value type of the method: where (i=
[integer], f= [float],and b=[boolean]).

The last option is used only for PeopleTools version 8.1x.

After installing the patch you must follow the steps as shown below:

1. A new PeopleSoft project called ITWS must be manually uploaded into
   the PeopleSoft Database. Start the Application Designer and from the
   signon window select to start the Application Designer in tier two
   mode as follows:
   *  Connection Type: <Database used> for example : Oracle
   *  Database Name: <Database Name>
   *  User ID: <Operator PS> for example: PS
   *  Password of User ID
   *  The Application Designer starts.

2. Using the Application Designer:
   *  Copy Project from the file
   *  Using the browser, edit the full path to specify the folder where
      the project that you want to load is located.
   *  The project is contained in the
      <TWSHOME>/methods/PeopleSoft/project-version> subdirectories under
      the specific PeopleTools version directories, where:
      project-version = PT84x | PT81x. 
      *  After you have chosen the folder PT84X (or PT81X) of project, a
         list of projects appears in the Project Name Field of the "Copy
         Project From File" window. Choose ITWS_PSXA and click on the
         copy Button.
      *  A Copy "window" appears showing a list of Object Types.
      *  To set the new settings, click the "Options" button
      *  Click on "Report Filter" tab
      *  Click on "Select All" button
      *  Click on the "OK" button
      *  Click on "select All"
      *  Click on "Copy", a copy progress bar appears.

      After loading the project, the PeopleSoft Database contains the
      following objects: 
      *  ITWS ProcessType Definition
      *  ITWS Permission List
      *  ITWS Cls

3. 

   To create the new Security Role ITWS_ROLE you can use the PeopleSoft
   Web GUI or the Application Designer. Follow the steps below:

   From the menu of the PeopleSoft Web GUI:

   *  People tools -> Security -> Permission and Roles -> Roles
   *  From the Tabs select "Add a new value"
   *  Edit ITWS_ROLE in the Role Name Field
   *  Select the permission lists tab, select ITWS from the list, and
      Save.

   From the Application Designer GUI:

   *  Using Maintain Security, edit the ITWS_ROLE window
   *  Select the Permissions list tab, select ITWS from the list, and
      save.

   To grant the ITWS_ROLE to all users who need to schedule jobs from
   Tivoli Workload Scheduler, you can use the PeopleSoft Web GUI or the
   Application Designer, following the steps below:

   From the Application Designer GUI:

   *  Using Maintain Security, edit the user name
   *  Select the Roles tab
   *  Add the ITWS_ROLE and Save.

   From the PeopleSoft WEB GUI:

   *  People Tools -> Security -> User Profiles ->
   *  Edit the User Name
   *  Select the Roles Tab
   *  Add the ITWS_ROLE and Save

4. 

   To add the ITWS process Types Definitions to the required Process
   Scheduler you can use the PeopleSoft Web GUI or the Application
   Designer. Follow the steps below:

   From the Application Designer GUI:

   *  Using Process Scheduler Manager
   *  Select the Server and add the ITWS_* Type definitions
   *  Process Type definitions
   *  Type definition

   From the PeopleSoft WEB GUI:

   *  PeopleTools -> Process Scheduler -> Servers -> Search your server
      -> Add the ITWS_*Process Types -> Save.

   Note: From the SQL interactive command line, the same task can be
         performed by the following sample statement, customized for
         your database environment: 
         INSERT INTO PS_SERVERCLASS SELECT o.SERVERNAME, 
         o.OPSYS,'ITWS_'||o.PRCSTYPE,o.PRCSPRIORITY,o.MAXCONCURRENT FROM PS_SERVERCLASS 
         o WHERE (  SELECT count(*) FROM PS_SERVERCLASS i WHERE 
         i.SERVERNAME=o.SERVERNAME AND   i.OPSYS=o.OPSYS AND   
         i.PRCSTYPE='ITWS_'||o.PRCSTYPE ) = 0 AND ( select count(*) from PS_PRCSTYPEDEFN 
         a where a.PRCSTYPE='ITWS_'||o.PRCSTYPE AND a.OPSYS=o.OPSYS ) > 0 

5. Restart the process servers.

You do not need to make any changes to the existing Tivoli Workload
Scheduler job definitions, except for the scheduling nVision process,
where the runcontrol ID must be specified using the
<BUSINESS_UNIT>.<REPORT_ID>convention.

An example related to Job Definition for the scheduling nVision process
is shown below:

-process <process-name>-type nVision-Report -runcontrol
<BUSINESS_UNIT>.<REPORT_ID>

-process 'NVSRUN' -type nVision-Report -runcontrol AUS01.VARIABLE



Special Considerations and Known Limitations

For PeopleTools version 8.4x, three new keywords are recognized in the
job definition to exploit a better output of jobs running under the
PeopleSoft Process scheduler. The new keywords are as follows:
*  outputtype (accepts PeopleSoft keywords: that is FILE, WEB,
   EMAIL....)
*  outputformat (accepts PeopleSoft keywords: that is PDF, HTML,....)
*  outputdest (accepts PeopleSoft recognized destinations corresponding
   to the output type)

No syntax check is performed on the values provided. If the values are
not recognized, defaults are used. During the Upload of the project a
basic set of Process Types starting with "ITWS_" are loaded
(approximately 145 for PT84x, and approximately 96 for PT81x). If you
submit a process with in-line bind variables belonging to a Process Type
<PT> that has no corresponding ITWS_<PT>, then you should create it
manually by using the PeopleSoft GUI.

Troubleshooting
1. 

   With PeopleTools Versions 8.x: CheckFile syntax is not supported.

2. 

   With PeopleTools Versions 8.x: The -operator keyword is ignored: if
   you need to use many different operator IDs, as a workaround, you can
   define multiple XA workstations (one per OperatorID), and configure
   the options file with the correct connection string.

3. 

   No defect number: During method execution with PeopleTools version
   8.41 servers, the following message may appear in the stdlist one or
   more times:

   "PSProperties not yet initialized
         java.lang.Throwable
         at psft.pt8.util.PSProperties.getProperties(PSProperties.java:49)
         at psft.pt8.definitions.Locale10Util.setLocale(Locale10Util.java:50)
         at psft.pt8.net.LoginInfo.setLocaleObj(LoginInfo.java:258)
         at psft.pt8.net.LoginInfo.setLocaleObj(LoginInfo.java:334)
         at psft.pt8.net.LoginInfo.setLanguageCd(LoginInfo.java:249)
         at psft.pt8.net.NetSession.deserializeUserContextDelta(NetSession.java:623)
         at psft.pt8.net.CertificateService.deserializeReply(CertificateService.java:133)
         at psft.pt8.net.NetService.requestService(NetService.java:147)
         at psft.pt8.net.NetReqRepSvc.requestService(NetReqRepSvc.java:264)
         at psft.pt8.net.NetSession.connect(NetSession.java:211)
         at psft.pt8.net.NetSession.init(NetSession.java:125)
         at psft.pt8.joa.Session.connectWithBlob(Session.java:232)
         at psft.pt8.joa.Session.connect(Session.java:28)
         at java.lang.reflect.Method.invoke(Native Method)
         at psft.pt8.joa.JOAObject.invokeMethodHelper(JOAObject.java:137)
         at psft.pt8.joa.JOAObject.invokeMethod(JOAObject.java:84)"

   This is a minor problem that does not affect the regular running of
   the job. It is also reported by PeopleSoft Support, but the
   resolution proposed is not working for version 8.4x.

4. 

   No defect number: During method execution with PeopleTools version
   8.17. There is a Date Format problem with the PeopleCode with
   versions of PeopleTools earlier than 8.18. This is a known PeopleSoft
   issue which has been referenced as the incident T-KRITZM-FR6JH
   "Component Interface PROCESSREQUEST PeopleCode needs to be updated
   for 8.1X". For PeopleTools versions before 8.18, you need to change
   the PeopleCode manually.

5. 

   If a job remains in INTRO state after you have submitted it you will
   see the following message in the log:

   Unable to set Processinstance to <xxx>
   *  TRC - Getting error message(s) from PSMessages:
   *  TRC - Number of Psoft Messages: 3
   *  TRC - Getting error message(s) from PSMessages:
   *  TRC - Number of Psoft Messages: 3
   *  TRC - PeopleSoftMessage:'Built-in function DatePart parameter 1 is
      invalid. (2,195) At PRCSRQSTBC_WRK.REQUESTTYPE.FieldFormula
      GetPrcsRqst PCPC:6975 Statement:111'
   *  TRC - PeopleSoftMessage:'Error changing value.
      {PROCESSREQUEST.PROCESSINSTANCE} (91,34)'
   *  TRC - PeopleSoftMessage:'Failed to execute PSBusComp request'

6. 

   The GetPrcsRqst Function in the
   PRCSRQSTBC_WRK.REQUESTTYPE.FieldFormula PeopleCode has to be modified
   with these changes for the 8.1X codeline:
   a. From your PeopleSoft Development Workstation open the "Application
      Designer" application.
   b. Select Insert, Objects into Project (or press the shortcut
      "Control-F7"). The "Insert into Project" dialog appears.
      (Control-F7)
   c. Open an Object Type of "Component Interfaces".
   d. In the Selection Criteria control group, in the"Name" input field,
      type "PROCESSREQUEST" and press the ENTER key to select the
      records.
   e. Click on the "Select All " button and then the "Insert" button.
   f. Close the "Insert into Project" before continuing.
   g. The PROCESSREQUEST Component Interface is shown in the tree view
      of the Application Designer window. You may need to expand the
      Component Interface folder to see it.
   h. Double click on the PROCESSREQUEST (or right click and select
      "View Definition"). You are shown the definition on the right
      window. Expand the "Scroll - Level 0" item.
   i. Right click on the "PRCSRQSTBC_WRK" record and select "View
      Definition"
   j. On the new window you see the record format of PRCSRQSTBC_WRK. Go
      to the field named "REQUESTTYPE" (it should be in bold typeface).
      Right click on it and select "View PeopleCode".
   k. The "PRCSRQSTBC_WRK. REQUESTTYPE.FieldFormula (Record PeopleCode)"
      window is the active window on the right side of your screen.
   l. Select "Edit->Find" (or press Contol-F) to search on the
      PeopleCode for the string "GetPrcsRqst".
   m. In the first lines of the PeopleCode Function "GetPrcsRqst" there
      is an SQLExec statement :
      SQLExec("SELECT A.RUNCNTLID, A.PRCSTYPE, A.PRCSNAME, A.PRCSJOBNAME, A.RUNLOCATION, A.SERVERNAMERQST, 
      A.SERVERNAMERUN, A.RECURNAME, A.RUNDTTM, A.OUTDESTTYPE, A.OUTDESTFORMAT, B.OUTDEST, A.RUNSTATUS, 
      C.XLATSHORTNAME FROM PSPRCSRQST A, PSPRCSPARMS B, XLATTABLE C, WHERE A.PRCSINSTANCE = B.PRCSINSTANCE 
      AND A.PRCSINSTANCE = :1 AND C.FIELDNAME = 'RUNSTATUS' AND C.FIELDVALUE = A.RUNSTATUS AND C.EFF_STATUS 
      = 'A'", &ProcessInstance, RUNCONTROLID, PRCSTYPE, PROCESSNAME, JOBNAME, &RunLocation, &SERVERNAMERQST, 
      &SERVERNAMERUN, RUNRECURRANCE, &RUNDTTM, &OutDestType, &OutDestFormat, OUTDEST, RUNSTATUS, RUNSTATUSDESCR);

   n. You need to update it as shown in the following line:
      SQLExec("SELECT A.RUNCNTLID, A.PRCSTYPE, A.PRCSNAME, A.PRCSJOBNAME, A.RUNLOCATION, A.SERVERNAMERQST, 
      A.SERVERNAMERUN, A.RECURNAME,%DateTimeOut(A.RUNDTTM), A.OUTDESTTYPE, A.OUTDESTFORMAT, B.OUTDEST,A.RUNSTATUS, 
      C.XLATSHORTNAME FROM PSPRCSRQST A, PSPRCSPARMS B, XLATTABLE C, PSOPTIONS D WHERE A.PRCSINSTANCE = B.PRCSINSTANCE 
      AND A.PRCSINSTANCE = :1AND C.FIELDNAME = 'RUNSTATUS' AND C.FIELDVALUE = A.RUNSTATUS AND C.EFF_STATUS 
      = 'A' AND C.LANGUAGE_CD = D.LANGUAGE_CD", &ProcessInstance, RUNCONTROLID, PRCSTYPE, PROCESSNAME, JOBNAME, 
      &RunLocation, &SERVERNAMERQST, &SERVERNAMERUN, RUNRECURRANCE, &RUNDTTM, &OutDestType, &OutDestFormat, OUTDEST, 
      RUNSTATUS, RUNSTATUSDESCR);

      Note: You are advised to duplicate the line before making the
            correction, and then to comment out the original statement
            by using the block comment characters "/*" <lines to
            comment> */)

   o. Select "File->Save" (or Control-S) to save your changes.
   p. Select "File->Exit" (or Control-Q) to close the Application
      Designer. If you are prompted to save your project, select "No".

7. 

   When scheduling jobs to PeopleSoft version 8.20 after you have
   installed Ext Api 8.20 on the Maestro system, if you follow the
   procedure: PeopleSoft version 8.1x, an error occurs. The job shows
   that class bea/jolt/JoltSessionAttributes are not found. This problem
   occurs because the psjoa.jar is not available locally on the
   Fault-tolerant Agent where ExtApi 8.20 is installed. The original
   psjoa.jar is located on the PeopleSoft 8.20 System: The path is as
   follows: %PS_HOME%\web\PSJOA.

   To work around the problem you must follow the procedure below:
   *  Create a folder called "class" in <PS_Ext_Api_HOME> folder. For
      example, if PeopleSoft ExtApi 8.20 Home is
      D:\PT820\bin\client\winx86_extapi, then create the folder as
      follows: D:\PT820\bin\client\winx86_extapi\class folder. Copy the
      psjoa.jar into the class folder.

      Stop and restart the Tivoli Workload Scheduler services.

      Note: The psjoa.jar is not provided with PeopleSoft 8.20. The
            defect number is: D 11447. "PeopleSoft CaseID 3179811 has
            been opened for this problem."

8. 

   When loading the project on the PeopleSoft Application from the
   Application Designer, a sequence of warning messages may appear as
   follows: 
   *  
          e:\pt84310-retail\SRC\PSSYS\pjmupd.cpp
          SQL error:Stmt#:425 Error Position: 12 Return:942-
          ORA-00942 table or view does not exist

   *  
          SQL Access Manager
          DELETE FROM PSPROJECTWORK WHERE
          PROJECTNAME =:1

   These popup messages are not error messages, they are only warnings.
   The ITWS_PSXA is built on the PeopleSoft Dev Environment PT816 and
   PT841, where the PSPROJECTWORK table exists. If the ITWS_PSXA project
   is loaded on the PeopleSystem where the PSPROJECTWORK no longer
   exists,  the above popup sequence may appear, warning you that the
   PSPROJECTWORK table does not exist. Click on the "OK" button, the
   project will continue loading.

9. 

   When installing PeopleSoft 8.1.1, from the window where you specify
   the PeopleTools Version and RunTime Environment, you have to start by
   selecting "Back-end PeopleTools 8.1x or PeopleTools 8.4x" and
   continue the installation. If you do not select "Back-end PeopleTools
   8.1x or PeopleTools 8.4x" and navigate between windows, when you
   select "Back-end PeopleTools 8.1x or PeopleTools 8.4x" the
   installation process will not let you specify the Ext Api8.x path. As
   a result you will be required to restart the installation. The
   internal defect opened for this problem is d 11351 "Installation does
   not require the correct back-end path version".

10. 

   The joblog of a job submitted to PeopleSoft 8.4x shows the following
   message: PeopleSoftMessage: 'Failed to execute PSBusComp request'
   even if the job ends successfully. This is only a warning message.
   The internal defect opened for this problem is : d 11462  "Failed to
   execute PSBusComp request" message always displayed.

11. 

   When submitting a job to PeopleSoft 8.1x the following message may be
   shown: PeopleSoftMessage: "First operand of . is NULL, so cannot
   access member Len. (2,236)". This is only a warning message, the
   execution will not be affected. The internal defect opened for this
   problem is d 11463 "Error First operand of . is NULL, so cannot
   access member Len".


