Debug Profile Service

Debug Profile Service is an API that provides RESTful access to the management of debug profiles.
Ensure that Debug Profile Service has been installed and configured before you start to use this API.

Version: 1.3
BasePath:/api/v1/profile

Access

Methods

[ Jump to Models ]

Table of Contents

DTCN Profile

DTSP Profile

DTCN Profile

Up 
get /dtcn
Retrieves CICS regions or up to 10 profiles from the repository (listProfiles)
Retrieve a list of CICS regions running in the LPAR.
Optional: specify the region to retrieve a list of DTCN profiles defined in the region.

Query parameters

region (optional)
Query Parameter — The region to query for profiles.

Return type

DTCN GET RESPONSE

Example data

Content-Type: application/json
{
    "hostname": "lpar1.ibm.com",
    "apiversion": "1.1",
    "regions": [
        {
            "regionname": "S07CICPW",
            "port": "27620",
            "ssl": false
        },
        {
            "regionname": "S07CICPY",
            "port": "27640",
            "ssl": false
        }
    ]
}

Produces

This API call produces the following media types according to the Accept request header; the media type will be conveyed by the Content-Type response header.

HTTP Responses

Up 
get /dtcn/{profileID}
Retrieves the DTCN profile in the specified region. (listProfile)
Retrieve a DTCN profile in the specified region.

Path parameters

profileID (required)
Path Parameter — Profile that needs to be retrieved.

Query parameters

region (required)
Query Parameter — The region to query for profiles.

Return type

DTCN GET RESPONSE

Example data

Content-Type: application/json
{
  "apiversion" : "1.1",
  "ciscregionname" : "S07CICPW",
  "cicstslevel" : "050400",
  "clientversion" : "0104",
  "message" : "OK",
  "profilerecord" : [
    {
      "activation" : "I",
      "commandfile" : "*",
      "level" : "ALL",
      "preferencefile" : "*",
      "profileid" : "TESTUSER",
      "program" : [
        {
          "pgmname" : "COBSUB",
          "loadname" : "COBPGM"
        }
      ],
      "promptlevel" : "PROMPT",
      "sessaddr" : "localhost",
      "sessport" : "8001",
      "sesstype" : "TCP",
      "trigger" : "TEST",
      "urmdeb" : "N",
      "uuid": "53fd3db1-5045-446c-8392-b8405d605590"
    }
  ],
  "profileversion" : "0103",
  "serviceversion" : "0103",
  "serviceid" : "DBGTPROF"
}

Produces

This API call produces the following media types according to the Accept request header; the media type will be conveyed by the Content-Type response header.

HTTP Responses

Up 
get /dtcn/chngeany
Check permission
Check whether the user ID has authority to update or delete another user's profile.

HTTP Responses

Up 
post /dtcn/{profileID}
Create a new debug profile (addProfile)
Create a new profile with the information in the HTTP request body. In the URI, you must provide the profile ID and the region. In the HTTP request body, you must provide all the profile information in a well-formed JSON document. In the HTTP response body, the API returns a JSON document that contains control information (for example, a message and the server version).

Path parameters

profileID (required)
Path Parameter — New profile that needs to be added to the repository.

Consumes

This API call consumes the following media types via the Content-Type request header:

Request body

body DTCN Create/Modify Profile (required)
Body Parameter — Profile that needs to be added to the repository

Query parameters

region (required)
Query Parameter — The region the profile belongs to.

Produces

This API call produces the following media types according to the Accept request header; the media type will be conveyed by the Content-Type response header.

HTTP Responses

Up 
put /dtcn/{profileID}
Update an existing debug profile (updateProfile)
Modify a specific profile with the information in the HTTP request body. In the URI, you must provide the profile ID and the region. In the HTTP request body, you must provide all the profile information in a well-formed JSON document. In the HTTP response body, the API returns a JSON document that contains control information (for example, a message and the server version).

Path parameters

profileID (required)
Path Parameter — Profile that needs to be updated in the repository.

Consumes

This API call consumes the following media types via the Content-Type request header:

Request body

body DTCN Create/Modify Profile (required)
Body Parameter — Profile that needs to be updated in the repository

Query parameters

region (required)
Query Parameter — The region the profile belongs to.

Produces

