Using the Profiler Utility in Online Mode

The Profiler utility in online mode is designed for getting a quick view to the last actions of a Natural online application. The utility is menu-based and provides functions to control profiler tracing, to select required event types, to maintain and display trace records, to download the event data to the PC and to save the event data as Profiler resource file.

The Profiler utility helps you analyze the logical flow of Natural applications and trace the utilization of resources.

This document covers the following topics:


Prerequisites

To use the Profiler utility in online mode, the keyword subparameter SIZE of the profile parameter RDC must be set to a value greater than 2, see RDC - Configure the Natural Data Collector in the Parameter Reference documentation.

In addition, the RDC parameter controls the following default behavior of the Profiler utility:

  • By setting RDC=ON, profiler tracing is already active when the Profiler utility is started. By default, RDC is set to OFF and profiler tracing must be activated separately, see Start/Stop Profiler Tracing.

  • The keyword subparameter EVENT determines which event types are selected for profiler tracing. By default, EVENT is set to ALL, which covers all available event types (see Data-Collecting Events in the SYSRDC Utility documentation).

  • For event types covered by the Profiler utility, see Events.

Invoking and Terminating the Profiler Utility Online

This section covers instructions for invoking and terminating the Profiler utility in online mode.

Start of instruction set To invoke the Profiler utility

  • Enter the following system command:

    PROFILER

    A menu similar to the example below appears. In the header of the menu, the current state with respect to profiler tracing is displayed (Trace started/Trace stopped). If profiler tracing is stopped, the number of trace records collected in the Natural Data Collector buffer is also displayed.

    12:30:57              ***** NATURAL PROFILER UTILITY *****           2016-03-07
    User SAG                         - Main Menu -                     1035 records
                                                                      Trace stopped
                                                                                   
                          Code  Function                                           
                                                                                   
                           S    Select Profiler events                             
                           L    List trace records                                 
                           D    Display trace record                               
                           T    Start/Stop Profiler tracing                        
                           P    Print trace records                                
                           W    Download trace records                             
                           B    Save data as resource                              
                           ?    Help                                               
                           .    Exit                                               
                                                                                   
                   Code .. _    Record from .. 1_____  to .. 1035__                
                                                                                   
                                                                                   
                                                                                   
    Profiler tracing successfully stopped.                                         
    Command ===>                                                                   
    Enter-PF1---PF2---PF3---PF4---PF5---PF6---PF7---PF8---PF9---PF10--PF11--PF12---
          Help        Exit                                                  Canc

Start of instruction set To terminate the Profiler utility

  • Press PF3 or PF12.

    Or:
    Enter a period (.) in the Code field.

    Or:
    Enter EXIT in the command line.

Events

During a Natural session, different kinds of events can occur, for example, a program start. Data specific to an event can be collected in a trace record. Each event is associated with an event type, that is, a one- or two-letter code. The following events and event types are available:

Event Event Type When the Event Occurs
Program Load PL When a program (Natural object) is loaded or when it is already located in the buffer pool.
Program Start PS When a program (Natural object) is started.
Program Termination PT When a program (Natural object) is terminated.
Before Database Call DB Before a database call is executed.
After Database Call DA After a database call has been executed.
Before Terminal I/O IB Before a terminal input/output is executed.
After Terminal I/O IA After a terminal input/output has been executed.
Before External Program Call CB Before an external program call (CALL statement) is executed.
After External Program Call CA After an external program call (CALL statement) has been executed.
Runtime Error E When a Natural runtime error has occurred.
Natural Statement NS When a Natural statement is executed. For technical reasons, there is no one-to-one relationship between a Natural source code statement and an object code in the cataloged object. Therefore, multiple Natural statements can be merged into one NS event and conversely, one Natural statement can cover multiple NS events.
User-Defined Event U When a user-defined event is generated using the Natural statement CALL 'CMRDC' 'U' (see User-defined Events in the SYSRDC Utility documentation). The first byte of the user data is interpreted as subtype. Therefore, a two-letter code is displayed for a user-defined event when the trace records are listed.

Functions

The functions covered by the Profiler utility in online mode can be divided into three categories:

  • Function Select Profiler Events to select events.

  • The display functions List Trace Records, Display Trace Record, Print Trace Records, Download Trace Records and Save Data as Resource to list, display, print, download or save trace records.

  • Function Start/Stop Profiler Tracing to start or stop profiler tracing.

