TAGTEST: PACKAGE; %INCLUDE DTADKPLI; MAIN: PROC OPTIONS(MAIN); /* This program demonstrates dynaTrace CICS ADK APIs. */ /* One group of APIs contains functions for starting and * ending a Purepath for the transaction and associated tagging * functions. A newer group of APIs permits nodes to be inserted * into a Purepath that is already in progress and to capture * its arguments or return value. The two groups of APIs are * unrelated, but they can be used within the same transaction. */ /* Optional name to describe the initial path. */ DCL PATHNAME CHAR(100) VARYING INIT('Started from tagging ADK'); /* Buffer to hold the tag that will identify a child path. * Note: DynaTrace 5.x requires a buffer of at least 77 bytes. */ DCL TAG_BUFFER CHAR(100) VARYING; DCL TAG_BUFFER_LEN FIXED BIN(31) INIT(100); DCL TERM_MSG CHAR(22) STATIC INIT('PL/I TAGTEST Complete.'); DCL RC FIXED BIN(31); DCL 1 ERROR_MSG, 5 MSG_API CHAR(8), 5 MSG_TEXT CHAR(16) INIT("API returned RC "), 5 MSG_RC PIC'SSS9'; DCL FROM FIXED BIN(15) INIT(1); DCL TO FIXED BIN(15) INIT(10); DCL S FIXED BIN(15); /* ----------------------------------------------------------------* * Start an initial path for this transaction. * * The first parameter is a varying PLI string, * The second parameter is its code page. * Zero indicates the default code page of the CICS region. * ----------------------------------------------------------------*/ /* ----------------------------------------------------------------* * Note that a transaction that receives a tag from a program * running on another platform should start a linked path instead * so it can set a tag. For an example, see subroutine SUB1 * below. * ----------------------------------------------------------------*/ RC = DTSPTP(PATHNAME, 0); IF RC <> 0 THEN DO; MSG_API = "DTSPTP"; MSG_RC = RC; EXEC CICS WRITE OPERATOR TEXT(ERROR_MSG); END; /* ----------------------------------------------------------------* * Note: * Any activity that occurs in this transaction between a start * path or start linked path API and the next DTEP API will be * associated with the started path. Optionally, insert link APIs * can be used to create tags to represent subpaths for children * of this transaction. The CICS agent automatically tags CICS * transactions started by DPL LINK or START requests made by any * traced transaction, so insert link is typically used to tag * service requests made to programs running on non-CICS platforms. * ----------------------------------------------------------------*/ /* ----------------------------------------------------------------* * Insert a link for a child path to trace a service request to a * program that will run on another platform. The tag length must * be initialized to the size of the buffer to hold the tag that * will be returned. * ----------------------------------------------------------------*/ RC = DTILTP(TAG_BUFFER, TAG_BUFFER_LEN); IF RC <> 0 THEN DO; MSG_API = "DTILTP"; MSG_RC = RC; EXEC CICS WRITE OPERATOR TEXT(ERROR_MSG); END; /* ----------------------------------------------------------------* * Note: * Pass the tag that was obtained above to the service to identify * the path that it will set to report its activity. * ----------------------------------------------------------------*/ /* ----------------------------------------------------------------* * End the initial path early because one transaction can't be * linked to two paths at once. Normally this API would be used * when the transaction is finished or when it wants to start * another path to trace a new unit of work. * ----------------------------------------------------------------*/ RC = DTEP(); IF RC <> 0 THEN DO; MSG_API = "DTEP"; MSG_RC = RC; EXEC CICS WRITE OPERATOR TEXT(ERROR_MSG); END; /* ----------------------------------------------------------------* * To avoid the inconvenience of defining additional transactions * and programs, we will call an embedded subroutine here instead * of making a request to an external service. * ----------------------------------------------------------------*/ /* ----------------------------------------------------------------* * Perform some calculations * ----------------------------------------------------------------*/ S = SUM(TAG_BUFFER); /* ----------------------------------------------------------------* * Send a message to the terminal and return to CICS. * ----------------------------------------------------------------*/ EXEC CICS SEND TEXT FROM(TERM_MSG) ERASE; EXEC CICS RETURN; END MAIN; SUM: PROCEDURE(TAG) RETURNS(BIN FIXED(15)); DCL (M, N) FIXED BIN(15); DCL TAG CHAR(100) VARYING; DCL R FIXED BIN; DCL RC FIXED BIN(31); DCL NODENAME CHAR(8) VARYING INIT("TESTPROG"); DCL ARGUMENT CHAR(6) VARYING INIT("Hello."); DCL TOKEN FIXED BIN(31); DCL 1 ERROR_MSG, 5 MSG_API CHAR(8), 5 MSG_TEXT CHAR(16) INIT("API returned RC "), 5 MSG_RC PIC'SSS9'; /* ----------------------------------------------------------------* * Start the linked path. If your CICS transaction receives a * dynaTrace tag from another platform, a DTSLP* API is all that * is required to trace the transaction and any other CICS * transactions that it starts through a supported protocol. * ----------------------------------------------------------------*/ RC = DTSLPTP(TAG); IF RC <> 0 THEN DO; MSG_API = "DTSLPTP"; MSG_RC = RC; EXEC CICS WRITE OPERATOR TEXT(ERROR_MSG); END; /* ----------------------------------------------------------------* * Simulate calling another program by inserting another node * into the Purepath here. A Data Capture API is used to specify * a string argument. Note that these functions are unrelated * to the tagging functions that are also being demonstrated * elsewhere in this program. * * The token value must be retained and supplied on the matching * Exit API. If nested nodes are created, each will have its own * token and the most recent one must be exited first. * * Start by capturing an argument for the simulated program node. * ----------------------------------------------------------------*/ RC = DTDCTP(ARGUMENT, 0); IF RC <> 0 THEN DO; MSG_API = "DTDCTP"; MSG_RC = RC; EXEC CICS WRITE OPERATOR TEXT(ERROR_MSG); END; /* ----------------------------------------------------------------* * Enter the simulated program. * ----------------------------------------------------------------*/ RC = DTENTP(NODENAME, TOKEN); IF RC <> 0 THEN DO; MSG_API = "DTENTP"; MSG_RC = RC; EXEC CICS WRITE OPERATOR TEXT(ERROR_MSG); END; /* ----------------------------------------------------------------* * The application work associated with this program goes here. * ----------------------------------------------------------------*/ R = 8; /* ----------------------------------------------------------------* * End the program node that we added with a return code 8. * * Start by capturing the return value. * ----------------------------------------------------------------*/ RC = DTDCS(R); IF RC <> 0 THEN DO; MSG_API = "DTDCS"; MSG_RC = RC; EXEC CICS WRITE OPERATOR TEXT(ERROR_MSG); END; /* ----------------------------------------------------------------* * Exit from the simulated program using the token from the most * recent Enter API. * ----------------------------------------------------------------*/ RC = DTEX(TOKEN); IF RC <> 0 THEN DO; MSG_API = "DTEX"; MSG_RC = RC; EXEC CICS WRITE OPERATOR TEXT(ERROR_MSG); END; /* ----------------------------------------------------------------* * End the linked path before returning. * ----------------------------------------------------------------*/ RC = DTEP(); IF RC <> 0 THEN DO; MSG_API = "DTEP"; MSG_RC = RC; EXEC CICS WRITE OPERATOR TEXT(ERROR_MSG); END; RETURN(R); END SUM;