This API call produces the following media types according to the Accept request header; the media type will be conveyed by the Content-Type response header.

HTTP Responses

Up 
delete /dtcn/{profileID}
Delete an existing debug profile (deleteProfile)
Delete a specific profile associated with a CICS region. In the URI, you must provide the profile ID and the region name.

Path parameters

profileID (required)
Path Parameter — User ID of profile owner

Consumes

This API call consumes the following media types via the Content-Type request header:

Query parameters

region (required)
Query Parameter — Region Name

Produces

This API call produces the following media types according to the Accept request header; the media type will be conveyed by the Content-Type response header.

HTTP Responses

DTSP Profile

Up 
get /ds/{dsnname}
Retrieve profile from existing EQAUOPTS data set. (dsDsnnameGet)
Retrieve profile from existing EQAUOPTS data set.

Path parameters

dsnname (required)
Path Parameter — Data set name.

Return type

DTSP GET RESPONSE

Example data

Content-Type: application/json
{
  "apiversion" : "1.1",
  "datasetname" : "TESTUSER.TEMP.EQUAOPTS",
  "dlaydbg" : true,
  "profilerecord" : {
    "uuid": "1070b6ab-3b42-4c9b-bb52-4ef18982a59b",
    "trigger" : "NOTEST",
    "level" : "ERROR",
    "commandfile" : "*",
    "promptlevel" : "PROMPT",
    "sesstype": "TCPIP",
    "sessaddr": "localhost",
    "preferencefile" : "*"
  }
}

HTTP Responses

Up 
post /ds/{dsnname}
Create new EQAUOPTS data set. (dsDsnnamePost)
Create new EQAUOPTS data set.

Path parameters

dsnname (required)
Path Parameter — Data set name.

Request body

body DTSP Create/Modify Profile (required)
Body Parameter — Profile that needs to be created.

HTTP Responses

Up 
put /ds/{dsnname}
Update existing EQAUOPTS data set. (dsDsnnamePut)
Update existing EQAUOPTS data set.

Path parameters

dsnname (required)
Path Parameter — Data set name.

Request body

body DTSP Create/Modify Profile (required)
Body Parameter — Profile that needs to be update.

HTTP Responses

Up 
delete /ds/{dsnname}
Delete existing EQAUOPTS data set. (dsDsnnameDelete)
Delete existing EQAUOPTS data set.

Path parameters

dsnname (required)
Path Parameter — Data set name.

HTTP Responses

Up 
get /ds/{userId}
Retrieve profile from existing default EQAUOPTS data set owned by userid. (dsUserIdGet)
Retrieve profile from existing default EQAUOPTS data set owned by userid.

Path parameters

userid (required)
Path Parameter — User id that owns the profile.

Return type

DTSP GET RESPONSE

HTTP Responses

Up 
post /ds/{userId}
Create profile in default EQAUOPTS data set owned by userid. (dsUserIdPost)
Create profile in default EQAUOPTS data set owned by userid.

Path parameters

userid (required)
Path Parameter — User id that owns the profile.

Request body

body DTSP Create/Modify Profile (required)
Body Parameter — Profile that needs to be created.

HTTP Responses

Up 
put /ds/{userId}
Update existing profile in default EQAUOPTS data set owned by userid. (dsUserIdPut)
Update existing profile in default EQAUOPTS data set owned by userid.

Path parameters

userid (required)
Path Parameter — User id that owns the profile.

Request body

body DTSP Create/Modify Profile (required)
Body Parameter — Profile that needs to be updated.

HTTP Responses

Up 
delete /ds/{userId}
Delete existing EQAUOPTS data set owned by userid. (dsUserIdDelete)
Delete existing EQAUOPTS data set owned by userid.

Path parameters

userid (required)
Path Parameter — User id that owns the profile.

HTTP Responses

Models

[ Jump to Methods ]

Table of Contents

  1. DTSP Model
  2. DTCN Model
  3. DTSP Create/Modify
  4. DTSP GET Response
  5. DTCN Create/Modify
  6. DTCN GET Response

DTSP Model

DTSP Model

Up

Definition of JSON names and how they map to TAG names in EQAUOPTS file

Output only header names:

