A fix is available
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:
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.
[{"Business Unit":{"code":"BU059","label":"IBM Software w\/o TPS"},"Product":{"code":"SSEPEK","label":"Db2 for z\/OS"},"Component":"","ARM Category":[],"Platform":[{"code":"PF025","label":"Platform Independent"}],"Version":"12.0","Edition":"","Line of Business":{"code":"LOB10","label":"Data and AI"}},{"Business Unit":{"code":"BU054","label":"Systems w\/TPS"},"Product":{"code":"SG19M","label":"APARs - z\/OS environment"},"Component":"","ARM Category":[],"Platform":[{"code":"PF025","label":"Platform Independent"}],"Version":"12.0","Edition":"","Line of Business":{"code":"","label":""}}]
Document Information
Modified date:
15 January 2018