All functions provided by the Profiler utility can be invoked from the main menu.

Start of instruction setTo invoke a function

  • Enter a function code in the Code field.

    Note:
    The input fields Record from and Record to can be modified to define a range of records that is listed or displayed at first by the functions List Trace Records and Display Trace Record, or to filter records for the functions Print Trace Records and Download Trace Records.

This section covers the following functions:

Select Profiler Events

This function is used to select event types for profiler tracing (in column Collect) and as filter for the display functions (in column Display).

Start of instruction setTo select an event type for profiler tracing

  • Enter any key in the corresponding input field in the Collect column. You need to select at least one event type.

    As a result, the Natural Data Collector is updated dynamically according to your selection. If profiler tracing is active, it is continued with the selections that you have made.

Notes:

  1. To activate profiler tracing for the event type Natural statement (NS), the profile parameter TRACE must be set to NATPROX and ITRACE to ON, see the Parameter Reference documentation. If you do not supply these values before starting your Natural session, you are prompted to do so when you select this event type.
  2. At session start, the event types selected for profiler tracing are specified by the RDC subparameter EVENT; see EVENT - Natural Data Collector Events to be Recorded in the Parameter Reference documentation. Any modification of this default selection is valid for the whole Natural session.

Start of instruction setTo select an event type as filter for display functions

  • Enter any key in the corresponding input field in the Display column. You need to select at least one event type.

Note:
At session start, the event types selected for display functions are specified by the RDC subparameter EVENT (see above). Any modification of this default selection is valid until the next LOGON. After this, the set of event types selected is equal to the set of event types selected for profiler tracing (see above).

PF Keys

The following PF keys are available:

PF Key Name Function
PF1 Help Display context-sensitive help. There is a specific help text for each input field. In other contexts, for example the command line, a general help text is displayed.
PF3 Exit Exit the current menu.
PF8 Reset Unselect all event types.
PF9 All Select all event types.
PF12 Canc Exit the current menu.

Example

In the example below, the following event types are selected for profiler tracing: PL, PS, PT, DB, DA, CB, CA, NS and U. The event types PL, PS, PT, DA, CB, CA and U are selected as filter for display functions.

10:13:24              ***** NATURAL PROFILER UTILITY *****           2011-03-29
User SAG                   - Select Profiler Events -                79 records
                                                                  Trace stopped

              Collect Display Type Profiler Event
              ------- ------- ---- ----------------------------
                 X       X     PL  Program load
                 X       X     PS  Program start
                 X       X     PT  Program termination
                 X       _     DB  Before database call
                 X       X     DA  After database call
                 _       _     IB  Before terminal I/O
                 _       _     IA  After terminal I/O
                 X       X     CB  Before external program call
                 X       X     CA  After external program call
                 _       _     E   Runtime error
                 X       _     NS  Natural statement
                 X       X     U   User-defined event



Command ===>
Enter-PF1---PF2---PF3---PF4---PF5---PF6---PF7---PF8---PF9---PF10--PF11--PF12---
      Help        Exit                          Reset All               Canc

List Trace Records

This function is used to list all trace records collected in the Natural Data Collector buffer. For this purpose, profiler tracing is stopped. A trace record can only be shown if the corresponding event type has been selected for the display functions by the Select Profiler Events function.

When the function is invoked, the trace record displayed at first is specified by the Record from field, see main menu. In addition, this trace record is also marked by an X, and the trace record specified by the Record to field by a Y.

This section covers the following topics:

Structure of Trace Records Displayed

Each trace record is displayed on a separate line which is headed by an input field for line commands (C). The record itself contains general and event-specific data. General data comprises features common to all records such as record number (Record), event type (Ev) or event time (Time). Event-specific data comprises features specific to a view, that is, a group of related events. For example, the event types PL, PS and PT constitute the view Program Load/Start/Termination. The view General Information includes all event types and covers the general data. The table below gives an overview on the available views and the event types associated:

View Code Event Types
General Information G all
Program Load/Start/Termination P PL, PS, PT
Before/After Database Call D DB, DA
Before/After Terminal I/O I IB, IA
Before/After External Program Call C CB, CA
Runtime Error E E
Natural Statement N NS
User-Defined Event U U

Notes:

  1. General Information (G) is the current view by default.
  2. If there is a view for which no event type has been selected to be displayed, the letter code for that view is replaced by a minus sign (-).

Navigation