Name Type Sample Value Description
apiversion variable string 1.1 Debug Profile Service API version
datasetname variable string USER1.DBGTOOLS.EQAUOPTS EQAUOPTS data set name
dlaydbg boolean false Indicate whether the profile is a delay debug profile
profile variable string see "profile data" below Profile information

Names in the profile data:

Name Type Valid/Sample Values Usage Default EQAUOPTS <TAG> Description
uuid string 1070b6ab-3b42-4c9b-bb52-4ef18982a59b Optional null <UID> An universally unique identifier (UUID) used to identify the profile
program list of "program record" see "program record" below optional null <PGM> or <NM2> for dlaydbg A list of up to 8 load modules/program names to be debugged
jobname string MYJOB Optional null <JBN> The job name of the batch job where you want to debug your application; it may contain a wild card character (*) at the end
stepname string RUN Optional null <STN> The step name of the batch job where you want to debug your application; it may contain a wild card character (*) at the end
imssubsystemid string IMSSYS1 Optional null <IID> The subsystem identifier of the IMS region where you want to debug your application
imstransactionid list of string IMSTRAN1 Optional null <ITR> The list of transaction identifiers of the applications that you want to debug
trigger string TEST, NOTEST Optional TEST part of <TST> To turn on or off debugging capabilities in your program
level string ALL, ERROR, NONE Optional ALL part of <TST> Conditions required for the z/OS Debugger to gain control
commandfile string USER1.TEST.COMMANDS Optional * part of <TST> The name of a file that contains a set of z/OS Debugger commands to control the debug session
promptlevel string PROMPT, NOPROMPT Optional PROMPT part of <TST> A prompt level that indicates whether z/OS Debugger is invoked at LE initialization. It can also contain commands
sesstype string TCPIP, MFI, VTAM, DBM, DBMDT, RDS Required N/A part of <TST> The method the end user wants to use to interact with z/OS Debugger [1]
sessaddr string 9.30.60.200 Depends on sesstype null part of <TST> The terminal ID or IP address of the device running your application
sessport string 8001 Optional 8001 part of <TST> TCP/IP port number of the device running your application
preferencefile string USER1.TEST.PREFFILE Optional null part of <TST> Name of a file containing a set of z/OS Debugger commands that customize the debug session
otheropts string STROAGE(00,00,00) Optional null part of <RTO> Additional LE run time options needed to run the application that the end user wants to debug
envar string EQA_STARTUP_KEY=CC Optional null part of <RTO> Environment variables needed to run the application that the end user wants to debug
eqaoptsfile string USER1.EQAOPTS.DATA Optional null <EQO> Name of a file containing a set of EQAOPTS commands to set the initial environment for the debug session

[1] For usage examples of the various sesstype options, see Example: TEST runtime options.

Example:

{
    "apiversion": "1.1",
    "datasetname": "TESTUSER.DBGTOOL.EQAUOPTS",
    "dlaydbg": false,
    "profile": {
      "uuid": "1070b6ab-3b42-4c9b-bb52-4ef18982a59b",
      "program": [
          {
              "pgmname": "HELLO1"
          },
          {
              "pgmname": "HELLO2"
          },
          {
              "pgmname": "HELLO3"
          },
          {
              "pgmname": "HELLO4"
          },
          {
              "pgmname": "HELLO5"
          },
          {
              "pgmname": "HELLO6"
          },
          {
              "pgmname": "HEHHO7"
          },
          {
              "pgmname": "HELLO8"
          }
      ],
      "jobname": "MYJOB",
      "stepname": "MYRUN",
      "imssubsystemid": "IMSA",
      "imstransactionid": [
          "IMSTRAN1",
          "IMSTRAN2",
          "IMSTRAN3"
      ],
      "trigger": "TEST",
      "level": "ALL",
      "commandfile": "*",
      "promptlevel": "PROMPT",
      "sesstype": "MFI",
      "sessaddr": "NETNAME.LUNAME",
      "preferencefile": "*",
      "otheropts": " STOR(00,00,00)",
      "eqaoptsfile": "USER1.EQAOPTS"
    }
  }
DTCN Model

DTCN Model

Up

Definition of JSON names for a DTCN profile

Output only header names:

