dtcn.ports, the Debug Profile Service CICS DTCN configuration file

A sample of dtcn.ports is as follows:
#*********************************************************************#
# Licensed Materials - Property of IBM                                #
#                                                                     #
# 5724-T07: IBM z/OS Debugger                                         #
# Copyright IBM Corp. 2025, 2025 All Rights Reserved                  #
#                                                                     #
# US Government Users Restricted Rights - Use, duplication or         #
# disclosure restricted by GSA ADP Schedule Contract with IBM Corp.   #
#                                                                     #
# Background:                                                         #
#                                                                     #
# The dtcn.ports configuration file is used by the Debug Profile      #
# Service (DPS) API as a lookup table. It defines the connection      #
# parameters that tell DPS how to connect to CICS regions in order    #
# to manage DTCN profiles.                                            #
#                                                                     #
# DPS API supports two integration options. Both provide the same     #
# outcome by establishing internal communication between DPS API and  #
# CICS regions.                                                       #
#                                                                     #
# 1) TCPIPSERVICE - This option requires the CICS system programmer   #
#                   to define and install CICS TCPIPSERVICE           #
#                   definitions in their CICS regions. These          #
#                   definitions are provided by z/OS Debugger. They   #
#                   enable the DTCN API, a REST service that manages  #
#                   DTCN profiles within the CICS region. Each region #
#                   must have its own DTCN API installed and          #
#                   configured with a unique TCP/IP port number. The  #
#                   dtcn.ports file is then used to define            #
#                   region/port mappings for all regions where the    #
#                   DTCN API is installed.                            #
#                                                                     #
# 2) EXCI        -  This option requires the CICS system programmer   #
#                   to define and install CICS EXCI definitions in    #
#                   their CICS regions. These definitions are         #
#                   provided by z/OS Debugger. The EXCI interface is  #
#                   an internal communication mechanism that allows   #
#                   non-CICS programs in MVS to call programs running #
#                   in a CICS region. This enables DPS API to manage  #
#                   DTCN profiles as if it were the DTCN program in   #
#                   the CICS region. Each region must have EXCI       #
#                   definitions installed and be configured with a    #
#                   unique APPLID, as defined in the system           #
#                   initialization (SIT) parameters. The dtcn.ports   #
#                   file is then used to define region/APPLID mappings#
#                   for all regions where EXCI is installed.          #
#                                                                     #
# Both integration options enable DPS API to server as the single     #
# point of entry for managing DTCN profiles across CICS regions.      #
#                                                                     #
# Note(s):                                                            #
#                                                                     #
# 1) For more information on how to set up the CICS TCPIPSERVICE or   #
#    EXCI, see "Defining the CICS TCPIPSERVICE resource" and          #
#    "Defining the CICS EXCI CONNECTION and SESSIONS resources"       #
#    in the IBM z/OS Debugger Customization Guide (SC27-9583)         #
#                                                                     #
# FORMAT:                                                             #
#                                                                     #
# <region>:<port>[,HOST=<hostname>][,APPLID=<applid>][,XCFGROUP=<xcf>]#
#                                                                     #
# <region>           : The identifier for the CICS region to be used  #
#                      for managing DTCN profiles. This is the name   #
#                      that UI clients see when selecting a CICS      #
#                      region. It may be an alias or the actual CICS  #
#                      region name. DPS API uses this value only as   #
#                      a lookup key.                                  #
#                                                                     #
# <port>             : The TCP/IP port number, or -1 to indicate EXCI.#
#                                                                     #
# [,HOST=<hostname>] : (Optional) The hostname that DPS API uses to   #
#                      establish the TCP/IP connection. If omitted,   #
#                      it defaults to the local system DNS `hostname` #
#                                                                     #
# [,APPLID=<applid>] : (Optional) The CICS APPLID associated with the #
#                      region. If omitted, it defaults to the         #
#                      <region> value.                                #
#                                                                     #
# [,XCFGROUP=<xcf>] :  (Optional) The CICS XCFGROUP associated with   #
#                      the region. If omitted, it defaults to         #
#                      DFHIR000 value.                                #
#                                                                     #
# CAUTIONS:                                                           #
#                                                                     #
# Using TCPIPSERVICE:                                                 #
#   - All TCP/IP port numbers must be unique within the z/OS image.   #
#   - Both <region> and <port> must be specified.                     #
#   - The HOST option is optional. If not provided, DPS API defaults  #
#     to DNS `hostname` of the z/OS image where it is running.        #
#     You can verify the default `hostname` by checking the server    #
#     output stream (default EQAPROF:STDOUT) near the top for the     #
#     'local host' log entry.                                         #
#   - The following options are not applicable when using TCPIPSERVICE#
#     and will be ignored:                                            #
#      - APPLID                                                       #
#      - XCFGROUP                                                     #
#                                                                     #
# Using EXCI:                                                         #
#   - Each CICS APPLID must be unique.                                #
#   - Both <region> and <port> must be specified. For EXCI, the <port>#
#     must be set to -1, which directs DPS API to use the EXCI        #
#     interface.                                                      #
#   - The APPLID option is optional. If omitted, it defaults to the   #
#     <region> value. Whether defaulted or specified, the value must  #
#     match the APPLID defined in the CICS SIT parameters.            #
#   - The XCFGROUP option is optional. If omitted, it defaults to     #
#     DFHIR000. Whether defaulted or specified, the value must        #
#     match the XCFGROUP defined in the CICS SIT parameters.          #
#     If provided, it must meet the following criteria:               #
#       - Valid characters: A to Z, 0 to 9, $, #, @.                  #
#       - Must not start with: A to C, E to I, or SYS.                #
#       - Must not be equal to UNDESIG.                               #
#   - The following options are not applicable when using EXCI        #
#     and will be ignored:                                            #
#      - HOST                                                         #
#                                                                     #
#*********************************************************************#
#
# For example, 
#
# The '#' symbol is used here for comments. When defining actual
# entries in the dtcn.ports file, do NOT include the '#'. Each entry
# must be on its own line. Spaces are optional but not required.
#
# CSYS01:6000
# CSYS02:6001
# CSYS03:6002,HOST=127.1.2.3
# CSYS04:6003,HOST=tempCICShost11.test.ibm.com
# CSYS05:-1
# CSYS06:-1,APPLID=CSYS06
# CSYS07:-1,APPLID=CICS07
# CSYS08:-1,APPLID=CICS08,XCFGROUP=DFHIRS08

