IBM Support

PI86867: SERVICE UPDATE OF DB2 11 NATIVE RESTFUL SERVICES SUPPORT

A fix is available

Subscribe

You can track all active APARs for this component.

APAR status

  • Closed as new function.

Error description

  • See PI86868 for DB2 12 for z/OS.
    Multiple improvements to the RESTful services support in DB2
    are being delivered.
    DB2REST
    .
          **********************
             Important Note
          **********************
    After delivery of this Db2 V11 APAR (PI86867), it was
    discovered that the DSN BIND SERVICE support delivered
    was incomplete, and does not work correctly in a Db2 Data
    Sharing mixed release environment with both Db2 V11 and
    Db2 V12.  The issue described is specific to the DSN BIND
    SERVICE command usage, and does not affect any other Db2
    functionality.
    
    Although a defect exists in the DSN BIND SERVICE support that
    was initially delivered in this APAR (PI86867), the
    corresponding PTF UI51795 will NOT be marked as "PE" because
    the error is isolated to the new BIND SERVICE functionality
    that was delivered by this new function APAR.  Using Db2
    V11 APAR PI86867 level DSN BIND SERVICE in a mixed release
    environment could result in various unexpected BIND SERVICE
    errors, including possible ABEND S0C4 in BIND related modules
    such as DSNTBAP2.  The Db2 V11 BIND SERVICE Data Sharing
    release incompatibility issue is corrected by Db2 V11 PI90243.
    
    In order to avoid any unexpected failures, it is recommended
    that all Db2 V11 users suspend/delay usage of the DSN BIND
    SERVICE command until Db2 V11 APAR PI90243 has been installed
    and is active in all Db2 V11 environments.
          **********************
             Important Note End
          **********************
    

Local fix

Problem summary

  • ****************************************************************
    * USERS AFFECTED: All users of DB2 11 for z/OS planning to     *
    *                 use DB2 native RESTful services support.     *
    ****************************************************************
    * PROBLEM DESCRIPTION: Update to the DB2 native RESTful        *
    *                      services support, including both        *
    *                      defect fixes and new functionality.     *
    ****************************************************************
    * RECOMMENDATION:                                              *
    ****************************************************************
    This APAR provides a service update to the DB2 native RESTful
    services support, including both defect fixes and new
    functionality.  In particular, this service update APAR
    addresses the following issues:
    
    1. The DB2 native REST services support currently
       provides REST service manager APIs that can be used
       to create or drop DB2 user defined REST services.
       These existing REST service manager APIs can be invoked
       from almost any REST client application or tooling, and
       are therefore very well suited for application
       developers.  However, the requirement to use a REST
       client and the DB2 REST service manager APIs to create
       or drop DB2 user defined REST services does not fit well
       with existing DB2 application deployment processes
       that are typically used by Database Administrators (DBAs).
       A new method, that is similar to the existing DB2
       application package creation and deletion processes, is
       needed by DB2 DBAs for creating and dropping DB2 user
       defined REST services.
    
    2. The current behavior of the DB2 native REST services
       is that DB2 will close the HTTP connection/socket
       immediately after processing each REST request.  This
       behavior requires that a new HTTP connection/socket be
       created by the REST client for each new DB2 REST service
       invocation.  Requiring a new HTTP connection/socket
       for each service invocation can result in poor
       performance, especially for secure HTTPS SSL/TLS
       connections, which must go through new SSL handshake
       processing for each new connection.
    
    3. Possible ABEND S0C4, LOC=DSNLDTML.DSNXATUM+007C2
       when making a DB2 native REST service request with
       BOTH SSL Client Certificate authentication AND
       Basic Authentication, but there is no matching
       DB2 Trusted Connection definition for the supplied
       Client Certificate authentication.
    
    4. When using the DB2 native REST service manager API
       to create a DB2 user defined REST service, the create
       service could succeed even if some bind options that
       are not applicable for a REST service were specified
       in the create service request.  The DB2 native REST
       service manager create API ignored the bind options
       that were not applicable instead of issuing an error
       message and failing the create service request.
       The DB2 native REST service manager create API should
       issue an error message and fail the service create
       request if any bind options that are not applicable or
       not supported for REST services are specified.
    
    5. For a new install of the DB2 DDF native REST support,
       sample job DSNTIJRS must be run to create the database
       objects that are required by the REST services support.
       Currently, the DB2 DDF native REST services support only
       checks for the availability of the required database
       objects when the DB2 DDF facility is started.  That means
       that the DB2 DDF facility must be recycled after running
       the sample DSNTIJRS job.  The DB2 DDF native REST support
       should be changed to not require DB2 DDF to be recycled in
       order to detect that the required database objects
       have been created.
    
    6. The built-in DB2ServiceDiscover service can be used to
       discover and list all available DB2 native REST services,
       using:
          POST <host:port>/services/DB2ServiceDiscover
       However, a POST invocation of the DB2ServiceDiscover
       service with NO input JSON body fails with a reply similar
       to the following example:
    
         {
          "StatusCode": 500,
          "StatusDescription": "Execution failed during
           DB2ServiceDiscover due to an internal server error.
           Please contact IBM support Error Location:DSNLJDSC:50"
         }
       This failure does not occur if the request includes an input
       JSON body, even if it is empty.
    

