II13728: USING THE DB2 STORED PROCEDURE DSNACCJQ

APAR status

• Closed as documentation error.

Error description

• Reported component= 5740XYR05, DB2 CONTROL CENTER
  Rep rel=81D   SCP rel=81D
  Using the DB2 stored procedure DSNACCJQ
  

Local fix

• This APAR provides a brief guide to the new stored
  procedure DSNACCJQ included with PTF UQ81110.
  
  Stored procedure DSNACCJQ
  ----------------------------
  
  1. Description
  ---------------
  
  DSNACCJQ is a DB2 stored procedure that gives
  applications a way to query job status. Depending on
  the requested operation, DSNACCJQ returns the job status
  indicating that the job is in the input queue, is active
  or is in the output queue, or returns the job status in
  a more detailed format.
  The application connects to a DB2 Universal Database
  for z/OS subsystem, and then calls DSNACCJQ to
  perform the requested operation.
  
  2. Environment
  ---------------
  
  DSNACCJQ runs in a WLM-established stored procedure address
  space.
  
  3. Authorization required
  --------------------------
  
  Please see the section " Notes on the required RACF authority"
  in the APAR II13698.
  
  4. DSNACCJQ syntax diagram
  ---------------------------
  
  >>__CALL__DSNACCJQ__(_____________________________________>
  > __operation__,__user-ID__,__user-pswd__,__________ _____>
  > __jes-ID__,__job-ID__,__wait-time___,___________________>
                           |___NULL___|
  > __return-code__,__job-status___,__msg-area___)_________><
  
  5. DSNACCJQ option descriptions
  --------------------------------
  
  operation -
     Specifies the format of the job status information:
        1 - Returns a job status indicating whether the job is
            in the input queue,
            is active, or is in the output queue.
        2 - Returns the job status in a more detailed format.
     This is an input parameter of type INTEGER.
  user-ID -
     Specifies the user ID that the stored procedure DSNACCJQ
     runs under.
     This is an input parameter of type VARCHAR(8).
  user-pswd -
     Specifies the password for the user ID specified in
     the user-ID parameter.
     This is an input parameter of type VARCHAR(8).
  jes-ID -
     This is the ID that has been assigned by the system
     programmer to the JES. If only one JES2 is in use
     then usually the default name 'JES2' is used.
     This is an input parameter of type VARCHAR(8).
  job-ID -
     Specifies a JES2 or JES3 job ID.
     It can have the format J####### or JOB#####,
     where the # symbol stands for any digit 0-9."
     This is an input parameter of type VARCHAR(8).
  wait-time -
     Specifies the number of seconds that DSNACCJQ
     will wait for the requested operation to be processed by
     JES. This value is ignored when operation 1 is specified.
     If this parameter is set as NULL then the default
     value (1 second) will be used.
     If the time expires then the stored procedure will finish
     with the return code 4.
     This is an input parameter of type INTEGER.
  return-code -
     Return code from the stored procedure. Possible values are:
         0 - The call completed successfully.
             If operation 2 is specified, the msg-area parameter
             contains the job status information in a more
             detailed format.
         4 - If operation 2 is specified, the call completed
             successfully but the operation is not processed
             within the time specified in the wait-time parameter.
             The msg-area parameter contains messages that
             describe the error.
         8 - The call did not complete successfully. An error
             occurred.
             The msg-area parameter contains messages that
             describe the error.
        12 - The call did not complete successfully. A severe
             error occurred.
             The msg-area parameter contains messages that
             describe the error.
        This is an output parameter of type INTEGER.
  job-status -
        If operation 1 is specified, one of the following job
        status information is returned:
            1 - The job was received, but not yet run (INPUT)
            2 - The job is running (ACTIVE)
            3 - The job has finished and has output to be
                printed or retrieved (OUTPUT)
            4 - The job is not found (return code is set to 4)
            5 - The job is in an unknown phase (return code
                is set to 4)
        If operation 2 is specified, zero is returned.
        This is an output parameter of type INTEGER.
  msg-area -
     Contains messages if an error occurs during stored procedure
     execution. The first messages in this area are generated
     by the stored procedure. Messages that are generated
     by z/OS might follow the first messages.
     This is an output parameter of type VARCHAR(32677).
  
  6. Example of DSNACCJQ invocation
  ----------------------------------
  
  The following Java example outlines the steps that you need to
  perform to invoke the stored procedure DSNACCJQ to get the
  job status and to retrieve the return code and messages that
  DSNACCJQ returns.
  
      ...
      Connection con;
      CallableStatement cs;
  
      // Assign values to DSNACCJQ input parameters
      int operation = 1;            // use FTP-like format
      String userID = "USER1";
      String pswd   = "PSWD1";
      String jesID  = "JES2";
      String jobID  = "JOB00102";
      ...
      // Create a CallableStatement object
      cs = con.prepareCall("CALL SYSPROC.DSNACCJQ(" +
                           "?, ?, ?, ?, ?, ?, ?, ?, ?)" );
  
      // Set DSNACCJQ input parameters
      cs.setInt(1,operation);  // set the operation code
      cs.setString(2, userID); // user ID DSNACCJQ will run under
      cs.setString(3, pswd);   // password of userID
      cs.setString(4, jesId);  // JES subsystem ID
      cs.setString(5, jobId);  // id of the job
      cs.setNull (6,Types.INTEGER);// wait-tTime is not required
                                   // for operation 1
      // Register DSNACCJQ output parameters
      cs.registerOutParameter(7,Types.INTEGER);     // return code
      cs.registerOutParameter(8,Types.INTEGER);     // job status
      cs.registerOutParameter(9,Types.LONGVARCHAR); // message are
  
      // Call DSNACCJQ
      cs.execute();
  
      // Retrieve DSNACCJQ output parameter 'return code'
      int rc = cs.getInt(7);
  
      // Retrieve DSNACCJQ output parameter 'job status'
      if (rc < 8) {
        int js = cs.getInt(8);
      }
  
      // Stored procedure did not complete successfully
      // retrieve error message
      if (rc != 0) {
         String message = cs.getString(9);
         ...
      }
  
      // Close the statement
      cs.close();
  
  ============================================
  

Problem summary

•  A brief user guide for the stored procedure
  DSNACCJQ  is required
  

Problem conclusion

•  A brief user guide is provided
  

Temporary fix

Comments

APAR Information

• APAR is sysrouted FROM one or more of the following:

• APAR is sysrouted TO one or more of the following:

Fix information

Applicable component levels