Defining Db2 to IMS

To define Db2 to IMS, the Db2 identification must be defined to the control region and the DL/I batch region. Optionally, you can also define the Db2 identification to each dependent region that accesses the Db2 subsystem.

Procedure

To define Db2 to IMS:

  1. Name an SSM member in IMS.PROCLIB by concatenating the value of the IMSID field of the IMS IMSCTRL macro (one to four alphanumeric characters) with any name (one to four alphanumeric characters) defined by your site.

    Each SSM entry in IMS.PROCLIB defines at least one connection from an IMS region to at least one different z/OS® subsystem. One SSM member can be shared by all of the IMS regions, or a specific member can be defined for each region. This record contains as many entries as there are connections to external subsystems. Each entry is an 80-character blocked or deblocked record. Fields are keyword or positional and are delimited by commas. The fields in this record are:

    SST=,SSN=,LIT=,ESMT=,RTT=,REO=,CRC=,RLA=
    SST=,SSN=,LIT=,ESMT=,RTT=,REO=,CRC=

    where:

    SST=DB2
    Identifies a required one-to eight-character name that defines the external subsystem type. It must be set to DB2 for IMS to connect to Db2.
    SSN=
    Identifies a required one-to four-character Db2 subsystem name. This name must be the name you specified for SUBSYSTEM NAME on installation panel DSNTIPM. The default is DSN1.
    LIT=
    Identifies a required four-character alphanumeric option, specifying the language interface token (LIT) supplied to IMS. The IMS-supplied language interface module (DFSLI000) requires a value of SYS1 for this option.
    ESMT=
    Identifies a required one-to eight-character alphanumeric option specifying the external subsystem module table. This module specifies which attachment modules must be loaded by IMS. DSNMIN10 is the required value for this field.
    RTT=
    Identifies an optional one to eight character alphanumeric name of the user-generated resource translation table (RTT). This table maps the IMS application names into Db2 plan names. If this entry is omitted, the Db2 plan name is the IMS application load module name.
    REO=
    Identifies the optional one-character region error option to be used if an IMS application attempts to reference a non-operational external subsystem or if resources are unavailable at create thread time. If Db2 detects the unavailable resource condition during normal SQL processing, a -904 SQLCODE is returned to the application.
    R
    Passes a SQL return code to the application, indicating that the request for Db2 services failed (default). The most commonly returned SQL codes are -922, -923, and -924. However, there might be other SQL codes returned to the application.

    When the first connection to Db2 cannot be established, a SQL return code is not returned. Instead, the application is terminated with an abend code U3047.

    Q
    Abends the application with an abend code U3051, backs out activity to the last commit point, does a PSTOP of the transaction, and re-queues the input message. This option only applies when an IMS application attempts to reference a non-operational external subsystem or if the resources are unavailable at create thread time. If Db2 detects the unavailable resource condition during normal SQL processing, a -904 SQLCODE is returned to the application.
    A
    Abends the application with an abend code of U3047 and discards the input message. This option only applies when an IMS application attempts to reference a non-operational external subsystem or if the resources are unavailable at create thread time. If Db2 detects the unavailable resource condition during normal SQL processing, a -904 SQLCODE is returned to the application.

    If Db2 is not active or the connection cannot be established when the first SQL call is made from the application program (such as Db2 unavailable, Db2 quiescing, or Db2 terminating), the action you take depends on the region error option specified. SQL codes of -922, -923, or -924 might be returned to the application if option R is specified.

    You can change the default for an application if a resource translation table entry is generated for that application.

    CRC=
    Identifies a command recognition character used by IMS to identify Db2 commands entered from an IMS terminal with the /SSR command. Any character is valid for the CRC except the period (.), slash (/), or comma (,). The default CRC is the hyphen (-).
    RLA=
    Start of changeIdentifies whether the Region Level ACEE (RLA) must be passed to Db2 for the following operations when no ESAF_SIGNON_ACEE is present and no TCB level ACEE is present:
    • External subsystem (ESS) signon
    • ESS create thread exit processing
    • ESS associate thread exit processing

    Using RLA=Y for all IMS dependent region types reduces accessor environment element (ACEE) creation and management overhead because the region level ACEE is created only once and then is available for future use. Specifying RLA=Y is similar to using ESAF_SIGNON_ACEE, which applies only to IMS JVM dependent regions. By default, the region-level ACEE is not passed to Db2. The RLA= parameter accepts the following values:

    N
    Do not pass the dependent region address space level ACEE to Db2.
    Y
    Pass the dependent region address space level ACEE to Db2 if no ESAF_SIGNON_ACEE is present and no TCB level ACEE is present.
    End of change

    These options apply to DL/I batch only:

    CONNECTION_NAME=
    Represents the name of the job step that is the coordinator for Db2 activity. The connection name is optional. The connection name defaults are:
    Table 1. Default connection names for DL/I batch
    Type of Application Default Connection Name
    Batch job Job name
    Started task Started task name
    TSO user TSO authorization ID
    If a batch job fails, you must use a separate job to restart the batch job. The connection name used in the restart job must be the same as the name used in the batch job that failed. Or, if the default connection name is used, the restart job must have the same job name as the batch update job that failed.

    Db2 requires unique connection names for Db2 DL/I batch support. If two applications try to connect with the same connection name, then the second application is not allowed to connect to Db2. CONNECTION_NAME can be 1 to 8 characters long.

    PLAN=
    Identifies a Db2 plan name. If you do not specify a plan name, the application program module name is checked against the optional resource translation table. If a match is found, the translated name is used as the Db2 plan name. If no match is found, the application program module name is used as the plan name. PLAN can be 1-8 characters long.
    Important: If you use the External Subsystem Attach Facility (ESAF) and the IBM Data Server Driver for JDBC and SQLJ to connect to a Db2 subsystem, a set of JDBC driver packages with a collection name that matches the application program module name (PSB name) must exist. If no packages with a matching collection name exist, you need to bind a set of driver packages with the -collection parameter value set to the application program module name. See DB2Binder utility for information on binding JDBC driver packages.
    PROG=
    Identifies the name of the application program that is to be loaded and to receive control. PROG is required and can be 1-8 characters long.
  2. Provide support for entering Db2 commands through IMS by defining the command recognition character (CRC) in the SSM member of the IMS control region. If the /SSR command is entered through the z/OS console, the AUTHID WTOR needs to be granted the appropriate authority. If the /SSR command is entered through an IMS terminal, the IMS LTERM name or the signon ID (if active) needs to be granted the appropriate authority.
    The /SSR command format is:
     /SSR crc DB2 command
    as in
     /SSR -DISPLAY THREAD (*)
  3. Specify the SSM EXEC parameter in the startup procedure of the IMS control, MPP, BMP, or DL/I batch region. The SSM is concatenated with the IMSID to form a member name in IMS.PROCLIB. The IMSID comes from the IMSID option of the IMSCTRL generation macro or the IMSID option in the control region startup procedure.

    For DL/I batch regions, you can specify the Db2 connection parameters in the DDITV02 data set instead of an SSM member. The DDITV02 data set and an SSM member have the same format.

    If you specify the SSM for the IMS control region, any dependent region running under the control region can attach to the Db2 subsystem named in the IMS.PROCLIB member specified by the SSM parameter. The IMS.PROCLIB member name is the IMS ID (IMSID=xxxx) concatenated with the one to four characters specified in the SSM EXEC parameter. The IMS ID is the IMSID parameter of the IMSCTRL generation macro.

    IMS allows you to define as many external subsystem connections as are required. More than one connection can be defined for different Db2 subsystems. All Db2 connections must be within the same z/OS system. For a dependent region, you can specify a dependent region SSM or use the one specified for the control region. You can specify different region error options (REOs) in the dependent region SSM member and the control region SSM member. The following table shows the different possibilities of SSM specifications.

    Table 2. SSM specifications options
    SSM for Control Region SSM for Dependent Region Action Comments
    No No None No external subsystem can be connected
    No Yes None No external subsystem can be connected.
    Yes No Use the control region SSM Applications scheduled in the region can access external subsystems identified in the control region SSM. Exits and control blocks for each attachment are loaded into the control region address space.
    Yes Yes (NULL entry) No SSM is used for the dependent region Applications scheduled in this region can access DL/I databases only. Exits and control blocks for each attachment are loaded into the control region address space and each dependent region address space.
    Yes Yes Check the dependent region SSM with the control region SSM. Applications scheduled in this region can access only external subsystems identified in both SSMs. Exits and control blocks for each attachment are loaded into the control region and the dependent region address space.

    No specific parameter exists to control the maximum number of SSM specification possibilities.