Additional steps for enabling web service user-defined functions

Enabling the web service user-defined functions allows you to specify a complete SOAP message as input, so you receive the complete SOAP messages from the web service provider's response.

Before you begin

Before you complete these steps, set up WLM application environments for web service user-defined functions.

Recommendation: Start of change For web service functions, use the DSNWLM_WEBSERVICES core WLM environment.End of change

About this task

Start of changeDuring installation or migration, the following web service user-defined functions were installed by job DSNTIJRT:End of change
  • DSNWSCVV
  • DSNWSCVC
  • DSNWSCCV
  • DSNWSCCC

Procedure

To set up the web service user-defined functions:

  1. The default timeout to read data from a web service provider is two seconds. Increase the timeout value by redefining the web service user-defined functions with the key and value pair DB2SOAP_TIMEOUT=X in the ENVAR parameter values, where X is a number that specifies the timeout value in seconds.
  2. Start of changeIf you want to use SOAP Version 1.2, include the key and value pair DB2SOAP_VERSION=SOAP_12 in the ENVAR parameter values. By default, DB2® uses SOAP Version 1.1. If you specify any other value for DB2SOAP_VERSION besides SOAP_12, SOAP Version 1.1 is assumed.

    If your subsystem uses SOAP Version 1.1 and SOAP Version 1.2, you must define two sets of SOAP user-defined functions: one without ENVAR("DB2SOAP_VERSION=SOAP_12"), and one with ENVAR("DB2SOAP_VERSION=SOAP_12").

    End of change
  3. Start of changeIf you want to receive SOAP error messages, specify the ENVAR option RETURN_ERROR=YES.

    If RETURN_ERROR=NO or the option is not specified and an error occurs, the web service provider returns a SOAP response to the client with an HTTP return code set other than 200. In this case, the user-defined functions end with SQLCODE=-443 and the complete HTTP response that was sent by web service provider is stored in the WSERROR DD file, as specified in the WLM startup procedure. The file contains the actual bytes that are sent by the web service provider.

    If you specify RETURN_ERROR=YES, the SOAPHTTP user-defined function writes the HTTP content to the WSERROR DD file when the HTTP status code is not 200. It also builds a new XML document with an error element node that contains an "httprc" attribute around the SOAP response, as follows: 
    <error httprc="{HTTP status code}">
      {SOAP response}
</error>
    The XML document is returned without issuing SQLCODE -443. Your applications must check for a root element node of error to determine if an HTTP error is returned. If an HTTP error is returned, the applications must process the SOAP response to handle the error.
    End of change
  4. Start of changeIf you do not use the DSNWLM_WEBSERVICES core WLM environment, add the following DD card to the WLM startup procedure where the user-defined functions are defined.End of change 
    // WSERROR DD PATH='<HFS filename>',
// PATHOPTS=(ORDWR,OCREAT,OAPPEND),
// PATHMODE=(SIRUSR,SIWUSR,SIRGRP,SIWGRP,SIROTH,SIWOTH)
    where <HFS filename> is the name of an HFS, such as /tmp/wsc.err.
    If the response is in Unicode, you can browse the file on an MVS™ system by issuing the following command:
    iconv -f UTF-8 -t IBM-1047 < tmp/wsc.err
    You can store the contents in EBCDIC by saving it to another file by issuing the following command:
    iconv -f UTF-8 -t IBM-1047 < wsc.txt > wsc_ebcdic.txt
    You can also FTP the file in BINARY mode to a workstation and open it using a text editor.