CICS TCPIPSERVICE

When you use the DTCN API via TCPIPSERVICE, provide the port number where it listens within the CICS region.

Example A
If DTCN API is configured to run on CICS01 and accept HTTP requests on port 8001, the following entry associates region CICS01 with port 8001 on the local host. In this case, local host means DPS API and CICS01 are running on the same LPAR.
CICS01:8001
Example B
If the local hostname is not desired or not publicly resolvable, override the hostname that Debug Profile Service (DPS) API uses to communicate with DTCN API. For example:
CICS01:8001,HOST=newhostname
This entry tells DPS API to connect to DTCN API for region CICS01 at port 8001 on host newhostname, which may be located on the same LPAR or a different one.
Example C
You can use an alias instead of the actual CICS region name. The alias serves as an identifier (or key) for the port and host.
CICS01X:8001,HOST=newhostname
In this case, CICS01X maps to the actual CICS region CICS01.
Example D
If DTCN API is configured to run on CICS regions across separate LPARs, explicitly define the entries that tell DPS API how to connect to each one. For example:
CICS0193:8001,HOST=lpar93.hostname
CICS0194:8001,HOST=lpar94.hostname
CICSPLX2:8001,HOST=vipa.hostname
These entries inform DPS API that a DTCN API instance runs on LPAR93 and LPAR94, each listening for incoming requests on port 8001 within their respective CICS regions, both named CICS01. To differentiate between them, the configuration defines unique aliases (for example, CICS0193, CICS0194) that incorporate the LPAR identifier and corresponding host for each target system. If a VIPA is available to route the connection, a separate alias can be defined using the VIPA hostname (for example, CICSPLEX2), which automatically resolves to either LPAR93 or LPAR94 based on routing rules.

CICS EXCI

When you use EXCI to manage DTCN profiles, specify the APPLID as defined in the APPLID system initialization (SIT) parameter of the target CICS region with a port value of -1. This instructs DPS API to use the EXCI interface to connect to the target CICS region.

Example A
If the EXCI interface is configured in a CICS region named CICS01 with APPLID CSYS01, the following entry defines the APPLID with port value of -1.This tells DPS API to use the EXCI interface to connect to the CICS region with APPLID CSYS01:
CSYS01:-1
Example B
You can use an alias instead of the actual CICS region name. The alias serves as an identifier (or key) for the APPLID.
CICS01X:-1,APPLID=CSYS01
In this case, CICS01X maps to the CICS region with APPLID CSYS01.