Using the Profiler Utility in Online Mode

#### Search Results

Search

# 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

- Invoking and Terminating the Profiler Utility Online

- Events

- Functions

## 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.

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

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.

To 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

- List Trace Records

- Display Trace Record

- Start/Stop Profiler Tracing

- Print Trace Records

- Download Trace Records

- Save Data as Resource

### Select Profiler Events

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

To 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.

To 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 of Event Type Selection

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
- Navigation
- Updating Event Types to be Displayed
- Line Commands
- Local Commands
- PF Keys
- Example of List Trace Records

#### 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
- Navigation within a List of Records

##### Navigation within a Record

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

To 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

To 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 the 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 of List Trace Records

The following menu lists trace records for event types `PL`, `PS`, `PT` and `DA`, which have been selected in the Example of Event Type Selection, 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
- PF Keys
- Example

#### Navigation

To 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 of List Trace Records 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.

To 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.

To 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.

To 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 by the Profiler Rich GUI, and by the Profiler utility in batch mode. The tools 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.

To 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.

### On this page

- Prerequisites
- Invoking and Terminating the Profiler Utility Online
- Events
- Functions