The list of trace records displayed by the List Trace Records function can be quite large with respect to the size of the records displayed and the number of records listed. This section covers the following options:

Navigation within a Record

To navigate within a record, you need to change the current view.

Start of instruction setTo change the current view

  • Select a letter code in View using the cursor and press ENTER. See the table above for available letter codes.

    Or:
    Press PF10 (<) to choose the neighboring view on the left. Press PF11 (>) to choose the neighboring view on the right.

Navigation within a List of Records

Start of instruction setTo navigate within a list of records

  • Enter a record number in the input field Record to position to the corresponding trace record. Note that the trace record selected must have an event type that has been selected for the display functions by the Select Profiler Events function.

    Or:
    Enter an event type in the input field Ev to step forward to the next trace record marked with such an event type. From this position, continue to press ENTER to step to the next matching occurrence. Use asterisk notation (*) to match a group of event types, for example D* for all database calls.

    Or:
    Press PF6 (--), PF7 (-), PF8 (+) or PF9 (++) to scroll through the list.

Updating Event Types to be Displayed

A selection of event types for display functions can be updated by pressing PF4 (DiEv). This opens a menu similar to the menu which is opened when choosing the Select Profiler Events function, with the exception that event types can only be selected for display functions. See PF Keys in Select Profiler Events for available PF keys.

Line Commands

You can enter a line command in the C column next to the trace record you have selected. The following line commands are available:

Local Command Function
D Display all information available for the selected record. See also Display Trace Records.
X Mark the line with an X. The Record from field in the main menu is updated accordingly.
Y Mark the line with a Y. The Record to field in the main menu is updated accordingly.

Local Commands

You can enter a local command in the Command line. The following local commands are available:

Local Command Function
X Scroll to the line marked by an X (and indicated by Record from).
Y Scroll to the line marked by a Y (and indicated by Record to).

PF Keys

The following PF keys are available:

PF Key Name Function
PF1 Help Display context-sensitive help. See above.
PF2 Disp Display all information available for the selected trace record. See also Display Trace Records.
PF3 Exit Exit the current menu.
PF4 DiEv Modify the selection of event types to be displayed. See section Updating Event Types to be Displayed.
PF5 Hex Display user data in hexadecimal mode (only for event type U).
Struc Display program structure (only for event types PL, PS and PT).
PF6 -- Scroll to the beginning of the list.
PF7 - Scroll one page up.
PF8 + Scroll one page down.
PF9 ++ Scroll to the end of the list.
PF10 < Select the view on the left side of the current view.
PF11 > Select the view on the right side of the current view.
PF12 Canc Exit the current menu.

Example

The following menu lists trace records for event types PL, PS, PT and DA, which have been selected in the example above, and displays trace information for view P which covers the event-specific data of the event types PL, PS and PT.

10:13:39              ***** NATURAL PROFILER UTILITY *****           2011-03-29
User SAG                    - List Trace Records -                   79 records
                      View:  G P D - C - - U
                             PL/PS/PT - Program Load/Start/Termination

  C Record Ev Library  Program  Type DBID  FNR
  - ______ __ -------- -------- ---- ----- -----
X _ 000001 PL SYSEXPG  DYNAMX06
  _ 000002 PS SYSEXPG  DYNAMX06  P      10  2430
  _ 000010 PL SYSEXPG  DYNAMX05
  _ 000011 PS SYSEXPG  DYNAMX05  N      10  2430
  _ 000018 PT SYSEXPG  DYNAMX05  N      10  2430
  _ 000025 PT SYSEXPG  DYNAMX06  P      10  2430
  _ 000026 PL SYSEXPG  EDITMX02
  _ 000027 PS SYSEXPG  EDITMX02  P      10  2430
  _ 000031 DA
  _ 000040 DA
  _ 000047 DA
  _ 000054 DA
  _ 000057 PT SYSEXPG  EDITMX02  P      10  2430
Use PF10/PF11 to show event-specific data of the trace records.
Command ===>
Enter-PF1---PF2---PF3---PF4---PF5---PF6---PF7---PF8---PF9---PF10--PF11--PF12---
      Help  Disp  Exit  DiEv  Struc --    -     +     ++    <     >     Canc

Display Trace Record

This function is used to display all tracing information for each trace record separately. For this purpose, profiler tracing is stopped. When the function is invoked, the trace record displayed at first is specified by the Record from field, see main menu.

This section covers the following topics:

Navigation