Name Max Length(bytes) Sample Value Description
apiversion variable 1.1 Debug Profile Service API Version
profileversion 4 0103 DTCN API Version used to create profile
servieid 8 DBGTPROF ID returned by the DTCN API
clientversion 4 0104 Version of the running client
serverversion 4 0103 Version of the running DTCN API
cicsregionname 8 S07CICPY The name of the CICS region
profilecount 2 5 Number of profiles in the "profilerecord" return by GET list
startprofilerecord 4 1 The number specified in the ?s= query parameter of the GET list URI
message 60 Invalid_Client_Version An informational or error message returned by the DTCN API
cicstslevel 6 050400 The CICS Version
profilerecord variable see "profile record" below A list of one or more profile records

Names in the profile record:

Name Max length (bytes) Valid/Sample Values Usage Default Description
profileid 8 USER1 Output only N/A ID for a profile whose data is in the HTTP response body
activation 1 A, I Optional I Status of the profile
program variable see "program record" below Optional null A list of up to 8 load modules/program names to be debugged
transactionid 4 TRN1 Optional null ID of the CICS transaction that starts the application that the end user wants to debug
terminalid 4 TRM1 Optional null ID of the CICS terminal running the application that the end user wants to debug
userid 8 USER1 Optional null The ID of the user that runs the transaction the end user wants to debug
netname 8 CICSNET1 Optional null The name of a logical unit in the VTAM network
clientip 60 9.30.60.1 Optional null The IP name or address that starts the CICS application that the end user wants to debug
commareaoffset 8 X'AC' Optional null A numeric, in character string or hexadecimal format, that represents an offset of data in a commarea passed to the program the end user wants to debug when that program is invoked
commareadata 60 x'C1C2C3' Optional null A data pattern, in character string or hexadecimal format, compared against a commarea passed to the program the end user wants to debug when that program is invoked. If the data pattern in the commarea and other specified resources match, that program is debugged
containername 16 INPUTCNT Optional null Name of the container within the current channel passed to the program the end user wants to debug when that program is invoked
containeroffset 8 X'12C' Optional null A numeric, in character string or hexadecimal format, that represents an offset of data in the named container within the current channel passed to the program the end user wants to debug when that program is invoked
containerdata 60 X'C1C2C3' Optional null A data pattern, in character string or hexadecimal format, compared to a container within the current channel passed to the program the end user wants to debug when that program is invoked. If the data patter in the container and other specified resources match, that program is debugged
urmdeb 1 Y, N Optional N A flag to indicate whether the end user wants to debug URMs during his debugging session
trigger 8 TEST, NOTEST Optional TEST Indicates whether to start z/OS Debugger when the application that the end user wants to debug is initialized
level 8 ALL, ERROR, NONE Optional ALL Conditions required for the z/OS Debugger to gain control
sesstype 4 TCP, MFI, DBM, DBMDT, DIRECT, RDS Optional TCP The method the end user wants to use to interact with z/OS Debugger [2]
sessaddr 60 9.30.60.200 Required if sesstype is TCP N/A The terminal ID or IP address of the device running your application
sessport 8 8005 Optional 8001 TCP/IP port number of the device running your application
commandfile 80 USER1.TEST.COMMANDSTEST Optional * The name of a file that contains a set of z/OS Debugger commands to control the debug session
preferencefile 80 USER1.TEST.PREFFILE Optional * Name of a file containing a set of z/OS Debugger commands that customize the debug session
promptlevel 80 PROMPT, NOPROMPT Optional PROMPT A prompt level that indicates whether z/OS Debugger is invoked at LE initialization. It can also contain commands
otheropts 80 STORAGE(00,00,00) Optional null Additional LE run time options needed to run the application that the end user wants to debug
eqaoptsfile 54 USER1.EQAOPTS.DATA Optional blank Name of a file containing a set of EQAOPTS commands to set the initial environment for the debug session
pmapplication 64 Optional null The name of the application associated with the task. Available since CICS TS 5.2, it is part of the application context that is made up of the application name, the platform name, the operation name, and the major.minor.micro version number of the application
pmplatform Optional null The name of the platform associated with the task, which is part of the application context
pmoperation 64 Optional null The name of the operation associated with the task, which is part of the application context
pmappvermaj 8 09 Optional null The major version of the application associated with the task
pmappvermin 8 01 Optional null The major version of the application associated with the task
pmappvermic 8 01 Optional null The major version of the application associated with the task
pmsysid 4 Optional null The name given to the local CICS system
uuid 36 53fd3db1-5045-446c-8392-b8405d605590 Optional null An universally unique identifier (UUID) used to identify the profile

