Digital PDFs

AA-PB90A-TE

December 1990

304 pages

Original

10MB

Document:	DECtrace for VMS 1.0 Users Guide 199006
Order Number:	AA-PB90A-TE
Revision:
Pages:	304
Original Filename:	http://bitsavers.org/pdf/dec/vax/vms/layered_product/AA-PB90A-TE_DECtrace_for_VMS_1.0_Users_Guide_199006.pdf

OCR Text

AA-PB90A"'.'"TE

DECtrace for VMS
User's Guide
June 1990

This manual describes the DECtrace for VMS software and how to use it to collect and
report on event-based data.

Operating System:

VMS

Software Version:

DECtrace for VMS Version 1.0

digital equipment corporation
maynard, massachusetts

First Printing, June 1990
The· information in this document is subject to change without notice and should not
be construed as a commitment by Digital Equipment Corporation.
Digital Equipment Corporation assumes no responsibility for any errors that may
appear in this document.
Any software described in this document is furnished under a license and may be
used or copied only in accordance with the terms of such license. No responsibility
is assumed for the use or reliability of software or equipment that is not supplied by
Digital Equipment Corporation or its affiliated companies.

Restricted Rights: Use, duplication, or disclosure by the U.S. Government is subject to
restrictions as set forth in subparagraph (c)(l)(ii) of the Rights in Technical Data and
Computer Software clause at DFARS 252.227-7013.
© Digital Equipment Corporation 1990.

All rights reserved.
Printed in U.S.A.
The Reader's Comments forms at the end of this document request your critical
evaluation to assist in preparing future documentation.
The following are trademarks of Digital Equipment Corporation: ALL--IN-1, DEC,
DECtrace~ RdbNMS, VAX, VAX ACMS, VAX C, VAX CDD, VAX COBOL, VAX
DATATRIEVE, VAX DBMS, VAX FORTRAN, VAX RMS, VAX SQL, VAXcluster, VMS,
and the DIGITAL Logo.

This· document was prepared using VAX DOCUMENT, Version 1.2.

Contents
Preface . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .

xiii

1 Introduction to DECtrace
1.1
1.2
1.3
1.3.1

1.3.2
1.4

1.5

What Is Event-Based Data Collection? ..................... .
What Can DECtrace Do for You? ......................... .
How Does DECtrace Work? ............................. .
DECtrace Registrar Process .......................... .
DECtrace Administration Database .................... .
Overview of DECtrace Processing ........................ .
Explanation of Sample Application ....................... .

1-1
1-1
1-2
1-3

1-3
1-4

1-5

2 Creating a Facility Selection
2.1
2.2
2.3
2.4
2.4.1
2.4.2

2.4.3

Choosing Which Data to Collect .......................... .
Creating a Selection ................................... .
Deleting a Selection . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Displaying Information About a Selection .................. .
BRIEF Format .................................... .
FULL Format ..................................... .
NAMES_ONLY Format ............................. .

2-2

2-3
2-4
2-5
2-5
2-6
2-7

Iii

3 Scheduling Data Collection
3.1
3.1. l
3.1.2
3.1.3
3.2
3.2. l
3.2.2

3.2.3
3.3
3.3. l

3.4
3.5
3.5.l
3.5.2

Choosing the Processes from Which to Collect Data .......... .
Process Registration ................................ .
Using the Registration ID ............................ .
Displaying Information about Process Registration ........ .
Scheduling a Collection ................................ .
Scheduling Data Collection on a Standalone System ....... .
Scheduling Data Collection on a Cluster ................ .
Scheduling Data Collection on Part of a Cluster .......... .
Data Collection Files ~ ................................. .
File Protection Schemes . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Canceling Data Collection .............................. .
Displaying Information about Data Collection ............... .
Displaying the Schedule for Data Collection ............. .
Displaying the History for Collections .................. .

3-2
3-2
3-3

3-5
3-8

3-9
3-9
3-9
3-11

3-12
3-13
3-14
3-14
3-15

4 Generating Reports
4.1
4.2
4.2.l
4.2.2

4.3
4.4
4.4.1

4.4.2
4.4.3

4.5
4.5.l
4.5.2
4.5.3

4.5.4
4.6
4.7

4.8

Overview of Reporting ................................. .
Merging and Formatting Your Data Files .................. .
Merging and Formatting the Collected Data into an RdbNMS
Database ........................................ .
Merging and Formatting the Collected Data into a VAX RMS
File ........................................... · · ·
Formatting Optimization ............................... .
Report 'Types . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Detail Report . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Frequency Report .................................. .
Summary Report .................................. .
Text Wrapping in Reports .............................. .
Groupable Items .................................. .
Groups .......................................... .
Headers ......................................... .
Report I tern Text .................................. .
Special Cases for Reporting on Duration Events ............. .
Report Optimization ................................... .
Report Options ....................................... .
REPORT OPTIONS-EVENT ........................... .
REPORT OPTIONS-ITEM . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
REPORT OPTIONS-RESTRICTION . . . . . . . . . . . . . . . . . . . . . .

4-2
4-2

4-2
4-3
4-3
4-4
4-5
4-9
4-11
4-18
4-18
4-18
4-19
4-20
4-20
4-22
4-22
4-24
4-27
4-28

5 Instrumenting Applications
5.1
Programming Interface ................................ .
5.2
DECtrace Data Structures ............................... .
5.3
Determining Your Events ............................... .
5.4
Using EPC$INIT to Register a Facility .................... .
5.4.l
Waiting for EPC$INIT to Complete .................... .
5.5
Coding an Event in the ATM Sample Application ............ .
5.6
Instrumenting an Application in VAX C ................... .
5.6.l
Instrumenting Simple Events ........................ .
5.6.2
Instrumenting Events and Items ...................... .
5.6.2. l
Collecting Basic Facility-Specific Items .............. .
5.6.2.2
Collecting Facility-Specific Items Efficiently .......... .
5.6.2.3
Collecting Facility-Specific Items with Maximum
5.7
5.7. l
5.7.2
5.7.3
5.7.4
5.8

Efficiency . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Instrumenting a Multi-Threaded Facility Using VAX BLISS-32 ..
Call EPC$INIT to Register the NEW_TOOL Facility ....... .
Call EPC$SET_CONTEXT to Set Thread Context ......... .
Call EPC$DELETE_CONTEXT to Delete the Thread
Context ......................................... .
Call EPC$START_EVENT and EPC$END_EVENT to Collect
Event Data ....................................... .
Linking an Instrumented Program ....................... .

5-2
5-4
5-5
5-6
5-9
5-10
5-11

5-12
5-13
5-14
5-19
5-20
5-28
5-28
5-30
5-31
5-31
5-32

6 Creating Facility Definitions
6.1
6.1. l
6.1.2
6.1.3
6.2
6.3
6.3. l
6.3.2
6.3.3
6.4
6.4.l
6.4.2
6.5

Creating a Facility Definition ............................ .
Creating and Defining Events ........................ .
Creating and Defining I terns ......................... .
Creating and Defining Collection Classes ............... .
Deleting Facility Definitions ............................ .
Transporting Facility Definitions ......................... .
Extracting Definitions .............................. .
Inserting Definitions Using a KITINSTAL.COM Procedure .. .
Inserting Definitions Without KITINSTAL.COM .......... .
Displaying Facility Definitions ........................... .
FULL Format ..................................... .
NAMES_ONLY Format , ............................ .
Facility Definition Options .............................. .
ITEM .............................................. .
GROUP ............................................ .
EVENT . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
CLASS..............................................
DEFAULT_CLASS.....................................

6-2
6-3
6-5
6-8
6-9
6-10
6-10
6-11

6-12
6-13
6-14
6-19
6-20
6-22
6-26
6-27
6-30
6-31
v

7 DECtrace Commands
@ (EXECUTE PROCEDURE). . . . . . . . . . . . . . . . . . . . . . . . . . . . .

CANCEL COLLECTION . . . . .. . . . . . . . . . . . . . . . . . . . . . . . . . . .
CREATE DEFINITION . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
CREATE DEFINITION OPrIONS-ITEM . . . . . . . . . . . . . . . . . .
CREATE DEFINITION OPrIONS-GROUP.................
CREATE DEFINITION OPrIONS-EVENT.................
CREATE DEFINITION OPrIONS-CLASS . . . . . . . . . . . . . . . . .
CREATE DEFINITION OPrIONS-DEFAULT_CLASS . . . . . . . .
CREATE SELECTION. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
DELETE DEFINITION . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
DELETE SELECTION. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
EXIT . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
EXTRACT DEFINITION . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
FORMAT . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
HELP...............................................
INSERT DEFINITION. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
REPORT . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
REPORT OPTIONS-EVENT . . . . . . . . . . . . . . . . . . . . . . . . . . . .
REPORT OPTIONS-ITEM..............................
REPORT OPTIONS-RESTRICTION . . . . . . . . . . . . . . . . . . . . . .
SCHEDULE COLLECTION. . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
SET HISTORY . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
SHOW COLLECTION . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
SHOW DEFINITION . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
SHOW HISTORY . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
SHOW REGISTER . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
SHOW SELECTION . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
SHOW VERSION. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
SPAWN . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
STOP SYSTEM . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .

7-4
7-5
7-8
7-11
7-15
7-16
7-19
7-20
7-21
7-25
7-27
7-29
7-30
7-32
7-39
7-40
7-42
7-47
7-51
7-52
7-54
7-59
7-61
7-63

7-65
7-68
7-69
7-71
7-72
7-76

8 DECtrace Service Routines
8.1

Error Handling ....................................... .
EPC$DELETE_CONTEXT .............................. .
EPC$END_EVENT ................................... .
EPC$END_EVENTW' .................................. .
EPC$EVENT ........................................ .
EPC$EVENTW ...................................... .
EPC$INIT .......................................... .
EPC$SET_CONTEXT ................................. .
EPC$START_EVENT .................................. .
EPC$START_EVENTW ................................ .

8-2
8-4
8-7
8-11

8-12
8-16
8-17
8-23
8-26
8-30

9 System Management Tasks
9.1

9.2
9.2.1
9.2.2
9.2.3
9.3
9.3. l
9.3.2

9.3.3
9.4

9.5
9.6

9.7
9.7.1

Required Account and Process Quotas ..................... .
Controlling DECtrace ...... ; ........................... .
Starting DECtrace ................................. .
Stopping DECtrace ................................ .
Recovering From a System Crash ..................... .
Installing Facilities on Your System ....................... .
Installing New Facilities ............................ .
Installing New Versions of Existing Facilities ............ .
Installing a New Version of Rdb/VMS .................. .
Managing the History Database ......................... .
Disabling Data Collection .............................. .
Improving DECtrace Performance ........................ .
Troubleshooting DECtrace .............................. .
Error Messages and Recovery Procedures ............... .

9-1

9-2
9-2
9-3
9-3
9-4
9-4
9-4

9-5
9-5
9-6
9-7
9-7
9-9

A Formatted Database and File Layouts
A. l
The Rdb/VMS Database ................................ .
A.1.1
The Data fypes ................................... .
A.1.2
String Data Segmentation ........................... .
A.1.3
Relations for the Control Information .................. .
A.1.3. l
The EPC$IDENT Relation ........................ .
A.1.3.2
The EPC$SELECTION Relation ................... .
A.1.3.3
The EPC$COLLECTION Relation .................. .
A.1.3.4
The EPC$DCF Relation .......................... .
A.1.3.5
The EPC$REG Relation .......................... .
A.1.3.6
The EPC$FACILITY Relation ..................... .

A-1
A-2
A-3
A-4

A-5
A-5
A-5
A-6
A-7
A-7

vii

A.1.3.7
A.1.3.8
A.1.3.9
A.1.3. 10
A.1.3. 11
A.1.3.12
A.1.3. 13
A.1.4
A.1.5
A.1.6
A. l.6. 1
A. l .6.2

The EPC$EVENT Relation ....................... .
The EPC$ITEM Relation ......................... .
The EPC$EVENT_ITEM Record ................... .
The EPC$PROCESS Relation ..................... .
The EPC$IMAGE Relation ........................ .
The EPC$DCF_IMAGE Relation ................... .
The EPC$FACILITY_IMAGE Relation ............... .
Relations for the Collected Data ...................... .
The Entity Relationship Diagram for the Database ........ .
The Predefined Views ............................... .
Relating Collection Information with Event Data ...... .
Relating Selection and Collection Information with Event
Data .................................. ·.······
A.1.6.3
Relating Image Information with Event Data ......... .
A.1.6.4
Relating Process and Image Information with Event
Data ......................................... .
A.1.7
Limitations . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
A.2
The VAX RMS File Format ............................. .
A.2.1
Data 'fypes ....................................... .
A.2. l. l
Date ......................................... .
A.2. 1.2
Fixed ASCI ClASCIW String ....................... .
A.2.2
Records Organization ............................... .
A.2.2. l
Control Records ................................ .
A.2.2. l. l
FMTDICT Record ............................ .
A.2.2. 1.2
COLLECTION Record ........................ .
A.2.2. 1.3
FACILITY Record ........................... .
A.2.2. 1.4
DCF Record ................................ .
A.2.2. 1.5
IMAGE Record .............................. .
A.2.2. 1.6
FACILITY-REGISTRATION Record .............. .
A.2.2.1.7
EVENT Record .............................. .
A.2.2. 1.8
Item Descriptor ............................. .
A.2.2.2
Data Collection Records .......................... .

Glossary
Index

viii

A-8
A-8
A-10
A-11
A-12
A-13
A-13
A-14
A-15
A-15
A-15
A-15
A-16
A-17
A-17
A-17
A-18
A-18
A-18
A-18
A-19
A-20
A-20
A-20
A-21
A-21
A-23
A-24
A-24
A-26

Examples
2-1
2-2
2-3
2-4
3-1
3-2
3-3
3-4
3-5
3-6
3-7
4-1
4-2
4-3
4-4
4-5
4-6
4-7
4-8
4-9
4-10

5-1
5-2
5-3
5-4
5-5
5-6
6-1
6-2
6-3

Display Format for SHOW DEFINITION
/FORMAT=NAMES_ONLY .............. ·................ .
Display for SHOW SELECTION Using the Brief Format ...... .
Display for SHOW SELECTION Using the Full Format ....... .
Display for SHOW SELECTION Using the Names Only
Format .................................... ···.······
Process Registration Display ............................ .
Display Format for SHOW REGISTER/CLUSTER ........... .
Display Format for SHOW REGISTER/NOCLUSTER ......... .
Sample Command Procedure for Starting a Local Collection .... .
Display for SHOW COLLECTION Using the Brief Format ..... .
Display for SHOW HISTORY /FORMAT=ERROR ............ .
Display for SHOW HISTORY /FORMAT=INFORMATIONAL ... .
Display for Detail Report ............................... .
Sample Detail Report Based on ATM Data ................. .
Display for Frequency Report Using /INTERVAL=SECONDS ... .
Sample Frequency Report Based on ATM Data .............. .
Display for Summary Report ............................ .
Sample Summary Report Based on ATM Data .............. .
Wrapping of a Groupable I tern ........................... .
Wrapping of Groups ................................... .
Wrapping of Headers .................................. .
Wrapping of Report I tern Text ........................... .
Instrumentation of EPC$INIT in the ATM Application ........ .
Code to Guarantee Collection of All Events ................. .
Instrumentation of the WITHDRAWAL Event in the ATM
Application .......................................... .
DB Sample Facility ................................... .
DB Sample Facility-Performance Optimized ............... .
Instrumentation Using LIB$FIND_IMAGE_SYMBOL ......... .
Sample Procedure to Insert Binary Facility Definitions ........ .
Display for SHOW DEFINITION Using the Full Format ...... .
Display for SHOW DEFINITION Using the Names Only
Format ............................................. .

2-3
2-6
2-7
2-7
3-4
3-6
3-7
3-10

3-15
3-16
3-17
4-5
4-6
4-10
4-11

4-14
4-16
4-18
4-19
4-20
4-20
5-8
5-9
5-10
5-15

5-24
5-33
6-11
6-15

6-20

Figures
1-1
5-1
A-1

Overview of DECtrace Processing ........................ .
Flowchart of the Sample Application Showing One Event ...... .
The Entity Relationship Diagram for the Database ........... .

1-4
5-7
A-16

Commands for Manipulating Collection Definitions . . . . . . . . . . . .
Commands for Manipulating Data Collections... . . . . . . . . . . . . .
Commands for Genera ting Reports . . . . . . . . . . . . . . . . . . . . . . . .
Format Optimization Parameters . . . . . . . . . . . . . . . . . . . . . . . . .
DECtrace Reports . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Data Formats.........................................
Parts of a Summary Report Event Group . . . . . . . . . . . . . . . . . . .
DECtrace Service Routines . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Resource Utilization Items. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Summary of Facility Definition Options. . . . . . . . . . . . . . . . . . . . .
Facility Definition Commands . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Standard Resource Utilization Items . . . . . . . . . . . . . . . . . . . . . . .
Summary of Facility Definition Options. . . . . . . . . . . . . . . . . . . . .
ITEM Data Types . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
ITEM Default Report Widths.............................
ITEM Usage Types . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
ITEM Usage Types by Data Type..........................
DECtrace Commands. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
ITEM Data Types . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
ITEM Default Report Widths.............................
ITEM Usage Types. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
ITEM Usage Types by Data Type. . . . . . . . . . . . . . . . . . . . . . . . . .
RdbNMS Optimization Parameters . . . . . . . . . . . . . . . . . . . . . . . .
DECtrace Service Routines . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
User Account Quotas for Using DECtrace . . . . . . . . . . . . . . . . . . .
Troubleshooting DECtrace Problems . . . . . . . . . . . . . . . . . . . . . . .
RdbNMS Representations of DECtrace-Supported Data Types . . .
The point event relation EPC$l;._40_REQUEST . . . . . . . . . . . . . .
A relation for segmented strings . . . . . . . . . . . . . . . . . . . . . . . . . .
EPC$IDENT Relation . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
EPC$SELECTION Relation..............................

2- l
3-2
4-1
4-3
4-4
4-4
4-13
5-1
5-3
5-13
6-1

Tables
2-1
3-1
4- l
4-2
4-3
4-4
4-5
5-1
5-2
5-3
6-1
6-2
6-3
6-4
6-5
6-6
6-7
7-1
7-2
7-3
7-4
7-5
7-6
8-1
9-1
9-2
A-1
A-2
A-3
A-4
A-5

6-6

6-20
6-22
6-24
6-24
6-25
7-2
7-11
7-13
7-13
7-14
7-34
8-1
9-1
9-7
A-2
A-3
A-4
A-5
A-5

A-6
A-7
A-8
A-9
A-10
A-11
A-12
A-13
A-14
A-15
A-16
A-17
A-18
A-19
A-20
A-21
A-22
A-23
A-24
A-25
A-26
A-27

EPC$COLLECTION Relation . . . . . . . . . . . . . . . . . . . . . . . . . . . .
EPC$DCF Relation . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
EPC$REG Relation . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
EPC$FACILITY Relation................................
EPC$EVENT Relation . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
EPC$ITEM Relation . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
EPC$EVENT_ITEM Relation. . . . . . . . . . . . . . . . . . . . . . . . . . . . .
EPC$PROCESS Relation . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
EPC$IMAGE Relation . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
EPC$DCF_IMAGE Relation . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
EPC$FACILITY_IMAGE Relation . . . . . . . . . . . . . . . . . . . . . . . . .
Event Relation Fields. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Record Type Literal . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
FMTDICT Record . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
COLLECTION Record . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
FACILITY Record . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
DCF Record . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
IMAGE Record . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
FACILITY-REGISTRATION Record........................
Event Record Description. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Item Descriptor . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Data Collection Record . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .

A-6
A-6
A-7
A-7
A-8
A-9
A-10
A- 11
A-12
A-13
A-14
A-15
A-18
A-20
A-20
A-21
A-21
A-22
A-23
A-24
A-25
A-26

Preface
This manual describes how to use DECtrace for VMS Vl.O. The documentation
refers to DECtrace for VMS by its abbreviated name: DECtrace.

Intended Audience
This manual is intended for application programmers, software performance
analysts, and database administrators. Users of the DECtrace software can be
divided into two distinct groups: general users and application developers. The
general user will use DECtrace to gather information from existing products
and applications. Developers will instrument their programs and applications
with DECtrace service routine calls so that users can collect the event-based
data.
General users should read this manual in the order that it is presented
(Chapter 1, 2, 3, 4, 5). Application developers should read Chapter 1, then skip
to Chapter 5 and Chapter 6 and then go back and read Chapters 2, 3, and 4.
System managers should read Chapter 9.
Chapters 7 and 8 provide reference material of interest to all users.

Operating System Information
Information about the versions of the operating system and related software
that are compatible with this version of DECtrace is included in the DECtrace
media kit in the Installation GUide.
For information on the compatibility of other software products with this
version of DECtrace, refer to the System Support Addendum (SSA) that comes
with the Software Product Description (SPD). You can use the SPD/SSA to
verify which versions of your operating system are compatible with this version
of DECtrace.

xiii

Structure
This manual has nine chapters, one appendix, a glossary, and an index:
Chapter 1

Provides an overview of the DECtrace software and describes· the
sample application.

Chapter 2

Describes how to create facility selections.

Chapter 3

Describes how to schedule data collection.

Chapter 4

Describes how to use the DECtrace reporting component.

Chapter 5

Describes how to instrument your application source code with
DECtrace service routines.

Chapter 6

Describes how to create facility definitions.

Chapter 7

Describes the DECtrace commands.

Chapter 8

Describes the DECtrace service routines.

Chapter 9

Describes system management tasks associated with the DECtrace
software.

Appendix A

Describes the formatted database and layouts produced by the
DECtrace formatter.

Glossary

Defines terms used in this manual and other manuals in the
documentation set.

Index

Provides page references for topics covered in this manual.

Related Documents
The other manuals in the DECtrace documentation set are:

• DECtrace for VMS Installation Guide-Provides instructions for installing
the DECtrace software on a VMS system.
• DECtrace for VMS Release Notes-Provides additional information about the DECtrace software that was not included in the
DECtrace for VMS User's Guide. The release notes are located in
SYS$HELP:EPCO 10.RELEASE_NOTES.
• Using DECtrace with Digital Products-Provides product-specific
information on how to use the DECtrace software with a variety of
layered products.

xiv

Conventions
The special symbols used in this book are:
Symbol

Meaning

ICTRL/xl

This symbol tells you to press the CTRL (control) key
and hold it down while pressing the specified letter key.

BOLD

Bold lettering in text indicates the definition of a new
term.

[]

Brackets indicate optional elements.
Horizontal ellipsis indicate that you can enter additional
parameters, values, or information.
Vertical ellipsis in an example means that information
not directly related to the example has been omitted.

The dollar sign is used to indicate the DCL prompt. This
prompt may be different on your system.

Color

In printed manuals, color in examples shows user input.

References to Products
The DECtrace for VMS documentation often refers to products by their
abbreviated names:
•

DECtrace for VMS software is referred to as DECtrace.

• VAX ACMS software is referred to as ACMS.
• VAX BLISS-32 software is referred to as BLISS-32.
• VAX C software is referred to as C.
• VAX CDD/Plus software is referred to as CDD/Plus.
• VAX COBOL software is referred to as COBOL.
• VAX DATATRIEVE software is referred to as DATATRIEVE.
• VAX FORTRAN software is referred to as FORTRAN.
• VAX Pascal software is referred to as Pascal.
• VAX Rdb/VMS software is referred to as Rdb/VMS.
• VAX SQL software is referred to as SQL.

1
Introduction to DECtrace

1. 1 What Is Event-Based Data Collection?
DECtrace is a VMS layered product that collects and reports on event-based
data gathered from any combination of VMS layered products and application
programs containing DECtrace service routine calls. The DECtrace software is
designed to operate with minimal performance impact on the system and thus
can be used in both production and development environments.
DECtrace considers an event to be an application-defined entity. An event
can have a start and an end (duration event), or it can simply occur (point
event). DECtrace allows events within layered products or application
programs to be defined and data items to be associated with each event. These
data items can be standard resource utilization statistics (see Table S-2) or
data items specific to an application.
DECtrace differs from other collectors in that it is event based, whereas most
other collectors are timer based. An event-based collector gathers data at
predefined locations in your program code when that code is executed. Timerbased collectors perform data collection at specified time intervals, but at
random places within your code. Advantages of event-based collectors include:
( 1 ) providing an easy way to collect and report on the actual resources utilized
by certain events in applications and (2) determining the actual frequency of
the execution of events, rather than an average or estimated frequency.

1.2 What Can DECtrace Do for You?
Event data collected from applications can be useful for many different
purposes .including:
•

Tuning the performance of applications

•

Planning hardware resources (capacity planning)

Introduction to DECtrace

1-1

• Tuning the performance of databases
• Debugging applications
• Logging errors
Data can be collected from layered products or applications that already
contain DECtrace calls, or you can add the calls to your own application or
layered product code. If your application uses one of the already-instrumented
products, called a facility, you can collect data automatically without adding
anything to your code. Predefined facilities include ALL-IN-1, ACMS, Rdb
/VMS, and VAX DBMS. See the Using DECtrace with Digital Products manual
for descriptions of the events and items specific to these facilities.
DECtrace does not attempt to analyze or modify the performance of an
application or database. Its function is to collect data requested by users
and
provide reports based on that data. Interpreting these reports is the
responsibility of the user or of other layered products.

1.3 How Does DECtrace Work?
When an application image that has DECtrace service routine calls in it
activates, it sends a registration message to the DECtrace Registrar process
saying, "Here I am, and I am ready to collect data." DECtrace compares the
information in this registration message to the criteria of any active collections
on the duster to determine if data should be collected from that process.
If a user has scheduled event data to be collected from that application

(or from a facility that the application image has activated), then a "Start
collecting" message is sent from DECtrace back to the image, enabling the
collection of specific events and data items. The image then begins recording
the appropriate event data to a data collection file until it receives a "Stop
collecting" message from DECtrace or until the image terminates normally.
If no data collection is active when the image sends a registration message, it

does not receive a "Start collecting" message and does not attempt to record
any data. However, the DECtrace software keeps track of all processes that
have registered. When a new collection begins, DECtrace compares the
selection criteria against the currently registered images and sends out the
appropriate "Start collecting" messages.

1-2 Introduction to DECtrace

1.3. 1 DECtrace Registrar Process
When you start the DECtrace software on your system (by using
SYS$SYSTEM:EPC$STARTUP.COM), you are starting the Registrar
process. This is a detached process that handles all communication between
the applications running on your system and the DECtrace software. The
Registrar tells your applications to start or stop collecting data, and maintains
a list (visible using the DECtrace SHOW REGISTER command) of the
processes available for data collection.
Note that a Registrar process must exist on every node from which you want to
collect data. The VMS SHOW SYSTEM command confirms that the Registrar
process is running on your system. For example:
$ SHOW SYSTEM
VAX/VMS V5.2 on node MYVAXl 11-SEP-1989 10:06:22.04
Uptime
25 23:31:29
Pid
Process Name
State Pri
I/O
CPU
Page flts Ph.Mero
25200021 SWAPPER
HIB
16
0
0 00:33:18.22
0
0
25200062 SMITH
LEF
4
1132
0 05:17:49.86
512
23591
25200026 ERRFMT
HIB
19371
0 00:05:19.66
97
8
76
25200027 CACHE SERVER
HIB
16
302
0 00:00:01.61
90
63
25200028 CLUSTER SERVER HIB
10
1308
0 00:00:40.74
208
124
25200029 OPCOM
HIB
8
2847
0 00:06:34.99
749
134
2520002A JOB CONTROL
HIB
10
22829
0 00:06:23.35
445
258
2520002B CONFIGURE
HIB
8
18
0 00:00:00.43
148
104
25200220 SYSTEM
CUR
115996
0 00:09:17.22
258
4
71090
25200030 NETACP
HIB
10
2711
0 00:19:15.60
79608
1500
25200032 REMACP
HIB
19
51
9
0 00:00:00.26
75
25200338 SMITH 1
LEF
6
14262
0 00:03:16.16
37920
512
252001DA EPC$REGISTRAR
HIB
8
10955
512
0 00:04:36.88
21334
25200588 RDMS MONITOR
LEF
558
0 00:00:02.29
53
15
2720

1.3.2

DECtrace Administration Database

When you install the DECtrace software on your system or V.AXcluster, the
installation procedure creates an RdbNMS database that DECtrace uses to
store the following:
•

Facility definitions

•

Facility selections

•

Data collection schedule information

The database is referred to as the DECtrace administration database.
A system-wide logical name, EPC$ADMIN_DB, points to the location of the
database.

Introduction to DECtrace

1-3

1.4 Overview of DECtrace Processing
Figure 1-1 illustrates the process of using the DECtrace software to collect and
report on event-based data.
Figure 1-1

Overview of DECtrace Processing

e
0
Application - - - - - ACMS

Server Code

~-·--- Collection File

Database
Report
Formatted
Database

'-------"

----...........................
.............................

Application Programmer Steps

0 Instrument application
G Create facility definition
User Steps

0 Create selection
f) Schedule collection
E) Collect data

0 Format data
Q Report data
NU-2050A-RA

Collecting data from predefined facilities consists of the following steps:

0 User creates a facility selection, naming the facilities from which to collect
data.

1-4 Introduction to DECtrace

8 User schedules data collection referencing the facility selection created in
Step 1 (or, a preexisting selection).

8 Someone runs the application program or layered product, causing
predefined events to execute and be collected by DECtrace.

0 User formats data collection files into either an RdbNMS database or an
RMS file. 1

0 User generates a DECtrace report from the formatted RdbNMS database
or uses a report generator (for example, VAX DATATRIEVE) to create a
report from either the RdbNMS database or RMS file.
You can also use DECtrace to collect event data from your own applications.
Creating your own facility consists of the following steps (then follow the
general user steps outlined in the previous section):
A

Application programmer instruments the source code with DECtrace
service routine calls.

Application programmer creates a facility definition for the product and
stores it in the DECtrace administration database.

1.5 Explanation of Sample Application
For application programmers who want to instrument their own code with
DECtrace service routine calls, a sample application that uses DECtrace
is included with the DECtrace software kit. The application simulates a
simple bank automated teller machine (ATM). Duration events are defined
for each of the basic transactions: checking a balance, depositing funds, and
withdrawing funds. A point event is defined to note execution of the error
handling procedure.
The instrumentation of the ATM application is designed to gather information
about the user interface. The goal is to be able to answer questions such as:
•

How long does it take to complete a transaction?

•

Do customers check their balance before or after every transaction?

•

Could overdrafts be reduced or eliminated by displaying the balance on the
withdrawal display?

• Are ATM machines used primarily for deposits or withdrawals?

The layouts of the RdbNMS and RMS file formats are described in Appendix A.

Introduction to DECtrace

1-5

Various examples throughout this manual are based on the VAX COBOL
version of the sample application. The source file for this program, along
with versions written in VAX FORTRAN and VAX Pascal, are located in
EPC$EXAMPLES. The three versions perform the same functions and collect
the same event data. To use the sample application, copy the executable
(EPC$ATM-SAMPLE.EXE) and the data file (EPC$ATM-SAMPLE.DAT) to
your directory. The data file contains ten account records, numbered from 1 to
10.

1-6 Introduction to DECtrace

2
Creating a Facility Selection
A facility selection describes which data to collect during data collection. It
specifies the individual facilities (applications and layered products) and the
class of data to collect for each one. Creating a facility selection is the first
step (see Figure 1-1) for general users of the DECtrace software who want to
gather event-based data from facilities on their system. See Chapter 5 and
Chapter 6 for information on how to create a new facility.
This chapter describes how to manipulate facility selections. It describes how
to:
•

Create selections

•

Delete selections

•

Display selections

Table 2-1 summarizes the DECtrace commands available to accomplish the
functions associated with facility selections.
Table 2-1

Commands for Manipulating Collection Definitions

Command

Description

CREATE SELECTION

Creates a facility selection in the DECtrace administration database. Selection names must be unique in
the DECtrace administration database. If you use the
/REPLACE qualifier, your new facility selection replaces
the old selection of the same name.

DELETE SELECTION

Deletes a facility selection from the DECtrace
administration database.

SHOW SELECTION

Displays a facility selection in one of three formats:
BRIEF, FULL, or NAMES_ONLY.

Creating a Facility Selection

2-1

2. 1 Choosing Which Data to Collect
The DECtrace software performs data collection on your system with minimal
performance impact to the application and the system. However, the impact
increases as you select more facilities from which to collect data, and as you
specify more data to collect from each facility. The data files produced by
DECtrace can become very large in a busy environment. If you are on a system
with limited free disk space, you should carefully consider how much data you
will be collecting. If you use DECtrace to collect all of the available data from
all of the facilities on your system, you could run out of disk space very quickly.
When you decide to use DECtrace you probably have a specific function or
area .about which you want more information. For example, some of your
applications might not be performing as well as you think they should, or you
might need to generate statistics for a capacity planning report for the next
fiscal year. DECtrace can collect a wide variety of data from the applications
running on your system. However, you may not need to collect all of the
possible data from all of the events occurring in the facilities you are using. It
is possible to end up with much more information than you really need.
To make it easier to collect the data that you really need and to protect
you from collecting data that you do not need, facilities can have one or
more collection classes associated with them. These classes are subsets
of all of the available events and items chosen by the facility developers for
their significance to a specific function. For example, a facility might have
specific collection classes defined for performance, workload analysis, capacity
planning, or debugging purposes. The importance of selecting a collection class
is illustrated by the following collection rates, which apply to the Debit/Credit
workload for RdbNMS and VAX DBMS:
•

20,000+ blocks per 1 TPS/hour for ALL class data

•

20,000 blocks per 1 TPS/hour for PERFORMANCE class data

•

10,000 blocks per 1 TPS/hour for WORKLOAD class data

You use the SHOW DEFINITION/FORMAT=NAMES_ONLY command to
determine what classes are available for a given facility. For example,
Example 2-1 shows that the NEW_FORMS facility has the collection classes
ALL, CAPACITY_PLANNING, PERFORMANCE, and WORKLOAD (default).
ATM_SAMPLE and MY_APPLICATION have only the default (ALL) class
available.

2-2

Creating a Facility Selection

Example 2-1

Display Format for SHOW DEFINITION /FORMAT=NAMES_
ONLY

23-DEC-1989 11:43
Names Only Report

Facility Definition Information

Facility:

Version:

Creation Date:

Class:

ATM SAMPLE
MY FACILITY
NEW FORMS

Vl.O
V2.0
V4.0

25-AUG-1989 14:17
12-AUG-1989 10:27
13-JUN-1989 07:22

ALL
(D)
ALL
(D)
ALL
CAPACITY PLANNING
PERFORMANCE
WORKLOAD
(D)

Page 1
DECtrace Vl.0-0

Every facility has the ALL class, which contains all of the events and items
defined for the facility. Furthermore, one of the classes is designated by the
facility developers as the default class based on its predicted importance and
frequency of use. Note that unless otherwise specified, the default is the ALL
class, which is generated automatically when the developer creates a facility
definition.

2.2 Creating a Selection
A DECtrace facility selection consists of:
• Name of the selection
•

List of facilities from which to collect data

•

Classes of data to collect for each facility

•

Comment describing the purpose of the selection

The format of the CREATE SELECTION command is:

CREATE SELECTION selection_name

IFACIL/TY=(faci!ity_name[, ... ]) ]
/COMMENT=" ... II
IOPTIONS[=file_spec]
[
/REPLACE

All facility selections are stored in the DECtrace administration database,
and any user can reference a facility definition created by any other user. The
facility selections remain in the database until they are deleted by their creator
or by a user with BYPASS or SYSPRV privilege.
You use the CREATE SELECTION command to choose a subset of the
available facilities from which you want to collect data. The following example
defines the facility selection MY_SELECTION to collect the default class of
data for ACMS:

Creating a Facility Selection

2-3

COLLECT CREATE SELECTION MY SELECTION /FACILITY=ACMS /COMMENT="Collect the defa;-lt VAX ACMS data"

To define a more detailed facility selection, you should use an options file. The
/OPTIONS qualifier allows you to specify more than one facility and choose
a different class of data for each facility. The qualifier takes the name of
an options file as an argument. If you do not specify a file name, DECtrace
prompts you for the options. Each facility must be defined on a separate line.
The format of the facility description is:
FACILITY facility-name

[!VERSION=" version-code"] [ICLASS=class-name]

facility-name

The name of the facility from which to collect data.
version-code

A text string identifying the version of the facility. The string must be enclosed
with quotation marks ( " " ). If you do not include the version code, DECtrace
uses the most recent version of the facility registered in the DECtrace
administration database.
class-name

The name of the class of data to collect for the facility.
The following example creates the facility selection COLLECT_ALL to collect
all of the possible events and data items for MY_APPLICATION and the
performance events and items for RdbNMS:
$ COLLECT CREATE SELECTION COLLECT ALL /OPTIONS
Option> FACILITY MY_FACILITY /CLASS=ALL
Option> FACILITY RDBVMS /CLASS=PERFORMANCE
Option> ICTRL/ZI
%EPC-S-SELCRE, Selection COLLECT ALL was created
$

2.3 Deleting a Selection
You can delete a facility selection from the DECtrace administration database
with the DELETE SELECTION command. You must be the creator of the
selection or have VMS BYPASS or SYSPRV privilege. Note that you cannot
delete a facility selection if any data collection, either active or pending, is
using that facility selection.
The following example deletes the facility selection TEMP_SELECTION:
$ COLLECT DELETE SELECTION TEMP SELECTION /NOCONFIRM
%EPC-S-SELDEL DELETED, Selection-TEMP SELECTION was deleted
$

2-4 Creating a Facility Selection

To delete a facility selection that is referenced by any active or pending
collections, you must first cancel the data collection. See Section 3.4 for
information on how to cancel all data collection using a particular facility
selection.
You can use the SHOW SELECTION/FORMAT=NAMES_ONLY command to
confirm the spelling of the names of facility selections that you want to delete.

2.4 Displaying Information About a Selection
You can display information about the facility selections stored in the
DECtrace administration database using the SHOW SELECTION command.
The command takes one argument: the name of a selection. If you do not
specify a selection name, DECtrace displays information on all of the facility
selections defined on the system.
You can specify the amount of information to display about a selection by using
the /FORMAT qualifier to the SHOW SELECTION command. There are three
valid format types:
•

BRIEF (default)

• FULL
• NAMES_ONLY

2.4. 1 BRIEF Format
If you specify /FORMAT=BRIEF with the SHOW SELECTION command,

DECtrace lists the names of the facility selections in the DECtrace
administration database together with the facilities, versions, and collection
classes that each selection describes. If you did not specify a facility version
when you created the facility selection, the most recently created version of the
facility definition is used and "(latest)" is displayed.
The BRIEF format is useful if you want to check what facilities are in a facility
selection. This will also show you if there is already a selection defined that
suits your collection needs.
Example 2-2 shows a sample of the display produced with the SHOW
SELECTION /FORMAT=BRIEF command.

Creating a Facility Selection 2-5

Example 2-2

Display for SHOW SELECTION Using the Brief Format

9-MAY-1989 10:03

Facility Selection Information

Page 1
DECtrace Vl.0

Selection Name

Facility

Version

Class

Al DATA ENTRY

OA
TESTER
RDBVMS

(latest)
T4.1
V3.1

ALL
ALL
ALL

ACMSDBMS

ACMS
DBMS

(latest)
(latest)

PERFORMANCE
PERFORMANCE

RDB LOAD TEST

RDBVMS

V3.1

WORKLOAD

2~4.2

FULL Format

If you specify /FORMAT=FULL with the SHOW SELECTION command,

DECtrace displays a full description of facility selections stored in the
DECtrace administration database. You can display the description of a
single selection if you include its name on the command line. For example, the
following command would display the complete description of the FINANCE
selection:
$

COLLECT SHOW SELECTION FINANCE /FORMAT=FULL

The FULL format display includes the following information:
• Name of the facility selection
• User. name of the facility selection's creator
• · Facility name, version, and collection class for each facility specified in the
selection
Example 2-3 shows a sample of the display produced with the SHOW
SELECTION /FORMAT=FULL command.

2-6 Creating a Facility Selection

Example 2-3

Display for SHOW SELECTION Using the Full Format

9-MAY-1989 10:04

Facility Selection Information

Selection:
Conunent:

Page 1
DECtrace Vl.O

Created By:

ACMSDBMS
This is the facility selection for VAX ACMS
and VAX DBMS performance data.
JONES

Facility:
Version:
Collection class:

ACMS
(latest)
PERFORMANCE

Facility:
Version:
Collection class:

DBMS
(latest)
PERFORMANCE

2.4.3

NAMES_ONLY Format

If you specify /FORMAT=NAMES_ONLY with the SHOW SELECTION

command, DECtrace lists the names of the facility selections alphabetically.
This format is useful to determine the correct spelling of a selection name or
to determine if a particular selection name already exists in the DECtrace
administration database.
Example 2-4 shows a sample of the display produced with the SHOW
SELECTION /FORMAT=NAMES_ONLY command.
Example 2-4
9-MAY-1989 10:03

Display for SHOW SELECTION Using the Names Only Format
Facility Selection Information

Page 1
DECtrace Vl.0

Selection Name
Al DATA ENTRY
ACMSDBMS
RDB LOAD TEST

Creating a Facility Selection

2-7

3
Scheduling Data Collection
Scheduling data collection is the second step (see Figure 1-1) for general
users of the DECtrace software. Data collection is the process of gathering
event-based data from facilities and applications running on your system.
You define the process by means of the SCHEDULE COLLECTION command
which allows you to specify:
• Which data to collect
•

How much data to collect

•

When to collect data

• Where to store collected data
This chapter describes how to work with DECtrace data collections including:
• Scheduling data collection
•

Canceling data collection

•

Displaying information about collections scheduled in the DECtrace
administration database

Table 3-1 summarizes the DECtrace commands available to accomplish the
functions associated with DECtrace data collection.

Scheduling Data Collection

3-1

Table 3-1

Commands for Manipulating Data Collections

Command

Description

SHOW REGISTER

Shows the individual processes for which data can be
collected.

SCHEDULE COLLECTION

Schedules data collection based on the specified
qualifiers.

CANCEL COLLECTION

Stops data collection for an active collection. If a
collection is pending, it removes the collection from
the schedule.

SHOW COLLECTION

Shows data collection information in one of two formats,
either BRIEF or FULL.

SHOW HISTORY

Shows all error or informational messages that have
occurred during one or all data collections active on your
system.

3. 1 Choosing the Processes from Which to Collect Data
The amount of data collected during data collection is dependent on how many
processes on each node are collecting data. By default, DECtrace gathers
data from all processes that are using the facilities specified in your facility
selection. You can optionally select a subset of the processes that would
normally collect data.
For example, if you have two processes on your system which are running
different ACMS applications, you can choose to collect data from either process
or from both.

3. 1. 1 Process Registration
When an image that contains DECtrace service routine calls activates, it issues
a call to EPC$INIT which registers both the process and the facility with
DECtrace. DECtrace maintains a user-visible register of information about
these images and processes. The register information includes:
• Name of the image
• Name of the facilities that issued the DECtrace initialization information
• Image-specific registration identifier(s) (ID) for the process
• User name, process name, and process identification number (EPID) of the
process in which the facility is running
• Node on which the process is running

3-2 Scheduling Data Collection

Several facilities may register for each process. For example, a program named
TEST_PROG may use both RdbNMS and VAX DBMS. In this case, each time
a user runs TEST_PROG.EXE, that user's process will register both facilities
with DECtrace. The facilities remain registered until the image terminates.
Note that it is not necessary for TEST_PROG to contain any DECtrace service
routine calls. DECtrace collects the predefined events and items in RdbNMS
and VAX DBMS as they occur as part of TEST_PROG's execution.

3. 1.2

Using the Registration ID

A registration ID is an optional facility-specific character string that is known
to the facility only at run time. When a facility is invoked, it can optionally
pass a registration ID to the DECtrace Registrar by means of the EPC$INIT
service routine. The registration ID is useful in distinguishing separate images
that are using the same facilities. For example, if there are two processes on
your system running different ACMS applications, you can use the registration
ID to collect data from only one of them. ACMS provides the ACMS application
name as the registration ID.
DECtrace also registers process-specific information when an image containing
DECtrace service routine calls activates. The process-specific registration IDs
include the EPID, the image name, the user name, and the process name.
You use the /REGISTRATION_ID qualifier on the SCHEDULE COLLECTION
command to collect data from processes with a specific registration ID. This
qualifier is not a substitute for a facility selection. It provides additional
restrictions to what you will be collecting.
You can specify one or more registration IDs when you schedule data collection.
This is useful for collecting data from only a few of the processes that are
using the facilities listed in your facility selection. Only those processes whose
registration IDs match the specified values (and also contain at least one
facility specified in your facility selection) will collect data when data collection
begins. This allows you to greatly reduce the scope of your collection. For
example, the following command schedules a collection to gather data from one
user (WEBSTER) running a specific application (SCHEDULE.EXE):
$

COLLECT SCHEDULE COLLECTION COURSE SCHEDULE DANIEL.DAT/SELECTION=JUST RDB /NOCLUSTER - -$ /BEGINNING=09:00 /ENDING=11:30 -$ /REGISTRATION ID=(WEBSTER,WORKl: [TOOLS] SCHEDULE.EXE)
/PROTECTION= (G:W)
%EPC_S_SCHED, Data collection COURSE_SCHEDULE is scheduled
$

See Section 3.3.1 for more information on collecting per-user data.
The following example tells DECtrace to select those processes on the cluster
that have ORDER_ENTRY as a registration ID. Then DECtrace collects the
ACMS and RdbNMS data from those processes:

Scheduling Data Collection 3-3

COLLECT SCHEDULE COLLECTION ORDER WORK ORDERS.DAT /SELECTION=ACMS AND RDB /CLUSTER--$ /BEGINNING=09:00 /ENDING=lO:OO /REGISTRATION ID=ORDER ENTRY
%EPC_S_SCHED, Data collection ORDER_WORK is scheduled
$

Example 3-1 shows the DECtrace register after the collection ORDER_WORK
activates. ACMS and RdbNMS event data is collected from the following
processes on MYVAXl: SMITH_2 and WRITER and from the following
processes on MYVAX2: CONTRACT and JONES_2. Note that SMITH_2 also
registered the MY_FACILITY facility. Because MY_FACILITY is not included
in the facility selection, DECtrace does not collect data from it. In addition,
note that SECRETARY registered both ACMS and RdbNMS. However, the
process does not have the correct registration ID, so no data is collected from
it.
Process Registration Display

Example 3-1

12-JUN-1989 9:03:22.4

Registrations not collecting
Node :

MYVAXl

Process

Process Name

Facility

Version

RDBVMS
21444556 JONES
WORK$DISK: [FINANCE]DEBIT_CREDIT.EXE;ll

V3.1

21544675 SMITH
USER2: [GAMES]POKER.EXE;3

V3.l

21457890

RDBVMS

DBMS
MY FACILITY
WORK$DISK: [TOOLS)INVENTORY_CHECK.EXE;5

V4.1
V2.0

DATA ENTRY

Version

Registration ID

ACMS
RDBVMS
MY FACILITY
WORK$DISK: [FINANCE]BUDGET_UPDATE.EXE;24

V3.l
V3.l
V2.0

BUDGET ANALYSIS

21778902 JONES
ACMS
WORK$DISK: [FINANCE)DEBIT_CREDIT.EXE;ll

V3.1

BUDGET ANALYSIS

Node :

SMITH 2

Registration ID

MYVAX2

Process

Process Name

21778900

SECRETARY

Facility

DATA ENTRY

Registrations actively collecting

(continued on next page)

3-4 Scheduling Data Collection

Example 3-1 (Cont.)
Node:

MYVAXl

Process

Process Registration Display
Collection:

ACMS AND ROB

Registration ID

21457890 SMITH 2
ACMS
WOR.K$DISK: [TOOLS]INVENTORY_CHECK.EXE;5

V3.l

ORDER ENTRY

21567444 WRITER
ACMS
WOR.K$DISK: [TOOLS]SPELL_CHECK.EXE;5

V3.1

ORDER ENTRY

MYVAX2

Facility

Selection:
Version

Node :

Process Name

ORDER WORK

Collection:

Process

Process Name

21778888

ORDER WORK

Facility

Selection:

ACMS AND ROB

Version

Registration ID

CONTRACT

ACMS
RDBVMS
WORK$DISK: [TOOLS]INVENTORY_CHECK.EXE;5

V3.l
V3.1

ORDER ENTRY

21778905

JONES 2

V3.1
V3.l

ORDER ENTRY

ACMS
RDBVMS
USERl: [JONES.TESTS]ORDER_ENTRY_PROTO.EXE;l

3. 1.3

Displaying Information about Process Registration

The SHOW REGISTER command allows you to examine the current state of
process registration on your system or VAXcluster. The SHOW REGISTER
display is divided into the following segments:
•

Registrations with no facility definitions
These processes actually represent an error condition where a facility has
made a call to EPC$INIT, but there is no corresponding facility definition
in the DECtrace administration database. No data can be collected for an
undefined facility.

•

Registrations not collecting
These processes do not have any active collections collecting data from
them, but they are available for data collection if the proper collection is
scheduled.

•

Registrations actively collecting
These processes have active data collection occurring.

Example 3-2 shows a typical register display produced by the SHOW
REGISTER/CLUSTER command. In the example, three separate processes
are running the WEEKLY_CHECKS program which has registered three
facilities: RdbNMS and two facilities for which no facility definitions exist
in the DECtrace administration database. Another process is running the
INVESTMENTS program which registered two facilities: Rdb/VMS and NEW_
FORMS. Lastly, the MORGAN process is running the MAINT_EMP program

Scheduling Data Collection 3-5

which also registered RdbNMS and NEW_FORMS, but has a different
registration ID than the INVESTMENTS program. Note that the registration
ID is optional, and not all facilities choose to provide one.
Two local collections are active on the cluster: ALL_DAY is active on MYVAXl,
and WED_2ND_SHIFT is active on MYVAX2.
Example 3-2

Display Format for SHOW REGISTER/CLUSTER

2-AUG-1989 21:25

l?age 1
DECtrace Vl.0-0

Registrations with no Facility definitions
Node: MYVAXl
Process

l?rocess Name

00000040

Wed J?ayroll

Facility

Registration Id

2235 Payroll
2236 Stock Plan
DISK$PAYROLL: [PAYROLL.IMAGES]WEEKLY_CHECKS.EXE;80
Node: MYVAX2
Process

l?rocess Name

00000021

Monday Payroll

00000025

Tuesday Payroll

Facility

Registration Id

2235 Payroll
2236 Stock Plan
DISK$PAYROLL: [l?AYROLL.IMAGES]WEEKLY_CHECKS.EXE;80
2235 Payroll
2236 Stock Plan
DISK$PAYROLL: [PAYROLL.IMAGES]WEEKLY_CHECKS.EXE;80
Registrations not collecting
Node: MYVAXl
Process

Process Name

Facility

Version

00000021

Monday Payroll

RDBVMS

V3.l

Registration Id

DISK$PAYROLL: [l?AYROLL.IMAGES]WEEKLY_CHECKS.EXE;80
00000025

Tuesday Payroll

RDBVMS

V3.l

DISK$PAYROLL: [PAYROLL.IMAGES]WEEKLY_CHECKS.EXE;80
00000027

MORGAN

RDBVMS

V3.l

DISK$PAYROLL: [PAYROLL.IMAGES)MAINT_EMP.EXE;3

(continued on next page)

3-0 Scheduling Data Collection

Example 3-2 (Cont.)

Display Format for SHOW REGISTER/CLUSTER

Registrations actively collecting
Node: MYVAXl

Collection: ALL DAY

Selection: FORMS AND DB

Process

Process Name

Facility

Version

Registration Id

00000059

LINDA

NEW FORM
RDBVMS

Tl.0-1
V3.l

Investment Stream

DISK$PAYROLL: [PAYROLL.IMAGES]INVESTMENTS.EXE;3
00000040 Wed Payroll
RDBVMS
V3.1
DISK$PAYROLL: [PAYROLL.IMAGES]WEEKLY_CHECKS.EXE;80

2-AUG-1989 21:25

Page 2
DECtrace Vl.0-0

Registrations actively collecting
Node: MYVAX2
Process

Collection: WED 2ND SHIFT
Process Name

Facility

Selection: JUST FORMS

Version

Registration Id

00000027 MORGAN
NEW FORM Tl.0-1
DISK$PAYROLL: [PAYROLL. IMAGES] MAINT _ EMP .EXE; 3

Payroll Stream

Example 3-3 shows the processes registered on the local node (MYVAX2).
Example 3-3

Display Format for SHOW REGISTER/NOCLUSTER

2-AUG-1989 21:23

Page 1
DECtrace Vl.0-0

Registrations with no Facility definitions
Node: MYVAX2
Process

Process Name

00000021

Monday Payroll

00000025

Tuesday Payroll

Facility

Registration Id

2235 Payroll
2236 Stock Plan
DISK$PAYROLL: [PAYROLL.IMAGES]WEEKLY_CHECKS.EXE;80
2235 Payroll
2236 Stock Plan
DISK$PAYROLL: [PAYROLL.IMAGES]WEEKLY_CHECKS.EXE;80

(continued on next page)

Scheduling Data Collection 3-7

Example 3-3 (Cont.)

Display Format for SHOW REGISTER/NOCLUSTER

Registrations not collecting
Node: MYVAX2
Process

Process Name

Facility

Version

00000021

Monday Payroll

RDBVMS

V3.l

Registration Id

DISK$PAYROLL: [PAYROLL.IMAGES)WEEKLY_CHECKS.EXE;80
00000025

Tuesday Payroll

RDBVMS

V3.1

DISK$PAYROLL: [PAYROLL.IMAGES)WEEKLY_CHECKS.EXE;80
00000027

MORGAN

RDBVMS

V3.1

DISK$PAYROLL: [PAYROLL.IMAGES)MAINT_EMP.EXE;3
Registrations actively collecting
Node: MYVAX2
Process

Collection: WED 2ND SHIFT
Process Name

Facility

Selection: JUST FORMS

Version

Registration Id

00000027 MORGAN
NEW FORM Tl.0-1
DISK$PAYROLL: [PAYROLL.IMAGES]MAINT_EMP.EXE;3

Payroll Stream

3.2 Scheduling a Collection
You must schedule data collection on your system before DECtrace can begin
gathering data. Data collection criteria include the output file for the collected
data, the start and end times (or alternately, the duration), which facility
selection to use, and whether to collect from your entire cluster or just the local
node. Note that although you can schedule many collections on a node, only
one data collection can be active on a node at any time. The DECtrace software
does not allow you to schedule collections that overlap or run simultaneously.
DECtrace detects the conflict immediately when you attempt to schedule the
conflicting collection.
You can specify data collection to occur either locally or cluster-wide using the
![NO]CLUSTER qualifier. By default, SCHEDULE COLLECTION schedules
data collection to occur on every node in the cluster. To schedule a collection
on a subset of the cluster, you must log in to each node that you want data
collection to occur on and schedule a local collection on that node. Note that on
a standalone system, the /CLUSTER qualifier is ignored.
When you successfully schedule data collection, and again when the collection
activates, DECtrace writes a confirmation message to the history database.
You can examine the history database at any time with the SHOW HISTORY
command. See Section 3.5.2 for information about the history database and
the SHOW HISTORY command.

3-8

Scheduling Data Collection

3.2. 1 Scheduling Data Collection on a Standalone System
If you have DECtrace installed on a standalone system, you can collect data
from applications running on that system.

The following example schedules the collection MY_TEST to begin at 11:00
and end at 12:00 on the current day. The collection uses the facility selection
MY_SELECTION and runs on the local node. DECtrace stores the collected
data in the file MY_DATA.DAT in your default device and directory:
COLLECT SCHEDULE COLLECTION MY_TEST MY_DATA.DAT /SELECTION=MY SELECTION /BEGINNING=ll~OO /ENDING=l2:00
%EPC-S-SCHED, Data collection MY_TEST is scheduled
$

Alternately, you can use the /DURATION qualifier in place of the /ENDING
qualifier. You must specify the duration as a relative VMS time. For example:
COLLECT SCHEDULE COLLECTION MY TEST MY DATA.DAT /SELECTION=MY SELECTION /BEGINNING=ll~OO /DURATION="l:" /NOCLUSTER
%EPC-S-SCHED, Data collection MY_TEST is scheduled
$

$
-$

3.2.2 Scheduling Data Collection on a Cluster
If you run DECtrace on a system that is a member of a VAXcluster, your
collections are automatically scheduled to run on all nodes in the cluster.

The following example schedules the collection MY_FULL_TEST to begin at
10:00 and end at 11:00 on the current day. The collection uses the facility
selection MY_SELECTION and runs on every node in the cluster. DECtrace
stores the collected data in the file CLUSTER_DATA.DAT in your default
device and directory:
COLLECT SCHEDULE COLLECTION MY_FULL_TEST CLUSTER DATA.DAT $ /SELECTION=MY SELECTION -$ /BEGINNING=lO~OO /ENDING=ll:OO
-$ /PROTECTION= (W:W)
%°EPC-S-SCHED, Data collection MY_FULL_TEST is scheduled
$

3.2.3 Scheduling Data Collection on Part of a Cluster
If you run DECtrace on a VAXcluster but you do not want to collect data from
every node, use the /NOCLUSTER qualifier when you schedule your data
collection. This will schedule a local collection (data collection that occurs
only on your local node).

The following example schedules the collection MY_LOCAL_TEST to begin
at 11:00 and end at 12:00 on the current day. The collection uses the facility
selection MY_SELECTION and runs on the local node (that is, the node you
are currently logged in to). DECtrace stores the collected data in the file
LOCAL_DATA.DAT in your default device and directory:

Scheduling Data Collection 3-9

COLLECT SCHEDULE COLLECTION MY LOCAL TEST LOCAL DATA.DAT $ /SELECTION=MY SELECTION -$ /BEGINNING=ll-;-00 /ENDING=12: 00 ~) /NOCLUSTER
%EPC-S-SCHED, Data collection MY_LOCAL_TEST is scheduled

To schedule data collection on a subset of the cluster, you must log in to each
node that you want data collection to occur on and schedule a local collection
on that node. Note that you should use a different name for the data files
produced by each of these collections. One suggestion is to include the node
name as part of the data file name. If you do not use different names for the
data files, DECtrace uses the file version number to distinguish each file. The
individual data files can be combined later using the FORMAT command. See
Section 4.2 for information on combining multiple data files.
Example 3-4 shows a sample command procedure that schedules a local
collection with the node name included as part of both the collection and data
file names.
Example 3-4

Sample Command Procedure for Starting a Local
Collection

$!
$!

LOCAL COLLECTION .COM

$! This procedure starts DECtrace data collection using the
$! node name as part of both the collection name and the data file
$ ! name.
$!

$! Find the name of the local node and append it to the collection
$! and data file names
$!
$ node name = F$GETSYI ("NODENAME")
$ coll;ction name ="MY COLL ''node name'"
$ data_file -= "DATA_"node_name' .DAT"
$
$ Put your facility selection name and start and end times here:
$

$ selection name = "MY SELECTION"
$ start tim;
"12:00"$ end time
= "13:00"
$
$ Schedule your local data collection
$
$ COLLECT SCHEDULE COLLECTION 'collection name' 'data file' /SELECTION='selection name' /BEGIN='start time' /END='end time' /NOCLUSTER /PROTECTION=(W:W) $ EXIT

3-1 O Scheduling Data Collection

If you have the VMS OPER privilege, you can use the VMS System

Management (SYSMAN) utility to schedule local data collection on nodes
in your cluster without logging in to each node. 1 SYSMAN is a utility that
centralizes the management of nodes and clusters by allowing you to define an
environment that can be a particular node, a group of nodes, or a cluster. You
can perform tasks on all nodes in the environment from your local node. The
following example shows how you can schedule local data collection on nodes
MYVAXl and MYVAX2 from your local node.
$ RUN SYS$SYSTEM:SYSMAN
SYSMAN> SET ENVIRONMENT/NODE=(MYVAX1,MYVAX2)
%SYSMAN-I-ENV, Current Command Environment:
Individual nodes: MYVAX1,MYVAX2
Username SMITH will be used on nonlocal nodes
SYSMAN> DO @LOCAL COLLECTION.COM
%SYSMAN-I-OUTPUT, Corrunand execution on node MYVAXl
%SYSMAN-I-OUTPUT, Corrunand execution on node MYVAX2
SYSMAN> EXIT
$

3.3 Data Collection Files
When you schedule data collection, you can specify one or many data files to
store the event data (refer to the SCHEDULE COLLECTION command in
Chapter 7 for details). In addition, one or many different executable images
(running in the context of one or many processes) that are collecting data on
the local system or VAXcluster can record the data in a common data collection
file. By default, there is one data collection file for all of the data related to a
particular collection. However, if the amount of data collected is too great for
the I/O bandwidth of the disk where the data file exists, you can specify more
than one file when scheduling data collection. In this case, each data file would
be on a different disk device. When you specify more than one file, DECtrace
performs a round-robin style load balancing among all executable images that
collect data. See Section 4.2 for information on how to combine these multiple
data files after data collection has ended.
The following example schedules data collection using three data collection
files, each on a separate device:
$

COLLECT SCHEDULE COLLECTION TSTVAX WORKLOAD USERl: [SMITH.DATA]TST1.DAT,USER2:(DATA]TST2.DAT, -$ USER3: [DATA]TST3.DAT /SELECTION=ACMS AND RDB =$ /BEGIN=09:00 /END=l7:00 /CLUSTER
-

If OPER is not a default privilege for your process, you must use the SET PROFILE
/PRIVILEGE=OPER command in SYSMAN. Refer to the VMS SYSMAN Utility Manual for
information about the SYSMAN utility.

Scheduling Data Collection 3-11

Alternately, you could use a file list, which is a file containing a list of
file specifications to use as output files. Note that the /FILELIST qualifier
is position-dependent; you must specify it on the second parameter to the
command. For example:
$

COLLECT SCHEDULE COLLECTION TSTVAX WORKLOAD $ DATA LIST.TXT /FILELIST /SELECTION=ACMS_AND_RDB /BEGIN=09:00 /END=17:00 /CLUSTER

Each file specification must be on a separate line within the file list. For
example:
USERl: [SMITH.DATA]TSTl.DAT
USER2: [DATA]TST2.DAT
USER3: [DATA)TST3.DAT

3.3. 1 File Protection Schemes
DECtrace uses the default file protection for your proces_s when creating the
data collection file(s) for a collection. For a process to record event data to your
file, it must have write access to that file. Use the /PROTECTION qualifier to
the SCHEDULE COLLECTION command to automatically set the protection
on your data collection files. Note that the data collection files are created
immediately when the collection is scheduled, not when the collection becomes
active.
The format of the qualifier is:
/PROTECTION=(ownership:access[, ... ])

Where:
• OWNERSHIP is one of the following: (S)ystem, (O)wner, (G)roup, or
(W)orld.
• ACCESS is any combination of the following: (R)ead, (W)rite, (E)xecute, or
(D)elete.
If you do not specify a value for each ownership category, or if you omit the

/PROTECTION qualifier, the DECtrace software applies the current default
protection for each unspecified category. If the data collection file replaces a
previous version, then the protection on the old file is used on the new one.
The following example schedules a collection where all members of the user's
UIC-based group have write access to the data collection file:
$ COLLECT SCHEDULE COLLECTION ALL DAY MONDAY.DAT $ /SELECTION=EVERYTHING /BEGIN=9~00 /END=17:00 -

=$ /PROTECTION=(G:W}

3-12 Scheduling Data Collection

3.4 Canceling Data Collection
You can cancel data collection that is active or pending with the CANCEL
COLLECTION command. When you cancel active data collection, DECtrace
stops recording data for the collection but does not delete the collection's
data file(s). You can format and create reports from the data file(s) as if the
data collection had run to completion. DECtrace also writes a message to
the history database indicating that the data collection has been cancelled.
You can examine the history database at any time with the SHOW HISTORY
command. See Section 3.5.2 for information about the history database and
the SHOW HISTORY command.
When you cancel a collection it does not terminate immediately, but is set to an
aborting state. For an active collection, the Registrar process (or processes in
a VAXcluster environment) sends a "Stop collecting'' message to each process
that is recording event data. This communication takes place very quickly,
but if you cancel a collection and immediately enter the SHOW COLLECTION
command, your collection will still exist in an aborting state. A collection that
is aborting is indicated in the SHOW COLLECTION display by two asterisks
( ** ) next to the entry. Whenever you cancel an active collection you receive an
informational message from the DECtrace Registrar stating that the collection
has been set to the aborting state:
$ COLLECT CANCEL COLLECTION TEMP /NOCONFIRM
%EPC-S-SCHED_ABTNG, Data collection TEMP has been set to aborting

In a cluster, CANCEL COLLECTION cancels data collection either locally
or cluster-wide depending on how the collection was originally scheduled.
If you scheduled data collection with the /NOCLUSTER qualifier, CANCEL
COLLECTION cancels the collection at the local node. If you scheduled data
collection with the /CLUSTER qualifier, CANCEL COLLECTION cancels the
collection on all nodes in the cluster. Note that you cannot cancel collections
from individual nodes in a cluster environment if you scheduled the collection
using /CLUSTER.
The following example cancels the collection MYTEST, which was originally
schedule to run on the local node:
$ COLLECT CANCEL COLLECTION MY TEST /NOCONFIRM
%EPC_S_SCHED_CANCEL, Collection-MY_TEST is cancelled.

You can cancel all of the collections (active or pending) that use a particular
facility selection if you specify the /SELECTION qualifier. This option is useful
if you typically schedule multiple data collections referencing the same facility
selection. It is also needed when you want to delete a facility selection. To do
this, you must first cancel all collections using that selection.

Scheduling Data Collection 3-13

The following example cancels all data collections that are scheduled with the
facility selection TEMP_SELE CTI ON:
$ COLLECT CANCEL COLLECTION /SELECTION=TEMP_SELECTION /NOCONFIRM
%EPC_S_SCHED_CANCEL, Collection MY COLL MYVAXl is cancelled.
%EPC S SCHED CANCEL, Collection MY COLL MYVAX2 is cancelled.
%EPC=S=SCHED=CANCEL, Collection TEMP_TEST is cancelled.

3.5 Displaying Information about Data Collection
This section describes the commands that allow you to examine the status of
data collection on your system. The actual recording of event data is the third
step (see Figure 1-1) in the DECtrace collection process. You can examine the
schedule of active and pending collections, and you can display any errors,
warnings, or informational messages encountered by the collections.

3.5. 1 Displaying the Schedule for Data Collection
Collections exist on your system in either an active or a pending state.
Because only one collection can be active on a particular node at any time, it is
important to know when data collection is scheduled to occur.
The DECtrace administration database maintains the schedule of data
collection on your VAX.cluster. You can display information about scheduled
collections with the SHOW COLLECTION command.
Example 3-5 shows a sample of the display produced with the SHOW
COLLECTION/FORMAT=BRIEF command. The arrow ( ->) next to the
line describing the MY_FULL_TEST collection indicates that the collection is
active. Note that only one collection can be active on a node at any time.

3-14

Scheduling Data Collection

Example 3-5

Display for SHOW COLLECTION Using the Brief Format

9-MAY-1989 10:09
Brief Report

Scheduled Collections

Page 1
DECtrace Vl.O

Collections scheduled for the entire cluster

Selection Name

Collection Name

Start

End

MY SELECTION

MY FULL TEST

9-MAY-89 10:00

9-MAY-89 11:00

DECtrace Collection Schedule for node MYVAXl
Selection Name

Collection Name

Start

End

MY SELECTION

MY COLL MYVAXl

9-MAY-89 12:00

9-MAY-89 13:00

DECtrace Collection Schedule for node MYVAX2
Selection Name

Collection Name

Start

End

MY SELECTION

MY COLL MYVAX2

9-MAY-89 12:00

9-MAY-89 13:00

DECtrace Collection Schedule for node SMTHVX
Selection Name

Collection Name

MY SELECTION

MY LOCAL TEST

3.5.2

Start

End

9-MAY~89

11:00

9-MAY-89 12:00

Displaying the History for Collections

The DECtrace history database contains a record of the informational and
error messages that are encountered during data collection. The SHOW
HISTORY command allows you to discover if any errors occurred during
a collection (or many collections). You can also display any informational
messages that occurred during data collection. An example of an informational
message is a confirmation message sent back to DECtrace by a process that has
actually begun data collection, or a message that a process has registered with
DECtrace and is available for collection. Displaying informational messages
is most useful for facility developers and support personnel, while displaying
errors is useful for general users.
The format of the SHOW HISTORY command is:

SHOW HISTORY collection-name

!BEFORE=" time"
![NOJCLUSTER
IFORMAT=type
INODE=node-name
!OUTPUT=file-spec
!SINCE=" time"

Valid format types are ERROR, INFORMATIONAL, and ALL which includes
both errors and informational messages.

Scheduling Data Collection 3-15

You should examine the history database during and after data collection to
verify that the collection started successfully and did not encounter any serious
errors. You should always examine the history before formatting your collected
data. Note that you can format data files from collections that failed during
active data collection, but you might not achieve the full results that you
wanted.
Note that an error encountered by a process which has registered with
DECtrace is not related to any collection for which the process might be
recording event data. If you use the COLLECTION-NAME parameter to the
SHOW HISTORY command, you do not see errors or messages generated by
the individual processes. For example, if a process is unable to record data
due to a file protection violation on the data collection file, the message is
on the SHOW HISTORY /FORMAT=ALL report; not the report for a specific
collection.
Example 3-6 shows the display for the SHOW HISTORY/FORMAT=ERROR
command and Example 3-7 shows the display for the SHOW HISTORY
/FORMAT=INFORMATIONAL command.
Example 3-6

Display for SHOW HISTORY /FORMAT=ERROR

04-APR-1990 10:03
Data Collection History
DECtrace error history for cluster

Page 1
DECtrace Vl.O

Collection:
Date and Time

EPID

Process Name

Registration Id

03-APR-1990 12:34:15.41 31600062 DBMS USERl
%SYSTEM-W-DEVICEFULL, device full - allocation failure
%EPC-E-HST_PRCERR, Error received from collecting process
03-APR-1990 12:34:16.48 31600062 ACMS USERl
Personnel
%SYSTEM-W-DEVICEFULL, device full - allocation failure
%EPC-E-HST_PRCERR; Error received from collecting process
04-APR-1990 09:47:42.73 31600006 DB MANAGER
%EPC-E-OPEDCF, Error opening data collection file
%EPC-E-HST_PRCERR, Error received from collecting process
04-APR-1990 09:47:47.07 316000D6 DB MANAGER
%EPC-E-HST PRCERR, Error received from collecting process
%SYSTEM~F-NOPRIV, no privilege for attempted operation

3-16

Scheduling Data Collection

Example 3-7

Display for SHOW HISTORY /FORMAT=INFORMATIONAL

04-APR-1990 10:05
Data Collection History
DECtrace informational history for cluster

l?age 1
DECtrace Vl.O

Collection: El?C$IVl? COLLECTION
Node: MYVAXl
Date and Time

El?ID

Process Name

Registration Id

03-APR-1990 15:03:24.74 38AOOB79
RTA16:
%El?C-S-HST_SCHED, Data collectio~ scheduled
03-APR-1990 15:03:29.38 38A0124E EPC$REGISTRAR
%EPC-S-HST_START, Collecting started

EPC$IVl?_SELECTION

03-APR-1990 15:03:53.55 38AOOB79
RTA16:
%EPC-S-HST_START_COLL, Process started collecting data
03-APR-1990 15:04:55.20 38AOOB79
RTA16:
%EPC-S-HST_ABORT, Collection abo~ting
03-APR-1990 15:04:58.04 38A0124E EPC$REGISTRAR
%EPC-S-HST_END, Collecting ended
03-APR-1990 15:05:01.50 38A0124E EPC$REGISTRAR
%EPC-S-HST_DELETED, Collection deleted

Scheduling Data Collection 3-17

4
Generating Reports

The DECtrace software can generate statistical reports based on your collected
data. This chapter describes how to manipulate your raw data collection files
into formatted reports. It describes how to:
• Merge data collection files
•

Format data collection files into either an RdbNMS database or a VAX
RMS file

•

Generate reports based on the formatted RdbNMS database

Formatting and reporting are the fourth and fifth steps (see Figure 1-1) for
general users of DECtrace. The final step is interpretation and analysis of the
DECtrace reports.
Table 4-1 summarizes the DECtrace commands available to accomplish the
functions associated with reporting.
Table 4-1

Commands for Generating Reports

Command

Description

FORMAT

Formats one or more DECtrace data files into a formatted data file or
database.

REPORT

Generates a report based on formatted data from one or more collections.

Generating Reports 4-1

4. 1 Overview of Reporting
After data collection is performed, the data collection files can be merged and
formatted into a single RdbNMS database or VAX RMS file. The formatted
database or file can contain data from one or more different collections as long
as an identical facility selection was used for each collection. The collections
can have run on the same node or on many different nodes. This capability
provides a convenient way to maintain all the data collected for one or several
collections.
You can write your own customized reports using the published formatted
database and file layouts described in Appendix A.

4.2 Merging and Formatting Your Data Files
The FORMAT command is used to merge and format collected data. The first
step in formatting is to decide whether you want to generate an RdbNMS
database or a VAX RMS file. The advantage of generating an RdbNMS
database is that you can generate DECtrace reports. In either case, you can
generate reports using a fourth-generation language or programming language
containing embedded calls to either RdbNMS or VAX RMS.
If you choose to format the data into an Rdb/VMS database, you can optionally
choose to store the record definitions in VAX CDD/Plus using the /CDDPLUS_
DEFINITIONS qualifier. Of course, this feature is only available if CDD/Plus
is currently installed on your system. If you format the data collection files
without the /CDDPLUS_DEFINITIONS qualifier and later decide that you
want to use CDD/Plus, you can use the INTEGRATE command ofRDO or SQL.

4.2. 1 Merging and Formatting the Collected Data into an
Rdb/VMS Database
Multiple data collection files can be merged into a single formatted database.
The following example formats the data in two files (COLLl_FILEl and
COLL1_FILE2) into an Rdb/VMS database called COLL_DB.
$ COLLECT FORMAT/TYPE=RDBVMS COLLl_FILEl,COLLl_FILE2 USERl:COLL_DB

If you wish to merge two more data collection files from another collection
(using the same facility selection) into the same Rdb/VMS database that was
just created, issue the following command:
$ COLLECT FORMAT/MERGE/TYPE=RDBVMS COLL2_FILE1,COLL2_FILE2 _$ USERl:COLL_DB

Formatting of a single data collection file is done using batch update
transaction mode. This speeds up the formatting operation, especially for
very large files. When formatting several data collection files into a single
formatted database, you should format the largest file first and then merge the
remaining files into the new database.

4-2

Generating Reports

4.2.2

Merging and Formatting the Collected Data into a VAX
RMS File

To merge two data collection files from a single collection into a new VAX RMS
file called COLL_FILE, issue the following command:
$

COLLECT FORMAT/TYPE=RMS COLLl_FILEl,COLLl_FILE2 USERl:COLL_FILE

If you want to merge two more data collection files from another collection

(using the same facility selection) into the same VAX RMS file that was just
created, issue the following command:
$
....:_$

COLLECT FORMAT/MERGE/TYPE=RMS COLL2_FILE1,COLL2_FILE2 USERl : COLL FILE

4.3 Formatting Optimization
You can improve response time for formatting data collection files into an Rdb
NMS database by specifying a set of optimization parameters on the FORMAT
command. The parameters are part of the /RDBVMS_OPTIMIZATION
qualifier, which has the following format:
/RDBVMS_OPTIMIZATION = (parame1er=value[, ... ])

Table 4-2 shows the optimization parameters and their defaults.
Table4-2

Format Optimization Parameters

Optimization Parameter

Default Value

ALLOCATION

2000 database pages

BUFFER_SIZE

30 blocks

[NO]JOURNAL

JOURNAL

MIN_EXTENT

500 pages

NUM_BUFFERS

30 buffers

[NO]STRING_OPTIMIZATION

STRING_OPTIMIZATION

[NONIEWS

VIEWS

The following example uses the optimization parameter to format a large data
collection file into a formatted RdbNMS database:
$ COLLECT FORMAT VERY BIG FILE.DAT BIG DATABASE _$ /RDBVMS OPTIMIZATION=(NOJOURNAL, ALLOCATION=lOOOO _$ STRING OPTIMIZATION=(FIRST=32, SEGMENT=64) _$ NOVIEWS)

See the description of the FORMAT command in Chapter 7 for a description of
each optimization parameter.

Generating Reports 4-3

4.4 Report Types
DECtrace can generate tabular reports based on the data in an RdbNMS
formatted database. Table 4-3 lists the three different types of reports that
you can produce.
Table 4-3

DECtrace Reports

Type of Report

Description

DETAIL

Actual values of the items collected for each event.

FREQUENCY

Event occurrence summary based on a selected time
interval.

SUMMARY (default)

Summary statistics about the collected data.

The example reports in this section use COBOL-like pictures to describe the
format of the data in the reports. Table 4-4 shows what each data format
means.
Table 4-4

Data Formats

Format

Meaning

DD-MMM-YYYY

Date format (for example, 09-May-1989).

HH:MM:SS.HH

Time format (for example, 11:42:23.98).

A printable ASCII character within a text field.

A numeric character, 0 through 9 1 •

A numeric character, 0 through 9 1 . Leading zeros are replaced
with blanks. If the numeric field is negative, a minus sign is
displayed immediately to the left of the most significant digit.

. (period)

A decimal point.

If a numeric value overflows the field, then the field is filled with asterisk (*)characters.

In the examples of reports, an exclamation point ( ! ) indicates a comment about
the layout of the report. The comment describes the line immediately to its
left. Note that the .comment does not appear in the actual report.

4-4

Generating Reports

4.4.1

Detail Report

The Detail Report is useful for application developers (for debugging purposes)
who want to see the actual values of the items for each start, end, or point
event record. The display for each event on the Detail Report consists of the
time and date stamp when the event record was recorded, and all of the report
items for the event records meeting the selection criteria specified on the
REPORT command. If the event was a duration event, the report displays the
values of the items collected on both the start and end events.
Example 4-1 shows the format of a basic report. Two events are displayed in
this report, each with three items (one string and two numeric items). The
first event is a point event for which five occurrences were recorded. The
second event is a duration event for which the items associated with both the
start and end events for one event occurrence are displayed. An index page,
which follows all reports consisting of more than one event, is not shown in the
example.
Example 4-1

Display for Detail Report

DD-MMM-YYYY HH:MM XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX PageZZZ9
Selection: XXXXXXXXXXXXXXX
DECtrace Vl.0-0
Event XXXXXXXXXXXXXX In Facility XXXXXXXX Version XXXXXXXXX ! Event 1
For Collections XXXX,XXXX
For Nodes XXXXXX,XXXXXX
These lines indicate optional
For PID
XXXXXX,XXXXXX
restrictions placed on the report
For Image XXXXXX,XXXXXX
using the RESTRICTIONS option
With XXXXXXXXXXXXX = XXXXXXXXXX
And xxxxxxxxxx = xxxxxxx
For Point event.
Time stamp
DD-MMM-YYYY HH:MM:SS.HH
DD-MMM-YYYY HH:MM:SS.HH
DD-MMM-YYYY HH:MM:SS.HH
DD-MMM-YYYY HH :MM: SS. HH
DD-MMM-YYYY HH:MM:SS.HH

xxxxxxxxxxxx xxxxxxxxx xxxxxxxxx
xxxxxxxxxxxx ZZZZZZZZ9 ZZZZZZZZ9
xxxxxxxxxxxx ZZZZZZZZ9 ZZZZZZZZ9
xxxxxxxxxxxx ZZZZZZZZ9 ZZZZZZZZ9
xxxxxxxxxxxx ZZZZZZZZ9 ZZZZZZZZ9
xxxxxxxxxxxx ZZZZZZZZ9 ZZZZZZZZ9

Item Headers
1st occurrence
2nd occurrence

Version XXXXXXXXX ! Event 2

(continued on next page)

Generating Reports 4-5

Example 4-1 (Cont.)

Display for Detail Report

! For Duration Event

Time stamp

XXXXXXXXXXXX

XXXXXXXXX

Item Headers

DD-MMM-YYYY HH:MM:SS.HH
DD~MMM-YYYY HH:MM:SS.HH

XXXXXXXXXXXX
XXXXXXXXXXXX

ZZZZZZZZ9
ZZZZZZZZ9

Start event
End event

·Headers and values for text are left justified. The headers and values for
numeric report items are right justified. See Section 4.5.4 for an explanation of
how this text is wrapped.
The item headers. are defined in the facility definition. You can override
the default header. text and width using the reporting options described in
Section 4.8.
Example 4-2 shows a Detail Report based on data collected from the ATM
sample application. The following example shows the command used to
generate the report:
$ COLLECT REPORT ATM DATA.RDB /TYPE=DETAIL

Example 4-2

Sample Detail Report Based on ATM Data

16-FEB-1990 16:46
Selection: JUST ATM
Event:

Detail Report

BALANCE EVENT

Timestamp
16-FEB-1990 16:16:11.87

In Facility:

ATM SAMPLE

PAGEFAULTS

381
381

Version:

Vl.O

Elapsed

BUFFERED IO

CPU TIME

CURREN
T PRIO

3.42

3966

1509

3979

1511

16-FEB-1990 16:16:15.29
DIRECT IO

Page 1
DECtrace Vl.0-0

PAGEFAULT
I Os

VIRTUAL
SIZE

GLOBAL WS

PRIVATE WS

5679

129

5112

397

5686

129

5112

397

WORKING
SET SIZ
1109
1109

(continued on next page)

4-6 Generating Reports

Example 4-2 (Cont.)

Sample Detail Report Based on ATM Data

================= Next Occurrence ====================
Timestamp
16-FEB-1990 16:16:23.16

Elapsed

BUFFERED IO

CPU TIME

CURREN
T PRIO

0.96

4033

1517

16-FEB-1990 16:16:24.12

4046

1519

DIRECT IO

PAGEFAULTS

PAGEFAULT
I Os

VIRTUAL
SIZE

GLOBAL WS

PRIVATE WS

381

5695

129

5112

108

397

381

5695

129

5112

108

397

WORKING
SET SIZ
1109
1109

================= Next Occurrence ====================

16-FEB-1990 16:46
Selection: JUST ATM
Event:

Detail Report

DEPOSIT EVENT

Timestamp
16-FEB-1990 16:16:18.67

In Facility:

Page 6
DECtrace Vl.0-0

ATM SAMPLE

Vl.O

Version:

Elapsed

BUFFERED IO

CPU TIME

3.38

3998

1513

4014

1515

16-FEB-1990 16:16:22.05

CURREN
T PRIO

DIRECT IO

PAGEFAULTS

PAGEFAULT
I Os

VIRTUAL
SIZE

GLOBAL WS

PRIVATE WS

381

5686

129

5112

397

381

5695

129

5112

108

397

WORKING
SET SIZ
1109
1109

(continued on next page)

Generating Reports 4-7

Example 4-2 (Cont.)
Sample Detail Report Based on ATM Data
================= Next Occurrence ====================
Time stamp
16-FEB-1990 16:17:03.31

Elapsed

BUFFERED IO

CPU TIME

CURREN
T l?RIO

6.08

4256

1544

4272

1546

16•FEB-1990 16:17:09.39
DIRECT IO

PAGEFAULTS

PAGEFAULT
I Os

VIRTUAL
SIZE

GLOBAL WS

PRIVATE WS

381

5695

129

5112

108

397

381

5695

129

5112

108

397

WORKING
SET SIZ
1109
1109

================= Next Occurrence ====================

Event:

Page 8
DECtrace Vl.0-0

Detail Report

16-FEB-1990 16:46
Selection: JUST ATM
WITHDRAW EVENT

Time stamp

In Facility:
Elapsed

ATM SAMPLE
BUFFERED IO

Vl. 0

Version:
CPU TIME

CURREN
T l?RIO

16-FEB-1990 16:16:46.19

2.34

16-FEB-1990 16:16:48.53

4127

1531

4143

1532

DIRECT IO

PAGEFAULTS

PAGEFAULT
I Os

VIRTUAL
SIZE

GLOBAL WS

PRIVATE WS

381

5695

129

5112

108

397

381

5695

129

5112

108

397

WORKING
SET SIZ
1109
1109

(continued on next page)

4-8

Generating Reports

Example 4-2 (Cont.)

Sample Detail Report Based on ATM Data
Detail Report

16-FEB-1990 16:46
Selection: JUST ATM

Page 9
DECtrace Vl.0-0

Report Index
Facility Name

Event Name

Page

ATM SAMPLE
ATM SAMPLE
ATM SAMPLE

BALANCE EVENT
DEPOSIT EVENT
WITHDRAW EVENT

1
6
8

4.4.2

Frequency Report

The Frequency Report presents the number of event occurrences for each
event, which match the selection criteria specified on the REPORT command.
The layout of the report is similar to the Summary Report (see Section 4.4.3)
except that it displays time period occurrences instead of statistics.
Generally, you use the /INTERVAL qualifier when you generate Frequency
Reports. This qualifier specifies the time interval for which event occurrences
are calculated. The time interval must be one second, one minute, or one hour,
specified as one of the following keywords:
SECONDS
MINUTES (default)
HOURS
Example 4-3 shows the format of a basic report generated using the
/INTERVAL=SECONDS qualifier. A count is displayed for each second
during which at least one event occurrence was recorded. An index page,
which follows all reports consisting of more than one event, is not shown in the
example.

Generating Reports 4-9

Example4-3

Display for Frequency Report Using /INTERVAL=SECONDS

DD-MMM-YYYY HH:MM xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx PageZZZ9
Selection: XXXXXXXXXXXXXXX
DECtrace Vl.0-0
Event XXXXXXXXXXXXXX In Facility XXXXXXXX Version XXXXXXXXX ! Event 1
For Collections XXXX,XXXX
For Nodes XXXXXX,XXXXXX
For PID
XXXXXX,XXXXXX
These lines indicate optional
For Image XXXXXX,XXXXXX
restrictions placed on the report
With XXXXXXXXXXXXX = XXXXXXXXXX
using the RESTRICTIONS option
And xxxxxxxxxx = xxxxxxx
Time Period

Occurrences

DD-MMM-YYYY HH:MM:SS
DD-MMM-YYYY HH:MM:SS
DD-MMM-YYYY HH:MM:SS
DD-MMM-YYYY HH:MM:SS

ZZZZZZZZZZ9
ZZZZZZZZZZ9
ZZZZZZZZZZ9
ZZZZZZZZZZ9

DD-MMM-YYYY HH:MM XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX PageZZZ9
Selection: XXXXXXXXXXXXXXX
DECtrace Vl.0-0
Event XXXXXXXXXXXXXX In Facility XXXXXXXX
For Collections XXXX,XXXX
For Nodes XXXXXX,XXXXXX
For PID
XXXXXX,XXXXXX
For Image XXXXXX,XXXXXX
With XXXXXXXXXXXXX = XXXXXXXXXX
And xxxxxxxxxx = xxxxxxx
Time Period

Occurrences

DD-MMM-YYYY HH:MM:SS
DD-MMM-YYYY HH:MM:SS
DD-MMM-YYYY HH:MM:SS
DD-MMM-YYYY HH:MM:SS
DD-MMM-YYYY HH:MM:SS
DD-MMM-YYYY HH:MM:SS

ZZZZZZZZZZ9
ZZZZZZZZZZ9
ZZZZZZZZZZ9
ZZZZZZZZZZ9
ZZZZZZZZZZ9
ZZZZZZZZZZ9

Version XXXXXXXXX ! Event 2

For duration events, only occurrences of completed start and end pairs are
counted. A diagnostic message is presented for incomplete pairs.
Example 4-4 shows a Frequency Report based on data collected from the
ATM sample application. The following example shows the command used to
generate the report:
$ COLLECT REPORT ATM DATA.ROB /TYPE=FREQUENCY -

/INTERVAL=MINUTES-

Although this report provides the least information of the three report types,
it is useful for tracing the execution of an instrumented application. For
example, in the ATM report it is apparent that the BALANCE_EVENT occurs
much more frequently than the other events. By examining the time-stamps on
the events (perhaps generating a new report using /INTERVAL=SECONDS), it
becomes evident that customers are checking their account balance before and
after each transaction. Based on this information, the application programmer

4-1 O Generating Reports

might choose to modify the ATM program to automatically display the new
balance after each transaction.
Example 4-4

Sample Frequency Report Based on ATM Data

16-FEB-1990 16:43
Selection: JUST ATM
Event:

BALANCE EVENT

Time Period

In Facility:

Vl.0

Version:

5
1
4

16-FEB-1990 16:43
Selection: JUST ATM

Page 2
DECtrace Vl.0-0

Frequency Report

DEPOSIT EVENT

Time Period

ATM SAMPLE

Occurrences

16-FEB-1990 16:16:00
16-FEB-1990 16:17:00
16-FEB-1990 16:20:00

Event:

Page 1
DECtrace Vl.0-0

Frequency Report

In Facility:

ATM SAMPLE

Vl.O

Version:

Occurrences

16-FEB-1990 16:16:00
16-FEB-1990 16:17:00

1
1

%EPC-I-NOEND, 1 Start Event Records had no matching End

16-FEB-1990 16:43
Selection: JUST ATM
Event:

Frequency Report

WITHDRAW EVENT

Time Period

In Facility:

ATM SAMPLE

Page 3
DECtrace Vl.0-0

Vl.O

Version:

Occurrences

16-FEB-1990 16:16:00

16-FEB-1990 16:43
Selection: JUST ATM

Frequency Report

Page 4
DECtrace Vl. 0-0

Report Index
Facility Name

Event Name

Page

ATM SAMPLE
ATM SAMPLE
ATM SAMPLE

BALANCE EVENT
DEPOSIT EVENT
WITHDRAW EVENT

4.4.3

2
3

Summary Report

The Summary Report presents up to 7 different statistics for each report
item that is specified in the selection criteria of the REPORT command. The

Generating Reports 4-11

statistics are: maximum, minimum, mean, standard deviation 1, count (number
of occurrences), total, and 95th percentile2 . The sample standard deviation is
computed by the following formula, where n is the sample size and Xi is the
value of each sample element:
Samplei =

n Lf=l X'f - (Lf=l Xi)2
n(n - 1)

The Summary Report contains an event group for each value of a groupable
item and for all events with the same event name. This capability allows
for subtotal summaries to be calculated for each groupable item. This also
allows grand total summaries to be calculated for each event name. Because
Example 4-5 contains 2 groupable items, there is a separate event group for
each different value of the second groupable item. This is followed by an event
group which presents a subtotal of the report items for all event groups for
each value of the first groupable item. At the end of all summary groups for an
event name, a summary group presents a grand total for all report items.
Table 4-5 describes the parts contained in each event group on the Summary
Report.

The various subvalues used to calculate the sample standard deviation are stored as
D-floating data types. They have a range of 0.29 * lOE-38 to 0.29 * 10E38 with 16 decimal
places of precision. The major implication is that if the squared elements summed requires
more than 16 decimal places, a roundoff error may occur.
2
The 95th percentile is based on the standard deviation. It assumes a relatively normal
distribution with a sample· size, n, greater than 1000. Based on sample sizes greater than
1000, a confidence level of 95% can be computed as 1.96 units away from the standard
deviation.

4-12 Generating Reports

Table 4-5

Parts of a Summary Report Event Group

Part

Meaning

Groupable
item values

Each value is on a separate line and left justified. The headers that
precede each groupable item are aligned. See Section 4.5.1 for an
explanation for how these items are wrapped. The groupable item
values are followed by a blank line.

Report item
headers

The text of the header is defined in the facility definition for the event
or can be specified by the user (see the ITEM report option for details).
The headers for the text items are left justified. Numeric headers are
right justified. See Section 4.5.3 for an explanation of how headers are
wrapped~ Each report item is separated by two blank columns.

Statistics

The format for the Statistics are:
Statistic

Elapsed Time

Minimum

ZZZZZ9.99

zzzz:z.zzz9

Maximum

ZZZZZ9.99

zzzz:z.zzzg

Mean

ZZZZZ9.99

ZZZZ:Z.9.99

ZZZZZ9.99

ZZZZ:Z.9.99

ZZZZZ9.99

ZZZZ:Z.9.99

zzzzzzzz9

ZZZZ:Z.ZZZ9.

Std Dev
95 Prct

Total
3

Count

Others

zzzzzzzzg

The Statistics are followed by a blank line.
1

Std Dev is Standard Deviation.

95 Prct is 95th Percentile.

Because the Count is the same for all report items, it is only displayed for the first report item.

If any of the event records for duration events have unmatched start and end

event pairs, a diagnostic message displays following the event. This message
indicates how many unmatched event records are encountered. Note that the
total of all unmatched event records for the entire report is included with the
grand totals.
Example 4-5 shows the structure of a Summary Report for two different types
of events. In each case, two groupable items and five report items are specified
in the REPORT options. The first groupable item is a 12-character text string.
The second groupable item is a longword data type. The five report items are
longword data types. All the statistics are requested for the first event. Only
the minimum, maximum, mean, and count statistics are requested for the last
event. The next to the last event group has incomplete start and end event

Generating Reports 4-13

record pairs; hence, the two diagnostic messages. An index page, which follows
all reports consisting of more than one event, is not shown in the example.
Example 4-5

Display for Summary Report

DD-MMM-YYYY HH:MM'. xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx:xxx PageZZZ9
Selection: XXXXXXXXXXXXXXX
DECtrace Vl.0-0
Event XXXXXXXXXXXXXX In Facility XXXXXXXX Version XXXXXXXXX ! First event
For Collections XXXX,XXXX
For Nodes XXXXXX,XXXXXX
For PID
XXXXXX,XXXXXX
These lines indicate optional
restrictions placed on the report
For Image XXXXXX,XXXXXX
using the RESTRICTIONS option
With XXXXXXXXXXXXX = XXXXXXXXXX
And xxxxxxxxxx = xxxxxxx
Value of first Groupable Item
Value of second Groupable Item

XXXXXX XXXX: XXXXXXXXXXXX
XXXXXXXXX XXXXX: ZZZZZZZZ9

xxxxxxxxx xxxxxxxxx xxxxxxxxx xxxxxxxxx xxxxxxxxx
Minimum
Maximum
Mean
Std Dev
95 Prct
Total
Count

ZZZZZ9.99
ZZZZZ9.99
ZZZZZ9.99
ZZZZZ9.99
ZZZZZ9.99
ZZZZZ9.99
ZZZZZZZZ9

ZZZZZ9.99
ZZZZZ9.99
ZZZZZ9.99
ZZZZZ9.99
ZZZZZ9.99
ZZZZZ9.99

ZZZZZZZZ9
ZZZZZZZZ9
ZZZZZ9.99
ZZZZZ9.99
ZZZZZ9.99
ZZZZZ9.99

XXXXXX XXXX: xxxxxxxxxxxx
XXXXXXXXX XXXXX: ZZZZZZZZ9

ZZZZZZZZ9
ZZZZZZZZ9
ZZZZZ9.99
ZZZZZ9.99
ZZZZZ9.99
ZZZZZ9.99

Value of first Groupable Item
Value of second Groupable Item

xxxxxxxxx xxxxxxxxx xxxxxxxxx xxxxxxxxx xxxxxxxxx
Minimum
Maximum
Mean
Std Dev
95 Prct
Total
Count

ZZZZZ9.99
ZZZZZ9.99
ZZZZZ9.99
ZZZZZ9.99
ZZZZZ9.99
ZZZZZ9.99
ZZZZZZZZ9

ZZZZZ9.99
ZZZZZ9.99
ZZZZZ9.99
ZZZZZ9.99
ZZZZZ9.99
ZZZZZ9.99

! Item Headers

ZZZZZZZZ9
ZZZZZZZZ9
ZZZZZ9.99
ZZZZZ9.99
ZZZZZ9.99
ZZZZZ9.99

Item Headers

ZZZZZZZZ9
ZZZZZZZZ9
ZZZZZ9.99
ZZZZZ9.99
ZZZZZ9.99
ZZZZZ9.99

Subtotals For:
XXXXXX XXXX: XXXXXXXXXXXX ! This group is a subtotal summary
of the first groupable item

xxxxxxxxx xxxxxxxxx xxxxxxxxx xxxxxxxxx xxxxxxxxx
Minimum
Maximum
Mean
Std Dev
95 Prct
Total
Count

ZZZZZ9.99
ZZZZZ9.99
ZZZZZ9.99
ZZZZZ9.99
ZZZZZ9.99.
ZZZZZ9.99
ZZZZZZZZ9

ZZZZZ9.99
ZZZZZ9.99
ZZZZZ9.99
ZZZZZ9.99
ZZZZZ9.99
ZZZZZ9.99

ZZZZZZZZ9
ZZZZZZZZ9
ZZZ.ZZ9. 99
ZZZZZ9.99
ZZZZZ9.99
ZZZZZ9.99

ZZZZZZZZ9
ZZZZZZZZ9
ZZZZZ9.99
ZZZZZ9.99
ZZZZZ9.99
ZZZZZ9.99

Item Headers

ZZZZZZZZ9
ZZZZZZZZ9
ZZZZZ9.99
ZZZZZ9.99
ZZZZZ9.99
ZZZZZ9.99

(continued on next page)

4-14 Generating Reports

Example 4-5 (Cont.)

Display. for Summary Report

================= Grand Total ====================
Minimum
Maximum
Mean
Std Dev
95 Prct
Total
Count

XXXXXXXXX

ZZZZZ9.99
ZZZZZ9.99
ZZZZZ9.99
ZZZZZ9.99
ZZZZZ9.99
ZZZZZ9.99
ZZZZZZZZ9

ZZZZZ9.99 ZZZZZZZZ9 ZZZZZZZZ9 ZZZZZZZZ9
ZZZZZ9.99 ZZZZZZZZ9 ZZZZZZZZ9 ZZZZZZZZ9
ZZZZZ9.99 ZZZZZ9.99 ZZZZZ9.99 ZZZZZ9.99
ZZZZZ9.99 ZZZZZ9.99 ZZZZZ9.99 ZZZZZ9.99
ZZZZZ9.99 ZZZZZ9.99 ZZZZZ9.99 ZZZZZ9.99
ZZZZZ9.99 ZZZZZ9.99 ZZZZZ9.99 ZZZZZ9.99
! This group summarizes the first event

Item Headers

And

Version XXXXXXXXX

! Second event

xxxxxxxxxx = xxxxxxx

XXXXXX XXXX: XXXXXXXXXXXX
XXXXXXXXX XXXXX: ZZZZZZZZ9

Value of first Groupable Item
Value of second Groupable Item

xxxxxxxxx xxxxxxxxx xxxxxxxxx xxxxxxxxx xxxxxxxxx
Minimum
Maximum
Mean
Total
Count

ZZZZZ9.99
ZZZZZ9.99
ZZZZZ9.99
ZZZZZ9.99
ZZZZZZZZ9

ZZZZZ9.99
zzzzz9.99
ZZZZZ9.99
ZZZZZ9.99

ZZZZZZZZ9
ZZZZZZZZ9
ZZZZZ9.99
ZZZZZ9.99

! Item Headers

ZZZZZZZZ9
ZZZZZZZZ9
ZZZZZ9.99
ZZZZZ9.99

XXXXXX XXXX: XXXXXXXXXXXX ! This group is a subtotal summary of the first
! groupable item
XXXXXXXXX XXXXXXXXX XXXXXXXXX XXXXXXXXX XXXXXXXXX ! Item Headers
Minimum
Maximum
Mean
Total
Count

ZZZZZ9.99
ZZZZZ9.99
ZZZZZ9.99
ZZZZZ9.99
ZZZZZZZZ9

ZZZZZ9.99
ZZZZZ9.99
ZZZZZ9.99
ZZZZZ9.99

ZZZZZZZZ9
ZZZZZZZZ9
ZZZZZ9.99
ZZZZZ9.99

================= Grand Total ====================
Minimum
Maximum
Mean
Total
Count

XXXXXXXXX

ZZZZZ9.99
ZZZZZ9.99
ZZZZZ9.99
ZZZZZ9.99
ZZZZZZZZ9

ZZZZZ9.99 ZZZZZZZZ9 ZZZZZZZZ9 ZZZZZZZZ9
ZZZZZ9.99 ZZZZZZZZ9 ZZZZZZZZ9 ZZZZZZZZ9
ZZZZZ9.99 ZZZZZ9.99 ZZZZZ9.99 ZZZZZ9.99
ZZZZZ9.99 ZZZZZ9.99 ZZZZZ9.99 ZZZZZ9.99
! This group summarizes the second event

Item Headers

%EPC-I-NOSTART, ZZZZZZZZ9 End Event Records had no matching Start
%EPC-I-NOEND, ZZZZZZZZ9 Start Event Records had no matching End

Example 4-6 shows a Summary Report based on data collected from the
ATM sample application. The following example shows the command used to
generate the report:

Generating Reports 4-1 S

$ COLLECT REPORT ATM DATA.RDB /TYPE=SUMMARY _$ /STATISTICS=ALL -

Sample Summary Report Based on ATM Data

Example4-6

Event :

Minimum
Maximum
Mean
Std Dev
95 Prct
Total
Count

Page 1
DECtrace Vl.0-0

Summary Report

30-APR-1990 14:19
Selection: JUST ATM
BALANCE EVENT

In Facility:

Version:

ATM SAMPLE

Vl.O

Elapsed

BUFFERED IO

CPU TIME

CURREN
T PRIO

DIRECT IO

PAGEFAULTS

0.64
4.79
1. 78
1.39
4.52
17.84
10

13
13
13.00
0.00
13.00
130

0
3
2.10
0.87
3.81
21

9
9
9.00
0.00
9.00
90

0
0

PAGEFAULT
I Os

VIRTUAL
SIZE

GLOBAL ws

PRIVATE WS

WORKING
SET SIZ

0
0
0.00
0.00
0.00
0
10

5112
5112
5112.00
0.00
5112.00
51120

99
108
106.70
2.75
112.09
1067

380
397
390.20
8.77
407.40
3902

1109
1109
1109.00
0.00
1109.00
11090

Minimum
Maximum
Mean
Std Dev
95 Prct
Total
Count

0.00
0.00
0.00

1.50
3.17

7. 71

%EPC-I-RPQU_BAD_95, 95 Prct for events with counts under 1000 are less precise

30-APR-1990 14:19
Selection: JUST_ATM
Event:

Minimum
Maximum
Mean
Std Dev
95 Prct
Total
Count

Page 2
DECtrace Vl.0-0

Summary Report

DEPOSIT EVENT

In Facility:

Version:

ATM SAMPLE

Vl.O

Elapsed

BUFFERED IO

CPU TIME

CURREN
T PRIO

DIRECT IO

l?AGEFAULTS

3.38
6.08
4.73
1. 90
8.47
9.46
2

16
16
16.00
0.00
16.00
32

2
2
2.00
0.00
2.00
4

0
0
0.00
0.00
0.00
0

9.00
0.00
9.00
18

4.50
6.36
16.97
9

(continued on next page)

4-16

Generating Reports

Example 4-6 (Cont.)

Sample Summary Report Based on ATM Data

PAGEFAULT
I Os

VIRTUAL
SIZE

GLOBAL WS

PRIVATE WS

WORKING
SET SIZ

0
0
0.00
0.00
0.00
0
2

5112
5112
5112. 00
0.00
5112.00
10224

108
108
108.00
0.00
108.00
216

397
397
397.00
0.00
397.00
794

1109
1109
1109.00
0.00
1109.00
2218

Minimum
Maximum
Mean
Std Dev
95 Prct
Total
Count

%EPC-I-RPQU_BAD 95, 95 Prct for events with counts under 1000 are less precise
%EPC-I-NOEND, 1 Start Event Records had no matching End

30-APR-1990 14:19
Selection: JUST ATM
Event:

Page 3
DECtrace Vl.0-0

Sununary Report

WITHDRAW EVENT

In Facility:

ATM SAMPLE

Vl.O

Version:

Elapsed

BUFFERED IO

CPU TIME

CURREN
T PRIO

DIRECT IO

PAGEFAULTS

2.34
2.34
2.33
0.00
2.33
2.33
1

16
16
16.00
0.00
16.00
16

1
1
1. 00
0.00
1. 00
1

9
9
9.00

0
0
0.00
0.00
0.00
0

PAGEFAULT
I Os

VIRTUAL
SIZE

GLOBAL WS

PRIVATE WS

WORKING
SET SIZ

0
0
0.00
0.00
0.00
0

5112
5112
5112. 00
0.00
5112. 00
5112

108
108
108.00
0.00
108.00
108

397
397
397.00
0.00
397.00
397

1109
1109
1109.00
0.00
1109.00
1109

Minimum
Maximum
Mean
Std Dev
95 Prct
Total
Count

o.oo
9.00
9

%EPC-I-RPQU_BAD 95, 95 Prct for events with counts under 1000 are less precise

30-APR-1990 14:19
Selection: JUST ATM

Index

Page 4
DECtrace Vl.0-0

Report Index
Facility Name

Event Name

Page

ATM SAMPLE
ATM SAMPLE
ATM SAMPLE

BALANCE EVENT
DEPOSIT EVENT
WITHDRAW EVENT

1
2
3

Generating Reports 4-17

4.5 Text Wrapping in Reports
Wrapping is supported on groupable items, groups, headers, and text report
items. This section gives an explanation of the rules for each case.

4.5.1

Groupable Items

Groupable items wrap at the last column of the report. The continuation of the
text occurs on the next line without any additional indentation. Example 4-7
shows a portion of a report where the groupable item is a file name.
Example 4-7

Wrapping of a Groupable Item

27-MAY-1989 21:45
Selection: ACC TRENDS

The Longest Files

Event TRANSACTION In Facility RDBVMS
For Collections 23MAYAM,24MAYAM
For Nodes MYVAXl, MYVAX2
With STREAM ID = 392
And STREAM-ID = 393

Page 1
DECtrace Vl.0-0
Version V3.1-0

DB Name: THIS IS A VERY LONG DEVICE NAME LOGICAL: [DIRECTORY LEVEL
_ONE-:-DIRECTORY=LEVEL_TWO.DIRECTORY__LEVEL_THREE] TH(~DATABASE_FILE
NAME.ROB

4.5.2 Groups
A Group consists of a set of items. If more report items are provided than can
be placed horizontally on the Summary Report, they wrap as a subsequent set
of rows. Example 4-8 shows how groups wrap in a report.

4-18 Generating Reports

Example 4-8

Wrapping of Groups

27-MAY-1989 21:45
Selection: ACC TRENDS

Monday AM Accounting Transactions

Event TRANSACTION In Facility RDBVMS
For Collections 23MAYAM,24MAYAM
For Nodes MYVAXl, MYVAX2
With STREAM ID
392
And STREAM-ID = 393

Page 1
DECtrace Vl.0-0

Version V3.1-0

Client PC: 3578
Elapsed

CPU TIME

BUFFERED IO

DIRECT IO

PRIVATE WS

GLOBAL WS

Minimum
Maximum
Count

0.02
10.65
346

2
534

25
945

685
1052

325
2056

287
4912

Minimum
Maximum
Count

RUJ File
Reads
65
75
346

DIRECT IO

PRIVATE WS

GLOBAL WS

AIJ File
Writes
12
17

Locks
Requested
39
1985

Client PC: 3580
Elapsed

4.5.3

CPU TIME

BUFFERED IO

Headers

Headers that exceed their report item width parameter will wrap. If an
underscore or a space exists in the header, then wrapping occurs at that
character. Otherwise, wrapping occurs at the last column. Example 4-9 shows
a portion of a database transaction report where the headers wrap.

Generating Reports 4-19

Example 4-9

Wrapping of Headers

27-MAY-1989 21:45
Selection: ACC TRENDS

Monday AM Accounting Transactions

Event TRANSACTION In Facility RDBVMS
For Collections 23MAYAM,24MAYAM
For Nodes MYVAXl, MYVAX2
With STREAM ID
392
And STREAM ID = 393

Page 1
DECtrace Vl.0-0

Version V3.l-O

Client PC: 3578
Pagefault
s

Pagefault
IO

Free VM
Bytes

Lock Reqs

WS Size

ws Global

Minimum
Maximum
Count

4.5.4

Report Item Text

The text for the Detail Report items are wrapped at the last column of the
report item. Example 4-10 shows a portion of a report where item text wraps.
Example 4-10

Wrapping of Report Item Text

27-MAY-1989 21:45
Selection: ACC TRENDS

Version V3.1-0

Event DATABASE In Facility RDBVMS
In Collections 23MAYAM,24MAYAM
For Nodes MYVAXl, MYVAX2
Point Time stamp

DB Name

20-Apr-1989 09:22:45.67

ACC DISK: (DA
TABASES]ACCO
UNTING MAIN.
RDB
ACC DISK: (DA
TABASES]ACCO
UNTING NEW.R
DB

20-Apr-1989 18:34:23.62

Page 1
DECtrace Vl.0-0

Accounting Database Binds

Stream Id

Client PC

3785

126457

3782

129381

4.6 Special Cases for Reporting on Duration Events
When generating a Summary Report for a duration event that contains an
item of type level found in both the start and end events, the values associated
with the item in the end event are used. If the item is collected only for the
start or end event, then the data is picked from the corresponding start or end
event.

4-20 Generating Reports

For Detail and Summary Reports containing duration events, if an item is
defined to be of type counter but does not exist in the item list for both the
start and end events, then the fields in the report are filled with dashes (-)to
indicate an error in the facility definition.
For Summary or Detail Reports, if a starting time-stamp for an event has
a value greater than the corresponding end event time-stamp, an error is
flagged. For Detail Reports, the elapsed time field is filled with dashes. For
Summary Reports, the time-stamps are ignored. The end of the Summary
Report for the event contains a message stating the number of occurrences
of end time-stamps preceding start time-stamps. Note, if this occurs it might
be because the system clock was changed while the collection was running.
Another cause may be placing your EPC$START_EVENT service routine call
at the end of an event and the EPC$END_EVENT call at the beginning. If
the clock is changed, all other items will be correct (for example, if CPU usage
was collected, it will be accurate). If the calls are reversed, then the other item
values for that event pair will either be zero or negative.

If the report field width of an item is too small to contain a given value, the
field is filled with asterisks ( * ). This condition can be fixed by specifying a
wider field using the ITEM report option. For example:
$ COLLECT REPORT MY DATABASE /OPTIONS
Option> EVENT MY EVENT /FACILITY=MY FACILITY
Option> ITEM BIG-VALUE /WIDTH=32
Option> lcTRL/ZI
$

If an arithmetic overflow occurs during report generation, the field is filled
with percentage signs ( % ). Data is stored internally using D-floating format.
For standard deviation and 95th percentile, the intermediate values may get
too large to fit in a D-floating variable (even though the final result would fit).
You can subdivide a report using the /GROUP_BY qualifier to reduce the
possibility of an overflow. In this case, the grand total displayed at the end of
the report will still contain overflowed values. Another option is to restrict the
amount of data reported by using the RESTRICTION option.

If you display a quadword data item as a decimal type, a round-off error may
occur. Quadwords displayed as decimal are stored internally as D-floating
point. The precision is only 16 decimal-digits with a range of .29*10**-38 to
1. 7*10**38. The recommended method is to use the IRADIX=HEXADECIMAL
qualifier to the ITEM option on the CREATE DEFINITION command.

Generating Reports 4-21

4.7 Report Optimization
The following recommendations apply to improving the performance of
generating reports from large formatted databases.
• You can put your database journal file on another device by assigning the
logical: RDMS$RUJ. For example:
$

DEFINE RDMS$RUJ DISKS: [TEMPFILES]

• You can put your SORT work files on another device by assigning the
logicals: SORTWORKO and SORTWORKl. For example:
$ ASSIGN DISKl: SORTWORKO
$ ASSIGN DISK2: SORTWORKl

• You may need to increase the enqueue limit (ENQLM) quota for your
process. The ENQLM quota allows you to limit the number of locks that a
process may take out. Digital recommends a minimum ENQLM value of
1800. If this value is too low, you will get the following error:
%EPC-E-Bugcheck, Fatal error
%NONAME-F-NOMGG, . . . . . . . . . . . . .
-RDMS-F-EXQUOTA, exceeded Quota
-SYSTEM-F-EXENQLM, exceeded Enque Quota

To generate a report from a 300k block formatted database, you may need
to raise your ENQLM to 10000. Note that increasing the ENQLM has
no negative effects on the system in terms of preallocated resources. Also
note that you will have to log out and back in again for the change to take
affect. See the VMS Authorize Utility Manual for information on changing
process quotas.

4.8 Report Options
This section describes the report options that you can specify to generate
customized reports. Specify options in an options file (or at the DECtrace
Option> prompt) when using the /OPTIONS qualifier to the REPORT
command. Specify each option on a separate line. You can specify each option
more than once. Report options include:
• EVENT
• ITEM
• RESTRICTION
The EVENT option defines characteristics about a specific event. The ITEM
and RESTRICTION options define additional characteristics for the EVENT
option that immediately precedes them. For example, the following command
generates a report from data in the ATM_DATA formatted database. Of all
the data in the file, only data collected from processes on node MYVAXl is

4-22 Generating Reports

reported. Furthermore, only occurrences of the DEPOSIT_EVENT between
1:00 and 3:00, and of the WITHDRAW_EVENT between 2:00 and 4:00 are
reported:
$ COLLECT REPORT ATM DATA.RDB /TYPE=SUMMARY _$ /STATISTICS=ALL /OPTIONS
Option>
Option>
Option>
Option>
Option>
Option>
Option>
Option>
Option>

EVENT DEPOSIT EVENT /SINCE="09-MAY-1990 13: 00" /BEFORE="09-MAY-1990 15: 00"
RESTRICTION NODE MYVAXl
EVENT WITHDRAW EVENT /SINCE="09-MAY-:-1990 14:00" /BEFORE="09-MAY-1990 16: 00"
RESTRICTION NODE MYVAXl
EXIT

The Using DECtrace with Digital Products manual describes how to generate
customized reports based on individual events in ALL--IN-1, ACMS, RDB
/VMS, and VAX DBMS.

Generating Reports 4-23

REPORT Options-EVENT

REPORT Options-EVENT
Defines the characteristics of a report on a specific event. You specify this
command using the /OPTIONS qualifier to the REPORT command.

Format
EVENT

event-name

Command Qualifiers

Defaults

/BEFORE="time"
/FACILITY=facility-name
/GROUP_BY=(item-name[, ... ])
/INTERVAL=time-unit
/[NO]ITEMS=(item-name[, ... ])
/SINCE="time 11
/STATISTICS=(stat-type[, ... ])
/SUBTITLE="text-string"
/TYPE=report-type

All data in file
None
See text
See text
/ITEMS=*
All data in file
See text
/SUBTITLE=" II
See text

Parameters
event-name

The name of an event to report on.

Qualifiers
/BEFORE=" dd-mmm-yyyy hh:mm:SS"

Specifies that DECtrace reports on all data collected at or before the indicated
time. By default, DECtrace reports on all data in the formatted database for
this event.
If you use the /BEFORE qualifier, you must specify the time as an absolute

date and time using a quoted string. You cannot use VMS delta time.
/FACILITY:facility-name

Specifies the name of the facility that contains the event.

4-24 Generating Reports

REPORT Options-EVENT

!GROUP_BY:(item-name[, ... ])

Specifies the time interval for FREQUENCY reports. FREQUENCY reports
calculate the number of occurrences of an event or events at given time
intervals during data collection. The /INTERVAL qualifier specifies the time
interval at which event occurrences are calculated. The time interval must be
one second, one minute, or one hour specified as one of the following keywords:
SECONDS
MINUTES
HOURS
If an /INTERVAL qualifier is specified on the REPORT command line, the

command line qualifier specifies the default interval. The /INTERVAL qualifier
on an EVENT option overrides the default interval for this event only.
The default interval is one minute.
The /INTERVAL qualifier is valid for FREQUENCY reports only. The qualifier
is ignored for other types of reports.
/ITEMS=(item-name[, ... ])
/NO ITEMS

Specifies the item or items on which to report. The /ITEMS qualifier is valid
for DETAIL and SUMMARY reports only; it is ignored for FREQUENCY
reports.
/SINCE=" dd-mmm-yyyy hh:mm:SS"

Specifies that DECtrace reports on all data collected for this event at or after
the specified time. By default, DECtrace reports on all the collected data in the
formatted database for this event name.
If you use the /SINCE qualifier, you must specify the time as an absolute date

and time using a quoted string. You cannot use a VMS delta time.

Generating Reports 4-25

REPORT Options-EVENT

!STATISTICS=(stat-type[, ... ])

Specifies the summary statistics to include for each item. Valid statistics are:
95_PERCENTILE
ALL
COUNT (default)
MAXIMUM
MEAN
MINIMUM
STANDARD_DEVIATION
TOTAL
If you specify the /STATISTICS qualifier on the REPORT command line, the
command line qualifier specifies the default statistics. The /STATISTICS
qualifier on an EVENT option overrides the default statistics for this event
only.

The /STATISTICS qualifier is valid for SUMMARY reports only. DECtrace
ignores the qualifier for DETAIL and FREQUENCY reports.
!SUBTITLE=" text-string"

Specifies a subtitle for the report. The subtitle is displayed only at the top of
the first page of the report. The subtitle is a text string that can contain any
printable characters. The string must be enclosed with quotation marks (" ")
/TYPE=report-type

Specifies the type of report to create. The valid report types are:
DETAIL
FREQUENCY
SUMMARY
If you specify the /TYPE qualifier on the REPORT command line, the command
line qualifier specifies the default report type. The !TYPE qualifier on an
EVENT option overrides the default report type for this event only.

The default report type is SUMMARY.

Description
Specify report options either in an options file or at the Option> prompt. You
must use the /OPTIONS qualifier to the REPORT command to specify options.
Specify each option on a separate line. You can specify each option more than
once.

4-26 Generating Reports

REPORT Options-ITEM

REPORT Options-ITEM
Defines the display characteristics of items in the report. You specify this
command using the /OPrIONS qualifier to the REPORT command.
Display characteristics include:
•

Report heading

• Display width
The default display characteristics of data items are defined in the
facility definition. The ITEM report option allows you to customize these
characteristics for an item pertaining to the preceding EVENT report option.
The characteristics defined in an ITEM option remain in effect only for a single
EVENT report option.

Format
ITEM

item-name

Command Qualifiers

Defaults

/REPORT_HEADER=text
/WIDTH=number-of-columns

See text
See text

Parameters
Item-name

The name of the item for which to define the characteristics.

Qualifiers
IREPORT_HEADER:text

Specifies the text to display as a heading in the report when listing data for
the specified item.
The facility definition specifies the default report heading.
IWIDTH=number-of-columns

Specifies the number of columns to reserve for displaying data for the specified
item.
The facility definition specifies the default width.

Generating Reports 4-27

REPORT Options-· RESTRICTION

REPORT Options-RESTRICTION
Defines a subset of the data to report on for the preceding EVENT report
option. You specify this command using the /OPTIONS qualifier to the
REPORT command.
You can selectively report on data based on the following items:
• Collection names
• Image names
• Item values
• Node names
• Process IDs (EPID)

Format
RESTRICTION

COLLECTION collection-name [, ... ]
EPID process-ID [, ... ]
IMAGE image-name [, ... ]
( ITEM item-name item-value
NODE node-name [, ... ]

)

Parameters
collection-name

The name of one or more collections to use to select data for reporting. Only
data collected during the specified collections is reported.
image-name

The name of the executable image which registered with the DECtrace
Registrar. Only data collected from processes running the specified images is
reported.
The image name that you specify is used as a wildcard in searching through
the formatted database for the desired images. The effect is that the restriction
is done on *image-name*.
item-name

The name of an item to use to select data for reporting.

4-28 Generating Reports

REPORT Options-RESTRICTION
item-value
The value of the item to use to select data. Only records that match the item
name and value are reported.
node-name
The name of one or more network nodes to use to select data for reporting.
Only data collected on the specified nodes is reported.
process-ID
The EPIDs of one or more processes to use to select data for reporting. Only
data collected from the specified processes is reported.

Generating Reports 4-29

5
Instrumenting Applications

DECtrace service routine calls must be instrumented in the source program
of an application for data collection to take place. The instrumentation consists
of adding DECtrace routine calls which identify the program as a DECtrace
facility, define the start and end of duration events and the occurrence of point
events within the program, and set and delete context for various threads in a
multi-threaded environment.
Instrumenting source code is the first step (see Figure 1-1) for application
programmers using DECtrace. General users do not need to add anything to
their applications to collect data from existing facilities.
Table 5-1 lists all of the DECtrace routine calls used for instrumenting
applications. Chapter 8 describes each of the service routines in detail.
Table 5-1

DECtrace Service Routines

Routine Name 1

Description

EPC$DELETE_CONTEXT

Deletes the context associated with a particular
thread (for multi-threaded facilities only).

EPC$END_EVENT

Records the end of a duration event to the data
collection file.

EPC$END_EVENTW

Records the end of a duration event to the data
collection file and waits for processing to complete
before returning.

The service routines are prefaced with "EPC" because that is the registered facility name of
DECtrace.

(continued on next page)

Instrumenting Applications 5-1

Table 5-1 (Cont.)

DECtrace Service Routines

Routine Name 1

Description

EPC$EVENT

Records the occurrence of a point event to the data
collection file.

EPC$EVENTW

Records the occurrence of a point event to the data
collection file and waits for processing to complete
before returning.

EPC$INIT

Registers a facility with DECtrace to enable data
collection on this facility.

EPC$SET_CONTEXT

Sets the context for a new or existing thread so
resource utilization items can be collected (for
multi-threaded facilities only).

EPC$START_EVENT

Records the start of a duration event to the data
collection file.

EPC$START_EVENTW

Records the start of a duration event to the data
collection file and waits for processing to complete
before returning.

1
The service routines are prefaced with "EPC" because that is the registered facility name of
DECtrace.

5. 1 Programming Interface
DECtrace routines must be placed in the source program of a facility in
order for data collection to take place for that facility. DECtrace provides
routines that allow you to record events which occur during the execution of
your application program (executable image.) These routines collect data for
each facility in an application program. DECtrace records the data in a data
collection file that can be common to one or many different processes that are
also collecting data on your system.
Figure 1-1 illustrates that the application program is made up of one or
many facilities. In this case the application consists of your own server code
(which may or may not be instrumented with DECtrace calls), ACMS, and an
application database (probably an Rdb/VMS or a VAX DBMS database). Each
of these component facilities is responsible for issuing calls to the DECtrace
service routines in order to collect data. The service routines record data in
a data collection file that can be shared by other processes that are collecting
data on the system or VAXcluster. Note that your server code does not need
to have any DECtrace calls in it in order to collect the ACMS event data. A
user can schedule data collection from any subset of the facilities defined in
the DECtrace administration database, regardless of what application actually
called the facility.

5-2 Instrumenting Applications

Each facility in the application image must include a call to EPC$INIT at
the first point of execution of the facility in order to register the facility with
DECtrace. Note that each facility needs to call EPC$INIT only once for
each image activation of the facility. Then, as the predefined events within
the facility execute, the facility places calls to EPC$EVENT(W) and/or to
EPC$START_EVENT(W) and EPC$END_EVENT(W) to denote the events from
which data is collected.
Events are classified as either duration events or point events. A duration
event has a definite start and end associated with it. A point event simply
occurs has no logical start or end. DECtrace provides routines to collect data
on either type of event. The EPC$EVENT(W) routine is called for point events.
The EPC$START_EVENT(W) routine is called at the start of duration events,
and the EPC$END_EVENT(W) routine is called at the end of duration events.
A facility can supply data that contains information specific to the facility
(referred to as facility-specific items) on each event call. In addition, DECtrace
can collect a set of resource utilization items on behalf of the facility for each
event that occurs. Table 5-2 describes the items that comprise this group
of items. If a multi-threaded facility (a multi-threaded server, for instance)
wants to collect resource utilization items on a per-thread basis, the facility
additionally needs to issue calls to EPC$SET_CONTEXT between context
switches to ensure that DECtrace accounts the resource utilization items to
the correct thread. In order for DECtrace to do this accounting properly, the
facility must issue a call to the EPC$SET_CONTEXT service to denote the
start of a new thread and also to denote a context change between threads.
The EPC$DELETE_CONTEXT service must also be called by the facility to
specify that data collection for a thread has ended.
Note Only multi-threaded facilities need to issue calls to EPC$SET_CONTEXT and

EPC$DELETE_CONTEXT.
Table 5-2 describes the standard resource utilization items collected by
DECtrace.
Table 5-2

Resource Utilization Items

Item Name

Item ID
Number

Description

Data Type

Usage

BIO

101

Number of buffered I/O operations

Longword

Counter

DIO

102

Number of direct I/O operations

Longword

Counter

PAGEFAULTS

103

Total number of hard and soft page faults

Longword

Counter

(continued on next page)

DECLIT AA VAX PB 9 0A
DECtrace for VMS user's
guide
Instrumenting Applications 5-3

Table 5-2 (Cont.)

Resource Utilization Items

Item Name

Item ID
Number

PAGEFAULT_IO

Description

Data Type

Usage

104

Number ofhard page faults (that is, page
faults to or from the disk)

Longword

Counter

CPU

105

Total amount of CPU time in tens of
milliseconds.

Longword

Counter

CURRENT_PRIO

106

Current priority of the process

Word

Level

VIRTUAL_SIZE

107

Number of virtual pages that are currently
mapped for the process

Longword

Level

WS_SIZE

107

Current working set size of the process

Longword

Level

WS_PRIVATE

109

Number of pages in the working set that
are private to the process

Longword

Level

WS_GLOBAL

110

Number of pages in the working set that
are globally shared among processes on
the system

Longword

Level

Note DECtrace stamps each data collection record with the current date and time,
process identification number (EPID), facility number, and event identifier.
Therefore, the elapsed time information for the EPID, the facility that logged
the event, and the event identifier are always collected.

5.2 DECtrace Data Structures
There are two major data structures that the facility can use to detect which
events and items to collect: the event flags and the item flags list. The
DECtrace event flags (see the EPC$INIT routine in Chapter 8 for a diagram)
consist of a list of 128 longword Boolean values. Each element of the list
corresponds to a particular event for a facility. If an element is set, it indicates
that data should be collected for that event.
The items to be collected for the event are represented in the item flags list
data structure. The item flags list is a list of 128-bit elements. Each bit in the
list element corresponds to an item identifier (defined in the facility definition).
If an item identifier is set, that item is collected for a particular event. The
event identifier is used as the offset into this list to obtain the corresponding
item flags for an event. In order for the facility to obtain the event flags and
item flags list, the facility must allocate virtual memory (either statically
or dynamically) and pass the address of these structures in the call to the
EPC$INIT service routine.

5-4 Instrumenting Applications

A buffer, referred to as an event record, can be optionally supplied by the
client to the EPC$EVENT(W), EPC$START_EVENT(W), and EPC$END_
EVENT(W) routines. This buffer contains the facility-specific items for the
event. When this buffer is specified, its layout is the same whether the facility
collects one item or all items. Any extra items passed by the facility for an
event are removed from the data collection files during the merge and format
operations, so that only those items that were specified in the facility selection
appear in the formatted database.

5.3 Determining Your Events
To effectively use DECtrace with your application, you must correctly identify
the events in your program. In addition, you must have a purpose or goal
for using DECtrace. Your purpose determines the types of items that you
should collect from your events. The ability to select specific groups of events
and items at collection time means that you can have multiple goals for your
instrumentation.
In the automated teller machine (ATM) sample application, events were chosen
based on the usage of the program. A duration event occurs when a customer
checks the account balance, or makes a withdrawal or deposit to an account.
A different type of event is based on the actual coding of the application. You
could create an event for each subroutine or procedure call. This difference in
events is based on a difference in the purpose of the instrumentation.
The instrumentation of the ATM application is designed to gather information
about the user interface. The goal is to be able to answer questions such as:
• How long does it take to complete a transaction?
• Do customers check their balance before or after every transaction?
•

Could overdrafts be reduced or eliminated by displaying the balance on the
withdrawal display?

• Are ATM machines used primarily for deposits or withdrawals?
Similar functionality-oriented events which could be developed for the ATM
application include:
• Which ATMs are used most often?
• What are the most common withdrawal amounts on each day of the week?
$10 on Mondays? $25 on Thursdays? $100 on Fridays?
• Does anyone ever make deposits in the the ATM machine in the shopping
mall?

Instrumenting Applications 5-5

If the goal of instrumenting the ATM application was to improve the

performance of the program, then a different set of events could be defined.
The events based on functionality could be· broken down into more specific
events. For example, the withdrawal event consists of three main steps:
1

Get the withdrawal amount.

Subtract the amount from the customer's balance.

Update the database with the new balance.

You can further break the withdrawal event into steps which detail the
actual execution sequence of the program. In fact, the following list of events
is similar to the pseudo-code and flowchart used to create the original,
non-instrumented, application program.
1

Display the withdrawal screen.

Read the withdrawal amount.

Find the customer's current balance in the database.

Check for possible overdraft.

Subtract the withdrawal amount from customer's balance.

Lock and then update the customer's account record.

After you have determined what events you want to define for your application,
you need to locate the events in a functional diagram of the application.
This helps you to locate the actual location of the event in your source code.
Figure 5-1 shows a flowchart of the sample ATM application with one event
outlined in detail.

5.4 Using EPC$1NIT to Register a Facility
The instrumentation of a program begins with an EPC$INIT call. This call
should be done early in the execution of a program, because until the DECtrace
Registrar process receives this message, no event data can be collected from
the application. The EPC$INIT call basically says, "Here I am."
The EPC$INIT call contains information describing the facility. It contains
the unique facility ID number, the version of the facility, a list of the events
defined for the facility, and the items associated with each event. Optionally,
the EPC$INIT call can include a facility-specific registration ID which can be
used at collection time to distinguish between images using the same facilities.
For example, ACMS provides the ACMS application name as the registration
ID. See Section 3.1.2 for a description of the uses of the registration ID.

5-6

Instrumenting Applications

Figure 5-1

Flowchart of the Sample Application Showing One Event
Start

EPC$1NIT
Read Account Number

Display Selection Menu

Read Selection

EPC$START EVENT

Balance

Deposit

•
•

•
•
•

Wthdr:al

8
•

•

Read Amount

•

Find Current Balance

Yes

Debit Balance

Update Record

EPC$END_EVENT
NU-2051 A-RA

Instrumenting Applications S-7

Example 5-1 shows the implementation of the EPC$INIT call in the ATM
sample application. The COBOL source file 1 of the ATM application is
available in EPC$EXAMPLES:EPC$ATM-SAMPLE.COB.
Example 5-1

Instrumentation of EPC$1NIT in the ATM Application

IDENTIFICATION DIVISION.
PROGRAM-ID. ATM-SAMPLE.
AUTHOR. Digital Equipment Corporation

*++

*The following variables are used for the DECtrace service routines.

*
77 Max events
77 Facility_number

77 Errors event id
77 Balanc"E; event id
- id
77 Deposit_event_
77 Withdrawal event id
01 Facility_version
02 Event_flags
01 Event handle
01 Cond status
01 Registration_id

PIC X(4) value "Vl.0".
PIC 9 (9) comp occurs 128 times.
PIC 9 (9) comp.
PIC 9 (9) comp.
PIC X(lS) value "ATM APPLICATION".

9 (9)
9 (9)
9 (9)
9 ( 9)
9 (9)
9 (9)

comp value 128.
comp value 4094.
comp value 1.
comp value 2.
comp value 3.
comp value 4.

PIC
PIC
PIC
PIC
PIC
PIC

PROCEDURE DIVISION.
INITIALIZE-DECTRACE.

* Perform facility initialization tasks, including the EPC$INIT call.

*
CALL "EPC$INIT" USING BY VALUE 0,
BY VALUE FACILITY_NUMBER,
BY DESCRIPTOR FACILITY_VERSION,
BY DESCRIPTOR REGISTRATION_ID,
BY REFERENCE EVENT FLAGS LIST
GIVING COND STATUS.

See Chapter 8 for a detailed description of the format of the EPC$INIT call.

Additional versions of the ATM program, written in FORTRAN and Pascal, are also available
in EPC$EXAMPLES.

5-8 Instrumenting Applications

5.4. 1 Waiting for EPC$1NIT to Complete
The EPC$INIT call registers a facility with the DECtrace Registrar process.
The Registrar records the fact that this process has registered and also
compares it to the criteria of any active collections. Although the processing
completes quickly, the application program continues to execute, and some
events might not get collected.
DECtrace does not cause the application to stop and wait for the Registrar
process. However, the application programmer has the ability to make the
program wait until data collection is enabled for the process, by passing the
event flags and the i tern flags buffers to the EPC$INIT routine. These buffers
are filled asynchronously when the process receives the "Start collecting"
message from the Registrar process.
If you do not want to miss any events, poll the event flags and wait until

they get written before continuing program execution. Note that a timeout or
retry limit should be set because if no active collections are defined to collect
data from that image, or if the DECtrace Registrar process is not active, the
program will wait indefinitely.
Example 5-2 shows a VAX C code segment from the DECtrace IVP program
that waits until the process has registered before continuing program
execution.
Example 5-2

Code to Guarantee Collection of All Events

/* Wait for the collection to be activated for this
*/
/*process. Keep checking the 1st event collection flag*/
/*to see if it's set. */
while((loop count++< RETRY TIMES) && (evntflgs[O] != 1))
{
status= lib$wait(&delay time);
if (status != SS$_NORMAL)
{

printf("Error returned from synchronization after
call to EPC$INIT\n");
return (status);

Instrumenting Applications 5-9

5.5 Coding an Event in the ATM Sample Application
Figure 5-1 illustrates the functionality of the ATM WITHDRAWAL event. The
instrumentation of the event consists of adding an EPC$START_EVENT call
to the beginning of the function, and an EPC$END_EVENT call to the end of
the function.
Example 5-3 shows the COBOL code required to implement the
WITHDRAWAL event.
Example 5-3

Instrumentation of the WITHDRAWAL Event in the ATM
Application

* The Withdrawal transaction begins here.

*
START-WITHDRAWAL.

* Start of event4: WITHDRAW. For efficiency, test to see if the event is to
* be collected prior to calling EPC$START_EVENTW.

IF EVENT_FLAGS(WITHDRAW_EVENT) = 1
THEN
CALL "EPC$START_EVENTW" USING BY VALUE 0,
BY VALUE FACILITY_NUMBER,
BY VALUE WITHDRAW_EVENT,
BY REFERENCE EVENT HANDLE
GIVING COND STATUS
END-IF.

* Clear the lower portion of the screen and display a withdrawal form.

DISPLAY Withdrawal_heading reversed AT LINE 5 COLUMN 32
ERASE TO END OF SCREEN.
DISPLAY "Amount of withdrawal:" AT LINE 12 COLUMN 15.
DISPLAY withdrawal-instruction AT LINE 22 COLUMN 1.

PROMPT-FOR-WITHDRAWAL.

*Clear the message line and then prompt for the user's input.

*
DISPLAY SPACE

AT LINE 20 COLUMN 1
ERASE TO END OF LINE.

ACCEPT transaction-amount

BOLD
PROTECTED
WITH CONVERSION
FROM LINE 12 COLUMN 40
ERASE TO END OF LINE.

(continued on next page)

S-1 O Instrumenting Applications

Example 5-3 (Cont.)

Instrumentation of the WITHDRAWAL Event in the
ATM Application

*Find the customer's record and make the withdrawal.

*
MOVE transaction-failed TO error-message.
READ DATA-FILE KEY IS Account-ID
INVALID KEY
PERFORM Invalid-input THROUGH End-Invalid-Input
GO TO END-WITHDRAWAL.
SUBTRACT Transaction-Amount FROM Balance GIVING Balance.

* If the withdrawal is larger than the current balance issue a error message.
* Otherwise, update the file.

*
IF Balance < 0
THEN MOVE overdraft TO error-message
PERFORM Invalid-input THROUGH End-Invalid-Input
ELSE REWRITE Account-record
INVALID KEY
PERFORM Invalid-input THROUGH End-Invalid-Input
GO TO END-WITHDRAWAL
END-IF.

* End of event4: WITHDRAW. For efficiency, test to see if the event is to
* be collected prior to calling EPC$END_EVENTW.

IF EVENT_FLAGS(WITHDRAW_EVENT) = 1
THEN
CALL "EPC$END_EVENTW" USING BY VALUE 0,
BY VALUE FACILITY_NUMBER,
BY VALUE WITHDRAW_EVENT,
BY REFERENCE EVENT HANDLE
GIVING COND STATUS
END-IF.

END-WITHDRAWAL.
EXIT.

5.6 Instrumenting an Application in VAX C
Instrumenting an application and creating its facility definition (as described
in Chapter 6) are similar exercises that can be developed simultaneously.
The following sections contain examples of source code instrumented with
DECtrace calls and written in VAX C.

Instrumenting Applications 5-11

5.6. 1 Instrumenting Simple Events
The /EVENTS qualifier to the CREATE DEFINITION command specifies a list
of events that occur within the facility. For example, the following command
defines a facility named DB with three events:
! DB Facility Definition (Three Events)
!

CREATE DEFINITION DB 2048 /VERSION="Vl.0-0"/EVENTS=(DATABASE,TRANSACTION,REQOEST_ACTOAL)

These three events would have only the standard resource utilization items
collected for them by DECtrace. DATABASE would have an event ID of 1,
TRANSACTION would have an event ID of 2, and so forth.
For efficiency, the DB facility can use the event IDs to determine whether a
facility selection is collecting data for any particular event. This test reduces
the overhead of DECtrace on your system when the event does not need to be
collected. You eliminate pushing the arguments on the stack and relying on
DECtrace to do argument validation. For example, the following source code
defines the DB events:
#define DATA EVENT ID
1
#define TRANS EVENT ID
2
#define REQ_ACT_EVENT_ID 3

/* DATABASE event ID */
/* TRANSACTION event ID */
/* REQOEST_ACTOAL event ID */

If data is being collected for the TRANSACTION event, DECtrace sets a flag in

a data structure called the event flags list, the address of which is one of the
parameters passed to the EPC$INIT routine.
The event flags list consists of 128 longword Boolean values. For example:
static int s_event_flags[128];

/* Event Flags list */

The DB facility uses the event ID as an offset to test the appropriate element of
the event flags list before calling EPC$EVENT(W) or EPC$START_EVENT(W).
For example:
if (s_event_flags[TRANS_EVENT_ID-1]

!=FALSE)

{

status = epc$event(

Event ID numbering begins at 1. C array element numbering begins at 0.
Thus, an adjustment to the array subscript is necessary.

5-12

Instrumenting Applications

5.6.2

Instrumenting Events and Items

The /OPTIONS qualifier to the CREATE DEFINITION command provides
capabilities beyond those provided by the /EVENTS qualifier, particularly the
ability to collect facility-specific items. Table 5-3 summarizes the facility
definition options, which are described in detail in Section 6.5.
TableS-3

Summary of Facility Definition Options

Option

Description

ITEM

Binds the name of a facility-specific item to a unique
numeric identifier and specifies the characteristics of the
data associated with that item.

GROUP

Conveniently allows you to refer to a set of items by a single
name. You can use the group name in an EVENT or CLASS
option to refer to all of the items within that group.

EVENT

Binds the name of an event to a unique numeric identifier
and specifies the items associated with that event.

CLASS

Binds a name to a set of events and a set of items to each
event. A facility selection can specify a class name to
limit data collection. Digital recommends that application
product developers define one or more of the following
standard classes:

DEFAULT_CLASS

•

CAPACITY_PLANNING-Includes those events and
items that are useful for capacity planning purposes.

•

DEBUGGING-Includes those events and items that
are useful for tracing the execution of your application.

•

ERROR_LOGGING-Includes those events and items
that are associated with error or exception handling
routines in your application.

•

PERFORMANCE-Includes those events and items
that are useful for application and/or database tuning.

•

WORKLOAD-Includes those events and items that
are useful for gathering information useful for tracing
the actual workload of the application and/or database
management system.

Indicates which class to collect if none is specified by the
facility selection.

Instrumenting Applications 5-13

5.6.2. 1 Collecting Basic Facility-Specific Items The ITEM option defines
an item of data that is specific to a facility. It binds the name of an item
to a unique numeric identifier and specifies the characteristics of the data
associated with that item. The EVENT option specifies the items associated
with an event.

For example, the sample database facility definition might contain the
following options:
! DB Facility Definition (Two Items and One Event)
!
CREATE DEFINITION DB 2048 /VERSION="Vl.0-0" /OPTIONS

ITEM TRANSACTION ID LONGWORD /ID=l /REPORT HEADER="Transaction ID"/USAGE_TYPE=LEVEL /CHARACTERISTICS=PRINTABLE
ITEM PERF ITEM LONGWORD /ID=2 /REPORT HEADER="Perf item"/USAGE_TYPE=COUNTER /CHARACTERISTICS=PRINTABLE
EVENT TRANSACTION /ID=l /REPORT HEADER="Transaction"/ITEMS= (TRANSACTION_ID, PERF_ITEM, RESOURCE_ITEMS)
EXIT

This facility definition specifies that the event TRANSACTION collects two
facility-specific items (TRANSACTION_ID and PERF_ITEM) along with the
standard resource utilization items.
The data structure used by the facility to pass facility-specific items to
DECtrace is called the record buffer. The DB facility uses a record buffer
with two fields, one for each facility-specific item:
typedef struct record buffer s
{

int transaction_id; /* Item number 1 */
int perf item;
/* Item number 2 */
RECORD_BUFFER_T;

RECORD BUFFER T

record_buffer;

A record buffer variable must be passed by descriptor. Thus the DB facility
contains:

5-14

Instrumenting Applications

#include <descrip.h>

/* VMS Descriptors */

struct dsc$descriptor_s
record_desc;

/* Descriptor for record buffer */

record_desc.dsc$b_class = DSC$K_CLASS_S;
record desc.dsc$w length= sizeof(RECORD BUFFER T);
record=desc.dsc$a:::J>ointer = &record_buff;r;
-

The facility writes the data into the record buffer and calls the appropriate
DECtrace service routine to execute the TRANSACTION event, passing the
address of the descriptor. For example:
record buffer.transaction id =
record buffer.per£ item
status - = epc$event ( . . . &record desc .

A complete sample facility is shown in Example 5-4
Example 5-4

DB Sample Facility

/*******************************************************************************
*
DB - Database Facility
* Facility:
*
DB$TRANS.C
* Module:
*
Module handles transactions for use as a code example
* Abstract:
for issuing DECtrace service routine calls.
*
*
*******************************************************************************/
/*******************************************************************************
**
Header Files
*******************************************************************************/
#include <stdio.h>
/* C standard I/O
*/
#include <ctype.h>
/* C type library
*/
#include <stdlib.h>
/* C standard library
*/
#include <descrip. h>
/* VMS Descriptors
*/
/*******************************************************************************
**
Macro definitions.
*******************************************************************************/
#define FAC NO 2048
/* Facility number */
#define TRANS EVENT ID 1
/* Transaction event ID */

(continued on next page)

Instrumenting Applications

5-15

Example 5-4 (Cont.)

DB Sample Facility

/*******************************************************************************
**
Type definitions.
*******************************************************************************/
typedef struct item_flags_s
{

int offsetl
32;
int offset2
32;
int offset3
32;
int offset4
4;
int epc bio item : 1;
int epc=rest : 27;
ITEM_FLAGS_T;

/* DECtrace BIO item number 101 */
/* DECtrace items 102-128 */

typedef struct record_buffer_s
{

int transaction id; /* Item number 1 */
int perf_item; /* Item number 2 */
RECORD_BUFFER_T;

/*******************************************************************************
**

External References

*******************************************************************************/
globalvalue EPC$ NOTINSTALL;
globalvalue El?C$-SUCCESS;
-

/* DECtrace not installed message */
/* DECtrace success status */
/* Facility version string */

/*******************************************************************************
**

Forward References

*******************************************************************************/
int db$$main(void);
int transaction(void);

/*Main program entry point
/*Transaction function

*/
*/

/*****************************************************************************

*
*

Main Program.

******************************************************************************/

int db$main ()
main_program
{

int status;

/* status Code */

(continued on next page)

S-16

Instrumenting Applications

Example 5-4 (Cont.)

DB Sample Facilly

/* Register with DECtrace */
status= epc$init(l,
FAC NO,
&s_fac_ver,
0,
&s event flags,
&s=event=item_flags,
0,
0,
0) ;

/* EFN */
/* Facility number */
/* Facility ver. string */
/* Registration ID string */
/* Event flags structure */
/* Event item flags structure */
/* rosB */
/* AST address */
/* AST parameter */

if ((status != EPC$_SUCCESS) && (status != EPC$_NOTINSTALL))
{

return (status);
status= transaction();
return (TRUE) ;

}; /* End db$main */

/*****************************************************************************

*
*
*

Transaction function.

******************************************************************************/
int transaction (void)
{

event_handle;
/* Event handle */
record_buffer;
/* The record buffer containing items for */
/* the transaction event */
struct dsc$descriptor s
record_desc;
/* Descriptor for record buffer */

int
RECORD BUFFER T

int

status;

/* Status Code */

record desc.dsc$b class = DSC$K CLASS S;
record-desc.dsc$w-length = sizeof(RECORD BUFFER T);
record=desc.dsc$a~ointer = &record_buffer;
-

(continued on next page)

Instrumenting Applications 5-17

Example 5-4 (Cont.)

DB Sample Facility

/* Start of the TRANSACTION event */
I* Check to see if the TRANSACTION start event should be collected
if (s event flags[TRANS EVENT ID-1]

{

!=FALSE)

I* Get the items for the transaction event */
status= get items(&record buffer);
/* Call EPC$START_EVENT to-log the start of the transaction event */
status = epc$start_event(
1,
/* EFN */
FAC NO,
/* Facility number */
TRANS EVENT Ib,/* Transaction event ID*/
&event_handle, /* Event handle */
0,
/* No thread context var */
&record_desc,
/* Facility items rec. buffer */
O,
/* Completion status */
O,
/* AST address */
0);
/* AST parameter */
if ((status != EPC$_SOCCESS) && (status != EPC$_NOTINSTALL))
return (status);
/* End Then */
/* End of the TRANSACTION event */
/* Check to see if the TRANSACTION end event should be collected */
if (s event flags[TRANS EVENT ID-1] !=FALSE)
{ -

I* Get the items for the transaction event */
status= get items(&record buffer);
/* Call EPC$END EVENT to log the end of the transaction event */
status= epc$end_event(
1,
/* EFN */
FAC_NO,
/* Facility number */
TRANS EVENT ID,/* Transaction event ID */
&event_handle, /* Event handle from start event */
o,
/* No thread context var *f
&record_desc,
/* Facility items rec. buffer */
0,
/* Completion status */
0,
/* AST address *I
0) ;
/* AST parameter */
if ((status != EPC$_SOCCESS) && (status != EPC$_NOTINSTALL))
return (status);

/* End Then */
return (TROE);

}; /* End transaction function */

5-18

Instrumenting Applications

5.6.2.2 Collecting Facility-Specific Items Efficiently Not all of the items
associated with an event are necessarily being collected at any given time. A
facility selection can specify a class that collects only a subset of the items in
a facility definition. For example, the DB facility definition might contain the
following CLASS options where WORKLOAD collects only one facility-specific
item:
! DB Facility Definition (Two Items,

One Event, and Two Classes)

CREATE DEFINITION DB 2048 /VERSION="Vl.0-0" /OPTIONS
ITEM TRANSACTION ID LONGWORD /ID=l /REPORT HEADER="Transaction ID"/USAGE_TYPE=LEVEL /CHARACTERISTICS=PRINTABLE
ITEM PERF ITEM LONGWORD /ID=2 /REPORT HEADER="Perf item"/USAGE _TYPE=COUNTER /CHARACTERISTICS=PRINTABLE
EVENT TRANSACTION /ID=l /REPORT HEADER="Transaction"/ITEMS= (TRANSACTION_ID, PERF_ITEM, RESOURCE_ITEMS)CLASS WORKLOAD TRANSACTION /ITEMS=(TRANSACTION_ID)
CLASS PERFORMANCE TRANSACTION /ITEMS=*
DEFAULT CLASS PERFORMANCE

Thus, for efficiency, a facility can check each item and pass only those items
that are being collected. That information is provided by DECtrace in a data
structure called the item flag list, which is a two-dimensional (128 by 128
element) bit array. Like the event flags list, the address of the item flags
structure is one of the parameters passed to EPC$INIT:
typedef struct item_flags_s
{

int db_trans_id_item : 1;
int db_perf_item : 1;
int offsetl
30;
int offset2
32;
int offset3
32;
int offset4
32;
ITEM_FLAGS_T;
static ITEM_FLAGS_T s_event_item_flags[128];

Using the event ID as an offset, the facility examines the appropriate fields in
the items flags structure to test the flag for each facility-specific item. If the
flag is set, the facility writes the data into the record buffer. For example:

Instrumenting Applications 5-19

if (s_event_flags[TRANS_EVENT_ID-1]

!=FALSE)

{

/* set up descriptor */

if (s_event_item_flags[TRANS_EVENT_ID-1].db_trans_id_item !=FALSE)
{

record buffer.transaction id =
}

if (s_event_item_flags[TRANS_EVENT_ID-1] .db_perf_item !=FALSE)
{

record_buffer.perf_item
}

status

epc$event(

&record desc

5.6.2.3 Collecting Facility-Specific Items with Maximum Efficiency As
stated in Section 5.6.2.2, not all of the items associated with an event are
necessarily being collected at any given time. Some facility-specific items
require a duration event; others require only a point event. Thus, a facility can
minimize overhead by executing an event as either a duration event or a point
event, as needed. For example, a facility definition might contain:

5-20 Instrumenting Applications

DB Facility Definition (Two Items, One Elaborated Event, and
Two Classes)
CREATE DEFINITION DB 2048 /VERSION="Vl.0-0" /OPTIONS
ITEM TRANSACTION ID LONGWORD /ID=l /REPORT HEADER="Transaction ID"/USAGE_TYPE=LEVEL /CHARACTERISTICS=PRINTABLE
ITEM PERF ITEM LONGWORD /ID=2 /REPORT HEADER="Perf item"/USAGE_TYPE=COUNTER /CHARACTERISTICS=PRINTABLE
EVENT TRANSACTION /ID=l /REPORT HEADER="Transaction"/ITEMS=
(TRANSACTION_ID, PERF_ITEM, RESOURCE_ITEMS) /START EVENT=
(TRANSACTION_ID,PERF_ITEM,RESOURCE_ITEMS)(
PERF_ITEM,RESOURCE_ITEMS)/END EVENT=
/POINT_EVENT=
(TRANSACTION_ID
)

CLASS WORKLOAD TRANSACTION /ITEMS=(TRANSACTION_ID)
CLASS PERFORMANCE TRANSACTION /ITEMS=*
DEFAULT CLASS PERFORMANCE

In this facility definition, the TRANSACTION event can be either a duration
event or a point event, depending on which items are being collected. The
/START_EVENT, /END_EVENT, and /POINT_EVENT qualifiers specify which
items are collected in each case.
The PERFORMANCE class requires all items, thus a duration event is
needed. However, because the TRANSACTION_ID item does not change
during the event, it is only necessary to collect it at the start of the event. The
WORKLOAD class requires only the TRANSACTION_ID item; thus a point
event is sufficient.
The facility determines whether a duration event or a point event is needed by
testing whether an item needed only in one type of event is being collected. In
the example, only duration events collect resource utilization items. Thus, the
facility can test a resource utilization item and, if that item is being collected,
execute a duration event; otherwise a point event. For example, the item flags
structure looks something like the following:

Instrumenting Applications 5-21

typedef struct item_flags_s
{

int db trans id item : 1;
int dbyerf_Tte; : 1;
int offsetl
30;
int off set2
32;
int off set3
32;
int offset4
4;
int epc bio item : 1;
int epc=rest : 27;
ITEM_FLAGS_T;

/* facility specific item 1 */
/* facility specific item 2 */

/* DECtrace BIO item number 101 */

In the item flags structure, the DECtrace resource utilization items begin
at nwnber 101. Thus, the facility can examine item 101, which happens to
be buffered inputloutput. If that item is being collected, the facility calls
EPC$START_EVENT event, otherwise EPC$EVENT. For example:
/* Check to see if the TRANSACTION event should be collected */
if (s_event_flags[TRANS_EVENT_ID-1] != FALSE)
{

if (s_event_item_flags[TRANS_EVENT_ID-1] .epc_bio_item !=FALSE)
{

/* This transaction is a duration event */

status

epc$start_event ( . . .

else

/* This transaction is a point event */

status

epc$ event ( . . .

After processing the transaction, the facility can check the item flags structure
again and call EPC$END_EVENT if necessary. For example:

5-22 Instrumenting Applications

if ((s event flags[TRANS EVENT ID-1) !=FALSE) &&
(s=event=item_flags[TRANS_EVENT_ID-1) .epc_bio_item !=FALSE))
/* This transaction is a duration event */

status = epc$end_event(

For maximum efficiency, the facility can use several different record buffers,
each optimized for one type of event. For example:
typedef struct s_record_buffer_s /* start event */
{

int transaction_id; /* Item number 1 */
int perf_item;
/* Item number 2 */
S_RECORD_BUFFER_T;
typedef struct e record_buffer_s /* end event */
{

int perf item;
E RECORD BUFFER_T;

/* Item number 2 */

typedef struct p record_buffer_s /* point event */
{

int transaction_id; /* Item number 1 */
P_RECORD_BUFFER_T;

When the TRANSACTION event is a point event, the only data that the facility
needs to get is the TRANSACTION_ID; thus, the facility sets up and passes
a record buffer containing that field only. It does no harm to pass a buffer
containing PERF_ITEM as well, but this utilizes more disk space.
When the TRANSACTION event is a duration event, the TRANSACTION_ID
item only needs to be collected once (it does not change during the transaction).
Thus, the record buffer passed to EPC$END_EVENT contains only one field
for PERF_ITEM.
A complete sample facility with maximum performance optimizations is shown
in Example 5-5.

Instrumenting Applications 5-23

Example 5-5

DB Sample Facility-Performance Optimized

/*******************************************************************************

DB - Database Facility
* Facility:
*
DB$TRANS.C
* Module:
*
Module handles transactions for use as a code example
* Abstract:
for issuing DECtrace service routine calls. This code example
*
illustrates the most optimal way of collecting events.
*
*
********************************************************************************

/*******************************************************************************
**
Header Files
*******************************************************************************/
#include <stdio.h>
/* c standard I/O
*/
#include <ctype.h>
/* C type library
*/
#include <stdlib.h>
/* c standard library
*/
#include <descrip.h>
/* VMS Descriptors
*/
/*******************************************************************************
**
Macro definitions.
*******************************************************************************/
#define FAC NO 2048
/* Facility number */
#define TRANS_EVENT_ID 1
/* Transaction event ID */
/*******************************************************************************
**
Type definitions.
*******************************************************************************/
typedef struct itern_flags_s
{

int offsetl
32;
int offset2
32;
int offset3
32;
int offset4
4;
int epc_bio_itern : l;
int epc_rest : 27;
ITEM_FLAGS_T;

/* DECtrace BIO item number 101 */

typedef struct e_record_buffer s
{

int perf_itern;
E_RECORD_BUFFER_T;

/* Item number 2 */

typedef struct p_record_buffer_s
{

int transaction_id; /* Item number 1 */
P_RECORD_BUFFER_T;
typedef struct s_record_buffer s
{

int transaction id; /* Item number 1 */
int perf_itern; /* Item number 2 */
S_RECORD_BUFFER_T;

(continued on next page)

5-24 Instrumenting Applications

DB Sample Facility-Performance Optimized

Example 5-5 (Cont.)

/*******************************************************************************
**
Variable declarations.
*******************************************************************************/
static int s_event_flags[l28];
/*Event Flags list*/
static ITEM FLAGS Ts event item flags[128];
/* Event item flags list */
static $DESCRIPTOR(s_fac_ver, "Vl.0-0");
/*******************************************************************************
**
External References
*******************************************************************************/
globalvalue EPC$ NOTINSTALL;
/* DECtrace not installed message */
globalvalue EPC$-SUCCESS;
/* DECtrace success status */
/* Facility version string */
/*******************************************************************************
**
Forward References
*******************************************************************************/
int db$$main(void);
/*Main program entry point
*/
int transaction(void);
/*Transaction function
*/
/******************************************************************************

*
*
*

Main program.

******************************************************************************/
int db$main ()
main_prograrn
{

int status;

/* Status Code */

/* Register with DECtrace */
status= epc$init(l,
FAC_NO,
&s_fac_ver,
0,

&s_event_flags,
&s_event_item_flags,
0,

0) ;

/* EFN */
/* Facility number */
/* Facility ver. string */
/* Registration ID string */
/* Event flags structure */
/* Event item flags structure */
/* IOSB */
/* AST address */
/* AST parameter */

if ((status != EPC$_SUCCESS) && (status != EPC$_NOTINSTALL))
{

return (status);
status= transaction();
return (TRUE);
}; /*End of db$rnain */

(continued on next page)

Instrumenting Applications 5-25

Example 5-5 (Cont.)

DB Sample Facility-Performance Optimized

/******************************************************************************

Transaction function.

******************************************************************************/
int transaction (void)
int
event_handle; /* Event handle */
E RECORD BUFFER T e_record_buffer;
/* The record buffer containing items for *I
/* the transaction end duration event */
P RECORD BUFFER T p_record_buffer;
/* The record buffer containing items for *I
I* the transaction point event */
S RECORD BUFFER T s record_buffer;
I* The record buffer containing items for */
/* the transaction start duration event */
struct dsc$descriptor s
record_desc;
/* Descriptor for record buffer */
int

/* Status Code */

status;

/* Start of the TRANSACTION event */
/* Check to see if the TRANSACTION event should be collected */
if (s event flags[TRANS EVENT ID-1) !=FALSE)

{

if (s_event_item_flags[TRANS_EVENT_ID-1) .epc_bio_item !=FALSE)
{

/* This transaction is a duration event */
record desc.dsc$b class = DSC$K CLASS S;
record-desc.dsc$w-length = sizeof(S RECORD BUFFER T);
record=desc.dsc$a~ointer = &s_record_buffer;
/* Get the items for the transaction event */
status= get items(&s record buffer);
/* Call EPC$START EVENT for the start of the transa.ction event */
status= epc$start_event(
11
/* EFN */
FAC_NO,
/* Facility number */
TRANS EVENT ID,/* Transaction event ID */
&event handle, /* Event handle */
O,
/* No thread context var */
&record desc,
/* Facility items rec. buffer */
0,
/* Completion status */
O,
/* AST address */
O);
/*AST parameter*/

(continued on next page)

5-26 Instrumenting Applications

Example 5-5 (Cont.)

DB Sample Facility-Performance Optimized

if ((status != EPC$_SUCCESS) && (status != EPC$_NOTINSTALL))
{

return (status);
/* End Then */
else
/* This transaction is a point event */
record desc.dsc$b class = DSC$K CLASS S;
record-desc.dsc$w-length = sizeof (P RECORD BUFFER T);
record=desc.dsc$a:Yointer = &p_reco~d_buffer;
/* Get the transaction ID item for the transaction event */
status= get trans id(&p record buffer);
/*call EPC$EVENT for the point-event */
status= epc$event(
1,
/* EFN */
FAC_NO,
/* Facility number */
TRANS EVENT ID,/* Transaction event ID */
O,
/* No thread context var */
&record desc,/* Facility items rec. buffer */
O,
/* Completion status */
0,
/* AST address */
0);
/* AST parameter */
if ((status != EPC$_SUCCESS) && (status != EPC$_NOTINSTALL))
{

return (status) ;
/* End Else *I
/* End Then */
/* End of the TRANSACTION event */
/* Check to see if the end of TRANSACTION event should be collected */
if ((s event flags[TRANS EVENT ID-1] !=FALSE) &&
(s=event=item_flags[TRANS_EVENT_ID-1) .epc_bio_item !=FALSE))
/* This transaction is a duration event */
record desc.dsc$b class = DSC$K CLASS S;
record=desc.dsc$w=length = sizeof(E_RECORD_BUFFER_T);
record_desc.dsc$a_pointer = &e_record_buffer;
/* Get the items for the transaction event */
status= get items(&e record buffer);
/* Call EPC$END EVENT-for the end of the transaction event */
status= epc$end_event(
1,
/* EFN */
FAC_NO,
/* Facility number */
TRANS EVENT ID,/* Transaction event ID */
&event handle; /* Event handle */
O,
/* No thread context var */
&record_desc,
/* Facility items rec. buffer */
0,
/* Completion status */
O,
/* AST address */
O);
/*AST parameter*/

(continued on next page)

Instrumenting Applications 5-27

Example 5-5 (Cont.)

DB Sample Facility-Performance Optimized

if ((status != EPC$_SUCCESS) && (status != EPC$_NOTINSTALL))
{

return (status);

/* End Then */
return (TRUE) ;

}; /* End transaction routine */

5.7 Instrumenting a Multi-Threaded Facility Using VAX
BLISS-32
This section contains an example of the code modifications required for an
event called TRANSACTION for the multi-threaded facility, NEW_TOOL. The
example contains code segments written in BLISS-32 and is composed of four
routines:
• NEWT$$INITIALIZE
• NE,VT$$THREAD_START_RESUME
• NEWT$$THREAD_DELETE
• NEWT$$TRANSACTION
The NEWT$$INITIALIZE routine represents a place in the source code for the
facility code where the first code execution takes place. NEWT$$THREAD_
START_REStJME represents a place in the code where new threads begin code
execution or existing threads resume code execution. The NEWT$$THREAD_
DELETE routine represents a place in the code where threads have completed
code execution, and NEWT$$TRANSACTION represents a place in the code
that comprises a TRANSACTION event.
The following sections describe the steps required to instrument each of the
the NEW_TOOL routines with DECtrace service routine calls.

5.7. 1 Coll EPC$1NIT to Register the NEW_TOOL Facility
When the NEW_TOOL facility image activates, this code issues a call to the
EPC$INIT service routine. This is the only time that a call to EPC$INIT is
issued for the NEW_TOOL facility. The EPC$JNIT call registers the facility
with DECtrace and allows this facility to collect data, provided that a user
schedules a collection to occur while this facility is executing.

5-28 Instrumenting Applications

!--------------------------------------------------------------------! Global routine NEWT$$INITIALIZE

LITERAL
max events = 128,
max_items = 128,
facility_number = 2049,
trans event id = O,

newt$k_dbs_writes_item= l;

FIELD
trans event rec fields

SET
dbs reads item
dbs writes item
TES;
OWN
event_flags

item_flags

Number of events/facility.
Number of items/facility.
Non-registered facility # for NEW TOOL
Event ID for TRANSACTION event. Note
that BLISS begins bitvector offsets
at 0. (Event ID - 1)
Item #2, DBS writes. (Item # - 1 for
BLISS)
Note that BLISS begins
bitvector offsets at 0.
TRANSACTION start and end event record
template. Note that the record
contains all possible items for the
transaction event

[O, O, 32, 0),
[ 4, 0, 32' 0] '

Total number of database reads.
Total number of database writes.

BLOCK [max_events,LONG] VOLATILE,
Vector to determine
whether to collect data
for a given event.
Offset is the event ID.
BLOCK [max_events*l6,BYTE] VOLATILE,
Vector of item_flags.
! Offset is the event ID.

trans_event_record_desc : BLOCK[DSC$C_S_BLN,BYTE] PRESET ! Record
! descriptor
([DSC$W_LENGTH] = 8, ! Length of event record
[DSC$B_CLASS]
DSC$K_CLASS_S),
The pointer will point
to the event record in
the thread block.
cond_status;
BIND
facility_ version

%ASCID 'Tl. 0-1',

The version of the NEW TOOL
facility.

trans item_flags =
item_flags[trans_event_id)-1 : BITVECTOR[max_items];
! The item flags for the
TRANSACTION event.

Instrumenting Applications

5-29

Perform facility initialization tasks, including a call to the
EPC$INIT service.
cond status = EPC$INIT (O,facility number,
facility_v;rsion,
O,event_flags,item_flags);

5.7.2

Call EPC$SET_CONTEXT to Set Thread Context

At the place where the thread resumes execution or immediately following
the place where the thread block is allocated for a new thread, a call to the
EPC$SET_CONTEXT service routine is issued. This call tells DECtrace to
keep some new context (resource utilization items) for this new thread and also
passes back a new thread identifier to the NEW_TOOL facility. When a thread
is resuming execution, this call merely tells DECtrace that the thread context
should be updated (that is, resource utilization items should be charged to this
thread).

!--------------------------------------------------------------------Global routine called NEWT$$THREAD_START_RESUME
When creating a new thread, allocate a thread block (called
thread_block) for storage local to this thread only.
In addition,
initialize the thread id field to zero, so you pass a zero value
thread identifier argument to EPC$SET CONTEXT. EPC$SET CONTEXT
then fills in the thread id field with a unique value a;sociated
with this thread.
Call EPC$SET CONTEXT to tell DECtrace that a new thread is
executing or-that an existing thread is resuming execution.
cond status

EPC$SET_CONTEXT (0,thread_block[thread_id]);

Call the NEWT$$TRANSACTION routine to process the database
transaction.
cond status

NEWT$$TRANSACTION ( ... );

5-30 Instrumenting Applications

5.7.3

Call EPC$DELETE_CONTEXT to Delete the Thread Context

When the thread has completed execution, prior to where the NEW_
TOOL facility deallocates the thread block for this thread, a call to the
EPC$DELETE_CONTEXT service routine is issued. The call tells DECtrace
no longer keep track of the resource utilization items for this thread.

!--------------------------------------------------------------------Global routine called NEWT$$THREAD DELETE
Call EPC$DELETE CONTEXT to tell DECtrace not to keep resource
utilization items for this thread any longer.
cond status= EPC$DELETE_CONTEXT (O,thread_block[thread_id]);
Deallocate the thread block.

5.7.4

Call EPC$START_EVENT and EPC$END_EVENT to Collect
Event Data

At the place in the code where the TRANSACTION event starts, a call to
the EPC$START_EVENT service routine is issued. At the place in the code
where the TRA.i."l\ISACTION event ends, a call to the EPC$END_EVENT service
routine is issued.

!--------------------------------------------------------------------Global routine called NEWT$$TRANSACTION.
Start of event called TRANSACTION.
For efficiency, test to see
if the TRANSACTION event is to be collected prior to calling
EPC$START_EVENT.
IF .event_flags[trans_event_id]-1 EQL 1
THEN
trans_event_record_desc[DSC$A_POINTER]
thread block[trans event record];
cond status
EPC$START_EVENT (0,facility_number,
trans_event_id,
thread block[event handle],
thread=block[thread_id],
trans_event_record_desc);
} Do all normal processin·g for the event.

Instrumenting Applications 5-31

Test to see if DBS_WRITES item should be captured for the
TRANSACTION event.
If so, when writes occur for the event,
update the count in the event record.
IF .trans item flags[newt$k dbs writes item]-1 EQL 1
THEN thre;d bl;ck[trans eve~t r;cord] [dbs writes item]
.thread_block[trans=event_record] [dbs_;rites_item] + l;

End of event called TRANSACTION. For efficiency, test to see if
the TRANSACTION event is to be captured prior to calling
EPC$END_EVENT.
IF .event_flags[trans_event_id]-1 EQL 1
THEN
trans event record desc[DSC$A POINTER]
th;ead block[trans event record];
cond status= EPC$END EVENT (O,fa;ility numbe-;,
trans_event_Id,
thread block[event handle],
thread=block[thread_id],
trans_event_record_desc);

5.8 Linking an Instrumented Program
There are two methods for linking an instrumented program. Which one you
use depends on whether or not DECtrace is installed on the target system (the
system where you will be running the application), and the version of VMS on
that system.
The DECtrace shareable image (SYS$SHARE:EPC$SHR.EXE) is included
with VMS Version 5.2 and higher, and is present on all systems where the
DECtrace software is installed. To link an instrumented program on these
systems, simply use the VMS LINK command. The resulting executable image
will run on any system with VMS Version 5.2 or higher, or any system where
DECtrace is installed. The following example shows the command to link the
ATM sample application:
$

LINK EPC$ATM-SAMPLE. OBJ

If you intend to run your application on a VMS Version 5.0 or Version 5.1

system where DECtrace is not installed, you must use LIB$FIND_IMAGE_
SYMBOL in your instrumentation to resolve symbolic references to the
DECtrace service routines. Use the LIB$FIND_IMAGE_SYMBOL call to
conditionalize each of the DECtrace service routine calls. If DECtrace is
not installed on the target system, the program should not attempt to make
any of the DECtrace calls. Make the calls using the symbols returned from
LIB$FIND_IMAGE_SYMBOL instead of making calls directly to the DECtrace

5-32 Instrumenting Applications

service routines. Note that this method also works for VMS Version 5.2 and
higher target systems, although it is not required.
Example 5-6 shows a code segment of an instrumented program which uses
LIB$FIND_IMAGE_SYMBOL calls. The example is written in VAX C.
Example·S-6

Instrumentation Using LIB$FIND_IMAGE_SYMBOL

extern unsigned long int
extern unsigned long int
extern unsigned long int
extern unsigned long int
extern unsigned long int
extern unsigned long int
extern unsigned long int
extern unsigned long int
extern unsigned long int

(*MYFAC$EPC$DELETE CONTEXT)();
(*MYFAC$EPC$END EvENT) ();
(*MYFAC$EPC$END=EVENTW) ();
(*MYFAC$EPC$EVENT) ();
(*MYFAC$EPC$EVENTW) ();
(*MYFAC$EPC$INIT) ();
(*MYFAC$EPC$SET CONTEXT)();
(*MYFAC$EPC$START_EVENT) ();
(*MYFAC$EPC$START_EVENTW) ();

$DESCRIPTOR (facility ver, "Vl. 0-0") ; /* Facility Version
$DESCRIPTOR (epc_lib=desc, "EPC$SHR");
$DESCRIPTOR
$DESCRIPTOR
$DESCRIPTOR
$DESCRIPTOR
$DESCRIPTOR
$DESCRIPTOR
$DESCRIPTOR
$DESCRIPTOR
$DESCRIPTOR

(delete context desc, "EPC$DELETE CONTEXT");
(end ev-ent desc-, "EPC$END EVENT");
(end=eventw_desc, "EPC$END_EVENTW");
(event desc, "EPC$EVENT");
(eventw_desc, "EPC$EVENTW");
(init_desc, "EPC$INIT");
(set context desc, "EPC$SET CONTEXT");
(start event-desc, "EPC$START EVENT");
(start=eventw_desc, "EPC$START_EVENTW");

/* Get entry points into DECtrace */
status
LIB$FIND IMAGE SYMBOL (&epc lib desc
- &del~te_context_d~sc ~ &MYFAC$EPC$DELETE_CONTEXT);
/* Error check */
status = LIB$FIND_IMAGE_SYMBOL (&epc_lib_desc ,
&end_event_desc, &MYFAC$EPC$END_EVENT);
/* Error check */
status = LIB$FIND IMAGE SYMBOL (&epc lib desc ,
- &end=eventw_desc ~ &MYFAC$EPC$END_EVENTW);
/* Error check */
status = LIB$FIND_IMAGE .SYMBOL (&epc lib desc ,
&event desc, &MYFAC$EPC$EVENT);
/* Error check */
status = LIB$FIND_IMAGE SYMBOL (&epc lib desc ,
&eve~tw_desc, &MYFAC$EPC$EVENTW);
/* Error check */
status = LIB$FIND_IMAGE SYMBOL (&epc_lib_desc ,
&init_desc, &MYFAC$EPC$INIT);
/* Error check */
status = LIB$FIND_IMAGE SYMBOL (&epc lib desc ,
&set_context_desc-, &MYFAC$EPC$SET_CONTEXT);

(continued on next page)

Instrumenting Applications 5-33

Example 5-6 (Cont.)

Instrumentation Using LIB$FIND_IMAGE_SYMBOL

/* Error check */
status = LIB$FIND_IMAGE_SYMBOL (&epc lib desc ,
&start event desc , &MYFAC$EPC$START_EVENT);
/* Error check */
status = LIB$FIND IMAGE SYMBOL (&epc lib desc ,
- &sta~t_eventw_des~ , &°MYFAC$EPC$START_EVENTW);
/* Error check */
/* If all calls to LIB$FIND IMAGE SYMBOL returned success */
if ((status & 1) == 1)
{

/* Issue initialize call to DECtrace Registrar */
status

= MYFAC$EPC$INIT(event_flag,
MYFAC$ _FACILITY,
&facility_ver,
&registration_id,
&MYFAC$_EPC_EVENT_FLAGS,
&MYFAC$_EPC_ITEM_FLAGS,
&init iosb,
0,
0);

5-34

Instrumenting Applications

/* Event Flag Number
*/
/* Facility number
*/
/* Facility version string*/
/* Registration ID string */
/* Event flags structure */
/* Event item flags struc */
/* IOSB
*/
/* AST address
*/
/* AST parameter
*/

6
Creating Facility Definitions

Each application program that is instrumented with DECtrace service routine
calls must provide a facility definition, which describes the events in the
application and the items to collect for each event. A facility definition also
provides useful information for reporting purposes, such as header information
for the events and items.
This chapter describes how to work with DECtrace facility definitions
including:
•

Creating facility definitions

•

Deleting facility definitions

•

Transporting facility definitions between systems

•

Displaying information about facility definitions stored in the DECtrace
administration database

Table 6-1 summarizes the DECtrace commands available to manipulate
facility definitions. See Chapter 7 for a description of the commands and their
syntax.
Table 6-1

Facility Definition Commands

Command

Description

CREATE DEFINITION

Creates a facility definition and stores it in the
DECtrace administration database.

DELETE DEFINITION

Deletes a facility definition from the DECtrace
administration database.
(continued on next page)

Creating Facility Definitions 6-1

Table 6-1 (Cont.)

Facility Definition Commands

Command

Description

EXTRACT DEFINITION

Extracts a facility definition from the DECtrace
administration database and stores it in a binary
file.

INSERT DEFINITION

Inserts a facility definition into the DECtrace
administration database from a binary DECtrace
facility definition file.

SHOW DEFINITION

Displays information about facility definitions in
the DECtrace administration database.

6. 1 Creating a Facility Definition
DECtrace facility definitions consist of:
• Name of the facility.
• ID number of the facility. Numbers in the range 1 to 2047 are reserved to
Digital and are referred to as registered facilities. Numbers in the range
2048 to 4095 specify non-registered facilities.
• Version of the facility (up to 10 characters). Some typical formats of version
strings are:
Vnn.nn (versions of software)
Vnn.nn-nn (versions and baselevels or revision levels of software)
Tnn.nn-nn (field test versions of software and baselevel)
• List of the events that occur within the facility.
• List of facility-specific items associated with the events.
The format of the CREATE DEFINITION command is:

CREATE DEFINITION facility _name facility_id

IEVENTS=(event_name[, ... ]) ]
!OPTIONS[=file_specj
[ !REPLACE
/VERSION=" version_ code"

There are two methods for creating a facility definition. You can create a
simple definition that associates only the default resource utilization items
(shown in Table 6-2) with your events, or you can create an advanced definition
with items that are specific to your application.

6-2

Creating Facility Definitions

To collect the default data, you can create the definition interactively. For
example, the following command creates the facility definition for the DB
facility which has two events:
$

COLLECT CREATE DEFINITION DB 2048 /VERSION="Vl.0-0" /EVENTS=(EVENT_l, EVENT_2)

To create a more detailed definition including facility-specific items, you should
use the /OPTIONS qualifier to the CREATE DEFINITION command and
specify an options file. There are several different ways to use the /OPrIONS
qualifier:
• Enter the /OPTIONS qualifier interactively without supplying a file
specification; DECtrace prompts you for the options. For example:
$ COLLECT
DECtrace> CREATE DEFINITION DB 2048 /VERSION="Vl.0-0" /OPTIONS
Option> ITEM TRANSACTION ID LONGWORD /ID=l

• Enter the /OPrIONS qualifier interactively and supply a file specification
that DECtrace uses as a source for facility definition options. For example:
$ COLLECT CREATE DEFINITION DB 2048 /VERSION="Vl.0-0" _$ /OPTIONS=DB_OPTIONS.OPT

• Invoke DECtrace to execute a file that contains the CREATE DEFINITION
command as well as the options:
$

COLLECT @DEFINE_DB.COM

• Execute a VMS command procedure that invokes DECtrace, enters the
CREATE DEFINITION command, and so forth. For example:
$

@DB.COM

6. 1. 1 Creating and Defining Events
DECtrace collects data for events which occur during run time. In the
automated teller machine (ATM) sample application, the defined events are:
•

Customer checks account balance.

•

Customer deposits funds into account.

•

Customer withdraws funds from account.

•

Customer makes an error and the application displays an error message.

The balance, deposit, and withdrawal events are duration events, which
begin when the customer selects the appropriate menu option and end when
the transaction is complete. The error message event is a point event, which
has no logical start or end and simply occurs.

Creating Facility Definitions 6-3

Once you have determined the events that your facility contains, you must
instrument your source code with DECtrace service routine calls. Chapter 5
describes how to instrument your code, and Chapter 8 describes the formats of
the service routines.
After instrumenting your code, you must create- a facility definition that
includes the events you have implemented. The /EVENTS qualifier to the
CREATE DEFINITION command specifies a list of events that occur within
the facility. Note that in a simple facility definition, no distinction is made
between point and duration events. For example, the following command
creates a facility definition for the ATM_SAMPLE application having four
events:
$ COLLECT CREATE DEFINITION ATM SAMPLE 4094 /VERSION="Vl. 0" -

_$ /EVENTS=(ERROR_DISPLAY, BALANCE_EVENT, DEPOSIT_EVENT, WITHDRAW_EVENT)

These events would have the resource utilization items shown in Table 6-2
collected for them. To collect facility-specific items or to collect a subset of the
resource items, you must use the /OPTIONS qualifier instead of the /EVENTS
qualifier. The /OPTIONS qualifier allows you to specify the following EVENT
characteristics:
• Name of the event.
• ID number of the event. The default is the next unused event ID between
1and128.
• Report header to use for the event.
• List of all items associated with the event.
• Items to collect at the start of duration events.
• Items to collect at the end of duration events.
• Items to collect for point events 1.
The format of the EVENT option is:

EVENT event_name

6-4

llDENTIFIER=evenUd
llTEMS=(item_name[, ... ])
/START_ EVENT=(item_name[, ... ])
IEND_EVENT=(item_name[, ... ])
IPOINT_EVENT=(item_name[, ... ])
IREPORT_HEADER=" text"

See Section 5.6.2.3 for a description of how some events can be handled as either a point or
duration.

Creating Facility Definitions

The following example creates the ATM_SAMPLE facility definition using the
/OPTIONS qualifier:
$ COLLECT CREATE DEFINITION ATM SAMPLE 4094 /VERSION="Vl.0" /OPTIONS
Option> EVENT ERROR DISPLAY /ID:;:l /REPORT HEADER="Errors" Option> ITEMS=(RESOURCE ITEMS) /POINT EvENT=(RESOURCE ITEMS)
Option> EVENT BALANCE EVENT /ID=2 /REPORT HEADER="Bala~ce" Option> /ITEMS=(RESOURCE ITEMS) /START EVENT=(RESOURCE ITEMS) -Option> /END EVENT= (RESOURCE ITEMS)
Option> EVENT-DEPOSIT EVENT /ID=3 /REPORT HEADER="Deposits" Option> /ITEMS=(RESOURCE ITEMS) /START EVENT=(RESOURCE ITEMS) -Option> /END EVENT= (RESOURCE ITEMS)
Option> EVENT-WITHDRAW EVENT /ID=4 /REPORT HEADER="Withdrawals" Option> /ITEMS=(RESOURCE ITEMS) /START EvENT=(RESOURCE ITEMS) =Opt ion> /END_EVENT= (RESOURCE_ITEMS)
Option> EXIT

Alternately, you could use a command file to create the ATM_SAMPLE facility
definition2 . For example:
$

COLLECT @EPC$ATM-FAC-DEF.COM

EPC$ATM-FAC-DEF.COM contains the following lines:
CREATE DEFINITION ATM_SAMPLE 4094 /VERSION="Vl.0" /OPTIONS
EVENT ERROR DISPLAY /ID=l /REPORT HEADER="Errors" /ITEMS=(RESOURCE_ITEMS) /POINT EVENT=(RESOURCE ITEMS)
EVENT BALANCE EVENT /ID=2 /REPORT HEADER="Balance" /ITEMS=(RESOURCE ITEMS) /START EVENT=(RESOURCE ITEMS) /END EVENT=(RESOURCE ITEMS)
EVENT DEPOSIT EVENT /ID=3 /REPORT HEADER:;:"Deposits" /ITEMS=(RESOURCE ITEMS)/START EVENT=(RESOURCE ITEMS) /END EVENT=(RESOURCE ITEMS)
EVENT WITHDRAW EVENT /ID=4 /REPORT HEADER="Withdrawals" ::
/ITEMS=(RESOURCE ITEMS) /START_EVENT=(RESOURCE_ITEMS) /END_EVENT=(RESOURCE_ITEMS)
EXIT

See Section 6.5 for a full description of the facility definition options.

6. 1.2 Creating and Defining Items
Items are elements of data associated with each event. They describe what
is collected for the event. Table 6-2 describes the set of standard DECtrace
resource utilization items. Note that these items are often taken as a whole,
and to facilitate this, they can be referred to by the group name: RESOURCE_
ITEMS. If disk space is not a concern, collecting all of the resource items
requires less CPU overhead than collecting a subset of them.

You can find EPC$ATM-FAC-DEF.COM in EPC$EXAMPLES.

Creating Facility Definitions 6-5

Table 6-2

Standard Resource Utilization Items

Item Name

Item ID
Number

Description

Data Type

Usage

BIO

101

Number of buffered I/O operations

Longword

Counter

DIO

102

Number of direct I/O operations

Longword

Counter

PAGEFAULTS

103

Total number of hard and soft page faults

Longword

Counter

PAGEFAULT_IO

104

Number of hard page faults (that is, page
faults to or from the disk)

Longword

Counter

CPU

105

Total amount of CPU time in tens of
milliseconds

Longword

Counter

CURRENT_PRIO

106

Current priority of the process

Word

Level

VIRTU AL_SIZE

107

Number of virtual pages that are currently
mapped for the process

Longword

Level

WS_SIZE

107

Current working set size of the process

Longword

Level

WS_PRNATE

109

Number of pages in the working set that
are private to the process

Longword

Level

WS_GLOBAL

110

Number of pages in the working set that
are globally shared among processes on
the system

Longword

Level

Note DECtrace stamps each data collection record with the current date and time,
extended process identification number (EPID), facility number, and event
identifier. Therefore, the elapsed time information for the EPID, the facility that
logged the event, and the event identifier are always collected.

You can collect information in addition to (or instead of) that provided by the
resource utilization items by creating facility-specific items and associating
them with your events. You use the /OPTIONS qualifier to the CREATE
DEFINITION command to create facility-specific items. The /OPTIONS
qualifier allows you to specify to following ITEM characteristics:
• Name of the item.
• Data type of the item.
• ID number of the item. The default is the next unused item ID between 1
and 100.
• Maximum size (in bytes) of the item.
• Report header for the i tern.
• Width of the column when displaying the item in a DECtrace report.

6-6

Creating Facility Definitions

•

Usage type of the item. Valid types are: LEVEL, COUNTER, PERCENT,
TEXT, and PRIVATE.

•

Characteristics of the item. Items can be either printable or nonprintable.

The format of the ITEM option is:

ITEM item_name datatype

!IDENTIFIER=item_id
!SIZE=n-bytes
!REPORT_ HEADER=" text"
IREPORT_WIDTH=number-of-spaces
!USAGE_ TYPE=usage-type
!CHARACTERISTICS=[nonjprintab/e

The following example creates a facility definition for the NEW_TOOL facility
with five items and two events:
! NEW TOOL facility definition
CREATE DEFINITION NEW_TOOL 2049 /VERSION="Tl.0-1" /OPTIONS

ITEM STREAM ID LONGWORD /ID=l /REPORT HEADER="Stream Id" /REPORT WIDTH=ll /USAGE TYPE=LEVEL /CHARACTERISTICS=PRINTABLE /RADIX=HEXADECIMAL
ITEM DBS-READS LONGWORD /ID=2 /REPORT HEADER="Data File Reads" /REPORT WIDTH=lO /USAGE TYPE=COUNTER /CHARACTERISTICS=PRINTABLE
ITEM DBS WRITES LONGWORD /ID=3 /REPORT HEADER="Data File Writes" /REPORT WIDTH=lO /USAGE TYPE=COUNTER-/CHARACTERISTICS=PRINTABLE
ITEM DB NAME ASCIC /ID=4 /REPORT HEADER="DB Name" /REPORT WIDTH=25 /USAGE TYPE=TEXT /CHARACTERISTICS=PRINTABLE /SIZE=255 ITEM LOCK MODE BYTE /ID=5 /REPORT HEADER="Lock Mode" /REPORT WIDTH=4 /USAGE_TYPE=LEVEL /CHARACTERISTICS=PRINTABLE
EVENT TRANSACTION /ID=l /REPORT HEADER="Transaction" /ITEMS=(RESOURCE ITEMS, STREAM ID, DB NAME, LOCK MODE, DBS READS, DBS WRITES) /START EVENT=(RESOURCE ITEMS, STREAM ID, DB NAME~ DBS READS, DBS WRITES) /POINT-EVENT=(STREAM ID, DB NAME, LOCK MODE) /END EVENT=(RESOURCE-ITEMS,-STREAM ID,-DB NAME, DBS READS, DBS WRITES)
EVENT DATABASE /ID=2 /REPORT HEADER="Databa;e" /ITEMS=(RESOURCE ITEMS, STREAM ID, DB NAME, DBS READS, DBS WRITES) /START EVENT=(RESOURCE ITEMS, STREAM ID, DB NAME, DBS READS, DBS WRITES) /POINT-EVENT=(STREAM ID, DB NAME) - /END_EVENT=(RESOURCE=ITEMS,-STREAM_ID, DB_NAME, DBS_READS, DBS_WRITES)
EXIT

Note that the /OPTIONS and /EVENTS (as described in Section 6.1.1)
qualifiers are mutually exclusive. See Section 6.5 for a full description of
the facility definition options. Section 5.6.2.1 describes how to instrument
items into your application source. code.

Creating Facility Definitions 6-7

6. 1.3

Creating and Defining Collection Classes

DECtrace can collect data from all of the events and items defined for your
facility. However, you can reduce overhead in terms of both CPU and disk
space utilization by collecting only data that pertains to your current needs.
You can create subsets of your events and items that are relative to specific
collection purposes. A facility selection (as described in Chapter 2) can
specify a collection class to limit data collection to only that data that is
important to the user. You can create a class for any usage. However, Digital
recommends that application product developers define one or more of the
following standard classes:
•

CAPACITY_PLANNING-Includes those events and items that are useful
for capacity planning purposes.

•

DEBUGGING-Includes those events and items that are useful for tracing
the execution of your application.

•

ERROR_LOGGING-Includes those events and items that are associated
with error handling routines in your application.

•

PERFORMANCE-Includes those events and items that are useful for
application and/or database tuning.

• WORKLOAD-Includes those events and items that are useful for
gathering information for tracing the actual workload of the application or
the database management system.
Use the /OPTIONS qualifier to the CREATE DEFINITION command to create
collection classes. The format of the CLASS option is:
CLASS class_name event_name

/ITEMS=(item_name[, ... ])

To define a collection class, list each event you want to include in the class and
specify the items that you want to collect for that event. Later, you can specify
that class on the CREATE SELECTION command (see Section 2.2). If you do
not include an event in the class definition, no data is collected for that event
when the application executes. The following example defines WORKLOAD
and PERFORMANCE classes for the NEW_TOOL application:
NEW TOOL facility definition
CREATE DEFINITION NEW TOOL 2049 /VERSION="Tl.0-1" /OPTIONS
!
ITEM STREAM ID LONGWORD /ID:o::l /REPORT HEADER="Stream Id" /REPORT WIDTH=ll /USAGE TYPE=LEVEL /CHARACTERISTICS=PRINTABLE /RADIX=HEXADECIMAL
ITEM DBS-READS LONGWORD /ID=2 /REPORT HEADER="Data File Reads" /REPORT WIDTH=lO /USAGE TYPE=COUNTER /CHARACTERISTICS=PRINTABLE
ITEM DBS WRITES LONGWORD f ID=3 /REPORT HEADER="Data File Writes" /REPORT WIDTH=lO /USAGE TYPE=COUNTER-/CHARACTERISTICS=PRINTABLE
ITEM DB NAME ASCIC /ID=4 fREPORT HEADER="DB Name" /REPORT WIDTH=25 /USAGE_TYPE=TEXT /CHARACTERISTICS=PRINTABLE /SIZE=255 ITEM LOCK MODE BYTE /ID=S /REPORT HEADER="Lock Mode" /REPORT WIDTH=4 /USAGE_TYPE=LEVEL /CHARACTERISTICS=PRINTABLE
-

6-8

Creating Facility Definitions

EVENT TRANSACTION /ID=l /REPORT HEADER="Transaction" /ITEMS=(RESOURCE ITEMS, STREAM ID, DB NAME, LOCK MODE, DBS READS, DBS WRITES) /START EVENT=(RESOURCE ITEMS, STREAM ID, DB NAME:- DBS READS, DBS WRITES) /POINT-EVENT=(STREAM ID, DB NAME, LOCK MODE) /END EVENT=(RESOURCE-ITEMS,-STREAM ID,-DB NAME, DBS READS, DBS WRITES)
EVENT DATABASE /ID=2 /REPORT HEADER="Database" /ITEMS=(RESOURCE ITEMS, STREAM ID, DB NAME, DBS READS, DBS WRITES) /START EVENT=(RESOURCE ITEMS, STREAM ID, DB NAME, DBS READS, DBS WRITES) /POINT-EVENT= (STREAM ID, DB NAME) - /END_EVENT=(RESOURCE=ITEMS,-STREAM_ID, DB_NAME, DBS_READS, DBS_WRITES)
CLASS WORKLOAD DATABASE /ITEMS=(STREAM ID, DBS READS, DBS WRITES)
CLASS WORKLOAD TRANSACTION /ITEMS=(STREAM ID, LOCK MODE, DBS_READS, DBS_WRITES)
!
CLASS PERFORMANCE TRANSACTION /ITEMS=*
DEFAULT CLASS WORKLOAD
EXIT

Note that the ALL class is created by default when you create a facility
definition and is composed of all events and associated items in your facility.
The ALL class is also the default class unless you specify another with the
DEFAULT_CLASS option.
See Section 6.5 for a full description of the facility definition options.
Section 5.6.2.2 describes how to use classes efficiently and how to instrument
the relevant events and items into your application source code.

6.2 Deleting Facility Definitions
You can delete facility definitions from the DECtrace administration database
with the DELETE DEFINITION command. Note that you do not delete the
actual facility images from your system, but merely the DECtrace facility
definitions. To delete definitions of registered facilities (numbered 1 to 204 7),
you must have VMS BYPASS or SYSPRV privilege. To delete definitions of
non-registered facilities (numbered 2048 to 4095), you must either be the
creator of the definition or have VMS BYPASS or SYSPRV privilege.
The following example deletes the facility definition for version Tl.O of the
TEMP_PROG facility:
$ COLLECT DELETE DEFINITION TEMP PROG /VERSION="Tl.0"
Delete TEMP PROG Tl.0 [N]: YES %EPC-S-FACDEL_DELETED, Facility definition TEMP_PROG Tl.O was deleted

You cannot delete a facility definition if any active or pending collections
are collecting data from that facility. Use the SHOW SELECTION
/FORMAT=BRIEF command to determine if a facility has active or pending
data collection associated with it. If it does, you must use the CANCEL
COLLECTION command to stop data collection before you can delete the
facility definition. In addition, you have to delete any facility selections that
explicitly specify the version of the facility whose definition you want to delete.

Creating Facility Definitions 6-9

If a facility selection does not specify the version of the facility and another

version exists on the system, you can delete the facility definition without
canceling scheduled data collection or deleting the facility selection.
The following example shows how to delete a facility definition that has active
data collection associated with it:
$ COLLECT DELETE DEFINITION TEMP PROG /VERSION="Tl.0" /NOCONFIRM
%EPC-F-FACDEL NOTDELETED, Facility is referenced by active data collection
$ COLLECT
DECtrace> SHOW SELECTION/FORMAT=BRIEF

22-AUG-1989 12:11

Facility Selection Information

Page 1
DECtrace Vl.0-0

Selection Name

Facility

Version

Class

Al DATA ENTRY

OA
TESTER
RDBVMS

(latest)
T4.1
V3 . 1

ALL
ALL
ALL

TEST SELECT

TEMP PROG

Tl.O

PERFORMANCE

DECtrace> CANCEL COLLECTION /SELECTION=TEST SELECT /NOCONFIRM
%EPC-S-SCHED_CANCEL, Collection QUICK_TEST is cancelled
DECtrace> DELETE SELECTION TEST SELECT /NOCONFIRM
%EPC-S-SELDEL DELETED, Facility-selection TEST SELECT was deleted
DECtrace> DELETE DEFINITION TEMP PROG /VERSION;;;;""Tl.0"
Delete TEMP PROG Tl.0 [NJ: YES %EPC-S-FACDEL_DELETED, Facility definition TEMP_PROG Tl.O was deleted
DECtrace> EXIT
$

You can use the SHOW DEFINITION /FORMAT=NAMES_ONLY command
to confirm the spelling of the names and the version codes for the facility
definitions that you want to delete.

6.3 Transporting Facility Defi~itions
You can transport a facility definition to another system or VAXcluster with
the EXTRACT DEFINITION and INSERT DEFINITION commands. This
feature is useful in creating installation kits for your applications. Your
installation procedure can automatically add a facility definition to the
DECtrace administration database.

6.3. 1 Extracting Definitions
You can extract a facility definition from the DECtrace administration database
with the EXTRACT DEFINITION command. The command creates a binary
file containing the facility definition information for the specified facility. You
must have VMS BYPASS, SYSPRV, or READALL privilege to extract registered
facility definitions or non-registered facility definitions that were created by
another user. The files are stored in binary format to prevent tampering with
the facility definitions.

6-10

Creating Facility Definitions

The following command extracts the facility definition for version Vl.O of the
ATM_SAMPLE facility. The facility definition is stored in the file ATM_FAC_
DEF.EPC$DEF:
COLLECT EXTRACT DEFINITION ATM SAMPLE ATM FAC DEF /VERSION="Vl.O"
%EPC-S-FACEXT, Facility definition(s) was successfully extracted

6.3.2

Inserting Definitions Using a KITINSTAL.COM Procedure

DECtrace provides a callback procedure compliant with the VMSINSTAL
procedure that any product can use to automatically insert a binary facility
definition into the DECtrace administration database. The procedure is
called INSERT_DEF, and is located in SYS$UPDATE:EPC$VMSINSTAL_
CALLBACK. COM. If DECtrace is not installed on the system, the
procedure inserts the facility definition into the DECtrace facility library:
SYS$COMMON:[SYSLIB]EPC$FACILITY.TLB, which is shipped with Version
5.2 or higher of the VMS operating system.
During installations of DECtrace, the system manager is asked to run
EPC$INSERT.COM (in EPC$EXAMPLES:), which checks the facility
library and moves any facility definitions found there into the DECtrace
administration database.
Example 6-1 shows a segment of a KITINSTAL.COM procedure which includes
the callback. The facility definition for MY_APPLICATION Vl.O is inserted
into the DECtrace administration database.
Example6-1

Sample Procedure to Insert Binary Facility Definitions

$ INSERT DEF:
$

$
$
$

Attempt to insert the facility definition. On error (DECtrace not
installed) insert it into sys$share:epc$facility.tlb

$
$

Parameters:

$
$

P2
P3
P4
PS

$
$
$
$
$

$
$

Return value (see below)
File specification for the binary facility definition file.
The facility name, up to 27 characters in length
The facility version, string up to 10 characters in length.

Return values in P2:
I : Successfully inserted into DECtrace admin db.
L
Successfully inserted into SYS$SHARE:EPC$FACILITY.TLB.
N : No operations were performed.

(continued on next page)

Creating Facility Definitions 6-11

Example 6-1 (Cont.)

Sample Procedure to Insert Binary Facility Definitions

$ !
$ !$ !+

Example of how to call INSERT_DEF callback.

$ !$ !+
$ ! Set up debug mode (VMSINSTAL OPTION K)
$ !o = "!"
! default is nodebug
$
x = "!"
! default is nodebug
$

IF .NOT. P2 THEN GOTO START
ON around OUR code
o = "SET VERIFY"
! OFF around Callbacks
x = "SET NOVERIFY"

$
$

$$ START:

$ !+
$ ! Copy the callback procedures to sys$update.
$ !COPY/NOLOG VMI$KWD:EPC$VMSINSTAL_CALLBACK.COM VMI$ROOT: [SYSUPD]*.*;
$
$
$ INSERT FACDEFS:
$ x
$VMI$CALLBACK PRODUCT EPC$VMSINSTAL CALLBACK:INSERT DEF RETURN SYMBOL VMI$KWD:MY FAC-DEF.EPC$DEF - MY APPLICATION Vl.0-0
$ 0
$IF RETURN SYMBOL .EQS. "N" THEN WRITE SYS$0UTPUT "DECtrace facility definition could not be installed"
$

$ !+
$ ! Delete the callback procedures from sys$update.
$ !-

$
$

DELETE/NOLOG VMI$ROOT: [SYSUPD]EPC$VMSINSTAL_CALLBACK.COM;*

6.3.3

Inserting Definitions Without KITINSTAL.COM

If your installation procedure is not VMSINSTAL compliant, you can use the
INSERT DEFINITION command to insert a facility definition (previously
created with the EXTRACT DEFINITION command) into the DECtrace
administration database on a target system or VAX.cluster. You must have
VMS BYPASS or SYSPRV privilege to insert a facility definition for a facility
that already exists in the target DECtrace administration database and that
was created by another user.

The following command inserts the facility definition for the ATM_SAMPLE
facility into the DECtrace administration database on the target system:
$COLLECT INSERT DEFINITION ATM FAC DEF.EPC$DEF
%EPC-S-FACCRE, Facility definition ATM SAMPLE was created

6-12

Creating Facility Definitions

Registered facilities insert their facility definitions into the DECtrace
administration database as part of their normal installation procedure.
However, if DECtrace does not exist on the target system (the INSERT
DEFINITION command fails), the facility definitions can be stored in the
DECtrace facility library. The installation procedure must perform the
following steps:
Create the facility library SYS$COMMON:[SYSLIBJEPC$FACILITY.TLB if
it does not already exist3 :
$ LIBRARY/TEXT/CREATE=(BLOCK=3,HISTORY=32767,KEYSIZE=39) _ $ SYS$CO.MMON: [ SYSLIB] EPC$FACILITY. TLB

Use the VMS librarian to insert the binary facility definition file into the
DECtrace facility library (note that the module name is a concatenation of
the facility name and the version string):
$ LIBRARY/TEXT/INSERT/REPLACE/MODULE=ATM SAMPLEVl.O _$SYS$COMMON: [SYSLIB]EPC$FACILITY.TLB ATM_FAC_DEF.EPC$DEF

During the DECtrace installation, the system manager can run
EPC$INSERT.COM (in EPC$EXAMPLES:) to automatically insert all of the
facility definitions that exist in SYS$SHARE:EPC$FACILITY.TLB into the
administration database.
If you plan to remove DECtrace from your system but want to retain the

facility definitions stored in your DECtrace administration database (in case
you later decide to reinstall DECtrace), you can extract the facility definitions
from your DECtrace administration database and store them in the DECtrace
facility library.
Use the /LIBRARY qualifier to the INSERT DEFINITION command to insert
a binary facility definition file into the DECtrace facility library. The following
example extracts the facility definition for the ATM_SAMPLE facility from the
DECtrace administration database and stores it in the facility library:
$ COLLECT EXTRACT DEFINITION ATM SAMPLE ATM FAC .DEF /VERSION="Vl. O"
$ COLLECT INSERT DEFINITION ATM_FAC_DEF.EPC$DEF /LIBRARY

6.4 Displaying Facility Definitions
You can display information about the facility definitions stored in the
DECtrace administration database using the SHOW DEFINITION command.
The command takes one argument: the name of a facility. If you do not specify
a facility name, DECtrace displays information on all of the facilities defined
on the system.

EPC$FACILITY.TLB is shipped with Version 5.2 or higher of the VMS operating system.

Creating Facility Definitions 6-13

You can specify the amount of information to display about a facility definition
by using the FORMAT qualifier to the SHOW DEFINITION command. There
are two valid format types:
• FULL
• NAMES_ONLY (default)
The following example writes information in the NAMES_ONLY format about
all of the facility definitions on the system to the file FAC_NAMES.DAT:
$

COLLECT SHOW SELECTION /FORMAT=NAMES_ONLY /OUTPUT=FAC_NAMES.DAT

6.4.1

FULL Format

If you specify /FORMAT=FULL with the SHOW DEFINITION command,
DECtrace displays a full description of facility definitions stored in the
DECtrace administration database. You can display the description of a single
definition if you include its name and version code on the command line. For
example, the following command displays the complete description of the
ATM_SAMPLE definition:
$

COLLECT SHOW DEFINITION ATM_SAMPLE /VERSION="Vl. 0" /FORMAT=FULL

The FULL format display includes the following information:
• Name and version of the facility
• Facility ID number
• Creation date of the facility definition
• User name of the facility definition's creator
• Description of events, items, groups, and classes defined for the facility
Example 6-2 shows a sample of the display produced with the SHOW
DEFINITION /FORMAT=FULL command. The "x" in the Position field
indicates that the items are default item collected by DECtrace and that the
image does not need to allocate space for the item in its event record buffer.
See Section 5.2 for a description of DECtrace data structures.

6-14

Creating Facility Definitions

Display for SHOW DEFINITION Using the Full Format

Example 6-2

Facility Definition Information

28-AUG-1989 17:02
Full Report
Facility:
Number:
Version:
Creation Date:
Created By:

Page 1
DECtrace Vl.0-0

ATM SAMPLE
4094
Vl .0
25-AUG-89 14:17
SYSTEM

Events:
Event Name

Event ID

Report Header

--------------- -------- ---------------ERROR DISPLAY
BALANCE EVENT
DEPOSIT EVENT
WITHDRAW EVENT

ERROR DISPLAY
BALANCE EVENT
DEPOSIT EVENT
WITHDRAW EVENT

1
2
3
4

Items:
Item Name

Item
ID

Datatype

BIO
DIO
PAGEFAULTS
PAGEFAULT IO

101
102
103
104

LONGWORD
LONGWORD
LONGWORD
LONGWORD

CPU
CURRENT PRIO
VIRTUAL SIZE
ws SIZE

105
106
107
108

LONGWORD
WORD
LONGWORD
LONGWORD

ws - PRIVATE
WS GLOBAL

109
110

LONGWORD
LONGWORD

--------------

Max.
Size

Usage
Type

-------

-------4
4
4

COUNTER
COUNTER
COUNTER
COUNTER

4
4

COUNTER
LEVEL
LEVEL
LEVEL

4
4

LEVEL
LEVEL

Item Report
Header

Report
Width

BUFFERED IO
DIRECT IO
PAGEFAULTS
PAGEFAULT
I Os
CPU TIME
CURRENT PRIO
VIRTUAL SIZE
WORKING SET
SIZ
PRIVATE WS
GLOBAL WS

11
11

------------

11
11
11
6

11
11
11

Char Rad

PRT
PRT
PRT
PRT

DEC
DEC
DEC
DEC

PRT
PRT
PRT
PRT

DEC
DEC
DEC
DEC

PRT
PRT

DEC
DEC

Item Groups:
Item Group Name:

RESOURCE ITEMS

Item Name
BIO
DIO
PAGEFAULTS
PAGEFAULT IO
CPU
CURRENT PRIO
VIRTUAL SIZE
WS SIZE
WS PRIVATE
·ws GLOBAL
Class:

ALL

(continued on next page)

Creating Facility Definitions

6-15

Example 6-2 (Cont.)
Event Name:

Display for SHOW DEFINITION Using the Full Format

BALANCE EVENT

Record Type

Item Name

START EVENT

BIO

28-AUG-1989 17:02
Full Report
Record Type

x
Facility Definition Information

Item Name
DIO
PAGEFAULTS
PAGEFAULT IO
CPU
CURRENT PRIO
VIRTUAL SIZE
WS SIZE
WS PRIVATE
WS GLOBAL

END EVENT

POINT EVENT

Position

BIO
DIO
PAGEFAULTS
PAGEFAULT IO
CPU
CURRENT PRIO
VIRTUAL SIZE
WS SIZE
WS PRIVATE
WS GLOBAL
BIO
DIO
PAGEFAULTS
PAGEFAULT IO
CPU
CURRENT PRIO
VIRTUAL SIZE
WS SIZE
WS PRIVATE
WS GLOBAL

Page 2
DECtrace Vl.0-0

Position
x

x
x
x

x
x
x
x
x
x
Y

x
x
x

x
x
x
x
x
x
x
x

x
x
x

x
x

(continued on next page)

6-16

Creating Facility Definitions

Example 6-2 (Cont.)
Event Name:

Display for SHOW DEFINITION Using the Full Format

DEPOSIT EVENT

Record Type

Item Name

START EVENT

BIO
DIO
PAGEFAULTS
PAGEFAULT IO
CPU
CURRENT FRIO
VIRTUAL SIZE
WS SIZE
WS PRIVATE
WS GLOBAL

END EVENT

28-AUG-1989 17:02
Full Report
Record Type

BIO
DIO
FAGEFA.ULTS

Position
x

x
x
x
x
x
x
x
x
x

x
x
x

PAGEFAUL'l' IO

CPU
CURRENT FRIO
VIRTUAL SIZE
ws - SIZE
ws PRIVATE

....
x
x
x
x

Facility Definition Information
Item Name

Page 3
DECtrace Vl.0-0

Position

WS GLOBAL
POINT Ev'ENT

BIO
DIO
PAGEFAULTS
PAGEFAULT IO
CPU
CURRENT PRIO
VIRTUAL SIZE
ws SIZE
ws PRIVATE
WS GLOBAL

x
x
x
x
x
x
x
x
x
x

(continued on next page)

Creating Facility Definitions 6-17

Example 6-2 (Cont.)
Event Name:

Display for SHOW DEFINITION Using the Full Format

ERROR DISPLAY

Record Type

Item Name

START EVENT

BIO
DIO
PAGEFAULTS
PAGEFAULT IO
CPU
CURRENT PRIO
VIRTUAL SIZE
WS SIZE
WS PRIVATE
WS GLOBAL

x
x

BIO
DIO
PAGEFAULTS
PAGEFAULT IO
CPU
CURRENT PRIO
VIRTUAL SIZE
WS SIZE
WS PRIVATE
WS GLOBAL

END EVENT

POINT EVENT

Event Name:

BIO
DIO
PAGEFAULTS
PAGEFAULT IO
CPU
CURRENT PRIO
VIRTUAL SIZE
WS SIZE
WS PRIVATE
WS GLOBAL

Position

x
x

x
x
x
x
x
x

x
x

x
x
x
x
x
x
x
x
x
x
X

x
x
x
x

WITHDRAW EVENT

Record Type

Item Name

START EVENT

BIO
DIO

Position

x
x

(continued on next page)

6-18

Creating Facility Definitions

Example 6-2 (Cont.)
28-AUG-1989 17:02
Full Report
Record Type

Display for SHOW DEFINITION Using the Full Format
Facility Definition Information

Item Name

Page 4
DECtrace Vl. 0-0

Position

--------------- -------PAGEFAULTS
x

PAGEFAULT IO
CPU
CURRENT FRIO
VIRTUAL SIZE
WS SIZE
ws - PRIVATE
ws GLOBAL
END EVENT

POINT EVENT

6.4.2

BIO
DIO
PAGEFAULTS
PAGEFAULT IO
CPU
CURRENT PRIO
VIRTUAL SIZE
ws- SIZE
WS PRIVATE
ws GLOBAL
BIO
DIO
PAGEFAULTS
PAGEFAULT IO
CPU
CURRENT PRIO
VIRTUAL SIZE
WS SIZE
ws PRIVATE
ws GLOBAL

x
x
x
x
x

x
x
x
x
x
x
x
x

NAMES_ONLY Format

If you specify /FORMAT=NAMES_ONLY with the SHOW DEFINITION
command, DECtrace lists the names of the facilities defined on your system.
This format is useful to determine the latest version of a facility installed on
your system. The report also shows the collection classes that are available
for each facility. This is useful to check before creating a facility selection (see
Section 2.2).

Example 6-3 shows a sample of the display produced with the SHOW
DEFINITION /FORMAT=NAMES_ONLY command.

Creating Facility Definitions 6-19

Example 6-3

Display for SHOW DEFINITION Using the Names Only Format

25-AUG-1989 14:28
Names Only Report

Facility Definition Information

Facility:

Version:

Creation Date:

Class:

ATM SAMPLE
RDBVMS

Vl.O

25-AUG-89 14:17
20-AUG-89 15:21

ALL
ALL

(D)

PERFORMANCE
WORKLOAD

(D)

V3.1

Page 1
DECtrace Vl.0-0

6.5 Facility Definition Options
The /OPTIONS qualifier to the CREATE DEFINITION command provides
capabilities beyond those provided by the /EVENTS qualifier, particularly the
ability to collect facility-specific items. Table 6-3 summarizes the facility
definition options.
Table 6-3

Summary of Facility Definition Options

Option

Description

ITEM

Binds the name of a facility-sped.fie item to a unique
numeric identifier and specifies the characteristics of the
data associated with that item.

GROUP

Conveniently allows you to refer to a set of items by a single
name. You can use the group name in an EVENT or CLASS
option to refer to all of the items within that group.

EVENT

Binds the name of an event to a unique numeric identifier
and specifies the items associated with that event.
(continued on next page)

6-20

Creating Facility Definitions

Table 6-3 (Cont.)

Summary of Facility Definition Options

Option

Description

CLASS

DEFAULT_CLASS

•

CAPACITY_PLANNING-Includes those events and
items that are useful for capacity planning purposes.

•

DEBUGGING-Includes those events and items that
are useful for tracing the execution of your application.

•

ERROR_LOGGING-Includes those events and items
that are associated with error or exception handling
routines in your application.

•

PERFORMANCE-Includes those events and items
that are useful for application and/or database tuning.

•

WORKLOAD-Includes those events and items that
are useful for gathering information useful for tracing
the actual workload of the application and/or database
management system.

Indicates which class to collect from if none is specified by
the facility selection.

Note Facility options are order-dependent. Each option must be defined before it is

referenced. The order dependencies are: ITEM, GROUP, EVENT, CLASS, and
DEFAULT_CLASS.

Creating Facility Definitions 6-21

ITEM

ITEM
The ITEM option identifies and describes the characteristics of a data item
that the facility can collect.

Format
ITEM

item-name datatype

Command Qualifiers

Defaults

/CHARACTERISTICS=(characteristic[, ... ])
/I DENTIFIER=item-id
/RA DIX=base-system
/REPORT_HEADER=text
/REPORT_WIDTH=number-of-spaces
/SIZE=n-bytes
/USAGE_TYPE=usage-type

/CHARACTERISTICS=PRINTABLE
Next unused item-id
/RADIX=DECIMAL
/REPORT_HEADER=item-name
See text
See text
None

Parameters
item-name
Specifies a text string that names the item. The string must be a valid VM:S
name, cannot end with a dollar sign ( $) or underscore ( _ ), and cannot be an
Rdb/VMS reserved word.
data type
Specifies the data type of the item. Table 6-4 lists the valid data types.
Table 6-4

ITEM Data Types

Data Type

Description

ASCIC

Varying-length counted string of up to 255 byres

ASCIW

Varying-length counted string of up to 16,383 byres

BYTE

Signed byre

FIXED _ASCIC

Fixed-length counted string of up to 255 bytes
(continued on next page)

6-22 Creating Facility Definitions

ITEM
Table 6-4 (Cont.)

ITEM Data Types

Data Type

Description

LONGWORD

Signed longword (4 bytes)

QUADWORD

Signed quadword (8 bytes)

WORD

Signed word (2 bytes)

Qualifiers
/CHARACTERISTICS=(characteristic[, ... ])

Either PRINTABLE or NONPRINTABLE that specifies whether the contents
of an item can be displayed. The default is PRINTABLE.
/IDENTIFIER=item-id

An integer between 1 and 100 that specifies a unique identifier for the item.
(Identifiers 101 to 128 are reserved for DECtrace-defined items.) The default is
the next unused ID between 1and100.
/RADIX=base-system

Either HEXADECIMAL or DECIMAL that specifies the base of the number
system used for numerical items. The default radix is DECIMAL.
/REPORT_ HEADER=" text"

A text string that specifies a heading to display when creating reports using
this item. The default is the name of the item.
IREPORT_ WIDTH=number-ot-spaces

An integer that specifies the width of the column to use when displaying item
values in a report. The default width depends on the item data type, as listed
in Table 6-5.

Creating Facility Definitions 6-23

ITEM
Table 6-5

ITEM Default Report Widths

Data Type

Width

ASCIC

80 columns

ASCIW

BYTE

FIXED _ASCIC

LONGWORD

QUADWORD

WORD

/SIZE=n-bytes

An integer that specifies the maximum size in bytes of the ASCIC, FIXED_
ASCIC, and ASCIW data types. The /SIZE qualifier is required for these data
types and ignored for all others.
/USAGE_ TYPE=usage-type

One of the keywords in Table 6-6 that specifies how the data is to be used.
Table 6-6

ITEM Usage Types

Usage Type

Description

COUNTER

Typically a running count or total; its value either always increases
or always decreases for the duration of the event. In a DECtrace
Summary report, for items with usage type COUNTER, DECtrace
displays the difference between the start and end values.

LEVEL

A meter or gauge that indicates the current value of some metric; its
value may increase or decrease over the duration of the event.

PERCENT

A percentage; similar to LEVEL, except that it has upper and lower
limits of 100 and 0, respectively.

PRIVATE

Facility-defined data that does not fall into one of the other usages.
DECtrace does not attempt to display this item on DECtrace reports.

TEXT

Text characters.

Valid usage types depend on the data type of the item, as shown in Table 6-7.

6-24 Creating Facility Definitions

ITEM
Table 6-7

ITEM Usage Types by Data Type

Data Type

Valid Usage Types

Default

ASCIC

TEXT, PRIVATE

TEXT

ASCIW

TEXT, PRIVATE

TEXT

BYTE

COUNTER,LEVEL,PERCEN~PRIVATE

COUNTER

FIXED_ASCIC

TEXT, PRIVATE

TEXT

LONGWORD

COUNTER,LEVEL,PERCEN~PRIVATE

COUNTER

QUADWORD

COUNTER, LEVEL, PERCENT, PRIVATE

COUNTER

WORD

COUNTER,LEVEL,PERCEN~PRIVATE

COUNTER

Creating Facility Definitions 6-25

GROUP

GROUP
The GROUP option allows you to refer to a set of items by a single name. You
can use a group name in the /ITEMS qualifier of an EVENT or CLASS option
to refer to all of the items within that group.

Format
GROUP

group-name

Command Qualifier

Default

/ITEMS=(itern-name[, ... ])

None

Parameter
group-name
Specifies the name of the group.

Qualifier
llTEMS=(item-name[, ... })
Specifies the items contained in the group. This is a required qualifier.

6-26

Creating Facility Definitions

EVENT

EVENT
The EVENT option identifies and describes the characteristics of an event
including the set of items to collect and (optionally) the items to collect when
the event is a point event, start event, or end event. By default, DECtrace
places each event in the facility class named ALL.

Format
EVENT

event-name

Command Qualifiers

Defaults

/END_EVENT=(item-name[, ... ])
/Fl RST_SEGMENT_SIZE=n-bytes
/IDENTIFIER=event-id
/[NO]ITEMS=(item-name[, ... ])
/POINT_EVENT=(item-name[, ... ])
/REPORT_HEADER=text
/SEGMENT_SIZE=n-bytes
/START_EVENT=(item-name[, ... J)

See text
None
Next unused event ID
/NOITEMS
See text
/REPORT_HEADER=event-name
None
See text

Parameter
event-name

Specifies the name of the event. The event name must be a valid VMS name
and cannot end with a dollar sign ( $) or underscore ( _ ).

Qualifiers
/END_ EVENT=(item-name[, ... ])

Specifies the items that DECtrace collects at the end of a duration event. If
you omit the /END_EVENT qualifier, DECtrace uses the /ITEMS qualifier to
define the items to collect at the end of a duration event.
/FIRST_ SEGMENT_ SIZE=n-bytes

Specifies the size of the first string segment for the event relation in the
formatted database. If you do not specify a size for the first segment, the
DECtrace formatting component uses 64 bytes.
See the OPTIMIZATION PARAMETERS under the FORMAT command in
Chapter 7 and Section A.1.2 for more information about string segmentation.

Creating Facility Definitions 6-27

EVENT
/IDENTIFIER=item-id

Specifies an integer between 1 and 128 that uniquely identifies the event. The
default is the next unused event identifier between 1 and 128.
llTEMS=(item-name[, ... ])
/NOITEMS (default)

Specifies the set of all items to collect for an event. The default is /NOITEMS.
This is a required qualifier.
/POINT_EVENT:{item-name[, ... ])

Specifies the items that DECtrace collects for a point event. If you omit the
/POINT_EVENT qualifier, DECtrace uses the !ITEMS qualifier to define the
items to collect for a point event.
IREPORT_HEADER:text

Specifies the text to display as a heading when creating reports using this
event. The default report heading is the name of the event.
/SEGMENT_ SIZE=n-bytes

Specifies the size of the remaining string segments (the first having been
defined with the /FIRST_SEGMENT_SIZE qualifier) for the event relation
in the formatted database. If you do not specify a size for the segments, the
DECtrace formatting component uses 128 bytes.
See the OPTIMIZATION PARAMETERS under the FORMAT command in
Chapter 7 and Section A.1.2 for more information about string segmentation.
/START_EVENT=(item-name[, ... ])

Specifies the items that DECtrace collects at the beginning of a duration event.
If you omit the /START_EVENT qualifier, DECtrace uses the !ITEMS qualifier

to define the items to collect at the beginning of a duration event.

6-28

Creating Facility Definitions

EVENT
Description
In the /ITEMS, /START_EVENT, /END_EVENT, and /POINT_EVENT
qualifiers, items are collected in the order specified. You can specify:
• Any item or item group that has already been defined.
• A predefined resource utilization item.
• The predefined item group RESOURCE_ITEMS, which collects all resource
utilization items.
• An asterisk ( * ) as a wildcard symbol, meaning all of the ITEM options in
the facility definition as well as resource utilization items. (This is for the
/ITEMS qualifier only.)

Creating Facility Definitions 6-29

CLASS

CLASS
The CLASS option defines a new class if the specified class does not already
exist and binds an event (with a subset of its associated items) to a class.

Format
CLASS

class-name event-name

Command Qualifier

Default

/[NO]ITEMS=(item-name[, ... ])

/NOITEMS

Parameters
class-name
Specifies the name of the class. A class name must be a unique 1 to 32
character string consisting of alphanumeric characters, dollar signs, and
underscores. The string must be unique within the context of the facility
definition only. The class name ALL is reserved.
event-name
Specifies the name of an event to add to the class. To define a class that
contains multiple events, specify a separate CLASS option for each event.

Qualifier
llTEMS=(item·name[, ... ])
/NOITEMS (default)

Specifies a set of items (or item groups) to collect for an event when the
selection specifies this class. You can supply an asterisk ( * ) as a wildcard
symbol to collect all of the items specified in the EVENT /ITEMS qualifier. The
default is /NOITEMS.

6-30

Creating Facility Definitions

DEFAULT_CLASS

DEFAULT_CLASS
The DEFAULT_CLASS option designates which class to collect when the
facility selection does not specify a class. If you omit the DEFAULT_CLASS
option, the ALL class is designated as the default class. By default, DECtrace
places each event in the facility class named ALL.

Format
DEFAULT_CLASS

class-name

Parameter
class·name

Specifies the name of the default class. It must be the class ALL or a
previously defined class. Digital recommends that the class most frequently
referred to by facility selections be specified as the default class.

Creating Facility Definitions 6-31

7
DECtrace Commands
DECtrace provides a command-line interface. To use the DECtrace commands,
preface them with the keyword COLLECT. For example:
$ COLLECT SHOW VERSION
DECtrace Version Vl.0-0
$

For better user interface performance, you can enter the DECtrace command
environment by entering the COLLECT command with no arguments. This
eliminates binding to the history and administration databases for each
command. DECtrace prompts you for commands until you return to DCL
command level with the EXIT command. For example:
$ COLLECT
DECtrace> SHOW VERSION
DECtrace Version Vl.0-0
DECtrace> EXIT
$

This chapter describes the format and usage of each DECtrace command.
Table 7-1 summarizes the available commands.

DECtrace Commands

7-1

Table 7-1

DECtrace Commands

Command

Description

@ (Execute Procedure)

Executes the commands in a command file as if you had
typed them at the DECtrace>. prompt.

CANCEL COLLECTION

Stops data collection for an active collection. If a
collection is pending, it removes the collection from
the schedule.

CREATE DEFINITION 1

Creates a facility definition in the DECtrace administration database.

CREATE SELECTION

DELETE DEFINITION

Deletes a facility definition from the DECtrace
administration database.

DELETE SELECTION

Deletes a facility selection from the DECtrace
administration database.

EXIT

Exits from DECtrace and returns to the DCL command
level.

EXTRACT DEFINITION

Extracts a facility definition from the DECtrace
administration database and stores it in a binary file.

FORMAT

Formats one or more DECtrace data files into a
formatted data file or database.

HELP

Displays requested information about the DECtrace
commands.

INSERT DEFINITION

Inserts a facility definition in a binary format into the
DECtrace administration database.

REPORT 2

Generates a report based on formatted data from one or
more collections.

SCHEDULE COLLECTION

Schedules data collection based on the specified
qualifiers.

1
Following the CREATE DEFINITION command section are separate reference sections on these
facility definition options: CLASS, DEFAULT_CLASS, EVENT, GROUP, and ITEM.
2

Following the REPORT command section are separate reference sections on these report options:
EVENT, ITEM, and RESTRICTION.

(continued on next page)

7-2

DECtrace Commands

Table 7-1 (Cont.)

OECtrace Commands

Command

Description

SET HISTORY

Changes the history database that DECtrace uses for
the SHOW HISTORY command or creates a new history
database.

SHOW COLLECTION

Shows data collection information in one of two formats:
BRIEF or FULL.

SHOW DEFINITION

Shows information about one or more facility definitions
registered in the DECtrace administration database in
one of two formats: FULL or N.AM:ES_ONLY.

SHOW HISTORY

Shows all error and/or informational messages that have
occurred during one or all data collections active on your
system.

SHOW REGISTER

Shows the individual processes for which data can be
collected.

SHOW SELECTION

Displays a facility selection in one of three formats:
BRIEF, FULL, or NAMES_ONLY.

SHOW VERSION

Shows the version number of DECtrace installed on your
system.

SPAWN

Creates a subprocess of the current process.

STOP SYSTEM

Stops DECtrace and interrupts any active data
collection.

DECtrace Commands

7-3

@ (Execute Procedure)

@(Execute Procedure)
The at sign (@) means execute, just as in DCL. When you type @and the name
of an indirect command file, DECtrace executes the statements in that file as if
you had typed them one at a time at the DECtrace> prompt. The command file
must be a VMS text file that contains DECtrace commands.

Format
@

file-spec

Parameter
tile-spec

The name of the indirect command file. You can specify a full VMS file
specification, a file name, or a logical name. If you specify a file name,
DECtrace looks in your current default VMS directory for a file by that name.
The file must contain valid DECtrace commands. The default file type is COM.

Description
This command is useful because it allows you to prepare a sequence of
commands that you use often and that must be repeated identically each time
you issue them. For example, if you generate weekly or monthly reports, you
will want the same parameters defined each time.

Example
DECtrace> @DISK$USER1: [SMITH.COMS]SCHEDULE_A_COLLECTION.COM

Executes the commands in the file SCHEDULE_A_COLLECTION.COM, where
the command file contains the following lines:
CREATE SELECTION VAX. INFO /OPTIONS FACILITY RDBVMS
FACILITY ACMS/CLASS=ALL
EXIT
SCHEDULE COLLECTION MY TEST MY DATA.DAT /SELECTION=VAX. INFO
/BEGIN=ll:OO /END=12:00
EXIT

7-4 DECtrace Commands

CANCEL COLLECTION

CANCEL COLLECTION
Stops one or more active or pending collections.

Format
CANCEL COLLECTION

(collection-name]

Command Qualifiers

Defaults

/[NO]CONFIRM
/SELECTION=selection-name

/CONFIRM
/SELECTION=*

Parameter
collection-name

The name of the data collection that you want to cancel. The collection name
is a unique text string that identifies one currently scheduled collection. You
can use an asterisk ( * ) as a wildcard to cancel all collections.
The collection name is optional; however, you must specify either the collection
name or a facility selection name (with the /SELECTION qualifier). If you
specify both a collection name and a selection name, the facility selection must
have been specified in the original SCHEDULE COLLECTION command or
DECtrace issues an error message and does not cancel any data collection.

Qualifiers
!CONFIRM (default)
/NOCONFIRM

Specifies whether DECtrace prompts you to confirm the cancellation of each
collection (similar to the VMS DCL command DELETE/CONFIRM).
If you use the /CONFIRM qualifier, DECtrace identifies each collection that
matches the specified collection name and asks if you want to cancel it. If

you use /NOCONFIRM, DECtrace cancels the specified collection(s) without
prompting for confirmation.

DECtrace Commands

7-5

CANCEL COLLECTION
!SELECTION:selection-name

Specifies a facility selection that has one or more collections active or pending
on the current system. If you specify an asterisk ( * ) as a wildcard character in
place of the selection name, DECtrace cancels all data collection.
The /SELECTION qualifier is optional; however, you must specify either a
facility selection name or a collection name. If not, DECtrace issues an error
message indicating that the command is ambiguous.
If you specify both a facility selection name and a collection name, the selection

must have been specified in the original SCHEDULE COLLECTION command
or DECtrace issues an error message and does not cancel any data collection.

Description
In a cluster, the CANCEL COLLECTION command cancels data collection
either locally or cluster-wide, depending on how the collection was originally
scheduled. If you scheduled data collection with the /NOCLUSTER qualifier,
CANCEL COLLECTION cancels the collection locally. If you scheduled data
collection with the /CLUSTER qualifier, CANCEL COLLECTION cancels the
collection on all nodes in the cluster.
If both a collection name and a facility selection name are supplied, they

must be the same as those given in the original SCHEDULE COLLECTION
command.
To cancel data collection, you must be the originator of the collection, or have
VMS BYPASS or SYSPRV privilege.

Examples
$ COLLECT CANCEL COLLECTION MONDAYS_TEST /CONFIRM
Cancel MONDAYS_TEST [N]: YES
%EPC-S-SCHED_CANCEL, Data collection MONDAYS_TEST is cancelled

Cancels the data collection named MONDAYS_TEST.

$ COLLECT CANCEL COLLECTION /SELECTION=ACMS_DATA /NOCONFIRM
%EPC-S-SCHED CANCEL, Data collection MY TEST is cancelled
%EPC-S-SCHED=CANCEL, Data collection TUESDAYS_TEST is cancelled
%EPC-S-SCHED_CANCEL, Data collection WEDNESDAYS_TEST is cancelled

Cancels all data collection associated with the facility selection ACMS_DATA.
In this example, three collections are canceled.

7-6

DECtrace Commands

CANCEL COLLECTION
3

$ COLLECT CANCEL COLLECTION MY_TEST /SELECTION=JOES_DATA /NOCONFIRM
%EPC-E-SCHED XFAILED, Cancel collection operation failed
%EPC-E-SCHED=NTFST, No collections found matching collection MY_TEST
in selection JOES DATA

Attempts to cancel the data collection named MY_TEST. However, MY_TEST
was not scheduled with the facility selection JOES_DATA, so DECtrace issues
an error message and does not cancel the collection.

DECtrace Commands

7-7

CREATE DEFINITION

CREATE DEFINITION
Creates a facility definition and defines its events.

Format
CREATE DEFINITION

facility-name facility-id

Command Qualifiers

Defaults

/EVENTS=(event-name[. ... ])
/[NO)OPTIONS[=file-spec]
/[NO] REPLACE
NE RS ION=" version-code"

See text
/NOOPTIONS
/NORE PLACE
See text

Parameters
facility-name

The name of the facility that you want to define. The maximum length of the
facility name is 27 characters.
facility-id

A unique numeric identifier for the facility. Facility IDs in the range 1 to 2047
are reserved to Digital. You can define facilities with IDs in the range 2048 to
4095. Note that the facility ID must match the ID specified in the EPC$INIT
service routine call (in the program source code).
All versions of a given facility use the same facility ID.

Qualifiers
/EVENTS=(event-name[, ... ])

Specifies the events that the facility includes. If you use the /EVENTS qualifier
to define events, the events collect data on the resource utilization items only,
and you cannot specify additional items.
The /EVENTS and /OPrIONS qualifiers are mutually exclusive, but you must
have one or the other.

7-8 DECtrace Commands

CREATE DEFINITION
/OPTIONS[:file_ spec]
/NOOPTIONS (default)
Specifies a file containing facility definition options. If you do not include a
file specification, the Option> prompt is displayed and you can enter your
options interactively. Facility options are order-dependent. Each option must
be defined before it is referenced.

The /EVENTS and /OPTIONS qualifiers are mutually exclusive, but you must
have one or the other.
Following the CREATE DEFINITION command are individual descriptions of
the facility definition options.
/REPLACE
/NOREPLACE (default)
Specifies that the current facility definition replaces any previously existing
facility definition with the same facility name and version code. If a facility
definition exists and you attempt to redefine it without using the /REPLACE
qualifier, DECtrace issues an error message and does not store the new
definition.
If no facility definition with the same name and version code exists, DECtrace

ignores the /REPLACE qualifier.
NERSION=" version-code"
Specifies the version of the facility. The name of the version can be any
printable string up to 10 characters. You must enclose the text string with
quotation marks (" "). This is a required qualifier and must match the version
specified in the EPC$INIT service routine call.

Description
The CREATE DEFINITION command creates a facility definition that is stored
in the DECtrace administration database, which is available cluster-wide.
The definition is retained until you explicitly delete it using the DELETE
DEFINITION command. DECtrace facility definitions consist of:
•

Class definitions (optional)

•

Creation date

•

Creator's username

Event definitions (optional)

•

Event names

DECtrace Commands

7-9

CREATE D,EFINITION
• Facility ID
• Facility name
• Item definitions (optional)
• Item group definitions (optional)
• Version code
Use the CREATE DEFINITION command to define the facility name,
ID, version code, and event names. DECtrace automatically records your
username and the creation date as part of the facility definition.
You need VMS SYSPRV or BYPASS privilege to create a registered facility
definition.

Examples
$COLLECT CREATE DEFINITION DATA_ENTRY 2052 /EVENTS=(INIT,STOP) _$ /VERSION="Vl. 0"

Creates the facility definition for version Vl.O of the DATA_ENTRY facility and
specifies that the default resource utilization items should be collected for the
events INIT and STOP. The facility ID for DATA_ENTRY is 2052.

$ COLLECT CREATE DEFINITION MY APPLICATION 2050 _$ /VERSION="Tl.0-3" /OPTIONS=MY_APP_OPTIONS.TXT

Creates the facility definition for version Tl.0-3 of the MY_APPLICATION
facility and specifies that the facility definition options listed in the file MY_
APP_OPTIONS.TXT be used. The facility ID for MY_APPLICATION is 2050.
3

$COLLECT CREATE DEFINITION /OPTIONS NEW TOOL 2049 /VERSION="Tl.0-1"
Option> ITEM IMAGE_NAME TEXT/SIZE=256
Option> EVENT INVOCATION/ITEMS=IMAGE_NAME
Option> lCTRL/ZI
$

Creates a facility definition for version Tl.0-1 ofthe NEW_TOOL facility. The
facility has one event (INVOCATION) which has one item (IMAGE_NAME)
associated with it. The facility ID for NEW_TOOL is 2049.

7-1 O DECtrace Commands

CREATE DEFINITION Options-ITEM

CREATE DEFINITION Options-ITEM
The ITEM option identifies and describes the characteristics of a data item
that the facility can collect.

Format
ITEM

item-name datatype

Command Qualifiers

Defaults

/CHARACTERISTICS==( characteristic[, ... ])
/I DENTI FIER=item-id
/RADIX=base-system
/REPORT_HEADER="text"
/REPORT_WIDTH=number-of-spaces
/SIZE=n-bytes
/USAGE_TYPE=usage-type

/CHARACTERISTICS=PRINTABLE
Next unused item-id
/RADIX=DECIMAL
/REPORT_HEADER=item-name
See text
See text
None

Parameters
item-name
Specifies a text string that names the item. The string must be a valid VMS
name, cannot end with a dollar sign ( $ ) or underscore ( _ ), and cannot be an
RdbNMS reserved word.
data type
Specifies the data type of the item. Table 7-2 lists the valid data types.
Table 7-2

ITEM Data Types

Data Type

Description

ASCIC

Varying-length counted string of up to 255 bytes

ASCIW

Varying-length counted string of up to 16,383 bytes

BYTE

Signed. byte

FIXED_ASCIC

Fixed-length counted string of up to 255 bytes
(continued on next page)

DECtrace Commands

7-11

CREATE DEFINITION Options-ITEM

Table 7-2 (Cont.)

ITEM Data Types

Data Type

Description

LONGWORD

Signed longword (4 bytes)

QUADWORD

Signed quadword (8 bytes)

WORD

Signed word (2 bytes)

Qualifiers
/CHARACTERISTICS:(characteristic[, ... ])

Either PRINTABLE or NONPRINTABLE that specifies whether the contents
of an item can be displayed. The default is PRINTABLE.
/IDENTIFIER=item-id

Either HEXADECIMAL or DECIMAL that specifies the base of the number
system used for numerical items. The default radix is DECIMAL.
/REPORT_ HEADER=" text"

A text string that specifies a heading to display when creating reports using
this item. The default is the name of the item.
IREPORT_ WIDTH=number-ot-spaces

An integer that specifies the width of the column to use when displaying item
values in a report. The default width depends on the item data type, as listed
in Table 7-3.

7-12

DECtrace Commands

CREATE DEFINITION Options-ITEM

Table 7-3

ITEM Default Report Widths

Data Type

Width

ASCIC

80 columns

ASCIW

BYTE

FIXED_ASCIC

LONGWORD

QUADWORD

WORD

/SIZE:n-bytes
An integer that specifies the maximum size in bytes of the ASCIC, FIXED_
ASCIC, and ASCIW data types. The /SIZE qualifier is required for these data
types and ignored for all others.
/USAGE_ TYPE=usage-type

One of the keywords in Table 7-4 that specifies how the data is to be used.
Table 7-4

ITEM Usage Types

Usage Type

Description

COUNTER

Typically a running count or total; its value either always increases
or always decreases for the duration of the event. In a DECtrace
Summary Report, for items with usage type COUNTER, DECtrace
displays the difference between the start and end values.

LEVEL

A meter or gauge that indicates the current value of some metric; its
value may increase or decrease over the duration of the event.

PERCENT

A percentage; similar to LEVEL, except that it has upper and lower
limits of 100 and 0, respectively.

PRIVATE

Facility-defined data that does not fall into one of the other usages.
DECtrace does not attempt to display this item on DECtrace reports.

TEXT

Text characters.

Valid usage types depend on the data type of the item, as shown in Table 7-5.

DECtrace Commands

7-13

CREATE DEFINITION Options-ITEM

Table 7-5

7-14

ITEM Usage Types by Data Type

Data Type

Valid Usage Types

Default

ASCIC

TEXT, PRIVATE

TEXT

ASCIW

TEXT, PRIVATE

TEXT

BYTE

COUNTER,LEVEL,PERCEN~PRIVATE

COUNTER

FIXED_ASCIC

TEXT, PRIVATE

TEXT

LONGWORD

COUNTER,LEVEL,PERCEN~PRIVATE

COUNTER

QUADWORD

COUNTER, LEVEL, PERCENT, PRIVATE

COUNTER

WORD

COUNTER,LEVEL,PERCEN~PRIVATE

COUNTER

DECtrace Commands

CREATE DEFINITION Options-GROUP

CREATE DEFINITION Options-GROUP
The GROUP option allows you to refer to a set of items by a single name. You
can use a group name in the /ITEMS qualifier of an EVENT or CLASS option
to refer to all of the items within that group.

Format
GROUP

group-name

Command Qualifier

Default

/ITEMS=(item-name[, ... ])

None

Parameter
group-name
Specifies the name of the group.

Qualifier
llTEMS=(item-name{, ... ))
Specifies the items contained in the group. This is a required qualifier.

DECtrace Commands

7-15

CREATE DEFINITION Options-EVENT

CREATE DEFINITION Options-EVENT
The EVENT option identifies and describes the characteristics of an event
including the set of items to collect and (optionally) the items to collect when
the event is a point event, start event, or end event. By default, DECtrace
places each event in the facility class named ALL.

Format
EVENT

event-name

Command Qualifiers

Defaults

/END_EVENT =(item-name[, ... ])
/FIRST_SEGMENT_SIZE=n-bytes
/I DENTI FIER=event-id
/[NO]ITEMS=(item-name[, ... ])
/POINT_EVENT =(item-name[, ... ])
/REPORT_HEADER=text
/SEGMENT_SIZE=n-bytes
/START_EVENT=(item-name[, ... ])

See text
None
Next unused event ID
/NO ITEMS
See text
/REPORT_HEADER=event-name
None
See text

Parameter
event-name

Specifies the name of the event. The event name must be a valid VMS name
and cannot end with a dollar sign ( $) or underscore ( _ ).

Qualifiers
/END_ EVENT=(item-name[, ... ])

Specifies the size of the first string segment for the event relation in the
formatted database. If you do not specify a size for the first segment, the
DECtrace formatting component uses 64 bytes.
See the OPTIMIZATION PARAMETERS under the FORMAT command and
Section A.1.2 for more information about string segmentation.

7-16

DECtrace Commands

CREATE DEFINITION Options-EVENT
/IDENTIFIER:item-id

Specifies an integer between 1 and 128 that uniquely identifies the event. The
default is the next unused event identifier between 1 and 128.
llTEMS:(item-name[, ... ])
/NO ITEMS (default)

Defines the set of all items to collect for an event. The default is /NOITEMS.
This is a required qualifier.
/POINT_EVENT:(item-name[, ... ])

Specifies the items that DECtrace collects for a point event. If you omit the
/POINT_EVENT qualifier, DECtrace uses the /ITEMS qualifier to define the
items to collect for a point event.
IREPORT_HEADER:text

Specifies the text to display as a heading when creating reports using this
event. The default report heading is the name of the event.
/SEGMENT_ SJZE=n-bytes

Specifies the size of the remaining string segments (the first having been
specified with the /FIRST_SEGMENT_SIZE qualifier) for the event relation
in the formatted database. If you do not specify a size for the segments, the
DECtrace formatting component uses 128 bytes.
See the OITIMIZATION PARAMETERS under the FORMAT command and
Section A.1.2 for more information about string segmentation.
!START_EVENT:(item-name[, ... ])

Specifies the items that DECtrace collects at the beginning of a duration event.
If you omit the /START_EVENT qualifier, DECtrace uses the /ITEMS qualifier

to define the items to collect at the beginning of a duration event.

DECtrace Commands

7-17

CREATE DEFINITION Options-EVENT

Description
In the /ITEMS, /START_EVENT, /END_EVENT, and /POINT_EVENT,
qualifiers, items are collected in the order specified. You can specify:
• Any item or item group that has already been defined.
• A predefined resource utilization item.
•

The predefined item group RESOURCE_ITEMS, which collects all resource
utilization items.

• An asterisk ( * ) as a wildcard symbol, meaning all of the ITEM options in
the facility definition as well as resource utilization items. (This is for the
/ITEMS qualifier only.)

7-18 DECtrace Commands

CREATE DEFINITION Options-CLASS

CREATE DEFINITION Options-CLASS
The CLASS option defines a new class if the specified class does not already
exist and binds an event (with a subset of its associated items) to a class.

Format
CLASS

class-name event-name

Command Qualifier

Default

/[NOJITEMS=(item-name[, ... ])

/NOITEMS

Parameters
class-name

Specifies the name of the class. A class name must be a unique 1- to 32character string consisting of alphanumeric characters, dollar signs ( $ ), and
underscores ( _) . The string must be unique within the context of the facility
definition. The class name ALL is reserved.
event-name

Specifies the name of an event to add to the class. To define a class that
contains multiple events, specify a separate CLASS option for each event.

Qualifier
llTEMS=(item-name[, ... ])
/NOITEMS (default)

Specifies a set of items or item groups to collect for an event when the selection
specifies this class. You can supply an asterisk ( *) as a wildcard symbol to
collect all of the items specified in the EVENT /ITEMS qualifier. The default is
/NO ITEMS.

DECtrace Commands

7-19

CREATE DEFINITION Options-DEFAULT_CLASS

CREATE DEFINITION Options-DEFAULT_CLASS
The DEFAULT_CLASS option designates which class to collect when the
facility selection does not specify a class. If you omit the DEFAULT_CLASS
option, the ALL class is designated as the default class. By default, DECtrace
places each event in the facility class named ALL.

Format
DEFAULT_CLASS class-name

Parameter
class-name
Specifies the name of the default class. It must be the class ALL or a
previously defined class. Digital recommends that the class most frequently
referred to by facility selections be specified as the default class.

7-20 DECtrace Commands

CREATE SELECTION

CREATE SELECTION
Creates a facility selection, that is, a list of the facilities for which to collect
data. You can optionally specify the class of data to collect for each facility.

Format
CREATE SELECTION

selection-name

Command Qualifiers

Defaults

/[NO]COMMENT="comment-string"
/FACILITY=(facility-name[, ... ])
/[NO]OPTIONS[=file-spec]
/[NO] REPLACE

/NOCOMMENT
/FACILITY=*
/NOOPTIONS
/NOREPLACE

Parameter
selection-name

Specifies the name of the facility selection that you want to define. The
selection name must be a unique 1- to 32-character string consisting of
alphanumeric characters, dollar signs ( $ ), and underscores ( _ ). The selection
name must be unique for the local system or for the entire cluster in a cluster
environment.

Qualifiers
/COMMENT
/NOCOMMENT (default)

Allows you to include a comment string describing the selection. The comment
can be up to 80 characters and must be enclosed with quotation marks (" ").
/FACILITY:(facility-name[, ... ])

Specifies one or more facilities for which to collect data. You can use an
asterisk ( *) as a wildcard to have DECtrace collect data for all available
facilities.
Use the /FACILITY qualifier to define simple facility selections where you want
to collect data from the default class for one or more facilities. If you want to
specify a collection class for individual facilities, use the /OPTIONS qualifier.
The /FACILITY and /OPTIONS qualifiers are mutually exclusive.

DECtrace Commands

7-21

CREATE SELECTION
If you do not specify either the /FACILITY or the /OPTIONS qualifier, the

facility selection describes the default class data for all facilities.
!OPTIONS[=file-spec]

Specifies a file that contains the details of the facility selection. The default file
type for the options file is OPT.
If you enter a VMS file specification with the /OPTIONS qualifier, DECtrace
uses that file as a source for facility selection options. If you enter /OPTIONS

without a file specification, DECtrace prompts you for the options interactively.
Press CTRL/Z or type EXIT to exit from the Option> prompt.
The /FACILITY and /OPTIONS qualifiers are mutually exclusive. If you do not
specify either the /FACILITY or the /OPTIONS qualifier, the facility selection
describes the default class data for all facilities. See the Description section for
information about facility selection options.
/REPLACE
/NOREPLACE {default)

Specifies that the current facility selection replaces any previously existing
selection with the same name. If a facility selection exists and you attempt to
redefine it without using the /REPLACE qualifier, DECtrace issues a warning
message and does not store the new selection.
If no facility selection with the same name exists in the DECtrace

administration database, the /REPLACE qualifier is ignored.

Description
DECtrace facility selections consist of:
• The name of the selection
• A list of facilities for which to collect data
• A collection class for each facility
You use the CREATE SELECTION command to choose a subset of the
available facilities for which you want to collect data. You can define most
general-purpose selections with the command without the /OPTIONS qualifier.
For example, the following command defines the facility selection ACMS_DATA
to collect data for the default class for VAX ACMS:
$ COLLECT CREATE SELECTION ACMS DATA /FACILITY=ACMS

7-22 DECtrace Commands

CREATE SELECTION
However, to define a more detailed facility selection, you should use an options
file. The /OPTIONS qualifier allows you to specify a different collection class
for each facility from which you ·want to collect data. The qualifier takes a file
name as an argument. The options file lists each facility and the collection
class you want to use. Each facility is described on a separate line in the file.
If you specify /OPTIONS but do not include a file name, DECtrace prompts you
for the options. The format of the facility description in the options file is:
FACILITY facility-name [NERSION=" version-code"] [!CLASS=class-name]

facility-name
The name of the facility for which to collect data.
version-code
A text string identifying the version of the facility. The string must be enclosed
with quotation marks (" ").
class-name
The class of data that you want collected for the facility. Facilities registered
with DECtrace can have one or more collection classes associated with them.
These classes are subsets of the available events and items chosen for their
significance to a specific function. For example, a facility might have specific
collection classes defined for performance, workload, or capacity planning.
You use the SHOW DEFINITION /FORMAT=NAMES_ONLY command to
determine what classes are available for a given facility. All facilities have the
ALL class which contains all of the events and associated items for the facility.
Furthermore, one of the classes is designated as the default class based on its
predicted importance and frequency of use.

Examples
$ COLLECT CREATE SELECTION ACMS_AND_RDB /FACILITY=(ACMS,RDBVMS)

Creates a facility selection that collects the default events for both the ACMS
and Rdb/VMS facilities. The selection name is ACMS_AND_RDB.

DECtrace Commands

7-23

CREATE SELECTION
2

$ COLLECT CREATE SELECTION VAX INFO DATA /OPTIONS
Option> FACILITY RDBVMS
Option> FACILITY ACMS/CLASS=ALL
Option> FACILITY DBMS/VERSION="V4.1"/CLASS=WORKLOAD
Option> ICTRL/ZI

Creates a facility selection that describes the following data:
• Default collection class data for the latest version of the RdbNMS facility
• All data for the ACMS facility
• Workload class data for Version 4.1 of the DBMS facility

$ COLLECT CREATE SELECTION TP_DATA /OPTIONS=TP_FACS.OPT

Creates a facility selection that collects data on the facilities listed in the
options file TP_FACS.DAT.

7-24

DECtrace Commands

DELETE DEFINITION

DELETE DEFINITION
Deletes one or more facility definitions from the DECtrace administration
database. Use this command when you install a new version of a product
and want to remove the facility definition for the previous version. Deleting
registered facility definitions (those in the range of 1 to 2047) is a management
function that requires VMS BYPASS or SYSPRV privilege to perform. For
non-registered facilities, you must have created the definition, or have VMS
BYPASS or SYSPRV privilege.

Format
DELETE DEFINITION

facility-name [, ... ]

Command Qualifiers

Defaults

/[NO]CONFIRM
NERSION="version-code"

/CONFIRM
See text

Parameter
facility-name

Specifies the name of one or more facilities for which you want to delete the
facility definition. You cannot use any wildcard characters.

Qualifiers
/CONFIRM {default)
/NOCONFIRM

Specifies whether DECtrace prompts you to confirm the deletion of each facility
definition (similar to the VMS DCL command DELETE/CONFIRM).
If you use the /CONFIRM qualifier, DECtrace identifies each facility definition

and version code that matches the specified facility name and version code and
asks if you want to delete it. If you use /NOCONFIRM, DECtrace deletes the
specified facility definition from the DECtrace administration database without
prompting for confirmation.
/VERSION=" version-code"

Specifies the version of the facility for which you want to delete the facility
definition. You must enclose the text string with quotation marks (" "). If
there is more than one version of the facility on the system, you can use the

DECtrace Commands

7-25

DELETE DEFINITION
NERSION qualifier to specify which version you want to delete. However, you
can use an asterisk ( *) as a wildcard character to delete the facility definitions
for all versions of a given facility.
This is a required qualifier.

Description
Use the DELETE DEFINITION command to delete facility definitions from the
DECtrace administration database. You do not delete the actual facility images
from your system, but merely the DECtrace facility definition for that facility.
You cannot delete a facility definition if any active or pending collections
are collecting data from that facility. Use the SHOW SELECTION
/FORMAT=BRIEF command to determine if a facility has active or pending
data collection associated with it. If it does, you must use the CANCEL
COLLECTION command to stop data collection before you can delete the
facility definition. Also, any facility selections that specify the facility definition
explicitly must be deleted. If a facility selection does not specify the version of
the facility and another version exists on the system, you can delete the facility
definition without canceling scheduled data collection.

Examples
$COLLECT DELETE DEFINITION TRANS2 /NOCONFIRM /VERSION="V2.0"
%EPC-S-FACDEL_DELETED, Facility definition TRANS2 V2.0 was deleted

Deletes the TRANS2 version V2.0 facility definition from the DECtrace
administration database.

$COLLECT DELETE DEFINITION TRANS2 /VERSION="V2.0"
Delete TRANS2 V2.0 [N]: YES
%EPC-S-FACDEL_DELETED, Facility definition TRANS2 V2.0 was deleted

Deletes the TRANS2 facility definition from the DECtrace administration
database after prompting for confirmation.

$ COLLECT DELETE DEFINITION MY_APPL /NOCONFIRM /VERSION=*
%EPC-S-FACDEL_DELETED, Facility definition MY_APPL V4.2 was deleted
%EPC-S-FACDEL DELETED, Facility definition MY APPL V4.3 was deleted
%EPC-S-FACDEL=DELETED, Facility definition MY=APPL V4.4 was deleted

Deletes the facility definitions for all versions of the facility MY_APPL by using
the /VERSION qualifier.

7-26 DECtrace Commands

DELETE SELECTION

DELETE SELECTION
Deletes one or more facility selectjons from the DECtrace administration
database.

Format
DELETE SELECTION

selection-name [, ... )

Command Qualifier

Default

/[NO]CONFIRM

/CONFIRM

Parameter
selection-name

Specifies the name of one or more facility selections that you want to delete.
You cannot use \vildcard characters.

Qualifier
/CONFIRM {default)
/NOCON FIRM

Specifies whether DECtrace prompts you to confirm the deletion of each facility
selection (similar to the VMS DCL command DELETE/CONFIRM).
If you use the /CONFIRM qualifier, DECtrace identifies each selection name
that matches the name you specified and asks jf you want to delete it. If you

use /NO CONFIRM, DECtrace deletes all matching facility selections without
prompting for confirmation.

Description
You can delete a facility selection from the DECtrace administration database
with the DELETE SELECTION command. You must be the creator of the
selection or have VMS BYPASS or SYSPRV privilege. You cannot delete a
facility selection if any data collection, either active or pending, is using that
facility selection.

DECtrace Commands

7-27

DELETE SELECTION
To delete a facility selection that is being used in any current or scheduled
data collections, you must first cancel the data collection. See Section 3.4
for information on how to cancel all data collection using a particular facility
selection.

Examples
$ COLLECT DELETE SELECTION ACMS_DATA /NOCONFIRM
%EPC-S-SELDEL_DELETED, Selection ACMS_DATA was deleted)

Deletes the ACMS_DATA facility selection from the DECtrace administration
database.

$ COLLECT DELETE SELECTION RDB DATA
Delete RDB_DATA [N]: YES
%EPC-S-SELDEL_DELETED, Selection RDB_DATA was deleted)

Deletes the RDB_DATA facility selection from the DECtrace administration
database after prompting you for confirmation.

7-28 DECtrace Commands

EXIT

EXIT
Exits DECtrace and returns to the DCL command level. Also used to exit from
the Option> prompt and return to the DECtrace> prompt.

Format
EXIT

Description
Use the EXIT command to quit the DECtrace prompting mode after entering
a series of commands. Alternately, you can press CTRL/Z at the DECtrace>
prompt.

Examples
1

DECtrace> EXIT
$

Exits DECtrace and returns to DCL command level.

DECtrace> lc1RL/Zl
$

Exits DECtrace and returns to DCL command level.

DECtrace> CREATE SELECTION INFO DATA /OPTIONS
Option> FACILITY ACMS/CLASS=ALLOption> FACILITY DBMS/VERSION="V4.1"/CLASS=WORKLOAD
Option> EXIT
DECtrace>

Exits from the DECtrace options environment and returns to the DECtrace>
prompt.

DECtrace Commands

7-29

EXTRACT DEFINITION

EXTRACT DEFINITION
Extracts a facility definition from the DECtrace administration database
and stores it in a binary file. You can later use the INSERT DEFINITION
command to store the extracted facility definition in another DECtrace
administration database.

Format
EXTRACT DEFINITION

facility-name file-spec

Command Qualifier

Default

NERSION= "version-code"

See text

Parameters
facility-name
Specifies the name of the facility definition that you want to extract into a
binary file. You cannot use wildcard characters.
file-spec
Specifies the name of the file that DECtrace creates to store the binary form of
the facility definition. The default device and directory are your VMS default
device and directory. The default file type is EPC$DEF.

Qualifier
/VERSION=" version-code"
Specifies the version of the facility. The name of the version can be any
printable text string up to 10 characters. You cannot use wildcard characters,
and the string must be enclosed with quotation marks (" ").
This is a required qualifier.

7-30

DECtrace Commands

EXTRACT DEFINITION

Description
Use the EXTRACT DEFINITION command to copy facility definitions from
one system to another. The binary file contains the entire facility definition,
including the original creation date. This allows an exact replica of the
facility definition to be moved to a remote site and included in the remote
site's DECtrace administration database by using the INSERT DEFINITION
command.
You need VMS BYPASS, READALL, or SYSPRV privilege to extract either a
registered facility definition or the definition for a facility created by another
user.

Example
$ COLLECT EXTRACT DEFINITION MY FACILITY MY FAC031 /VERSION="V3.l"
%EPC-S-FACEXT, Facility definitfon(s) was successfully extracted

Creates a file containing the facility definition for version V3.1 of MY_
FACILITY. DECtrace uses your default device and directory and the default
file type.

DECtrace Commands 7-31

FORMAT

FORMAT
Formats one or more DECtrace data files into one formatted data file or
database.

Format
FORMAT

data-file[, ... ] [formatted-file-or-database]

Command Qualifiers

Defaults

/[NO]CDDPLUS_DEFINITIONS=pathname
/[NO]FILELIST
/[NO]MERGE
/RDBVMS_OPTIMIZATION=(param=value[, ... ])
!TYPE=output-type

/NOCDDPLUS_DEFINITIONS
/NOFILELIST
/NOMERGE
See text
!TYPE=RDBVMS

Parameters
data-file

Must be either of the following:
• The name of a data capture file produced by data collection. You can also
specify data capture files from more than one collection, provided all the
collections reference the same facility selection.
• The name of a file that contains a list of data collection file names produced
by one or more collections. (See the description of the /FILELIST qualifier.)
If the data collection files contain data from collections that are associated

with different facility selections, DECtrace issues an error and no formatting is
done.
You cannot use any wildcard characters in the data file specifications. The
default device and directory are your default VMS device and directory. The
default file type is DAT.
formatted-file-or-database

Specifies the name of the formatted data file or database that DECtrace creates
to store the data. The default device and directory are your VMS default device
and directory. The /TYPE qualifier determines whether DECtrace creates a
VAX RMS file or an Rdb/V1v.IS database.

7-32 DECtrace Commands

FORMAT
For VAX RMS formatted files, the default file type is DAT. For RdbNMS
databases, you cannot specify a file type because RdbNMS creates both a
database and a snapshot file. If you do specify a file type and request an
RdbNMS database, DECtrace returns an error message and does not format
the file.
The formats of both the VAX RMS file and the RdbNMS database are described
in Appendix A.
Note DECtrace reports can be generated only from a formatted Rdb /VMS database.

Qualifiers
/CDDPLUS_DEFINITIONS:pathname
/NOCDDPLUS_DEFINITIONS {default)

Specifies whether to create VAX CDD/Plus record definitions for the formatted
database or data file records. If you request VAX CDD/Plus record definitions,
you must specify a pathname where the definitions will be stored in the VAX
CDD/Plus dictionary.
You can only specify the /CDDPLUS_DEFINITIONS qualifier when you are
formatting your data collection file(s) into an RdbNMS formatted database.
/FILELIST
/NOFILELIST (default)

Specifies that the first parameter to the FORMAT command is a file list,
which is a file containing a list of file specifications for the data files you want
to format. For example:
$

COLLECT FORMAT MY_LIST.TXT /FILELIST MY_DATA

Each file specification must be on a separate line within the file list. For
example, MY_LIST.TXT contains the following lines:
DISK$USER1: [SMITH.COLLECTOR]DATAl.DAT
DISK$USER2:[DATA]DATA2.DAT
DISK$USER3:[DATA]DATA3.DAT

The default file type for the file list is TXT.
/MERGE
/NOMERGE (default)

Specifies that the data in the data files should be merged with existing data
in the specified formatted output file or database. The /MERGE qualifier lets
you combine data from previous collections (that have already been formatted)

DECtrace Commands

7-33

FORMAT
with data from new collections. Only data from collections scheduled using the
same facility selection can be combined.
When you specify the !MERGE qualifier and the output file or database does
not exist, DECtrace issues an error and does not perform any formatting.
If you do not specify /MERGE, and the output file already exists, DECtrace
creates a new version of the file using the same name.
!RDBVMS_ OPTIMIZAT/ON=(param:value[, ... ])

Specifies to use optimization parameters when creating an Rdb/VMS formatted
database. Table 7-6 shows the parameters and their default. Each parameter
is described in the following section under Optimization Parameters.
Table 7-6

Rdb NMS Optimization Parameters

Optimization Parameter

Default Value

ALLOCA:TIO N

2000 database pages

BUFFER_SIZE

30 blocks

[NO]JOURNAL

.JOURNAL

MIN_EXTENT

500 pages

NUM_BUFFERS

30 buffers

[NO]STRING_OPTIMIZATION

STRING_OPTIMIZATION

[NO]VIEWS

VIEWS

ITYPE=output-type

Specifies the format of the formatted data file. Valid format types are:
RDBVMS
RMS
If you use the RDBVMS keyvrnrd, DECtrace creates an RdbNMS database
that you can use with the REPORT command to generate reports. If you use
the RMS keyword, DECtrace.creates a VAX RMS sequential file. The choice
of output types lets you select the format best suited for your purposes. With
either type, you can choose to write your own reports by interpreting the data
through user-written reporting programs or a report generator such as VAX
DATATRIEVE.

7-34 DECtrace Commands

FORMAT
RDBVM:S is the default output type. The ITYPE=RMS qualifier is provided for
users who plan to create their own reports based on the collected data. The
formats of the both the VAX RMS file and the RdbNMS database are described
in Appendix A.

Optimization Parameters
ALLOCATION:number-ot-pages

Specifies the number of database pages allocated for the data file produced
when you create an Rdb/VMS database. You may want to increase the value
of this qualifier when creating a very large RdbNMS database from your data
collection file(s). The recommended value for the ALLOCATION parameter is
based on the following formula:
number-of-pages= (4000 + size-ofDCF)/2

Where size-of-DCF is the size in blocks of all data collection files.
The default allocation is 2000 pages.
BUFFER_ SIZE:number-of-blocks

Specifies the number of blocks allocated per buffer for use in creating an
RdbNMS database. Valid buffer sizes range from 1 to 64.
The BUFFER_SIZE and NUM_BUFFERS parameters enable you to reduce the
direct I/O required during formatting operations. However, the direct I/O is
inversely proportional to the page faulting required; as you reduce the direct
I/O, you increase your process's page faulting because the I/O operations have
been transferred to the paging disk. In general, you can safely increase the
number of buffers and the buffer size only if your system has a large amount of
memory. You should experiment with different values to determine the optimal
size and number of buffers for your application.
The default buffer size is 30 blocks.
[NO]JOURNAL

Specifies whether the database should be recoverable in the event of a
formatting failure. If you specify NOJOURNAL, the database will be corrupted
if formatting of a file fails. The disadvantage of using JOURNAL, is that
formatting operations take longer to complete.

DECtrace Commands

7-35

FORMAT
Note that if you specify NOJOURNAL when formatting a group of data
collection files, and one of the files fails to format correctly, the database will
be corrupted from that point on in the formatting. In this case, the format
operation may fail completely.
The default is JOURNAL.
MIN_EXTENT:number-of-pages

Specifies the minimum number of pages used for the data file extent. You
may want to increase the value of this qualifier when creating a very large
Rdb/VMS database from your data collection file(s).
The default minimum extent is 500 pages.
NUM_BUFFERS:number-of-buffers

Specifies the number of buffers allocated for the creation of an RdbNMS
database. The number is an an unsigned integer greater than zero.
The BUFFER_SIZE and NUM_BUFFERS parameters enable you to reduce the
direct 1/0 required during formatting operations. However, the direct 1/0 is
inversely proportional to the page faulting required; as you reduce the direct
1/0, you will increase your process's page faulting because the 1/0 operations
have been transferred to the paging disk. In general, you can safely increase
the number of buffers and the buffer size only if your system has a large
amount of memory. You should experiment with different values to determine
the optimal size and number of buffers for your application.
The default number of buffers is 30.
[NO]STRING_ OPTIMIZATION

Specifies whether string storage optimization should be performed using a
segmentation storage scheme. This parameter can greatly reduce the size of
the formatted database for data oflarge ASCIC, ASCIW, and FIXED_ASCIC
types. However, it will be more difficult to write report generators for a
database using this optimization. DECtrace reporting is unaffected by the
opt:imiza ti on.
The STRING_ OPTIMIZATION parameter takes a list of the following
parameters:
• FIRST_SEGMENT_SIZE=n-bytes-the size of the first string segment
stored in the event data relation.
• SEGMENT_SIZE=n-bytes--the size of additional segments stored in the
segmented string relation.

7-36

DECtrace Commands

FORMAT
The default is STRING_OPrIMIZATION and the default values of the
optimization parameters are based on the data specified in the facility
definition.
[NO]V/EWS

Specifies whether views should be created for the event-data relations. If so,
DECtrace creates four views for each event-data relation.
For data collection files with a large number of different event types, you
can greatly increase formatting performance by specifying the NOVIEWS
parameter. Note that DECtrace reporting does not need views.
The default is VIEWS.

Description
DECtrace collects raw data from the facilities that you select. The raw
data must then be formatted into either an RdbNMS database or a VAX
RMS file in order to be used. To use DECtrace reporting, you must specify
trYPE=RDBVMS (or use the default to the /TYPE qualifier) to create an
RdbNMS database. For example, the following command creates a formatted
RdbNMS database named ALL_MY_DATA.RDB:
$

COLLECT FORMAT DUAO: [DATA]FOOl.DAT,DUAl: [DATA]F002.DAT ALL_MY_DATA

Examples
$ COLLECT FORMAT MY COLLECTION.DAT TEST DATA

Formats the data in the file MY_COLLECTION.DAT and stores the formatted
data in an RdbNMS database in your current default VMS device and
directory under the name TEST_DATA.RDB.

$ COLLECT FORMAT MY_LIST.TXT /FILELIST MY_DATA

Formats the data in the files listed in MY_LIST.TX.T and stores the formatted
data in an RdbNMS database in your current default VMS device and
directory under the name MY_DATA.RDB. MY_LIST.TXT contains a list of
data file names, one per line.

$ COLLECT FORMAT WEEK3.DAT JUNE_DATA /MERGE

Formats the data in WEEK3.DAT and merges it with the data already in the
previously formatted JUNE_DATA.RDB database.

DECtrace Commands 7-37

FORMAT
4

$ COLLECT FORMAT ONE BIG FILE.DAT ALL DATA $ /RDBVMS OPTIMIZATION=(NUM BUFFERS=40, BUFFER SIZE=50, NOVIEWS,
STRING_OPTIMIZATION=(FIRST=32,SEGMENT=64), ALLOCATION=lOOOO)

Formats the data in ONE_BIG_FILE.DAT and stores the formatted data in
an RdbNMS database named ALL_DATA.RDB. Because the file is very large,
the normal formatting parameters are increased to provide more optimal
performance.

7-38

DECtrace Commands

HELP

HELP
Displays information about DECtrace and DECtrace commands.

Format
HELP

[topic] ...

Parameter
topic
Specifies the subject about which you want information from the HELP library.
You can specify the names of one main topic and up to eight subtopics with the
HELP command.

Example
DECtrace> HELP CREATE
CREATE
Creates a facility definition or a facility selection.
Additional information available:
DEFINITION

SELECTION

CREATE Subtopic?

Invokes DECtrace HELP to display information about the CREATE
DEFINITION and CREATE SELECTION commands and prompts for further
information.

DECtrace Commands

7-39

INSERT DEFINITION

INSERT DEFINITION
Inserts a facility definition in a binary format (previously created by the
EXTRACT DEFINITION command) into the DECtrace administration
database.

Format
INSERT DEFINITION

file-spec

Command Qualifiers

Defaults

/[NO)LIBRARY
/[NO) REPLACE

/NOLIBRARY
/NORE PLACE

Parameter
file-spec
Specifies the name of the binary file that contains the facility definition. The
default device and directory are your VMS default device and directory. The
default file type is EPC$DEF.

Qualifiers
/LIBRARY
/NOLIBRARY {default)

Inserts the facility definition into the DECtrace facility library
(EPC$FACILITY.TLB) located in SYS$COMMON:[SYSLIBJ. This text library
is referenced during reinstallations of DECtrace. If you are going to remove
DECtrace from your system but wish to retain all of your facility definitions,
you need to extract the definitions from the DECtrace administration database
(with the EXTRACT DEFINITION command) and re-insert them into the
DECtrace facility library.
/REPLACE
/NOREPLACE {default)

Specifies that the facility definition replaces any previously existing facility
definition with the same facility name and version code. If a facility definition
exists and you attempt to insert a matching facility and version without using
the /REPLACE qualifier, DECtrace issues a warning and does not store the
new definition.

7-40

DECtrace Commands

INSERT DEFINITION
If no facility definition with the same name and version code exists, the
/REPLACE qualifier is ignored.

Description
The EXTRACT DEFINITION and INSERT DEFINITION commands allow you
to replicate facility definitions on multiple systems. This is useful when you
want to test an application in several different environments.
You need VMS SYSPRV or BYPASS privilege to replace either a registered
facility definition or the definition for a facility created by another user.

Examples
$ COLLECT INSERT DEFINITION MY_FAC031 /REPLACE

Inserts the facility definition in the binary file MY_FAC031.EPC$DEF into the
DECtrace administration database.

$ COLLECT INSERT DEFINITION NEW_TOOL /LIBRARY

Inserts the facility definition in the binary file NEW_TOOL.EPC$DEF into the
DECtrace administration database and the DECtrace facility library.

DECtrace Commands

7-41

REPORT

REPORT
Generates a report based on formatted data from one or more collections.

Format
REPORT

formatted-database

Command Qualifiers

Defaults

/BEFORE="time"
/EVENTS=( event-name[, ... ])
/FACILITY=(facility-name[, ... ])
/INTERVAL=ti me-unit
/LENGTH=number-of-lines
/[NO)OPTIONS=file-spec
/OUTPUT=file-spec
/SINCE="time"
/STATISTICS=(stat-type[, ... ])
/TITLE="text-string"
/TYPE=report-type
/WIDTH=number-of-columns

All data in file
/EVENTS=*
/FACILITY=*
/INTERVAL=MINUTES
/LENGTH=60
/NOOPTIONS
/OUTPUT=SYS$0UTPUT
All data in file
/STATISTICS=COUNT
fflTLE=""
/TYPE=SUMMARY
/WIDTH=80

Parameter
formatted-database

Specifies the name of a formatted database created with the FORMAT
command. If the specified parameter is not an RdbNMS database, DECtrace
issues an error message and generates a 0-block output file.
This is a required parameter.

Qualifiers
/BEFORE=" dd-mmm-yyyy hh:mm:SS"

Specifies that DECtrace reports on all data collected at or before the indicated
time. By default, DECtrace reports on all data in the formatted database.
If you use the /BEFORE qualifier, you must specify the time as an absolute

date and time using a quoted string. You cannot use a VMS delta time.

7-42 DECtrace Commands

REPORT
IEVENTS=(event-name[, ... ])

Specifies one or more events to report on. By default, DECtrace reports on the
data collected for all facilities and events contained in the formatted database.
You can use the /EVENTS qualifier to restrict the report to specific events.
If you specify the /EVENTS qualifier, you must list the facilities you want with

the /FACILITY qualifier. You cannot use the default /FACILITY=* if you use
the /EVENTS qualifier. An error occurs if you specify a facility which does not
contain the specified event(s).
The /EVENTS and /OPTIONS qualifiers are mutually exclusive.
IFACILITY:{facility-name[, ... ])

Specifies one or more facilities to report on. By default, DECtrace reports
on the data collected for all facilities and events contained in the formatted
database. You can use the /FACILITY qualifier to restrict the report to specific
facilities.
If you specify the /FACILITY qualifier, you do not have to use the /EVENTS
qualifier. If you do, the effects are cumulative: for example, if you specify two

facilities and one event, DECtrace reports on that event for both facilities,
provided both facilities contain the event. Note that an error occurs if you
specify a facility which does not contain the specified event(s).
The /FACILITY and /OPTIONS qualifiers are mutually exclusive.
/INTERVAL=time-unit

Specifies the time interval for FREQUENCY reports. FREQUENCY reports
calculate the number of occurrences of an event or events at given time
intervals during data collection. The /INTERVAL qualifier specifies the time
interval at which event occurrences are calculated. The time interval must be
one second, one minute, or one hour, specified as one of the following keywords:
SECONDS
MINUTES
HOURS
The default interval is one minute.
The /INTERVAL qualifier is valid for FREQUENCY reports only. DECtrace
ignores the qualifier for other types of reports. Use the /TYPE qualifier to
specify a FREQUENCY report.

DECtrace Commands

7-43

REPORT
ILENGTH=number-ot-lines

Specifies the length of each page of the report in number of lines. The default
length is 60 lines.
/OPTJONS[=file-spec]
/NOOPTIONS (default)

Specifies an option file that describes the contents and format of the report.
The default file type for the options file is OPT.
If you supply a VMS file specification with the /OPTIONS qualifier, DECtrace

uses that file as a source for the report characteristics. If you enter /OPTIONS
without a file specification, DECtrace prompts you for the options. See
Section 4.8 for a description of the report characteristics that you can specify
in an options file.
The /EVENTS and /OPTIONS qualifiers are mutually exclusive.
/OUTPUT=file-spec

Specifies the destination for the report. By default, DECtrace displays the
report on the SYS$0UTPUT device (usually, your terminal). The /OUTPUT
qualifier can redirect the output to a file or another device.
!SINCE=" dd-mmm-yyyy hh:mm:SS"

Specifies that DECtrace reports on all data collected at or after the specified
time. By default, DECtrace reports on all the collected data in the formatted
database.
If you use the /SINCE qualifier, you must specify the time as an absolute date

and time using a quoted string. You cannot use a VMS delta time.
/STATISTICS:(stat-type[1 • • • ])

Specifies the statistics to include for each data item in a SUMMARY report.
Valid statistics are:
ALL
COUNT (default)
MAXIMUM
MEAN
MINIMUM
STANDARD_DEVIATION
TOTAL
95_PERCENTILE

7-44

DECtrace Commands

REPORT
The /STATISTICS qualifier is valid for SUMMARY reports only. DECtrace
ignores the qualifier for DETAIL and FREQUENCY reports.
fflTLE=" text-string"

Specifies the title of the report. The title is displayed at the top of each page of
the report. The title is a text string that can contain any printable characters.
The string must be enclosed with quotation marks ( " " ).
ffYPE=report-type

Specifies the type of report to create. The valid report types are:
DETAIL
FREQUENCY
SUMMARY
The default report type is SUMMARY. See Section 4.4 for a detailed description
of each report.
/WIDTH:number-of-columns

Specifies the width of each page of the report in number of characters. Valid
widths are 80 and 132. If you specify a value other than 80 or 132, or if you do
not specify a width, DECtrace uses 80 characters.

Description
In the simplest case, the REPORT command creates a summary report,
displayed to SYS$0UTPUT, on all of the data in the formatted database. For
example, the following command generates a report based on the data in the
formatted database MY_TEST.RDB:
$

COLLECT REPORT MY_TEST.RDB

You can further refine the report with the /FACILITY and /EVENTS qualifiers.
For example, the following command reports on only the ACMS PROCEDURE_
CALL events:
$

COLLECT REPORT MY TEST /FACILITY=ACMS /EVENT=PROCEDURE_CALL

The /BEFORE, /INTERVAL, /SINCE, and /STATISTICS qualifiers provide
additional customizing features that you may want to use.

DECtrace Commands

7-45

REPORT
You can specify all of the characteristics of the report using the REPORT
qualifiers listed in the previous paragraph. However, the qualifiers are global;
that is, the statistics that you request with the /STATISTICS qualifier apply to
all of the events that you ask to be included in the report. You can override the
qualifiers for each event. If you want to define separate characteristics for each
event, you can use the /OPTIONS qualifier.
See Section 4.8 for an example of the report characteristics that you can
specify in the report options file. Also, following the REPORT command in this
reference section are descriptions of the report options EVENT, ITEM, and
RESTRICTION.

Examples
$ COLLECT REPORT MY_REPORT /OUTPUT=MY_REPORT.TXT

Creates a summary report on all of the data in the formatted file MY_
REPORT.RDB and stores the report in the file MY_REPORT.TXT.

$ COLLECT REPORT MY REPORT /OUTPUT=MY REPORT.TXT -

_$ /FACILITY=ACMS /EVENT=TASK /STATISTICS=(MINIMUM,MAXIMUM,MEAN)

Creates a summary report of ACMS task data stored in the formatted database
MY_REPORT.RDB. The report lists the minimum, maximum, and mean values
of task data items. DECtrace stores the report in the file MY_REPORT.TX.T.
3

$ COLLECT REPORT MY REPORT /OUTPUT=MY REPORT.TXT /OPTIONS
Option> EVENT TASK /FACILITY=ACMS /STATISTICS=MAXIMUM Option> /GROUP BY=TASK NAME
Option> IClRL/ZI -

Creates a summary report of ACMS task data from the formatted database
MY_REPORT.RDB. The report lists the maximum number of occurrences of
the TASK event, grouped by task name. DECtrace stores the report in the file
MY_REPORT.TX.T.

7-46 DECtrace Commands

REPORT Options-EVENT

REPORT Options-EVENT
Defines the characteristics of a report on a specific event. You specify this
command using the /OPTIONS qualifier to the REPORT command.

Format
EVENT

event-name

Command Qualifiers

Defaults

/BEFORE=time
/FACILITY =facility-name
/GROUP_BY=(item-name[, ... ])
/INTERVAL=time
/[NO]ITEMS=(item-name[, ... ])
/SINCE=time
/STATISTICS=(stat-type[, ... ])
/[NO]SUBTITLE= "text-string"
ITYPE=report-type

All data in file
None
See text
See text
/ITEMS=*
All data in file
See text
/NOSUBTITLE
See text

Parameter
event-name

Specifies the name of an event to report on.

Qualifiers
/BEFORE=" dd-mmm-yyyy hh:mm:SS"

Specifies that DECtrace reports on all data collected at or before to the
indicated time. By default, DECtrace reports on all data in the formatted
database for this event.
If you use the /BEFORE qualifier, you must specify the time as an absolute

date and time using a quoted string. You cannot use VMS delta time.
/FACILITY=facility-name

Specifies the name of the facility that contains the event.

DECtrace Commands

7-47

REPORT Options-EVENT

/GROUP_BY:(item-name[, ... ])

Specifies the item or items by which to group event occurrences. In SUMMARY
and FREQUENCY reports, the report statistics are divided into groups based
on equivalent values of the specified items. The final group displays grand
total statistics for the entire report.
In DETAIL reports, event occurrences are listed in ascending order based on
the item values. If the event is a duration event, the end value of the item is
used, providing the item was collected on the end event. Otherwise, the start
value is used.
For segmented ASCII strings, the /GROUP_BY qualifier is based on the first
segment in the event relation. If two items are not equal, but the difference
does not occur until after the first segment, the report considers them equal.
/INTERVAL=time-unit

Specifies the time interval for FREQUENCY reports. FREQUENCY reports
calculate the nwnber of occurrences of an event or events at given time
intervals during data collection. The /INTERVAL qualifier specifies the time
interval at which event occurrences are calculated. The time interval must be
one second, one minute, or one hour specified as one of the following keywords:
SECONDS
MINUTES
HOURS
If an /INTERVAL qualifier is specified on the REPORT command line, the

Specifies the item or items on which to report. The /ITEMS qualifier is valid
for DETAIL and SUMMARY reports only. It is ignored for FREQUENCY
reports.
If you specify /NO ITEMS and /GROUP_BY on a DETAIL report, DECtrace
ignores the /GROUP_BY qualifier. The resulting report contains only the
report header information.

7-48

DECtrace Commands

REPORT Options-EVENT
If you specify /NOITEMS on a SUMMARY report, DECtrace uses
/STATISTICS=COUNT and ignores any other statistic that you specify in
the command.
/SINCE=" dd-mmm-yyyy hh:mm:SS"

and time using a quoted string. You cannot use a VMS delta time.
/STATISTICS:(stat-type[, ... J)

command line qualifier specifies the default statistics. The /STATISTICS
qualifier on an EVENT option overrides the default statistics for this event
only.
The /STATISTICS qualifier is valid for SUMMARY reports only. DECtrace
ignores the qualifier for DETAIL· and FREQUENCY reports.
/SUBTITLE=" text-string"
/NOSUBTITLE (default)

DECtrace Commands

7-49

REPORT Options-EVENT

!TYPE=report-type
Specifies the type of report to create. The valid report types are:
DETAIL
FREQUENCY
SUMMARY
If you specify the /TYPE qualifier on the REPORT command line, the command
line qualifier specifies the default report type. The /TYPE qualifier on an
.EVENT option overrides the default report type for this event only.

The default report type is SUMMARY.

Description
Specify options either in an options file or at the Option> prompt. In either
case, you must use the /OPTIONS qualifier to the REPORT command to specify
options. Specify each option on a separate line. You can specify each option
more than once.

7-50

DECtrace Commands

REPORT Options-ITEM

REPORT Options-ITEM
Defines the display characteristics of items in the report. You specify this
command using the /OPTIONS qualifier to the REPORT command.
Display characteristics include:
• Report heading
• Display width
The default display characteristics of data items are defined in the
facility definition. The ITEM report option allows you to customize these
characteristics for an item pertaining to the preceding EVENT report option.
The characteristics defined in an ITEM option remain in effect only for a single
EVENT report option.

Format
ITEM

item-name

Command Qualifiers

Defaults

/REPORT_HEADER=text
NJI DTH=number-of-colum ns

See text
See text

Parameter
item-name

The name of the item for which to define the characteristics.

Qualifiers
/REPORT_HEADER=text

Specifies the text to display as a heading in the report when listing data for
the specified item.
The facility definition specifies the default report heading.
IWIDTH=number-ot-columns

Specifies the number of columns to reserve for displaying data for the specified
item.
The facility definition specifies the default width.

DECtrace Commands 7-51

REPORT Options-RESTRICTION

Collection names

• Image names
• Item values
• Node names
• Process IDs (EPID)

Format
RESTRICTION

COLLECTION collection-name [, ... ]
EPID process-ID [, ... ]
IMAGE image-name [, ... ]
ITEM item-name item-value
NODE node-name[, ... ]

Parameters
collection-name
The name of one or more collections to use to select data for reporting. Only
data collected during the specified collections is reported.
Image-name
The name of the executable image which registered with the DECtrace
Registrar process. Only data collected from processes running the specified
image(s) is reported.
The image name that you specify is used as a wildcard in searching through
the formatted database for the desired images. The effect is that the restriction
is done on *image-name*.
Item-name
The name of an item to use to select data for reporting.

7-52 DECtrace Commands

REPORT Options-RESTRICTION
Item-value
The value of the item to use to select data. Only records that match the item
name and value are reported.
node-name
The name of one or more network nodes to use to select data for reporting.
Only data collected on the specified nodes is reported.
process-ID
The EPIDs of one or more processes to use to select data for reporting. Only
data collected from the specified processes is reported.

DECtrace Commands 7-53

SCHEDULE COLLECTION

SCHEDULE COLLECTION
Schedules data collection to occur on the cluster or local node.

Format
SCHEDULE COLLECTION

collection-name data-collection-file[, ... ]

Command Qualifiers

Defaults

/BEGINNING=time
/[NO]CLUSTER
/DURATION=time
/ENDING=time
/[NO]FILELIST
/PROTECTION=(ownership:access[, ... ])
/REGISTRATION_ID=(registration-id[, ... ])
/SELECTION=selection-name

/BEGINNING=current-time
/CLUSTER
See text
See text
/NOFILELIST
See text
/REGISTRATION_ID=*
See text

Parameters
collection-name
The name of the collection you are scheduling. The collection name must be a
unique 1- to 32-character string consisting of alphanumeric characters, dollar
signs ( $ ), and underscores ( _ ). The collection name must be unique for the
local system or for the entire cluster in a cluster environment.
data-collection-file
The name of the file or files to create for storing the collected data.

The file specification can consist of a device, directory, file name, and file type.
The device and directory default to your current VMS default device and
directory.
DECtrace creates the data collection file(s) when the collection is scheduled,
not when data collection actually begins. The default protection on the data
collection file is your default protection. You can set the protection on the file
using the /PROTECTION qualifier. For example, by removing world write
access and specifying group write access, you can restrict data collection to
only those processes that are in your UIC group.

7-54

DECtrace Commands

SCHEDULE COLLECTION
You can specify more than one data file to spread the output over multiple
disks and avoid I/O bottlenecks during collection. See the FORMAT command
for instructions on combining these multiple data files afterwards.

Qualifiers
/BEGINNING=time

Specifies when data collection starts. You can specify the starting time using
either a VMS absolute or delta time format, including both date and time.
By default, data collection starts immediately. If you specify a relative date
and time, the starting time is determined by the relative offset from the
current time. For example, if you ask for "+1:" at 10:00, the test begins at
11:00.
The starting time for data collection must be in the future. If you specify a
starting time that has already passed, DECtrace issues an error message and
does not schedule data collection.
/CLUSTER (default)
/NOCLUSTER

Specifies whether data collection occurs only on the local node or on all nodes
of the cluster.
By default, SCHEDULE COLLECTION schedules data collection cluster-wide
(that is, data collection occurs on every node in the cluster). You use the
/NOCLUSTER qualifier to schedule data collection on only the current node.
On a standalone system, the /CLUSTER qualifier is ignored.
/DURAT/ON=time

Specifies the length of time over which data collection occurs. You must specify
the duration as a VMS delta time.
The /DURATION and /ENDING qualifiers are mutually exclusive.
/ENDING=fime

Specifies when data collection ends. You can specify the ending time using
either a relative or absolute VMS time format, including both date and time.
You must specify an ending time or use the /DURATION qualifier. If you do
not include the /ENDING or /DURATION qualifiers, DECtrace issues an error
message and does not schedule data collection.

DECtrace Commands

7-55

SCHEDULE COLLECTION
If you specify a relative date and time, the ending time is determined by the

relative offset from the current time, not the starting time.
If the ending time is earlier than the starting time, DECtrace issues an error

message and does not schedule data collection.
IFILELIST
/NOFILELIST (default)
Specifies that the second parameter to the SCHEDULE COLLECTION
command is a file list, which is a file containing a list of file specifications to
.use as output data files for data collection. One advantage of using a file list
is that you can specify multiple data files without worrying about the DCL
limitations on the length of a command line.

The /FILELIST qualifier is position-dependent; you must specify it on the
second parameter to the command. For example:
$

COLLECT SCHEDULE COLLECTION MY_TEST DATA_FILE.TXT /FILELIST

Each file specification must be on a separate line within the file list. For
example:
DISK$USER1: [SMITH.COLLECTOR]DATAl.DAT
DISK$USER2: [DATA]DATA2.DAT
DISK$USER3: [DATA]DATA3.DAT

The default file type for the file list is TXT.
/PROTECTION=(ownershlp:access[, ••• ])
Specifies the protection on the data collection file(s). A process must have write
access to a file in order to record event data in the file.

Valid ownership categories are (S)ystem, (O)wner, (G)roup, and (W)orld.
A valid access code is any combination of the following: (R)ead, (W)rite,
(E)xecute, and (D)elete.
If you do not specify a value for each ownership category, or if you omit the
/PROTECTION qualifier, DECtrace applies the current default protection for
each unspecified category. If the data collection file replaces a previous version,
the protection scheme of the old file is used on the new one.

/REGISTRATION_ID=(reglstration-id[, ••• ])
Identifies facility- and process-specific registration IDs to limit the number
of processes collecting data. By default, no restrictions are placed on data
collection.

7-56

DECtrace Commands

SCHEDULE COLLECTION
When an image instrumented with DECtrace activates, several process-specific
registration IDs are registered automatically. By specifying the appropriate
combinations of the process ID (EPID), process name, image name, and user
name, you can collect data on a per-process, per-image, or per-user basis.
Use the SHOW REGISTER command to display the registration information
associated with a process.
A facility can pass a facility-specific registration ID on its EPC$INIT call. This
allows you to specify a subset of the processes using a facility. For example,
the ACMS facility can restrict the processes collecting data to those that use
specific applications. In this case, the registration ID is the application name.
Note that not all facilities choose to provide a registration ID.
If you specify a registration ID, it must be exactly as it appears in the SHOW

REGISTER display. You cannot use abbreviations or default values.
See Section 3.1.2 for more information about registration IDs.
/SELECTION=selection-name

Specifies the facility selection to use for the collection. The facility selection
lists the facilities for which data will be collected and specifies a collection class
for each.
This is a required qualifier.

Description
You can schedule data collection cluster-wide or on a subset of the nodes in a
VAX.cluster. To schedule data collection on a subset of a cluster, you must log
in to each node on which you want to schedule the collection and start local
data collection on each of those nodes.
Only one collection can be active on a particular node at any time. You can
schedule many different collections on your local system or cluster, but the
collections cannot have overlapping time intervals. However, you can schedule
overlapping collections on different subsets of your cluster. For example, you
could schedule a collection on two nodes and have a different collection active
on the remaining nodes in the cluster at the same time.

DECtrace Commands

7-57

SCHEDULE COLLECTION
The situations that result in an error are:
•

If the ending time is earlier than the starting time

•

If the starting date and time are in the past

•

If another collection is active or is scheduled to become active on that node
during the same time interval

See Section 3.2 for more information on scheduling data collection.

Examples
1

$ COLLECT SCHEDULE COLLECTION MY TEST MY DATA.DAT $ /SELECTION=ACMS DATA -

-$ /BEGIN=ll:OO /END=12:00 -$ /NOCLUSTER
%EPC-S-SCHED, Data collection MY_TEST is scheduled

Schedules the collection MY_TEST to run on the local node and to begin at
11:00 and end at 12:00 on the current day. DECtrace stores the collected data
in the file MY_DATA.DAT in your default device and directory and uses your
default protection scheme.

$ COLLECT SCHEDULE COLLECTION WEDNESDAYS TEST WEDNESDAY DATA.DAT $ /SELECTION=RDB AND ACMS -$ /BEGINNING="+l-:-" /DURATION="2:" -$ /PROTECTION=(W:W) /CLUSTER
%EPC-S-SCHED, Data collection WEDNESDAYS_TEST is scheduled

Schedules a cluster-wide collection to begin at the current time on the following
day. The name of the collection is WEDNESDAYS_TEST. It collects the data
described by the RDB_AND_ACMS facility selection. Data is collected for two
hours and is stored in the file WEDNESDAY_DATA.DAT.
3

$ COLLECT SCHEDULE COLLECTION ALL DAY LOTSOFDATA.DAT $ /SELECTION=JUST RDB -$ /DURATION="2:"-::-$ /CLUSTER -$ /PROTECTION=(G:W) /REGISTRATION_ID=(DISKl: [PAYROLL.IMAGES]WEEKLY_CHECKS.EXE)

Schedule data collection to begin immediately and run for two hours. The
collection runs on the entire cluster and collects RdbNMS event data from the
WEEKLY_CHECKS program.

7-58 DEctrace Commands

SET HISTORY

SET HISTORY
Temporarily changes the history database that DECtrace uses for the SHOW
HISTORY command, or creates a new history database.

Format
SET HISTORY

[history-file]

Command Qualifier

Default

/[NO]NEW_FILE

/NONEW_FILE,

Parameter
history-file

Specifies the history database to use when displaying history information with
the SHOW HISTORY command. The SET HISTORY command remains in
effect for the life of the user's process or until another SET HISTORY command
is issued. The default file type is RDB.
If you do not specify the /NEW_FILE qualifier, then the history-file is a

required parameter.

Qualifier
/NEW_FILE
/NONEW_FILE (default)

Specifies that a new history database will be created. The /NEW_FILE
qualifier does not accept a file specification. DECtrace creates the new history
file with the logical name EPC$HISTORY_DB and the next higher version
number.
Use of the /NEW_FILE qualifier requires VMS OPER privilege.

Description
The SET HISTORY command perlorms two separate functions:
• Setting an alternate history file for SHOW IDSTORY commands
•

Creating a new history file for recording DECtrace messages

DECtrace Commands

7-59

SET Hl'STORY
If you specify the history-file parameter, DECtrace points all SHOW HISTORY

commands to the specified file. This command is useful for examining the
information in an old history file. Note that the scope of this command is
limited to within the DECtrace> prompt context for this process. If you exit
from the DECtrace command environment and then re-enter it, all subsequent
SHOW IDSTORY commands will reference the current, active history file.
If you specify the /NEW_FILE qualifier, DECtrace creates a new history file

and writes any new messages to the new file. A slight lapse between the time
you issue the SET HISTORY command and the time DECtrace starts writing
to the new file should not exceed 30 seconds. In the meantime, history records
continue to be written to the old file.
If you specify both a history file name and the /NEW_FILE qualifier, DECtrace

issues an error message and does not perform either function.

Examples
$ COLLECT
DECtrace> SET HISTORY OLD HISTORY
DECtrace> SHOW HISTORY

Temporarily changes the history file for SHOW IDSTORY commands to the file
OLD_HISTORY.RDB so that you can display information from an old history
database.
2

$ COLLECT SET HISTORY /NEW_FILE

Creates a new history file with the same file name as referred to by the logical
name EPC$HISTORY_DB and a version number one higher than the current
file.

7-60 DECtrace Commands

SHOW COLLECTION

SHOW COLLECTION
Displays information about active or pending data collection on your system.

Format
SHOW COLLECTION

[collection-name]

Command Qualifiers

Defaults

/[NO]CLUSTER
/FORMAT=type
/OUTPUT=file-spec
/SELECTION=selection-name

/CLUSTER
/FORMAT=BRIEF
/OUTPUT=SYS$0UTPUT
/SELECTION=*

Parameter
collection-name

Specifies the name of the data collection for which to display information. You
can omit the collection name or use an asterisk (*)as a wildcard character to
display information about all collections.
If you specify both a facility selection (with the /SELECTION qualifier) and
a collection, DECtrace uses the collection name first. If the data collection

does not use the specified selection, DECtrace executes the command using the
collection name but also issues a warning message.

Qualifiers
!CLUSTER {default)
/NOCLUSTER

Specifies whether to display information about data collection scheduled only
on the local node, or about data collection scheduled on any node in the cluster.
By default, SHOW COLLECTION displays information about data collection
scheduled on any node in the cluster.
On a standalone system, the /CLUSTER qualifier is ignored.

DECtrace Commands

7-61

SHOW COLLECTION
/FORMAT:type

Specifies the amount of information to display. Valid types are:
BRIEF
FULL
The default format is BRIEF, which displays the collection name, facility
selection name, and starting and stopping times for data collection. If you
specify /FORMAT=FULL, DECtrace displays a complete description of the data
collection.
/OUTPUT:file-spec

Specifies the destination for the display. By default, DECtrace displays the
information on the current SYS$0UTPUT device (usually, your terminal). The
/OUTPUT qualifier can redirect the output to a file or another device.
/SELECTION:selection-name

Specifies the name of a facility selection for which you want to see schedule
information. If you use an asterisk ( * ) as a wildcard character, or if you omit
both the collection name and the /SELECTION qualifier, DECtrace displays
information about all data collection currently running or scheduled for the
system or VAXcluster.

Description
See Section 3.5.1 for a full description of the information in the SHOW
COLLECTION displays.

Examples
1

$ COLLECT SHOW COLLECTION /SELECTION=ACMS_DATA /NOCLUSTER

Displays information about any data collection running or scheduled to run on
the local node that uses the facility selection ACMS_DATA.

$ COLLECT SHOW COLLECTION WEDNESDAYS_TEST

Displays information about the data collection WEDNESDAYS_TEST.

7-62 DECtrace Commands

SHOW DEFINITION

SHOW DEFINITION
Displays information about one or more facility definitions registered in the
DECtrace administration database.

Format
SHOW DEFINITION

[facility-name]

Command Qualifiers

Defaults

/FORMAT=type
/OUTPUT=file-spec
NERSION= "version-code"

/FORMAT=NAMES_ONLY
/OUTPUT=SYS$0UTPUT
/VERSION=*

Parameter
facility-name
Specifies the name of the facility definition you want information about. You
can use an asterisk ( *) as a wildcard character to display information about
all of the facilities defined on the system.

If you do not specify a facility name, DECtrace displays information on all the
currently defined facilities.

Qualifiers
IFORMAT:type
Specifies the amount of information to display. Valid types are:

FULL
NAMES_ONLY
The default format type is NAMES_ONLY.
/OUTPUT:file-spec
Specifies the destination for the display. By default, DECtrace displays the
information on the current SYS$0UTPUT device (usually, your terminal). The
/OUTPUT qualifier can redirect the output to a file or another device.
NERSION=" version-code"
Specifies the version of the facility that you want information about. You must
enclose the text string with quotation marks ( " " ).

DECtrace Commands 7-63

If you do not specify a version code or if you use an asterisk ( * ) as a wildcard
character, DECtrace displays information about all versions of the facility that
you name.

Description
See Section 6.4 for a description of each type of SHOW DEFINITION display.

Examples
$ COLLECT SHOW DEFINITION /FORMAT=NAMES_ONLY
23-DEC-1989 11:42
Facility Definition Information
Page 1
Names Only Report
DECtrace Vl.O

Facility:

Version:

Creation Date:

Class:

ATM SAMPLE
MY FACILITY

Vl.O
V4.2

25-AUG-1989 14:17
23-0CT-1989 17:09

ALL
ALL

(D)
(D)

Displays the names, versions, creation dates, and collection classes for all of
the facility definitions on the system.

$ COLLECT SHOW DEFINITION MY_FACILITY /VERSION="V4.2" /FORMAT=FULL
23-Dec-1989 11:43
Facility Definition Information
Page 1
Full Report
DECtrace Vl.O

Facility:
Number:
Version:
Creation date:
Created by:

MY FACILITY
2048
V4.2
13-0ct-1989 17:09
SMITH

Events:

Items:

Displays complete information about the MY_FACILITY Version V4.2 facility
definition.

7-64

DECtrace Commands

SHOW HISTORY

SHOW HISTORY
Displays information about the DECtrace system, including:
• When the system started and stopped
• When collections started, stopped, or were canceled
• When processes registered and unregistered
• Any errors that occurred in the DECtrace registration and collecting
processes

Format
SHOW HISTORY

[collection-name]

Command Qualifiers

Defaults

/BEFORE=time
/[NO]CHRONOLOGICAL
/[NO]CLUSTER
/FORMAT=type
/NODE=" node-name"
/OUTPUT=file-spec
/SINCE=time

All data in file
/NOCHRONOLOGICAL
/CLUSTER
/FORMAT=ERROR
/NODE=*
/OUTPUT=SYS$0UTPUT
All data in file

Parameter
collection-name
The name of the collection for which to display information. By default,
DECtrace displays the history for all collections. You can display information
for a single collection by specifying a collection name on the command line.
You cannot use wildcard characters.

Qualifiers
IBEFORE:time

Specifies that only information before a specific date and time be displayed. By
default, DECtrace displays all information in the history file.

DECtrace Commands 7-65

SHOW HISTORY
!CHRONOLOGICAL
/NOCHRONOLOGICAL (default)

Specifies for history messages to be displayed in chronological order with
headers displayed for each message. This qualifier is used primarily for
debugging purposes in a cluster environment.
/CLUSTER {default)
/NOCLUSTER

Specifies whether DECtrace displays information on the current node only or
on all nodes in the VA.Xcluster.
By default, SHOW HISTORY displays cluster-wide information.
On a standalone system, the /CLUSTER qualifier is ignored.
/FORMAT:type

Specifies the type of messages that should be displayed. By default, SHOW
HISTORY displays only the error messages. The valid types are:
ALL
INFORMATIONAL
ERROR (default)
/NODE=" node-name"

Selects only those messages from the specified node. By default, DECtrace
displays history messages from all nodes in the VAXcluster.
/OUTPUT:file-spec

Specifies that only information after a specific date and time be displayed. By
default, DECtrace displays all of the information in the history file.

Description
The SHOW HISTORY command can be used in conjunction with the SET
HISTORY command to display information from older history databases.
See Section 3.5.2 for a description of the information in the SHOW HISTORY
displays.

7-66

DECtrace Commands

SHOW HISTORY

Examples
$ COLLECT SHOW HISTORY

Displays the errors which have occurred for the DECtrace system on the local
VAXcluster (in a cluster environment).

$ COLLECT SHOW HISTORY /FORMAT=INFORMATIONAL /OUTPUT=HISTORY.LOG

Writes a description of all informational messages and events to the file
HISTORY.LOG.

$ COLLECT
DECtrace> SET HISTORY OLD HISTORY
DECtrace> SHOW HISTORY

Temporarily changes the history file for SHOW HISTORY commands to the file
OLD_HISTORY.RDB so that you can display information from an old history
database.

$ COLLECT SHOW HISTORY /NODE=MYVAX2 /FORMAT=ALL

Displays all of the errors and messages for node MYVAX2.

DECtrace Commands

7-67

SHOW REGISTER

SHOW REGISTER
Displays information about processes currently registered with the DECtrace
administration database, the facilities and registration IDs for the processes,
and whether the processes are currently collecting data.

Format
SHOW REGISTER

Command Qualifiers

Defaults

/(NO]CLUSTER
/OUTPUT=file-spec

/CLUSTER
/OUTPUT=SYS$0UTPUT

Qualifiers
/CLUSTER
/NOCLUSTER (default)

Specifies whether DECtrace displays information on the processes on the local
node only or on all nodes in the VAX.cluster.
On a standalone system, the /CLUSTER qualifier is ignored.
/OUTPUT=file-spec

Description
See Section 3.1.2 for a description of the information in the SHOW REGISTER
display.

Example
$ COLLECT SHOW REGISTER

Displays the names and process IDs of processes registered with the DECtrace
administration database.

7-68 DECtrace Commands

SHOW SELECTION

SHOW SELECTION
Displays information about one or more facility selections stored in the
DECtrace administration database on the current system or VAXcluster.

Format
SHOW SELECTION

[selection-name]

Command Qualifiers

Defaults

/FORMAT=type
/OUTPUT=file-spec

/FORMAT=BRIEF
/OUTPUT=SYS$0UTPUT

Parameter
selection-name

The name of the facility selection for which you want information. You can use
an asterisk (*)as a wildcard character to display information about all facility
selections defined on the system.
If you do not specify a selection name, DECtrace displays information on all of
the facility selections defined on the system.

Qualifiers
/FORMAT:type

Specifies the amount of information to display. Valid types are:
BRIEF
FULL
NAMES_ ONLY
The default format is BRIEF.
/OUTPUT=file-spec

DECtrace Commands

7-69

SHOW SELECTION

Description
See Section 2.4 for a full description of the information in the SHOW
SELE CTI ON displays.

Examples
$ COLLECT SHOW SELECTION /FORMAT=NAMES_ONLY

Displays the names of all facility selections on the system.

$ COLLECT SHOW SELECTION ACMS DATA /FORMAT=FULL _$ /OUTPUT=ACMS_DATA_FULL.LIST

Writes a complete description of the ACMS_DATA facility selection to the file
ACMS_DATA_FULL.LIST.

7-70 DECtrace Commands

SHOW VERSION

SHOW VERSION
Displays the version number of DECtrace running on your system.

Format
SHOW VERSION

Example
DECtrace> SHOW VERSION
DECtrace Version Vl.0-0
DE Ctr ace>

Displays the version number of DECtrace installed on the system~in this
case, version Vl.O.

DECtrace Commands

7-71

SPAWN

SPAWN
Creates a subprocess of the current process. Allows you to temporarily
exit from the DECtrace command environment without detaching from the
DECtrace administration database.

Format
SPAWN

[command)

Command Qualifiers

Defaults

/[NO)CARRIAGE_CONTROL
/[NO]CLI
/INPUT=file-spec
/[NO] KEYPAD
/[NO]LOGICAL_NAMES
/[NO]NOTI FY
/OUTPUT=file-spec
/PROCESS=subprocess-name
/[NO) PROM PT[=string)
/[NO]SYMBOLS
/[NO]WAIT

See text
See text
See text
/KEYPAD
/LOGICAL_NAMES
/NONOTIFY
/OUTPUT=SYS$0UTPUT
See text
See text
/SYMBOLS
/WAIT

Parameter
command
Specifies an optional command to be executed by the subprocess you are
creating. If you specify the command parameter, you create a subprocess
which executes the command and returns control to the DECtrace session
when the command terminates. If you include the /INPUT qualifier with the
command parameter, the subprocess reads the commands from the specified
input file after the command executes. The command string cannot exceed 132
characters.
If you omit the command parameter, the SPAWN command creates a
subprocess and attaches your terminal to it. You can return to your DECtrace
session by logging out of the subprocess or by issuing the ATTACH/PARENT
command. If you have created several subprocesses, you can switch between
them using the ATTACH/IDENTIFICATION command.

7-72 DECtrace Commands

SPAWN

Qualifiers
/CARRIAGE_ CONTROL
/NOCARRIAGE_ CONTROL

Determines whether carriage control or line feed characters (or both) are
prefixed to the DCL-prompt string of the subprocess. The default is the current
setting of the parent process.
!CLl[=cli]
/NOCLI

Specifies an alternate command language interpreter (CLI) for the subprocess
to use. The default is the CLI the parent process uses.
The CLI you specify must be located in SYS$SYSTEM and have the file type
EXE.
/INPUT=file-spec

Specifies an input file containing one or more commands for the spawned
subprocess to execute. If you specify a command with an input file, the
command is processed before the commands in the input file. The subprocess
terminates when processing is complete. You cannot use wildcards in the file
specification.
/KEYPAD (default)
/NO KEYPAD

Determines whether DCL keypad symbols and the current DCL keypad state
are copied from the parent process to the subprocess. The default is to copy
any key definitions or states (or both) you have established with the DEFINE
/KEY command. Use the /NO KEYPAD qualifier if you do not want the key
settings to be copied.
ILOGICAL_NAMES (default)
/NOLOGICAL_NAMES

Determines whether the system passes process logical names and logical name
tables to the subprocess. The default is to copy all process logical names
and logical name tables except those marked CONFINE or those created in
executive or kernel mode.
/NOTIFY
/NONOTIFY (default)

Determines whether a message is sent to your terminal to notify you that your
subprocess has been completed or aborted. Do not specify /NOTIFY unless you
also specify the /NOWAIT qualifier.

DECtrace Commands

7-73

SPAWN
!OUTPUT=file-spec
Specifies the output file to which the output of the SPAWN operation is to be
written. When you specify /NOWAIT, you should use /OUTPUT to specify an
output other than SYS$0UTPUT to prevent your terminal from being used by
both processes simultaneously. By default, DECtrace directs the output to the
current SYS$0UTPUT device (usually, your terminal).
!PROCESS=subprocess-name
Specifies the name of the subprocess to be created. The default name for the
subprocess is USERNAME_#. The pound sign ( #) denotes a unique number.
/PROMPT[=string]
Specifies the prompt string for the subprocess. If you specify /PROMPT but do
not specify a string, the default prompt is displayed. The default is to copy the
current prompt string from the parent process.
!SYMBOLS (default)
/NOSYMBOLS
Determines whether the system passes DCL global and local symbols to the
subprocess.
/WAIT (default)
/NOWAIT
Controls whether the system waits until the subprocess is completed before
allowing more commands to be issued by the parent process. The /NOWAIT
qualifier allows you to enter more commands while the specified subprocess
is running. When you specify /NOWAIT, you should also specify /OUTPUT to
direct output to a file (rather than to your screen). This prevents your terminal
from being used by both processes simultaneously.

Description
The SPAWN command creates a subprocess of your current DECtrace sessionyour parent process. The context of your DECtrace process is copied to the
subprocess.
You can use the SPAWN command to leave the DECtrace command
environment temporarily, to perform some non-DECtrace activities, and
then return to your original DECtrace session. The advantage to using the
SPAWN command is that you do not have to detach and reattach to the
DECtrace administration database each time you need to leave the DECtrace
command environment.

7-74

DECtrace Commands

SPAWN

Example
$ COLLECT
DECtrace> SPAWN
$ SHOW DEVICE DUA2
Device
Name
MYVAX$DUA2:

Device
Status
Mounted

Error
Count
0

Volume
Label
USER2

Free Trans Mnt
Blocks Count Cnt
242686
2 25

LOGOUT
Process SMITH_l logged out at 10-FEB-1990 16:07:58.50
%EPC-S-SPAWN, Spawn successfully completed
DECtrace>
$

Creates a subprocess of the current process so that you can execute some
non-DECtrace activities. In this case, the user checks the free space on a disk,
then returns to the parent process.

DECtrace Commands

7-75

STOP SYSTEM

STOP SYSTEM
Stops the DECtrace Registrar process and interrupts any active data collection.
This command is usual1y performed as part of your system shutdown
procedure. Stopping DECtrace is a management function that requires VMS
OPER privilege to perform.

Format
STOP SYSTEM

Command Qualifier

Default

/[NO]ABORT

/NOABORT

Qualifier
/ABORT
/NOABORT {default)

Specifies whether DECtrace can abort active data collection on the system.
If data collection is occurring on the system and you use the STOP SYSTEM
command without the /ABORT qualifier, DECtrace issues an error message
indicating that data collection must be interrupted, but it not stop the system.
To stop the system while data collection is occurring, you must use the /ABORT
qualifier. In this situation, DECtrace issues a warning message that data
collection will be interrupted and stops the system.
If no collections are currently active, DECtrace ignores the /[NO]ABORT
qualifier.

Description
This command is not intended for normal interactive use. However, it is
supplied for unusual cases where you want to stop the DECtrace system
interactively. It is recommended that you stop the DECtrace system as part of
your normal system shutdown procedure. You should add the following lines to
your file SYS$MANAGER:SHUTDWN.COM:

7-76 DECtrace Commands

STOP SYSTEM
$!Shutdown DECtrace and abort all active data collection
$ COLLECT STOP SYSTEM /ABORT

Note You must stop the DECtrace before attempting to stop the Rdb/VMS monitor

process.
To restart DECtrace, issue the command:
$

@SYS$STARTUP:EPC$STARTUP.COM

Examples
$ COLLECT STOP SYSTEM
%EPC-I-STOPPED, System stopped at user's request.
$

Stops DECtrace if data collection is not currently active on the system.

$ COLLECT
DECtrace> STOP SYSTEM
%EPC-E-NOTSTOPPED, System was not stopped because data collection
is active.
%EPC-I-USEABORT, You must use the /ABORT qualifier to interrupt active
data collection.

Attempts to stop DECtrace while data collection is occurring. DECtrace issues
an error message indicating that data collection is active on the system and
that the system cannot be stopped without the /ABORT qualifier.

DECtrace> STOP SYSTEM /ABORT
%EPC-I-STOPPED, System stopped at user's request.
DECtrace> jClRL/ZI
$

Interrupts all active data collection and shuts down the DECtrace registrar
process.

DECtrace Commands

7-77

8
DECtrace Service Routines

DECtrace provides a set of service routines to use when ini;trumenting an
application program so that event data can be collected from it. These routines
are to be embedded in the source code of the program. Chapter 5 describes
how to correctly instrument your code with DECtrace service routine calls.
Table 8-1 lists the DECtrace service routine calls and summarizes their
descriptions.
Table 8-1

DECtrace Service Routines

Routine Name

Description

EPC$DELETE_CONTEXT

Deletes the context associated with a particular
thread (for multi-threaded facilities only).

EPC$END_EVENT

Records the end of a duration event to the data
collection file.

EPC$END_EVENTW

Records the end of a duration event to the data
collection file and waits for processing to complete
before returning.

EPC$EVENT

Records the occurrence of a point event to the data
collection file.

EPC$EVENTW

Records the occurrence of a point event to the data
collection file and waits for processing to complete
befo.re returning.

EPC$INIT

Registers a facility with DECtrace to enable data
collection on this facility.
(continued on next page)

DECtrace Service Routines 8-1.:

Table 8-1 (Cont.)

DECtrace Service Routines

Routine Name

Description

EPC$SET_CONTEXT

Sets the context for a new or existing thread so
resource utilization items can be collected (for multithreaded facilities only).

EPC$START_EVENT

Records the start of a duration event to the data
collection file.

EPC$START_EVENTW

Records the start of a duration event to the data
collection file and waits for processing to complete
before returning.

The DECtrace service routines are similar to· the VMS system services.
Any routines that perform 1/0 have two types: synchronous ( W) and
asynchronous. A synchronous routine ends in W (for example, EPC$START_
EVENTW) whereas the asynchronous version has no W (for example,
EPC$START_EVENT). The routines that record data collection records in
the data collection file are EPC$EVENT(W), EPC$START_EVENT(W), and
EPC$END_EVENT(W). All DECtrace routines operate in executive mode and
are AST reentrant.

8. 1 Error Handling
Error reporting is taken care of as follows. Each routine returns a longword
condition value informing the caller of the completion status of the call.
An optional quadword argument containing the completion status for the
asynchronous part of the calls can be returned to the caller. In addition, all
errors encountered during data collection are logged to the system-wide or
cluster-wide history database.
Two types of errors are returned: DECtrace errors and system service errors.
DECtrace errors are prefaced with EPC$. If an unexpected error occurs
during a system routine, DECtrace returns the actual system code. These
system errors usually result from low process quotas or system parameters.
EPC$INIT calls the following system routines: GETSYI, GETTIM, ENQ, DEQ,
SETEF, CLREF, CREMBX, GETJPI, GETDVI, QIO, EXPREG, and DCLAST.
The DECtrace start, end, and point event routines call the following system
routines: GETTIM, ENQ, DEQ, SETEF, CLREF, QIO, EXPREG, and DCLAST.
Each DECtrace service routine has a set of return values associated with it.
See the description of each service routine for a complete list of return values.
Most of these values are self explanatory, but the following values are not as
obvious as the rest:

8-2 DECtrace Service Routines

• The EPC$_DISABLED return value has several different meanings
depending on the context it is returned in. First, this value is returned if
the facility and version do not match any active collection. Second, if this
facility had been collecting data within the context of the current image
and an error occurred on an earlier DECtrace call, EPC$_DISABLED
will be returned on subsequent calls to DECtrace. Finally, this value
will be returned if data collection has been disabled by defining the
EPC$DISABLED logical. See Section 9.5 for more information on disabling
data collection.
• The EPC$_EVNTNOTCOL return value indicates that the facility and
version match the criteria of an active collection, but the current event was
not specified in the selection criteria.
• The EPC$_FACNOTCOL return value indicates that the process has
registered another facility which is actively collecting data, but the current
facility does not match the selection criteria.
• The EPC$_INIT2 return value indicates that the current facility and
version have already registered once within this image activation. This
represents an instrumentation error in the application. EPC$INIT should
only be called once by each facility within an image activation.
• The EPC$_NOREGEXISTS return value indicates that the DECtrace
Registrar process (EPC$REGISTRAR) is not running on the local node.
Use the SYS$STARTUP:EPC$STARTUP.COM procedure to restart the
Registrar process. See Section 9.2 for more information on starting and
stopping the Registrar process.
• The EPC$_NOTINSTALLED return value indicates that the DECtrace
software is not installed on the system.

DECtrace Service Routines 8-3

EPC$DELETE_CONTEXT

EPC$DELETE_CONTEXT
EPC$DELETE_CONTEXT deletes all associated context for the given context
variable.

Format
EPC$DELETE_CONTEXT [efn] ,context-variable [,status] [,astadr ,astparam]

Returns
VMS Usage: cond_value
type:
longword (unsigned)
access:
write only
mechanism: by value

Arguments
etn
VMS Usage: ef_number
type:
longword (unsigned)
access:
read only
mechanism: by value
The VMS event flag to be set when EPC$DELETE_CONTEXT completes. The
efn argument is a longword containing the address of this· flag.
Upon initiation, EPC$DELETE_CONTEXT clears the specified event flag
(or event flag 0 if efn was not specified). When EPC$DELETE_CONTEXT
returns, it sets the specified event flag (or event flag 0).

context-variable
VMS Usage: context
type:
longword (unsigned)
access:
modify
mechanism: by reference
The address of the longword that contains the context variable to delete.
EPC$DELETE_CONTEXT sets the longword value to zero.

8-4 DECtrace Service Routines

EPC$DELETE_CONT~XT

status
VMS Usage: io_status_block
type:
quadword (unsigned)
access:
write only
mechanism: by reference

When you specify the status argument, EPC$DELETE_CONTEXT sets the
first longword to zero at initiation. The second longword is always zero. Upon
completion, a condition value returns in the first longword.
astadr
VMS Usage: ast_procedure
type:
procedure entry mask
access:
call without stack unwinding
mechanism: by reference

The address of the entry mask of the AST service routine to be executed when
EPC$DELETE_CONTEXT completes.
If you specify the astadr argument, the AST routine executes in the same

access mode as the caller of EPC$DELETE_CONTEXT.
astparam
VMS Usage: user_arg
type:
longword (unsigned)
access:
read only
mechanism: by value

The AST parameter to be passed to the AST service routine specified by the
astadr argument. The astparam argument is a longword parameter.
Include this argument only when you specify the astadr argument.

Description
The EPC$DELETE_CONTEXT routine deletes the context variable. All
associated context for DECtrace to collect resource utilization items for a
particular context variable is deleted.
The value of the context-variable argument is set to zero upon completion.
A facility calls the EPC$DELETE_CONTEXT service only if an associated
EPC$SET_CONTEXT call was previously issued and when execution of a
thread completes to its entirety.

DECtrace Service Routines 8-5

EPC$DELETE_CONTEXT

Return Values

EPC$_BADASTADR

Bad A.g'f address specified.

EPC$_BADASTPRM

Bad A.g'f parameter specified.

EPC$_BADSTATUS

Bad status argument passed.

EPC$_BADTHREAD

Bad thread argument passed.

EPC$_DISABLED

Collection has been disabled.

EPC$_INSARGS

Insufficient arguments specified.

EPC$_NOTHREAD

No thread argument was passed.

EPC$_NOTINSTALL

DECtrace soft.ware is not installed.

EPC$_SUCCESS

This call was successful.

DECtrace Service Routines

EPC$END~EVENT

EPC$END_EVENT
EPC$END_EVENT records the end of an event to the data collection file.
The EPC$END_EVENT routine completes asynchronously. It returns control
to the caller after initiating the $END_EVENT processing, without waiting for
1/0 processing to complete.

Format
EPC$END_EVENT

[efn] ,facility ,event-id ,handle [,context-variable] [,event-rec] [,status]
[,astadr ,astparam]

Returns
VMS Usage: cond_value
type:
longword (unsigned)
access:
write only
mechanism: by value

Arguments
efn
VMS Usage: ef_number
type:
longword (unsigned)
access:
read only
mechanism: by value

The VMS event flag to be set when EPC$END_EVENT completes. The efn
argument is a longword containing the address of this flag.
Upon initiation, EPC$END_EVENT clears the specified event flag (or event
flag 0 if efn was not specified). When EPC$END_EVENT returns, it sets the
specified event flag (or event flag 0).
facility
VMS Usage: longword_unsigned
type:
longword (unsigned)
access:
read only
mechanism: by value

The facility number for the calling facility. Facilities 1 through 2047 are
reserved for Digital. Facilities 2048 through 4097 are user-defined.

DECtrace SeNice Routines 8-7

EPC$END_EVENT
event-id
VMS Usage: longword_unsigned
type:
longword (unsigned)
access:
read only
mechanism: by value

The event identifier for the event.
handle
VMS Usage: context
type:
longword (unsigned)
access:
write only
mechanism: by reference

The address of the longword to retrieve a process unique event handle for this
particular event.
The supplied longword handle is the same handle that was returned from the
corresponding EPC$START_EVENT call for an event instance.
context-variable
VMS Usage: context
type:
longword (unsigned)
access:
read only
mechanism: by reference

The address of the longword used to identify the context in which this
call appears. When specified, the value of the longword corresponds to the
context-variable argument returned from the call to EPC$SET_CONTEXT.
event-rec
VMS Usage: vector_byte_signed
type:
any binary or ASCII data
access:
read only
mechanism: by descriptor-fixed length descriptor

The address of a descriptor pointing to a record buffer containing the item
values for an event. The item values are facility specific; they do not include
any resource utilization items. DECtrace handles the resource item values
transparently. As a result, you do not need to specify the event-rec on
the EPC$END_EVENT call if you want only the set of standard resource
utilization items.

8-8

DECtrace Service Routines

EPC$END_EVENT
status
VMS Usage: io_status_block
type:
quadword (unsigned)
access:
write only
mechanism: by reference
When you specify the status argument, EPC$END_EVENT sets the first
longword to zero at initiation. The second longword is always zero. Upon
completion, a condition value returns in the first longword.

astadr
VMS Usage: ast_procedure
type:
procedure entry mask
access:
call without stack unwinding
mechanism: by reference
The address of the entry mask of the AST service routine to be executed when
EPC$END_EVENT completes.
If astadr is specified, the AST routine executes in the same access mode as the

caller of EPC$END_EVENT.

astparam
VMS Usage: user_arg
type:
longword (unsigned)
access:
read only
mechanism: by value
AST parameter to be passed to the AST service routine specified by the astadr
argwnent. The astparam argwnent is a longword parameter.
Include this argwnent only when you specify the astadr argument.

Description
The EPC$END_EVENT routine enables a given facility to log an end event
record to the data collection file. This service is called at the end of a duration
event with various items determined by the item flags list for a given facility.
For performance reasons, DECtrace does not write every record directly to the
data collection file. Instead, records are buffered and flushed to disk when the
buffer is full. The EPC$END_EVENT routine completes asynchronously. It
returns to the caller after copying the end event record to the buffer without
waiting for any buffer flushes to complete.

DECtrace Service Routines

8-9

EPC$END_EVENT

Return Values
EPC$_BADASTADR

Bad ASr address specified.

EPC$_BADASTPRM

Bad ASr parameter specified.

EPC$_BADEVNT

Bad event ID argument passed.

EPC$_BADEVNTREC

Bad event record argument passed.

EPC$_BADFAC

Bad facility code passed.

EPC$_BADHANDL

Bad handle argument passed.

EPC$_BADSTATUS

Bad status argument passed.

EPC$_BADTHREAD

Bad thread argument passed.

EPC$_DCFCORRUPT

Data capture file is corrupt.

EPC$_DISABLED

Collection has been disabled.

EPC$_EVTNOTCOL

Event is not being collected.

EPC$_FACNOTCOL

Facility is not being collected.

EPC$_ILLBUFLEN

The record buffer was larger than the maximum.

EPC$_INSARGS

Insufficient arguments specified.

EPC$_NODCFEXISTS

The specified data capture file does not exist.

EPC$_NOEVNT

No event ID argument specified.

EPC$_NOFAC

No facility argument specified.

EPC$_NOHANDL

No handle argument passed.

EPC$_NOTINSTALL

DECtrace software is not installed.

EPC$_SUCCESS

This call was successful.

8-10 DECtrace Service Routines

EPC$END~EVENTW

EPC$END_EVENTW
EPC$END_EVENTW records the end of an event to the data collection file.
This service is called at the end of a duration event with various items
determined by the item flags list for a given facility.
The EPC$END_EVENTW routine completes synchronously. It returns control
to the caller when the $END_EVENTW processing completes.

Format
EPC$END_EVENTW

[efn] ,facility ,event-id ,handle [,context-variable] [,event-rec] [,status]
[,astadr ,astparam]

Description
For asynchronous completion, use the EPC$END_EVENT routine. EPC$END_
EVENT returns to the caller after initiating the processing without waiting for
1/0 to complete.
For performance reasons, DECtrace does not write every record directly to the
data collection file. Instead, records are buffered and flushed to disk when the
buffer is full. The EPC$END_EVENTW routine completes synchronously. That
is, if a buffer flush needs to be performed, it waits for 1/0 to complete before
returning to the caller.
In all other respects, EPC$END_EVENTW is identical to EPC$END_EVENT.
Refer to EPC$END_EVENT for all other information about the EPC$END_
EVENTW service routine.

DECtrace Service· Routines

8-11

EPC$EVENT

EPC$EVENT
EPC$EVENT records the occurrence of a point event to the data collection file.
The EPC$EVENT routine completes asynchronously. It returns control to
the caller after initiating the $EVENT processing without waiting for 1/0
processing to complete.

Format
EPC$EVENT [efn] ,facility ,event-id [,context-variable] [,event-rec] [,status] [,astadr
,astparam]

Returns
VMS Usage: cond_value
type:
longword (unsigned)
access:
write only
mechanism: by value

Arguments
etn
VMS Usage: ef_number
type:
longword (unsigned)
access:
read only
mechanism: by value

The VMS event flag to be set when EPC$EVENT completes. The efri argument
is a longword containing the address of this flag.
Upon initiation, EPC$EVENT clears the specified event flag (or event flag 0 if
efn was not specified). When EPC$EVENT returns, it sets the specified event
flag (or event flag 0).
facility
.
VMS Usage: longword_unsigned
type:
longword (unsigned)
access:
read only
mechanism: by value

· The facility number for the calling facility. Facilities 1 through 2047 are
reserved for Digital. Facilities 2048 through 4097 are user-defined.

8-12

DECtrace SeNice Routines

EPC$E,VENT
event-id
VMS Usage: longword_unsigned
type:
longword (unsigned)
access:
read only
mechanism: by value
The event identifier for an event.
context-variable
VMS Usage: context
type:
longword (unsigned)
access:
read only
mechanism: by reference
The address of the longword used to identify the context variable. When
specified, the value of the longword corresponds to. the context-variable
argwnent returned from the call to EPC$SET_CONTEXT.
event-rec
VMS Usage: vector_byte_signed
type:
any binary or ASCII data
access:
read only
mechanism: by descriptor-fixed length descriptor
The address of a descriptor pointing to a record buffer containing the item
values for an event. The item values are facility specific; they do not include
the resource utilization items. DECtrace handles the resource item values
transparently. As a result you do not need to specify the event-rec on the
EPC$EVENT call if you only want the set of standard resource utilization
items.
status
VMS Usage: io_status_block
type:
quadword (unsigned)
access:
write only
mechanism: by reference
When you specify the status argument, EPC$EVENT sets the first longword
to zero at initiation. The second longword is always zero. Upon completion, a
condition value returns in the first longword.
astadr
VMS Usage: ast_procedure
type:
procedure entry mask
access:
call without stack unwinding

DECtrace Service Routines 8-13

EPC$EVENT
mechanism: by reference

The address of the entry mask of the AST service routine to be executed when
EPC$EVENT completes.
If the astadr is specified, the AST routine executes in the same access mode as
the caller of EPC$EVENT.

astparam
VMS Usage: user_arg
type:
longword (unsigned)
access:
read only
mechanism: by value

Description
EPC$EVENT routine enables a given facility to record the occurrence of a
point event to the data collection file.
For performance reasons, DECtrace does not write every record directly to the
data collection file. Instead, records are buffered and flushed to disk when the
buffer is full. The EPC$EVENT routine completes asynchronously. That is, it
returns to the caller after copying the point event record to the buffer without
waiting for any buffer flushes to complete.

Return Values

8-14

EPC$_BADASTADR

Bad AST address specified.

EPC$_BADASTPRM

Bad AST parameter specified.

EPC$_BADEVNT

Bad event ID argument passed.

EPC$_BADEVNTREC

Bad event record argument passed.

EPC$_BADFAC

Bad facility code passed.

EPC$_BADSTATUS

Bad status argument passed.

EPC$_BADTHREAD

Bad thread argument passed.

EPC$_DCFCORRUPT

Data capture :file is corrupt.

DECtrace Service Routines

EPC$EVENT

EPC$_DISABLED

Collection has been disabled.

EPC$_EVTNOTCOL

Event is not being collected.

EPC$_FACNOTCOL

Facility is not being collected.

EPC$_ILLBUFLEN

The record buffer was larger than the maximum.

EPC$_INSARGS

Insufficient arguments specified.

EPC$_NODCFEXISTS

The specified data capture file does not exist.

EPC$_NOEVNT

No event ID argument specified.

EPC$_NOFAC

No facility argument specified.

EPC$_NOTINSTALL

DECtrace software is not installed.

EPC$_SUCCESS

This call was successful.

DECtrace Service Routines 8-15

EPC$EVENTW

EPC$EVENTW
EPC$EVENTW records the occurrence of a point event to the data collection
file and waits for 1/0 processing to complete before returning control.
The EPC$EVENTW routine completes synchronously. It returns to the caller
when the $EVENTW processing completes.

Format
EPC$EVENTW

[efn] ,facility ,event-id [,context-variable] [,event-rec] [,status] [,astadr
,astparam]

Description
For asynchronous completion, use the EPC$EVENT service; EPC$EVENT
returns to the caller after initiating the processing without waiting for I/Oto
complete.
For performance reasons, DECtrace does not write every record directly to the
data collection file. Instead, records are buffered and flushed to disk when the
buffer is full. The EPC$EVENTW routine completes synchronously. That is, if
a buffer flush needs to be performed, it will wait for the I/O to complete before
returning to the caller.
In all other respects, EPC$EVENTW is identical to EPC$EVENT. Refer to
EPC$EVENT for all other information about the EPC$EVENTW service
routine.

8-16

DECtrace Service Routines

EPC$1NIT

EPC$1NIT
EPC$INIT registers a facility with DECtrace.

Format
EPC$1NIT [efn] ,facility ,version [,registration_id] [,eventflgs] [,itemflgs] [,status] [,astadr
,astparam]

Returns
VMS Usage: cond_value
type:
longword (unsigned)
access:
write only
mechanism: by value

Arguments
efn
VMS Usage: ef_number
type:
longword (unsigned)
access:
read only
mechanism: by value

The VMS event flag to be set when EPC$INIT completes. The efn argwnent is
a longword containing the address of this flag.
Upon initiation, EPC$INIT clears the specified event flag (or event flag 0 if efn.
was not specified). When EPC$INIT returns, it sets the specified event flag (or
event flag 0).
facility
VMS Usage: longword_unsigned
type:
longword (unsigned)
access:
read only
mechanism: by value

The facility number for the calling facility. Facilities 1 through 204 7 are
reserved for Digital. Facilities 2048 through 4097 are user-defined.

DECtrace SeNice Routines 8-17

EPC$1NIT
version
VMS Usage: char_string
type:
character-coded text string
access:
read only
mechanism: by descriptor
The string, up to 10 characters, identifying the current version of the facility.
Note that the string must match identically with that specified in the facility
definition.

reglstratlon_id
VMS Usage: char_string
type:
character-coded text string
access:
read only
mechanism: by descriptor
A string of up to 255 characters containing the identifier this facility wants to
associate with this VMS process. This identifier is "registered" in the DECtrace
administration database along with other information for this process. The
registration identifier gives the user the ability to schedule data collection for
a group of processes. For example, if ACMS uses this identifier to describe a
particular application, the user can then choose to schedule data collection for
all processes that belong to that particular application, rather than collect data
on all ACMS applications.
The registration-id can contain the following characters:
• A through Z
• a through z
• 0 through 9
• Underscore ( _)
• Hyphen(-)

eventflgs
VMS Usage: vector_longword_unsigned
type:
longword (unsigned)
access:
write only
mechanism: by reference
A list of 128 longword Boolean values. Each list element corresponds to
an event identifier and designates whether data collection is enabled for a
particular event.

8-18

DECtrace Service Routines

EPC$1NIT
A facility needs only one copy of the event flags.
The following figure shows the physical structure of the event flags:
Event Flags List
0

Event Flag 1

Event ID 1

•
•

•

I _________E_ve_n_t_F_1a_g_1_2s_ _ _ _ _ _ _ ___,

Event ID 128 ....

If True = 1, If False =0
NU-2052A-RA

ltemflgs
VMS Usage: item_flags_list
type:
longword (unsigned)
access:
write only
mechanism: by reference

A list of 128 item flags. Each set of item flags, referred to as a list element,
is 128 bits and corresponds to a particular event. The flags designate which
items are to be collected for a particular event. If bit 0 is set for item flags 1,
then item 1 is to be collected for event 1.
The facility needs only one copy of the item flags.
The following figure shows the physical structure of the item flags list:

DECtrace Service Routines 8-19

EPC$1NIT

Item Flags List

127
Event ID 1

Item
128

Item
127

Item
126

• • •

Item
3

Item
2

Item
1

List
Element 1

Item
3

Item
2

Item
1

List
Element 128

•

•
•
Event ID 128

Item
128

Item.
127

Item
126

• • •

If item flag 1 , collect data
If item flag= 0, do not collect data
NU-2053A-RA

status
VMS Usage: io_status_block
type:
quadword (unsigned)
access:
write only
mechanism: by reference

When you specify the status argument, EPC$INIT sets the first longword to
zero at initiation. The second longword is always zero. Upon completion, a
condition value returns in the first longword.
astadr
VMS Usage: ast_procedure
type:
procedure entry mask
access:
call without stack unwinding
mechanism: by reference

The address of the entry mask of the AST service routine to be executed when
EPC$INIT completes.
If the astadr is specified, the AST routine executes in the same access mode as
the caller of EPC$INIT.
astparam
VMS Usage: user_arg
type:
longword (unsigned)
access:
read only
mechanism: by value

8-20 DECtrace Service Routines

EPC$1NIT
The AST parameter to be passed to the AST service routine specified by the
astadr argument. The astparam argument is a longword parameter.
Include this argument only when you specify the astadr argument.

Description
The EPC$INIT routine registers a facility with DECtrace. By registering,
active and pending collections are enabled for this facility (provided that data
collection is scheduled using the SCHEDULE command).
The EPC$INIT routine completes in both a synchronous and asynchronous
nature. The initial values of the eventflgs and item.figs arguments, if
specified, are returned synchronously, which allows the facility to determine
which events and associated items are to be collected immediately following
the call to EPC$INIT. However, the values of the eventfigs and item.figs can
change as collections become active. The values of the eventftgs and item.figs
change to reflect the values in the corresponding facility selection for the data
collection.
As collections become active, the DECtrace registrar process notifies the
application process of the event and item flags for that specific collection.
Because of the communication involved and the asynchronous nature by which
you can schedule data collection, the values of the event and item flags can
change asynchronously.
The status argument is returned when EPC$INIT completes.

Return Values
EPC$_BADEVNTFLGS

Bad facility event :flags passed.

EPC$_BADFAC

Bad facility code passed.

EPC$_BADFACVER

Bad facility version passed.

EPC$_BADITMFLGS

Bad facility item :flags passed.

EPC$_BADREGID

Bad facility registration group ID passed.

EPC$_DISABLED

Data collection disabled.

EPC$_FACVERREQ

Facility version required.

EPC$_INIT2

EPC$1NIT called twice.

EPC$_NODCFEXISTS

No data capture file exists.

DECtrace SeNice Routines 8-21

EPC$1NIT

EPC$_NOTINSTALL

No registrar process exists on this node.
DECtrace ·software is not installed.

EPC$_SUCCESS

Routine completed successfully.

EPC$_NOREGEXISTS

8-22 DECtrace Service Routines

EPC$SET_CONTEXT

EPC$SET_CONTEXT
EPC$SET_CONTEXT records a context variable for a new or existing thread
so that resource utilization items can be collected for multi-threaded facilities.

Format
EPC$SET_CONTEXT

[efn] ,context-variable [,status] [,astadr ,astparam]

Returns
VMS Usage: cond_value
type:
longword (unsigned)
access:
write only
mechanism: by value

Arguments
etn
VMS Usage: ef_number
type:
longword (unsigned)
access:
read only
mechanism: by value

The VMS event flag to be set when EPC$SET_CONTEXT completes. The efn
argument is a longword containing the address of this flag.
Upon initiation, EPC$SET_CONTEXT clears the specified event flag (or event
flag 0 if efn was not specified). When EPC$SET_CONTEXT returns, it sets
the specified event flag (or event flag 0).
context-variable
VMS Usage: context
type:
longword(unsigned)
access:
modify
mechanism: by reference

The address of the longword that contains the context variable to which context
should be set.

DECtrace Service Routines 8-23

EPC$SET_CONTEXT
If a zero value is passed at the address specified, then EPC$SET_CONTEXT
returns a value that identifies the new thread context. If the address contains

a non-zero context variable, then a context change record is written to the data
collection file.
status
VMS Usage: io_status_block
type:
quadword (unsigned)
access:
write only
mechanism: by reference

When you specify the status argwnent, EPC$SET_CONTEXT sets the first
longword to zero at initiation. The second longword is always zero. Upon
completion, a condition value returns in the first longword.
astadr
VMS Usage: ast_procedure
type:
procedure entry mask
access:
call without stack unwinding
mechanism: by reference

The address of the entry mask of the AST service routine to be executed when
EPC$SET_CONTEXT completes. The astadr is the address of the entry mask
of this routine.
If you specify the astadr, the AST routine executes in the same access mode

as the caller of EPC$SET_CONTEXT.
astparam
VMS Usage: user_arg
type:
longword (unsigned)
access:
read only
mechanism: by value

The AST parameter to be passed to the AST service routine specified by the
astadr argwnent. The astparam argument is a longword parameter.
Include this argwnent only when you specify the astadr argwnent.

8-24

DECtrace ·Service Routines

EPC$SET_CONTEXT

Description
The EPC$SET_CONTEXT routine sets context for a new thread or an existing
thread so that resource utilization items can be collected for multi-threaded
facilities. This routine is called by a facility when a thread context is initially
created or reentered (by way of a context switch) when resource utilization
items are to be collected on a per-thread basis.
If a zero value is passed at the address specified, then EPC$SET_CONTEXT
returns a value that identifies the new thread context.

The associated EPC$DELETE_CONTEXT routine must be called by a multithreaded facility when a thread executes to its entirety in order to delete
context information that DECtrace maintains on behalf of the facility.

Return Values
EPC$_BADASTADR

Bad AST address specified.

EPC$_BADASTPRM

Bad AST parameter specified.

EPC$_BADSTATUS

Bad status argument passed.

EPC$_BADTHREAD

Bad thread argument passed.

EPC$_DISABLED

Collection has been disabled.

EPC$_INSARGS

Insufficient arguments specified.

EPC$_NOTHREAD

No thread argument was passed.

EPC$_NOTINSTALL

DECtrace software is not installed.

EPC$_SUCCESS

This call was successful.

DECtrace Service Routines 8-25

EPC$START_EVENT

EPC$START_EVENT
EPC$START_EVENT records the start of an event to the data collection file.
The EPC$START_EVENT routine completes asynchronously. It returns to the
caller after initiating the $START_EVENT processing without waiting for 1/0
processing to complete.

Format
EPC$START_EVENT

[efn] ,facility ,event-id ,handle (,context-variable] [,event-rec]
[,status] [,astadr ,astparam]

Returns
VMS Usage: cond_value
type:
longword (unsigned)
access:
write only
mechanism: by value

Arguments
efn
VMS Usage: ef_number
type:
longword (unsigned)
access:
read only
mechanism: by value

The VMS event flag to be set when EPC$START_EVENT completes. The efn
argument is a longword containing the address of this flag.
Upon initiation, EPC$START_EVENT clears the specified event flag (or event
flag 0 if efn was not specified). When EPC$START_EVENT returns, it sets the
specified event flag (or event flag 0).
facility

VMS Usage: longword_unsigned
type:
longword (unsigned)
access:
read only
mechanism: by value

The facility number for the calling facility. Facilities 1 through 2047 are
reserved for Digital. Facilities 2048 through 4097 are user-defined.

8-26 DECtrace SeNice Routines

EPC$START_EVENT
event-id
VMS Usage: longword_unsigned
1ype:
longword (unsigned)
access:
read only
mechanism: by value

The event identifier for an event.
handle
VMS Usage: context
type:
longword (unsigned)
access:
write only
mechanism: by reference

The address of the longword to store a process unique event handle for this
particular event. The handle is used in the corresponding EPC$END_EVENT
call for an event.
context-variable
VMS Usage: context
type:
longword (unsigned)
access:
read only
mechanism: by reference

The address of a descriptor pointing to a record buffer containing the item
values for an event. The item values are facility specific; they do not include
the resource utilization items. DECtrace handles the resource item values
transparently. As a result, you do not need to specify the event-rec on
the EPC$START_EVENT call if you want only the set of standard resource
utilization items.
status
VMS Usage: io_status_block
type:
quadword (unsigned)
access:
write only

DECtrace Service Routines 8-27

EPC$START_EVENT
mechanism: by reference

When you specify the status argument, EPC$START_EVENT sets the first
longword to zero at initiation. The second longword is always zero. Upon
completion, a condition value returns in the first longword.
astadr
VMS Usage: ast_procedure
type:
procedure entry mask
access:
call without stack unwinding
mechanism: by reference

The address of the entry mask of the AST service routine to be executed when
EPC$START_EVENT completes.
If you specify the astadr, the AST routine executes in the same access mode
as the caller of EPC$START_EVENT.

astparam
VMS Usage: user_arg
type:
longword (unsigned)
access:
read only
mechanism: by value

Description
The EPC$START_EVENT routine enables a given facility to log the start of
an event to the data collection file. This routine is called at the beginning of a
duration event that can have various facility-specific items associated with it.
The items recorded· are determined by the item flags list for the facility. A call
to EPC$END_EVENT follows this call where the event ends.
For performance reasons, DECtrace does not write every record directly to the
data collection file. Instead, records are buffered and flushed to disk when the
buffer is full. The EPC$START_EVENT routine completes asynchronously.
That is, it returns to the caller after copying the start event record to the
buffer without waiting for any buffer flushes to complete.

8-28

DECtrace SeNlce Routines

EPC$START_EVENT

Return Values
EPC$_BADASTADR

Bad AST address specified.

EPC$_BADASTPRM

Bad AST parameter specified.

EPC$_BADEVNT

Bad event ID argument passed.

EPC$_BADEVNTREC

Bad. event record argument passed.

EPC$_BADFAC

Bad facility code passed.

EPC$_BADHANDL

Bad handle argument passed.

EPC$_BADSTATUS

Bad status argument passed.

EPC$_BADTHREAD

Bad thread argument passed.

EPC$_DCFCORRUPT

Data capture file is corrupt.

EPC$_DISABLED

Collection has been disabled.

EPC$_EVTNOTCOL

Event is not being collected.

EPC$_FACNOTCOL

Facility is not being collected.

EPC$_ILLBUFLEN

The record buffer was larger than the maximum.

EPC$_INSARGS

Insufficient arguments specified.

EPC$_NODCFEXISTS

The specified data capture file does not exist.

EPC$_NOEVNT

No event ID argument specified.

EPC$_NOFAC

No facility argument specified.

EPC$_NOHANDL

No handle argument passed.

EPC$_NOTINSTALL

DECtrace software is not installed.

EPC$_SUCCESS

This call was successful.

DECtrace Service Routines 8-29

EPC$START_EVENTW

EPC$START_EVENTW
EPC$START_EVENTW records the start of a duration event to the data
collection file.
The EPC$START_EVENTW routine completes synchronously. It returns to the
caller after all $START_EVENTW processing completes.

Format
EPC$START_EVENTW [efn] ,facility ,event-id ,handle [,thread] [,event-rec] [,status]
[,astadr ,astparam]

Description
For asynchronous completion, use the EPC$START_EVENT service;
EPC$START_EVENT returns control to the caller after initiating the
processing, without waiting for 1/0 processing to complete.
For performance reasons, DECtrace does not write every record directly to the
data collection file. Instead, records are buffered and flushed to disk when the
buffer is full. The EPC$START_EVENTW routine completes synchronously;
if a buffer flush needs to be performed, it waits for the 1/0 to complete before
returning to the caller.
In all other respects, EPC$START_EVENTW is identical to EPC$START_
EVENT. Refer to EPC$EVENT for all other information about the
EPC$START_EVENTW routine.

8-30

DECtrace Service Routines

9
System Management Tasks
This chapter describes the system management functions associated with using
DECtrace.

9.1

Required Account and Process Quotas
You must make sure that the appropriate user accounts have sufficient quotas
to be able to use DECtrace. If you typically format very large collection files
(over 50,000 blocks) and generate reports based on large formatted databases,
you can improve performance by increasing several of your account quotas.
Table 9-1 summarizes the required and optional user account quotas.
Table 9-1

User Account Quotas for Using DECtrace

Account Quota

Normal Use

ASTLM

BIOLM

BYTLM

20,480

DI OLM

ENQLM

1,800

FILLM

PGFLQUO

20,000

PRCLM

WSEXTENT

2048

WSQUOTA

1024

Formatting and Reporting on Large Files

34,810
10,000
75,000

System Management Tasks 9-1

User account quotas are stored in the file SYSUAF.DAT. Use the VMS
Authorize Utility to verify and change user account quotas. First set your
directory to SYS$SYSTEM and then run AUTHORIZE:
$ SET DEFAULT SYS$SYSTEM
$ RUN AUTHORIZE

UAF>

At the UAF> prompt, use the SHOW command with an account name to check
a particular account. For example:
UAF> SHOW SMITH

To change a quota, use the MODIFY command at the UAF> prompt. MODIFY
has the following format:
MODIFY account-name

/quota-name=NNN

The following example changes the FILLM quota for the SMITH account and
then exits from the utility:
UAF>MODIFY SMITH /FILLM=50
UAF>EXIT

After you exit from the utility, the system displays messages indicating
whether or not changes were made. Once you have made the changes, users
must log out and log in again for the new quotas to take effect.
For more information on modifying account quotas, see the VMS Authorize
Utility Manual.

9 .2 Controlling DECtrace
A part of DECtrace called the Registrar process is designed to be active on
your system or cluster at all times. This process handles all communication
between your application programs and DECtrace. Without this process,
applications instrumented with DECtrace calls cannot register with DECtrace.
In addition, you cannot schedule data collection without the Registrar process.

9 .2. 1 Starting DECtrace
Generally, you should start the DECtrace Registrar process as part of your
normal system startup procedure. Note that you must start the Registrar
process after activating the RdbNMS monitor process on your system.
Add the DECtrace startup procedure to the system startup command file on
each node that you want DECtrace to run on:
$! Start the Rdb/VMS monitor process
$ @SYS$STARTUP:RMONSTART

$! Start DECtrace
$ @SYS$STARTUP:EPC$STARTUP

9-2 System Management Tasks

You can also restart the Registrar process interactively with the following
command:
$

@SYS$STARTUP:EPC$STARTUP

9 .2.2

Stopping DECtrace

Digital recommends that you stop DECtrace as part of your normal system
shutdown procedure. Note that you must stop the DECtrace Registrar process
before stopping the Rdb/VMS monitor process. If you attempt to stop the
Rdb/VMS monitor first, both processes will hang and you will have to use the
VMS STOP/ID command to cancel the EPC$REGISTRAR process.
Add the DECtrace shutdown command to SYS$MANAGER:SYSHUTDWN.COM
on each node that DECtrace is running on:
$! Shutdown DECtrace and abort all active data collection
$ COLLECT STOP SYSTEM/ABORT
$! Shutdown the Rdb/VMS monitor process
$ @SYS$MANAGER:RMONSTOP

You can also stop the Registrar process interactively with the following
command:
$

COLLECT STOP SYSTEM/ABORT

Note that when the Registrar process is stopped, any processes that are
actively collecting data continue to record data to the data collection file(s).
Data collection continues until either the image terminates or the Registrar is
restarted and the collection ends normally.

9 .2.3

Recovering From a System Crash

After a system crash, the DECtrace registrar process should restart
automatically as part of your normal system startup procedure.
If a collection is active when the system goes down, data collection resumes

so long as the registrar process is restarted before the scheduled end-time
of the collection. If a collection is pending when the system goes down, data
collection begins as scheduled so long as the registrar process restarts before
the scheduled end-time. For example, consider the following collections
scheduled on node MYVAXl:
24-JUL-1989 08:45
Brief Report

Page 1
DECtrace Vl.O

Scheduled Collections

Collection Schedule for node MYVAXl

Selection Name

Collection Name

Start

End

MY SELECTION
TOOLS SELECTION
MY SELECTION

MORNING DATA
JOB123
AFTERNOON DATA

24-JUL-89 08:00
24-JUL-89 10:00
24-JUL-89 12:00

24-JUL-89 10:00
24-JUL-89 12:00
24-JUL-89 16:00

System Management Tasks 9-3

If MYVAXl crashes at 09:00 and comes back at 09:30, the collection
MORNING_DATA resumes data collection for the remaining 15 minutes
of the scheduled collection interval. The pending collections: JOB123
and AFTERNOON_DATA are unaffected by the system crash and start as
scheduled.
If MYVAXl crashes at 09:00 and comes back at 10:15, the collection JOB123
starts and runs until its normal completion time. The pending collection:
AFTERNOON_DATA is unaffected by the system crash. Note that the
collection MORNING_DATA successfully collected data from 08:00 until
the crash occurred at 09:00. The partial data capture file(s) produced by the
collection can be formatted and reported on as if the collection had run to
completion.

9 .3 Installing Facilities on Your System
When you perform a product installation on your system, there are several
cases where this could affect your use of DECtrace.

9 .3. 1 Installing New Facilities
When you install a product that has just added DECtrace support or when you
install a supporting product for the first time, there is nothing that you need to
do for DECtrace. The product's installation procedure automatically inserts a
new facility definition into the DECtrace administration database.

9 .3.2

Installing New Versions of Existing Facilities

When you install a product whose previous version also supported DECtrace,
you need to update any of your facility selections which specifically reference
the previous version of the product. The product's installation procedure
automatically inserts a new facility definition into the DECtrace administration
database, but unless you change your facility selections to use the correct
version number for the new product version, you will not be able to collect any
data for that product.
Note that if you create your facility selections without specifying a version for
the facilities, DECtrace always uses the latest version of the facility installed
on your system. You won't have to change your facility selections when you
perform an installation. However, you must recognize that any data collected
from the new version may not be compatible with data collected before the
installation. You would not be able to merge new data into. an existing
formatted database or file.

9-4 System Management Tasks

9.3.3

Installing a New Version of RdbNMS

Before installing a new version of Rdb/VMS, you must perform a full RMU 1
backup of the DECtrace administration and history databases (as well as
any other Rdb/VMS databases on your system, including DECtrace-formatted
databases produced with the FORMAT command).
To backup the DECtrace administration database, use the following command:
$

RMU/BACKUP EPC$ADMIN_DB EPC$ADMIN_DB.RBF

To backup the DECtrace history database, use the following command:
$

RMU/BACKUP EPC$HISTORY_DB EPC$HISTORY_DB.RBF

After installing the new version of RdbNMS you must restore your databases.
The RMU/RESTORE operation restores the database to its original location.
To restore the DECtrace administration database, use the following command:
$

RMU/RESTORE/NEW_VERSION EPC$ADMIN_DB.RBF

To restore the DECtrace history database, use the following command:
$

RMU/RESTORE/NEW_VERSION EPC$HISTORY_DB.RBF

Because the DECtrace administration database is not available during the
installation, Rdb/VMS inserts its facility definition into the DECtrace facility
library SYS$SHARE:EPC$FACILITY.TLB. You must extract this definition and
insert it into the DECtrace administration database. For example:
$ LIBRARY /TEXT /EXTRACT=RDBVMSV3.1-0 /OUT=RDBVMS.EPC$DEF _$ SYS$SHARE:EPC$FACILITY.TLB
$ COLLECT INSERT DEFINITION RDBVMS.EPC$DEF /REPLACE

Note See the VAX Rdb/VMS Release Notes for the version number of your Rdb /VMS
software.

9.4 Managing the History Database
DECtrace maintains a user-visible history database which contains a record
of all informational and error messages encountered during data collection.
There is no automatic purging function and over time, the history database can
become very large. You should periodically create a new (empty) database and
either offload or delete the old version.

RMU is the RdbNMS Management Utility

System Management Tasks 9-5

Use the SET HISTORY /NEW_FILE command to create a new version of the
history database. For example:
$ COLLECT SET HISTORY /NEW FILE
$ PURGE/LOG EPC$HISTORY_DB%PURGE-I-FILPURG, EPC$DATABASE_DIR:EPC$HISTORY_DB.RDB;l deleted
(22640 blocks)

One method of regularly creating a new history database is to put the
DECtrace SET HISTORY/NEW_FILE command into your site-specific startup
procedure. Each time your system reboots, the old history database is closed
and a new one is created. If you choose to do this, you should put the command
before the execution of EPC$STARTUP so that no history data is lost. For
example:
$ COLLECT SET HISTORY/NEW FILE
$ PURGE/NOLOG/NOCONFIRM/KEEP=2 SYS$SYSDEVICE: [EPC.DATABASESJEPC$HISTORY DB.ROB
$ @SYS$STARTUP:EPC$STARTUP
-

The DECtrace Registrar process binds to the history database once when it is
first created, and unbinds when you issue either the STOP SYSTEM or the
SET HISTORY/NEW_FILE command. The modify date of the history database
is updated only when the Registrar unbinds. Because of this, incremental
backups of your disks may not copy the history database (or the DECtrace
administration database).
The solution is to create a new history database prior to performing your
incremental backups. Alternately, you could perform an RdbNMS online
backup using the RMU/BACKUP/ONLINE command.

9 .5 Disabling Data Collection
You can assign the logical, EPC$DISABLED, to turn off process registration
within the scope of the logical name. To specify the logical name table (which
determines the scope) where you want to enter a logical name, use the
/PROCESS, /JOB, /GROUP, /SYSTEM, or /TABLE qualifier. For example, the
following command disables all process registrations in your UIC group:
$ASSIGN/GROUP EPC$DISABLED EPC$DISABLED

See the ASSIGN command in the VMS DCL Dictionary for more information
about creating logical names.

9-6 System Management Tasks

9 .6 Improving DECtrace Performance
After you install DECtrace, you might want to adjust your system to enhance
performance or lower the use of some system resc;>urces. One recommendation
is to increase process working set parameters to speed up DECtrace formatting
operations and report generations.
Another possible improvement relates to the formatting of large data collection
files into Rdb/VMS databases. The logical name RDMS$BIND_WORK_FILE
lets you specify temporary tables that Rdb/VMS uses on a disk structure other
than the disk that contains the database, thus reducing the disk I/O operation
on the disk where the database resides. The default location is SYS$LOGIN:.
For example:
$ ! Assign the work area to another disk with read-write access
$ DEFINE RDMS$BIND_WORK_FILE WORK$DISK: [ROB.WORK]

9.7 Troubleshooting DECtrace
This section describes some typical problems that you might encounter when
using DECtrace on your system. Table 9-2 shows the symptoms, causes, and
cures of many common problems.
Note that the primary troubleshooting tool is the SHOW IDSTORY command
which displays error or warning messages that occur during data collection.
See Section 3.5.2 for a description of the SHOW IDSTORY command.
Table 9-2

Troubleshooting DECtrace Problems

Symptom

Possible Cause

Solution

Data collection is active
but no data is collected.

No applications contained facilities
that were specified in the facility
selection.

Use SHOW REGISTER to show
all available applications.

Your output disk is full.

Purge old files and spread new
data files across several disks
using the /FILELIST qualifier to
the SCHEDULE COLLECTION
command.

The DECtrace registrar has
stopped.

Restart the registrar process.
See Section 9.2.1.

You are collecting too much data.

Use a collection class to limit
the amount of data collected.
See Section 2.1.

Output disks fill up too
quickly.

(continued on next page)

System Management Tasks 9-7

Table 9-2 (Cont.)

Troubleshooting DECtrace Problems

Symptom

You cannot delete
facility definitions or
facility selections or you
cannot cancel collections.

Collections only run
on the local node (in a
cluster environment).

Possible Cause

Solution

Insufficient disk space to begin
with.

Spread data files over several
disks using the /FILELIST
qualifier to the SCHEDULE
COLLECTION command.

History database has grown too
large.

Start a new history database
with the SET HISTORY/NEW_
FILE command and offioad the
old version.

You are not the creator of the
specified definition, selection or
collection.

You must have VMS BYPASS
OR SYSPRV privilege to delete
other users' definitions or
selections.

You cannot delete a facility
definition that is referenced by
a facility selection.

You must delete any facility
selections that reference the
facility definition.

You cannot delete a selection
that is referenced by an active or
pendin1~ collection.

You must cancel any active
or pending collections that
reference the facility selection.

You did not specify /CLUSTER on
the SCHEDULE COLLECTION
command.

Schedule a cluster-wide
collection. See Section 3.2.2.

DECtrace is not running on the
rest of the nodes in the cluster.

You must start DECtrace on
every node in the cluster. See
Section 9.2.1.

The EPC$ADMIN_DB and
EPC$HISTORY_DB logicals do
not reference the same databases
on all nodes in the cluster.

Reinstall DECtrace. When
prompted for EPC$ROOT,
specify a directory that is
common across all nodes in
the cluster.
(continued on next page)

9-8 System Management Tasks

Table 9-2 (Cont.)

Troubleshooting DECtrace Problems

Symptom

Possible Cause

Solution

Elapsed time information for duration events
is negative.

The system time was changed
during the execution of the event.

Reschedule data collection and
do not change system time
during active collections.

The start event and end event
service routines are switched in
your facility.

Move the EPC$START_EVENT
and EPC$END_EVENT service
routine calls to their proper
location and recompile your
program.

The RdbNMS monitor process is
not running.

Use the VMS STOP/ID command to stop the EPC$REGISTRAR
process. See Section 9.2.2.

You cannot stop the
D ECtrace registrar
process (the STOP
SYSTEM command
fails).

9. 7. 1 Error Messages and Recovery Procedures
The file SYS$HELP:EPC$MSG.DOC contains a listing of a subset of the
DECtrace error messages, with explanations and user actions. The messages
are arranged in alphabetical order by error code. You can use a text editor or
the DCL SEARCH command to locate specific error codes or text strings.
Within the DECtrace command environment, you can use the HELP command
to display the explanation and user action associated with an error message.
For example, the following command displays information about the error code
FACCRE_NOEVTOPTS:
DECtrace>

HELP ERROR FACCRE NOEVTOPTS

Error_Messages_and_Recovery
FACCRE NOEVTOPTS
Must specify list of events or event options
Explanation: User attempted to create a facility definition
which did not contain any events.
User Action: You must specify at least one event when creating
a facility definition.

System Management Tasks 9-9

Note that an error encountered by a process which has registered with
DECtrace is not related to any collection for which the process might be
recording event data. If you use the COLLECTION-NAME parameter to the
SHOW HISTORY command, you will not see errors or messages generated by
the individual processes. For example, if a process is unable to record data
due to a file protection violation on the data collection file, the message will be
on the SHOW HISTORY /FORMAT=ALL report, not the report for a specific
collection.

9-10 System Management Tasks

A
Formatted Database and File Layouts
The DECtrace formatter component formats the DECtrace data collection files
(DCFs) into either an RdbNMS databasP- or a VAX RMS file. The formatted
RdbNMS database or VAX RMS file can then be used for reporting and
analyzing.

A. 1 The Rdb/VMS Database
You can use the DECtrace formatter to merge, format, and store the event data
collected from multiple collections that reference the same facility selection
into an RdbNMS database.
Only collections of identically defined selections can be merged into a single
database. Identically defined selections have identical data for the following
fields:
• For the EPC$SELECTION relation-all fields except SELECTION_
RECORD_ID (SELECTION_NAME and SELECTION_COMMENT)
• For the EPC$FACILITY relation-all fields except SELECTION_RECORD_
ID (FACILITY_NUMBER, FACILITY_NAME, FACILITY_VERSION,
FACILITY_DEFINITION_TIME, and. COLLECTION_CLASS)
• For the EPC$EVENT relation-all fo~lds except SELECTION_RECORD_
ID and RELATION_NAME (FACILI'J.'Y_NUMBER, EVENT_NUMBER,
EVENT_NAME, EVENT_HEADER, EVENT_TYPE, and ITEM_FLAGS)
• For the EPC$ITEM relation-all fields except SELECTION_RECORD_ID
(FACILITY_NUMBER, ITEM_NUMBER, ITEM_NAME, ITEM_HEADER,
ITEM_TYPE, ITEM_WIDTH, ITEM_MAX_SIZE, ITEM_USAGE, and
ITEM_CHARACTERISTICS)

Formatted Database and File Layouts A-1

• For the EPC$EVENT_ITEM relation-all fields except SELECTION_
RECORD_ID (FACILITY_NUMBER, EVENT_NUMBER, ITEM_NUMBER,
ITEM_POSITION, ITEM_USAGE_POINT, ITEM_USAGE_START, and
ITEM_USAGE_END)
This version of the DECtrace formatter will only format and merge Version
1.0-0 of the DECtrace data collection file. The DCF_VERSION field within
the data collection file should have the value ''Vl.0-0". It will only merge the
data into an RdbNMS database created by Version 1.0-0 of the DECtrace
formatter. The FORMAT_VERSION field of the EPC$IDENT relation in the
RdbNMS database should also have the value "Vl.0-0". Moreover, it will only
merge those DCFs that have not been merged. When a DCF is merged, the
information that uniquely identifies the file is stored in the EPC$DCF relation.
The DECtrace formatter skips a DCF that is not mergeable.

A. 1. 1 The Data Types
Table A-1 shows the data types that are used in RdbNMS to represent the
DECtrace-supported data types.
Table A-1

Rdb/VMS Representations of DECtrace-Supported Data Types

DECtrace-Supported Data Type

Rdb/VMS Data Type

BYTE
WORD

SMALLINT
SMALLINT

LONGWORD

INTEGER

QUADWORD

ASCIC

VARCHAR of up to 255 characters

ASCIW

VARCHAR of up to 16383 characters

FIXED_ASCIC

VARCHAR of up to 255 characters

There are two types of relations in the database for storing two types of data:
1

Control information-collection information, facility information

Collected event data

The following sections describe in detail the relations in the database. Field
names in bold signify key fields. Field names in italic signify foreign key
fields.
Note Some of the relations described here may be views that are defined over other

base relations. The format of these base relations may change over time for
improvements in performance and I or space utilization of the database. The

A-2 Formatted Database and File Layouts

names and formats of the relations I views and fields described here, however,
are unlikely to change.

A. 1.2 String Data Segmentation
A form of string segmentation has been implemented to improve formatting
performance as well as save storage space. It applies to all data items of type
FIXED_ASCIC, ASCIC or ASCIW in all event data relations.
All collected string data of type FIXED_ASCIC, ASCIC, or ASCIW are stored in
multiple segments, except when the entire string is small enough to fit in the
first segment. Usually, the first segment of a string datum is stored in the base
event data relation, while additional segments are stored in a separate relation
for segmented strings only. There is one segmented-string relation for each
base event data relation that has at least one data item of type FIXED_ASCIC,
ASCIC, or ASCIW, in the event data relation. The storage space for the first
segment could be specified to be of size zero, in which case all string segments
for this data field are stored in the segmented-string relation.
All segments of a single datum are inter-related through a string ID that is
unique within an event data relation. For every collected data item of type
FIXED_ASCIC, ASCIC, or ASCIW, there is an additional field in the same
event data relation for the string ID. The name of this additional field is
<item_name>_STR_ID. For example, WHERE_BLOCK_STR_ID is the field for
the string IDs of the data for data item WHERE_BLOCK of a point event, and
WHERE_BLOCK_END_STR_ID is the field for the string IDs of the end data
of a duration event. A value of 0 (zero) in this field indicates that there is only
one string segment: the first, for a datum.
EPC$1_40_REQUEST is an example of an event data relation where two of
the data item, ARGUMENT_LIST and WHERE_BLOCK, are of the ASCIW
type, and one item, TARGET_DBKEY, is of the ASCIC type. Therefore, three
additional fields, with a domain of STR_ID_DOMAIN (type INTEGER), are
also created for the string IDs of these data fields. Table A-2 describes the
fields in these relations.
Table A-2

The point event relation EPC$1_40_REQUEST

Field name

RdbNMS Data Type

COMP_STATUS

INTEGER

CODE_QUADWORD

QUADWORD

ARGUMENT_LIST

VARCHAR(x)

ARGUMENT_LIST_STR_ID

INTEGER
(continued on next page)

Formatted Database and Fiie Layouts A-3

Table A-2 (Cont.)

The point event relation EPC$1_40_REQUEST

Field name

RdbNMS Data Type

WHERE_BLOCK

VARCHAR(y)

WHERE_BLOCK_STR_ID

INTEGER

TARGET_DBKEY

VARCHAR(z)

TARGET_DBKEY_STR_ID

INTEGER

Segmented-string relations are named <event_data_relation_name>_ST, and
have three fields. Table A-3 describes the fields in these relations.
Table A-3

A relation for segmented strings

Field name

Rdb/VMS Data Type

Description

STR_ID

INTEGER

The string ID of the datum.

SEGMENT_NUMBER

SMALLINT

Segment sequence number,
starts with 1.

STR_SEGMENT

VARCHAR(n)

String segment.

One index will be created for each of these relations, on the STR_ID field. The
index will be named the same as the relation itself.
Two data fields in two of the DECtrace system relations indicate the segment
sizes of the segmented strings:
The ITEM_FIRST_SEGMENT_SIZE field, of domain ITEM_FIRST_
SEGMENT_SIZE_DOMAIN, a SMALLINT, in the EPC$EVENT_ITEM
relation, indicates the storage size for the first string segment of the data
item in the base event data relation.
2

SEGMENT_SIZE, of domain EVENT_SEGMENT_SIZE_DOMAIN, a
SMALLINT, in the EPC$EVENT relation, indicates the segment size of
all the additional string segments in the segmented-string relation for the
event.

A. 1.3

Relations for the Control Information

There are 13 relations that hold control information: EPC$IDENT,
EPC$SELECTION, EPC$COLLECTION, EPC$DCF, EPC$REG_PROCESS,
EPC$FACILITY, EPC$EVENT, EPC$ITEM, EPC$EVENT_ITEM,
EPC$PROCESS, EPC$IMAGE, EPC$DCF_IMAGE, and
EPC$FACILITY_IMAGE.

A-4 Formatted Database and Fiie Layouts

A.1.3. 1 The EPC$1DENT Relation The EPC$IDENT relation holds
information of the DECtrace collector that collected the data.

The IDENT_RECORD_ID field is a formatter-introduced field used as the
key field and is indexed. Table A-4 describes the fields in the EPC$IDENT
relation.
Table A-4

EPC$1DENT Relation

Field Name

Data Type/Size

Description

IDENT_RECORD_ID

Signed word

The EPC$IDENT record
identifier.

PRODUCT_VERSION

Varying string, 10 bytes

The DECtrace product version
string.

DCF_VERSION

Varying string, 10 bytes

The data collection :file version
string.

FORMAT_VERSION

Varying string, 10 bytes

The formatted database
version string.

The EPC$SELECTION Relation The EPC$SELECTION relation holds
the facility selection definition information.

A.1.3.2

The SELECTION_RECORD_ID field is a formatter-introduced field used
as the key field and is indexed. Table A-5 describes the fields in the
EPC$SELECTION relation.
TableA-5

EPC$SELECTION Relation

Field Name

Data Type/Size

Description

SELECTION_RECORD_ID

Signed word

The EPC$SELECTION
record identifier. Range: 1
to 999 inclusive.

SELECTION_NAME

Varying string, 32 bytes

The selection name.

SELECTION_COMMENT

Varying string, 80 bytes

The comment for the
selection.

A. 1.3.3

The EPC$COLLECTION Relation

The EPC$COLLECTION relation

holds the collection information.
The COLLECTION_RECORD_ID field is a formatter-introduced field used as
the key field and is indexed. The SELECTION_RECORD_ID field serves as a
foreign key from relation EPC$SELECTION. Table A-6 describes the fields in
the EPC$COLLECTION relation.

Formatted Database and Fiie Layouts A-5

TableA-6

EPC$COLLECTION Relation

Field Name

Data Type/Size

Description

COUECTION_RECORD_ID

Signed word

The EPC$COLLECTION
record identifier.

COLLECTION_NAME

Varying string,
32 bytes

The collection name.

START_TIME

Date

The collection start time.

END_TIME

Date

The collection end time.

SELECTIONJl,ECORD_ID

Signed word

The EPC$SELECTION
record identifier.

A.1.3.4

The EPC$DCF Relation

The EPC$DCF relation holds the data

collection file information.
The DCF_RECORD_ID field is a formatter-introduced field used as the key
field and is indexed. The COLLECTION_RECORD_ID field serves as a foreign
key from relation EPC$COLLECTION. Table A-7 describes the fields in the
EPC$DCFzex relation.
TableA-7

EPC$DCF Relation

Field Name

Data Type/Size

Description

DCF_RECORD_ID

Signed word

The EPC$DCF record identifier.

SYSTEM_ID

Integer, 6 bytes

The system identification of
the node, obtain with an
SYS$GETSYI call, specifying
SYI$_NODE_SYSTEMID.

ACTIVATION_TIME

Date

Collection activation time.

TOTAL_FILES

Signed word

The total number of DCFs from
the collection.

FILE_NUMBER

Signed word

The file number of this DCF.

FILE_NAME

Varying string,
255 bytes

The file name of this DCF.

COLLECTION_RECORD_ID

Signed word

The EPC$COLLECTION record
identifier.

A-6 Formatted Database and Fiie Layouts

A.1.3.5 The EPC$REG Relation The EPC$REG relation holds the
registration identification information.

The COLLECTION_RECORD_ID field serves as a foreign key from relation
EPC$COLLECTION.
.
Table A-8 describes the fields in the EPC$REG relation.
Table A-8

EPC$REG Relation

Field Name

Data Type/Size

Description

COLLECTION_RECORD_ID

Signed word

The EPC$COLLECTION
record identifier.

REG_ID

Varying string,
255 bytes

The registration ID.

A.1.3.6

The EPC$FACILITY Relation

The EPC$FACILITY relation holds the

facility definition information.
The SELECTION_RECORD_ID and FACILITY_NUMBER together form the
key field and are indexed. The SELECTION_RECORD_ID field also serves as
a foreign key from relation EPC$SELECTION. Table A-9 describes the fields
in the EPC$FACILITY relation.
Table A-9

EPC$FACILITY Relation

Field Name

Data Type/Size

Description

SELECTION_RECORD_ID

Signed word

The EPC$SELECTION
record identifier.

FACILITY_NUMBER

Signed word

The facility number.

FACILITY_NAME

Varying string,
27 bytes

The facility name.

FACILITY_VERSION

Varying string,
10 bytes

The facility version.

FACILITY_DEFINITION_TIME

Date

Facility definition creation
date.

COLLECTION_CLASS

Varying string,
32 bytes

The collection class name.

Formatted Database and File Layouts

A-7

A. 1.3.7

The EPC$EVENT relation holds the event

The EPC$EVENT Relation

information for a facility.
The SELECTION_RECORD_Ip, FACILITY_NUMBER and EVENT_
NUMBER together form the key field for this relation and are indexed.
The SELECTION_RECORD_ID field also serves as a foreign key from relation
EPC$SELECTION. The FACILITY_NUMBER field also serves as a foreign
key from relation EPC$FACILITY. Table A-10 describes the fields in the
EPC$EVENT Relation.
TableA-10

EPC$EVENT Relation

Field Name

Data Type/Size

Description

SELECTION_RECORD_ID

Signed word

The EPC$SELECTION record identifier.

FACIUTY_NUMBER

Signed word

The facility each event is associated with.

EVENT_NUMBER

Signed word

The event number for this event.

EVENT_NAME

Varying string,
15 bytes

Na.me describing the event.

EVENT_HEADER

Varying string,
15 bytes

The header used in reports.

EVENT_TYPE

Signed word

The event type. Possible values follow:
•

EPC$K_EVENT_TYPE_POINT(81)Indicates a point event type.

•

EPC$K_EVENT_TYPE_
DURATION(84)-lndicates a duration
event type.

ITEM_FLAGS

Bit array,
16 bytes

The item flags for the event.

SEGMENT_SIZE

Signed word

Size of the segmented string..

RELATION_NAME

Varying string,
28 bytes

The name of the relation that holds the
captured data for this event.

A. 1.3.8

The EPC$1TEM Relation

The EPC$ITEM relation holds the item

information for a facility.
The SELECTION_RECORD_ID, FACILITY_NUMBER, and ITEM_
NUMBER together form the key field for this relation and are indexed.
The SELECTION_RECORD_ID field also serves as a foreign key from relation
EPC$SELECTION. The FACILITY_NUMBER field also serves as a foreign
key from relation EPC$FACILITY. Table A-11 describes the fields in the
EPC$ITEM relation.

A-8

Formatted Database and File Layouts

Table A-11

EPC$1TEM Relation

Field Name

Data Type/Size

Description

SELECTION_RECORD_ID

Signed word

The EPC$SELECTION record identifier.

FACILITY_NUMBER

Signed word

The facility each it.em is associated with.

ITEM_NUMBER

Signed word

The item number for this event.

ITEM_NAME

Varying string,

Name describing the item.

15 bytes
ITEM_HEADER

Varying string,
15 bytes

The column header used in reports.

ITEM_TYPE

Signed word

The data type of the item.

ITEM_RADIX

Signed word

The radix of the item.

ITEM_WIDTH

Signed word

The column width used in reports.

ITE¥_MAX_SIZE

Signed word

The m.aDmum size of the item.

ITEM_USAGE

Signed word

Usage of the item. Possible values follow:
•

EPC$K_ITM_U_LEVEL(l}-Indicates
the item is a level. A level is a meter or
gauge that indicates the "CURRENT''
value of some metric. Its value may go
up & down.

•

EPC$K_ITM_U_COUNTER(2}Indicates the item is a counter. A
counter indicat.es the number of times
something occurred. Its value increases
over time.

•

EPC$K_ITM_U_PERCENT(3}Indicates the item is a percentage.
A percentage is a type of level.

•

EPC$K_ITM_U_TEXT(4}-lndicates
the item is text.

•

EPC$K_ITM_U_PRIVATE(5}Indicates the item is for private use
by the facility.

(continued on next page)

Formatted Database and File Layouts A-9

Table A-11 (Cont.)

EPC$1TEM Relation

Field Name

Data Type/Size

Description

ITEM_CHARACTERISTICS

Signed longword

Item value characteristics. Possible values
follow:
•

EPC$K_ITM_CHR_PRINT(l}Printable item value.

EPC$K_ITM_CHR_NONPRINT(2}Non-printable item value.

A.1.3.9 The EPC$EVENT_ITEM Record The EPC$EVENT_ITEM relation
holds the relationship information between the events and items of a facility.

The SELECTION_RECORD_ID, FACILITY_NUMBER, EVENT_NUMBER,
and ITEM_NUMBER together form the key field for this relation and are
indexed. The SELECTION_RECORD_ID field also serves as a foreign key from
relation EPC$SELECTION. The FACILITY_NUMBER field also serves as a
foreign key from relation EPC$FACILITY. The EVENT_NUMBER field also
serves as a foreign key from relation EPC$EVENT. The ITEM_NUMBER field
also serves as a foreign key from relation EPC$ITEM. Table A-12 describes the
fields in the EPC$EVENT relation.
TableA-12

EPC$EVENT_ITEM Relation

Field Name

Data Type/Size

Description

SELECTION_RECORDJD

Signed word

The EPC$SELECTION record
identifier.

FACIUTY_NUMBER

Signed word

The facility each event-item pair is
associated with.

EVENT_NUMBER

Signed word

The event number of the event-item
pair.

ITEM_NUMBER

Signed word

The item number of the event-item
pair.

ITEM_POSITION

Signed word

The item position in the event record.

(continued on next page)

A-10 Formatted Database and File Layouts

Table A-12 (Cont.)

EPC$EVENT_ITEM Relation

Field Name

Data Type/Size

Description

ITEM_FIRST_SEGMENT_SIZE

Signed word

The size the :first segment of the
segmented string.

ITEM_USAGE_START

Signed word

A value of one indicates that this data
item will be collected in a START
event, for the above event number. A
value of zero indicates otherwise.

ITEM_USAGE_END

Signed word

A value of one indicates that this
data item will be collected in an END
event, for the above event number. A
value of zero indicates otherwise.

A.1.3. 10

The EPC$PROCESS Relation

The EPC$PROCESS relation holds

the process information.
The PROCESS_RECORD_ID field is a formatter-introduced field used
as the key field and is indexed. The NODE field is also indexed. The
IDENT_RECORD_ID field serve as a foreign key from relation EPC$IDENT.
Table A-13 describes the fields in the EPC$PROCESS relation.
Table A-13

EPC$PROCESS Relation

Field Name

Data Type/Size

Description

PROCESS_RECORD_ID

Signed word

The EPC$PROCESS record
identifier.

EPID

Signed longword

The extended process identity
number.

USERNAME

Varying string,
12 bytes

The username of the process.

ACCOUNT

Varying string,
8 bytes

The process account name.

UIC

Signed longword

The process user identification.

PROCESS_NAME

Varying string,
15 bytes

The process name.

CREATION_TIME

Date

Process creation time.

BASE_PRIORITY

Signed longword

The base priority of the process.

PROCESS_MODE

Signed longword

The process mode.
(continued on next page)

Formatted Database and File Layouts A-11

Table A-13 (Cont.)

EPC$PROCESS Relation

Field Name

Data Type/Size

Description

SYSTEM_ID

Integer, 6 bytes

The system identification of
the node, obtained with a
SYS$GETSYI call, specifying
SYI$_NODE_SYSTEMID.

NODE_NAME

Varying string, up
to 404 bytes

The full DECNET node name, obtained with a SYS$GETSYI call,
specifying SYI$_NODENAME.

NODE

Varying string, up
to 64 bytes

The abbreviated version of the
above DECNET node name.

CPU_TYPE

Varying string,
31 bytes

The CPU type, obtained with
a SYS$GETSYI call, specifying
SYI$_HW_NAME.

VMS_VERSION

Varying string,
8 bytes

The VMS version, obtained with
a SYS$GETSYI call, specifying
SY!$_VERSION.

BOOT_TIME

Date

The boot time of the node, result
of a SYS$GETSYI call when
specifying SYI$_BOOTTIME.

IDENT_RECORD_ID

Signed word

The EPC$IDENT record
identifier.

A. 1.3.11

The EPC$1MAGE Relation

The EPC$IMAGE relation holds the

image information.
The IMAGE_RECORD_ID field is a formatter-introduced field used as the key
field and is indexed. The PROCESS_RECORD_ID field serves as a foreign
key from relation EPC$PROCESS. Table A-14 describes the fields in the
EPC$IMAGE relation.
TableA-14

EPC$1MAGE Relation

Field Name

Data Type /Size

Description

IMAGE_RECORD_ID

Signed longword

The EPC$IMAGE record identifier.

IMAGE_NAME

Varying string,
255 bytes

The full file specification of the
image.

ACTIVATION_TIME

Date

Image activation time.
(continued on next page)

A-12

Formatted Database and File Layouts

Table A-14 (Cont.)

EPC$1MAGE Relation

Field Name

Data Type/Size

Description

LINK_TIME

Date

Image link time.

IMAGE_ID

Varying string,
15 bytes

The image identity number.

PROCESS_RECORD_ID

Signed word

The EPC$PROCESS record
identifier.

The EPC$DCF_IMAGE Relation The EPC$DCF_IMAGE relation
captures the relationship information between data collection files and
execution images.

A. 1.3. 12

The DCF_RECORD_ID and IMAGE_RECORD_ID together form the key field
for this relation and are indexed. The DCF_RECORD_ID field also serves as
a foreign key from relation EPC$DCF. The IMAGE_RECORD_ID field also
serves as a foreign key from relation EPC$IMAGE. Table A-15 describes the
fields in the EPC$DCF_IMAGE relation.
Table A-15

EPC$DCF_IMAGE Relation

Field Name

Data Type/Size

Description

DCF_RECORD_ID

Signed word

The EPC$DCF record identifier.

IMAGE_RECORD_ID

Signed longword

The EPC$IMAGE record identifier.

A. 1.3. 13 The EPC$FACILITY_IMAGE Relation The EPC$FACILITY_IMAGE
relation holds the relationship information between facilities and execution
images.

The SELECTION_RECORD_ID, FACILITY_NUMBER, and IMAGE_RECORD_
ID together form the key field for this relation and are indexed. The
SELECTION_RECORD_ID field also serves as a foreign key from relation
EPC$SELECTION. The FACILITY_NUMBER field also serves as a foreign key
from relation EPC$FACILITY. The IMAGE_RECORD_ID field also serves as a
foreign key from relation EPC$IMAGE. Table A-16 describes the fields in the
EPC$FACILITY_IMAGE relation.

Formatted Database and File Layouts A-13

TableA-16

EPC$FACILITY_IMAGE Relation

Field Name

Data Type/Size

Description

SELECTION_RECORD_ID

Signed word

The EPC$SELECTION
record identifier.

FACILITY_NUMBER

Signed word

The facility number.

FACILITY_VERSION
IMAGE_RECORD_ID

Varying string, 10 bytes

The facility version.

Signed longword

The EPC$IMAGE record
identifier.

REG_ID

Varying string,
255 bytes

The facility registration ID.

A. 1.4 Relations for the Collected Data
A relation for the data collected for an event is created only if data has been
collected for that event. The name for an event data relation is:
EPC$<SELECTION_RECORD_ID>_<FACILITY_NUMBER>_<EVENT_
NAME>.
For a point event data relation, the item name of an item is used as the column
name in the relation.
For a duration event data relation, the suffixes _START and _END are added
to the item names for items that are collected at event start time and event
end time respectively.
For example, an item named MEMORY_USAGE will have a column name
MEMORY_USAGE in a point event data relation. A similar item will have a
column name MEMORY_USAGE_START for item data collected at event start
time. A similar item will have a column name MEMORY_USAGE_END for
item data collected at event end time.
In addition to facility-defined events and process items, all event relations will
also include the fields described in Table A-17.

A-14 Formatted Database and Fiie Layouts

Table A-17

Event Relation Fields

Field Name

Data Type/Size

Description

COLLECTION_RECORD_ID

Signed word

The EPC$COLLECTION record
identifier, a foreign key.

IMAGE_RECORD_ID

Signed longword

The EPC$IMAGE record
identifier, a foreign key.

CONTEXT_NUMBER

Signed longword

The context number.

TIMESTAMP_POINT

Date

Point event logged time, for
point events only.

TIMESTAMP_START

Date

Duration event start time, for
duration events only.

TIMESTAMP_END

Date

Duration event end time, for
duration events only.

A. 1.5 The Entity Relationship Diagram for the Database
Figure A-1 shows the ER diagram for the formatted database.

A. 1.6 The Predefined Views
To facilitate data retrieval, the following views are predefined:
A. 1.6. 1 Relating Collection Information with Event Data A view is defined
for each event relation to relate collection information to the events:
CREATE VIEW <Event RELATION NAME> C
AS
SELECT *
FROM
<Event RELATION NAME>, EPC$COLLECTION
WHERE <Event RELATION NAME>.COLLECTION RECORD ID =
EPC$COLLECTION.COLLECTION_RECORD_ID

A. 1.6.2 Relating Selection and Collection Information with Event Data
A view is defined for each event relation to relate selection and collection
information to the events:
CREATE VIEW <Event RELATION NAME> SC
AS
SELECT *
FROM
<Event RELATION_NAME>, EPC$COLLECTION, EPC$SELECTION
WHERE <Event RELATION NAME>.COLLECTION RECORD ID =
EPC$COLLECTION.COLLECTION ·RECORD-ID
AND EPC$COLLECTION.SELECTION_RECORD_ID = EPC$SELECTION.SELECTION_RECORD_ID

Formatted Database and File Layouts A-15

Figure A-1

The Entity Relationship Diagram for the Database
EPC$1DENT
O:M

1:1

EPC$REG

EPC$DCF
O:M

1:1

1 :1

1:M

EPC$PROCESS
1:M

1 :1

EPC$1MAGE

EPC$COLLECTION

1:M

1:1

Data Relations

1 :1

1:M

EPC$FACILITY
O:M

EPC$1TEM

EPC$EVENT
EPC$EVENT_ITEM

NU-2054A-RA

A.1.6.3 Relating Image Information with Event Data A view is defined for
each event relation to relate image information to the events:
CREATE VIEW <Event RELATION NAME> I
AS
SELECT *
FROM
<Event RELATION NAME>, EPC$IMAGE
WHERE <Event RELATION=NAME>.IMAGE_RECORD_ID = EPC$IMAGE.IMAGE_RECORD_ID

A-16 Formatted Database and File Layouts

A. 1.6.4 Relating Process and Image Information with Event Data A view is
defined for each event relation to relate process and image information to the
events:
CREATE VIEW <Event RELATION NAME> PI
AS
SELECT *
FROM
<Event RELATION NAME>, EPC$IMAGE, EPC$PROCESS
WHERE <Event RELATION-NAME>.IMAGE RECORD ID = EPC$IMAGE.IMAGE RECORD ID
AND EPC$IMAGE.PROCESS_RECORD_ID-= EPC$PROCESS.PROCESS_RECORD_ID
-

A. 1. 7 Limitations
Due to the range limitation placed on SELECTION_RECORD_ID and the sizes
of COLLECTION_RECORD_ID, IDENT_RECORD_ID, PROCESS_RECORD_
ID, and IMAGE_RECORD_ID, the maximum numbers of unique record
that can be stored in EPC$SELECTION, EPC$COLLECTION, EPC$DCF,
EPC$IDENT, EPC$PROCESS, and EPC$IMAGE relations are 999, 32768,
32768, 32768, 32768, and 214 748364 7 respectively.

A.2 The VAX RMS File Format
This section describes the formatted VAX RMS file created by DECtrace when
you specify the ITYPE=RMS qualifier to the FORMAT command.
The DECtrace formatter component merges, formats, and stores the event
data collected from multiple collections of the same facility selection into a
formatted VAX RMS file. Formatted VAX RMS files are sequential files with
variable length records. Maximum size of a record is 32,765 bytes. This is the
maximum record size for a VAX RMS sequential file written to disk.
Only collections with identical facility selections can be merged into a single
VAX RMS file. Identically defined selections have the same data for the
following fields:
•

For the COLLECTION record-SELECTION NAME and SELECTION
COMMENT

•

For the FACILITY record-FACILITY NUMBER, FACILITY NAME,
FACILITY VERSION, FACILITY DEFINITION TIME, and COLLECTION
CLASS

•

For the EVENT record-FACILITY NUMBER, EVENT NUMBER, EVENT
NAME, EVENT HEADER, EVENT TYPE, RESOURCE ITEM FLAGS, and
everything in each COLLECTION ITEM DESCRIPTOR

This version of the DECtrace formatter will only format and merge Version
1.0-0 of the DECtrace data collection file. The DCF_VERSION field within the
data collection file should have the value ''Vl.0-0". It only merges the data
into a VAX RMS file created by Version 1.0-0 of the DECtrace formatter. The
FORMAT_VERSION field of the IMAGE record in the VAX RMS file should

Formatted Database and File Layouts

A-17

also have the value "Vl.0-0". Moreover, it only merges those DCFs that have
not been merged. When a DCF is merged, the information that uniquely
identifies the file is stored in the dictionary as well as the DCF record. The
DECtrace formatter skips a DCF that is not mergeable.

A.2. 1 Data Types
The following sections describe the data types used in the formatted VAX RMS
file.
A.2. 1. 1 Date A date field contains a time and date in the standard VMS
quadword binary format.
A.2. 1.2 Fixed ASCIC/ ASCIW String A fixed ASCIC string field records the
actual length of the string in the first byte, followed by the actual string itself.
A fixed ASCIW string field records the actual length of the string in the first
word, followed by the actual string itself. The field size is fixed. The content of
the additional space following the actual string is undetermined. For example,
the SELECTION NAME field of the COLLECTION record is a field of 33 bytes
long. The first byte of this field contains a count of the selection name, followed
by the selection name of up to 32 characters. Therefore, for a selection name
that is only five character long, the first byte of this field has a value of five,
followed by the selection name, followed by 27 unused bytes with unpredictable
values in them.

A.2.2

Records Organization

There are ten types of records: seven for control information (FMTDICT,
COLLECTION, FACILITY, DCF, IMAGE, FACILITY-REGISTRATION, and
EVENT records) and three for collected data (POINT, START, and END
records). The first byte of a record contains a literal which indicates the type
of the record. Table A-18 shows the possible record types.
Table A-18

Record Type Literal

Record Type

Literal

FMTDICT
COLLECTION

EPC$K_FMTDICT_REC
EPC$K_COLLECTION_REC

FACILITY
DCF
IMAGE
FACILITY_REGISTRATION

EPC$K_FACILITY_REC
EPC$K_DCF_REC
EPC$K_IMAGE_REC
EPC$K_FACREG_REC
(continued on next page)

A-18 Formatted Database and Fiie Layouts

Table A-18 (Cont.)

Record Type Literal

Record Type

Literal

EVENT

EPC$K_EVENT_REC

POINT

EPC$K_POINT_REC

START

EPC$K_START_REC

END

EPC$K_END_REC

The formatter dictionary record (FMTDICT) contains dictionary information
that is used by the formatter only. Instances of this record may appear
anywhere in a formatted VAX RMS file. This record should simply be ignored
and skipped over by any program that reads the VAX RMS file.
A formatted VAX RMS file consists of one or more collection sections. Each
collection section has a COLLECTION record, followed by one or more
FACILITY records and a collected data section. The appearance of a new
COLLECTION record in a file signifies the end of the last collection section
and the beginning of the next, and the information in the new COLLECTION
record supersedes that of the previous one.
A collected data section is composed of one or more merged data collection files
(DCFs). A DCF record signifies the end of the previous DCF and the beginning
of a new one. Within a collected data section are a number of IMAGE records,
FACILITY-REGISTRATION records, EVENT records, and the Data Collection
records. An IMAGE record that describes an image precedes the data that was
collected from that image. A FACILITY-REGISTRATION record indicates the
registration of a facility through an image. The EPID in this record points
to the last IMAGE record that has the same EPID. An EVENT record that
describes an event precedes the first collected data record for that event. The
last IMAGE record that has an EPID that matches the EPID field of a collected
data record shows the image where the data was collected.
Note that data collected from the same collection may be separated by
collection sections of some other collections, depending on the order in which
the DCFs were merged. In this case, each of the separated parts is a complete
collection section with an identical COLLECTION record, and most likely the
same set of FACILITY and IMAGE records. They would have different DCF
records, however.
A.2.2.1 Control Records
sections.

The control records are described in the following

Formatted Database and File Layouts A-19

A.2.2.1.1

FMTDICT Record

Table A-19 describes the fields in the formatter

dictionary record.
Table A-19

FMTDICT Record

Field Name

Data Type

Bytes

Description

RECORD TYPE

Signed byte

Contains EPC$K_FMTDICT_
REC to indicate that this is a
formatter dictionary record.

DICTIONARY SIZE

Signed longword

The size of the dictionary to
follow.

DICTIONARY

N bytes

A.2.2. 1.2

The formatter dictionary.

COLLECTION Record

Table A-20 describes the fields in the

COLLECTION record.
Table A-20

COLLECTION Record

Field Name

Data Type

Bytes

Description

RECORD TYPE

Signed byte

Contains EPC$K_
COLLECTION_REC to
indicate that this is a
COLLECTION record.

SELECTION NAME

Fixed ASCI C string

The selection name.

SELECTION COMMENT Fixed ASCI C string

The comment for the
selection.

COLLECTION NAME

Fixed ASCIC string

The collection name.

START TIME

Date

The collection start time
and date.

END TIME

Date

The collection end time and
date.

REG ID LIST COUNT

Signed longword

Registration ID list count.

REG ID

Fixed ASCIC string

256

The registration ID.

A.2.2.1.3

FACILITY Record

Table A-21 describes the fields in the FACILITY

record.

A-20 Formatted Database and File Layouts

Table A-21

FACILITY Record

Field Name

Data Type

Bytes

Description

RECORD TYPE

Signed byte

Contains EPC$K_
FACILITY_REC to
indicate that this is a
FACILITY record.

FACILITY NUMBER

Signed word

The facility number.

FACILITY NAME

Fixed ASCIC string

The facility name.

FACILITY VERSION

Fixed ASCIC string

The facility version.

FACILITY DEFINITION
TIME

Date

Facility definition creation
time.

COLLECTION CLASS

Fixed ASCIC string

The collection class name.

A.2.2. 1.4 DCF Record
file record.

Table A-22 describes the fields in the data collection

Table A-22

DCF Record

Field Name

Data Type

Bytes

Description

RECORD TYPE

Signed byte

Contains EPC$K_DCF_REC
to indicate that this is a Data
Collection File information
record.

ACTIVATION TIME

Date

Collection activation time.

SYSTEM ID

Integer

The system identification of
the node, obtained with a
SYS$GETSYI call, specifying
SYI$_NODE_SYSTEMID.

TOTAL FILES

Signed word

The total number of DCFs
from the collection.

FILE NUMBER

Signed word

The :file number of this DCF.

FILE NAME

Fixed ASCI C string

256

The :file name of this DCF.

A.2.2. 1.5
record.

IMAGE Record

Table A-23 describes the fields in the IMAGE

Formatted Database and File Layouts A-21

TableA-23

IMAGE Record

Field Name

Data Type

Bytes

Description

RECORD TYPE

Signed byte

Contains EPC$K_IMAGE_
REC to indicate that this is an
IMAGE record.

PRODUCT VERSION

Fixed ASCIC
string

The DECtrace product version
string.

DCFVERSION

Fixed ASCIC
string

The data collection file version
string.

FORMAT VERSION

Fixed ASCIC
string

The formatted VAX RMS file
version string.

EPID

Signed
longword

The extended process identity
number.

UIC

Signed
longword

The process user identification.

ACCOUNT

Fixed ASCIC
string

The process account name.

USERNAME

Fixed ASCIC
string

The username of the process.

PROCESS NAME

Fixed ASCIC
string

The process name.

PROCESS CREATION
TIME

Date

Process creation time.

BASE PRIORITY

Signed
longword

The base priority of the
process.

PROCESS MODE

Signed
longword

The process mode.

SYSTEM ID

Integer

The system identification of
the node, obtained with a
SYS$GETSYI call, specifying
SYI$_NODE_SYSTEMID.

NODE NAME

Fixed ASCIW
string

406

The DECNET node name,
obtained with a SYS$GETSYI
call, specifying SYI$_
NODENAME.

CPU TYPE

Fixed ASCIC
string

The CPU type, obtained with
a SYS$GETSYI call, specifying
SYI$_HW_NAME.
(continued on next page)

A-22 Formatted Database and File Layouts

Table A-23 (Cont.)

IMAGE Record

Field Name

Data Type

Bytes

Description

VMS VERSION

Fixed ASCIC
string

The VMS version, obtained
with a SYS$GETSY1 call,
specifying SY1$_VERSION.

SYSTEM BOOT TIME

Date

The time the node was booted,
result of an SYS$GETSYI
call when specifying SYI$_
BOO'ITIME.

IMAGE LINK TIME

Date

The time when this image was
linked.

IMAGE ID

Fixed ASCIC
string

The image identity number.

IMAGENAME

Fixed ASCIC
string

256

The full file specification of the
image.

IMAGE ACTIVATION
TIME

Date

Image activation time.

A.2.2. 1.6

FACILITY-REGISTRATION Record

Table A-24 describes the fields in

the FACILITY-REGISTRATION record.
Table A-24

FACILITY-REGISTRATION Record

Field Name

Data Type

Bytes

Description

RECORD TYPE

Signed byte

Contains EPC$K_FACREG_
REC to indicate that this is an
IMAGE record.

EPID

Signed
longword

The extended process identity
number.

FACILITY NUMBER

Signed word

The facility number.

FACILITY VERSION

Fixed ASCIC
string

The facility version.

REG ID

Fixed ASCIC
string

256

The registration ID.

Formatted Database and File Layouts

A-23

A.2.2. 1.7
record.

EVENT Record

Table A-25

Event Record Description

Field Name

Data Type

Bytes

Description

RECORD TYPE

Signed byte

Contains EPC$K_EVENT_REC to
indicate that this is an EVENT record.

FACILITY NUMBER

Signed word

The facility each event is associated with.

EVENT NUMBER

Signed byte

The event number for this event.

EVENTNAME

Fixed ASCIC
string

Name describing the event.

EVENT HEADER

Fixed ASCIC
string

The column header used in reports.

EVENT TYPE

Signed byte

The event type. Possible values are:

ITEM DESCRIPTOR
LIST COUNT

Signed
longword

ITEM DESCRIPTOR
LIST

44n bytes

A.2.2. 1.8 Item Descriptor
descriptor record.

A-24

Table A-25 describes the fields in the EVENT

•

EPC$K_EVENT_TYPE_POINT(81)Indicates a point event type.

•

EPC$K_EVEN•t_TYPE_START(82)Indicates a duration event type,
with start items in the ITEM
DESCRIPTOR LIST.

•

EPC$K_EVENT_TYPE_END(83)Indicates a duration event type,
with end items in the ITEM
DESCRIPTOR LIST.

Item descriptor list count.
A list of item descriptor structures. See
Section A.2.2.1.8.

Table A-26 describes the fields in the item

Formatted Database and File Layouts

TableA-26

Item Descriptor

Field Name

Data Type

Bytes

Description

ITEM NUMBER

Signed byte

The item number for this item.

ITEMNAME

FixedASCIC
string

Name describing the item.

ITEM HEADER

FixedASCIC
string

The column header used in reports.

ITEM TYPE

Signed word

The data type of the item.

ITEM WIDTH

Signed word

The column width used in reports.

ITEM MAX SIZE

Signed word

The maximum size of the item.

ITEM USAGE

Signed byte

Usage of the item. Possible values follow:
EPC$K_ITM_U_LEVEL(l)• Indicates
the item is a level. A level
is a meter or gauge that indicates
the "CURRENT'' value of some
metric. I ts value may go up and
down.
EPC$K_ITM_U _COUNTER(2)• Indicates
the item is a counter. A
counter indicates the number of
times something occurred. Its value
is ever increasing.
EPC$K_ITM_U _PERCENT(3)• Indicates
the item is a percentage.
A percentage is a type of level.
U _TEXT( 4)-Indicates
• EPC$K_ITM_
the item is text.
EPC$K_ITM_U_PRNATE(5)• Indicates
the item is for private use·
by the facility.

ITEM CHARACTERISTICS

Signed
longword

Item value characteristics. Possible
values follow:

• EPC$K_ITM_CHR_PRINT(l)Printable item value.
• EPC$K_ITM_CHR_NONPRINT(2)Non-printable item value.

Formatted Database and File Layouts A-25

A.2.2.2 Data Collection Records The data collection records contain a fixed
length portion with fields that point to the image and facility that generated
the data. This is followed by the actual collected data. The optional process
data items appears first, followed by the facility data items in the order the
collection item descriptors appear in each EVENT record. Each data item
occupies only as much space as needed according to the data type: four bytes
for a longword, nine bytes for a ASCIC type with a count of eight in the count
field and so forth.

Table A-27 describes the fields in the data collection record.
TableA-27

Data Collection Record

Field Name

Data Type

Bytes

Description

RECORD TYPE

Signed byte

Contains one of the following to indicate one
of the data collection records:
a
• EPC$K_POINT_REC-Indicates
point data collection record.
a start
• EPC$K_START_REC-Indicates
data collection record.
an end
• EPC$K_END_REC-Indicates
data collection record.

EPID

Signed
longword

The extended process identity number.

TIME

Date

The record log time and date.

FACILITY NUMBER

Signed word

The facility that logged the event.

EVENT NUMBER

Signed byte

The event number of the logged event.

CONTEXT
NUMBER

Signed
longword

Context number.

HANDLE

Signed
longword

Instance handle used to match start and end
records.

COLLECTED DATA

Varied
structure

The collected data.

A-26 Formatted Database and File Layouts

Glossary

administration database

A single VAX RdbNMS database that contains the DECtrace facility definitions,
facility selections, schedule information, and information about the registered and
current VMS processes that are performing data collection on a given system. There
is one DECtrace administration database per system or VAXcluster.
application program

A sequence of instructions and routines, not part of the basic operating system,
designed to serve the specific needs of a user. An application program can be
instrwnented with DECtrace service routine calls. Also referred to as a facility,
especially after the DECtrace calls have been added.
AST

See asynchronous system traps.
asynchronous system traps

A software-simulated interrupt to a user-defined service routine. ASTs enable
a user process to be notified asynchronously, with respect to the process, of the
occurrence of a specific event. Many of the DECtrace service routines use ASTs to
reduce execution time.
collection class

A set (or group) of events and items that can be collected for a facility. Classes for a
facility are specified in the facility definition. Users refer to a class when creating a
facility selection. There can be one or more classes for each facility. Typical classes
include CAPACITY_PLANNING, PERFORMANCE, and WORKLOAD.

Glossary-1

collection interval

See interval
collection name

A 1- to 16-character string that represents the name of a particular collection.
data collection file
A file that contains raw data gathered during data collection. A single data
collection file stores data for one or more VMS processes. The file is created and
written to by the DECtrace service routines.
data collection

The process of collecting data on a system or VAX.cluster. Criteria in the scheduling
of data collection include when to collect data, where to put the output, and which
facility selection to use. Data collection must be scheduled on a system in order
to collect data. Only one data collection can actively collect data at any time on a
given node.
data formatting

Organizing collected data into a VAX Rdb/VMS database or a formatted VAX RMS
file. Collected data must be formatted before DECtrace can generate reports based
on it.
data merging

Combining several data files into a single formatted database during data
formatting.
DECtrace service routines

See service routines
duration event

See event
end event

The end of a duration event. See event

Glossary-2

event

An occurrence of some activity within a facility. There are two types of events:
duration and point. Duration events have logical beginning and ending points.
Point events occur instantaneously. You can define up to 128 events for each facility.
event flag

A Boolean value corresponding to a particular event for a facility. If an event flag is
set, it indicates that data capture is enabled for that event.
event flag list
A 128-element array of event flags for all events within a facility. Each facility has
its own event flag list.

event handle

A unique numeric identifier generated by DECtrace on the EPC$START_EVENT
routine call identifies the start and end for a particular instance of a duration event.
event ID

A numeric representation of a predefined event. Valid event identifiers range from 1
to 128.
event name

A 0- to 16-character string that names an event.
event pair

The matching start and end events which indicate the occurrence of a duration
event.
event record

A record buffer used to pass the facility-specific items for an event to the DECtrace
service routines.
facility

Software, usually referred to as a layered product, that serves a particular purpose
and operates under VMS. See also application program

Glossary-3

facility definition

A description of the events and items that DECtrace can capture for a particular
facility. Each facility for which DECtrace can collect data must have a facility
definition stored in the DECtrace administration database.
facility library

A text library which is referenced during DECtrace reinstallations. Facilities
installed on your system before the installation of DECtrace can store their
facility definitions in the facility library. The file specification for the library is
SYS$COMMON:[SYSLIB]EPC$FACILITY.TLB.
facility selection

A description of what to collect during data collection. Facility selections include a
list of facilities and their collection classes. One or more data collections can use the
same facility selection.
file list

A file containing a list of file specifications to use as data capture files. Each file
specification must be on a separate line within the file list. The default file type for
the file list is TXT.
formatted data file

A file that contains data organized for reporting. The formatted data file can
contain data from one or more data files.
history database

A single RdbNMS database that contains all of the informational and error
messages associated with data collection. There is one history database per
system or VAX.cluster. You reference the history database with the logical name
EPC$HISTORY_DB.
instrumenting

The act of adding DECtrace service routine calls to an application program so that
event data can be collected.
interval

A time period when data collection takes place.

Glossary-4

item

A numeric or string value that can be collected for an occurrence of an event. Up to
128 items can be captured for each event.
item flag

A 128-bit element of the item flags list. Each bit corresponds to an item that can
be captured for a particular event for a facility. Each event has a 128-bit item flag
associated with it.
item flag list

A 128-element array of item flags for all events for the facility. Each facility has its
own item flag list.
item ID

A numeric representation of an item. Valid item identifiers range from 1 to 128.
item name

A 0- to 16-character string representing the name of an item.
local collection

A collection that is active or pending either on a standalone system or on one node
in a VAXcluster as opposed to data collection scheduled cluster-wide.
local node

The system you are currently logged in to.
non-registered facility

A facility whose facility ID number is not registered with Digital. The facility ID
for a non-registered facility is in the range of 2048 to 4095. Non-registered facilities
usually represent customer-created applications. See also facility
point event

See event
registered facility

A facility whose facility ID number is registered with Digital. The facility ID for a
registered facility is in the range of 1 to 2047. Registered facilities usually represent
DIGITAL layered products. See also facility

Glossary-5

registrar process

A detached process that handles all communication between the applications
instrumented with DECtrace routine calls and the DECtrace administration
database.
registration identifier

A 0- to 255-character string that is useful in distinguishing separate images use
the same facilities. You use the /REGISTRATION_ID qualifier to the SCHEDULE
COLLECTION command to collect data from processes with a specific registration
ID.
remote

Pertaining to or originating from another node in the network.
reporting

The process of creating reports based on a formatted file or database. DECtrace can
create reports based on data stored in a VAX RdbNMS database.
resource utilization items

A set of standard items that DECtrace collects for all facilities. The items are
referenced by the group name RESOURCE_ITEMS.
service routines

A set of predefined DECtrace routines whose calls are instrumented in the source
code of an application program so that event data can be collected.
source program

A program that expresses an algorithm in a programming language such as
FORTRAN, COBOL, or assembly language.
start event

The beginning of a duration event. See event

Glossary-6

Index
@ (Execute Procedure) command, 7-4

A
administration database, 1-3
backing up, 9-5
ALL collection class
See collection class

B
BIO, 6-5
buffered I/O operations, 6-5

c
CANCEL COLLECTION command
example, 3-13
format, 7-5
CAPACITY_PLANNING collection class
See collection class
CDD/Plus, 4-2
class
see collection class
cluster operations
canceling data collection, 3-13
scheduling data collection, 3-9
starting DECtrace, 9-2
stopping DECtrace, 9-3
collection class
creating, 6-8

collection class (Cont.)
definition, 2-2
recommended types, 6-8
collection process, 1-4
Commands, 7-ltab
CANCEL COLLECTION, 7-5
CREATE DEFINITION, 7-8
CREATE SELECTION, 7-21
DELETE DEFINITION, 7-25
DELETE SELECTION, 7-27
@(Execute Procedure), 7-4
EXIT, 7-29
EXTRACT DEFINITION, 7-30
FORMAT, 7-32
HELP, 7-39
INSERT DEFINITION, 7-40
REPORT, 7-42
SCHEDULE COLLECTION, 7-54
SET HISTORY, 7-59
SHOW COLLECTION, 7-61
SHOW DEFINITION, 7-63
SHOW HISTORY, 7-65
SHOW REGISTER, 7-68
SHOW SELECTION, 7-69
SHOW VERSION, 7-71
SPAWN, 7-72
STOP SYSTEM, 7-76
CPU usage, 6-5
CREATE DEFINITION command
format, 7-8

lndex-1

CREATE DEFINITION command
(Cont.)
options
CLASS, 7-19
DEFAULT_CLASS, 7-20
EVENT, 7-16
GROUP, 7-15
ITEM, 7-11
CREATE SELECTION command
example, 2-3
format, 7-21
CURRENT_PRIO, 6-5

EPC$START_EVENT, 8-26
example, 5-31
EPC$START_EVENTW, 8-30
error handling, 8-2
error messages and recovery, 9-9
event-based collection, 1-1
events
creating, 6-3
EXIT command, 7-29
EXTRACT DEFINITION command
example, 6-10
format, 7-30

data collection file, 3-11
file protection, 3-12
data merging, 4-2
deinstalling DECtrace, 6-13
DELETE DEFINITION command
example, 6-9
format, 7-25
DELETE SELECTION command
example, 2-4
format, 7-27
Detail Report, 4-5
DIO, 6-5
direct I/O operations, 6-5
disabling collection, 8-3, 9-6

facility definition
creating, 6-2
definition, 6-1
deleting, 6-9
displaying, 6-13
options, 6-20
facility library, 6-13
facility selection
.See also CREATE SELECTION
command
creating, 2-1, 2-3
deleting, 2-4
displaying, 2-5
facility-specific items, 6-5
facility version, 6-2
file list, 3-12
file protection, 3-12
FORMAT command
examples
RdbNMS database, 4-2
VAX. RMS file, 4-3
format, 7-32
Frequency Report, 4-9

E
EPC$DELETE_CONTEXT, 8-4
example, 5-31
EPC$END_EVENT, 8-7
example, · 5-31
EPC$END_EVENTW, 8-11
EPC$EVENT, 8-12
EPC$EVENTW, 8-16
EPC$INIT, 8-17
description of, 3-2
example, 5-28
instrumenting, 5-6
EPC$SET_CONTEXT, 8-23
example, 5-30

lndex-2

G
guaranteeing data collection, 5-9

H
HELP command, 7-39
history database, 9-5

INSERT DEFINITION command
example, ,6--12
format, 7-40
inserting definitions
manually, 6--12
using KITINSTAL.COM, 6--11
instrumenting an application, 5-1
events and items, 5-13
in VAX BLISS-32, 5-28
in VAX C, 5-11
in VAX COBOL, 5-8, 5-10
in VAX FORTRAN, 1-6
in VAX Pascal, 1-6
linking, 5-32
simple events, 5-12
items
creating, 6--5

performance (Cont.)
instrumenting for maximum
efficiency, 5-20
PERFORMANCE collection class
See collection class
priority of a process, 6--5

Rdb/VMS monitor process, 9-2, 9-3
registered facility, 6-2
Registrar process, 1-3, 3-2
starting, 9-2
stopping, 9-3
registration ID, 3-3
See also SHOW REGISTER command
facility-specific, 5-6
REPORT command
format, 7-42
options
EVENT, 4-24, 7-47
ITEM, 4-27, 7-51
RESTRICTION, 4-28, 7-52
resource utilization items, 6--5
RESOURCE_ITEMS group, 6--5
RMU Monitor, 9-2, 9-3

local collection, 3-9
local node, 3-9

sample application
description, 1-5
determining events, 5-5
facility definition, 6--5
instrumenting, 5-6
SCHEDULE COLLECTION command
format, 7-54
scheduling data collection
on a cluster, 3-9
on a standalone system, 3-9
on part of a cluster, 3-9
service routines, 8-1 tab
EPC$DELETE_CONTEXT, 8-4
EPC$END_EVENT, 8-7
EPC$END_EVENTW, 8-11
EPC$EVENT, 8-12

merging data files, 4-2
multi-threaded facilities, 5-28

N
non-registered facility, 6--2

p
PAGEFAULTS, 6--5
PAGEFAULT_IO, 6--5
performance
enhancing DECtrace, 9-1, 9-7
instrumenting efficiently, 5-19

lndex-3

service routines (Cont.)
EPC$EVENTW, 8-16
EPC$INIT, 8-17
EPC$SET_CONTEXT, 8-23
EPC$START_EVENT, 8-26
EPC$START_EVENTW, 8-30
return values, 8-2
SET HISTORY command, 7-59
SHOW COLLECTION command
form.at, 7-61
SHOW DEFINITION command
examples
FULL format, 6-14
NAMES_ONLY format, 6-19
format, 7-63
SHOW HISTORY command
example, 3-15
format, 7-65
SHOW REGISTER command
example, 3-5
format, 7-68
SHOW SELECTION command
examples
BRIEF format, 2-5
FULL format, 2-6
NAMES_ONLY format, 2-7
format, 7-69
SHOW VERSION command, 7-71
SPAWN command, 7-72
STOP SYSTEM command
example, 9-3
format, 7-76
Summary Report, 4-11

T
troubleshooting DECtrace problems,
9-7
See also SHOW HISTORY command

v
virtual pages, 6-5
VIRTUAL_SIZE, 6-5

lndex-4

w
working set size, 6-5
WORKLOAD collection class
See collection class
WS_GLOBAL, 6-5
WS_PRIVATE, 6-5
WS_SIZE, 6-5

How to Order Additional Documentation

Technical Support
If you need help deciding which documentation best meets your needs, call 800-343-4040
before placing your electronic, telephone, or direct mail order.

Electronic Orders
To place an order at the Electronic Store, dial 800-DEC-DEMO (800-332-3366) using
a 1200- or 2400-baud modem. If you need assistance using the Electronic Store,
call 800-DIGITAL (800-344-4825).

Telephone and Direct Mail Orders
Your Location

Call

Contact

Continental USA,
Alaska, or Hawaii

800-DIGITAL

Digital Equipment Corporation
P.O. Box CS2008
Nashua, New Hampshire 03061

Puerto Rico

809-754-7575

Local Digital subsidiary

Canada

800-267-6215

Digital Equipment of Canada
Attn: DECdirect Operations KA02/2
P.O. Box 13000
100 Herzberg Road
Kanata, Ontario, Canada K2K 2A6

International

Local Digital subsidiary or
approved distributor

Internal 1

USASSB Order Processing - WMO/E15
or
U.S. Area Software Supply Business
Digital Equipment Corporation
Westminster, Massachusetts 014 73

1For internal orders, you must submit an lntemal Software Order Form (EN-01740-07).

Reader's Comments

DECtrace for VMS
User's Guide
AA-PB90A-TE

Your comments and suggestions help us improve the quality of our publications.

Please rate the manual in the
following categories:
Accuracy (product works as described)
Completeness (enough information)
Clarity (easy to understand)
Organization (structure of subject matter)
Figures (useful)
Exam pl es (useful)
Table of contents (ability to find topic)
Index (ability to find topic)
Page design (overall appearance)
Print quality

Excellent

Good

Fair

Poor

D
D
D
D
D
D
0
D
D
D

D
D
D
D
D
D
D
D
D
D

What I like best about this manual:
What I like least about this manual:

Additional comments or suggestions:

I found the following errors in this manual:
Page

Description

For which tasks did you use this manual?

D Installation
D Maintenance
D Marketing

D Operation/Use

D Programming
D System Management
D Training
D Other (please specify)

Nametritle
Company
Address
Phone

Date

.
I

----------------------------·Fold Here and Tape-----------------------------·~--'
Please
Affix Stamp
Here

mamaama™

DIGITAL EQUIPMENT CORPORATION
Corporate User Publications

55 Northeastern Blvd.
NU01-1/G10
Nashua, NH 03062-3191

·- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - Fold

Here ---·--------------------------------

-Ill

".::::i
"Cl

~
0

c,,..
c

<
='

Reader's Comments

DECtrace for VMS
User's Guide

AA-PB90A-TE

Your comments and suggestions help us improve the quality of our publications.

Please rate the manual in the
following categories:
Accuracy (product works as described)
Completeness (enough information)
Clarity (easy to understand)
Organization (structure of subject matter)
Figures (useful)
Examples (useful)
Table of contents (ability to find topic)
Index (ability to find topic)
Page design (overall appearance)
Print quality

Excellent

Good

Fair

Poor

D
D
D

D
D
D
D

D
D
D
D
D
D
D
D
D
D

D
D
D
D
D
D

What I like best about this manual:
What I like least about this manual:

Additional comments or suggestions:

I found the following errors in this manual:
Page

Description

For which tasks did you use this manual?
D Installation
D Maintenance
D Marketing
D Operation/Use

D Programming

D System Management
D Training
D Other (please specify)

N ame/I'itle
Company
Address
Phone

Date

D
D
D

D
D
D
D

D
D
D

- - - - - - - - - - - - - - - - - - - - - - - - - - - - • Fold Here and Tape - - - - - - - - - - - - - - - - - - - - - - - - - - - - -·;.. - -

I
1

Please
Affix Stamp
Here

mamaama™

DIGITAL EQUIPMENT CORPORATION
Corporate User Publications

55 Northeastern Blvd.
NU01-1/G10
Nashua, NH 03062-3191

·- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - Fold Here • - -.- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -

·.::;
"O

~
0

.,..

c
0

<
1;
0