Start of instruction setTo navigate to another trace record

  • Enter a record number in the input field Record to position to the corresponding trace record. Note that the trace record selected must have an event type that has been selected for the display functions by the Select Profiler Events function.

    Or:
    Press PF6 (--), PF7 (-), PF8 (+) or PF9 (++) to scroll through the sequence of trace records displayed.

PF Keys

The following PF keys are available:

PF Key Name Function
PF1 Help Display context-sensitive help. See above.
PF3 Exit Exit the current menu.
PF5 Hex Display user data in hexadecimal mode (only for event type U).
PF6 -- Display the first trace record.
PF7 - Display the preceding trace record.
PF8 + Display the succeeding trace record.
PF9 ++ Display the last trace record.
PF10 LongE Show long error message (only defined for event type E).
PF12 Canc Exit the current menu.

Example

In the example below, trace record 10 which has already been listed in the example above is displayed with all trace information.

10:14:01              ***** NATURAL PROFILER UTILITY *****           2011-03-29
User SAG                    - Display Trace Record -                 79 records


Record / Event .... 10____  /  PL - Program load

Event time ........ 10:12:14.130696    Elapsed time ....... 0.000157
CPU time .......... 0
Current user ID ... SAG                Current group ID ...
Current program ... DYNAMX06           Library ............ SYSEXPG
Program level .....                    Program line ....... 0160

Loaded program .... DYNAMX05           Invocation type .... CALLNAT
Library ........... SYSEXPG






Enter required record number, or use PF6 - PF9 for paging.
Command ===>
Enter-PF1---PF2---PF3---PF4---PF5---PF6---PF7---PF8---PF9---PF10--PF11--PF12---
      Help        Exit              --    -     +     ++                Canc

Start/Stop Profiler Tracing

This function is used to switch profiling on or off. If profiler tracing has been active, it is stopped. Conversely, if it has been inactive, it is started. As a result, the new state is displayed in the header of the main menu.

Start of instruction setTo start or stop profiler tracing

  • Enter T in the Code field and press ENTER.

Note:
As an alternative, you can also use the commands described in the Trace Recording section of the SYSRDC Utility documentation.

Print Trace Records

This function is used to print the trace records within the range defined by the input fields Record from and Record to. For this purpose, profiler tracing is stopped. Note that a trace record can only be printed if the corresponding event type has been selected for the display functions by the Select Profiler Events function.

Start of instruction setTo print trace records

  1. Enter P in the Code field.

    As a result, a separate window is opened in which you can modify the (default) printer name or the range of trace records to be printed. You can also specify if the trace records are printed with header information. The printer used is identified by print file 1.

  2. Press ENTER.

Download Trace Records

This function is used to download the trace records within the range defined by the input fields Record from and Record to. For this purpose, profiler tracing is stopped. Note that a trace record can only be downloaded if the corresponding event type has been selected for the display functions by the Select Profiler Events function.

Start of instruction setTo download trace records

  1. Enter W in the Code field.

    As a result, a separate window is opened in which you can modify the range of trace records to be downloaded. The download file used is identified by work file 7. For downloading to the PC, we recommend that you use Natural Connection.

  2. Press ENTER.

    Notes:

    1. Specify .htm for the extension of the downloaded file.
    2. We recommend that you use MS Excel to display the downloaded trace records. This requires that MS Excel and Natural have compatible settings, for example with respect to the decimal character used.

Save Data as Resource

This function is used to save all trace records in a Profiler resource file (extension .nprf). For this purpose, profiler tracing is stopped.

The Profiler resource file can be read by NaturalONE and by the Profiler utility in batch mode which provide a performance analysis (hot spots) and other evaluations. For more information, see the NaturalONE documentation and Using the Profiler Utility in Batch Mode.

Notes:

  1. If the Profiler utility runs under CICS or Com-plete, only the elapsed time is provided but not the CPU time.
  2. The event data collected by the Profiler utility in online mode does not contain copycode information.

Start of instruction setTo save the data as resource

  1. Enter B in the Code field.

    As a result, a separate window is opened in which you can modify the (default) resource name and library. You can also specify whether the resource should be replaced, if it already exists.

    The default resource name is *INIT-USER_yyyymmdd_hhiiss where *INIT-USER is the user ID under which the Natural session is running and yyyymmdd_hhiiss is the current date and time. If the extension .nprf (Natural Profiler resource file) has not been specified with the resource name, it is added automatically.

    The default library is the current library.

  2. Press ENTER.