[2] For usage examples of the various sesstype options, see Example: TEST runtime options.

Names in the program record:

Name Max length (bytes) Sample value Usage Default Description
loadname 8 APP1LMD1 Optional null The name of the load module that the user wants to debug
pgmname 8 APP1PGM1 Optional null The name of the compile unit the user wants to debug

Example:

{
  "apiversion": "string",
  "profileversion": "string",
  "serviceid": "string",
  "clientversion": "string",
  "serverversion": "string",
  "cicsregionname": "string",
  "cicstslevel": "string",
  "profilerecord": [
      {
          "profileid": "string",
          "activation": "string",
          "program": [
              {
                  "loadname": "string",
                  "pgmname": "string"
              },
              {
                  "loadname": "string",
                  "pgmname": "string"
              }
          ],
          "transactionid": "string",
          "terminalid": "string",
          "userid": "string",
          "netname": "string",
          "clientip": "string",
          "commareaoffset": "string",
          "containeroffset": "string",
          "urmdeb": "string",
          "trigger": "string",
          "level": "string",
          "sesstype": "string",
          "sessaddr": "string",
          "sessport": "string",
          "commandfile": "string",
          "preferencefile": "string",
          "promptlevel": "string"
      }
  ]
  }

DTSP Create/Modify

DTSP Create/Modify

Up

{
      "sesstype": "string",
      "sessaddr": "string"
    }
  

DTSP Get

DTSP Get

Up

{
      "apiversion" : "string",
      "datasetname" : "string",
      "dlaydbg" : boolean,
      "profilerecord" : {
        "uuid" : "string",
        "level" : "string",
        "commandfile" : "string",
        "trigger" : "string",
        "preferencefile" : "string",
        "promptlevel" : "string"
      }
    }

DTCN Create/Modify

DTCN Create/Modify

Up

{
      "program": [
        {
          "loadname": "string",
          "pgmname": "string"
        }
      ],
      "sessaddr": "string",
      "sessport": "string",
      "sesstype": "string",
      "trigger": "string"
    }
  

DTCN Get

DTCN Get

Up

{
      "apiversion" : "string",
      "ciscregionname" : "string",
      "cicstslevel" : "string",
      "clientversion" : "string",
      "message" : "string",
      "profilerecord" : [
        {
          "activation" : "string",
          "commandfile" : "string",
          "level" : "string",
          "preferencefile" : "string",
          "profileid" : "string",
          "promptlevel" : "string",
          "sessaddr" : "string",
          "sessport" : "string",
          "sesstype" : "string",
          "trigger" : "string",
          "program" : [
            {
              "pgmname" : "string",
              "loadname" : "string"
            },
            {
              "pgmname" : "string",
              "loadname" : "string"
            }
          ],
          "urmdeb" : "string"
        }
      ],
      "profileversion" : "string",
      "serviceversion" : "string",
      "serviceid" : "string"
    }

HTTP Responses

The following table shows the status codes and reason phrases returned by the Debug Profile Service API.

Status code Reason phrase Explanation
200
 OK The DTCN profile manager completed the method (action) successfully.
200
 Profile_Already_Exists_With_Identical_Resources A POST request was sent specifying resources that are already used by another profile in the DTCN profile repository. The DTCN profile manager did not create a new profile.
200
 Profile_Already_Exists_With_Same_Owner A POST request was sent specifying a profile ID that is already used by another profile in the DTCN profile repository. The DTCN profile manager did not create a new profile.
201
 OK The DTSP profile was created successfully.
201
 Profile_Created_OK The DTCN profile manager successfully created a new profile.
400
 Unsupported_Client_Version A client version that is 2 or more levels higher or lower than the server version was specified.
400
 Invalid_Client_Version The syntax of the clientversion symbol is incorrect.
400
 Invalid_Profile_Record_Number Starting profile record number is incorrect.
400
 No_Resource_Specified No resources were specified in the HTTP request body.
400
 Site_Rules_Require_Terminal_ID_Specified The HTTP request body does not specify a terminal ID. The DTCN profile manager requires that you specify a terminal ID.
