Defining the CICS® TCPIPSERVICE resource

Before your users can use the profile view or develop applications that use the APIs, you must define the CICS TCPIPSERVICE resource and add a URIMAP definition for every CICS® region that users access.

To aid with the configurations, use IBM z/OS Debugger CICS CSD Resource Definitions EQAW.SEQASAMP(EQACCSD) sample file, and submit sample job EQAW.SEQASAMP(EQAWCCSD) to create the TCPIPSERVICE and URIMAP definitions for every CICS regions. For more details, see Adding support for debugging under CICS. Debug Profile Service API can start to successfully communicate with the target CICS region, once step 1 and 2 are completed.

For more details, complete the following steps for every region that users access:

  1. Define the TCP/IP address and host name for the z/OS® system. By default, they are defined in the PROFILE.TCPIP and TCPIP.DATA data sets.
  2. Ensure the following CICS System initialization parameter are set for each CICS region:
    GRPLIST
    The group, defined in the service must be in the startup GRPLIST, so that the listener starts when CICS starts. For example, if EQAW.SEQASAMP(EQACCSD) group name is EQA and list name is EQALIST then EQALIST must be appended to GRPLIST=(DFHLIST,TIVLIST,EQALIST).
    SEC
    Change the SEC=YES for authentication support.
  3. Add a TCP/IP listener to CICS. Use the following CEDA command to define a TCPIPSERVICE in a group:
    CEDA DEF TCPIPSERVICE(service-name) GROUP(group-name)
    The following list explains what values to use for some of the key fields:
    TCpipservice(service-name)
    Create a name that is eight characters or less. For example, EQADTCN.
    GROup(group-name)
    Create a name that is eight characters or less. For example, EQA.
    Urm
    Specify EQADCAN0.
    POrtnumber
    Specify an unused port number that Debug Profile Service uses for the API's communication.
    To see the active port numbers used by CICS regions, run the following TSO command. Change #cicsname to the desired naming pattern: TSO NETSTAT CO (CLI #cicsname*.
    STatus
    Specify Open.
    PROtocol
    Specify Http.
    TRansaction
    Specify CWXN.
    Backlog
    The number of TCP/IP requests that are queued before TCP/IP starts to reject incoming requests. For example, 30.
    SOcketclose
    Specify No.
    Maxdatalen
    Specify the maximum size, in bytes, of the body (the XML document) of the HTTP request or response. For example, 032768 represents 32K bytes.
    SSl
    Specify Yes if you are using SSL encryption with the HTTPS protocol.
    AUthenticate
    Specify No because Debug Profile Service manages Basic and JWT authentications.
    GRPcritical
    Specify No.
  4. Add a URIMAP definition to match the URLs of the incoming HTTP requests:
    CEDA DEF URIMAP(map-name) GROUP(group-name)
    The following list explains what values to use for the key fields:
    URIMAP(map-name)
    Create a name that is eight characters or less. For example, EQAURIM.
    GROUP(group-name)
    Specify the same group-name as used in the TCPIPSERVICE resource definition.
    STATUS
    Specify Enabled.
    USAGE
    Specify Server.
    SCHEME
    Specify HTTP.
    HOST
    Specify *.
    PATH
    Specify /dtcn/*.
    ANALYZER
    Specify Yes.
  5. Verify TCPIPSERVICE(service-name) and URIMAP(map-name) are defined:
    CEDA DISPLAY GROUP(group-name)
  6. Verify the associated GRPLIST list-name is defined:
    CEDA DISPLAY LIST(list-name)
  7. Enter the following commands to install the TCPIPSERVICE and URIMAP definitions:
    CEDA INS TCPIPSERVICE(service-name) GROUP(group-name)
    CEDA INS URIMAP(map-name) GROUP(group-name)
  8. Restart the CICS region for the changes to take effect.
  9. Restart Debug Profile Service for the changes to take effect.
    • Ensure that the Debug Profile Service API dtcn.port configuration file is updated with the target CICS region name and port number that it is listening to.
  10. To verify the installation up to this point - login to the Profile Management web UI. The UI will attempt to query the target CICS region name. If no errors are reported, then Debug Profile Service was successful at querying a debug profile with CICS TCPIPSERVICE.
  11. If you encounter problems with the connection from the workstation to the HTTP server in the CICS region, issue the command on the CICS region to verify if your settings match the definitions.
    CEMT INQUIRE TCPIPSERVICE(service-name)
    CEMT INQUIRE URIMAP(map-name)
  12. Ask your system administrator to provide access to transactions CWBA and CWXN because they are used in the HTTP request processing.