Problem conclusion

Temporary fix

Comments

  • The following changes have been made:
    
    1. This APAR adds new "BIND SERVICE" and "FREE SERVICE"
       DSN subcommands that can be used to create and drop
       DB2 user defined REST services.
    
       The following is a short summary of the new commands.
       Also enclosed are the new and changed Db2 messages that
       are introduced or updated in support of the new commands.
    
       Refer to the Db2 for z/OS documentation in the IBM Knowledge
       Center for complete information about the updated Db2
       native REST services support.
    
       The general syntax for the new DSN BIND SERVICE
       subcommand is:
    
        BIND SERVICE(<collection-id>) NAME(<service-name>)
              SQLDDNAME(<ddname>)
              SQLENCODING( ASCII | EBCDIC | UNICODE | <ccsid>)
              DESCRIPTION (<description-string>)
               <Additional BIND options>
    
    
        Descriptions of the BIND SERVICE options:
        =========================================
        collection-id
          Identifies the collection of the service.  There is
          no default.  The collection-id can be an undelimited
          or a delimited identifier.  The delimiter for
          collection-id is double quotation marks (").  If
          collection-id is delimited, DB2 does not convert the
          value to uppercase.
    
        service-name
          Identifies the service.  There is no default.
          The service-name can be an undelimited or a delimited
          identifier.  The delimiter for service-name is double
          quotation marks (").  If service-name is delimited,
          DB2 does not convert the value to uppercase.
    
        description-string
          A brief description of the service that can be up
          to 250 characters in length. If provided, DB2 stores
          the value in the DESCRIPTION column of the
          SYSIBM.DSNSERVICE catalog table.
    
        ddname
          Locates the file or dataset that contains a single SQL
          statement to be included as the new service.
          If the SQLDDNAME parameter is not provided,
          DSNSTMT is used as the default ddname.
    
          The JCL for the BIND SERVICE command job must provide
          a valid DD specification for ddname.  The DSNAME
          parameter of the DD specification must refer to
          either a valid DSORG=PS dataset or a member-qualified
          library, e.g. library.name(member).  If the SQL
          statement text is provided via a zFS or UNIX
          file, the PATH parameter (which is mutually
          exclusive with the DSNAME parameter) must specify
          a fully qualified name to the zFS or UNIX file.
    
        SQLENCODING
          Specifies the encoding of the SQL statement located by
          SQLDDNAME(ddname).  If SQLENCODING is not specified,
          the DB2 default EBCDIC CCSID from DSNHDECP
          is used.
    
        Additional BIND options
          Refer to the DB2 for z/OS documentation in the IBM
          Knowledge Center for the descriptions of any
          additional BIND options.
    
    
       The general syntax for the new DSN FREE SERVICE
       subcommand is:
    
           FREE SERVICE(<collection-id>.<service-name>)
    
        Descriptions of the FREE SERVICE options:
        =========================================
        collection-id
          Identifies the collection of the service.  There is
          no default.  The collection-id can be an undelimited
          or a delimited identifier.  The delimiter for
          collection-id is double quotation marks (").  If
          collection-id is delimited, DB2 does not convert the
          value to uppercase.
    
    
        service-name
          Identifies the service.  There is no default.
          The service-name can be an undelimited or a delimited
          identifier.  The delimiter for service-name is double
          quotation marks (").  If service-name is delimited,
          DB2 does not convert the value to uppercase.
    
    
    2. This APAR now adds support for HTTP persistent
       connections to be used when invoking/executing DB2 native
       REST user services.  DB2 will no longer immediately close
       the HTTP connection/socket following a SUCCESSFUL (HTTP
       status code 200 OK) invocation of a user defined service.
       DB2 will now allow the connection/socket to remain open
       for a short period of time following the successful
       service invocation.  The initial amount of time that the
       connection/socket will remain open following a successful
       invocation is approximately fifteen (15) seconds,
       although this delay time may be adjusted by future DB2
       maintenance.
    
       Note: At this time, the new persistent connection
       support is only available for SUCCESSFUL (HTTP status
       code 200 OK) invocation/execution of DB2 user defined
       services.  An HTTP connection that is used for a service
       invocation that is not successful (any returned status
       code that is not 200/OK), or a connection that is used
       for other DB2 DDF native REST service activities (such
       as create, free, or discover) will still be immediately
       closed by DB2 after processing the request.
    
    3. DB2 has been corrected to return the expected error
       message if BOTH SSL Client Certificate authentication AND
       Basic Authentication are provided on the DB2 native REST
       request, but there is no matching DB2 Trusted Connection
       definition for the supplied Client Certificate
       authentication.
    
    4. The DB2 native REST service manager API has been
       corrected to issue an error message and fail the request
       if any bind options that are not applicable or not
       supported for REST services are specified on the create
       request.
    
    5. The DB2 native REST service support has been enhanced to
       detect if the required DSNTIJRS database objects have
       been created without requiring a DB2 DDF restart.
    
    6. The DB2ServiceDiscover service code has been fixed so it
       will work correctly when the request does not include
       an input JSON body.
    
    
    DB2 Information APAR II14827 MUST be reviewed for
    any IMPORTANT additional documentation, and any known
    limitations or restrictions related to the DB2 native REST
    services support.
    
    
    New messages added for BIND SERVICE and FREE SERVICE
    =====================================================
    
    DSNT274I   ERROR USING SQLDDNAME(ddname): error-text
    
     Explanation
      DB2 could not open or read the data set or file
      assigned to the ddname DD statement in the JCL for
      the BIND SERVICE subcommand because of one
      of the conditions specified in error-text.
    
     ddname
      The name specified for the SQLDDNAME parameter of the
      BIND SERVICE command.
    
     error-text
      Possible conditions that can cause the error:
    
      DDNAME CANNOT BE OPENED
       The DD job card is not provided in the JCL job or
       an error prevents the opening of the data set or file.
       Review all job messages.
    
      INVALID DSORG OR RECFM SPECIFICATION
       The output can be a data set, a fully-qualified member
       of a PDS/PDSE library, or a zFS or UNIX file. The
       organization of the data set or file must be
       sequential. The format must be F (fixed-length records,
       unblocked), FB (fixed-length records, blocked),
       V (variable-length records, unblocked), or VB
       (variable-length records, blocked). Make sure that
       RECFM=VB is specified with the DD statement when
       it refers to a zFS or UNIX file.
    
      EMPTY DATASET OR FILE
       The end of file is reached before any data
       is read in.
    
      I/O ERROR DETECTED - error-desc
       During a read of the ddname data set or file, an I/O error
       with error-desc is detected.  See "SYNADAF Error
       Descriptions" in the z/OS documentation for more
       information. One possible cause for the I/O error
       "WRNG.LEN.RECORD" is that a member name is not specified
       with the PDS or PDSE library name for the ddname DD
       statement.
    
    
     System action
      The BIND SERVICE subcommand operation is not performed.
    
     System programmer response
      If an I/O error is detected, verify that the data set or
      file specified for the DD statement is a supported
      DSORG or RECFM and that the data set or file exists and can
      be opened.
    
     User response
      Verify that the BIND SERVICE job JCL contains a valid
      ddname DD specification and the data set or file
      containing the SERVICE SQL statement actually exists. Make
      sure that the data set or file can be opened and contains
      an SQL statement.
    
     Severity
      8 (error)
    
    
    DSNT276I SUCCESSFUL bind-type FOR SERVICE = service-name
    
     Explanation
      The BIND or FREE SERVICE subcommand has completed
      successfully.
    
     bind-type
      Type of bind subcommand: BIND or FREE
    
     service-name
      Name of the service in the following format:
      'location.collection.service.(version)'
    
     System action
      The service is successfully bound or freed.
    
    
    DSNT277I UNSUCCESSFUL bind-type FOR SERVICE = service-name
    
     Explanation
      The BIND or FREE SERVICE command failed because of an
      error in the previous operation. The error is not resolved
      yet.
    
     bind-type
      Type of bind subcommand: BIND or FREE
    
     service-name
      Name of the service in the following format:
      'location.collection.service.(version)'
    
     System action
      The service-name service is not bound or freed.
    
     System programmer response
      See the preceding error message or messagess
      to determine the cause and respond accordingly.
    
    
    DSNT278I bind-type SERVICE ERROR FOR service-name
             BECAUSE error-text
    
     Explanation
      The BIND or FREE SERVICE subcommand failed because of
      one or more conditions specified in error-text.
    
     bind-type
      Type of bind subcommand: BIND or FREE
    
     service-name
      Name of the service in the following format:
      'location.collection.service.(version)'
    
     error-text
      Possible conditions that can cause the error:
      - SERVICE DOES NOT EXIST.
      - SERVICE ALREADY EXISTS.
      - THE SQL STATEMENT IS NOT SUPPORTED.
      - CALL HOST-VARIABLE IS NOT SUPPORTED. USE CALL
        PROCEDURE-NAME INSTEAD.
      - OFFLOAD OF NON-SELECT STATEMENTS IS NOT SUPPORTED.
      - STATEMENT CONTAINS UNBALANCED DELIMITERS.
      - STATEMENT CONTAINS BOTH HOSTVARS AND PARAMETER MARKERS.
      - STATEMENT CONTAINS A ZERO LENGTH HOSTVAR.
      - STATEMENT CONTAINS NO HOSTVAR IDENTIFIER AFTER COLON.
    
     System action
      The service-name service is not bound or freed.
    
     System programmer response
      See error-text to determine the cause of the error.
    
    
    DSNT279I csect-name A REST SERVICE CANNOT BE
             bind-result-type USING THE bind-type PACKAGE
             COMMAND
    
     Explanation
      A BIND PACKAGE COPY or a FREE PACKAGE subcommand was
      issued to bind or free a REST service. A DB2 REST
      service can be bound or freed only by using the
      BIND SERVICE or FREE SERVICE subcommand.
    
     bind-result-type
      Result type of bind subcommand: BOUND or FREED
    
     bind-type
      Type of bind subcommand: BIND or FREE
    
     System action
      The TSO Attachment Facility is ready for more input.
    
     User response
      Use the BIND or FREE SERVICE subcommand to bind or
      free a REST service.
    
    
    Changed message to include BIND SERVICE information
    ===================================================
    
    The system action section of message DSNT234I is updated
    to include information about the BIND SERVICE subcommand.
    
    DSNT234I MESSAGE LIMIT EXCEEDED
    
     Explanation:
      A fixed amount of space exists in which to generate
      bind subcommand messages. This message says that the
      bind subcommand generated more messages than will fit
      in that space.
    
     System action:
      For bind subcommands that affect a single package or a
      service, the bind subcommand process continues.  However,
      no other messages are generated except for completion
      message DSNT232I or DSNT233I for packages, or completion
      message DSNT276I or DSNT277I for services. For bind
      subcommands that affect more than one package or a
      service, the bind subcommand process terminates and no
      other messages are generated.
    
     System programmer response:
      The 'FLAG' parameter of the bind subcommand may be used
      to limit the types of messages that are generated.
    

APAR Information

  • APAR number

    PI86867

  • Reported component name

    DB2 OS/390 & Z/

  • Reported component ID

    5740XYR00

  • Reported release

    B10

  • Status

    CLOSED UR1

  • PE

    NoPE

  • HIPER

    NoHIPER

  • Special Attention

    NoSpecatt / Xsystem

  • Submitted date

    2017-09-05

  • Closed date

    2017-11-08

  • Last modified date

    2018-06-27

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

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

    PI86868 UI51795

Modules/Macros

  • DSNECP00 DSNECP08 DSNECP19 DSNECP29 DSNECP48
    DSNECP49 DSNECP54 DSNFCDIR DSNFTDIR DSNLCBFM DSNLDTI2 DSNLEDDA
    DSNLEDTM DSNLIINI DSNLIIN2 DSNLIRTR DSNLJACC DSNLJDG1 DSNLJDSC
    DSNLJDSN DSNLJECK DSNLJEMG DSNLJGUS DSNLJHPP DSNLJMUS DSNLJSSG
    DSNLJSSP DSNLJTIN DSNLJXUS DSNLQACT DSNLQCRP DSNLQCTL DSNLQDIS
    DSNLQINA DSNLSSST DSNLTDDF DSNLTSTR DSNLVVDB DSNLXGLM DSNLXRUW
    DSNTBAB  DSNTBAB2 DSNTBAP  DSNTBAPM DSNTBAP1 DSNTBAP2 DSNTBAR
    DSNTBAS2 DSNTBCM  DSNTBCM2 DSNTBCM5 DSNTBEPL DSNTBFR2 DSNTBMSG
    DSNTBRSD DSNTBSPL DSNTBTRG DSNTGEPL DSNWDFDI DSNXELX  DSNXEPP
    DSNXERT2 DSNXIANR DSNXIDPK DSNXIDRT DSNXIDTR DSNXISUB HDBBB10J
    

Publications Referenced
SC19405400 GC19406200      

Fix information

  • Fixed component name

    DB2 OS/390 & Z/

  • Fixed component ID

    5740XYR00

Applicable component levels

  • RB10 PSY UI51795

       UP17/11/29 P F711

Fix is available

  • Select the PTF appropriate for your component level. You will be required to sign in. Distribution on physical media is not available in all countries.



Document information

More support for: DB2 for z/OS

Software version: 11.0

Reference #: PI86867

Modified date: 27 June 2018


Translate this page: