IBM Support

PI86868: SERVICE UPDATE OF DB2 12 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 PI86867 for DB2 11 for z/OS.
    Multiple improvements to the RESTful services support in DB2
    are being delivered.
    DB2REST
    .
    If you use BMC Utilities, please install BMC Fix BUC1000 to
    avoid an BMC IVP Engine failure and to be able to use IBM DB2's
    NF Restful enhancement successfully.
    

Local fix

Problem summary

  • ****************************************************************
    * USERS AFFECTED:                                              *
    * All users of DB2 12 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:                                              *
    * Apply corrective PTF when available                          *
    ****************************************************************
    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

    PI86868

  • Reported component name

    DB2 OS/390 & Z/

  • Reported component ID

    5740XYR00

  • Reported release

    C10

  • 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-01-15

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

    PI86867

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

    UI51748

Modules/Macros

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

Fix information

  • Fixed component name

    DB2 OS/390 & Z/

  • Fixed component ID

    5740XYR00

Applicable component levels

  • RC10 PSY UI51748

       UP17/11/28 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: C10

Reference #: PI86868

Modified date: 15 January 2018


Translate this page: