A fix is available
APAR status
Closed as new function.
Error description
Extended API and EXEC DL/I interface support for API function of IPR Unload.
Local fix
Problem summary
**************************************************************** * USERS AFFECTED: All users of IPR Unload utility of IMS * * Parallel Reorganization for z/OS Version 2 * * Release 1 (FMID=H25N210). * **************************************************************** * PROBLEM DESCRIPTION: The call types supported by application * * programming interface (API) for IPR * * Unload Utility is extended by this * * maintenance. Two new control statements * * APISET and PCBLIST are introduced. * * Application programming interface (API) * * for IPR Unload Utility supported an * * EXEC DLI command interface for an HSSR * * call. * **************************************************************** * RECOMMENDATION: Apply the maintenance for this APAR. * **************************************************************** The call types supported by application programming interface for IPR Unload Utility is extended by this maintenance. Application programming interface (API) for IPR Unload Utility supported an EXEC DLI command interface for an HSSR call. *==========================* * Summary of New Functions * *==========================* 1. APISET control statement is introduced and the supported call types can be extended by specifying the control statement. - APISET 1 is the default and is compatible with the existing API. The API is extended to support GNP and GHNP calls without SSA or GNP command without SEGMENT options. - APISET 2 is an extension of APISET 1. In APISET 2, the following call types, in addition to the call types supported in APISET 1, are supported for HD and partitioned HD databases: GN, GHN, GNP, and GHNP calls with an unqualified SSA that contains the name of a dependent segment type or GN and GNP commands with a SEGMENT option. - APISET 3 is an extension of APISET 2. In APISET 3, almost all types of DL/I Get calls are supported. If a call of a type that is not supported in APISET 2 is issued, the succeeding calls are processed by DL/I call handler, not by HSSR Engine. 2. PCBLIST control statement is introduced. You can specify whether the DBT HSSR-compatible PCB list or the IMS PCB list is passed to the application program. For details, see the documentation change in the COMMENTS section of this APAR.
Problem conclusion
Temporary fix
Comments
======================== = DOCUMENTATION CHANGE = ======================== IMS Parallel Reorganization for z/OS Version 2 Release 1 User's Guide (Document Number: SC27-1180-02) should be changed as follows. - The changes in following Chapters are included in this APAR: Chapter 3. IPR Unload Utility Chapter 6. Setting Installation Default Options Appendix A. Application Programming Interface A.1.2 Preparing and Running Application Program A.1.2.4a Call Types Supported by Each API SET - The changes in following Chapters are included in APAR PQ80267: Appendix A. Application Programming Interface A.1.2 Preparing and Running Application Program A.1.2.4b EXEC DLI Command Types Supported by Each API SET A.1.4 PCB feedback Information Appendix F. Messages and Codes * Chapter 3.IPR Unload Utility 3.7 JCL Requirements 3.7.2 DD Statements DFSVSAMP DD Describes the data set ... ... Otherwise, a larger number of region size is required to run the IPR Unload utility. | You should, however, specify DL/I buffers in DFSVSAMP in the | following cases: | - When you specify BLDLPCK=YES in the HPSIN data set. This | is because a DL/I call is issued internally to build an | LPCK in that case. | - When APISET=3 is specified in the HPSIN data set or by | the site default option table. In this case, if a call | that is not supported in APISET=2 is issued, that call | and all succeeding calls are passed to DL/I and are | processed by DL/I action modules. | The usual DFSVSAMP definitions should be used in tuning | the processing of these internal DL/I calls. 3.8 Control Statements 3.8.4 Control Statements for HSSR Engine 3.8.4.1 BLDLPCK Control Statement The following item is added to Notes: | 6. If APISET=3 is specified, the BLDLPCK statement is | ignored and the BLDLPCK=YES is always assumed. 3.8.4.4 BYINDEX Control Statement The following Note is added: | Note: If APISET=3 is specified, this statement cannot be | specified. 3.8.4.5 COMPAREDLI Control Statement : Notes: | 1. If COMPAREDLI=YES is specified, the database data sets | must be allocated with DISP=SHR. | 2. If APISET=3 is specified, the comparison is not done for | the calls that are finally processed by DL/I. 3.8.4.7 DBSTATS Control Statement The following Note is added: | Note: If APISET=3 is specified, this statement cannot be | specified. 3.8.4.9 KEYCHECK Control Statement : GG Performs key checking ... ... If the SKIPERROR control statement is inactive, HSSR Engine resets the current position to the beginning of the database. | For the EXEC DLI command, the status 'GX' is not returned | to the application program. Instead, message DFS1041 is | issued in the EXEC DLI interface module (DFSEIPB0). It | ends with a code of U1041. GX Performs key checking and returns a warning GX status code if a sequence error is detected. The segment with the incorrect key is returned to the IPR Unload utility. | Note: If APISET=3 is specified, this statement cannot be | specified. 3.8.4.12 SKIPERROR Control Statement The following Note is added: | Note: If APISET=3 is specified, this statement cannot be | specified. 3.8.4.13 TRACE Control Statement <_,________________ _,1_ >>__TRACE=___ _CALL_ ______ __ |__|____|______________>< | |_,NPF_| | |_,n_| |_CB_____________| | |_CBX____________| |_BUF____________| |_BUFCB__________| The TRACE statement ... ... If this control statement is not specified, the trace information is not generated at all. CALL Traces such call information as the call function, PCB, IOAREA, SSA, and segment prefix. You can optionally specify NPF keyword after the keyword CALL to exclude the segment prefix information from the call trace. | Does a trace for the EXEC DLI command, just the same as for | the DL/I call. This is because the command is converted to | the format of a DL/I call and made to the HSSR call handler. NPF Excludes the segment prefix information from the call trace. This keyword, if specified, must be specified just after the keyword CALL. | CB or CBX | Traces control blocks of HSSR Engine. If CBX is specified, | traces are also done for the extended control blocks of HSSR | Engine. | If both CB and CBX are specified, CBX is taken. BUF Traces I/O buffers. : Note: | 1. All operands are optional, but you must specify at least one operand. | 2. The trace of the control blocks of HSSR Engine (which | is called for by specifying the CB, CBX, BUF, or BUFCB | option for the TRACE control statement) is not intended | to be reviewed by users, but might be needed by the IBM | Support Center to analyze a problem. Chapter 6.Setting Installation Default Options 6.2 Creating an Installation Default Option Table (HPSCOPTI) : Defaults for the following options can be changed by creating an HPSCOPTI: - DECODEDBD option for IPR Driver : - PARTINFO option for IPR Unload | - APISET option for API Function of IPR Unload | - PCBLIST option for API Function of IPR Unload - DECODEDBD option for IPR Reload - PARTINFO option for IPR Reload 6.4 How to Code HPSCOPT Macro Statements The installation default options ... ... The general syntax of the HPSCOPT macro statement is as follows: | >>__HPSCOPT=___START______________________________________>< | |_END____________________________________| | |_DRIVER_,_| A |_,_| B |_________________| | |_UNLOAD_,_| C |_,_| D |_,_| E |_,_| F |_| | |_RELOAD_,_| C |_,_| D |_________________| A: |_DECODEDBD=_(___NO____,___NO____)_________________| |_YES_| |_YES_| : D: |_PARTINFO=____YES_________________________________| |_NO_| | E: |_APISET=____1_____________________________________| | |_2_| | |_3_| | F: |_PCBLIST=____HSSR_________________________________| | |_IMS__| | : The first positional parameter ... ... The default values for the following control statements can be specified: - DECODEDBD for IPR Driver : - PARTINFO for IPR Unload | - APISET option for API Function of IPR Unload | - PCBLIST option for API Function of IPR Unload - DECODEDBD for IPR Reload - PARTINFO for IPR Reload Appendix A. Application Programming Interface A.1 API for IPR Unload A.1.1 Overview : A batch DL/I application program ... ... A buffer pool is allocated by HSSR Engine for each data set group of the database for which the HSSR PCB is used. Each | DL/I call or EXEC DLI command to the HSSR PCB (called an HSSR call) is processed by HSSR Engine. If the PCB is not an HSSR PCB, HSSR Call Router passes control to the DL/I program request handler. A.1.1.1 Application Program That Can Benefit from HSSR Engine Not every IMS application program ... ... | HSSR Engine is optimized for GN and GNP calls with unqualified segment search argument(SSA) call. Unless you | issue several GN or GNP calls for each GU call, do not run your application program by using the IPR Unload Utility. | Note: If APISET=2 is specified, a GN or GNP call with an | unqualified SSA that contains the name of a dependent | segment type can be processed by HSSR Engine. If | APISET=3 is specified, you can issue other types of | DL/I calls. But if HSSR Call Analyzer encounters a | DL/I call that is not supported by APISET=2, that | call and all succeeding calls are processed by DL/I, | not by HSSR Engine. IBM recommends that you use | APISET=1 or 2 for application programs running on IPR | Unload Utility and that, if your application program | issues a call not supported by APISET=2, you use | native IMS instead. A.1.2 Preparing and Running Application Program A.1.2.2 Preparing a PSB To run an HSSR application program in the DLI or DBB region, you must prepare a PSB. In the PSB, at least one HSSR-eligible PCB, explained later in this appendix, must be coded. Only the HSSR-eligible PCB can be specified as an HSSR PCB. | An HSSR PCB is a PCB, the DL/I call or EXEC DLI command to which is processed by HSSR Engine. An HSSR PCB is specified by the PCB and the PCBNAME control statements. : | A.1.2.3 Coding DL/I Calls or EXEC DLI command for HSSR PCB | An HSSR call is a DL/I call or an EXEC DLI command that is issued against an HSSR PCB. Each HSSR call is processed by HSSR Engine. | The HSSR call is issued through the DL/I language interface, | but the call is transferred to the HSSR Call Analyzer. The | call is finally processed by either HSSR Call Handler or | DL/I, depending on the type of the call and the API set | specified. You can specify an API set by making it the site | default or by including an APISET control statement in the | HPSIN DD statement. | For details, see "APISET Control Statement" in topic A.1.7.1 | and "Setting Installation Default Options" in topic 6.0. | A.1.2.4a Call Types Supported by Each API Set | IPR Unload Utility supports three API sets. APISET=1 is the | system default. The following table shows the DL/I call | types supported by each API set, and their effects with and | without segment search arguments (SSAs): | +-----------------------------------------------------------+ | | Table 38a. DL/I Call Types Supported by Each API Set | | +----------+------------------------------------------------+ | | API Set | Call Types Supported | | +----------+------------------------------------------------+ | | APISET=1 | The following call types are supported: | | | | - GU and GHU calls without SSA: the first root | | | | segment of the database is retrieved. | | | | - GU and GHU calls with an SSA that is | | | | qualified on the root sequence key: either a | | | | specific root segment or the first root | | | | segment with a key greater than or equal to | | | | the key specified in the SSA, is retrieved. | | | | - GN and GHN calls without SSAs. | | | | - GN and GHN calls with an unqualified SSA that| | | | contains the name of a root segment type. | | | | - GNP and GHNP calls without SSAs. | | +----------+------------------------------------------------+ | | APISET=2 | The following call types are supported for HD | | | | and partitioned HD databases in addition to | | | | the call types supported in APISET=1: | | | | - GN and GHN calls with an unqualified SSA | | | | that contains the name of a dependent segment| | | | type. | | | | - GNP and GHNP calls with an unqualified SSA | | | | that contains the name of a dependent | | | | segment type. | | +----------+------------------------------------------------+ | | APISET=3 | Calls of types GU, GHU, GN, GHN, GNP, and GNHP | | | | are all supported. | | +-----------------------------------------------------------+
APAR Information
APAR number
PQ79142
Reported component name
IMS PARALLEL RE
Reported component ID
5655F7400
Reported release
210
Status
CLOSED UR1
PE
NoPE
HIPER
NoHIPER
Special Attention
NoSpecatt / Xsystem
Submitted date
2003-10-02
Closed date
2003-11-05
Last modified date
2003-12-03
APAR is sysrouted FROM one or more of the following:
APAR is sysrouted TO one or more of the following:
UQ81856
Modules/Macros
HPSCOPT HPSCOPTD HPSCOPTS
| SC27118002 |
Fix information
Fixed component name
IMS PARALLEL RE
Fixed component ID
5655F7400
Applicable component levels
R210 PSY UQ81856
UP03/11/16 P F311
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":"BU058","label":"IBM Infrastructure w\/TPS"},"Product":{"code":"SSVL5Q","label":"IMS Database Reorganization Expert for z\/OS"},"Component":"","ARM Category":[],"Platform":[{"code":"PF025","label":"Platform Independent"}],"Version":"210","Edition":"","Line of Business":{"code":"LOB35","label":"Mainframe SW"}}]
Document Information
Modified date:
06 January 2023