get /dtcn
get /dtcn/{profileID}
get /dtcn/chngeany
post /dtcn/{profileID}
put /dtcn/{profileID}
delete /dtcn/{profileID}
get /ds/{dsnname}
post /ds/{dsnname}
put /ds/{dsnname}
delete /ds/{dsnname}
get /ds/{userId}
post /ds/{userId}
put /ds/{userId}
delete /ds/{userId}
{
"hostname": "lpar1.ibm.com",
"apiversion": "1.1",
"regions": [
{
"regionname": "S07CICPW",
"port": "27620",
"ssl": false
},
{
"regionname": "S07CICPY",
"port": "27640",
"ssl": false
}
]
}
application/json
application/xml
{
"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"
}
application/json
application/xml
application/json
application/xml
application/json
application/xml
application/json
application/xml
application/json
application/xml
application/json
application/xml
application/json
application/xml
{
"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" : "*"
}
}
DTSP Model
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 |
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
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 |
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.
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
{
"sesstype": "string",
"sessaddr": "string"
}
DTSP Get
{
"apiversion" : "string",
"datasetname" : "string",
"dlaydbg" : boolean,
"profilerecord" : {
"uuid" : "string",
"level" : "string",
"commandfile" : "string",
"trigger" : "string",
"preferencefile" : "string",
"promptlevel" : "string"
}
}
DTCN Create/Modify
{
"program": [
{
"loadname": "string",
"pgmname": "string"
}
],
"sessaddr": "string",
"sessport": "string",
"sesstype": "string",
"trigger": "string"
}
DTCN Get
{
"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"
}
The following table shows the status codes and reason phrases returned by the Debug Profile Service API.
Status code | Reason phrase | Explanation |
---|---|---|
OK | The DTCN profile manager completed the method (action) successfully. | |
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. | |
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. | |
OK | The DTSP profile was created successfully. | |
Profile_Created_OK | The DTCN profile manager successfully created a new profile. | |
Unsupported_Client_Version | A client version that is 2 or more levels higher or lower than the server version was specified. | |
Invalid_Client_Version | The syntax of the clientversion symbol is incorrect. | |
Invalid_Profile_Record_Number | Starting profile record number is incorrect. | |
No_Resource_Specified | No resources were specified in the HTTP request body. | |
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. | |
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. | |
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. | |
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. | |
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. | |
Site_Rules_Require_NetName_Specified | The HTTP request body does not specify a netname. The DTCN profile manager requires that you specify a netname. | |
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. | |
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. | |
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. | |
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. | |
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. | |
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. | |
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. | |
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. | |
Error_Parsing_XML_Doc | z/OS XML parser failed to parse the HTTP request. | |
Bad Request | The URI is invalid. | |
Session type required | The HTTP request body does not specify the "sesstype" name. | |
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. | |
Required region name missing | A CICS region name is not specified in a query parameter in the HTTP URI. | |
User name and password missing | The HTTP Authorization request header does not specify the username and password. | |
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. | |
CICS_Default_Userid_Not_Allowed | The CICS default user ID can not be used to access profiles. | |
Create_Not_Allowed_By_Non_Owner | Only the owner of a profile can create a profile with the same user ID. | |
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. | |
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. | |
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. | |
CICS_Error | There was an error in the CICS region. | |
Dtcn_Manager_Received_Invalid_Function | The DTCN profile manager had internal error. | |
Unknown_Return_Code_Error | The DTCN profile manager had internal error. | |
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. | |
Region region name not available | The CICS region is either offline, or the DTCN TCPIPSERVICE port is not set up. | |
The Remote Debug Service is unavailable | The service is either offline, or there was an error retrieving the configuration information. | |
DEBUGTOOL_System_Setting_Is_On | The CICS DEBUGTOOL system setting is on. Turn it off to use the DTCN profile manager. |