Use the CICS and IMS SDK for custom tracing

The CICS and IMS SDK supports customer-specific distributed tracing that uses either standard Dynatrace tags or customer-supplied custom tags.

The CICS and IMS SDK also provides APIs that let you add nodes to an existing PurePath® distributed trace and associate arguments and return values with them. Each API returns 0 to indicate success or another integer value, positive or negative, to indicate failure. See the list of return codes below.

Link the stub

DTSTUB provides access to SDK functions. Add a DD statement and an INCLUDE to the binder step to include it in your program. For example:

//SZDTLOAD  DD  DISP=SHR,DSN=_hlq_.SZDTLOAD

...

  INCLUDE SZDTLOAD(DTSTUB)

Include API function declarations

#include <DTADK>

%INCLUDE DTADKPLI;

You can download and use these include and sample programs:

These sample programs with SDK API calls are also availabe in the <hlq>.SZDTSAMP product dataset.

API naming conventions

Each function name starts with DT, followed by characters that define the purpose of the function and an optional suffix that indicates the argument type.

DTaaaabb
^ ^   ^
| |   `- Parameter type:
| |       - 'TN'  text - null terminated string
| |       - 'TP'  text - PL/I string
| |       - 'TF'  text - fixed length string
| |       - 'A'   byte array
| |       - 'S'   16-bit signed integer
| |       - 'I'   32-bit signed integer
| |       - 'L'   64-bit signed integer
| |
| `-- Method type:
|      - 'SP'   Start PurePath distributed trace
|      - 'SLP'  Start linked PurePath distributed trace
|      - 'SCLP' Start linked PurePath distributed trace with custom tag
|      - 'IL'   Insert link
|      - 'ICL'  Insert link with custom tag
|      - 'IAL'  Insert asynchronous link
|      - 'IACL' Insert asynchronous link with custom tag
|      - 'EP'   End PurePath distributed trace
|      - 'EN'   Enter
|      - 'EX'   Exit
|      - 'EXEX' Exit with exception
|      - 'DC'   Data capture
|
  `---- 'DT' prefix

Start PurePath distributed trace

Starts a new CICS or IMS distributed trace that is unrelated to any existing distributed trace.

Note that CICS LINKs, CICS STARTs, and IMS program to program message switches initiated by the transaction being traced automatically create their own linked subpaths.

CALL "DTSP" RETURNING RC.
CALL "DTSPTF" USING FIXED_LEN_STRING, LENGTH, CCSID RETURNING RC.

rc = DTSP();
rc = DTSPTN(c_string, ccsid);
rc = DTSPTP(pli_string, ccsid);
rc = DTSPTF(fixed_len_string, length, ccsid);

int DTSP (void);
int DTSPTN (const char* c_string, const int* ccsid);
int DTSPTP (const void* pli_string, const int* ccsid);
int DTSPTF (const char* fixed_len_string, const int* length, const int* ccsid);

Parameters

Start linked PurePath distributed trace

Starts a CICS or IMS distributed trace that is a continuation of another PurePath, typically in response to an inbound service request from another platform.

Note that CICS LINKs, CICS STARTs, and IMS program to program message switches initiated by the transaction being traced automatically create their own linked subpaths.

CALL "DTSLPA" USING BINARYTAG, LENGTH RETURNING RC.
CALL "DTSCLPA" USING CUSTOMTAG, LENGTH RETURNING RC.
CALL "DTSLPTF" USING FIXED_LEN_STRING, LENGTH RETURNING RC.

rc = DTSLPA(binarytag, length);
rc = DTSCLPA(customtag, length);
rc = DTSLPTN(c_string);
rc = DTSLPTP(pli_string);
rc = DTSLPTF(fixed_len_string, length);

int DTSLPA (const void* binarytag, const int* length);
int DTSCLPA (const void* customtag, const int* length);
int DTSLPTN (const char* c_string);
int DTSLPTP (const void* pli_string);
int DTSLPTF (const char* fixed_len_string, const int* length, const int* ccsid);

Parameters

End PurePath distributed trace

Terminates the current distributed trace created by a Start PurePath distributed trace or Start Linked PurePath distributed trace API.

The End PurePath distributed trace API may not be required because the distributed trace ends automatically at the end of the transaction, or when another Start PurePath distributed trace or Start Linked PurePath distributed trace API is used in the same transaction to trace another input message. End PurePath distributed trace should be used before a long running transaction waits for another input message to arrive.

When used, End PurePath distributed trace must be issued by the same transaction that issued the Start PurePath distributed trace or Start Linked PurePath distributed trace, regardless of CICS LINKs, CICS STARTs, or IMS program to program message switches which create their own linked subpaths automatically, which are independent of the SDK.

CALL "DTEP" RETURNING RC.

rc = DTEP();

int DTEP (void);

Parameters

None

Insert link

Links the current distributed trace to another distributed trace, typically in response to an outbound request from the CICS or IMS application to a server on another platform.

The string or array used with these APIs returns a new tag that is sent with the outbound request, but DTICLA requires the caller to supply a custom tag.

CALL "DTILA" USING BINARYTAG, TAG_BUFFER_LEN RETURNING RC.
CALL "DTICLA" USING CUSTOMTAG, LENGTH RETURNING RC.
CALL "DTILTF" USING FIXED_LEN_STRING, TAG_BUFFER_LEN RETURNING RC.

rc = DTILA(binarytag, tag_buffer_len);
rc = DTICLA(customtag, length);
rc = DTILTN(c_string, tag_buffer_len);
rc = DTILTP(pli_string, tag_buffer_len);
rc = DTILTF(fixed_len_string, tag_buffer_len);

int DTILA (void* binarytag, int* tag_buffer_len);
int DTICLA (const void* customtag, const int* length);
int DTILTN (char* c_string, const int* tag_buffer_len);
int DTILTP (void* pli_string, const int* tag_buffer_len);
int DTILTF (char* fixed_len_string, int* tag_buffer_len);

Parameters

Insert asynchronous link

Links the current distributed trace to another distributed trace, typically in response to an outbound request from the CICS or IMS application to a server on another platform.

This feature is very similar to the Insert link with important difference that it inserts links for outbound requests that do not necessarily operate in a synchronous manner.

The string or array used with these APIs returns a new tag that is sent with the outbound request, but DTIACLA requires the caller to supply a custom tag.

CALL "DTIALA" USING BINARYTAG, TAG_BUFFER_LEN RETURNING RC.
CALL "DTIACLA" USING CUSTOMTAG, LENGTH RETURNING RC.
CALL "DTIALTF" USING FIXED_LEN_STRING, TAG_BUFFER_LEN RETURNING RC.

rc = DTIALA(binarytag, tag_buffer_len);
rc = DTIACLA(customtag, length);
rc = DTIALTN(c_string, tag_buffer_len);
rc = DTIALTP(pli_string, tag_buffer_len);
rc = DTIALTF(fixed_len_string, tag_buffer_len);

int DTIALA (void* binarytag, int* tag_buffer_len);
int DTIACLA (const void* customtag, const int* length);
int DTIALTN (char* c_string, const int* tag_buffer_len);
int DTIALTP (void* pli_string, const int* tag_buffer_len);
int DTIALTF (char* fixed_len_string, int* tag_buffer_len);

Parameters

Enter node

Adds a node to the currently active CICS or IMS subpath to indicate the execution start of a new program or activity.

The number of Exit node and Exit node with exception APIs must equal the number of Enter node APIs. Subpaths with unbalanced numbers of enter and exit APIs are marked as corrupted.

Typically, this API is used by the program calling the named program but it could also be issued at the beginning of the called program. The Enter node API returns a 32-but integer token that must be saved so it can be specified on the associated Exit node or Exit node with exception API.

CALL "DTENTF" USING FIXED_LEN_STRING, LENGTH, TOKEN RETURNING RC.

rc = DTENTN(c_string, token);
rc = DTENTP(pli_string, token);
rc = DTENTF(fixed_len_string, length, token);

int DTENTN (const char* c_string, int* token);
int DTENTP (const void* pli_string, int* token);
int DTENTF (const char* fixed_len_string, const int* length, int* token);

Parameters

Exit node

Indicates that the program or activity associated with the most recent Enter node API has ended.

Each Exit node or Exit node with exception API pairs with the most recent Enter node API. Subpaths with unbalanced numbers of enter and exit APIs are marked as corrupted.

Related Enter node and Exit node APIs should be issued by the same program in most cases. This is so an exit does not attempt to end a node associated with a program with its own node due to a LE call, CICS LINK, or IMS program to program message switch invoked since the most recent Enter node API.

''CALL "DTEX" USING TOKEN RETURNING RC.

rc = DTEX(token);

int DTEX (const int* token);

Parameters

Exit node with exception

Indicates that the program or activity associated with the most recent Enter node API ended with an error.

Each Exit node or Exit node with exception request pairs with the most recent Enter node request. Subpaths with unbalanced numbers of enter and exit APIs are marked as corrupted.

Related Enter node and Exit node APIs should be issued by the same program in most cases. This is so an exit does not attempt to end a node associated with a program with its own node due to a LE call, CICS LINK, or IMS program to program message switch invoked since the most recent Enter node API.

CALL "DTEXEX" USING TOKEN RETURNING RC.

rc = DTEXEX(token);

int DTEXEX (const int* token);

Parameters

Data capture

Provides an argument capture value for a subsequent Enter node API, or the return value for a subsequent Exit node or Exit node with exception API.

Multiple Data capture APIs may be issued before an Enter node API to capture entry arguments, but only one return value may be associated with an Exit node or Exit node with exception API.

An Enter node, Exit node, or Exit node with exception API should always immediately follow one or more Data capture APIs to prevent the captured value being unintentionally associated with another node.

CALL "DTDCS" USING INT16_VALUE RETURNING RC.
CALL "DTDCI" USING INT32_VALUE RETURNING RC.
CALL "DTDCL" USING INT64_VALUE RETURNING RC.
CALL "DTDCTF" USING FIXED_LEN_STRING, LENGTH, CCSID RETURNING RC.

rc = DTDCS(int16_value);
rc = DTDCI(int32_value);
rc = DTDCL(int64_value);
rc = DTDCTN(c_string, ccsid);
rc = DTDCTP(pli_string, ccsid);
rc = DTDCTF(fixed_len_string, length, ccsid);

int DTDCS (const short* int16_value);
int DTDCI (const int* int32_value);
int DTDCL (const long long* int64_value);
int DTDCTN (const char* c_string, const int* ccsid);
int DTDCTP (const void* pli_string, const int* ccsid);
int DTDCTF (const char* fixed_len_string, const int* length, const int* ccsid);

Parameters

API return codes

All APIs return an integer value.

Negative return codes

A negative return code generally indicates that the CICS or IMS instrumentation is not available, so the application program should continue on the assumption that tracing isn't being performed.

In a CICS environment, the CICS DFHRMCAL interface passes SDK requests to the CICS module's task related user exit (TRUE). DFHRMCAL returns undocumented negative values such as -2 if the CICS instrumentation is not active. If negative return codes are encountered, you can use the DTAX transaction to see whether the CICS instrumentation is enabled.

In an IMS environment, a negative return code also indicates that the IMS instrumentation is not available.

If the SDK returns negative return codes while other transactions in the affected dependent region are traced successfully, please contact a Dynatrace product expert via live chat within your Dynatrace environment.

API notes

The CICS and IMS SDK supports COBOL, PL/I, Assembler, and C/C++. PL/I and C provide include members that declare the API functions.

COBOL programs must specify a type such as PIC S9(9) that corresponds to a binary fullword for integer variables such as RC, LENGTH (not a valid COBOL variable name), CCSID, and TAG_BUFER_LEN. Array or string variables can be declared as PIC X(##).

All character string values assume the default EBCDIC code page of the CICS or IMS region unless the API accepts an explicit CCSID override.

The binary tag length is 30 bytes and a string tag may be up to 79 bytes. The tag_buffer_len specifying the area length to hold an output tag argument must be set as follows:

It is recommended that code that handles standard string tags should support tags that are significantly larger than the minimum sizes above to minimize compatibility issues with future extended tag formats.

Input string arguments other than tags are currently limited to a maximum length of 200 bytes. This limit does not include the two-byte length of a PLI varying string or the null terminator byte of a null-terminated string, just the text contents of the string.