400
 Site_Rules_Require_Transaction_ID_Specified The HTTP request body does not specify a transaction ID. The DTCN profile manager requires that you specify a transaction ID.
400
 Site_Rules_Require_At_Least_One_Load_Mod_Name_Specified The HTTP request body does not specify the name of a load module. The DTCN profile manager requires that you specify the name of at least one load module.
400
 Site_Rules_Require_At_Least_One_Program_Name_Specified The HTTP request body does not specify the name of a compile unit. The DTCN profile manager requires that you specify the name of at least one compile unit.
400
 Site_Rules_Require_User_ID_Specified The HTTP request body does not specify a user ID. The DTCN profile manager requires that you specify a user ID.
400
 Site_Rules_Require_NetName_Specified The HTTP request body does not specify a netname. The DTCN profile manager requires that you specify a netname.
400
 Site_Rules_Require_Client_IP_Specified The HTTP request body does not specify the IP address of the client. The DTCN profile manager requires that you specify the IP address of the client.
400
 Invalid_Session_Address For a PUT or POST request, the HTTP request body is missing the "sessaddr" name or a value in the "sessaddr" name, which is required if you specify TCP in the "sessiontype" name.
400
 Invalid_Session_Type The HTTP request body specifies a value for the "sesstype" name that is invalid. MFI or TCP are the only valid values for the "sesstype" name.
400
 Invalid_Session_Port The HTTP request body specifies a value for the "sessport" name that is not numeric or specifies a port number when the session type is MFI. A port number is used only when the session type is TCP.
400
 Invalid_UrmDeb_Flag The HTTP request body specifies a value for "urmdeb" name that is invalid. Y or N are the only valid values for the "urmdeb" name.
400
 Invalid_Activation_Flag The HTTP request body specifies a value for the "activation" name that is invalid. A or I are the only valid values for the "activation" name.
400
 Invalid_Trigger The HTTP request body specifies a value for the "trigger" name that is invalid. TEST or NOTEST are the only valid values for the "trigger" name.
400
 Invalid_Test_Level The HTTP request body specifies a value for the "level" name that is invalid. The only valid values for the "level" name are ALL, ERROR, or NONE.
400
 Error_Parsing_XML_Doc z/OS XML parser failed to parse the HTTP request.
400
 Bad Request The URI is invalid.
400
 Session type required The HTTP request body does not specify the "sesstype" name.
400
 Profile data set already exists or is in use Either the DTSP profile data set already exists for a POST request, or the dataset is in use for a PUT request.
400
 Required region name missing A CICS region name is not specified in a query parameter in the HTTP URI.
401
 User name and password missing The HTTP Authorization request header does not specify the username and password.
401
 No_Write_Access_For_Unauthorized_User The user ID specified in the "userid" name is not authorized (through RACF®) to update or delete another user's profile.
401
 CICS_Default_Userid_Not_Allowed The CICS default user ID can not be used to access profiles.
401
 Create_Not_Allowed_By_Non_Owner Only the owner of a profile can create a profile with the same user ID.
403
 No response is received, probably because the required RACF authority is missing. Ensure the BPX.SRV.** SURROGAT profile is defined, and the user ID STCEQA is given READ permission to it.
404
 Data set not in catalog or catalog can not be accessed. For the GET, PUT, or DELETE request of a DTSP profile, the EQAUOPTS data set either does not exist or is not in a catalog.
404
 Profile_Not_Found For the GET, POST, or DELETE request, the DTCN profile manager did not find a profile with the specified profile (user) ID.
500
 CICS_Error There was an error in the CICS region.
500
 Dtcn_Manager_Received_Invalid_Function The DTCN profile manager had internal error.
500
 Unknown_Return_Code_Error The DTCN profile manager had internal error.
500
 The dtcn.ports file or TCP/IP service resource is misconfigured. Also, this could occur in case the CICS region is offline. Ensure the configuration is correct, and the CICS region is online.
503
 Region region name not available The CICS region is either offline, or the DTCN TCPIPSERVICE port is not set up.
503
 The Remote Debug Service is unavailable The service is either offline, or there was an error retrieving the configuration information.
503
 DEBUGTOOL_System_Setting_Is_On The CICS DEBUGTOOL system setting is on. Turn it off to use the DTCN profile manager.