The name of the calling program ("caller")
The name of the called function ("callee")
The time used by the called function.
The number of times the function was called.
-->
User's guide
DRA is a Profile tool that can be used to analyse the performance of an application program while it is executing.
DRA can analyse Batch programs, CICS programs and DLL's. It operates as a profile event handler, and is loaded by Language Environment during Enclave initialization when the LE runtime option PROFILE(ON) is specified.
The application program to be analysed is expected to be LE-conform. The analyser recognizes functions, routines, procedures written in C, C++, Cobol, PL/1 and Assembler using the standard, fastlink or xplink linkage convention.
A function, routine or procedure can be analysed when it is represented by a Function Descriptor Control Block (FDCB). The FDCB is generated by the compiler and completed by the Loader at runtime. It contains, among other things, a pointer to the function. When the program is loaded, this pointer is saved and replaced by DRA to contain the address of a socalled "function interceptor". This is a DRA routine that gets control when the function is called by the application program via the modified pointer in the FDCB. The function interceptor performs analysis as directed by DRA options and calls the intercepted function using the saved pointer from the original FDCB.
If a function is not called through a Function Descriptor then it can not be intercepted using this method. Therefore, it is important that the compiler generates Function Descriptors. The C-compiler generates Function Descriptors when compiler option DLL is specified otherwise it generates direct calls. The C++ compiler always compiles with option DLL and therefore generates Functions Descriptors. However, the compiler does not generate Function Descriptors when the calling function is in the same compilation unit (same source file) as the called function. In this case, the function is called by means of a direct branch instead of going through a Function Descriptor. Therefore, the caller must be compiled in a compilation unit separate from the callee. The separately compiled functions are linked together by the Binder.
If for some reason, it is not possible to compile the caller and the callee in separate compilation units then the program should be recompiled with compiler option TEST. This compiler option generates socalled "hooks". These are special instructions inserted by the compiler at certain points. These hooks are normally used by the Debug tool. However, these same hooks can also be used by a Profile tool such as DRA. When the application program executes a hook then DRA will get a "hook" event, thus enabling it to analyse the program. See option HOOK for further details. However, if possible, the preferred method is to analyse the application program by intercepting calls through Function Descriptors because this method does not require the program to be recompiled.
The analyser records the following information:
The name of the calling program ("caller")
The name of the called function ("callee")
The time used by the called function.
The number of times the function was called.
The measured time is in microseconds and is differentiated between elapsed time, cpu time and wait time. See option TIME for further details.
The name of the calling program (caller) and the name of the called function (callee) is taken from the PPA, which is an internal control block at the entry point of every LE-conforming program. In the case of C++, this name includes the name space and the class name.
A summary at the completion of the program shows the number of times each function is called (and by whom) and the total time used by this function (clock time and cpu time). The wait time, if any, is computed by substracting the cpu time from the clock time.
The analyser also shows which DLL's (if any) were loaded during runtime, and how often they were loaded. It also shows the time (elapsed, cpu and wait time) that was needed to load the DLL. The functions imported from the DLL are analysed when they are called. See option DLL for further details.
When a condition is raised DRA will trace the name of the program who threw the exception as well as the name of the program who caught it. See Condition handling for further details.