CICS and IMS ADK

The CICS and IMS ADK supports customer-specific tagging that uses either standard AppMon tags or customer-supplied custom tags. AppMon 7.0 and later includes additional APIs that let you add nodes to an existing PurePath and associate arguments and return values with them. This ADK is part of the CICS and IMS Agents. It requires no additional license.

See Agent Development Kit (ADK) for general tagging information.

DTSTUB provides access to ADK 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 for C and PL/I

PL/I:

%INCLUDE DTADKPLI;

C or C++:

#include <DTADK>

See API Include and Sample Files (attachments) at the bottom of this page.

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 Path
 |      - 'SLP'  Start Linked Path
 |      - 'SCLP' Start Custom Linked Path
 |      - 'IL'   Insert Link
 |      - 'ICL'  Insert Custom Link
 |      - 'IAL'  Insert Async Link
 |      - 'IACL' Insert Async Custom Link
 |      - 'EP'   End Path
 |      - 'EN'   Enter
 |      - 'EX'   Exit
 |      - 'EXEX' Exit with Exception
 |      - 'DC'   Data Capture
 |
   `---- 'DT' prefix

API function examples for COBOL, PL/I and C

The API supports all common z/OS languages.

Each API call returns an integer value to indicate failure, or zero to indicate success. See the list of return codes below.

Start path

Start a new CICS or IMS PurePath that is unrelated to any existing PurePath.

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.

COBOL examples

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

PL/I examples

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

C function declarations

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

c_string Path name specified as a null-terminated string.
pli_string Path name specified as a PLI varying string.
fixed_len_string Path name specified as a fixed-length string with an explicit length.
length Length of the specified fixed-length string.
ccsid Coded character set identifier for the string. Specify a value of zero (0) to use the CICS or IMS region's default code page.

Start linked path

Start a CICS or IMS PurePath 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.

COBOL examples

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

PL/I examples

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

C function declarations

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

binarytag Standard AppMon binary tag specified as a byte array.
customtag Custom tag specified as a byte array.
c_string Standard AppMon string tag specified as a null-terminated string.
pli_string Standard AppMon string tag specified as a PLI varying string.
fixed_len_string Standard AppMon string tag specified as a fixed-length string with an explicit length.
length Length of the specified fixed-length string or byte array. Note that this is the length of the tag, not the buffer.

End path

Terminate the current PurePath created by a Start Path or Start Linked Path API call.

The End Path API may not be required because the PurePath ends automatically at the end of the transaction, or when another Start Path or Start Linked Path API is used in the same transaction to trace another input message. End Path should be used before a long running transaction waits for another input message to arrive. When used, End Path must be issued by the same transaction that issued the Start Path or Start Linked Path, 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 ADK.

COBOL example

CALL "DTEP" RETURNING RC.

PL/I example

rc = DTEP();

C function declaration

int DTEP (void);

Parameters

None

Link the current PurePath to another PurePath, 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 AppMon tag that is sent with the outbound request, but DTICLA requires the caller to supply a custom tag.

COBOL examples

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.

PL/I examples

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);

C function declarations

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

binarytag Standard AppMon binary tag returned as a byte array (output).
customtag Custom tag specified as a byte array (input).
c_string Standard AppMon string tag returned as a null-terminated string (output).
pli_string Standard AppMon string tag returned as a PLI varying string (output).
fixed_len_string Standard AppMon string tag returned as a fixed-length string with an explicit length (output).
length Length of the supplied byte array (input).
tag_buffer_len Length of the supplied buffer that is used to return the new  tag (input).

Also used as an output parameter by DTILA and DTILTF to return the actual length of the returned array or string.

Link the current PurePath to another PurePath, typically in response to an outbound request from the CICS or IMS application to a server on another platform. These APIs duplicate the Insert Link APIs, but also insert links for outbound requests that do not necessarily operate in a synchronous manner.

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

COBOL examples

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.

PL/I examples

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);

C function declarations

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

binarytag Standard AppMon binary tag returned as a byte array (output).
customtag Custom tag specified as a byte array (input).
c_string Standard AppMon string tag returned as a null-terminated string (output).
pli_string Standard AppMon string tag returned as a PLI varying string (output).
fixed_len_string Standard AppMon string tag returned as a fixed-length string with an explicit length (output).
length Length of the supplied byte array (input).
tag_buffer_len Length of the supplied buffer that returns the new tag (input). Also used as an output parameter by DTIALA and DTIALTF to return the actual length of the returned array or string.

Enter Node

Add 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 API calls must equal the number of Enter Node API calls or the Purepath is 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 API returns a 32-but integer token that must be saved so it can be specified on the associated Exit or Exit Exception API call.

COBOL examples

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

PL/I examples

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

C function declarations

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

c_string Program name specified as a null-terminated string.
pli_string Program name specified as a PLI varying string.
fixed_len_string Program name specified as a fixed-length string with an explicit length.
length Length of the specified fixed-length string.
token A 32-bit binary integer token used to associate this node with the corresponding Exit or Exit Exception (output).

Exit Node

Indicate that the program or activity associated with the most recent Enter Node API call has ended.

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.

COBOL example

CALL "DTEX" USING TOKEN RETURNING RC.

PL/I example

rc = DTEX(token);

C function declarations

int DTEX (const int* token);

Parameters

token The 32-bit integer token that was returned by the most recent DTEN API call.

Exit Node with Exception

Indicate that the program or activity associated with the most recent Enter Node API call 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.

COBOL example

CALL "DTEXEX" USING TOKEN RETURNING RC.

PL/I example

rc = DTEXEX(token);

C function declarations

int DTEXEX (const int* token);

Parameters

token The 32-bit integer token that was returned by the most recent DTEN API call.

Data Capture

Provide 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, but only one return value may be associated with an Exit Node or Exit Node with Exception API.

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

COBOL examples

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.

PL/I examples

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);

C function declarations

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

c_string Capture value specified as a null-terminated string.
pli_string Capture value specified as a PLI varying string.
fixed_len_string Capture value specified as a fixed-length string with an explicit length.
length Length of the specified fixed-length string.
ccsid Coded character set identifier for the string. Specify a value of zero (0) to use the CICS or IMS region's default code page.
int16_value A 16-bit signed binary value such as a COBOL PIC S9(5) COMP, PLI FIXED BIN 15. C short int, or assembler fullword.
int32_value A 32-bit signed binary value such as a COBOL PIC S9(9) COMP, PLI FIXED BIN 31. C int, or assembler fullword (F).
int64_value A 64-bit signed binary value such as a COBOL PIC S9(18) COMP, PLI FIXED BIN 63. C long long int, or assembler doubleword (FD).

API return codes

All APIs return an integer value.

Return Code API Types Action Description
0 All As documented Success
4 SP
SLP
SCLP
None A path is already in progress for this transaction.
4 DC
EN
EX
EXEX
EP
IL
ICL
IAL
IACL
None No path is in progress for this transaction at this time.
8 EP None A different sensor started the path that is in progress for this transaction.
8 SLP None The specified AppMon tag's format is invalid or the specified string length doesn't match the actual string tag length.
8 IL
IAL
None The supplied buffer is too small to hold the tag.
8 EX
EXEX
None The supplied token is not valid.
12 SP None The specified path name is too long.
12 SLP
SCLP
ICL
IACL
None The specified tag length is negative or too long.
12 DC None The specified capture string is too long (currently limited to 200 bytes).
12 EN None The specified node name is too long (currently limited to 8 bytes).
16 SLP None A dummy AppMon tag was specified.
2000 Any Correct calling program A program check occurred in the CICS or IMS agent while handling an ADK call. This is presumably caused by an incorrect argument.

Negative return codes

A negative return code generally indicates that the Agent 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 ADK requests to the CICS agent's task related user exit (TRUE). DFHRMCAL returns undocumented negative values such as -2 if the agent is not active. If negative return codes are encountered, you can use the DTAX transaction to see whether the Agent is enabled.

In an IMS environment, a negative return code also indicates that the AppMon IMS agent is not available. Return code -1 means the IMS agent is not installed in this IMS subsystem. Return code -4 means the IMS agent is installed but has been disabled. Return code -5 indicates that the installation process is not completed in this dependent region. Return code -5 is expected if the ADK starts a Purepath in the first transaction to execute after the message region starts or the IMS agent is enabled. Initialization may take a second or two, so this condition may occur for more than one transaction at startup.

Contact AppMon support if the ADK returns negative return codes when AppMon is actively tracing other transactions in the affected dependent region.

API notes

The CICS and IMS ADK 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 77 bytes. The tag_buffer_len specifiing the area length to hold an output tag argument must be set as follows:

  • DTILA and DTIALA API ‐ 30 or more.
  • DTILTF and DTIALTF API ‐ 77 or more.
  • DTILTN and DTIALTN API ‐ 78 or more to allow for a null terminator byte.
  • DTILTP and DTIALTP API ‐ 79 or more to allow for the halfword string length.

Use a buffer size somewhat larger than these minimum sizes to minimize compatibility issues with future AppMon releases.

Input string arguments 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.

API include and sample files