Reporter - IBMpublib.boulder.ibm.com/tividd/td/reporter/repl1mst/en_US/PDF/repl1... · ORACLE Books ... This guide uses several typeface conventions for special terms and actions

ReporterLog Collector Guide and ReferenceVersion 2.0

ReporterLog Collector Guide and ReferenceVersion 2.0

TME 10 Reporter Log Collector Guide and Reference (March 1997)Copyright NoticeCopyright 1991, 1997 by Tivoli Systems, an IBM Company, including this documentation and allsoftware. All rights reserved. May only be used pursuant to a Tivoli Systems Software LicenseAgreement or Addendum for Tivoli Products to IBM Customer or License Agreement. No part of thispublication may be reproduced, transmitted, transcribed, stored in a retrieval system, or translated intoany computer language, in any form or by any means, electronic, mechanical, magnetic, optical,chemical, manual, or otherwise, without prior written permission of Tivoli Systems. The document is notintended for production and is furnished “as is” without warranty of any kind. All warranties on thisdocument are hereby disclaimed including the warranties of merchantability and fitness for aparticular purpose.

Note to U.S. Government Users–Documentation related to restricted rights–Use, duplication, ordisclosure is subject to restrictions set forth in GSA ADP Schedule Contract with IBM Corp.

Trademarks

The following product names are trademarks of Tivoli Systems or IBM Corporation: AIX, IBM,NetView, Tivoli Management Environment, and TME 10.

Other company, product, and service names mentioned in this document are trademarks or registeredtrademarks of their respective manufacturers. These company, product, and service names might bedenoted by a double asterisk (**) at their first occurrence in this publication.

Notice

References in this publication to Tivoli Systems or IBM products, programs, or services do not implythat they will be available in all countries in which Tivoli Systems or IBM operates. Any reference tothese products, programs, or services is not intended to imply that only Tivoli Systems or IBM products,programs, or services can be used. Subject to Tivoli System's or IBM's valid intellectual property orother legally protectable right, any functionally equivalent product, program, or service can be usedinstead of the referenced product, program, or service. The evaluation and verification of operation inconjunction with other products, except those expressly designated by Tivoli Systems or IBM, are theresponsibility of the user.

Patents may be pending.

Version 2.0iv

Log Collector Guide and ReferencePreface . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .xi

Introducing the Log CollectorCollecting Log Data . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1-1Listing Log Data . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1-2Maintaining Data Tables . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1-3Maintaining Definitions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .1-3Summary of Log Collector Statements . . . . . . . . . . . . . . . . . . . . . . . 1-4

Getting Started With the Log Collector LanguageCreating the Data Table . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2-3Describing the Log File and Its Records . . . . . . . . . . . . . . . . . . . . . . 2-4Specifying the Update Process . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2-5Creating Table and Storing Definitions . . . . . . . . . . . . . . . . . . . . . . . 2-8Verifying Record Definitions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2-9Collecting Log Data Using the COLLECT Statement . . . . . . . . . . . . . 2-11Collecting Log Data Using SMIT . . . . . . . . . . . . . . . . . . . . . . . . . . 2-12

Advanced Use of Logs and RecordsWriting Record Definitions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3-1Defining a Record Containing a Section . . . . . . . . . . . . . . . . . . . . . . 3-4Defining Multiple Record Types . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3-7

Defining the Records . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3-9Changing Log and Record Definitions . . . . . . . . . . . . . . . . . . . . . . . 3-10

Using the ALTER RECORD Statement . . . . . . . . . . . . . . . . . . . . 3-10Using the DROP Statement . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3-11

TME 10 Reporter: Log Collector Guide and Reference v

Advanced Use of TablesUpdating a Table from Multiple Record Types . . . . . . . . . . . . . . . . . . 4-1Updating a Table from Another Table . . . . . . . . . . . . . . . . . . . . . . . . 4-6Managing Data Within Tables . . . . . . . . . . . . . . . . . . . . . . . . . . . . 4-11

Deleting Data . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .4-12Changing Data Within Tables . . . . . . . . . . . . . . . . . . . . . . . . . . . 4-13

Advanced Use of Update DefinitionsDetermining the Minimum, Maximum, and Average . . . . . . . . . . . . . . . 5-1Determining Percentiles . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .5-4Distributing Measurements . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .5-7Determining Resource Availability . . . . . . . . . . . . . . . . . . . . . . . . . 5-10Summarizing Availability by Schedule Period . . . . . . . . . . . . . . . . . . 5-19Using Repeated Sections Within Records . . . . . . . . . . . . . . . . . . . . 5-23

Defining a Record with Repeated Section . . . . . . . . . . . . . . . . . . . 5-25Defining Updates for Records with Repeated Sections . . . . . . . . . . 5-25

Using Nested Sections Within Records . . . . . . . . . . . . . . . . . . . . . . 5-29Defining a Record with Nested Sections . . . . . . . . . . . . . . . . . . . . 5-31Accessing Data in Nested Sections . . . . . . . . . . . . . . . . . . . . . . . 5-32

Accessing Data from Records with Sections . . . . . . . . . . . . . . . . . . 5-33Changing and Deleting Update Definitions . . . . . . . . . . . . . . . . . . . . 5-37

Using the ALTER UPDATE Statement . . . . . . . . . . . . . . . . . . . . . 5-37Using the DROP Statement . . . . . . . . . . . . . . . . . . . . . . . . . . . . 5-38

Collecting Log DataControlling Data Collection . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 6-1

Limiting the Collection to Certain Records . . . . . . . . . . . . . . . . . . . 6-1Including and Excluding Data Tables . . . . . . . . . . . . . . . . . . . . . . . 6-2Controlling When a COMMIT Is Made . . . . . . . . . . . . . . . . . . . . . . 6-3Controlling Buffer Size . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 6-3Handling Overflows . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .6-4

Collecting Data More than Once . . . . . . . . . . . . . . . . . . . . . . . . . . . 6-4Collecting Data from Partially Processed Logs . . . . . . . . . . . . . . . . 6-5

Verifying Log Data Sets During Data Collection . . . . . . . . . . . . . . . . . 6-5

Elements of the Log Collector Language

Version 2.0vi

Characters . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .7-1Tokens . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .7-2

Words . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .7-2Delimited Words . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .7-2String Constants . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .7-3Integer Constants . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .7-4Floating-point Constants . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .7-4Delimiters . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .7-4

Input Lines . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .7-5Blanks . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .7-5Comments . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .7-6

Line Comments . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .7-6Block Comments . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .7-6

How Your Text Is Processed . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 7-7Identifiers . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .7-9Table Names . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .7-10File Names . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .7-10Statements . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .7-11Using Variables to Modify Your Text . . . . . . . . . . . . . . . . . . . . . . . . 7-11

Values and ExpressionsData Types . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .8-2

Integers . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .8-2Floating-point Numbers . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .8-2Character Strings . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .8-3Dates . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .8-3Times . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .8-3Timestamps . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .8-3Truth Values . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .8-3

Missing and Invalid Data . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 8-4Null Value . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .8-4Unknown Truth Value . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 8-5Error Handling . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .8-5

Some Simple Ways of Specifying a Value . . . . . . . . . . . . . . . . . . . . . 8-6Specifying a Value Explicitly . . . . . . . . . . . . . . . . . . . . . . . . . . . . 8-6Specifying a Value Using an Identifier . . . . . . . . . . . . . . . . . . . . . . 8-7Obtaining the Value of a Variable . . . . . . . . . . . . . . . . . . . . . . . . . 8-8Obtaining Current Date, Time, or User . . . . . . . . . . . . . . . . . . . . . . 8-9

TME 10 Reporter: Log Collector Guide and Reference vii

Date/Time Strings . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .8-9Labeled Durations . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .8-11Using Operators . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .8-12

Arithmetic Operations . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .8-13Incrementing and Decrementing Date/Time Values . . . . . . . . . . . . 8-14Concatenating Strings . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .8-15Comparisons . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .8-16Pattern Matching . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .8-17Logical Operations . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .8-18

Testing for Null . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 8-19Case Expressions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .8-20Lookup Expressions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .8-22Expressions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .8-27Conditions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .8-28

FunctionsCHAR . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .9-2DATE . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .9-3DAY . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .9-4DAYS . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .9-5DAYTYPE . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .9-7DIGITS . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .9-11FLOAT . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .9-12HOUR . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .9-13INTEGER . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .9-14INTERVAL . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .9-15LENGTH . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .9-16MICROSECOND . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .9-17MINUTE . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .9-18MONTH . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .9-19PERIOD . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .9-20ROUND . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .9-25SECOND . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .9-27SECTNUM . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .9-28SUBSTR . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .9-30TIME . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .9-31TIMESTAMP . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .9-32TRANSLATE . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .9-34

Version 2.0viii

VALUE . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .9-36WORD . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .9-37YEAR . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .9-38

Log Collector Language StatementsALTER LOG . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .10-2ALTER RECORD . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .10-7ALTER RECORDPROC . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .10-11ALTER UPDATE . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .10-13COLLECT . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .10-17COMMENT ON . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .10-22DEFINE LOG . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .10-24DEFINE PURGE . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .10-29DEFINE RECORD . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .10-31DEFINE RECORDPROC . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .10-39DEFINE UPDATE . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .10-41DROP . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .10-56LIST RECORD . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .10-58LOGSTAT . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .10-66PURGE . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .10-68RECALCULATE . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .10-70SET . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .10-76SQL . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .10-78

Using Log and Record ProceduresSpecifying Log and Record Procedures . . . . . . . . . . . . . . . . . . . . . . A-3Calling Log and Record Procedures . . . . . . . . . . . . . . . . . . . . . . . . A-3Interface to Log and Record Procedures . . . . . . . . . . . . . . . . . . . . . A-5

The CL Interface . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . A-5The C Interface . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . A-8

Example of Log Procedure . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . A-9

Invoking the Log CollectorControl Variables . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .B-3

Variables That Can Only Be Defined on Invocation . . . . . . . . . . . . B-3Variables That Can Also Be Defined Using SET . . . . . . . . . . . . . . B-5

TME 10 Reporter: Log Collector Guide and Reference ix

Storing and Retrieving Database Data

How to Read Syntax Diagrams

BibliographyAIX Books . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .Bib-1DB2 for AIX Books . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Bib-2ORACLE Books . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .Bib-2NetView for AIX Books . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Bib-3SYBASE Books . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .Bib-3Systems Monitor for AIX Books . . . . . . . . . . . . . . . . . . . . . . . . . . Bib-3XRT/graph Books . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .Bib-3

Glossary

Index

Version 2.0x

Preface

PrefaceThe TME 10 Reporter Log Collector Guide and Referenceis a guideto understanding and customizing TME 10 Reporter for maximumbenefit to your organization and users. It describes how to use the logcollector language.

The term UNIX as used in this book covers the AIX, HP-UX, andSun Solaris operating systems. The term AIX refers only to the IBMoperating system.

Who Should Read This GuideThe TME 10 Reporter Log Collector Guide and Referenceis forTME 10 Reporter administrators and performance analysts orprogrammers responsible for maintaining system log data and reports.For the purpose of this book, you should be familiar with StructuredQuery Language (SQL).

Related DocumentsFollowing is a list of documents related to TME 10 Reporter:

TME 10 Reporter Installation and Administration, SH19-4119TME 10 Reporter Messages Guide, SH19-4233TME 10 Reporter Reporting Dialog Guide, SH19-4120TME 10 Reporter User's Reference, SH19-4122

The “Bibliography” on page Bib-1 lists other books that can behelpful when using TME 10 Reporter.

What This Guide ContainsThis guide comprises the following:

■ The first part of the book introduces the TME 10 Reporter logcollector and describes how to use its log collector language todefine and manage logs, records, tables, and updates.

■ The second part presents the reference information for eachelement, function, and statement of the TME 10 Reporter log

TME 10 Reporter: Log Collector Guide and Reference xi

Preface

collector. Each reference contains a syntax diagram, adescription, and a simple example of usage.

■ Appendixes provide additional reference information.

This book also contains a bibliography, glossary, and index.

Typeface ConventionsThis guide uses several typeface conventions for special terms andactions. These conventions have the following meaning:

Bold Identifies text on push buttons, user selections, andcommands.

Italics Identifies terms that are defined in the following text,and parameters whose actual names or values are tobe supplied by the user.

Monospace Identifies examples, messages, and text you may seedisplayed, and information you should actually type.

This guide may include icons in the left margin. These icons providecontext for the discussion in the text for performing a step within aprocedure. For example, if you start a procedure by double-clickingon a task icon, that icon appears in the left margin to the first step. Ifthe fourth step of the procedure instructs you to open another icon,that icon appears in the left margin next to the fourth step.

Contacting Customer SupportWe are very interested in hearing from you about your experiencewith the products and documentation in the Tivoli ManagementEnvironment. We welcome your suggestions for improvements.

If you encounter difficulties in any TME 10 product, please contactyour customer support representative. To assist you, the TME 10Framework includes the wsupport command. This command promptsyou for problem information, which can be E-mailed to your supportprovider or saved to a text file. You can then print the saved file, andfax the resulting TME Problem Report form to your support provider.See the TME 10 Framework Reference Manual for additionalinformation about the wsupport command.

Version 2.0xii

Preface

If you have comments or suggestions about the TME 10documentation, please send E-mail to [email protected].

TME 10 Reporter: Log Collector Guide and Reference xiii

Version 2.0xiv

Intro

du

ction1

Introducing the Log Collector

TME 10 Reporter (hereafter also referred to as Reporter) helps youeffectively manage the performance of your UNIX system bycollecting performance data in a database and generating reports fromthat data. A central part of Reporter is a program called thelogcollector, which reads performance data, organizes that data, andstores it in the database. You control the log collector withinstructions written in the log collector language. Each instruction isa statement in the language.

This chapter provides an overview of the log collector and itslanguage.

Collecting Log DataPerformance data is available in files called log files or logs.

The main function of the log collector is to read data from the logfiles and store it in database tables (called data tables). This processis called collecting log data. The log collector can perform extensiveprocessing on the data before storing it, such as:

■ Grouping data by hour, day, or month■ Computing sums, maximum or minimum values, averages, or

percentiles■ Calculating resource availability

The purpose of this processing is to transform large amounts of datainto useful information. The volume of data stored in the database isusually much smaller than the volume of data read from the log.

TME 10 Reporter: Log Collector Guide and Reference 1-1

Listing Log Data

To collect log data, you must describe the log to be processed and, inparticular, the layout of records in the log. You describe them in thelog collector language, using the DEFINE LOG and DEFINERECORD statements. You must also specify the processing to beperformed on the data from the log and how to update data tableswith the result. You specify these processes using the DEFINEUPDATE statement.

When the log collector executes the statements DEFINE LOG,DEFINE RECORD, and DEFINE UPDATE, it stores the definitionsof the log, record, and update process. The log, record, and updateprocess then become defined to the log collector. Notice that the logcollector stores the definitions, not the statements themselves.

Having defined the log, records, and update process, you collect datafrom the log using the COLLECT statement. When the log collectorexecutes the statement, it retrieves the stored definitions and performsthe data collection specified by those definitions.

You can use the stored definitions any number of times to collectdata from any number of log files, as long as the definitions properlydescribe the files and the required processing. You normally definethe log, records, and update process only once, when installingReporter. You then use the stored definitions to periodically collectperformance data generated by your installation.

Listing Log DataSometimes you might need to examine the contents of a log filewithout updating the data tables. If you have defined the log and itsrecords to the log collector, use the LIST RECORD statement tointerpret the log data and format it in a printable file.

To count the records for each record type contained in the log, usethe LOGSTAT statement.

Version 2.01-2

Intro

du

ction

Maintaning Definitions

Maintaining Data TablesYou normally do not keep all performance data forever, but discard itwhen it is no longer useful. You might, for example, discard dailystatistics when they are one month old and monthly statistics whenthey are one year old.

Use the log collector to discard old data. The basic principle is thesame as for collecting data: you store the definition of the job to bedone and then repeatedly use the stored definition to perform that job.

Using the DEFINE PURGE statement, you specify apurge conditionfor a data table. The condition identifies the data to be discarded,depending upon the current date and time. When the log collectorexecutes this statement, it stores the purge condition, which becomesdefined to the log collector. Having defined the purge condition forone or more tables, discard old data using the PURGE statement.When the log collector executes this statement, it retrieves the storedpurge conditions and purges the tables based on those conditions.

Occasionally, data entered into a data table is incorrect or the datatable is damaged. To repair the data, use SQL statements executedfrom the log collector. Use the RECALCULATE statement to alterdata stored by the log collector.

Maintaining DefinitionsThe main principle of using the log collector is that you define thelog, records, update process, and purge conditions only once. Havingdefined them, you use the stored definitions repeatedly for productionruns.

Sometimes, however, you might need to change the storeddefinitions. For example, you might install a new version of a productthat generates slightly different records in its log, or you might decideto collect more information.

The log collector language includes several ALTER statements formodifying stored definitions. You can also delete an entire storeddefinition using the DROP statement, and then store a modifieddefinition using one of the DEFINE statements.


Summary of Log Collector Statements

You can document the stored definitions by adding comments tothem using the COMMENT ON statement. When you display thedefinitions online using the System Management Interface Tool(SMIT), you see the comments you stored.

Summary of Log Collector StatementsThe log collector language comprises the following statements:

■ Definition statements

� DEFINE LOG� DEFINE PURGE� DEFINE RECORD� DEFINE RECORDPROC� DEFINE UPDATE� ALTER LOG� ALTER RECORD� ALTER RECORDPROC� ALTER UPDATE� SET� DROP� COMMENT ON

■ Log processing statements

� COLLECT� LIST RECORD� LOGSTAT

■ Table maintenance statements

� PURGE� RECALCULATE

■ Other statements

� SQL

Version 2.01-4

Gettin

g S

tarted

2Getting Started With the LogCollector Language

This chapter uses a simple example to describe how to use the logcollector language.

Assume that you want to determine how many read and write errorsare produced per hour by three applications: APPL1, APPL2, andAPPL3. The applications write information about read and writeerrors to a log file called rwstat.example. They update this file everyhour.

You want to collect data from the rwstat.example file and store it ina data table called PERFREP.RWDATA.

The records written by the applications have the following layout:

Table 1. Layout of Records in the rwstat.example File

Field Name Offset Length Description

A_NAME 0 10 The name of the applicationwriting this record

DATE 10 6 Date, in the format yymmdd

TIME 16 6 Time, in the format hhmmss

R_ERR 22 8 The number of read errors as aninteger in decimal notation

W_ERR 30 8 The number of write errors as aninteger in decimal notation


Getting Started

A specific record might look as follows. The record is shown in boldat the bottom, and the names above it identify the fields within therecord:

A_NAME DATE TIME R_ERR W_ERR

┌────────┐┌────┐┌────┐┌──────┐┌──────┐

│ ││ ││ ││ ││ │

APPL1 97ð125ð1ððð1 3 5

Figure 1. A Record in the rwstat.example File

Assume that the rwstat.example contains the following records (eachrecord is shown on a separate line):

APPL1 97ð125ð1ððð1 3 5APPL2 97ð125ð1ððð2 1 3APPL3 97ð125ð1ððð3 2 ðAPPL1 97ð125ð2ððð1 ð ðAPPL2 97ð125ð2ððð2 2 1APPL3 97ð125ð2ððð3 5 3APPL1 97ð125ð3ððð1 4 6APPL2 97ð125ð3ððð2 1 3APPL3 97ð125ð3ððð3 2 2

Figure 2. Content of the rwstat.example File

The PERFREP.RWDATA table is to contain the data from the logfile summarized by hour. The content of the table after datacollection is:

Table 2. Read and Write Error Statistics in Data Table PEFREP.RWDATA

DTE HOUR RD_ERR WR_ERR TOT_ERR

1997-01-25 1 6 8 14

1997-01-25 2 7 4 11

1997-01-25 3 7 11 18

Version 2.02-2

Gettin

g S

tarted

Creating the Data Table

The table contains the following columns:

Column ContainsDTE A dateHOUR An hour within that dateRD_ERR Total number of read errors registered during that hourWR_ERR Total number of write errors registered during that hourTOT_ERR Total number of errors (read and write) registered

during that hour

Before you can collect the data, you must:

■ Create the PERFREP.RWDATA table■ Describe the rwstat.example file and its records to the log

collector■ Specify the update process: how to enter data from the file into

the table

To create the table, use SQL. To describe the log file in the logcollector language, use the DEFINE LOG and DEFINE RECORDstatements. To specify the update process, use the DEFINE UPDATEstatement.

After writing the statements DEFINE LOG, DEFINE RECORD, andDEFINE UPDATE, run the log collector to execute them. When thelog collector executes those statements, it stores the definitions of thelog, record, and update process. The log, record, and update processthen become defined to the log collector.

The following three sections explain the statements that you need.The section “Creating Table and Storing Definitions” on page 2-8describes how to execute those statements.

Creating the Data TableTo create the PERFREP.RWDATA table, use SQL statements. Forthe purpose of this section, it is assumed that you know how to useSQL to create database tables. If you are not experienced with SQL,refer to your databaseSQL Reference for more information.


Describing the Log File

The SQL statement to create the PERFREP.RWDATA table dependson the database manager that you are using and on the organizationof your database. Assume that the statement is as the following:

CREATE TABLE PERFREP.RWDATA

(DTE DATE,

HOUR SMALLINT,

RD_ERR INTEGER,

WR_ERR INTEGER,

TOT_ERR INTEGER);

Use the log collector to execute the statement. Add the keyword SQLin front of the statement, as follows:

SQL CREATE TABLE PERFREP.RWDATA

(DTE DATE,

HOUR SMALLINT,

RD_ERR INTEGER,

WR_ERR INTEGER,

TOT_ERR INTEGER);

Describing the Log File and Its RecordsTo describe the log file rwstat.example to the log collector, startwith the following DEFINE LOG statement:

DEFINE LOG RWSTAT;

It defines a type of log file that contains the same kind of records anddata as the rwstat.example file. The statement gives the nameRWSTAT to this type of log file.

Notice that you do not define the specific log file rwstat.example.The reason is that your definitions are used many times, for log fileswith different names.

In this example, you used the DEFINE LOG statement only to give aname to the type of log file. But, you can include more informationto verify the log file and to control the data collection. See“Collecting Log Data” on page 6-1 for more information.

Version 2.02-4

Gettin

g S

tarted

Specifying the Update Process

To describe the records of the file rwstat.example to the logcollector, use the following DEFINE RECORD statement:

DEFINE RECORD RWSTAT_REC IN LOG RWSTAT

FIELDS

(A_NAME OFFSET ð LENGTH 1ð CHAR,

DATE OFFSET 1ð LENGTH 6 DATE(YYMMDD),

TIME OFFSET 16 LENGTH 6 TIME(HHMMSS),

R_ERR OFFSET 22 LENGTH 8 EXTERNAL INTEGER,

W_ERR OFFSET 3ð LENGTH 8 EXTERNAL INTEGER);

You assigned the name RWSTAT_REC to the record and specifiedthat it occurs in the RWSTAT log. Then, you identified each field inthe record by specifying the name, location in the record, length, andformat. Consider the following field description:

R_ERR OFFSET 22 LENGTH 8 EXTERNAL INTEGER

It states that the field called R_ERR begins at offset 22 in theRWSTAT_REC record. It is 8 bytes long and contains data inexternal integer form, that is, a number in decimal notation.

Specifying the Update ProcessTo specify how to store the data in the data table, use the followingDEFINE UPDATE statement:

DEFINE UPDATE TOT_ERRS

FROM RWSTAT_REC

TO PERFREP.RWDATA

GROUP BY

(DTE = DATE,

HOUR = HOUR(TIME))

SET

(RD_ERR = SUM(R_ERR),

WR_ERR = SUM(W_ERR),

TOT_ERR = SUM(R_ERR + W_ERR));

You indicated that you specify the process of entering data from theRWSTAT_REC records to the PERFREP.RWDATA table. You alsoassigned the name TOT_ERRS to the process. Then, you used theGROUP BY and SET clauses to define what to do with the data.



Understanding the GROUP BY ClauseIn each row of the PERFREP.RWDATA table, you want to collectdata from records written during the same hour on the same day. Theday is identified by the DATE field of each record. The hour isobtained from the TIME field using the HOUR function byspecifying HOUR(TIME). Use the following GROUP BY clause tospecify that records are to be grouped by DATE and HOUR(TIME):

GROUP BY

(DTE = DATE,

HOUR = HOUR(TIME))

The expressions to the right of the equal sign identify the values usedfor grouping.

To visualize the grouping process, imagine that the log collectormaintains a number of buckets labeled with different dates and hours.When the log collector reads each record, it computes DATE andHOUR(TIME) for the record and then drops the record into theappropriate bucket. After all records are processed, each bucketcontains the group of records that were written during the same houron the same day.

Figure 3 on page 2-7 shows how source records are groupedaccording to your GROUP BY clause.

For each group of records, the log collector creates one row in thedata table. It stores the values of DATE and TIME(HOUR) for thatgroup in the columns DTE and HOUR, respectively. These columnsare identified to the left of the equal sign in your GROUP BY clause.

Understanding the SET ClauseIn each row of the PERFREP.RWDATA table, you want to store thesum of certain values from all records in the group represented bythat row. You identified these sums using the SET clause:

SET




Version 2.02-6

Gettin

g S

tarted


Each expression to the right of the equal sign specifies what tocompute. The name to the left of the equal sign identifies the columnin the data table where the result is stored. For example,

TOT_ERR = SUM(R_ERR + W_ERR)

is an instruction to compute R_ERR + W_ERR for each record in thegroup, to add the resulting numbers, and to store the sum in thecolumn TOT_ERR of the row.

Figure 3 shows how the sums are calculated according to your SETclause, and how the results are stored in the data table.

rwstat.example ┌────────────────────────────────────────┐

┌─│ APPL1 97ð125ð1ððð1 3 5 │

┌───│ │ APPL2 97ð125ð1ððð2 1 3 ││ └─│ APPL3 97ð125ð1ððð3 2 ð │

│ ┌─│ APPL1 97ð125ð2ððð1 ð ð │

│┌──│ │ APPL2 97ð125ð2ððð2 2 1 │││ └─│ APPL3 97ð125ð2ððð3 5 3 │

││ ┌─│ APPL1 97ð125ð3ððð1 4 6 │

││┌─│ │ APPL2 97ð125ð3ððð2 1 3 ││││ └─│ APPL3 97ð125ð3ððð3 2 2 │

│││ └────────────────────────────────────────┘

│││

│││ Group for DATE=1997-ð1-25, HOUR(TIME)=3

│││ ┌────────────────────────────────────────┐

│││ │ APPL1 97ð125ð3ððð1 4 6 │─┐

GROUP BY ││└──5│ APPL2 97ð125ð3ððð2 1 3 │ │──────┐

DATE ││ │ APPL3 97ð125ð3ððð3 2 2 │─┘ │

HOUR(TIME) ││ └────────────────────────────────────────┘ │

││ Group for DATE=1997-ð1-25, HOUR(TIME)=2 │

││ ┌────────────────────────────────────────┐ │

││ │ APPL1 97ð125ð2ððð1 ð ð │─┐ │

│└───5│ APPL2 97ð125ð2ððð2 2 1 │ │─────┐│

│ │ APPL3 97ð125ð2ððð3 5 3 │─┘ ││

│ └────────────────────────────────────────┘ ││

│ Group for DATE=1997-ð1-25, HOUR(TIME)=1 ││

│ ┌────────────────────────────────────────┐ ││

│ │ APPL1 97ð125ð1ððð1 3 5 │─┐ ││

└────5│ APPL2 97ð125ð1ððð2 1 3 │ │────┐││

│ APPL3 97ð125ð1ððð3 2 ð │─┘ │││

└────────────────────────────────────────┘ │││ SET

│││ SUM(R_ERR)

PERFREP.RWDATA │││ SUM(W_ERR)

┌──────────┬───────┬───────┬───────┬───────┐ │││ SUM(R_ERR+W_ERR))

│ DTE │ HOUR │RD_ERR │WR_ERR │TOT_ERR│ │││

├──────────┼───────┼───────┼───────┼───────┤ │││

│1997-ð1-25│ 1 │ 6 │ 8 │ 14 │%────┘││

│1997-ð1-25│ 2 │ 7 │ 4 │ 11 │%─────┘│

│1997-ð1-25│ 3 │ 7 │ 11 │ 18 │%──────┘

└──────────┴───────┴───────┴───────┴───────┘

Figure 3. Example of GROUP BY and SET Processing


Creating Table and Storing Definitions

Creating Table and Storing DefinitionsAfter writing the statements, run the log collector to create the tableand store the definitions of the log, record, and update process.

Assuming that you typed all the statements in a file called lcdefs, thecontent of the file is:

SQL CREATE TABLE PERFREP.RWDATA

(DTE DATE,

HOUR SMALLINT,

RD_ERR INTEGER,

WR_ERR INTEGER,

TOT_ERR INTEGER);

DEFINE LOG RWSTAT;


FIELDS







FROM RWSTAT_REC

TO PERFREP.RWDATA

GROUP BY

(DTE = DATE,

HOUR = HOUR(TIME))

SET




To create the table and store the definitions, you invoke the logcollector with the lcdefs file as its standard input file. To invoke thelog collector, you must know the table prefix of data tables in yourdatabase. It may be different for different installations. If you do notknow the prefix at your installation, ask your system administrator.

For the following examples, it is assumed that the prefix of systemtables isperfrep. Replace it with your prefix when issuing thecommands.

Version 2.02-8

Gettin

g S

tarted

Verifying Record Definitions

To create the table and store the definitions, enter this command at anAIX prompt:

prlogcol tabprefix=perfrep <lcdefs

The log collector reads the statements from the lcdefs file andexecutes them.

When the log collector executes the statement SQL CREATETABLE, it removes from it the keyword SQL, and passes theremaining CREATE TABLE statement to the database manager. Thedatabase manager creates the table as specified in that statement.

When the log collector executes the statements DEFINE LOG,DEFINE RECORD, and DEFINE UPDATE, it stores the definitionsof the log, record, and update process. Notice that the log collectorstores the definitions, not the statements themselves.

The log collector responds with messages confirming the completionof each statement.

If the log collector finds an error in a statement, it does not executethat statement. It issues a message indicating that the statement wasnot executed and the reason.

Verifying Record DefinitionsAfter storing the log and record definitions, use the LIST RECORDstatement to verify that the record definition is correct. When theLIST RECORD statement is executed, data is not collected. Instead,the content of the log file is written in the format specified with thestored record definition.

To list the RWSTAT_REC records, enter the following statement in afile named listrec:

LIST RECORD RWSTAT_REC

FIELDS DATE, TIME, R_ERR, W_ERR

LISTFILE 'rwstat.list'

LOGFILE 'rwstat.example';


Verifying Record Definitions

To execute the LIST RECORD statement, enter the followingcommand at an AIX prompt:

prlogcol tabprefix=perfrep <listrec

Following is an example of the log collector messages that resultfrom the execution of the LIST RECORD statement:

PRCOL3ððI List started at 1997-ð2-25-ðð.14.21.

PRCOL3ð2I Processing rwstat.example.

PRCOL38ðI 9 records read from the input log.

PRCOLðð3I

PRCOL315I Records read from the log or built by log procedure:

PRCOL317I Record name | Number

PRCOL318I -------------------|----------

PRCOL319I RWSTAT_REC | 9

PRCOL318I -------------------|----------

PRCOL321I Total | 9

PRCOL381I 11 records written to the file rwstat.list.

PRCOL3ð1I List ended at 1997-ð2-25-ðð.14.21.

Figure 4. Messages Resulting from Execution of a LIST RECORD Statement

After the command is executed, the content of the rwstat.list file is:

DATE TIME R_ERR W_ERR

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

1997-ð1-25 ð1.ðð.ð1 3 5

1997-ð1-25 ð1.ðð.ð2 1 3

1997-ð1-25 ð1.ðð.ð3 2 ð

1997-ð1-25 ð2.ðð.ð1 ð ð

1997-ð1-25 ð2.ðð.ð2 2 1

1997-ð1-25 ð2.ðð.ð3 5 3

1997-ð1-25 ð3.ðð.ð1 4 6

1997-ð1-25 ð3.ðð.ð2 1 3

1997-ð1-25 ð3.ðð.ð3 2 2

Figure 5. Records Listed by the LIST RECORD Statement

Version 2.02-10

Gettin

g S

tarted

Collecting Log Data

Collecting Log Data Using the COLLECTStatement

After you create the table and store the log, record, and updatedefinitions, you can collect data from the rwstat.example file. Tocollect log data, enter this command at an AIX prompt:

prlogcol tabprefix=perfrep

If you do not specify a file for standard input, the log collector waitsfor log collector statements from the terminal. To collect data fromthe log file rwstat.example of type RWSTAT, enter:

collect rwstat from 'rwstat.example';

When the log collector executes this COLLECT statement, it uses allupdate definitions that you have stored for log type RWSTAT. Thelog collector uses the TOT_ERRS update, reads data fromRWSTAT_REC records and stores it in the PERFREP.RWDATAtable.

The log collector issues messages about the execution of theCOLLECT statement. Following is an example of such messages:

PRCOL3ððI Collect started at 1997-ð3-31-22.47.34.

PRCOL3ð2I Processing rwstat.example.

PRCOL31ðI A database update started after 9 records due to end of log.

PRCOLðð3I



PRCOL318I -------------------|----------

PRCOL319I RWSTAT_REC | 9

PRCOL318I -------------------|----------

PRCOL321I Total | 9

PRCOLðð3I

PRCOL323I -------Buffer------ ------Database-----

PRCOL324I Table name | Inserts Updates Inserts Updates

PRCOL325I ----------------------------|----------------------------------------

PRCOL326I PERFREP .RWDATA | 3 6 3 ð

PRCOL325I ----------------------------|----------------------------------------

PRCOL327I Total | 3 6 3 ð

PRCOLðð3I

PRCOL3ð1I Collect ended at 1997-ð3-31-22.47.37.

Figure 6. Messages Resulting from Execution of COLLECT Statement


Collecting Log Data

After the last message, press Control-D to terminate the log collectorinput.

After data collection, the content of the PERFREP.RWDATA tableis:

Instead of entering the COLLECT statement from the terminal, youcan enter it in a file and supply that file as input to the log collector,the same way as the LIST RECORD statement in “Verifying RecordDefinitions” on page 2-9.

Table 3. Content of the PERFREP.RWDATA Table After Data Collection


1997-01-25 1 6 8 14

1997-01-25 2 7 4 11

1997-01-25 3 7 11 18

Collecting Log Data Using SMITYou can perform data collection using SMIT, too. From SMIT, youcan:

■ Display log, record and update definitions.■ Collect data from log files.

For more information about using SMIT, refer to TME 10 ReporterInstallation and Administrationmanual.

Version 2.02-12

Lo

gs an

d R

ecord

s

3Advanced Use of Logs andRecords

In “Getting Started With the Log Collector Language” you learnedhow to write definitions and collect log data from a simple log file.However, log files are typically much more complex. They usuallycontain more than one record type, each with a different recordlayout.

This chapter tells you more about writing record definitions. It alsoexplains how to define complex record structures and how to modifyrecord definitions after they are stored.

Writing Record DefinitionsIn “Getting Started With the Log Collector Language” you definedthe RWSTAT_REC records with the following statement:


FIELDS






For each field, the field name, offset, length, and format wasspecified. Following are some alternatives of writing thosespecifications.


Writing Record Definitions

Omitting Fields and Field NamesWhen you define a record, specify only the fields from which youplan to collect data. For example, define the RWSTAT_REC recordas follows:


FIELDS

(DATE OFFSET 1ð LENGTH 6 DATE(YYMMDD),




Do not specify the A_NAME field because you do not use it in yourupdate definition. If you want to include the field (for a later use orfor documentation), but do not want to invent a name for it, you mayadd an asterisk (\) instead of the name:


FIELDS

(\ OFFSET ð LENGTH 1ð CHAR,





By using an asterisk instead of a field name, you cannot refer to thisfield in any other log collector statement (such as DEFINE UPDATEor LIST RECORD).

Using Default OffsetIf a field follows immediately after the field defined before it, youcan omit the OFFSET clause. You can also omit OFFSET 0 for thefirst field. Hence, omit all offsets in the definition of RWSTAT_REC:


FIELDS

(A_NAME LENGTH 1ð CHAR,

DATE LENGTH 6 DATE(YYMMDD),

TIME LENGTH 6 TIME(HHMMSS),

R_ERR LENGTH 8 EXTERNAL INTEGER,

W_ERR LENGTH 8 EXTERNAL INTEGER);

Omitting the offset for the first field, A_NAME, means that the fieldbegins at offset 0. Omitting the offset for the DATE field means thatit immediately follows the A_NAME field and begins at offset 10

Version 2.03-2

Lo

gs an

d R

ecord

s

Writing Record Definitions

(the offset of the A_NAME field plus the length of the A_NAMEfield). Because the TIME field immediately follows the DATE field,it begins at offset 16, and so on.

Using Default LengthIn many cases, you can omit the LENGTH clause and use the defaultlength, which is determined by the field format. For example, thelength of a date field in the format yymmdd is 6 bytes, so you canspecify the DATE field without a length. The default length of anexternal integer field is 8, so you can omit the lengths of R_ERR andW_ERR.

You can specify the length of a character field when you specify theformat. For example, instead of specifying LENGTH 10 for the fieldA_NAME, you can specify its format as CHAR(10). (This notation isnot allowed for any other formats.)

Using all these facilities, define the RWSTAT_REC record asfollows:


FIELDS

(\ CHAR(1ð),

DATE DATE(YYMMDD),

TIME TIME(HHMMSS),

R_ERR EXTERNAL INTEGER,

W_ERR EXTERNAL INTEGER);

Things to Watch ForAlthough using defaults makes typing definitions quicker, be carefulbecause problems may arise. For example, if you edit the definitionof the RWSTAT_REC record written in the previous example anddelete the first field, you must remember to specify OFFSET 10 forDATE. Otherwise, DATE appears as the first field in the record,which means that it begins at offset 0. The offsets of all other fieldsare reduced by 10. Collecting data with this definition producesinvalid results.

Another problem might occur if you specified an incorrect length fora field. Because offsets are calculated using lengths, the error resultsin incorrect offsets for the remaining fields.


Defining a Record Containing a Section

Using Comments to Document Your DefinitionThe log collector ignores any text starting with a double minus sign(--) up to the end of the line. The following DEFINE RECORDstatement produces exactly the same record definition as thestatement in the previous example:

DEFINE RECORD RWSTAT_REC IN LOG RWSTAT -- Error statistics record

FIELDS

(\ CHAR(1ð), -- Application name (unused)

DATE DATE(YYMMDD), -- Date record written

TIME TIME(HHMMSS), -- Time record written

R_ERR EXTERNAL INTEGER, -- Number of read errors

W_ERR EXTERNAL INTEGER); -- Number of write errors

The text starting with a double minus sign is called a comment.Adding comments to your definitions makes them easier tounderstand. Notice that the comments are not stored with thedefinition. To store a comment, use the COMMENT ON statement.For more information, see “COMMENT ON” on page 10-22.

Defining a Record Containing a SectionMany log records containsections. A section is a named area withina record.

The offset and length of the section can be fixed or can be stored inthe record. If they are stored in the record, a section can havedifferent offset and length for different records. The offsets of fieldswithin a section are determined from the start of the section.

Assume that you want to collect data about the applications runningon your UNIX system. The data is contained in a section calledAPPL of a SYS_INFO record. The field AOFF in the record providesinformation about the location of the section.

The SYS_INFO records have the following structure.

Version 2.03-4

Lo

gs an

d R

ecord

s


Notice that offsets of fields in a section are determined from the startof the section.

A specific SYS_INFO record can look as follows:

Table 4. Structure of a Record Containing a Section




AOFF 12 2 Offset of APPL section as aninteger in decimal notation

■ ■ (Other fields within the record)■

APPL section. The section is 20 bytes long and starts at the offset specified byAOFF

NODE 0 8 Node name

PROG 8 8 Program name

VERS 16 4 Version number of program

APPL section

┌──────────────────┐

other │ │

DATE TIME AOFF fields NODE PROG VERS

┌────┐┌────┐┌┐ ┌──────┐┌──────┐┌──┐

│ ││ │││ │ ││ ││ │

97ð12512ðððð33....................NODE1 PROGA V5R3

│ &

└──specifies offset──┘

Figure 7. Example of a Record Containing a Section



A log file containing SYS_INFO records can look like the following(notice the different offsets of the APPL section in different records):

97ð12512ðððð34....................NODE1 PROGA V5R397ð12512ððð134....................NODE2 PROGA V5R497ð12512ððð23ð................NODE3 PROGB V2R797ð12512ððð33ð................NODE4 PROGB V2R797ð12512ððð436......................NODE5 PROGC V1Rð

Figure 8. Example of File Containing SYS_INFO Records

To define the SYS_INFO record, use the following DEFINERECORD statement:

DEFINE RECORD SYS_INFO IN LOG SLOG

FIELDS

(DATE OFFSET ð LENGTH 6 DATE(YYMMDD),


AOFF OFFSET 12 LENGTH 2 EXTERNAL INTEGER)

SECTION APPL

OFFSET AOFF

LENGTH 2ð

FIELDS

(NODE OFFSET ð LENGTH 8 CHAR,

PROG OFFSET 8 LENGTH 8 CHAR,

VERS OFFSET 16 LENGTH 4 CHAR);

You named the record and specified that it occurs in a log calledSLOG. Then you identified each of the fields in the record.Remember that you need to define only the fields to be used later.Identify the AOFF field because it is used in the SECTION clause.

The SECTION clause states that the SYS_INFO record contains asection called APPL. The OFFSET clause specifies that the numbercontained in field AOFF is the offset where APPL begins:

Fields in a section are defined in the same way as fields are definedin a record.

The SYS_INFO record in the previous example contained only onesection, but a record can have different sections. It can also haverepeated sections, which are sections that occur more than once in a

Version 2.03-6

Lo

gs an

d R

ecord

s

Defining Multiple Record Types

record, and nested sections, which are sections within sections. Formore information about repeated sections, see “Using RepeatedSections Within Records” on page 5-23. For more information aboutnested sections, see “Using Nested Sections Within Records” onpage 5-29.

Defining Multiple Record TypesFor the examples illustrated so far, it was assumed that all recordswithin a log file are of the same kind. But log files typically containmany different kinds of records, called record types.

Assume that you have a log file called rwinfo.example that containsdata about read and write errors. Some applications (APPL1, APPL2,and APPL3) write records of type A to rwinfo.example.

The records of type A have the following layout:

Table 5. Layout of Type A Records


TYPE 0 2 Character string A

A_NAME 2 10 The name of the applicationwriting this record.



RA_ERR 24 8 The number of read errors as aninteger in decimal notation

WA_ERR 32 8 The number of write errors as aninteger in decimal notation



A specific record of type A can look as follows (notice that allrecords of type A have a field called TYPE that contains the stringA):

TYPE A_NAME DATE TIME RA_ERR WA_ERR

┌┐┌────────┐┌────┐┌────┐┌──────┐┌──────┐

│││ ││ ││ ││ ││ │

A APPL1 97ð12423ððð1 ð 2

Figure 9. A Record of Type A

Other applications (APPL4, APPL5, and APPL6) write records oftype B to the rwinfo.example file. The records of type B have thefollowing layout:

A specific record of type B can look as follows (notice that allrecords of type B have a field called TYPE that contains the stringB):

Table 6. Layout of Type B Records


TYPE 0 2 Character string B



RB_ERR 14 8 The number of read errors as aninteger in decimal notation

WB_ERR 22 8 The number of write errors as aninteger in decimal notation

TYPE DATE TIME RB_ERR WB_ERR

┌┐┌────┐┌────┐┌──────┐┌──────┐

│││ ││ ││ ││ │

B 97ð12423ððð3 4 1

Figure 10. A Record of Type B

Version 2.03-8

Lo

gs an

d R

ecord

s


The rwinfo.example file can contain the following records:

A APPL1 97ð12423ððð1 ð 2A APPL3 97ð12423ððð2 3 1B 97ð12423ððð3 4 1A APPL1 97ð125ð1ððð1 3 5A APPL2 97ð125ð1ððð2 1 3A APPL3 97ð125ð1ððð3 2 ðB 97ð125ð1ððð4 4 2A APPL1 97ð125ð2ððð1 3 5B 97ð125ð2ððð2 1 3A APPL2 97ð125ð2ððð3 1 3A APPL3 97ð125ð2ððð4 2 ð

Figure 11. Example of a Log File with Type A and Type B Records

Defining the RecordsTo define records of type A and B, use the following statements:

DEFINE LOG RWINFO;

DEFINE RECORD TYPA_REC IN LOG RWINFO -- Record of type A

IDENTIFIED BY TYPE='A'

FIELDS

(TYPE OFFSET ð LENGTH 2 CHAR,

A_NAME OFFSET 2 LENGTH 1ð CHAR,

DATE OFFSET 12 LENGTH 6 DATE(YYMMDD),


RA_ERR OFFSET 24 LENGTH 8 EXTERNAL INTEGER,

WA_ERR OFFSET 32 LENGTH 8 EXTERNAL INTEGER);

DEFINE RECORD TYPB_REC IN LOG RWINFO -- Record of type B

IDENTIFIED BY TYPE='B'

FIELDS




RB_ERR OFFSET 14 LENGTH 8 EXTERNAL INTEGER,

WB_ERR OFFSET 22 LENGTH 8 EXTERNAL INTEGER);


Changing Log and Record Definitions

These statements create a separate definition for each record type.You distinguish between different record types using theIDENTIFIED BY clause. Whenever TYPE='A', the record definitionfor type A records applies. Whenever TYPE='B', the record definitionfor type B records applies.

“Updating a Table from Multiple Record Types” on page 4-1describes how to use these definitions to collect data and update adata table.

Changing Log and Record DefinitionsAfter you have stored log and record definitions you can changethem:

■ Using the ALTER LOG or the ALTER RECORD statement.

■ Using the DROP statement to delete the existing definition andthen using the DEFINE LOG or the DEFINE RECORDstatement to create a new log or record definition.

Using the ALTER RECORD StatementYou can use the ALTER RECORD statement to change a storedrecord definition.

For example, assume you had this record definition:


FIELDS




SECTION APPL

OFFSET AOFF

LENGTH 2ð

FIELDS

(NODE OFFSET ð LENGTH 8 CHAR,

PROG OFFSET 8 LENGTH 8 CHAR,


Version 2.03-10

Lo

gs an

d R

ecord

s


Assume that you want to add a field called N_FIELD after the fieldAOFF. To add the field use the following ALTER RECORDstatement:

ALTER RECORD SYS_INFO

ADD FIELDS(N_FIELD OFFSET 14 LENGTH 2 CHAR);

When you execute this statement, the field N_FIELD is added to therecord, starting at offset 14.

Using the DROP StatementYou can use the DROP statement to delete a stored record definition.For example, assume that you wanted to delete the stored definitionfor SYS_INFO records. To delete the definition, use the followingstatement:

DROP RECORD SYS_INFO;

You can also use the DROP statement in combination with theDEFINE RECORD statement to make modifications to a storeddefinition.

Consider the record SYS_INFO discussed under “Using the ALTERRECORD Statement” on page 3-10. Assume that you want to addN_FIELD to the APPL section beginning at offset 0. This changesthe offsets of all fields in the section and the total length of thesection. Using an ALTER RECORD statement to add N_FIELD atoffset 0 does not adjust the offsets of other fields or the sectionlength. You must explicitly alter each of them.



A convenient way to make the required changes is by executing thefollowing statements:

DROP RECORD SYS_INFO;


FIELDS




SECTION APPL

OFFSET AOFF

LENGTH 22

FIELDS

(N_FIELD OFFSET ð LENGTH 2 CHAR,

NODE OFFSET 2 LENGTH 8 CHAR,

PROG OFFSET 1ð LENGTH 8 CHAR,


The statement DROP RECORD SYS_INFO deletes the stored definition ofSYS_INFO. The statementDEFINE RECORD SYS_INFO stores a newdefinition.

The advantage of this method is that the new DEFINE RECORDstatement provides a complete documentation of the new definition. Ifyou use ALTER RECORD, the documentation consists of two parts:the old DEFINE RECORD statement and the ALTER RECORDstatement used to modify it. Because of this, the ALTER RECORDstatement is best suited for making quick temporary changes.

Version 2.03-12

Tab

les

4Advanced Use of Tables

“Getting Started With the Log Collector Language,” describes how tostore data from a single record type into a data table. But, you canalso perform more complex tasks with data tables. For example, youcan store data from multiple record types into a data table. Then, youcan take the data from that data table, summarize it, and store theresult in another data table. This chapter describes how to performthese tasks. It also explains how to use log collector languagestatements to manage data within tables.

Updating a Table from Multiple RecordTypes

“Defining Multiple Record Types” on page 3-7 describes how todefine two record types (type A and type B) that occur in a log filecalled rwinfo.example.


Updating a Table from Multiple Record Types

The following log and record definitions were used:

DEFINE LOG RWINFO;

DEFINE RECORD TYPA_REC IN LOG RWINFO -- Record of type A

IDENTIFIED BY TYPE='A'

FIELDS


A_NAME OFFSET 2 LENGTH 1ð CHAR,



RA_ERR OFFSET 24 LENGTH 8 EXTERNAL INTEGER,

WA ERR OFFSET 32 LENGTH 8 EXTERNAL INTEGER);

DEFINE RECORD TYPB_REC IN LOG RWINFO -- Record of type B

IDENTIFIED BY TYPE='B'

FIELDS




RB_ERR OFFSET 14 LENGTH 8 EXTERNAL INTEGER,

WB_ERR OFFSET 22 LENGTH 8 EXTERNAL INTEGER);

Assume that the rwinfo.example file contains the following records:

A APPL1 97ð12423ððð1 ð 2A APPL3 97ð12423ððð2 3 1B 97ð12423ððð3 4 1A APPL1 97ð125ð1ððð1 3 5A APPL2 97ð125ð1ððð2 1 3A APPL3 97ð125ð1ððð3 2 ðB 97ð125ð1ððð4 4 2A APPL1 97ð125ð2ððð1 3 5B 97ð125ð2ððð2 1 3A APPL2 97ð125ð2ððð3 1 3A APPL3 97ð125ð2ððð4 2 ð

Figure 12. Example of a Log File with Type A and Type B Records

Version 2.04-2

Tab

les


Assume that you want to collect data from records of both types andstore the result in a single data table. You want the table to containdata about read and write errors summarized by hour, like thefollowing:

The table has these columns:

Column ContainsDTE A dateHOUR An hour within that date.RD_ERR Total number of read errors during that hour (from both

record types)WR_ERR Total number of write errors during that hour (from

both record types)TOT_ERR Total of number of errors during that hour (from both

record types)

To create the table, use this log collector statement:

SQL CREATE TABLE PERFREP.STATS_H

(DTE DATE,

HOUR SMALLINT,

RD_ERR INTEGER,

WR_ERR INTEGER,

TOT_ERR INTEGER);

Table 7. Error Statistics by Hour


1997-01-24 23 7 4 11

1997-01-25 1 10 10 20

1997-01-25 2 7 11 18



To collect data from both record types (A and B) into a single datatable, you need two DEFINE UPDATE statements, one for eachrecord type:

DEFINE UPDATE HOUR_STATS_A -- Update definition for Type A records

FROM TYPA_REC

TO PERFREP.STATS_H

GROUP BY

(DTE = DATE,

HOUR = HOUR(TIME))

SET

(RD_ERR = SUM(RA_ERR),

WR_ERR = SUM(WA_ERR),

TOT_ERR = SUM(RA_ERR + WA_ERR));

DEFINE UPDATE HOUR_STATS_B -- Update definition for Type B records

FROM TYPB_REC

TO PERFREP.STATS_H

GROUP BY

(DTE = DATE,

HOUR = HOUR(TIME))

SET

(RD_ERR = SUM(RB_ERR),

WR_ERR = SUM(WB_ERR),

TOT_ERR = SUM(RB_ERR + WB_ERR));

When you store data from more than one record type into a singledata table, you must follow these rules:

■ All update definitions must store the grouping values in thesame columns. That is, the column names specified in theGROUP BY clause to the left of the equal sign must be thesame for both record types.

■ If you want to store data from different records into the samecolumn, you must summarize that data in the same way. Forexample, if your SET clause specifies:

RD_ERR = SUM(RA_ERR)

for the first record type, you must also use the SUM functionfor the second record type:

RD_ERR = SUM(RB_ERR)

Version 2.04-4

Tab

les


When you collect data from the rwinfo.example file, data from bothrecord types is grouped together by date and hour as specified by theGROUP BY clauses. The functions specified by the SET clauses areapplied to the groups and the result for each group is stored as asingle row in the PERFREP.STATS_H table.

Figure 13 on page 4-6 illustrates this process.

After data collection, the PERFREP.STATS_H table contains thefollowing data:

Table 8. Contents of the PERFREP.STATS_H Table After Data Collection


1997-01-24 23 7 4 11

1997-01-25 1 10 10 20

1997-01-25 2 7 11 18


Updating a Table from Another Table

rwinfo.example ┌──────────────────────────────────────────┐

┌─│ A APPL1 97ð12423ððð1 ð 2 │┌───│ │ A APPL2 97ð12423ððð2 3 1 ││ └─│ B 97ð12423ððð3 4 1 │

│ ┌─│ A APPL1 97ð125ð1ððð1 3 5 ││ │ │ A APPL2 97ð125ð1ððð2 1 3 ││┌──│ │ A APPL3 97ð125ð1ððð3 2 ð │││ └─│ B 97ð125ð1ððð4 4 2 │

││ ┌─│ A APPL1 97ð125ð2ððð1 3 5 │││ │ │ B 97ð125ð2ððð2 1 3 │

││┌─│ │ A APPL2 97ð125ð2ððð3 1 3 ││││ └─│ A APPL3 97ð125ð2ððð4 2 ð │

│││ └──────────────────────────────────────────┘

GROUP BY │││

DATE │││ Group for DATE=1997-ð1-25, HOUR(TIME)=2

HOUR(TIME) │││ ┌──────────────────────────────────────────┐

│││ │ A APPL1 97ð125ð2ððð1 3 5 ├─┐││└──5│ B 97ð125ð2ððð2 1 3 │ │

││ │ A APPL2 97ð125ð2ððð3 1 3 │ │────┐││ │ A APPL3 97ð125ð2ððð4 2 ð │─┘ │

││ └──────────────────────────────────────────┘ │


││ ┌──────────────────────────────────────────┐ │

││ │ A APPL1 97ð125ð1ððð1 3 5 │─┐ │

│└───5│ A APPL2 97ð125ð1ððð2 1 3 │ │ │

│ │ A APPL3 97ð125ð1ððð3 2 ð │ │───┐││ │ B 97ð125ð1ððð4 4 2 │─┘ ││ SET

│ └──────────────────────────────────────────┘ ││ SUM(RA_ERR)

│ Group for DATE=1997-ð1-24, HOUR(TIME)=23 ││ SUM(WA_ERR)

│ ┌──────────────────────────────────────────┐ ││ SUM(RA_ERR+WA_ERR)

│ │ A APPL1 97ð12423ððð1 ð 2 │─┐ ││

└────5│ A APPL3 97ð12423ððð2 3 1 │ │──┐││ SUM(RB_ERR)

│ B 97ð12423ððð3 4 1 │─┘ │││ SUM(WB_ERR)

└──────────────────────────────────────────┘ │││ SUM(RB_ERR+WB_ERR)

│││

PERFREP.STATS_H │││

┌──────────┬───────┬───────┬───────┬───────┐ │││


├──────────┼───────┼───────┼───────┼───────┤ │││

│1997-ð1-24│ 23 │ 7 │ 4 │ 11 │%───┘││

│1997-ð1-25│ 1 │ 1ð │ 1ð │ 2ð │%────┘│

│1997-ð1-25│ 2 │ 7 │ 11 │ 18 │%─────┘

└──────────┴───────┴───────┴───────┴───────┘

Figure 13. Processing Two Update Definitions

Updating a Table from Another TableWhen you collect data, you can:

■ Store data about hourly activities in one data table.■ Summarize the hourly activities by day and store the result in

another data table.■ Store a monthly summary in still another data table.

Version 2.04-6

Tab

les


Storing data in one table, summarizing it, and storing the result inanother table is called a cascaded update.

Assume that when you collect data and store it in thePERFREP.STATS_H table (on an hourly basis), you also want tosummarize the data on a daily basis and store the result in anotherdata table, called PERFREP.STATS_D. You want the table to looklike the following:

The table has the following columns:

Column ContainsDTE A date.RD_ERR Total number of read errors on that dateWR_ERR Total number of write errors on that dateTOT_ERR Total of number of errors on that date

To create the table, use the following log collector statement:

SQL CREATE TABLE PERFREP.STATS_D

(DTE DATE,

RD_ERR INTEGER,

WR_ERR INTEGER,

TOT_ERR INTEGER );

Table 9. Error Statistics by Day

DTE RD_ERR WR_ERR TOT_ERR

1997-01-24 7 4 11

1997-01-25 17 21 38



To create a cascaded update, you must specify how to process datafrom the PERFREP.STATS_H table and how to store the result in thePERFREP.STATS_D table. To do so, use this DEFINE UPDATEstatement:

DEFINE UPDATE DAY_STATS

FROM PERFREP.STATS_H

TO PERFREP.STATS_D

GROUP BY

(DTE = DTE)

SET

(RD_ERR = SUM(RD_ERR),

WR_ERR = SUM(WR_ERR),

TOT_ERR = SUM(TOT_ERR));

Notice that the location of the source data (specified by the FROMclause) is the table PERFREP.STATS_H.

When you collect data from the rwinfo.example file, the logcollector uses the update definitions HOUR_STATS_A andHOUR_STATS_B discussed in “Updating a Table from MultipleRecord Types” on page 4-1, and updates the tablePERFREP.STATS_H as described there. Finding an update definitionthat specifies PERFREP.STATS_H as the source of data, it also usesthat update definition and updates the PERFREP.STATS_D table.

Based on your GROUP BY clause, the rows in thePERFREP.STATS_H table are grouped by the DTE column. Eachgroup is then summarized in a single row of thePERFREP.STATS_D table. Your SET clause defines how the data inthat row are obtained from the group.

Figure 15 on page 4-10 illustrates the whole process.

Version 2.04-8

Tab

les


This is an example of messages written by the log collector during acascaded update:

PRCOL3ððI Collect started at 1997-ð4-ð2-ð2.11.32.

PRCOL3ð2I Processing rwinfo.example.

PRCOL31ðI A database update started after 11 records due to end of log.

PRCOLðð3I



PRCOL318I -------------------|----------

PRCOL319I TYPA_REC | 8

PRCOL319I TYPB_REC | 3

PRCOL318I -------------------|----------

PRCOL321I Total | 11

PRCOLðð3I

PRCOL323I -------Buffer------ ------Database-----

PRCOL324I Table name | Inserts Updates Inserts Updates

PRCOL325I ----------------------------|----------------------------------------

PRCOL326I PERFREP .STATS_D | 2 1 2 ð

PRCOL326I PERFREP .STATS_H | 3 8 3 ð

PRCOL325I ----------------------------|----------------------------------------

PRCOL327I Total | 5 9 5 ð

PRCOLðð3I

PRCOL3ð1I Collect ended at 1997-ð4-ð2-ð2.11.36.

Figure 14. Messages Resulting from a Cascaded Update



rwinfo.example ┌──────────────────────────────────────────┐

┌─│ A APPL1 97ð12423ððð1 ð 2 │┌───│ │ A APPL3 97ð12423ððð2 3 1 ││ └─│ B 97ð12423ððð3 4 1 │

│ ┌─│ A APPL1 97ð125ð1ððð1 3 5 ││ │ │ A APPL2 97ð125ð1ððð2 1 3 ││┌──│ │ A APPL3 97ð125ð1ððð3 2 ð │││ └─│ B 97ð125ð1ððð4 4 2 │

││ ┌─│ A APPL1 97ð125ð2ððð1 3 5 │││ │ │ B 97ð125ð2ððð2 1 3 │

││┌─│ │ A APPL2 97ð125ð2ððð3 1 3 ││││ └─│ A APPL3 97ð125ð2ððð4 2 ð │

│││ └──────────────────────────────────────────┘

GROUP BY │││

DATE │││ Group for DATE=1997-ð1-25, HOUR(TIME)=2

HOUR(TIME) │││ ┌──────────────────────────────────────────┐

│││ │ A APPL1 97ð125ð2ððð1 3 5 ├─┐││└──5│ B 97ð125ð2ððð2 1 3 │ │

││ │ A APPL2 97ð125ð2ððð3 1 3 │ │────┐││ │ A APPL3 97ð125ð2ððð4 2 ð │─┘ │

││ └──────────────────────────────────────────┘ │


││ ┌──────────────────────────────────────────┐ │

││ │ A APPL1 97ð125ð1ððð1 3 5 │─┐ │

│└───5│ A APPL2 97ð125ð1ððð2 1 3 │ │ │

│ │ A APPL3 97ð125ð1ððð3 2 ð │ │───┐││ │ B 97ð125ð1ððð4 4 2 │─┘ ││ SET

│ └──────────────────────────────────────────┘ ││ SUM(RA_ERR)

│ Group for DATE=1997-ð1-24, HOUR(TIME)=23 ││ SUM(WA_ERR)

│ ┌──────────────────────────────────────────┐ ││ SUM(RA_ERR+WA_ERR)

│ │ A APPL1 97ð12423ððð1 ð 2 │─┐ ││

└────5│ A APPL3 97ð12423ððð2 3 1 │ │──┐││ SUM(RB_ERR)

│ B 97ð12423ððð3 4 1 │─┘ │││ SUM(WB_ERR)

└──────────────────────────────────────────┘ │││ SUM(RB_ERR+WB_ERR)

│││

PERFREP.STATS_H │││

┌──────────┬───────┬───────┬───────┬───────┐ │││


├──────────┼───────┼───────┼───────┼───────┤ │││

┌─────│1997-ð1-24│ 23 │ 7 │ 4 │ 11 │%───┘││

│┌──┬─│1997-ð1-25│ 1 │ 1ð │ 1ð │ 2ð │%────┘│

││ └─│1997-ð1-25│ 2 │ 7 │ 11 │ 18 │%─────┘

GROUP BY ││ └──────────┴───────┴───────┴───────┴───────┘

DTE ││

││ Group for DTE=1997-ð1-25

││ ┌──────────┬───────┬───────┬───────┬───────┐

│└───5│1997-ð1-25│ 1 │ 1ð │ 1ð │ 2ð │─┬────┐

│ │1997-ð1-25│ 2 │ 7 │ 11 │ 18 │─┘ │

│ └──────────┴───────┴───────┴───────┴───────┘ │

│ Group for DTE=1997-ð1-24 │

│ ┌──────────┬───────┬───────┬───────┬───────┐ │

└────5│1997-ð1-24│ 23 │ 7 │ 4 │ 11 │─────┐│ SET

└──────────┴───────┴───────┴───────┴───────┘ ││ SUM(RD_ERR)

││ SUM(WR_ERR)

PERFREP.STATS_D ││ SUM(TOT_ERR)

┌──────────┬───────┬───────┬───────┐ ││

│ DTE │RD_ERR │WR_ERR │TOT_ERR│ ││

├──────────┼───────┼───────┼───────┤ ││

│1997-ð1-24│ 7 │ 4 │ 11 │%────────┘│

│1997-ð1-25│ 17 │ 21 │ 38 │%─────────┘

└──────────┴───────┴───────┴───────┘

Figure 15. Cascaded Update

Version 2.04-10

Tab

les

Managing Data Within Tables

After data collection, the tables contain the following data:

Notice that, when you perform this cascaded update, thePERFREP.STATS_D table is updated using only the data entered intothe PERFREP.STATS_H table in the same data collection process.For example, if you start with an empty PERFREP.STATS_D tableand with PERFREP.STATS_H containing some data, then, after datacollection, PERFREP.STATS_D contains the summary of only thedata that you just collected. If you want to include the earliercontents of PERFREP.STATS_H in the summary, use theRECALCULATE statement as discussed in “Managing Data WithinTables.”

Table 10. Contents of the PERFREP.STATS_H Table After Data Collection


1997-01-24 23 7 4 11

1997-01-25 1 10 10 20

1997-01-25 2 7 11 18

Table 11. Contents of the PERFREP.STATS_D TableAfter Data Collection


1997-01-24 7 4 11

1997-01-25 17 21 38

Managing Data Within TablesUse log collector statements to:

■ Delete data from tables. Use the PURGE statement to deletedata from tables. The PURGE statement performs the deletionbased on the criteria you specify with the DEFINE PURGEstatement.



■ Modify data within tables. Use the RECALCULATE statementto correct invalid data. You can also insert and delete rows byusing the RECALCULATE statement.

When you modify data in a table, you can reflect modifications inother tables if they derive data from the first table. For example, youcan change data in the PERFREP.STATS_H table and reflect thechanges in the PERFREP.STATS_D table from the precedingexample.

Deleting DataDelete data from data tables using the PURGE statement. Use thePURGE statement when you want to regularly delete certain data,such as data older than a certain number of days, from the table.

To use the PURGE statement, you must first specify the purgeconditions using the DEFINE PURGE statement. For example, thetable PERFREP.STATS_H stores the read and write errors by date.Assume that you want to delete all data that is more than 14 daysold.

To specify purge condition for the PERFREP.STATS_H table, usethis DEFINE PURGE statement:

DEFINE PURGE FROM PERFREP.STATS_H

WHERE DTE < CURRENT DATE - 14 DAYS;

The WHERE clause identifies the data to be purged (in this case, allrows with date older than 14 days). It must specify a valid SQLsearch condition. Notice that the syntax of an SQL search conditionmight be different for different database managers. For example, thecondition in the example is valid for DB2/6000, but for ORACLEyou specify:

WHERE DTE < SYSDATE - 14;

If you are uncertain which are the valid search conditions, refer toyour database SQL Reference.

Version 2.04-12

Tab

les


To store a purge condition for the PERFREP.STATS_H table,execute the above statement. You can then purge data using thefollowing statement:

PURGE;

Executing PURGE purges data from all tables that have a purgecondition.

To purge data from the PERFREP.STATS_H table only, use thefollowing statement:

PURGE

INCLUDE PERFREP.STATS_H;

When you specify the INCLUDE clause, data is purged only from thetables listed in the clause (and then only if they have a purgecondition).

Changing Data Within TablesUse the RECALCULATE statement to change data that is stored inthe data tables, and then update more tables based on the changedinformation.

Correcting DataAssume that you are verifying the accuracy of the data in thePERFREP.STATS_H table, which contains the following values:

You determine that the number of read errors produced in hour 2 isincorrect. The correct number of read errors should be 4 instead of 7,so the TOT_ERR column is also incorrect. The total errors producedin hour 2 were 15 instead of 18.

Table 12. Contents of the PERFREP.STATS_H Table Before RECALCULATE


1997-01-24 23 7 4 11

1997-01-25 1 10 10 20

1997-01-25 2 7 11 18



Use the following RECALCULATE statement to correct thePERFREP.STATS_H table:

RECALCULATE

UPDATE PERFREP.STATS_H

SET

(RD_ERR = 4,

TOT_ERR = 15)

WHERE

DTE = '1997-ð1-25'

AND HOUR = 2;

In this statement, you specified that you want to change the fieldRD_ERR for the row where DTE is 1997-01-25 and HOUR is 2.After you executed the RECALCULATE statement, thePERFREP.STATS_H table contains the following data:

Notice that in the row where DTE is 1997-01-25 and HOUR is 2,RD_ERR now contains a value of 4 and TOT_ERR contains a valueof 15.

The WHERE clause in the RECALCULATE statement must specifya valid SQL search condition. Notice that the syntax of an SQLsearch condition might be different for different database managers.For example, the condition in the example is valid for DB2/6000, butfor ORACLE with default date format, you specify:

WHERE

DTE = '25-JAN-97'

AND HOUR = 2;

If you are uncertain which are the valid search conditions, refer toyour database SQL Reference.

Assume that you stored an update definition to summarize data fromthe PERFREP.STATS_H table in the PERFREP.STATS_D table, as

Table 13. Contents of the PERFREP.STATS_H Table After RECALCULATE


1997-01-24 23 7 4 11

1997-01-25 1 10 10 20

1997-01-25 2 4 11 15

Version 2.04-14

Tab

les


described in “Updating a Table from Another Table” on page 4-6.The PERFREP.STATS_D table is then also updated to reflect thechanged data and contains now these values:

Table 14. Contents of the PERFREP.STATS_D TableAfter RECALCULATE


1997-01-24 7 4 11

1997-01-25 14 21 35

Deleting and Adding RowsDelete rows from tables or add more rows to tables using theRECALCULATE statement. For example, assume that you want todelete the row where DTE is 1997-01-25 and HOUR is 2. To do so,use the RECALCULATE statement:

RECALCULATE

DELETE FROM PERFREP.STATS_H

WHERE

DTE = '1997-ð1-25'

AND HOUR = 2;

The PERFREP.STATS_D table is also changed. But notice that thischange does not result in rows being deleted from thePERFREP.STATS_D table. Even if you delete all rows for the date1997-01-25 from the PERFREP.STATS_H table, thePERFREP.STATS_D table still contains a row for that date, with allerror counts 0.

You can insert additional rows into a table. For example, assume thatyou want to add the row you just deleted back into thePERFREP.STATS_H table. To do so, use this RECALCULATEstatement:

RECALCULATE

INSERT INTO PERFREP.STATS_H

(DTE, HOUR, RD_ERR, WR_ERR, TOT_ERR)

VALUES (DATE('1997-ð1-25'),2,4,11,15);

When you add a row to a table, you specify the column names andthe data to go into the columns. The columns you do not specify are



set to null. Remember that for some columns, the null value mightnot be valid.

You may omit the column names, but then you must specify valuesfor all columns, in the order they appear in the table.

Version 2.04-16

Up

date D

efinitio

ns

5Advanced Use of UpdateDefinitions

“Getting Started With the Log Collector Language” described how towrite an update definition to collect data from a simple log and storeit in a data table. This chapter describes how to specify morecomplex processing. It tells you how to compute the minimum,maximum, and average values, how to compute percentiles, how todistribute measurements, how to determine resource availability, andhow to summarize availability by schedule period. It also tells youhow to process data from repeated and nested sections.

Determining the Minimum, Maximum, andAverage

The most common way to summarize data is by computing the sumof values contained in the records or table rows. This way was usedin all examples in “Getting Started With the Log Collector Language”on page 2-1 and “Advanced Use of Tables” on page 4-1. Butsometimes you need to know the lowest value, the highest value, orthe average, rather than the sum.

Assume that you want to determine the minimum, the maximum, andthe average amount of CPU time used per job. The records thatcontain information about CPU times are of type JOB_INFO andhave the following layout.


Determining Minimum, Maximum, and Average

A log file containing those records might look like the following:

Table 15. Layout of JOB_INFO Records

Field name Offset Length Description


JOB_ID 8 4 Job identification

JOB_CPU 12 8 CPU seconds used by the job, indecimal notation

DATE JOB_ID JOB_CPU

971ðð1 4546 2.5 971ðð1 5367 1.7 971ðð1 5893 1.9 971ðð1 6192 1.3 971ðð1 7338 1.9 971ðð2 16ðð .8 971ðð2 1775 2.1 971ðð2 199ð 1.4 971ðð2 2222 1.ð 971ðð3 1572 1.1 971ðð3 3193 1.9 971ðð3 4ððð 1.5 971ðð4 1655 1.7

Figure 16. Log File Containing JOB_INFO Records

You want to store the information in a data table calledPERFREP.CPUTAB that has these columns:

Column ContainsDAY The day portion of date, identifying a dayJOB_CNT The number of jobs on that dayMIN_CPU The lowest CPU time used by a job on that dayMAX_CPU The highest CPU time used by a job on that dayAVE_CPU The average CPU time per job

To calculate the lowest, highest, and average CPU time, use thefollowing update definition.

Version 2.05-2

Up

date D

efinitio

ns

Determining Minimum, Maximum, and Average

DEFINE UPDATE CPU_STAT

FROM JOB_INFO

TO PERFREP.CPUTAB

GROUP BY

(DAY = DAY(DATE))

SET

(MIN_CPU = MIN(JOB_CPU),

MAX_CPU = MAX(JOB_CPU),

AVE_CPU = AVG(JOB_CPU, JOB_CNT),

JOB_CNT = COUNT(JOB_CPU));

In this update definition, the records are grouped by the day portionof the DATE field. The lowest and highest value is determined bythese lines:

MIN_CPU = MIN(JOB_CPU),

MAX_CPU = MAX(JOB_CPU),

The MIN and MAX functions obtain, respectively, the lowest and thehighest value of JOB_CPU for all records in the group.

The average is determined by these lines:

AVE_CPU = AVG(JOB_CPU, JOB_CNT)

JOB_CNT = COUNT(JOB_CPU)

The AVG function calculates the average value of JOB_CPU for allrecords in a group. To use the function, you must specify a columnof the table that contains the number of JOB_CPU values in thegroup. Here, you used the column JOB_CNT, with value specified asCOUNT(JOB_CPU).

After data collection, the contents of the PERFREP.CPUTAB tableare:

Table 16. Contents of the PERFREP.CPUTAB Table After Data Collection

DAY JOB_CNT MIN_CPU MAX_CPU AVE_CPU

1 5 1.30 2.50 1.860

2 4 0.80 2.10 1.325

3 3 1.10 1.90 1.500

4 1 1.70 1.70 1.700


Determining Percentiles

Notice that the value of the column specified as the second argumentof the AVG function (like JOB_CNT here) must be defined by meansof either the COUNT function or the SUM function. If you specify acolumn with value defined by means of COUNT, as in this example,the AVG function computes the ordinary average. If you specify acolumn with value defined by means of SUM, the AVG functioncomputes a weighted average. The values specified as the argumentof SUM are then used as the weights.

Determining PercentilesYou can use the DEFINE UPDATE statement to calculatepercentiles. You may need to know, for example, what is the 75thpercentile of response times for a particular application. (The 75thpercentile is a value such that 75% of response times do not exceedthat value, and the remaining 25% are above the value.) The recordsthat contain response times are of type RESP_DATA and have thislayout:

Table 17. Layout of RESP_DATA Records




APPL_ID 16 8 Application name

TRANS_NO 24 4 Transaction number

RESP_TIME 28 8 Response time in seconds, indecimal notation.

Version 2.05-4

Up

date D

efinitio

ns


A log file containing these records might look like this:

DATE TIME APPL TRANS RESP

ID NO TIME

97ð3ð5 ð9ð9ð1 APP_A 1332 .3397ð3ð5 111ð22 APP_A 211ð .9597ð3ð5 1315ðð APP_A 2413 .2497ð3ð5 15ðð2ð APP_A 4ð1ð .9997ð3ð5 164315 APP_A 5121 .7597ð3ð5 1853ð7 APP_A 6567 .5397ð3ð5 19ðððð APP_A 68ðð .4697ð3ð5 2119ð8 APP_A 7548 .3997ð3ð5 2215ðð APP_A 8812 .5797ð3ð5 23ðððð APP_A 9325 .3797ð3ð5 231912 APP_A 9794 .3997ð3ð5 235ð55 APP_A 9794 .25

Figure 17. Log File Containing RESP_DATA Records

You want to determine the 75th percentile of response times for thesetransactions. You want to store the resulting data in a table calledPERFREP.RTIME that has these columns:

Column ContainsDTE A dateAPPL The name of an applicationNUM_RESP The total number of transactions on that day and for

that applicationRESP_75 The 75th percentile of response times for these

transactions



To calculate the 75th percentile, use the following update definition:

DEFINE UPDATE DET_PERT

FROM RESP_DATA

TO PERFREP.RTIME

GROUP BY

(DTE = DATE,

APPL = APPL_ID)

SET

(NUM_RESP = COUNT(RESP_TIME),

RESP_75 = PERCENTILE(RESP_TIME,NUM_RESP,75));

In this update definition, the records are grouped by DATE andAPPL_ID. The 75th percentile is calculated using:

NUM_RESP = COUNT(RESP_TIME)

RESP_75 = PERCENTILE(RESP_TIME,NUM_RESP,75)

The PERCENTILE function calculates the response time that is the75th percentile of all response times within a group. To use thefunction, you must specify a column of the table that contains thenumber of RESP_TIME values in the group. You used here thecolumn NUM_RESP, with value specified as COUNT(RESP_TIME).

The contents of the PERFREP.RTIME table after data collection are:

And indeed, 9 transactions (that is, 75%) out of 12 had responsetimes that do not exceed .57 sec, while the remaining 3 (that is, 25%)had response times above that value.

When using the PERCENTILE function, process all input values atthe same time. Processing input values during different datacollections gives average percentiles of each collection, rather thanone overall percentile.

Table 18. Contents of the PERFREP.RTIME Table AfterData Collection

DTE APPL NUM_RESP RESP_75

1997-03-05 APP_A 12 .57

Version 2.05-6

Up

date D

efinitio

ns

Distributing Measurements

Distributing MeasurementsMany times, you want to determine statistics for a specific period, butyou know the statistics during time intervals that do not coincideexactly with the period. You can use the DISTRIBUTE clause of theDEFINE UPDATE statement to distribute the known statistics evenlyover the periods.

For example, assume that you know the amount of CPU time usedper job. The jobs take several hours and do not start or end on thehour. You want to determine the amount of CPU time used each hour(assuming the CPU time is used at an even rate throughout the job).

The information about the jobs is contained in records of typeCPU_INFO that have the following layout:

A log file containing these records might look like the following:

Table 19. Layout of CPU_INFO Records


JOB_ID 0 8 Name of a job

STA_DATE 8 6 Start date of the job, in the formatyymmdd

STA_TIME 16 6 Start time of the job, in the formathhmmss

END_DATE 24 6 End date of the job, in the formatyymmdd

END_TIME 32 6 End time of the job, in the formathhmmss

CPU_TIME 38 8 Total CPU time used by the job

JOB STA STA END END CPU

ID DATE TIME DATE TIME TIME

JOB123 97ð2ð5 163ððð 97ð2ð5 193ððð 36.ðJOB456 97ð2ð5 2ð45ðð 97ð2ð5 2345ðð 18.ð

Figure 18. Log File Containing CPU_INFO Records



You want to store the result in a table called PERFREP.JOBSTATthat has these columns:

Column ContainsDTE A dateHOUR An hour within that dateCPU_TIME The total CPU time used during that hourUSAGE The total number of seconds that different jobs were

running during that hour

To distribute the job data by hour, use the following updatedefinition:

DEFINE UPDATE DIST_CPU

FROM CPU_INFO

TO PERFREP.JOBSTAT

DISTRIBUTE CPU_TIME

BY 36ðð

START TIMESTAMP(STA_DATE,STA_TIME)

END TIMESTAMP(END_DATE,END_TIME)

TIMESTAMP INTV_START

INTERVAL INTV_LENGTH

GROUP BY

(DTE = DATE(INTV_START),

HOUR = HOUR(INTV_START))

SET

(CPU_TIME = SUM(CPU_TIME),

USAGE = SUM(INTV_LENGTH));

The DISTRIBUTE clause states that you want to distribute intervaldata over certain periods. The clause BY 3600 specifies these periodsas consecutive 1-hour (3600-second) periods starting at midnight. Tospecify the start and end of the interval, you used the START andEND clauses. You specified the start of the interval using theTIMESTAMP function, which produces a timestamp from the startingdate (STA_DATE) and starting time (STA_TIME) fields. Youspecified the end of the interval using the TIMESTAMP function toproduce a timestamp from the ending date (END_DATE) and endingtime (END_TIME) fields.

When the log collector executes the DISTRIBUTE clause, it firstsplits each interval at the period boundaries. Then it generates oneinternal record for each interval resulting from the split.

Version 2.05-8

Up

date D

efinitio

ns


16.3ð 19.3ð

│ │

│%──────────────────── INTERVAL ─────────────────────5│

│ │

│ part 1 │ part 2 │ part 3 │ part 4 │

│%──────5│%───────────────5│%───────────────5│%──────5│

│ │ │ │ │

└────────────────┴─────────────────┴─────────────────┴────────────────┘

16.ðð 17.ðð 18.ðð 19.ðð 2ð.ðð

Figure 19. Splitting the Interval at 1-hour Boundaries

Figure 19 illustrates the process of splitting the interval from the firstCPU_INFO record. When the log collector processes the twoCPU_INFO records, it generates the following internal records:

JOB STA STA END END CPU INTV INTV

ID DATE TIME DATE TIME TIME START LENGTH

JOB123 97ð2ð5 163ððð 97ð2ð5 193ððð 6.ð 1997-ð2-ð5-16.3ð.ðð 18ðð JOB123 97ð2ð5 163ððð 97ð2ð5 193ððð 12.ð 1997-ð2-ð5-17.ðð.ðð 36ðð JOB123 97ð2ð5 163ððð 97ð2ð5 193ððð 12.ð 1997-ð2-ð5-18.ðð.ðð 36ðð JOB123 97ð2ð5 163ððð 97ð2ð5 193ððð 6.ð 1997-ð2-ð5-19.ðð.ðð 18ðð JOB456 97ð2ð5 2ð45ðð 97ð2ð5 2345ðð 1.5 1997-ð2-ð5-2ð.45.ðð 9ðð JOB456 97ð2ð5 2ð45ðð 97ð2ð5 2345ðð 6.ð 1997-ð2-ð5-21.ðð.ðð 36ðð JOB456 97ð2ð5 2ð45ðð 97ð2ð5 2345ðð 6.ð 1997-ð2-ð5-22.ðð.ðð 36ðð JOB456 97ð2ð5 2ð45ðð 97ð2ð5 2345ðð 4.5 1997-ð2-ð5-23.ðð.ðð 27ðð

Figure 20. Internal Records Generated by Measurement Distribution

Each internal record contains the same fields as the original record.The values of fields you have listed after the keyword DISTRIBUTE(CPU_TIME in this case) are distributed proportionally to the lengthof the interval represented by the row. The contents of the remainingfields are copied unchanged from the original record.

Each record also contains two more fields: INTV_START andINTV_LENGTH. They contain, respectively, the start and length ofthe interval represented by the row. You specified the names of thesecolumns using the TIMESTAMP and INTERVAL clauses. (For


Determining Resource Availability

readability, the timestamps in the INTV_START field are shownwithout microseconds.)

Your GROUP BY and SET clauses are applied to the internalrecords, and the result is used to update the data table.

The contents of the PERFREP.JOBSTAT table after data collectionare:

Table 20. Contents of the PERFREP.JOBSTAT TableAfter Data Collection

DTE HOUR CPU_TIME USAGE

1997-02-05 16 6.0 1800

1997-02-05 17 12.0 3600

1997-02-05 18 12.0 3600

1997-02-05 19 6.0 1800

1997-02-05 20 1.5 900

1997-02-05 21 6.0 3600

1997-02-05 22 6.0 3600

1997-02-05 23 4.5 2700

Determining Resource AvailabilityAn important aspect of system performance management is todetermine the availability of a particular resource at any given time,and to summarize the availability during certain periods (such asshifts).

Typically, information about the availability of a resource comesfrom several different sources. For example, you can determine that aparticular resource is available, if that resource is being used by a jobrunning in your system, if the resource is using CPU time, or if it isproducing messages from transactions. If applications are trying touse a particular resource and generating error messages showing thatthey could not use it, the resource is unavailable.

Using the MERGE clause of the DEFINE UPDATE statement, youcan put all this information together to obtain the status of the

Version 2.05-10

Up

date D

efinitio

ns


resource at different times. You may think of this process asreconstructing facts from different pieces of evidence.

This evidence is usually incomplete, or even conflicting, andthe log collector must make assumptions that conform best to thecollected data.

Assume that you want to determine the availability of certainresources (such as database servers), using data stored in log files oftype RES_DATA. A log of type RES_DATA contains records oftype:

■ A, which contain data about jobs using a resource

■ B, which are written when an application attempts to access aresource and receives no answer before the timeout period

■ C, which are created whenever a resource is started by thesystem operator

Records of type A have the following layout:

Table 21. Layout of Type A Records (RES_DATA_A)


REC_TYPE 0 1 Character string A

RESOURCE 2 8 Resource name

START_DATE 12 6 Start date of job using theresource, in the format yymmdd

START_TIME 20 6 Start time of job using theresource, in the format hhmmss

END_DATE 28 6 End date of job using the resource,in the format yymmdd

END_TIME 36 6 End time of job using the resource,in the format hhmmss



Records of type B have the following layout:

Records of type C have the following layout:

Table 22. Layout of Type B Records (RES_DATA_B)


REC_TYPE 0 1 Character string B


DATE 12 6 Date of attempted access, in theformat yymmdd

TIME 20 6 Time of attempted access, in theformat hhmmss

TIMEOUT 28 6 Time, in seconds, that theapplication waited withoutobtaining a response

Table 23. Layout of Type C Records (RES_DATA_C)


REC_TYPE 0 1 Character string C


START_DATE 12 6 Date the resource was started, inthe format yymmdd

START_TIME 20 6 Time the resource was started, inthe format hhmmss

Version 2.05-12

Up

date D

efinitio

ns


A log file containing these records might look like the following:

record 1: C DBSERV1 97ð323 ð1ðððð record 2: A DBSERV1 97ð323 ð4ðððð 97ð323 ð6ðððð record 3: A DBSERV1 97ð323 ð5ðððð 97ð323 ð7ðððð record 4: B DBSERV1 97ð323 ð8ðððð 18ðð record 5: C DBSERV1 97ð323 1ððððð record 6: A DBSERV1 97ð323 13ðððð 97ð323 14ðððð record 7: A DBSERV1 97ð323 142ððð 97ð323 15ðððð record 8: C DBSERV1 97ð323 18ðððð record 9: A DBSERV1 97ð323 182ððð 97ð323 19ðððð

Figure 21. Log File Containing RES_DATA Records

All records in this log contain data about the same resource, namelyDBSERV1, during the same day, namely March 23, 1997. (A lognormally contains data about many resources, and may cover morethan one day.) Reading the log, you can reason as follows to establishthe availability of DBSERV1 at different times:

Record number 1 indicates that DBSERV1 was started at 01.00. Afterthis, it must have been up for at least some short time. Nothing isthen known about DBSERV1 until 04.00.

Record number 2 indicates that a job was using DBSERV1 from04.00 through 06.00, and record number 3 indicates that another jobwas using it from 05.00 through 07.00. These two records togetherprovide evidence that DBSERV1 was up all the time from 04.00 to07.00.

Record number 4 indicates that at 08.00, an application attempted touse DBSERV1 and did not receive any answer for the subsequent 30minutes. This provides evidence that the resource was down from08.00 to 08.30, but you cannot tell exactly when it went down.Record number 5 indicates that the operator restarted DBSERV1 at10.00, but the interval from 08.30 to 10.00 is too long to concludethat DBSERV1 was down all that time.

Records number 6 and 7 indicate that DBSERV1 was up from 13.00to 14.00 and then from 14.20 to 15.00. Although you have nopositive evidence for the 20-minute period between 14.00 and 14.20,



it seems likely that DBSERV1 was up during that time; you mayassume that it was up all the time from 13.00 to 15.00.

Finally, records number 8 and 9 indicate that DBSERV1 wasrestarted at 18.00 and then used from 18.20 through 19.00. Again,you may assume that DBSERV1 was up during the 20-minuteinterval for which you have no positive evidence.

Figure 22 illustrates the availability of DBSERV1 thus obtained fromthe log. A double line (==) represents the resource being up, andcrosses (XX) represent the resource being down. A vertical bar (|)represents a change of status. Blank spaces represent unknown status.

|= ============= XX |= ========= |====

└───┴───┴───┴───┴───┴───┴───┴───┴───┴───┴───┴───┴───┴───┴───┴───┴───┴───┴───┴───┴───┴───┴───┴───┘

ðð ð1 ð2 ð3 ð4 ð5 ð6 ð7 ð8 ð9 1ð 11 12 13 14 15 16 17 18 19 2ð 21 22 23 24

Figure 22. Availability of DBSERV1 Between 00.00 and 24.00 on March 23, 1997

When the log collector processes a RES_DATA log, it works inessentially the same way. At the end, it stores the resultingavailability data in a database table. The table containing this datamight look as follows:

Table 24 (Page 1 of 2). Data Table PERFREP.AVAIL_STATUS: An Example ofAvailability Data

RES_ID TYPE INT_START INT_END QUIET

DBSERV1 1997-03-23-00.00.00 1997-03-23-01.00.00 0

DBSERV1 |== 1997-03-23-01.00.00 1997-03-23-01.00.01 3600

DBSERV1 1997-03-23-01.00.01 1997-03-23-04.00.00 0

DBSERV1 === 1997-03-23-04.00.00 1997-03-23-07.00.00 1800

DBSERV1 1997-03-23-07.00.00 1997-03-23-08.00.00 0

DBSERV1 XXX 1997-03-23-08.00.00 1997-03-23-08.30.00 0

DBSERV1 1997-03-23-08.30.00 1997-03-23-10.00.00 0

DBSERV1 |== 1997-03-23-10.00.00 1997-03-23-10.00.01 3600

Version 2.05-14

Up

date D

efinitio

ns


Table 24 (Page 2 of 2). Data Table PERFREP.AVAIL_STATUS: An Example ofAvailability Data

RES_ID TYPE INT_START INT_END QUIET

DBSERV1 1997-03-23-10.00.01 1997-03-23-13.00.00 0

DBSERV1 === 1997-03-23-13.00.00 1997-03-23-15.00.00 1800

DBSERV1 1997-03-23-15.00.00 1997-03-23-18.00.00 0

DBSERV1 |== 1997-03-23-18.00.00 1997-03-23-19.00.00 1800

DBSERV1 1997-03-23-19.00.00 1997-03-23-24.00.00 0

Each row of the table corresponds to one interval in Table 24 onpage 5-14. The columns INT_START and INT_END contain thestart and end of an interval, stored as timestamps. (For readability,the timestamps are shown without microseconds.) The column TYPEcontains a three-character code representing the interval type. Thiscode is similar to the symbols used in the figure. Table 43 onpage 10-54 lists the possible codes.

The column QUIET contains additional information needed by thelog collector to process evidence that may become available at a latertime. It is used to bridge the gaps, such as those between the logrecords 6 and 7, or 8 and 9. The number in the column is themaximum length, in seconds, of the gap that can be so bridged. Forexample, the number 1800 in the fourth row in Table 24 onpage 5-14 means:

If, in the future, you receive evidence that DBSERV1 was up at anyinstant between 07.00 and 07.00 plus 1800 seconds (that is, between07.00 and 07.30), you may assume it was up all the time between07.00 and that instant.

The number in the column QUIET can be seen as the likely length ofa quiet period when the resource was not used. It cannot provideevidence of its status.

The table in the example contains availability data for only oneresource, but normally such a table contain data for many resources.The column RES_ID would then identify the resource.



To process a RES_DATA log in the described way, and obtain theavailability data shown in Table 24 on page 5-14, you must providesuitable instructions to the log collector. These instructions have theform of three update definitions, one for each record type.

These update definitions might look like the following:DEFINE UPDATE AVAIL_A

FROM RES_DATA_A

TO PERFREP.AVAIL_STATUS

GROUP BY

(RES_ID = RESOURCE)

MERGE

(TYPE = '===',

INT_START = TIMESTAMP(START_DATE,START_TIME),

INT_END = TIMESTAMP(END_DATE,END_TIME),

QUIET = 18ðð);

DEFINE UPDATE AVAIL_B

FROM RES_DATA_B


GROUP BY

(RES_ID = RESOURCE)

MERGE

(TYPE = 'XXX',

INT_START = TIMESTAMP(DATE,TIME),

INT_END = TIMESTAMP(DATE,TIME) + TIMEOUT SECONDS,

QUIET = ð);

DEFINE UPDATE AVAIL_C

FROM RES_DATA_C


GROUP BY

(RES_ID = RESOURCE)

MERGE

(TYPE = '|==',


INT_END = TIMESTAMP(START_DATE,START_TIME) + 1 SECOND,

QUIET = 36ðð);

In each of the three updates, you specified grouping of the records byRESOURCE. As a result, the records are grouped so that each groupconsists of records containing information about the same resource.The MERGE clause is then applied to each such group of records toderive the availability information. Because all three updatedefinitions specify the same target table, the information from allthree types of records is combined together before it is stored in thetable.

Notice that the MERGE clause generates several rows for each group(for example, all rows in PERFREP.AVAIL_STATUS are generated

Version 2.05-16

Up

date D

efinitio

ns


from the same group). In this respect, the MERGE clause is differentfrom the SET clause, which summarizes each group in a single row.

Understanding the MERGE ClauseThe MERGE clause derives from each record an interval similar tothose in the PERFREP.AVAIL_STATUS table. The intervals thusobtained are merged to obtain the final result.

The way the interval is derived from a record depends on the recordtype. A record of type A is evidence that the resource was up fromthe start of a job at START_DATE, START_TIME to the end of thejob at END_DATE, END_TIME. This is represented as an upinterval (===) between these two times. The MERGE clause forrecords of type A specifies that interval like this:

MERGE

(TYPE = '===',


INT_END = TIMESTAMP(END_DATE,END_TIME),

QUIET = 18ðð);

The expressions to the right of the equal signs specify the interval.The first expression specifies the interval type. The second and thethird expression specify the start and end of the interval. The fourthexpression specifies the quiet period. (Notice that the start and end ofthe interval must be specified as timestamps; the TIMESTAMPfunction constructs the timestamp from date and time. Table 43 onpage 10-54 lists the possible interval type codes.)

The names to the left of the equal signs in the MERGE clause arenames of columns in the target table that receive the specified values.These columns are in this case: TYPE, INT_START, INT_END, andQUIET, respectively. They must be the same in all three updatedefinitions.

A record of type B is evidence that the resource was down forTIMEOUT seconds starting at DATE, TIME. This is represented as adown interval (XXX), in this way:



MERGE

(TYPE = 'XXX',

INT_START = TIMESTAMP(DATE,TIME),

INT_END = TIMESTAMP(DATE,TIME) + TIMEOUT SECONDS,

QUIET = ð);

A record of type C is evidence that at START_DATE,START_TIME, the resource changed status from down to up, andthen was up for some time, perhaps 1 second, but possibly muchmore. This is represented as a 1-second interval of type |== with along quiet period:

MERGE

(TYPE = '|==',


INT_END = TIMESTAMP(START_DATE,START_TIME) + 1 SECOND,

QUIET = 36ðð);

Figure 23 illustrates the process of merging the intervals derivedfrom the individual records. A single line (----) in the figurerepresents quiet periods.

records

|=--- 1

=========-- 2

│ =========-- 3

│ │ XX 4

│ │ │ |=--- 5

│ │ │ │ ====-- 6

│ │ │ │ │ ====-- 7

│ │ │ │ │ │ |=--- 8

│ │ │ │ │ │ │ ==-- 9

│ │ │ │ │ │ │ │

6 6 6 6 6 6 6 6 6

merged |=--- =============-- XX |=--- =========-- |====--

└───┴───┴───┴───┴───┴───┴───┴───┴───┴───┴───┴───┴───┴───┴───┴───┴───┴───┴───┴───┴───┴───┴───┴───┘

ðð ð1 ð2 ð3 ð4 ð5 ð6 ð7 ð8 ð9 1ð 11 12 13 14 15 16 17 18 19 2ð 21 22 23 24

Figure 23. Merging of Intervals Derived from the Records

Version 2.05-18

Up

date D

efinitio

ns

Summarizing Availability

Summarizing Availability by Schedule PeriodAfter determining the availability of a resource at different times, youcan summarize it according to schedule periods. You do it using theAPPLY SCHEDULE clause of DEFINE UPDATE statement.

A schedule is a scheme that divides each day into named periods(such as shifts). This scheme is defined by means of system tableCAL_DAY_PERIOD that should be set up when the product isinstalled. The table on your system might contain this information:

The table CAL_DAY_PERIOD defines one schedule for eachcalendar used by your installation. The calendars are internallyidentified by integers, such as 0 or 5. The partition of a day intoperiods depends on theday type of the day. The day types are definedby the system tables CAL_DAY_OF_WEEK andCAL_SPECIAL_DAY, as explained under “DAYTYPE” onpage 9-7.

Table 25. Example of CAL_DAY_PERIOD Table

CALENDARID

DAYTYPE

STARTTIME

ENDTIME

PERIODNAME

0 WORKDAY 00.00.00 08.00.00 NIGHT

0 WORKDAY 08.00.00 17.00.00 PRIME

0 WORKDAY 17.00.00 24.00.00 NIGHT

0 SAT 00.00.00 08.00.00 NIGHT

0 SAT 08.00.00 24.00.00 HOLIDAY

0 SUN 00.00.00 24.00.00 HOLIDAY

0 HOLIDAY 00.00.00 24.00.00 HOLIDAY

5 WORKDAY 00.00.00 09.00.00 NIGHT

5 WORKDAY 09.00.00 18.00.00 PRIME

5 WORKDAY 18.00.00 24.00.00 NIGHT

5 WEEKEND 00.00.00 24.00.00 CLOSED

5 HOLIDAY 00.00.00 24.00.00 CLOSED



Each row in the table CAL_DAY_PERIOD defines one period withinthe day of type DAY_TYPE in the schedule for calendarCALENDAR_ID. The group of rows with the same CALENDAR_IDand DAY_TYPE specify the partitions of one day. For example, aday of type WORKDAY is in the schedule for calendar 0, dividedinto three periods:

■ 00.00 through 08.00, named NIGHT■ 08.00 through 17.00, named PRIME■ 17.00 through 24.00, named NIGHT

See “PERIOD” on page 9-20 for more information about schedules.

Assume that you have a table PERFREP.AVAIL_STATUS,containing availability data as shown in Table 24 on page 5-14.Assume that the work shifts at your installation follow the scheduledefined by the above CAL_DAY_PERIOD table for calendar 0. Youwant to compute the total number of seconds that each resource wasavailable during each shift. You want to store the result in a datatable called PERFREP.AVAIL_BY_SHIFT that has these columns:

Column ContainsDTE A dateSHIFT The name of a shift on that dateRESRCE The name of a resourceUP_TIME The number of seconds the resource was available

during that shift

Assume further that March 23, 1997 is of type WORKDAY.Figure 24 shows the schedule for March 23, 1997 together with theavailability data for that day:

NIGHT PRIME NIGHT

┌───────────────────────────────┬───────────────────────────────────┬───────────────────────────┐

|= ============= XX |= ========= |====

└───┴───┴───┴───┴───┴───┴───┴───┴───┴───┴───┴───┴───┴───┴───┴───┴───┴───┴───┴───┴───┴───┴───┴───┘

ðð ð1 ð2 ð3 ð4 ð5 ð6 ð7 ð8 ð9 1ð 11 12 13 14 15 16 17 18 19 2ð 21 22 23 24

Figure 24. Status of the Resource and the Schedule for March 23, 1997

Version 2.05-20

Up

date D

efinitio

ns


To summarize the availability data by schedule period, use thisupdate definition:

DEFINE UPDATE APPLY_SCHEDULE

FROM PERFREP.AVAIL_STATUS

TO PERFREP.AVAIL_BY_SHIFT

APPLY SCHEDULE FOR CALENDAR ð

TO TYPE, INT_START, INT_END

PERIOD SHIFT

GROUP BY

(DTE = DATE(INT_START),

SHIFT = SHIFT,

RESRCE = RES_ID)

SET

(UP_TIME = SUM(CASE

WHEN SUBSTR(TYPE,2,1) = '='

THEN INTERVAL(INT_START,INT_END)

END));

The APPLY SCHEDULE ClauseWhen executing the update definition shown above, the log collectorfirst creates a temporary internal table. This table is a copy of thesource table, with two modifications:

■ The intervals that cross the boundaries between the scheduleperiods are split at these boundaries.

■ An additional column identifies the period containing theinterval.

You requested creation of the temporary table by means of theselines:

APPLY SCHEDULE FOR CALENDAR ð

TO TYPE, INT_START, INT_END

PERIOD SHIFT

In the first line, you identified the schedule to be used.

In the second line, you specified where to find the availability data.The three names listed after the keyword TO are the names ofcolumns that contain, respectively, the interval type code, the intervalstart, and the interval end.



In the last line, you specified the name for the column added toidentify the period. It is the name appearing after the keywordPERIOD.

The temporary internal table for the availability data of Table 24 onpage 5-14 is shown below. Notice that an interval was split at 17.00.

Table 26. Temporary Internal Table Created by APPLY SCHEDULE

RES_ID TYPE INT_START INT_END QUIET SHIFT

DBSERV1 1997-03-23-00.00.00 1997-03-23-01.00.00 0 NIGHT

DBSERV1 |== 1997-03-23-01.00.00 1997-03-23-01.00.01 1800 NIGHT

DBSERV1 1997-03-23-01.00.01 1997-03-23-04.00.00 0 NIGHT

DBSERV1 === 1997-03-23-04.00.00 1997-03-23-07.00.00 1800 NIGHT

DBSERV1 1997-03-23-07.00.00 1997-03-23-08.00.00 0 NIGHT

DBSERV1 XXX 1997-03-23-08.00.00 1997-03-23-08.30.00 0 PRIME

DBSERV1 1997-03-23-08.30.00 1997-03-23-10.00.00 0 PRIME

DBSERV1 |== 1997-03-23-10.00.00 1997-03-23-10.00.01 1800 PRIME

DBSERV1 1997-03-23-10.00.01 1997-03-23-13.00.00 0 PRIME

DBSERV1 === 1997-03-23-13.00.00 1997-03-23-15.00.00 1800 PRIME

DBSERV1 1997-03-23-15.00.00 1997-03-23-17.00.00 0 PRIME

DBSERV1 1997-03-23-17.00.00 1997-03-23-18.00.00 0 NIGHT

DBSERV1 |== 1997-03-23-18.00.00 1997-03-23-19.00.00 1200 NIGHT

DBSERV1 1997-03-23-19.00.00 1997-03-23-24.00.00 0 NIGHT

Your GROUP BY and SET clauses are applied to the internal table.You specified grouping by date, shift, and resource:

GROUP BY

(DTE = DATE(INT_START),

SHIFT = SHIFT,

RESRCE = RES_ID)

Your SET clause specifies how to compute the total up time for eachshift:

SET

(UP_TIME = SUM(CASE

WHEN SUBSTR(TYPE,2,1) = '='

THEN INTERVAL(INT_START,INT_END)

END));

Version 2.05-22

Up

date D

efinitio

ns

Using Repeated Sections Within Records

The CASE expression tests whether the middle character in TYPE isan equal sign (meaning an up interval). If so, the result of CASE isthe number of seconds between INT_START and INT_END,computed using the INTERVAL function. Otherwise, the result ofCASE is a null value, meaning no data. The SUM function ignoresthe null values; its result is thus the total up time within the shift.

The contents of the table PERFREP.AVAIL_BY_SHIFT after datacollection are:

Table 27. Contents of the PERFREP.AVAIL_BY_SHIFTTable After Data Collection

DTE SHIFT RESRCE UP_TIME

1997-03-23 NIGHT DBSERV1 14401

1997-03-23 PRIME DBSERV1 7201

Using Repeated Sections Within RecordsAs discussed in “Advanced Use of Logs and Records,” records thatcontain sections are a common occurrence. In many records, sectionsare repeated. A repeated section is a section that occurs more thanonce in a record. The number of times a section appears in the recordcan be fixed, or it can be specified by data within the record.

Assume that you want to collect statistics about files processed byyour application. For each file processed, the application writes asection in a FILE_INFO record. The section, called FILE, containsthe file name and the number of bytes processed. The section is 16bytes long. The first FILE section within the record starts at offset18, the second immediately after the first (that is, at offset 34), thethird immediately after the second, and so on. The number of FILEsections in the record is equal to the total number of files, which isstored in a field called NFILE.

The following table shows the structure of FILE_INFO records.



A specific FILE_INFO record may look like the following:

Table 28. Structure of a Record Containing a Repeated Section




NFILE 12 4 Total number of files read, as aninteger in decimal notation

FILE section. Multiple occurrences of this section exist within aFILE_INFO record. Each occurrence is 16 bytes long. The first occurrencestarts at offset 18. The number of occurrences is specified by NFILE.

NAME 0 8 File name

BYTES 8 8 Number of bytes processed in thefile, as an integer in decimalnotation

First FILE Second FILE

┌──────────────┐┌──────────────┐

│ ││ │

DATE TIME NFILE NAME BYTES NAME BYTES

┌────┐┌────┐┌──┐ ┌──────┐┌──────┐┌──────┐┌──────┐

│ │ ││ │ │ ││ ││ ││ │

97ð32ðð65311 2 FILE_A 1254ð9FILE_B 75432 &

│

└────specifies number of FILE sections

Figure 25. Record with Repeated Section

A log file filestat.example containing the FILE_INFO records maylook like the following:

97ð32ðð65311 2 FILE_A 1254ð9FILE_B 75432 97ð32ðð924ðð 1 FILE_C 642ð96 97ð321ð1ðððð 2 FILE_D 37415FILE_E 121899

97ð322151358 2 FILE_F 92496FILE_G 52919

Figure 26. Log File with Repeated Sections

Version 2.05-24

Up

date D

efinitio

ns


Defining a Record with Repeated SectionTo define the record FILE_INFO, use this statement:

DEFINE RECORD FILE_INFO IN LOG FILESTAT

FIELDS

(DATE OFFSET ð LENGTH 6 DATE(YYMMSS),


NFILE OFFSET 12 LENGTH 4 EXTERNAL INTEGER)

SECTION FILE

OFFSET 18

LENGTH 16

NUMBER NFILE

REPEATED

FIELDS

(NAME OFFSET ð LENGTH 8 CHAR,

BYTES OFFSET 8 LENGTH 8 EXTERNAL INTEGER);

Specifying a repeated section is similar to specifying a section that isnot repeated. To identify the section, use the SECTION clause. TheOFFSET clause specifies the offset of the first occurrence of thesection. The remaining occurrences follow immediately one afteranother. The LENGTH clause specifies the length of each occurrence.The NUMBER clause specifies the number of occurrences, in thiscase given by the value in the NFILE field. The keywordREPEATED identifies the section as repeated.

Defining Updates for Records with Repeated SectionsYou control the processing of repeated sections by means of theSECTION clause of DEFINE UPDATE statement.

If you do not code the SECTION clause, the log collector ignores therepeated section. The records are processed in the usual way, butyour definition can access only the stem, which is the part of therecord that consists of all fields outside the repeated sections.

If you code the SECTION clause, the log collector generates aninternal record for each occurrence of the repeated section. Therecord contains all data from that occurrence and all data from therecord stem. The GROUP BY and SET clauses are applied to theseinternal records, not to the original records from the log.



Accessing Data from the Record StemAssume that you want to collect the total number of files processedper day. You want to store the information in a data table calledPERFREP.TOTAL that has these columns:

Column ContainsDTE A dateFILES The number of files processed on that date

The number of files processed by each application is available in thefield NFILE. This field is in the record stem, not in the repeatedsection. To access data in the record stem, use this DEFINEUPDATE statement:

DEFINE UPDATE COUNT_FILES

FROM FILE_INFO

TO PERFREP.TOTAL

GROUP BY

(DTE=DATE)

SET

(FILES=SUM(NFILE));

In this statement, you specified the processing exactly as for recordswithout repeated sections. When the log collector uses this updatedefinition, it ignores the repeated section. The records of thefilestat.example file are processed as if they looked like this:

DATE TIME NFILE

97ð32ðð65311 2 97ð32ðð924ðð 1 97ð321ð1ðððð 2 97ð322151358 2

Figure 27. The Accessible Fields When SECTION Is Not Specified

In your DEFINE UPDATE statement, you specified that the recordsare to be grouped by DATE (specified with the GROUP clause) andthat the total number of files processed per day is to be computed(specified with the SET clause).

Version 2.05-26

Up

date D

efinitio

ns


The results stored in the PERFREP.TOTAL table after collecting datafrom the filestat.example file are:

Table 29. Contents of thePERFREP.TOTAL Table AfterData Collection

DTE FILES

1997-03-20 3

1997-03-21 2

1997-03-22 2

Accessing Data from Repeated SectionsAssume that you want to determine the total number of bytes readeach day. You want to store the information in a data table calledPERFREP.BYTES that has these columns:

Column ContainsDTE A dateBYTES The number of bytes processed on that date

The number of processed bytes is available in the FILE sections ofeach FILE_INFO record. To access data in the repeated section, usethis DEFINE UPDATE statement:

DEFINE UPDATE COUNT_BYTES

FROM FILE_INFO SECTION FILE

TO PERFREP.BYTES

GROUP BY

(DTE=DATE)

SET

(BYTES=SUM(BYTES));

The clause SECTION FILE after record name in this statement statesthat you want to collect data from the FILE sections. When the logcollector uses this update definition, it generates one internal recordfor each occurrence of the FILE section. For the filestat.example file,these internal records are:



DATE TIME NFILE NAME BYTES

97ð32ðð65311 2 FILE_A 1254ð9 97ð32ðð65311 2 FILE_B 75432 97ð32ðð924ðð 1 FILE_C 642ð96 97ð321ð1ðððð 2 FILE_D 37415 97ð321ð1ðððð 2 FILE_E 121899 97ð322151358 2 FILE_F 92496 97ð322151358 2 FILE_G 52919

Figure 28. Internal Records Generated By Update from SECTION FILE

Notice that each record contains all data from one occurrence ofFILE and all data from the record stem. Your GROUP BY and SETclause are applied to these records. In your DEFINE UPDATEstatement, you specified that the records are to be grouped by DATE(specified with the GROUP clause) and that the total bytes processedper day are to be computed (specified with the SET clause).

The results stored in PERFREP.BYTES table after collecting datafrom filestat.example are:

Notice that you cannot collect the total number of processed files justby adding a FILES column to the PERFREP.BYTES table andadding a lineFILES=SUM(NFILE) to the SET clause. The column thusspecified contains the numbers 5, 4, and 4 rather than the correctnumbers 3, 2, and 2. This is because data from the stem is repeatedin several internal records. To collect both the number of files andthe number of processed bytes, you need two update definitions, onewith and one without the SECTION clause.

Table 30. Contents of thePERFREP.BYTES Table AfterData Collection

DTE BYTES

1997-03-20 842937

1997-03-21 159314

1997-03-22 145415

Version 2.05-28

Up

date D

efinitio

ns

Using Nested Sections Within Records

Using Nested Sections Within RecordsRecords often contain sections within sections. These sections arecalled subsections or nested sections. Like sections, nested sectionscan be repeated or nonrepeated.

Assume that you have a record similar to FILE_INFO. This record,called FILE_ERR, contains nested sections within each FILE sectionthat describe errors encountered while processing files.

This table shows the structure of FILE_ERR records:

Table 31 (Page 1 of 2). Structure of a Record Containing Nested Sections




NFILE 12 4 Total number of files read, as aninteger in decimal notation

FILE section. Multiple occurrences of this section exist within a REP_RECrecord. Each occurrence is 20+NERR*8 bytes long. The first occurrencestarts at offset 18. The number of occurrences is specified by NFILE.

NAME 0 8 File name

BYTES 8 8 Number of bytes processed in thefile, as an integer in decimalnotation

NERR 16 4 Number of occurrences of theERROR section within thisoccurrence of FILE, as an integerin decimal notation

ERROR nested section. Multiple occurrences of this section exist within aFILE section. Each occurrence is 8 bytes long. The first occurrence starts atoffset 20. The number of occurrences is specified by NERR.

NREC 0 4 Number of records with error, asan integer in decimal notation



A specific FILE_ERR record might look like Figure 29. Notice thateach occurrence of the FILE section has a different length, dependingon the number of occurrences of the ERROR section contained in it.

Table 31 (Page 2 of 2). Structure of a Record Containing Nested Sections


RC 4 4 Highest return code, as an integerin decimal notation


┌──────────────────────────┐┌──────────────────────────────────┐

│ ││ │

ERROR ERROR ERROR

┌──────┐ ┌──────┐┌──────┐

│ │ │ ││ │

DATE TIME NFILE NAME BYTES NERR NREC RC NAME BYTES NERR NREC RC NREC RC

┌────┐┌────┐┌──┐ ┌──────┐┌──────┐┌──┐┌──┐┌──┐┌──────┐┌──────┐┌──┐┌──┐┌──┐┌──┐┌──┐

│ ││ ││ │ │ ││ ││ ││ ││ ││ ││ ││ ││ ││ ││ ││ │

97ð32ðð65311 2 FILE_A 1254ð9 1 12 2 FILE_B 75432 2 5ð 5 62 1 & & &

│ │ │

│ │ │

│ number of ERROR sections number of ERROR sections

│ in first FILE section in second FILE section

│

number of FILE sections in record

Figure 29. Record with Nested Repeated Sections

A log file ioerr.example containing the FILE_ERR records mightlook like this:

97ð32ðð65311 2 FILE_A 1254ð9 1 12 2 FILE_B 75432 2 5ð 5 62 197ð32ðð924ðð 1 FILE_C 642ð96 ð97ð321ð1ðððð 2 FILE_D 37415 2 5 24 9 17 FILE_E 121899 1 17 397ð322151358 2 FILE_F 92496 1 91 4 FILE_G 52919 2 2 8 1ð 4

Figure 30. Log File with Nested Repeated Sections

Version 2.05-30

Up

date D

efinitio

ns


Defining a Record with Nested SectionsTo define the FILE_ERR record, use the following statement:

DEFINE RECORD FILE_ERR IN LOG IOERR

FIELDS



NFILE OFFSET 12 LENGTH 4 EXTERNAL INTEGER)

SECTION FILE

OFFSET 18

LENGTH 2ð + NERR\8

NUMBER NFILE

REPEATED

FIELDS

(NAME OFFSET ð LENGTH 8 CHAR,

BYTES OFFSET 8 LENGTH 8 EXTERNAL INTEGER,

NERR OFFSET 16 LENGTH 4 EXTERNAL INTEGER)

SECTION ERROR

IN SECTION FILE

OFFSET 2ð

LENGTH 8

NUMBER NERR

REPEATED

FIELDS

(NREC OFFSET ð LENGTH 4 EXTERNAL INTEGER,

RC OFFSET 4 LENGTH 4 EXTERNAL INTEGER);

You specify a nested section like you specify a section. But noticethe IN clause:

SECTION ERROR

IN SECTION FILE

You use the IN clause to identify ERROR as a nested section,occurring in the FILE section. Notice also that the length of eachoccurrence of FILE must be computed from the number ofoccurrences of ERROR within it:

LENGTH 2ð + NERR\8



Accessing Data in Nested SectionsAssume you want to determine the number of records that hadprocessing errors. You want to store the information in a data tablecalled PERFREP.PROERR that has these columns:

Column ContainsDTE A dateREC_ERR The number of records with error on that date

The number of records with errors is available in the ERRORsections of each FILE_ERR record. You can use this DEFINEUPDATE statement to collect the data:

DEFINE UPDATE COUNT_ERRORS

FROM FILE_ERR SECTION ERROR

TO PERFREP.PROERR

GROUP BY

(DTE = DATE)

SET

(REC_ERR = SUM(NREC));

The clause SECTION ERROR after the record name states that youwant to collect data from the ERROR section of FILE_ERR record.When the log collector uses this update definition, it generates oneinternal record for each occurrence of the ERROR section. Forrecords in the ioerr.example log, these internal records are:

DATE TIME NFILE NAME BYTES NERR NREC RC

97ð32ðð65311 2 FILE_A 1254ð9 1 12 2 97ð32ðð65311 2 FILE_B 75432 2 5ð 5 97ð32ðð65311 2 FILE_B 75432 2 62 1

97ð321ð1ðððð 2 FILE_D 37415 2 5 2497ð321ð1ðððð 2 FILE_D 37415 2 9 1797ð321ð1ðððð 2 FILE_E 121899 1 17 3

97ð322151358 2 FILE_F 92496 1 91 497ð322151358 2 FILE_G 52919 2 2 8

97ð322151358 2 FILE_G 52919 2 1ð 4

Figure 31. Internal Records Generated by Update from Nested Repeated Section

Version 2.05-32

Up

date D

efinitio

ns

Accessing Data from Records with Sections

Notice that each record contains all data from:

■ One occurrence of the ERROR section

■ The containing occurrence of the FILE section

■ The record stem

Your GROUP BY and SET clauses are applied to these internalrecords. The contents of the PERFREP.PROERR table after datacollection is:

Table 32. Contents of thePERFREP.PROERR TableAfter Data Collection

DTE REC_ERR

1997-03-20 124

1997-03-21 31

1997-03-22 103

Accessing Data from Records with SectionsWhen you specify processing of a repeated section using theSECTION clause of the DEFINE UPDATE statement, the logcollector generates an internal record for each occurrence of thatrepeated section. Your GROUP BY and SET clauses are then appliedto these internal records, rather than records from the log.

Each internal record contains fields from one occurrence of thespecified repeated section. It also contains fields from all sectionscontaining that occurrence, from the record stem, and from certainnonrepeated subsections.

(Notice that the log collector does not physically construct newrecords. It only selects portions of the original record for processing.So generating the internal records does not result in a performancepenalty.)



As an example, consider this record:

section occurrences

A B(1) B(2) C(1) C(2)

│%───5│%───────5│%──5│%──────────────5│%────────────────────5│

│ │ │ │ │ │

┌─────┬─────┬────┬────┬────┬────┬─────┬─────┬────┬─────┬─────┬─────┐

│ R │ A │ B1 │ D1 │ B2 │ C1 │ E11 │ E12 │ C2 │ E21 │ E22 │ E23 │

└─────┴─────┴────┴────┴────┴────┴─────┴─────┴────┴─────┴─────┴─────┘

Figure 32. Example of a Record with Different Kinds of Sections

The record contains the following sections:

A A nonrepeated section.

B A repeated section that contains a nested nonrepeated section(D).

C A repeated section that contains a nested repeated section (E).

D A nonrepeated section contained in section B. Section D ispresent only in the first occurrence of section B.

E A nested repeated section contained in C. Two occurrences ofsection E are contained in the first occurrence of section C, andthree occurrences of section E are contained in the secondoccurrence of section C.

The different parts of the record are:

R Fields in the record.

A Fields in section A.

B1 Fields in the first occurrence of section B.

B2 Fields in the second occurrence of section B.

C1 Fields in the first occurrence of section C.

C2 Fields in the second occurrence of section C.

D1 Fields in subsection D in the first occurrence of B.

Version 2.05-34

Up

date D

efinitio

ns


E11 Fields in the first occurrence of E in the first occurrence of C.

...

E23 Fields in the third occurrence of E in the second occurrence ofC.

Figure 33 shows the internal records generated by the log collector,depending on the SECTION clause:

Record REC: ┌─────┬─────┬────┬────┬────┬────┬─────┬─────┬────┬─────┬─────┬─────┐

│ R │ A │ B1 │ D1 │ B2 │ C1 │ E11 │ E12 │ C2 │ E21 │ E22 │ E23 │

└─────┴─────┴────┴────┴────┴────┴─────┴─────┴────┴─────┴─────┴─────┘

Update FROM REC: ┌─────┬─────┐

│ R │ A │

└─────┴─────┘

Update FROM REC SECTION B: ┌─────┬─────┬────┬────┐

│ R │ A │ B1 │ D1 │

└─────┴─────┴────┴────┘

┌─────┬─────┬────┬ ─ ─

│ R │ A │ B2 │ │ (subsection D absent)

└─────┴─────┴────┴ ─ ─

Update FROM REC SECTION C: ┌─────┬─────┬────┐

│ R │ A │ C1 │

└─────┴─────┴────┘

┌─────┬─────┬────┐

│ R │ A │ C2 │

└─────┴─────┴────┘

Update FROM REC SECTION E: ┌─────┬─────┬────┬─────┐

│ R │ A │ C1 │ E11 │

└─────┴─────┴────┴─────┘

┌─────┬─────┬────┬─────┐

│ R │ A │ C1 │ E12 │

└─────┴─────┴────┴─────┘

┌─────┬─────┬────┬─────┐

│ R │ A │ C2 │ E21 │

└─────┴─────┴────┴─────┘

┌─────┬─────┬────┬─────┐

│ R │ A │ C2 │ E22 │

└─────┴─────┴────┴─────┘

┌─────┬─────┬────┬─────┐

│ R │ A │ C2 │ E23 │

└─────┴─────┴────┴─────┘

Figure 33. Data Available for Collection, Depending on SECTION Clause

To find out which fields are included in the generated records, youmay use the following method. Represent sections in the record by atree structure as in Figure 34 on page 5-36. The top node representsthe record, and the remaining nodes represent the repeated sections.



Each node includes its nonrepeated subsections. A line such as fromC to E indicates that E is a subsection of C.

┌───────────────┐

│ R + A │

└──────┬─┬──────┘

│ │

┌─────────┘ └─────────┐

│ │

┌───────┴───────┐ ┌───────┴───────┐

│ B + D │ │ C │

└───────────────┘ └───────┬───────┘

│

│

┌───────┴───────┐

│ E │

└───────────────┘

Figure 34. Tree Structure of a Record with Repeated Sections

Your SECTION clause specifies one of the repeated sections. Thisrepeated section is represented by one of the nodes of the tree. Theinternal records generated for this section contain all fields from thesections represented by that node and by all nodes on the pathleading upwards.

Obtaining a Section Occurrence NumberWhen processing any of the internal records generated from arepeated section, you can use the SECTNUM function to identify theoccurrence of each section included in the record. The functionreturns the occurrence number of the specified section within itscontaining section. If you apply the SECTNUM function to anonrepeated section, the result is always either 1 (if the section ispresent) or 0 (if the section is absent).

Figure 35 on page 5-37 shows the result of SECTNUM for differentrecords internal records from the preceding example.

Version 2.05-36

Up

date D

efinitio

ns

Changing and Deleting Update Definitions

┌─────┬─────┬────┬────┐

│ R │ A │ B1 │ D1 │ SECTNUM(A)=1 SECTNUM(B)=1 SECTNUM(D)=1

└─────┴─────┴────┴────┘

┌─────┬─────┬────┬ ─ ─

│ R │ A │ B2 │ │ SECTNUM(A)=1 SECTNUM(B)=2 SECTNUM(D)=ð

└─────┴─────┴────┴ ─ ─

┌─────┬─────┬────┬─────┐

│ R │ A │ C1 │ E11 │ SECTNUM(A)=1 SECTNUM(C)=1 SECTNUM(E)=1

└─────┴─────┴────┴─────┘

┌─────┬─────┬────┬─────┐


└─────┴─────┴────┴─────┘

┌─────┬─────┬────┬─────┐


└─────┴─────┴────┴─────┘

┌─────┬─────┬────┬─────┐


└─────┴─────┴────┴─────┘

┌─────┬─────┬────┬─────┐


└─────┴─────┴────┴─────┘

Figure 35. Result of SECTNUM for Different Internal Records

Changing and Deleting Update DefinitionsAfter you have stored update definitions you can change them:

■ Using the ALTER UPDATE statement.

■ Using the DROP statement to delete the existing definition andusing the DEFINE UPDATE statement to create a new updatedefinition.

Using the ALTER UPDATE StatementYou can use the ALTER UPDATE statement to change a storedupdate definition.



For example, assume you had the following update definition:


FROM RWSTAT_REC

TO PERFREP.RWDATA

GROUP BY

(DTE = DATE,

HOUR = HOUR(TIME))

SET




Assume that R_REC records contain fields that you did not use whenyou defined an update using the record. These fields are:

■ TOTR_ATT contains the total number of read attempts.■ TOTW_ATT contains the total number of write attempts.

You want to collect data from these fields and store it in threecolumns of the PERFREP.RWSTAT table:

Column ContainsRD_ATT The number of read attempts.WR_ATT The number of write attempts.TOT_ATT The total number of read and write attempts.

To store the additional data in columns R_ATT, W_ATT, andTOT_ATT, use these ALTER UPDATE statements:

ALTER UPDATE TOT_ERRS SET RD_ATT = SUM(TOTR_ATT);

ALTER UPDATE TOT_ERRS SET WR_ATT = SUM(TOTW_ATT);

ALTER UPDATE TOT_ERRS SET TOT_ATT = SUM(TOTR_ATT + TOTW_ATT);

When you execute these statements, the additional specifications areadded to the SET clause of the TOT_ERRS update.

Using the DROP StatementYou can use the DROP statement to delete a stored update definition.For example, assume that you wanted to delete the stored updatedefinition TOT_ERRS. To delete the definition, use this statement:

DROP TOT_ERRS;

Version 2.05-38

Up

date D

efinitio

ns


You can also use the DROP statement in combination with theDEFINE UPDATE statement to change a stored definition.

For example, you can make the same change as in the previousexample by executing these statements:

DROP UPDATE TOT_ERRS;


FROM RWSTAT_REC

TO PERFREP.RWDATA

GROUP BY

(DATE = DATE,

HOUR = HOUR(TIME))

SET



TOT_ERR = SUM(R_ERR + W_ERR),

RD_ATT = SUM(TOTR_ATT),

WR_ATT = SUM(TOTW_ATT),

TOT_ATT = SUM(TOTR_ATT + TOTW_ATT));

The statement DROP UPDATE TOT_ERRS deletes the stored definition. ThestatementDEFINE UPDATE TOT_ERRS stores a new definition.

The advantage of this method is that the new DEFINE UPDATEstatement provides a complete documentation of the new definition. Ifyou use ALTER UPDATE, the documentation consists of two parts:the old DEFINE UPDATE statement and the ALTER UPDATEstatement used to modify it. Because of this, the ALTER UPDATEstatement is best suited for making quick temporary changes.


Version 2.05-40

Co

llecting

Lo

g D

ata

6Collecting Log Data

This chapter describes how to control the collection process. It alsodescribes how to collect data from logs that have already beenprocessed and how to use the HEADER clause of the DEFINE LOGstatement to verify the completeness of a log during collection.

Controlling Data CollectionWhen you collect log data, you can control much of the collectionprocess. Using the COLLECT statement, you can control:

■ Which records in a log are processed■ Which tables are updated■ The size of the collect buffer■ How often records are written to the database and a commit is

made■ What happens if an overflow condition occurs during the update

of a table row

Limiting the Collection to Certain RecordsWhen you collect log data, the log collector uses all updates that aredefined for records in the log being collected. For example, if youspecify COLLECT SOME_LOG, the log collector uses all stored updatedefinitions for records in that log and collects data based on thosedefinitions.

Sometimes, you have many record types within a log file and youwant to collect data only from some of these record types. For


Controlling Data Collection

example, assume that SOME_LOG has 5 different record types.Each record type has a field called RC_TPE that has a value from 1to 5 (corresponding to the record type).

To collect data only from records of type 3, use the followingCOLLECT statement:

COLLECT SOME_LOG FROM 'some.file'

WHERE (RC_TPE=3);

During data collection, the log collector processes only those recordswhere the RC_RPE field contains 3.

(To be used in a COLLECT statement, the field RC_TPE must bedefined using the HEADER clause of the DEFINE LOG statement.For more information about using the HEADER clause, see“Verifying Log Data Sets During Data Collection” on page 6-5.)

Including and Excluding Data TablesYou can control which data tables are updated during data collectionby using the INCLUDE and EXCLUDE clauses on the COLLECTstatement. An example in “Advanced Use of Tables” on page 4-1showed how data was collected, stored in a table calledPERFREP.STATS_H, summarized, and then stored in a table calledPERFREP.STATS_D. Assume that you want to collect log data andupdate the PERFREP.STATS_H table, but you do not want to updatethe PERFREP.STATS_D table. Use the following INCLUDE clause:

COLLECT RWINFO_LOG FROM 'some.file'

INCLUDE PERFREP.STATS_H;

When you use the INCLUDE clause, you specify that data will becollected for that table only. No other tables (such as summarytables) are affected by the data collection.

You can also exclude certain tables. For example, if you want tocollect data, but you do not want to update the PERFREP.STATS_Dtable, use the following EXCLUDE clause:


EXCLUDE PERFREP.STATS_D;

Version 2.06-2

Co

llecting

Lo

g D

ata

Controlling Data Collection

You specified that all tables associated with the RWINFO_LOGshould be updated except the PERFREP.STATS_D table.

Using the Percent Sign (%)You can use the percent sign (%) to include or exclude groups oftables. For example, assume you want to update all tables havingnames beginning with PERFREP.STAT, except the tablePERFREP.STATS_D. To do so, use the following COLLECTstatement:


INCLUDE LIKE 'PERFREP.STAT%'

EXCLUDE PERFREP.STATS_D

Controlling When a COMMIT Is MadeYou can use the COMMIT AFTER clause to specify when the logcollectorcommits the changes to the data tables, that is, makes thesechanges permanent. You can specify that the log collector commitsthe changes:

■ When the buffer is full, or■ At the end of log data set processing, or■ After a certain number of records.

For example, assume you want to update the database after every5000 records. To do so, use this COMMIT AFTER clause:


COMMIT AFTER 5ððð RECORDS;

Controlling Buffer SizeFor performance reasons, the log collector collects data from manyrecords in a storage buffer before writing this data to the database. Itwrites the data to the database when the buffer is full, or when itshould commit the changes (for example, after every 5000 records ifso specified using the COMMIT AFTER clause.)


Collecting Data More than Once

The size of the buffer is normally 10 000 000 bytes, but you canchange it using the BUFFER clause of the COLLECT statement. Forexample, to specify a buffer size of 500 000 bytes, use the followingBUFFER clause:


BUFFER SIZE 5ððððð;

The minimum size of the buffer is 10 000 bytes. The maximum sizeof the buffer is limited by the available storage. Notice that the logcollector sometimes needs more buffer space than you specify. Itterminates processing if it cannot obtain that extra space.

Handling OverflowsYou can specify what the log collector does if an overflow conditionoccurs during the update of a table row. An overflow occurs whenthe result of an accumulation function exceeds the capacity of thecolumn intended to receive it.

You can specify that the log collector either continue processing,reinitializing the row that overflowed, or stop processing.

Collecting Data More than OnceSometimes, you may need to collect data again after you havealready updated data tables. However, the log collector keeps track ofthe processed logs to prevent collecting the same data twice. If youtry to collect data from the same log more than once, the logcollector issues a message saying that the log has already beenprocessed. If you need to collect data from a log again anyway, usethe REPROCESS keyword on the COLLECT statement:


REPROCESS;

When you use the REPROCESS keyword, the data that is alreadystored in data tables is not replaced. Instead, new data is added to theexisting data. If you want to start over (store data in an empty datatable), you must first delete the data using SQL, or using a PURGEstatement as discussed in “Deleting Data” on page 4-12. Then youcan reprocess a log and store the data in the data table.

Version 2.06-4

Co

llecting

Lo

g D

ata

Verifying Log Data Sets

Collecting Data from Partially Processed LogsOccasionally, a system failure or other condition might cause thecollection process to halt prematurely. If the log has not beencompletely processed, you can restart the data collection by issuingthe COLLECT statement again. The log collector will beginprocessing data again, starting after the last completely processedrecord.

Verifying Log Data Sets During DataCollection

You can use the DEFINE LOG statement to verify that the log iscomplete.

Assume that you have a log (called SOME_LOG). Although the logcontains many different record types, these fields are common to allrecords:

The log always contains a record of type A (TYPE = 'A') as the firstrecord in the log and a record of type Z (TYPE = 'Z') as the lastrecord.


TYPE 0 1 Record type code

TIME 2 6 Time the record was written, in theformat hhmmss

DATE 8 6 Date the record was written, in theformat yymmdd


Verifying Log Data Sets

Use the following DEFINE LOG statement to define the log:

DEFINE LOG SOME_LOG

HEADER

TYPE OFFSET ð LENGTH 1 CHAR,



TIMESTAMP TIMESTAMP(DATE,TIME)

FIRST RECORD TYPE='A'

LAST RECORD TYPE='Z';

The HEADER clause identifies the fields that are common to allrecords in SOME_LOG. They are defined in the same way that therecord fields were defined in “Describing the Log File and ItsRecords” on page 2-4.

When you collect log data, the log collector checks the FIRSTRECORD and LAST RECORD conditions to determine if this is acomplete and valid log data set. If any of the conditions are notsatisfied, the log collector writes a warning message.

If you specify the TIMESTAMP clause, the log collector stores thetimestamps of the first and last records. It also writes messagescontaining these timestamps, so that you know the time periodcovered by the log file.

In the HEADER clause, identify only the fields that you need. Here,you need to identify DATE, TIME, and TYPE because you use themin the TIMESTAMP, FIRST RECORD, and LAST RECORD clauses.Notice that the header field definitions can only be used in the logdefinition itself, and in the WHERE clause of the COLLECTstatement. If you plan to use these fields in the data collectionprocess, you need to define them again using the DEFINE RECORDstatement.

Version 2.06-6

Lo

g C

ollecto

r Lan

gu

age

7Elements of the Log CollectorLanguage

This chapter introduces basic elements common to all statements:keywords, identifiers, constants, and delimiters. It explains how toenter text in a data set, and how to use blanks and comments toformat and annotate the text.

The chapter also introduces the naming convention for database tablesand AIX files, and describes how you can modify your text usingvariables.

CharactersThe basic symbols of the log collector language are single-byteASCII characters. Within some language elements, you can also entermultiple-byte characters. Unless otherwise stated, all charactersnamed hereafter are single-byte ASCII characters:

■ A letter is one of the characters A through Z and a through z.■ A digit is any of the characters 0 through 9.


Tokens

TokensThe smallest building blocks of the language are tokens. The syntaxdiagrams show the sequence of tokens, rather than individualcharacters. The tokens are of six kinds:

■ Words■ Delimited words■ String constants■ Integer constants■ Floating-point constants■ Delimiters

WordsA word is a letter, optionally followed by zero or more characters,each of which is a letter, a digit, or the underscore character (_).

Examples:

A ABC Length Z_121

Before processing, all lowercase letters in a word are translated touppercase. This means, for example, thatlength, Length, and LENgth

are all interpreted asLENGTH.

The words are used as language keywords and as identifiers. Thekeywords must be entered exactly as specified in the syntaxdiagrams. The identifiers are names you give things you work with.See “Identifiers” on page 7-9 for more information about identifiers.

Delimited WordsA delimited word is a sequence of one or more characters enclosedwithin quotation marks ("). The sequence can contain any characters,but quotation marks can appear only in pairs (""). Any unpairedquotation mark is interpreted as the end of the token.

Examples:

"A 2" "JobClass ""A"""

Before processing, the enclosing quotation marks are removed, andeach pair of quotation marks within the token is replaced by a single

Version 2.07-2

Lo

g C

ollecto

r Lan

gu

age

Tokens

quotation mark. The two examples become thusA 2 and JobClass "A",respectively. Notice that each contains a blank in the middle.

After delimiting, the delimited word is treated the same as a word.Thus, delimited words let you code words that contain charactersother than uppercase letters, digits, and underscore.

A delimited word can contain multiple-byte characters.

The delimited words are used as identifiers. See “Identifiers” onpage 7-9 for more information about identifiers.

String ConstantsA string constant is a sequence of zero or more characters enclosedwithin apostrophes ('). The sequence can contain any characters, butapostrophes can appear only in pairs (''). Any unpaired apostrophe isinterpreted as the end of the token.

Examples:

'A 2' 'a:b' 'JobClass ''A''' ''

A string constant represents the character string obtained by removingthe enclosing apostrophes and replacing each pair of apostrophes witha single apostrophe. The first three constants in the example thusrepresent the stringsA 2, a:b, and JobClass 'A', respectively. Noticethat the first and the third contain a blank in the middle. The lastexample represents the empty string: a sequence of zero characters.

A string constant can contain multiple-byte characters.

The maximum length of a string represented by a string constant is254 bytes.

The string constants are used to specify string values (see “Specifyinga Value Explicitly” on page 8-6) and file names (see “File Names”on page 7-10).


Tokens

Integer ConstantsAn integer constant is a sequence of one or more digits.

Examples:

62 1ðð 32767 72ð176 ðððððððð15

An integer constant represents a whole number in decimal notation.The number must not exceed 2 147 483 647. The maximum length ofthe token is 32 characters.

Floating-point ConstantsA floating-point constant is a sequence of one or more digitsfollowed by a decimal point and zero or more digits, optionallyfollowed by an E and a signed or unsigned number.

Examples:

25.5 1ððð. ð.ð 37589.33333 15E1 2.5E5 2.2E-1 5.E+22

A floating-point constant represents a 64-bit floating-point number.The number is represented in decimal notation, withEnn meaningmultiplied by 10 to power nn. Thus, for example,2.5E5 means2.5×10õ, and 2.2E-1 means 2.2×10-ñ. The specified value is roundedto the closest value that can be represented as a 64-bit floating-pointnumber.

The range of possible values depends on the hardware used to run thelog collector. For RS/6000 machines, the highest value is about1.8E308, and the smallest value different from 0 is about 2.2E-308.

The maximum length of the token is 32 characters.

DelimitersA delimiter is any of these characters or character pairs:

( ) , . ; : + - / \ = < > <> >= <= ||

Version 2.07-4

Lo

g C

ollecto

r Lan

gu

age

Blanks

Input LinesYou enter the log collector language text in a file.

An input line is a portion of the file between two consecutivenew-line characters, not including the new-line characters. Itcorresponds to a line displayed on an editor screen (when you editthe file), or to a printed line (when you print the file).

When the log collector processes your text, it acts as if all input lineswere concatenated into one long string. The only case where a linebreak influences processing is when it terminates a comment line.Otherwise, line breaks are ignored.

Example:

Suppose you entered these lines on the editor screen (both startingfarthest to the left):

'ABC

DEF'

If you ended the first line with a new-line character immediately afterC (no blanks at the end of the line), the log collector interprets this as'ABCDEF'.

BlanksSome tokens cannot be entered immediately one after another,because together, they form another token. For example, you cannotenter the word LENGTH immediately followed by the integer constant 2,because the log collector would treat them as one word,LENGTH2. Toseparate these tokens, enter one or more blanks between them.

Apart from this function of separating tokens, all blanks betweentokens are ignored by the log collector.

The blanks between tokens are allowed, and ignored, even if they arenot needed to separate the tokens. For example, A + B is correct andequivalent toA+B. You normally use blanks to arrange the text so thatit is readable.


Comments

Notice that, contrary to blanks between tokens, blanks within tokensare significant and not ignored.

CommentsTo make your text comprehensible, you can include explanations thatwill be ignored by the log collector. You can enter theseexplanations, or comments, anywhere between tokens. Any sequenceof comments and blanks between tokens is allowed and ignored.Blanks and comments are also ignored before the first and after thelast token. If you wish, you can use a comment instead of blanks toseparate tokens. Comments are of two kinds:

■ Line comments■ Block comments

Line CommentsA line comment is any sequence of characters starting with a doubleminus sign (--) up to the end of the current input line.

Examples:

-- This is a line comment.

-- Another line comment. Notice that it can contain unpaired ' and ".

A comment can contain multiple-byte characters.

Block CommentsA block comment is any sequence of characters starting with slashasterisk (/\) up to the next asterisk slash (\/).

Example:

/\ This is a block comment.

Notice that it can extend over several lines.

It can contain -- and unpaired ' or " \/

A comment can contain multiple-byte characters.

Version 2.07-6

Lo

g C

ollecto

r Lan

gu

age

How Your Text Is Processed

How Your Text Is ProcessedBefore processing your text, the log collector converts it into asequence of tokens. Understanding how this is done might help youwrite the text and interpret messages about syntax errors. The processis illustrated in this example:

Example: The following two lines constitute a fragment of a logcollector statement (each line starts with a blank):

/\ Summarize the data \/

Group By (Job="Job Name"||'ð1') -- By job name with ð1 appended

This fragment is first split into tokens, blanks, and comments:

blanks:

block comment: /\ Summarize the data \/

blanks:

word: Group

blanks:

word: By

blanks:

delimiter: (

word: Job

delimiter: =

delimited word: "Job Name"

delimiter: ||

string constant: 'ð1'

delimiter: )

blanks:

line comment: -- By job name with ð1 appended

Then the blanks and comments are discarded, and words anddelimited words are transformed as described under “Words” onpage 7-2 and “Delimited Words” on page 7-2. The result is thefollowing sequence of tokens.


How Your Text Is Processed

word: GROUP

word: BY

delimiter: (

word: JOB

delimiter: =

word: Job Name

delimiter: ||

string constant: 'ð1'

delimiter: )

This sequence of tokens constitutes the proper input to the logcollector and is specified by syntax diagrams. The syntax diagramspecifying this particular fragment of a statement is:

┌ ┐─,───────────────────5──GROUP BY ──(─ ───

6┴column-name = expression ─)───────────────5

(If you are not familiar with this kind of syntax diagrams, see “Howto Read Syntax Diagrams” on page D-1 for explanation.)

By comparing the sequence of tokens with this syntax, the logcollector recognizes GROUP and BY as keywords, and JOB as an identifier(a column name). Similarly, by using the syntax for expression, itrecognizes Job Name as an identifier. Notice thatJob Name is treated asone word, containing a blank. Notice also that it would make nodifference if you coded "GROUP" (with quotation marks) instead ofGroup.

The log collector always processes the text in one direction. When itcomes to a point where it cannot interpret the next portion of the textas a token, blank, or comment, it never returns to try an alternativeinterpretation, but signals an invalid character, skips the character,and proceeds to identify the next token, blank, or comment. When thelog collector finds that a token does not match the syntax, it does notreturn to try alternatives, but signals an unexpected token. In eachcase, after signaling the error, the log collector skips the rest of thecurrent statement, that is, all tokens up to, and including, the nearestsemicolon token.

Version 2.07-8

Lo

g C

ollecto

r Lan

gu

age

Identifiers

IdentifiersWords and delimited words are mainly used as names of things youwork with: logs, records, fields within records, and so on. When usedin this way, they are called identifiers.

You select the identifiers. By coding an identifier as a delimitedword, you can use any sequence of characters as the name, includingblanks and multiple-byte characters. In general, the only restriction onyour choice of an identifier is that it must not exceed 18 bytes. Hereare more restrictions on identifiers used for specific purposes:

■ The name of a log cannot exceed 16 bytes.

■ The name of a record cannot have the asterisk (*) as both thefirst and the last character.

■ The name of a table column must consist of uppercase letters,digits, and underscore characters. It must start with a letter andmust be distinct from all SQL reserved words.

■ The name of a program cannot exceed 8 bytes.

Remember that in some contexts, an identifier might be confusedwith a keyword. For this reason, do not use the wordsCASE, CURRENT,LOOKUP, NOT, and USER as names of anything you might refer to withinan expression; in particular, do not use them as names of fields in arecord.


File Names

Table NamesThe database tables have names that consist of two identifiersseparated by a period (.). Both identifiers must consist of uppercaseletters, digits, and underscore characters, and each must start with aletter. They must be distinct from all SQL reserved words. The firstidentifier cannot exceed 8 bytes.

Example:

ABC.DAYSTAT_1

The first identifier (ABC in this case) is called the prefix, and the tablename written in this form is called a qualified table name. You canalso code a single identifier as a table name. Such an unqualifiedtable name is implicitly prefixed with the user ID of the user whoruns the log collector. Thus, for example, if your user ID is ABC, thenspecifying DAYSTAT_1 as a table name is equivalent to specifyingABC.DAYSTAT_1.

If not stated otherwise, the term table name anywhere in this bookmeans a qualified or unqualified table name.

File NamesThe names of AIX files are represented by string constant tokens, asdefined under “String Constants” on page 7-3.

Examples:

'/u/romanrr/logs/sample.log'

'john''s.log'

These tokens represent the file names /u/romanrr/logs/sample.logand john's.log, respectively. Notice that the standard AIXconventions apply: the first name, starting with a slash (/), is the fullname of a file; the second is the name within current directory.

If not stated otherwise, the term file name anywhere in this bookmeans a file name written as a string constant, together with theenclosing apostrophes.

Version 2.07-10

Lo

g C

ollecto

r Lan

gu

age

Using Variables to Modify Your Text

StatementsThe input in the log collector language is a sequence of statements.The statements must be separated by semicolons (;). The semicolonsare not considered a part of the statement and are not shown insyntax diagrams.

Using Variables to Modify Your TextSometimes it is convenient to leave certain details open, and fill themin at the last moment. Suppose that you are writing definitions forsome installation, and that you do not know the prefix used for tablenames at that installation. You can then code everything except forthe prefix. Instead of the prefix, you can write a marker that will bereplaced by the prefix at a later time. This marker, called a variablemarker, has the form of an ampersand (&) immediately followed by aword. For example, you can use:

DEFINE UPDATE XYZ FROM &PREFIX.JOBSTAT_D TO ...

Here, the variable marker is &PREFIX. One way to specify the actualprefix is to execute a log collector statement such as:

SET PREFIX='ABC';

As explained in “SET” on page 10-76, this statement defines avariable PREFIX with value ABC. After the SET statement is processed,whenever the log collector encounters the marker &PREFIX, it logicallyreplaces the marker by the value of the variable PREFIX. Thus, yourstatement is processed as if you had used:

DEFINE UPDATE XYZ FROM ABC.JOBSTAT_D TO ..

You can use the variable marker at any place you can use a token. Toproperly terminate it, you might have to follow it with a blank or acomment. Any lowercase letters in the variable marker are translatedto uppercase before the marker is used to identify the variable. Thereplacement string can consist of any number of tokens, blanks,and/or comments.


Using Variables to Modify Your Text

An alternative way to define a variable is to codePREFIX=ABC as a partof the invocation of the log collector. See “Invoking the LogCollector” on page B-1 for details.

If you use variable markers, you fill in the details at the time the logcollector processes your text. If your text is, for example, an updatedefinition, this means that all details are fixed before the definition isstored. Another method, described in “Obtaining the Value of aVariable” on page 8-8, lets you postpone this until the moment whenthe stored definition is actually used.

Version 2.07-12

Valu

es and

Exp

ression

s

8Values and Expressions

This chapter discusses the data items, or values, processed by the logcollector. It introduces the notion of a data type and null value, anddescribes how values are specified by means ofexpressions.

Expressions are important tools for defining what log collector is todo with the data, and are used in almost all statements of the logcollector language. You will in most cases use rather simpleexpressions, consisting of a single identifier or a constant, or perhapstwo such items and an operator. However, you can use theconstructions described here to specify calculations of almost anycomplexity. The only limitation is the size of the expression, whichcannot exceed 2 000 bytes. The size of the internal representation ofthe expression is also limited, which sometimes might limit theexternal form to less than 2 000 bytes. The nesting depth of certainstructures (such as parentheses) is also limited, but you are unlikelyto reach those limits.

An expression that specifies a truth value (that is, one of the valuestrue and false) is called a condition.

This chapter does not cover everything about expressions.“Functions” on page 9-1 discusses the special case of an expressioncalled a function call.


Data Types

Data TypesThe main task of the log collector is to process data. The smallestunit of data processed by the log collector is called a value. A valuemay be obtained, for example, from a field in a record, from adatabase table, stated explicitly in your definition, or computed fromother values. The values handled by the log collector are:

■ Integers, such as 5, 0, or -127■ Floating-point numbers, such as 3.333 or 1.5×107

■ Character strings, such as xy%(?z or ABC■ Dates, such as April 15, 1997■ Times, such as 16 hours 32 minutes 55.123456 seconds■ Timestamps, such as 16 hours 32 minutes 55.123456 seconds on

April 15, 1997■ Truth values, such as false

These seven kinds are called data types. For convenience, the integersand floating-point numbers are together called numbers, or numericvalues. The dates, times, and timestamps are together called date/timevalues.

IntegersAn integer is a whole number in the range −2 147 483 648 to+2 147 483 647.

Floating-point NumbersA floating-point number is a number that can be represented as a64-bit floating-point number. The range of numbers that can be thusrepresented depends on the hardware used to run the log collector.For RS/6000 machines, the numbers can have absolute values up toabout 1.8×10308. The smallest absolute value different from 0 that canbe represented is about 2.2×10−308.

Version 2.08-2

Valu

es and

Exp

ression

s

Data Types

Character StringsA character string, or string, is a sequence of 0 to 254 bytes. It cancontain multiple-byte characters. The length of the string is thenumber of bytes in the sequence. The string of length 0 is called theempty string.

DatesA date is a three-part value (day, month, year) designating a dayaccording to the Gregorian calendar. The range of the year part is 1to 9 999. The range of the month part is 1 to 12. The range of theday part is 1 to x, where x depends on the month.

All computations on dates are performed as if the Gregorian calendarhad been in effect since year 1.

TimesA time is a four-part value (hour, minute, second, and microsecond)designating a time of day under a 24-hour clock. The range of thehour part is 0 to 24, the range of the minute and second part is 0 to59, and the range of the microsecond part is 0 to 999 999. If the houris 24, the remaining parts must be 0.

TimestampsA timestamp is a seven-part value (year, month, day, hour, minute,second, and microsecond) that designates a point in time: a day and atime on that day. The year, month, and day designate the day asspecified under “Dates.” The hour, minute, second, and microseconddesignate the time as specified under “Times.”

Truth ValuesA truth value is one of the values true and false.


Missing and Invalid Data

Missing and Invalid DataIn some situations, the value specified by your definition cannot beobtained. For example, you specify a value from a field in a record,but the record is too short to contain the field; or the record sectionthat should contain the field is absent; or the field is present butcontains invalid data.

It also happens that the value has been obtained from a field, but youspecified an operation on it that cannot be performed. For example,you specified that you want the result of dividing the value from afield A by the value from a field B. If this second value happens tobe 0, the requested result cannot be obtained; you cannot divide by 0.

Null ValueFor the purpose of specifying what to do with data, it is convenientto treat an absence of data as just another value, distinct from allother values handled by the log collector. This special value is calledthe null value.

The null value is useful because whenever you specify that a valueshould be obtained in some way, you can be sure that you alwaysobtain a value (sometimes null, and sometimes not). You need nottreat separately the cases of data being present and data being absent.

The rules of the log collector language specify exactly when theresult of each action is null. For example, the value obtained from anabsent or an invalid field is null, the result of division by 0 is null,and so on. The rules also specify what happens when an operationhas null as one of the arguments. For example, the result of additionor multiplication is null whenever one of the operands is null. Otheroperations, such as SUM or MAX, just ignore null operands. Theserules correspond to the way you normally understand absence of data.(For example, if you do not have the value A or B, you do not haveA+B either.) If the rules do not suit your purpose, you can alwaysreplace a null value by a default. You can use the VALUE functionfor this purpose. (See “VALUE” on page 9-36.)

Version 2.08-4

Valu

es and

Exp

ression

s

Missing and Invalid Data

Remember that the null value is not the same as the empty string.The former is an absence of data; the latter is a well-defined dataitem, namely a string of 0 bytes.

Unknown Truth ValueIf you specify a test such as A>1ð, and you do not have A (that is, A isnull), you cannot decide whether the result of the test is true or false.You simply do not have any result. This absence of a truth value hasslightly different consequences than absence of other kinds of value.It is therefore not represented by a null value, but by a new valuecalledunknown. You can regard it as a third truth value besides trueand false.

If you do not use the logical operator NOT, you may treat unknownas equivalent to false. This is so because whenever a truth value isused, the outcome depends only on whether the value is true or nottrue.

If you use the operator NOT, however, you cannot treat these valuesas equivalent. This is so because NOT(false)=true, whileNOT(unknown)=unknown.

Error HandlingSometimes the null value results from situations that are normal, suchas on absent field or absent section. Other times the null value resultsfrom errors, such as invalid data or a violation of language rules.

If the log collector obtains the null value as the result of an error,you are notified in some way that there was an error. The notificationdepends on the statement that detected the error. For example, theCOLLECT statement issues a message that values were set to nullbecause of error; the LIST RECORD statement represents the nullvalue resulting from an error in a special way.

Some errors are detected at an early stage, before they can result inthe null value. For example, if you by mistake write 15/ð in yourdefinition, you get an error message, and your definition is notaccepted. Notice, however, that not all errors of this kind are detectedearly. For example, if you codeTIMESTAMP('ðð.ðð.ðð.ðððððð'), the log


Simple Ways of Specifying a Value

collector does not detect the error (time string instead of timestampstring) until it uses your definition and tries to evaluate theTIMESTAMP function.

Some Simple Ways of Specifying a ValueThis section discusses two ways in which you can specify a value:

■ Write the value explicitly

■ Write the name of the value, or of something that holds thevalue

These are the simplest forms of an expression. Notice that a truthvalue cannot be specified in either of these ways. It can only becomputed from other values.

Specifying a Value ExplicitlyYou can specify a value explicitly by writing an integer constant, afloating-point constant, or a string constant. For example:

72ð176 2.2E-1 'JobClass ''A'''

(For more information about constants, see “Tokens” on page 7-2.)

Using the integer constant or floating-point constant alone, you canonly represent non-negative numbers. To represent a negativenumber, use the minus operator (-) in front of the constant. See“Arithmetic Operations” on page 8-13.

Notice that you cannot explicitly write a date/time value or a truthvalue, because there are no date/time constants or truth constants. Towrite a specific date/time value, use a function and a date/time string,as explained in “Date/Time Strings” on page 8-9. To write a specifictruth value, use a comparison involving two constants, such as ð=ð.See “Comparisons” on page 8-16.

Version 2.08-6

Valu

es and

Exp

ression

s


Specifying a Value Using an IdentifierThe most common way to specify a value is to write an identifier.(For more information about identifiers, see “Tokens” on page 7-2and “Identifiers” on page 7-9.) The identifier is usually the name ofsomething that holds a value, such as a field in a record, or a columnin a database table. (See Table 42 on page 10-37 for detailedinformation on how the value is obtained from a field in a record.See “Storing and Retrieving Database Data” on page C-1 for detailedinformation on how the value is obtained from a column in adatabase table.)

The identifier can also be the name of the value itself, such as avalue defined by means of a LET clause of the DEFINE UPDATEstatement.

Whenever a syntax diagram of a statement specifies an expression,the description of the statement indicates which identifiers areallowed in that expression. For example, in the DEFINE RECORDstatement, the expression defining the offset of a section may onlycontain names of fields in certain previously defined sections. If youspecify another name (for instance, a name that is not used in thedefinition, or the name of a section in the record, or the name of afield that cannot be referenced), you get an error message stating thatthe name is unknown, or that you cannot use it in this context.

Some expressions cannot contain any identifiers, for example, theexpression following the keyword PARM in the statements DEFINELOG and DEFINE RECORDPROC. If you use an identifier there,you get an error message stating that the name is unknown.



Obtaining the Value of a VariableAs explained in “SET” on page 10-76, you can define a namedstring, called a variable, by executing a log collector statement suchas:

SET SYSTEM_ID = 'server_17';

This statement defines the variable SYSTEM_ID having valueserver_17.The variable remains defined, with its value unchanged, until the endof the current log collector run, or until you change its value byexecuting another SET statement. (An alternative way of defining avariable is to codeSYSTEM_ID=server_17 as a part of the invocation oflog collector. See “Invoking the Log Collector” on page B-1 fordetails.)

You can obtain the value of a variable by coding a variablereference. A variable reference consists of a colon (:) followed by thevariable name, for example, :SYSTEM_ID.

Using a variable reference has the effect of modifying your storeddefinition just before it is used. Suppose you have stored an updatedefinition containing the fragment:

SYSID = :SYSTEM_ID

If you execute a COLLECT statement using this update definition,this fragment has the same effect as if you have codedSYSID = 'server_17' (assuming the variable was defined as in theexample above).

A variable reference, being a special case of expression, can be usedonly where of an expression is allowed. Another way to modify yourstatements uses variable markers. It is described under “UsingVariables to Modify Your Text” on page 7-11. That method lets youreplace any part of your text, not only an expression. However,variable markers modify the text when your definition is stored; byusing a variable reference, you postpone the modification until thedefinition is used.

Version 2.08-8

Valu

es and

Exp

ression

s

Date/Time Strings

Obtaining Current Date, Time, or UserThe log collector maintains a timestamp identifying the time when itstarted the execution of the current statement. You can obtain thistimestamp, or the date or time part of it, by writing one of these pairsof keywords:

CURRENT DATE

CURRENT TIME

CURRENT TIMESTAMP

The values thus specified are of type date, time, and timestamp,respectively. Notice that because these values correspond to the startof the current statement, you obtain the same value every time youuse these keywords within the same statement.

The log collector also has access to the user ID of the user running it.You can obtain this user ID by writing:

USER

The value specified by this keyword is a character string of length 8.

Date/Time StringsAs explained in “Specifying a Value Explicitly” on page 8-6, youcan specify an integer, a floating-point number, or a character stringby writing a constant of the corresponding kind. This method cannotbe used for date/time values; there are no date/time constants. Towrite specific date/time values, you must code expressions such as:

DATE('1997-ð6-27')

TIME('1ð.32.55.123456')

TIMESTAMP('1997-ð6-27-1ð.32.55.123456')

These expressions are specific cases of function calls, discussed in“Functions” on page 9-1. The character strings1997-ð6-27,1ð.32.55.123456, and 1997-ð6-27-1ð.32.55.123456 are examples ofdate/time strings. Date/time strings are character strings of a specificformat:

■ A date string is a character string that represents a date in theform yyyy-mm-dd whereyyyy is the year,mm is the month, anddd is the day.


Date/Time Strings

■ A time string is a character string that represents a time in theform hh.mm.ss.uuuuuu, wherehh is the hour,mm is the minute,ss is the second, anduuuuuu is the microsecond.

■ A timestamp string is a character string that represents atimestamp in the formyyyy-mm-dd-hh.mm.ss.uuuuuuwhere yyyy, mm, dd, hh, mm, ss,anduuuuuu are as above.

The DATE function converts a date string to a date. The expressionsuch as DATE('1997-ð6-27') specifies the result of such conversion,here, the date June 27, 1997. In a similar way, the TIME functionconverts a time string to a time, and TIMESTAMP converts atimestamp string to a timestamp. The expressionTIME('1ð.32.55.123456') specifies thus the time 10 hours 32 minutes55.123456 seconds, and the expressionTIMESTAMP('1997-ð6-27-1ð.32.55.123456') specifies the timestamp 10hours 32 minutes 55.123456 seconds on June 27, 1997.

In some special cases, you may code a date/time string instead of adate/time value, and the log collector will automatically perform theconversion for you. For example, if CREATION_DATE specifies a date,you may code CREATION_DATE<'1997-ð8-25'. As described in“Comparisons” on page 8-16, the log collector will thenautomatically convert the date string to a date, and compare the resultwith the date specified by CREATION_DATE. The information on such anautomatic conversion is found in the description of the operation thatimplies it.

You will most likely use date/time strings to write specific date/timevalues. But notice that these strings are more than a substitute fordate/time constants; all that was stated earlier also applies todate/time strings obtained as a result of your processing, not onlythose specified as constants.

Version 2.08-10

Valu

es and

Exp

ression

s

Labeled Durations

Labeled DurationsA labeled duration specifies a number of time units, for example, 2hours, or 15 minutes. It is used for incrementing or decrementingdate/time values. (See “Incrementing and Decrementing Date/TimeValues” on page 8-14.) It is also used to specify the rounding factorfor the ROUND function. (See “ROUND” on page 9-25.) Notice thata labeled duration by itself does not specify any value.

The syntax of labeled duration is:

5──┤ count ├─ ──┬ ┬─YEAR ─────── ───────────────────────────5 ├ ┤─YEARS ────── ├ ┤─MONTH ────── ├ ┤─MONTHS────── ├ ┤─DAY ──────── ├ ┤─DAYS ─────── ├ ┤─HOUR ─────── ├ ┤─HOURS ────── ├ ┤─MINUTE────── ├ ┤─MINUTES───── ├ ┤─SECOND────── ├ ┤─SECONDS───── ├ ┤─MICROSECOND── └ ┘─MICROSECONDS─

count:├─ ──┬ ┬─constant ──── ──────────────────────────────────────┤ ├ ┤─identifier ── ├ ┤─function ──── └ ┘─(expression)─

constantIs a constant that explicitly specifies a value. See “Specifying aValue Explicitly” on page 8-6.

identifierIs the name of a value or of something that holds a value. Itspecifies that value. See “Specifying a Value Using an Identifier”on page 8-7.


Using Operators

functionIs a function call. It specifies the result of a function. See“Functions” on page 9-1.

(expression)Specifies the value of expression. See “Expressions” onpage 8-27.

The count must specify a number. If this number is a floating-pointnumber, it is converted to an integer by discarding the fractional part.

Examples:

2 YEARS

X DAYS

(N/6ð) MINUTES

Using Operators“Some Simple Ways of Specifying a Value” on page 8-6 describeshow you can specify a value either by writing it explicitly, or bywriting its name. You can also specify a value by modifying orcombining other values. This section discusses how to specify newvalues by means of:

■ Arithmetic operations on numbers■ Incrementing and decrementing date/time values■ Concatenating strings■ Comparisons■ Pattern matching■ Logical operations on truth values

All these operations are specified by means of an operator writtenbetween the operands (an infix operator), or in front of an operand (aprefix operator). “Functions” on page 9-1 describes a much greatervariety of operations, using another format.

Version 2.08-12

Valu

es and

Exp

ression

s

Using Operators

Arithmetic OperationsYou can apply the prefix operators plus (+) and minus (-) to anynumeric value.

Examples:

-DOWN_TIME +4ð -23.456 -1E8

The result is of the same type as the operand. The prefix plus doesnot change its operand. The prefix minus reverses the sign of itsoperand.

You can apply any of the infix operators plus (+), minus (-), multiply(\), and divide (/), to any pair of numeric values.

Examples:

A+B N_DATASETS-5 COUNT\1E-6 RESP_TIME/6ð

The result depends on the operand types:

■ If both operands are floating-point numbers, the result is afloating-point number. The operation is performed usingfloating-point arithmetic.

■ If one of the operands is an integer and the other afloating-point number, the integer is converted to afloating-point number. The operation is then performed on theresult of the conversion, using floating-point arithmetic. Theresult is a floating-point number.

■ If both operands are integers, the result is an integer. Theoperation is performed using integer arithmetic. The division isperformed so that the remainder has the same sign as thedividend.

Notice that the result of dividing an integer by another integer isalso an integer. Thus, for example, if RESP_TIME is an integer lessthan 60, the result of RESP_TIME/6ð is 0. If you want the exactresult, you may writeRESP_TIME/6ð.ð instead. The divisor is thenthe floating-point number 60.0; the left-hand operand,RESP_TIME,is converted to a floating-point number, and the result is afloating-point number.


Using Operators

For all operators (both prefix and infix), the result is null if any ofthe operands is null. If the result is an integer, the result must bewithin the range of integers. If the result is a floating-point number,the result must be within the range of floating-point numbers. Thedivisor of a divide operator must not be 0.

Incrementing and Decrementing Date/Time ValuesYou can modify a date/time value by adding or subtracting aspecified number of time units. The operation is expressed by meansof an infix operator plus (+) or minus (-). The left-hand operand isthe date/time value. The right-hand operand must be a labeledduration. (See “Labeled Durations” on page 8-11.)

Examples:

CURRENT DATE + 2 MONTHS

INTV_END - X SECONDS

JOB_START + (N/6ð) MINUTES

These expressions specify, respectively: the date 2 months from now,the time X seconds before the time INTV_END, and the timestampN/6ð minutes after the timestamp JOB_START.

The number of time units specified by the labeled duration can benegative or 0. Adding a negative number of units is the same assubtracting that number of units. Subtracting a negative number ofunits is the same as adding that number of units.

The result of the operation is null if the date/time value is null, or ifthe count in the labeled duration is null.

Incrementing and Decrementing DatesIf the left-hand operand is a date, the right-hand operand must be alabeled duration of years, months, or days. The result is a date.

Adding or subtracting a number of years affects the year part of thedate. The month is unchanged, and so is the day unless the resultwould be February 29 of a non-leap year. In that case, the day ischanged to 28.

Adding or subtracting a number of months affects the month and, ifnecessary, the year. For the purpose of this operation, a month is the

Version 2.08-14

Valu

es and

Exp

ression

s

Using Operators

equivalent of a calendar page. Adding or subtracting months is liketurning the pages of a calendar. The day part is unchanged unless theresult would be invalid (September 31, for example). In that case, theday is changed to the last day of the month.

Adding or subtracting a number of days affects the day and, ifnecessary, also the month and year.

The result must be within the range of dates.

Incrementing and Decrementing TimesIf the left-hand operand is a time, the right-hand operand must be alabeled duration of hours, minutes, seconds, or microseconds. Theresult is a time with an hour part in the range from 0 to 23.

Any overflow or underflow from the hour part is discarded.

Incrementing and Decrementing TimestampsIf the left-hand operand is a timestamp, the right-hand operand can bea labeled duration of any units. The result is a timestamp with anhour part in the range from 0 to 23.

Adding or subtracting a number of years, months, or days affects thedate part as described in “Incrementing and Decrementing Dates” onpage 8-14. Adding or subtracting a number of hours, minutes,seconds, or microseconds can cause an overflow or underflow fromthe hour part. This overflow or underflow is carried on to the daypart and affects the date part in the same way as adding orsubtracting a number of days.

The result must be within the range of timestamps.

Concatenating StringsYou can concatenate strings using two vertical bars (||) as an infixoperator.

Example:

JOB_NAME || 'ð1'

The result is a character string. The length of the result cannot exceed254. If any of the strings being concatenated is null, the result is null.


Using Operators

ComparisonsYou can compare two values using one of the infix operators equal(=), not equal (<>), greater than (>), less than (<), greater than or equal(>=), less than or equal (<=). The result is a truth value. If one of thecompared values is null, the result is unknown.

Examples:

A>1ð JOB_NAME<'ABC' DATE<>'1997-ð4-15'

Numbers may be compared with numbers. Character strings may becompared with character strings and date/time values. Date/timevalues may be compared with character strings or date/time values ofthe same type. No other comparisons are allowed.

Numbers are compared by their algebraic value.

■ If both numbers are floating-point, they are compared using afloating-point operation. Two floating-point numbers areconsidered equal only if their normalized forms have identicalbit configurations.

■ If one of the numbers is an integer and the other a floating-pointnumber, the integer is converted to a floating-point number. Thecomparison is then performed with the result of the conversion.

Character strings are compared byte by byte, left to right. If thestrings are not of the same length, the comparison is made with atemporary copy of the shorter string that has been padded on the rightwith blanks so that it has the same length as the other string.

Two strings are equal if they are both empty or if all correspondingbytes are equal. Otherwise, their relation is determined by thecomparison of the first unequal pair of bytes.

When a character string is compared with a date/time value, it mustbe a valid date/time string of the corresponding kind. The string isconverted to a date/time value and the comparison is performed onthe result.

All comparisons of date/time values are chronological; the valuerepresenting the later time is considered to be greater.

Version 2.08-16

Valu

es and

Exp

ression

s

Using Operators

Because the hour part may be 0 or 24, certain pairs of differenttimestamps represent the same time. When such timestamps arecompared, the one with a greater date part is considered greater. Forexample, the result of this comparison is true:

TIMESTAMP('1985-ð2-23-ðð.ðð.ðð.ðððððð')>TIMESTAMP('1985-ð2-22-24.ðð.ðð.ðððððð')

(Notice, however, that the INTERVAL function computes the intervalbetween these timestamps as 0.)

Pattern MatchingYou can use the infix operator LIKE to test whether a string matches agiven pattern. This operator can be used only within a lookupexpression. (Pattern matching can also be specified in the INCLUDEor EXCLUDE clause of certain statements.)

Examples:

JOB_NAME LIKE '%A_CD'

SYSTEM_ID LIKE 'BU%'

Both operands must be character strings. The left-hand operand is thestring being tested. The right-hand operand is the pattern.

The result is a truth value. The result of the operation is true if thestring matches the pattern. The result is false if the string does notmatch the pattern. The result is unknown if the string or the pattern isnull.

The string matches the pattern if it can be divided into substrings ofzero or more characters, matching the consecutive characters of thepattern in such a way that:

■ Each percent sign in the pattern is matched by a sequence ofzero or more arbitrary characters in the string.

■ Each underscore character in the pattern is matched by anarbitrary character in the string.

■ All other characters in the pattern are matched by identicalcharacters in the string.


Using Operators

If the pattern is an empty string, the only string matching it is theempty string. Notice that empty string also matches a patternconsisting of one or more percent signs.

Examples:

The string ABCAXCD matches the pattern%A_CD. The required partition is:

ABC A X C D

| | | | |

% A _ C D

Another string matching this pattern isABCD:

A B C D

| | | | |

% A _ C D

The stringsAB, XYZCD, and AXYCD do not match the pattern.

Multiple-byte characters are not recognized in pattern matching.

Logical OperationsYou can apply the prefix operator NOT to any truth value. The resultis defined as follows for operand p:

Table 33. Logical Operation NOT

p NOT p

True False

False True

Unknown Unknown

Version 2.08-18

Valu

es and

Exp

ression

s

Testing for Null

You can apply the infix operators AND, OR to any pair of truthvalues. The result is defined as follows for operands p and q:

Table 34. Logical Operations AND and OR

p q p AND q p OR q

True True True True

True False False True

True Unknown Unknown True

False True False True

False False False False

False Unknown False Unknown

Unknown True Unknown True

Unknown False False Unknown

Unknown Unknown Unknown Unknown

Testing for NullBecause the result of any comparison involving a null value isunknown, you cannot use a comparison operator to test whether agiven value is null. To test whether a value is null, you can code thekeywords IS NULL or IS NOT NULL

after it.

Examples:

JOB_NAME IS NULL

START_TIME IS NOT NULL

The result is true or false depending on whether the tested value isnull. The value being tested must not be a truth value.


Case Expressions

Case ExpressionsA case-expression specifies a value selected by testing one or moreconditions. It has this format:

┌ ┐───────────────────────────────────5──CASE ─ ───

6┴─WHEN ──condition ──THEN ──expression ─ ───────────5

5─ ──┬ ┬───────────────── ─END ─────────────────────────────5 └ ┘ ─ELSE ──expression ─

WHEN condition THEN expressionDefines one of the possible cases. The case is applicable if thevalue of condition is true. The result of the case-expression isequal to the result of expression in the applicable case. If severalcases are applicable, the result is defined by the first of them. Ifnone of the cases is applicable, the result of case-expression isdefined by the ELSE clause.

The expressions in all case definitions must specify values of thesame type.

ELSE expressionDefines the result of the case-expression if none of the cases isapplicable. The result of the case-expression is then equal to theresult of expression. If the ELSE clause is absent, the result isnull.

The expression in the ELSE clause must specify a value of thesame type as expressions in the case definitions.

Version 2.08-20

Valu

es and

Exp

ression

s

Case Expressions

An alternative form of case-expression is:

5──CASE ──expression ──────────────────────────────────────5

┌ ┐────────────────────────────────────5─ ───

6┴─WHEN ──expression ──THEN ──expression ─ ────────────────5

5─ ──┬ ┬───────────────── ─END ─────────────────────────────5 └ ┘ ─ELSE ──expression ─

CASE expressionThe expression is evaluated and the result is compared withresults of expressions appearing in the WHEN clauses.

WHEN expression THEN expressionDefines one of the possible cases. The case is applicable if theresult of the expression following WHEN is equal to the result ofthe expression appearing in the CASE clause (and neither of themis null). The result of the case-expression is equal to the result ofthe expression appearing after THEN in the applicable case. Ifseveral cases are applicable, the result is defined by the first ofthem. If none of the cases is applicable, the result ofcase-expression is defined by the ELSE clause.

All expressions following WHEN must specify values of the sametype as the expression in the CASE clause. All expressionsfollowing THEN must specify values of the same type (but notnecessarily the same as the expressions following WHEN).

ELSE expressionDefines the result of the case-expression if none of the cases isapplicable. The result of the case-expression is then equal to theresult of expression. If the ELSE clause is absent, the result isnull.

The expression in the ELSE clause must specify a value of thesame type as expressions following THEN.


Lookup Expressions

Examples:

CASE

WHEN X='A12' THEN 1

WHEN Y>'BCD' THEN 2

ELSE ð

END

If X has the value A12, the result is 1; otherwise, if Y has a valuegreater than BCD, the result is 2; otherwise the result is 0.

CASE X

WHEN 'A12' THEN 1

WHEN 'B23' THEN 2

END

If X has the value A12, the result is 1; if X has the value B23, theresult is 2; otherwise the result is null.

Lookup ExpressionsA lookup expression specifies a value obtained from a table. It hasthis form:

5──LOOKUP──column_name──IN ──table_name ──────────────────────5

5──WHERE ──┤ lookup_condition ├────────────────────────────5

lookup_condition: ┌ ┐─AND──────────────────────────────────────├─ ───

6┴──┬ ┬ ─expression ──compare_operator ──column_name─ ────────┤

└ ┘─expression ──LIKE ──column_name───────────

compare_operator:├─ ──┬ ┬─ = ── ────────────────────────────────────────────┤

├ ┤─ <> ─├ ┤─ < ──├ ┤─ > ──├ ┤─ <= ─└ ┘─ >= ─

LOOKUP column_nameIdentifies the column of the lookup table from which to obtain thevalue.

Version 2.08-22

Valu

es and

Exp

ression

s

Lookup Expressions

IN table_nameIdentifies the lookup table, that is, the table from which to obtainthe value.

WHERE lookup_conditionIdentifies the row of the lookup table from which to obtain thevalue.

expression compare_operator column_nameIs a comparison, as described in “Comparisons” on page 8-16.The names in expression are names belonging to the contextwhere the lookup expression is used. The column_name is thename of a column of the lookup table. See “Storing andRetrieving Database Data” on page C-1 for this detailedinformation on how the value is obtained from that column.

expression LIKE column_nameSpecifies pattern matching as described in “Pattern Matching” onpage 8-17. The names in expression are names belonging to thecontext where the lookup expression is used. The column_name isthe name of a column of the lookup table.

ANDIs the logical operator defined in “Logical Operations” onpage 8-18.

How the Result Is Obtained: The result of the lookup expressionis defined by this procedure:

■ Replace each expression in the lookup condition by its value.

■ Evaluate the resulting condition for each row of the lookuptable, replacing each column_name by a value from that row.

■ If the condition is true for exactly one row, obtain the resultfrom that row.

■ If the condition is true for several rows, select one of them:

� If the condition does not contain LIKE operators, selectany row with a true condition.


Lookup Expressions

� If the condition contains one or more LIKE operators,select among the rows with a true condition, the row withthe most specific pattern.

Obtain the result from the selected row.

■ If the condition is not true for any row, the result of the lookupexpression is null.

(This procedure is just a way of defining the result. The actualmethod used by the log collector does not necessarily require that allrows be tested.)

Which Is the Most Specific Pattern: To see which of twopatterns is more specific, you can use this method. Represent eachpattern by a string of letters X, U, A, and T like this:

■ Represent each percent sign by X.■ Represent each underscore by U.■ Represent each of the remaining characters by A.■ Add T at the end.

The resulting string is called the pattern scheme. The more specificpattern is one whose pattern scheme comes first in alphabetical order.

If the lookup condition contains more than one LIKE operator,compare the patterns obtained by concatenating the right-handoperands of all LIKE operators in the order they appear in thecondition.

Example:

Suppose the table ACCOUNTING_PERIODS contains this data:

Table 35. Lookup TableACCOUNTING_PERIODS

START_DATE END_DATE PERIOD

1997-01-01 1997-01-28 97/01

1997-01-29 1997-02-25 97/02

1997-02-26 1997-03-25 97/03

... ... ...

Version 2.08-24

Valu

es and

Exp

ression

s

Lookup Expressions

An example of a lookup expression using this table is:

LOOKUP PERIOD IN ACCOUNTING_PERIODS

WHERE SMF72DTE >= START_DATE

AND SMF72DTE <= END_DATE

Assume that SMF72DTE is a field containing the date 1997-01-30.To evaluate the lookup expression, replace SMF72DTE in the lookupcondition by its value. The result is:

DATE('1997-ð1-3ð') >= START_DATE AND

DATE('1997-ð1-3ð') <= END_DATE

Now, evaluate this condition for each row ofACCOUNTING_PERIODS, using the values of START_DATE andEND_DATE from that row.

The condition is true only for the second row. Obtain the result of thelookup expression from the PERIOD column in that row. The resultis 97/ð2.

If SMF72DTE contains the date 1996-12-31, the condition is not truefor any row, and the result of the lookup expression is null.

Example:

Suppose the table TRANSACTION_CODES contains this data:

Table 36. Lookup TableTRANSACTION CODES

TRANSID

SYSTEMID

TRANSCODE

FA21 ABCDPROD T1

B% ABCDPROD T2

BU% ABCDPROD T3

F% ABCDPROD T4

X% ABCDTEST T5

Y% ABCDTEST T6

BUS% % T7

BUS_ % T8


Lookup Expressions

An example of a lookup expression using this table is:

LOOKUP TRAN_CODE IN TRANSACTION_CODES

WHERE SMF67SYS LIKE SYSTEM_ID

AND SMF67TRAN LIKE TRANS_ID

If SMF67SYS is a field containing the stringABCDPROD andSMF67TRAN is a field containing the stringBUS1, the conditionevaluated for each row of the table is:

'ABCDPROD' LIKE SYSTEM_ID AND 'BUS1' LIKE TRANS_ID

This condition is true for rows 2, 3, 7, and 8. These rows, with theirconcatenated patterns and pattern schemes (sorted by pattern scheme),are:

TRANS SYSTEM TRAN concatenated pattern

ID ID CODE pattern scheme

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

BU% ABCDPROD T3 ABCDPRODBU% AAAAAAAATAAXT most specific

B% ABCDPROD T2 ABCDPRODB% AAAAAAAATAXT

BUS_ % T8 %BUS_ XTAAAUT

BUS% % T7 %BUS% XTAAAXT most general

The row with the most specific pattern is one where columnTRAN_CODE contains the string T3. The result of the lookupexpression is T3.

Note: To achieve acceptable performance, lookup tables are readinto storage buffers at the start of processing. This means that thetables should not be too large. It also means that any changes to alookup table resulting from a collect operation do not affect the resultof a lookup before the collect is completed.

Version 2.08-26

Valu

es and

Exp

ression

s

Expressions

ExpressionsThis diagram specifies the general form of expression to be usedwherever the syntax specifies an expression. Notice that the diagramdoes not reflect all the rules that you must follow when you useoperators. You can find these rules in section “Using Operators” onpage 8-12.

┌ ┐─operator──────────────────────────────────────────────────────────────5─ ───

6┴──┬ ┬───── ──┬ ┬─constant──────────── ──┬ ┬───────────────────────────────── ──────────────────5

├ ┤─ + ─ ├ ┤─identifier ───────── │ │┌ ┐─────────────────────────────── └ ┘─ - ─ ├ ┤──: identifier ────── └ ┘───

6┴──┬ ┬─ + ─ ─labeled_duration─

├ ┤─case_expr ────────── └ ┘─ - ─ ├ ┤─lookup_expr ──────── ├ ┤─function──────────── ├ ┤─(expression) ─────── ├ ┤─CURRENT DATE ─────── ├ ┤─CURRENT TIME ─────── ├ ┤─CURRENT TIMESTAMP ─ └ ┘─USER ────────────────

operator:├─ ──┬ ┬─ + ── ────────────────────────────────────────────────────────────────────────────────────┤

├ ┤─ - ──├ ┤─ \ ──├ ┤─ / ──└ ┘─ || ─

constantIs a constant that explicitly specifies a value. See “Specifying aValue Explicitly” on page 8-6.

identifierIs the name of a value or of something that holds a value. Itspecifies that value. See “Specifying a Value Using an Identifier”on page 8-7.

: identifierSpecifies the value of a variable. See “Obtaining the Value of aVariable” on page 8-8.

case_exprIs a case expression. See “Case Expressions” on page 8-20.

lookup_exprIs a lookup expression. See “Lookup Expressions” on page 8-22.


Conditions

functionIs a function call. It specifies the result of a function. See“Functions” on page 9-1.

(expression)Specifies the value of expression.

labeled_durationIs a labeled duration. See “Labeled Durations” on page 8-11.

CURRENT DATECURRENT TIMECURRENT TIMESTAMP

Specify current date, time, or timestamp. See “Obtaining CurrentDate, Time, or User” on page 8-9.

USERSpecifies current user ID. See “Obtaining Current Date, Time, orUser” on page 8-9.

+ − * / ||Are operators. Their meaning is specified in “Using Operators” onpage 8-12.

Precedence of OperatorsIf not specified otherwise by means of parentheses, the prefix plusand minus are applied before multiply and divide. Multiply anddivide are applied before infix plus and minus. Operators of the samepriority are applied from left to right.

ConditionsThe following diagram specifies the general form of expression thatyou can use wherever the syntax specifies a condition. Notice that thediagram does not reflect all the rules that you must follow when youuse operators. You can find these rules in “Using Operators” onpage 8-12.

Version 2.08-28

Valu

es and

Exp

ression

s

Conditions

┌ ┐─logical_operator ────────────────────────────────────5─ ───

6┴──┬ ┬───── ──┬ ┬ ─expression ──compare_operator ──expression ─ ────────────5

└ ┘─NOT ─ ├ ┤ ─expression ─ ──┬ ┬─IS NULL──── ────────────│ │└ ┘─IS NOT NULL─

└ ┘─(condition)────────────────────────────

logical_operator:├─ ──┬ ┬─AND ─ ──────────────────────────────────────────────────────────┤ └ ┘─OR ──

compare_operator:├─ ──┬ ┬─ = ── ─────────────────────────────────────────────────────────┤

├ ┤─ <> ─├ ┤─ < ──├ ┤─ > ──├ ┤─ <= ─└ ┘─ >= ─

expression compare_operator expressionIs a comparison, as described in “Comparisons” on page 8-16.

expression IS NULLexpression IS NOT NULL

Is a test for null. See “Testing for Null” on page 8-19.

(condition)Specifies the value of condition.

AND, OR, NOTAre logical operators defined in “Logical Operations” onpage 8-18.

Precedence of OperatorsIf not specified otherwise by means of parentheses, NOT is appliedbefore AND and OR. The operators AND and OR are then appliedfrom left to right.


Version 2.08-30

Fu

nctio

ns9

Functions

This chapter describes a special form of expression called a functioncall. You can use a function call directly in the statements, wheneverthe syntax specifies an expression. You can also use it as a part ofmore complex expressions.

A function call specifies a value as the result of applying a namedoperator, called a function, to one or more arguments. It consists of afunction name followed by arguments in parentheses. Most argumentsare values specified by means of expressions. However, somefunctions use arguments that are not values, for example, a sectionname or a labeled duration.

The result of a function is null if any of the arguments is null. Theonly exception to this rule is the VALUE function (see “VALUE” onpage 9-36).

This chapter describes, in alphabetical order, all functions available inthe log collector language. It describes the purpose, syntax, and resultof each function. It also provides examples of how to use eachfunction.


CHAR

CHARThe CHAR function obtains a string representation of a date/timevalue.

Syntax

5─ ──CHAR (expression ) ────────────────────────────────────5

The argument must be a date, a time, or a timestamp.

ResultThe result is a character string. It is the date/time string thatrepresents the argument.

ExampleAssume that:

■ X_DATE has the value May 3, 1997.■ X_TIME has the value 5 hours, 17 minutes, and 34 seconds.■ X_TSTAMP has the value 5 hours, 17 minutes, and 34 seconds

on May 3, 1997.

The function produces these results:

CHAR(X_DATE) = '1997-ð5-ð3'

CHAR(X_TIME) = 'ð5.17.34.ðððððð'

CHAR(X_TSTAMP) = '1997-ð5-ð3-ð5.17.34.ðððððð'

Version 2.09-2

Fu

nctio

ns

DATE

DATEThe DATE function obtains a date from a value.

Syntax

5─ ──DATE (expression ) ────────────────────────────────────5

The argument must be a date, a timestamp, a number, or a datestring.

ResultThe result is a date.

■ If the argument is a date, the result is that date.

■ If the argument is a timestamp, the result is the date part of thattimestamp.

■ If the argument is a number, consider the integer part of thatnumber as n. It must be in the range 1 to 3 652 059. The resultof the function is the date of the day with sequential number n,counting from January 1, 0001 as day 1.

■ If the argument is a date string, the result is the date representedby that string.

ExampleAssume that:

■ X_DATE has the value April 22, 1997.■ X_TSTAMP has the value 15 hours, 2 minutes, and 1 second on

March 6, 1997.■ X_STRING has the value '1997-03-06'.


DATE(X_DATE) = April 22, 1997

DATE(X_TSTAMP) = March 6, 1997

DATE(72862ð) = November 23, 1997

DATE('1997-11-15') = November 15, 1997

DATE(X_STRING) = March 6, 1997


DAY

DAYThe DAY function obtains the day part of a value.

Syntax

5─ ──DAY (expression ) ─────────────────────────────────────5

The argument must be a date or a timestamp.

ResultThe result is an integer between 1 and 31. It is the day part of thedate or timestamp.

ExampleAssume that:

■ X_DATE has the value November 9, 1997.

■ X_TSTAMP has the value 15 hours, 2 minutes, and 1 second onFebruary 19, 1997.


DAY(X_DATE) = 9

DAY(X_TSTAMP) = 19

Version 2.09-4

Fu

nctio

ns

DAYS

DAYSThe DAYS function obtains the day number corresponding to a date.

Syntax

5─ ──DAYS (expression ) ────────────────────────────────────5

The argument must be a date, a timestamp, a date string, or atimestamp string.

ResultThe result is an integer. It is the sequential number of the dayrepresented by the argument, considering January 1, 0001 as day 1.

■ If the argument is a date or a date string, the result is thesequential number of the day represented by the date.

■ If the argument is a timestamp or a timestamp string, the resultis the sequential number of the day represented by the date partof the timestamp.

ExampleAssume that:

■ X_DATE has the value April 15, 1997.

■ X_TSTAMP has the value 11 hours, 33 minutes, and 21 secondson August 26, 1997.


DAYS(X_DATE) = 728398

DAYS(X_TSTAMP) = 728531

DAYS('1997-ð5-ð3') = 728416

DAYS('1997-ð5-ð3-15.45.ð1.ðððððð') = 728416


DAYS

Usage NotesYou can use the DAYS function to obtain the day of week for agiven date. To compute the day of week for X_DATE, use thisexpression:

DAYS(X_DATE)-((DAYS(X_DATE)-1)/7)\7

The result is a number from 1 through 7, representing Mondaythrough Sunday. If X_DATE has the value April 15, 1997, the resultis 6 which represents a Saturday.

You can use the DAYS function, with the DATE function, to obtainthe date of Monday in the week containing a given date. To computethe Monday date of the week containing X_DATE, use thisexpression:

DATE((DAYS(X_DATE)/7)\7 + 1)

(This expression assumes that weeks start on Monday.) If X_DATEhas the value April 15, 1997, then the result is April 10, 1997, whichis a Monday of the week that includes April 15, 1997.

Version 2.09-6

Fu

nctio

ns

DAYTYPE

DAYTYPEThe DAYTYPE function obtains the day type of a given day.

Syntax

5─ ──DAYTYPE (expression ,expression ) ────────────────────────5

The first argument must be an integer. The second argument must bea date or a timestamp.

The result of the function is defined by means of two system tables,CAL_DAY_OF_WEEK and CAL_SPECIAL_DAY. These tablesshould be set up when the product is installed. (For more information,refer to theTME 10 Reporter Installation and Administrationmanual.)

The table CAL_DAY_OF_WEEK defines a 16-character string, calleda day type code, for each day of the week. The table on your systemmight contain the information shown below. (The table may alsocontain other columns, but they are not used to define the day type.)

Table 37 (Page 1 of 2). Example ofCAL_DAY_OF_WEEK

CALENDARID

DAY OFWEEK

DAY TYPE

0 1 WORKDAY

0 2 WORKDAY

0 3 WORKDAY

0 4 WORKDAY

0 5 WORKDAY

0 6 SAT

0 7 SUN

5 1 WORKDAY

5 2 WORKDAY

5 3 WORKDAY


DAYTYPE

The table defines day type codes according to two calendars. Thecalendars are internally identified by integers, in this case 0 and 5.These integers appear in the column CALENDAR_ID. The numbers1 through 7 in the column DAY_OF_WEEK identify the days ofweek, Monday through Sunday. In calendar 0, Monday throughFriday have day type WORKDAY, while Saturday and Sunday haveday types SAT and SUN, respectively. In calendar 5, Mondaythrough Friday also have day type WORKDAY, but Saturday andSunday have day type WEEKEND.

The table CAL_SPECIAL_DAY defines day type codes that are to beused for certain dates (such as holidays), regardless of their day ofweek. These special days may be different in different calendars. Thetable on your system might contain the information shown below.(The table may also contain other columns, but they are not used todefine the day type.)

The table defines January 6, 1997 as a special day, of typeHOLIDAY, in calendar 0. This day is not a special day in calendar 5;

Table 37 (Page 2 of 2). Example ofCAL_DAY_OF_WEEK

CALENDARID

DAY OFWEEK

DAY TYPE

5 4 WORKDAY

5 5 WORKDAY

5 6 WEEKEND

5 7 WEEKEND

Table 38. Example of CAL_SPECIAL_DAYTable

CALENDARID

SPECIALDATE

DAY TYPE

0 1997-01-06 HOLIDAY

5 1997-01-01 HOLIDAY

Version 2.09-8

Fu

nctio

ns

DAYTYPE

in that calendar, January 1, 1997 is a special day, also of typeHOLIDAY.

ResultThe result is a 16-character string. It is the day type code for the dayrepresented by the second argument, in the calendar identified by thefirst argument.

Let cal be the first argument of DAYTYPE, and let date be thesecond argument (if the second argument is a date) or the date part ofthe second argument (if the second argument is a timestamp). Let wbe a number representing the day of week for date, the values 1through 7 standing for Monday through Sunday. The result ofDAYTYPE is specified by this expression:

VALUE( LOOKUP DAY_TYPE IN &TABPREFIX.CAL_SPECIAL_DAY

WHERE cal = CALENDAR_ID

AND date = DATE,

LOOKUP DAY_TYPE IN &TABPREFIX.CAL_DAY_OF_WEEK


AND w = DAY_OF_WEEK )

A null result of this expression is considered an error. It means that arow with calendar id cal and day of week number w is missing fromCAL_DAY_OF_WEEK.

ExampleAssume that:

■ CAL_DAY_OF_WEEK contains the data shown in Table 37 onpage 9-7.

■ CAL_SPECIAL_DAY contains the data shown in Table 38 onpage 9-8.

■ X_TSTAMP has the value 10 hours, 5 minutes, and 12 secondson January 6, 1997.


DAYTYPE


DAYTYPE(ð,DATE('1996-12-31')) = 'SAT '

DAYTYPE(5,DATE('1996-12-31')) = 'WEEKEND '

DAYTYPE(ð,DATE('1997-ð1-ð1')) = 'SUN '

DAYTYPE(5,DATE('1997-ð1-ð1')) = 'HOLIDAY '

DAYTYPE(ð,DATE(X_TSTAMP)) = 'HOLIDAY '

DAYTYPE(5,DATE(X_TSTAMP)) = 'WORKDAY '

Version 2.09-10

Fu

nctio

ns

DIGITS

DIGITSThe DIGITS function obtains a character string representation of anumber.

Syntax

5─ ──DIGITS (expression ) ───────────────────────────────────5

The argument must be an integer.

ResultThe result is the string of digits (other than leading zeroes) thatrepresents the absolute value of the argument.

ExampleDIGITS(754) = '754'

DIGITS(ððð54) = '54'

DIGITS(-54) = '54'


FLOAT

FLOATThe FLOAT function obtains a floating-point representation of anumber.

Syntax

5─ ──FLOAT (expression ) ───────────────────────────────────5

The argument must be a number.

ResultIf the argument is an integer, the result is a floating-pointrepresentation of that integer. If the argument is a floating-pointnumber, the result is that number.

ExampleFLOAT(14) = 14.ð

FLOAT(25.7) = 25.7

Version 2.09-12

Fu

nctio

ns

HOUR

HOURThe HOUR function obtains the hour part of a value.

Syntax

5─ ──HOUR (expression ) ────────────────────────────────────5

The argument must be a time or a timestamp.

ResultThe result is an integer between 0 and 24. It is the hour part of theargument.

ExampleAssume that:

■ X_TIME has the value 14 hours, 20 minutes, 55 seconds.

■ X_TSTAMP has the value 10 hours, 5 minutes, and 21 secondson June 27, 1997.


HOUR(X_TIME) = 14

HOUR(X_TSTAMP) = 1ð


INTEGER

INTEGERThe INTEGER function obtains the integer part of a number.

Syntax

5─ ──INTEGER (expression ) ──────────────────────────────────5

The argument must be a number.

ResultIf the argument is an integer, the result is that integer. If theargument is a floating-point number, the result is the integer part ofthat number.

ExampleINTEGER(45) = 45

INTEGER(-75.3) = -75

INTEGER(ð.ððð5) = ð

Version 2.09-14

Fu

nctio

ns

INTERVAL

INTERVALThe INTERVAL function obtains the length of a time interval inseconds.

Syntax

5─ ──INTERVAL (expression , expression ) ──────────────────────5

Both arguments must be date/time values of the same type.

ResultThe result is a floating-point number.

The result is the interval, in seconds, from the instant designated bythe first argument to the instant designated by the second argument.

If the first argument is later than the second, the result is negative.

The result has the maximum precision allowed by its floating-pointrepresentation.

ExampleAssume you have these variables:

■ TME1 has the value of 6 hours, 20 minutes, 29 seconds, and25 000 microseconds.

■ TME2 has the value of 18 hours, 25 minutes, 20 seconds.■ DAY1 has the value of March 5, 1997.■ DAY2 has the value of March 8, 1997.■ TS1 has the value of 5 hours on March 5, 1997.■ TS2 has the value of 10 hours, 30 minutes on March 11, 1997.


INTERVAL(TME1, TME2) = 4349ð.975

INTERVAL(TME2, TME1) = -4349ð.975

INTERVAL(DAY1, DAY2) = 2592ðð.ð

INTERVAL(TS1, TS2) = 5382ðð.ð


LENGTH

LENGTHThe LENGTH function obtains the length of a character string.

Syntax

5─ ──LENGTH (expression ) ───────────────────────────────────5

The argument must be a character string.

ResultThe result is an integer. It is the length of the argument.

ExampleAssume X_STRING has the value of 'LOG_NAME'. The functionproduces these results:

LENGTH(X_STRING) = 8

LENGTH('REC_LOG') = 7

LENGTH(' ') = 1

LENGTH('') = ð

Version 2.09-16

Fu

nctio

ns

MICROSECOND

MICROSECONDThe MICROSECOND function obtains the microsecond part of avalue.

Syntax

5─ ──MICROSECOND (expression ) ───────────────────────────────5


ResultThe result is an integer between 0 and 999 999. It is the microsecondspart of the argument.

ExampleAssume that:

■ X_TIME has the value 14 hours, 20 minutes, 55 seconds and155 microseconds.

■ X_TSTAMP has the value 8 hours, 30 minutes, and 45 secondson March 25, 1997.


MICROSECOND(X_TIME) = 155

MICROSECOND(X_TSTAMP) = ð


MINUTE

MINUTEThe MINUTE function obtains the minute part of a value.

Syntax

5─ ──MINUTE (expression ) ───────────────────────────────────5


ResultThe result is an integer between 0 and 59. It is the minute part of theargument.

ExampleAssume that:

■ X_TIME has the value 17 hours, 16 minutes, 22 seconds and100 000 microseconds.

■ X_TSTAMP has the value 8 hours, 58 minutes, and 19 secondson April 1, 1997.


MINUTE(X_TIME) = 16

MINUTE(X_TSTAMP) = 58

Version 2.09-18

Fu

nctio

ns

MONTH

MONTHThe MONTH function obtains the month part of a value.

Syntax

5─ ──MONTH (expression ) ───────────────────────────────────5


ResultThe result is an integer between 1 and 12. It is the month part of theargument.

ExampleAssume that:

■ X_DATE has the value July 22, 1997.■ X_TSTAMP has the value May 3, 1997.


MONTH(X_DATE) = 7

MONTH(X_TSTAMP) = 5


PERIOD

PERIODThe PERIOD function obtains the name of the period containing agiven time instant.

Syntax

5─ ──PERIOD (expression , expression , expression ) ─────────────5

The first argument must be an integer. The second argument must bea date. The third argument must be a time.

The result of the function is defined by means of a system tableCAL_DAY_PERIOD. This table should be set up when the productis installed. (For more information, refer to theTME 10 ReporterInstallation and Administrationmanual.)

The table CAL_DAY_PERIOD defines schedules. A schedule is ascheme that divides each day into named intervals (such as shifts).These intervals are called periods. The partition of a day into periodsdepends on theday type of the day. The day types are defined by thesystem tables CAL_DAY_OF_WEEK and CAL_SPECIAL_DAY, asexplained under “DAYTYPE” on page 9-7.

The table CAL_DAY_PERIOD defines one schedule for eachcalendar used by your installation. The calendars are internallyidentified by integers, like 0 or 5.

The table on your system might contain the information shown inTable 39 on page 9-21. (The table may also contain other columns,but they are not used to define the periods.)

Version 2.09-20

Fu

nctio

ns

PERIOD

Each row in the table defines one period within the day of typeDAY_TYPE in the schedule for calendar CALENDAR_ID. Theperiod starts at START_TIME and extends up to END_TIME. Itincludes START_TIME, but not END_TIME. The group of rowswith the same CALENDAR_ID and DAY_TYPE specify partitioningof one day. The intervals they specify must not overlap and mustcover the whole day from hour 00 to hour 24.

As specified by the table in Table 39, a WORKDAY in the schedulefor calendar 0 is divided into three periods named, respectively,NIGHT, PRIME, and NIGHT. These periods start, respectively, athours 00, 08, and 17. A WORKDAY in the schedule for calendar 5is also divided into three periods with similar names, but starting atdifferent hours.

Table 39. Example of CAL_DAY_PERIOD Table

CALENDARID

DAY TYPE STARTTIME

END TIME PERIODNAME

0 WORKDAY 00.00.00 08.00.00 NIGHT

0 WORKDAY 08.00.00 17.00.00 PRIME

0 WORKDAY 17.00.00 24.00.00 NIGHT

0 SAT 00.00.00 08.00.00 NIGHT

0 SAT 08.00.00 24.00.00 HOLIDAY

0 SUN 00.00.00 24.00.00 HOLIDAY

0 HOLIDAY 00.00.00 24.00.00 HOLIDAY

5 WORKDAY 00.00.00 09.00.00 NIGHT

5 WORKDAY 09.00.00 18.00.00 PRIME

5 WORKDAY 18.00.00 24.00.00 NIGHT

5 WEEKEND 00.00.00 24.00.00 CLOSED

5 HOLIDAY 00.00.00 24.00.00 CLOSED


PERIOD

ResultThe result is an 8-character string.

Let the three arguments of PERIOD be called cal, date, and time,respectively. The result of PERIOD is the name of the period in theschedule for calendar cal that contains the time instant identified bydate and time. It is specified by this lookup expression:

LOOKUP PERIOD_NAME IN &TABPREFIX.CAL_DAY_PERIOD


AND DAYTYPE(date) = DAY_TYPE

AND time >= START_TIME

AND time < END_TIME

A null result of this lookup expression is regarded as an error. Itmeans that one, or both, of the tables CAL_DAY_OF_WEEK andCAL_DAY_PERIOD is incomplete.

Version 2.09-22

Fu

nctio

ns

PERIOD

ExampleAssume that CAL_DAY_PERIOD is as shown in Table 39 onpage 9-21, and that DAYTYPE is defined by these tables:

Table 40. Example of CAL_DAY_OF_WEEKTable

CALENDARID

DAY OFWEEK

DAY TYPE

0 1 WORKDAY

0 2 WORKDAY

0 3 WORKDAY

0 4 WORKDAY

0 5 WORKDAY

0 6 SAT

0 7 SUN

5 1 WORKDAY

5 2 WORKDAY

5 3 WORKDAY

5 4 WORKDAY

5 5 WORKDAY

5 6 WEEKEND

5 7 WEEKEND

Table 41. Example of CAL_SPECIAL_DAYTable

CALENDARID

DATE DAY TYPE

0 1997-01-06 HOLIDAY

5 1997-01-01 HOLIDAY


PERIOD

The function produces these results (January 1, 1997 is a Sunday):

PERIOD(ð,DATE('1997-ð1-ð1'),TIME('12.34.56.ðððððð')) = 'HOLIDAY '

PERIOD(ð,DATE('1997-ð1-ð1'),TIME('24.ðð.ðð.ðððððð')) = 'NIGHT '

PERIOD(5,DATE('1997-ð1-ð2'),TIME('12.34.56.ðððððð')) = 'PRIME '

PERIOD(5,DATE('1997-ð1-ð6'),TIME('ð9.ðð.ðð.ðððððð')) = 'PRIME '

Notice that hour 24 is treated as hour 00 of the next day.

Version 2.09-24

Fu

nctio

ns

ROUND

ROUNDThe ROUND function rounds a date/time value down to a multiple ofthe specified number of time units.

Syntax

5─ ──ROUND (expression , labeled-duration ) ───────────────────5

The first argument must be a date, a time, or a timestamp. Thesecond argument must be a labeled duration.

■ If the first argument is a date, the second argument must be alabeled duration of years, months, or days.

■ If the first argument is a time, the second argument must be alabeled duration of hours, minutes, seconds, or microseconds.

■ If the first argument is a timestamp, the second argument can beany labeled duration.

In each case, the labeled duration must specify a number of unitsgreater than 0.

ResultThe result is of the same type as the first argument. It is obtainedfrom the first argument by this procedure:

■ Select the part that corresponds to the time unit used in thelabeled duration. That means, if the labeled duration is nYEARS, select the year part; if the labeled duration is nMONTHS, select the month part; and so on.

■ Round the selected part to a whole multiple of the secondargument, in this sense:

� If the part is an hour, minute, second, or microsecond (andthus has values starting with 0), round it down to thenearest number kn, where k ≥ 0 is a whole number, and nis the number of units in the labeled duration.


ROUND

� If the part is a month or a day (and thus has values startingwith 1), round it down to the nearest number 1 + kn,where k ≥ 0 is a whole number, and n is the number ofunits in the labeled duration.

� If the part is a year, round it down to the closest numberkn, where k ≥ 0 is a whole number, and n is the number ofyears in the labeled duration. If the result is 0, replace itby 1.

■ Replace all lower-order parts by their lowest values (that is, 1for month and day, or 0 for other parts).

■ Leave the remaining parts unchanged.

ExampleROUND(DATE('1997-ð6-27'),1 MONTH) = June 1, 1997

ROUND(DATE('1997-ð6-27'),3 MONTHS) = April 1, 1997

ROUND(DATE('1997-ð6-27'),6 MONTHS) = January 1, 1997

ROUND(DATE('1997-ð6-27'),15 DAYS) = June 16, 1997

ROUND(DATE('1997-ð6-27'),5ð DAYS) = June 1, 1997

ROUND(TIME('12.47.39.125ððð'),1 HOUR) = 12 hours

ROUND(TIME('12.47.39.125ððð'),6ð MINUTES) = 12 hours

ROUND(TIME('12.47.39.125ððð'),3ð MINUTES) = 12 hours, 3ð minutes

ROUND(TIME('12.47.39.125ððð'),2ð MINUTES) = 12 hours, 4ð minutes

ROUND(TIME('12.47.39.125ððð'),5 SECONDS) = 12 hours, 47 minutes, 35 seconds

Usage NotesNotice that:

■ Rounding a date to 3 months produces the first day of a quarter.

■ Rounding a date to 6 months produces the first day of ahalf-year period.

■ Rounding a date to 15 days produces the first day of a 15-dayperiod within a month.

■ Rounding to a large number of units is allowed, but it does notaffect the higher-order parts. For example, rounding a date to 50days produces the same effect as rounding to 1 month.

Version 2.09-26

Fu

nctio

ns

SECOND

SECONDThe SECOND function obtains the seconds part of a value.

Syntax

5─ ──SECOND (expression ) ───────────────────────────────────5


ResultThe result is an integer between 0 and 59. It is the seconds part ofthe argument.

ExampleAssume that:

■ X_TIME has the value 0 hours, 4 minutes, 25 seconds, and1 432 microseconds.

■ X_TSTAMP has the value 17 hours, 25 minutes, 50 seconds,and 5 microseconds on June 20, 1997.


SECOND(X_TIME) = 25

SECOND(X_STAMP) = 5ð


SECTNUM

SECTNUMThe SECTNUM function obtains the sequential number of a sectionoccurrence.

Syntax

5─ ──SECTNUM (section_name) ─────────────────────────────────5

This function is intended for use with an internal record generatedfrom a repeated section (see “Using Repeated Sections WithinRecords” on page 5-23). The section-name must identify one of thesections included in that record.

ResultThe result is an integer. It is the sequential number (within thecontaining section) of the occurrence ofsection-name that was usedto build the record.

If section-name is not a repeated section, the result is 1 if the sectionis present in the record, or 0 if it is absent.

For more information about using this function, see “Obtaining aSection Occurrence Number” on page 5-36.

ExampleAssume that you have this record:


┌──────────────────────────┐┌─────────────────────────────────┐

│ ││ │

ERROR ERROR ERROR

┌──────┐ ┌──────┐┌──────┐

│ │ │ ││ │

DATE TIME NFILE NAME BYTES NERR NREC RC NAME BYTES NERR NREC RC NREC RC

┌────┐┌────┐┌──┐ ┌──────┐┌──────┐┌──┐┌──┐┌──┐┌─────┐┌──────┐┌──┐┌──┐┌──┐┌──┐┌──┐

│ ││ ││ │ │ ││ ││ ││ ││ ││ ││ ││ ││ ││ ││ ││ │

97ð62ðð65311 2 FILE_A 1254ð9 1 12 2 FILE_B 75432 2 5ð 5 62 1

Figure 36. Example of a Record Containing Nested Sections

Version 2.09-28

Fu

nctio

ns

SECTNUM

Assume that SECTNUM is evaluated while processing an internalrecord generated for the first occurrence of the ERROR section in thesecond occurrence of the FILE section.


SECTNUM(ERROR) = 1

SECTNUM(FILE) = 2


SUBSTR

SUBSTRThe SUBSTR function obtains a substring of a character string.

Syntax

5─ ──SUBSTR (expression , expression ──┬ ┬───────────── ) ───────5 └ ┘──, expression

In this description, the three arguments are called, respectively,string,start, and length. The string must be a character string. The startmust be an integer in the range 1 to 254. The length must be aninteger in the range 0 to 255−start.

ResultThe result is a character string.

If length is specified, the result consists of length bytes of string,starting at the position start. The string is regarded as extended onthe right with the necessary number of blanks so that the specifiedsubstring exists.

If length is not specified, the result consists of all bytes of string,starting at the position start and extending up to the end of string. Ifstart is greater than the length of string, the result is an empty string.

Both start and length are expressed in bytes. The SUBSTR functiondoes not recognize multiple-byte characters, and the result need notbe a well-formed character string.

ExampleThe function produces these results:

SUBSTR('SUB_REC',3,2) = 'B_'

SUBSTR('SUB_REC',3) = 'B_REC'

SUBSTR('SUB_REC',3,1ð) = 'B_REC '

Version 2.09-30

Fu

nctio

ns

TIME

TIMEThe TIME function obtains a time from a value.

Syntax

5─ ──TIME (expression ) ────────────────────────────────────5

The argument must be a time, a timestamp, or a time string.

ResultThe result is a time.

■ If the argument is a time, the result is that time.

■ If the argument is a timestamp, the result is the time part of thattimestamp.

■ If the argument is a time string, the result is the timerepresented by that string.

ExampleAssume that:

■ X_TIME has the value 3 hours, 24 minutes, 20 seconds, and 2microseconds.



TIME(X_TIME) = 3 hours, 24 minutes, 2ð seconds, and 2 microseconds

TIME('17.24.13.ðððð25') = 17 hours, 24 minutes, 13 seconds, and 25 microseconds

TIME(X_TSTAMP) = 15 hours, 33 minutes, 25 seconds, and 75 microseconds


TIMESTAMP

TIMESTAMPThe TIMESTAMP function obtains a timestamp from a value or apair of values.

Syntax

5─ ──TIMESTAMP (expression ──┬ ┬───────────── ) ───────────────5 └ ┘──, expression

ResultThe result of the function depends on whether one or both argumentsare specified.

If only one argument is specified:

The argument must be a timestamp or a timestamp string. The resultis a timestamp:

■ If the argument is a timestamp, the result is that timestamp.

■ If the argument is a timestamp string, the result is the timestamprepresented by that string.

If both arguments are specified:

The first argument must be a date or a date string. The secondargument must be a time or a time string.

The result is a timestamp. It consists of the date and time specifiedby the arguments.

ExampleAssume that:

■ X_TIME has the value 3 hours, 24 minutes, 20 seconds, and 2microseconds.

■ X_DATE has the value February 11, 1997.


Version 2.09-32

Fu

nctio

ns

TIMESTAMP


TIMESTAMP(X_TSTAMP) = 15 hours, 33 minutes, 25 seconds,

and 75 microseconds on June 2ð, 1997

TIMESTAMP('1997-ð4-17-19.ð1.25.ðððððð') = 19 hours, 1 minute,

25 seconds on April 17, 1997

TIMESTAMP(X_DATE, X_TIME) = 3 hours, 24 minutes, 2ð seconds,

and 2 microseconds on February 11, 1997


TRANSLATE

TRANSLATEThe TRANSLATE function translates a character string to anotherrepresentation.

Syntax

5─ ──TRANSLATE (expression ──┬ ┬────────────── ) ──────────────5 └ ┘ ─,──┤ codes ├─

codes:├─ ──┬ ┬─────────── ───────────────────────────────────────5 └ ┘─expression ─

5─ ──┬ ┬──────────────────────────────────── ──────────────┤ └ ┘ ─,─ ──┬ ┬─────────── ──┬ ┬────────────── └ ┘─expression ─ └ ┘ ─,──expression ─

In this description, the four arguments are called, respectively,string,to-codes, from-codes, and pad-byte. All arguments must be characterstrings. The pad-byte must be a string of length 1.

ResultThe result is a character string. It is a copy of string in which someof the bytes have been replaced by others (string itself is not altered).

■ If from-codes is present, each byte of string is looked up infrom-codes. If it is found on position n of from-codes, it isreplaced by the byte appearing on positionn of to-codes;otherwise it is left unchanged.

If to-codes is shorter than n or omitted, it is conceptuallyextended on the right with as many copies of the pad-byte asneeded. If pad-byte is omitted, a blank is used instead.

■ If from-codes is absent and to-codes is present, each byte ofstring is replaced by the byte appearing on positionn = b + 1 ofto-codes, where b is the binary value of the byte.

Version 2.09-34

Fu

nctio

ns

TRANSLATE

If to-codes is shorter than n, it is conceptually extended on theright with as many copies of the pad-byte as needed. If pad-byteis omitted, a blank is used instead.

■ If both from-codes and to-codes are omitted,string is translatedto uppercase: all occurrences of lowercase letters (a-z) arereplaced by their uppercase counterparts (A-Z).

The TRANSLATE function does not recognize multiple-bytecharacters, and the result need not be a well-formed character string.

ExampleTRANSLATE('abcdef') = 'ABCDEF'

TRANSLATE('abcdef', '\#$', 'bde') = 'a\c#$f'

TRANSLATE('abcdef', 'CD', 'acde', '.') = 'CbD..f'


VALUE

VALUEThe VALUE function returns the first argument that is not null.

Syntax

┌ ┐─────────────5─ ──VALUE (expression ───

6┴, expression ) ────────────────────5

All arguments must have the same data type.

ResultThe result has the same data type as the arguments. It is equal to thefirst argument that is not null. If all arguments are null, the result isnull.

ExampleAssume that:

■ EXPA has the value of 25.■ EXPB has the value of 50.■ EXPC has a null value.


VALUE(EXPA, EXPB, EXPC) = 25

VALUE(EXPC, EXPB, EXPA) = 5ð

VALUE(EXPB, EXPA) = 5ð

Version 2.09-36

Fu

nctio

ns

WORD

WORDThe WORD function extracts a word from a character string.

Syntax

5─ ──WORD (expression , expression ──┬ ┬───────────── ) ────────5 └ ┘──, expression

In this description, the three arguments are called, respectively,string,n, and delimiters. The first and third arguments must be characterstrings. The second argument must be an integer.

ResultThe result is a character string. If n is positive, the result is the nthword of string. If n is negative, the result is the nth word of string,counting from the end. If n is 0, or if the string contains fewer thannwords, the result is an empty string.

The function treats string as a sequence of words separated bydelimiters. A delimiter is any byte present in delimiters, or a blank ifthe delimiters argument is absent or empty. A word is any substringnot containing delimiters, preceded by a delimiter (or start of string),and followed by a delimiter (or end of string).

If a blank is specified as a delimiter, a whole sequence of adjacentblanks is counted as one delimiter.

The WORD function recognizes multiple-byte characters in string,but all delimiters must be single-byte characters.

ExampleWORD('A B',2,' ') = 'B'

WORD('A,,,B',2,',') = ''

WORD('A,,,B',-1,',') = 'B'


YEAR

YEARThe YEAR function obtains the year part of a value.

Syntax

5─ ──YEAR (expression ) ────────────────────────────────────5


ResultThe result is an integer between 1 and 9 999. It is the year part of theargument.

ExampleAssume that:

■ X_DATE has the value February 11, 1997.



YEAR(X_DATE) = 1997

YEAR(X_TSTAMP) = 1997

Version 2.09-38

Lan

gu

age S

tatemen

ts

10Log Collector LanguageStatements

The log collector language consists of statements that you use todetermine how data is collected, processed, and stored. It alsoprovides statements that you can use to maintain data tables and toperform the collection process.

This chapter provides an alphabetical listing of the languagestatements. For each statement, the chapter describes:

■ The purpose of the statement■ The syntax used for the statement■ Parameters (clauses and keywords) that are part of the statement■ Examples of how to use the statement■ Usage notes, if needed, that explain issues to consider when

using the statement


ALTER LOG

ALTER LOGUse the ALTER LOG statement to modify a stored log definition.You can add, change, or delete a:

■ Header■ Timestamp expression■ Source expression■ First record or last record condition■ Log procedure name and the parameters passed to the log

procedure

This description assumes that you are familiar with log definitionsand the DEFINE LOG statement. So, it explains only how ALTERLOG modifies the log definition. It does not explain what themodification means. The syntax diagram shows all the clauses thatyou can specify, but they are explained only as much as it is neededto tell what is altered. See “DEFINE LOG” on page 10-24 for moreinformation.

Version 2.010-2

Lan

gu

age S

tatemen

ts

ALTER LOG

Syntax

55──ALTER LOG ──log_name ───────────────────────────────────────5

┌ ┐─,─────────5─ ──┬ ┬ ─HEADER ─ ──┬ ┬──( ───

6┴─┤ field ├─ ) ───────────────── ───────5%

│ │└ ┘─NONE ────────────── ├ ┤ ─TIMESTAMP ─ ──┬ ┬─expression─ ────────────────────── │ │└ ┘─NONE ────── ├ ┤ ─SOURCE ─ ──┬ ┬─expression─ ───────────────────────── │ │└ ┘─NONE ────── ├ ┤ ─FIRST RECORD─ ──┬ ┬─condition ─ ──────────────────── │ │└ ┘─NONE ────── ├ ┤ ─LAST RECORD─ ──┬ ┬─condition ─ ───────────────────── │ │└ ┘─NONE ────── └ ┘ ─LOGPROC ─ ──┬ ┬ ─procedure_name ──┤ procedure_parms ├─ └ ┘─NONE ──────────────────────────────

procedure_parms:├─ ──┬ ┬────────────────── ──┬ ┬───────────────────── ─────────────┤ └ ┘ ─LANGUAGE ─ ──┬ ┬─C── └ ┘ ─PARM ─ ──┬ ┬─expression─ └ ┘─CL─ └ ┘─NONE ──────

field:├─ ──┬ ┬─field_name─ ──┬ ┬───────────────────────── ────────────────5 └ ┘─\───────── └ ┘ ─OFFSET ──integer_constant ─

5─ ──┬ ┬───────────────────────────── ─field_format───────────────┤ └ ┘ ─LENGTH ─ ──┬ ┬─integer_constant ─ └ ┘─\───────────────


ALTER LOG

Descriptionlog_name

Identifies the log definition that you want to alter.

HEADER (field, ...)Adds or replaces the header definition. The header fields arespecified in the same way as in the DEFINE LOG statement. If aheader is already defined for the log, the entire header definitionis replaced.

HEADER NONEDeletes all header fields.

TIMESTAMP expressionAdds or replaces the timestamp expression.

TIMESTAMP NONEDeletes the timestamp expression.

SOURCE expressionAdds or replaces the source expression.

SOURCE NONEDeletes the source expression.

FIRST RECORD conditionAdds or replaces the first record condition.

FIRST RECORD NONEDeletes the first record condition.

LAST RECORD conditionAdds or replaces the last record condition.

LAST RECORD NONEDeletes the last record condition.

Version 2.010-4

Lan

gu

age S

tatemen

ts

ALTER LOG

LOGPROC procedure_name procedure_parmsAdds or modifies the LOGPROC clause.

If no log procedure is defined for the log, a log proceduredefinition is added. You use thenprocedure_name andprocedure_parms in the same way as in the DEFINE LOGstatement.

If a log procedure is already defined for the log, you useprocedure_name and procedure_parms to alter the existing logprocedure definition:

procedure_nameReplaces the log procedure name. If you do not want to alterthe name, you must code here the same name as alreadydefined.

LANGUAGEAlters the LANGUAGE clause. An omitted LANGUAGEmeans no change.

PARM expressionAdds or replaces the parameter expression.

PARM NONEDeletes the parameter expression.

LOGPROC NONEDeletes the log procedure definition.

ExampleAssume you want to add F_FIELD=1 as the first record condition fora log called SOME_LOG. Use this ALTER LOG statement to addthe condition:

ALTER LOG SOME_LOG FIRST RECORD F_FIELD=1;


ALTER LOG

Usage NotesWhen you use the ALTER LOG statement, you specify only a part ofthe log definition. You cannot see the complete definition. Thismakes the change difficult if the definition is complex. It may bemore convenient to delete the entire definition using a DROPstatement and then store a modified definition using a DEFINE LOGstatement.

Version 2.010-6

Lan

gu

age S

tatemen

ts

ALTER RECORD

ALTER RECORDUse the ALTER RECORD statement to modify a stored recorddefinition. You can add, change, or delete:

■ Fields■ Sections■ Condition that identifies the record■ Name of the record procedure that builds the records

This description assumes that you are familiar with record definitionsand the DEFINE RECORD statement. So, it explains only howALTER RECORD modifies the record definition. It does not explainwhat the modification means. The syntax diagram shows all theclauses that you can specify, but they are explained only as much asit is needed to tell what is altered. See “DEFINE RECORD” onpage 10-31 for more information.


ALTER RECORD

Syntax

55──ALTER RECORD ──record_name ────────────────────────────────────────────────────5

5─ ──┬ ┬ ─IN LOG──log_name ─────────────────────────────────────────────────── ─────────5% ├ ┤ ─BUILT BY ─ ──┬ ┬─procedure_name─ ──────────────────────────────────── │ │└ ┘─NONE ───────────── ├ ┤ ─IDENTIFIED BY─ ──┬ ┬─condition ─ ──────────────────────────────────── │ │└ ┘─NONE ─────── │ │┌ ┐─,─────────── ├ ┤ ─ADD FIELDS─ ──( ───

6┴─┤ field ├─ ) ──┬ ┬─────────────────────────────────

│ │└ ┘ ─IN SECTION──section_name ─ ├ ┤ ─DELETE FIELD ──field_name───────────────────────────────────────── ├ ┤─ADD SECTION ──┤ section ├────────────────────────────────────────── ├ ┤ ─DELETE SECTION──section_name ──────────────────────────────────── └ ┘ ─SECTION──section_name ──┤ section_attributes ├───────────────

section:├──section_name ─ ──┬ ┬───────────────────────────────── ────────────────────────────────5 └ ┘ ─IN SECTION──section_name ─

5─ ──┬ ┬───────────────────────────── ──┬ ┬───────────────────────── ─────────────────────────5 └ ┘ ─PRESENT IF──condition ─ └ ┘ ─OFFSET──expression─5─ ──┬ ┬───────────────────────── ──┬ ┬───────────────────────────── ──┬ ┬───────────── ────────5 └ ┘ ─LENGTH──expression─ └ ┘ ─NUMBER─ ──┬ ┬─expression─ └ ┘─REPEATED ─ └ ┘─\─────────────

5─ ──┬ ┬───────────────────────────────── ──────────────────────────────────────────────────┤ │ │┌ ┐─,─────────── └ ┘ ─FIELDS──(─ ───

6┴─┤ field ├─ ─)─

section_attributes:├─ ──┬ ┬───────────────────────────────────── ──┬ ┬───────────────────────────────── ─────────5 └ ┘ ─IN SECTION─ ──┬ ┬─section_name ─ └ ┘ ─PRESENT IF─ ──┬ ┬─condition ─ └ ┘─NONE ─────────── └ ┘─NONE ───────

5─ ──┬ ┬───────────────────────────── ──┬ ┬───────────────────────────── ─────────────────────5 └ ┘ ─OFFSET─ ──┬ ┬─expression─ └ ┘ ─LENGTH─ ──┬ ┬─expression─ └ ┘─NONE ──────── └ ┘─NONE ────────

5─ ──┬ ┬───────────────────────────── ──┬ ┬───────────────── ─────────────────────────────────┤ └ ┘ ─NUMBER─ ──┬ ┬─expression─ ├ ┤─REPEATED ───── ├ ┤─\───────────── └ ┘─NONREPEATED ─ └ ┘─NONE ────────

field:├─ ──┬ ┬─field_name─ ──┬ ┬───────────────────────────────── ───────────────────────────────5 └ ┘─\───────────── └ ┘ ─OFFSET──integer_constant ─

5─ ──┬ ┬───────────────────────────────────── ─field_format ─────────────────────────────┤ └ ┘ ─LENGTH─ ──┬ ┬─integer_constant ─ └ ┘─\─────────────────────

Descriptionrecord_name

Identifies the record definition that you want to alter.

IN LOG log_nameReplaces the IN LOG clause.

BUILT BY procedure_nameAdds or replaces the BUILT BY clause.

Version 2.010-8

Lan

gu

age S

tatemen

ts

ALTER RECORD

BUILT BY NONEDeletes the BUILT BY clause.

IDENTIFIED BY conditionAdds or replaces the IDENTIFIED BY condition.

IDENTIFIED BY NONEDeletes the IDENTIFIED BY condition.

ADD FIELDS ( field, ... )Adds or replaces one or more fields. The fields are specified inthe same way as in the DEFINE RECORD statement.

IN SECTION section_nameSpecifies the section where to add the fields. An omitted INSECTION means that you want to add fields in the record.

DELETE FIELD field_nameDeletes the field field_name.

ADD SECTION sectionAdds a section. The section is specified in the same way as in theDEFINE RECORD statement.

DELETE SECTION section_nameDeletes the specified section.

SECTION section_nameModifies the attributes of section section_name.

IN SECTION section_nameAdds or replaces the IN SECTION attribute.

IN SECTION NONEDeletes the IN SECTION attribute.

PRESENT IF conditionAdds or replaces the PRESENT IF condition.

PRESENT IF NONEDeletes the PRESENT IF condition.

OFFSET expressionAdds or replaces the OFFSET attribute.


ALTER RECORD

OFFSET NONEDeletes the OFFSET attribute.

LENGTH expressionAdds or replaces the LENGTH attribute.

LENGTH NONEDeletes the LENGTH attribute.

NUMBER expressionNUMBER *

Adds or replaces the NUMBER attribute.

NUMBER NONEDeletes the NUMBER attribute.

REPEATEDSpecifies the section to be repeated.

NONREPEATEDSpecifies the section to be non-repeated.

ExampleAssume that you want to add a 10-byte character field at offset 52 ina section called SUB_SECT. Use this ALTER RECORD statementto add the field:

ALTER RECORD SOME_REC

ADD FIELDS (NEW_FIELD OFFSET 52 CHAR(1ð)) IN SECTION SUB_SECT;

For more examples of how to use the ALTER RECORD statement,see “Using the ALTER RECORD Statement” on page 3-10.

Usage NotesWhen you use the ALTER RECORD statement, you specify only apart of the record definition. You cannot see the complete definition.This makes the change difficult if the definition is complex. It maybe more convenient to delete the entire definition using a DROPstatement and then store a modified definition using a DEFINERECORD statement.

Version 2.010-10

Lan

gu

age S

tatemen

ts

ALTER RECORDPROC

ALTER RECORDPROCUse the ALTER RECORDPROC statement to modify a stored recordprocedure definition. You can change the:

■ Record types for which the record procedure applies■ ■ Parameters that are passed to the record procedure

This description assumes that you are familiar with record proceduresand the DEFINE RECORDPROC statement. So, it explains only howALTER RECORDPROC modifies the definition of a recordprocedure. It does not explain what the modification means. See“DEFINE RECORDPROC” on page 10-39 for more information.

Syntax

55──ALTER RECORDPROC ──procedure_name ────────────────────────5

┌ ┐─,─────────5─ ──┬ ┬─FOR ─ ───

6┴─record_name─ ─ ────────────────────────────5%

├ ┤ ─LANGUAGE ─ ──┬ ┬─C── ──── │ │└ ┘─CL ─ └ ┘ ─PARM ─ ──┬ ┬─expression ─ └ ┘─NONE ──────

Descriptionprocedure_name

Identifies the record procedure definition that you want to alter.

FOR record_name , ...Replaces the list of records processed by the procedure.

LANGUAGEAlters the LANGUAGE clause.

PARM expressionAdds or replaces the parameter expression.

PARM NONEDeletes the parameter expression.


ALTER RECORDPROC

ExampleAssume that you want to change the record procedure definitionPR2CIC1 so the log collector will pass the number 9 to it as aparameter the first time the procedure is called. Use this ALTERRECORDPROC statement to specify the parameter:

ALTER RECORDPROC PR2CIC1 PARM 9;

Usage NotesWhen you use the ALTER RECORDPROC statement, you specifyonly a part of the record procedure definition. You cannot see thecomplete definition. This makes the change difficult if the definitionis complex. It may be more convenient to delete the entire definitionusing a DROP statement and then store a modified definition using aDEFINE RECORDPROC statement.

Version 2.010-12

Lan

gu

age S

tatemen

ts

ALTER UPDATE

ALTER UPDATEUse the ALTER UPDATE statement to modify a stored updatedefinition. You can add, change, or delete:

■ The SECTION clause■ The WHERE clause■ Parts of the LET, GROUP BY, or SET clauses■ The APPLY SCHEDULE, DISTRIBUTE, or MERGE clauses

This description assumes that you are familiar with update definitionsand the DEFINE UPDATE statement. So, it explains only howALTER UPDATE modifies the update definition. It does not explainwhat the modification means. The syntax diagram shows all theclauses that you can specify, but they are explained only as much asit is needed to tell what is altered. See “DEFINE UPDATE” onpage 10-41 for more information.


ALTER UPDATE

Syntax

55──ALTER UPDATE──update_name────────────────────────────────────────5

5─ ──┬ ┬─SECTION─ ──┬ ┬─section_name─ ─────────────── ────────────────────5% │ │└ ┘─NONE───────── ├ ┤ ─WHERE─ ──┬ ┬─condition─ ──────────────────── │ │└ ┘─NONE──────

├ ┤─┤ apply_schedule_clause ├────────────────├ ┤─APPLY SCHEDULE NONE──────────────────────├ ┤─┤ distribute_clause ├────────────────────

├ ┤─DISTRIBUTE NONE──────────────────────────├ ┤──LET identifier = ──┬ ┬─expression─ ───────

│ │└ ┘─NONE───────├ ┤──GROUP BY column_name = ──┬ ┬─expression─ ─

│ │└ ┘─NONE───────├ ┤──SET column_name = ──┬ ┬─┤ accumulation ├─

│ │└ ┘─NONE─────────────├ ┤─┤ merge_clause ├─────────────────────────

└ ┘─MERGE NONE───────────────────────────────

accumulation:├─ ──┬ ┬──SUM (expression) ────────────────────────────────────── ───────┤

├ ┤──MIN (expression) ──────────────────────────────────────├ ┤──MAX (expression) ──────────────────────────────────────├ ┤──COUNT (expression) ────────────────────────────────────├ ┤──FIRST (expression) ────────────────────────────────────├ ┤──LAST (expression) ─────────────────────────────────────├ ┤──AVG (expression, column_name) ─────────────────────────└ ┘──PERCENTILE (expression, column_name, integer_constant)

apply_schedule_clause:├──APPLY SCHEDULE─ ──┬ ┬────────────────────────── ─────────────────────5 └ ┘ ─FOR CALENDAR──expression─

5─ ──TO column_name_1, column_name_2, column_name_3 ───────────────────5

5──PERIOD──identifier────────────────────────────────────────────────┤

distribute_clause: ┌ ┐─,───────────────├──DISTRIBUTE─ ───

6┴──┬ ┬─field_name── ─BY──expression───────────────────5

└ ┘─column_name─

5─ ─START──expression─ ─END──expression──TIMESTAMP──identifier─────────5

5──INTERVAL──identifier──────────────────────────────────────────────┤

merge_clause:├──MERGE──(─ ──column_name = expression ─,─────────────────────────────5

5─ ──column_name = expression ─,─ ──column_name = expression ─,──────────5

5─ ──column_name = expression ─)───────────────────────────────────────┤

Version 2.010-14

Lan

gu

age S

tatemen

ts

ALTER UPDATE

Descriptionupdate_name

Identifies the update definition that you want to alter.

SECTION section_nameAdds or replaces the SECTION clause.

SECTION NONEDeletes the SECTION clause.

WHERE conditionAdds or replaces the WHERE condition.

WHERE NONEDeletes the WHERE condition.

apply_schedule_clauseAdds or replaces the APPLY SCHEDULE clause. The clause isspecified as in the DEFINE UPDATE statement.

APPLY SCHEDULE NONEDeletes the APPLY SCHEDULE clause.

distribute_clauseAdds or replaces the DISTRIBUTE clause. The clause is specifiedas in the DEFINE UPDATE statement.

DISTRIBUTE NONEDeletes the DISTRIBUTE clause.

LET identifier = expressionAdds or replaces the specification of identifier in the LET clause.

LET identifier = NONEDeletes the specification of identifier from the LET clause.

GROUP BY column_name = expressionAdds or replaces the specification of column column_name in theGROUP BY clause.

GROUP BY column_name = NONEDeletes the specification of column column_name from theGROUP BY clause.


ALTER UPDATE

SET column_name = accumulationAdds or replaces the specification of column column_name in theSET clause.

SET column_name = NONEDeletes the specification of column column_name from the SETclause.

merge_clauseAdds or replaces the MERGE clause. The clause is specified as inthe DEFINE UPDATE statement.

MERGE NONEDeletes the MERGE clause.

ExampleThe update definition UPD_WKLD applies to records of typeWKLD_REC, which contain a field WRKFLD. Assume that youwant to change UPD_WKLD so that it will only apply toWKLD_REC records when WRKFLD is not equal to 120. Use thisALTER UPDATE statement to change the condition to whichUPD_WKLD applies:

ALTER UPDATE UPD_WKLD

WHERE WRKFLD <> 12ð;

For more information about using the ALTER UPDATE statement,see “Changing and Deleting Update Definitions” on page 5-37.

Usage NotesWhen you use the ALTER UPDATE statement, you specify only apart of the update definition. You cannot see the complete definition.This makes the change difficult if the definition is complex. It maybe more convenient to delete the entire definition using a DROPstatement and then store a modified definition using a DEFINEUPDATE statement.

Version 2.010-16

Lan

gu

age S

tatemen

ts

COLLECT

COLLECTUse the COLLECT statement to collect log data. The processing iscontrolled by the stored definitions of the log, records, and updates.

Syntax

┌ ┐─,────────55──COLLECT──log_name ──FROM ─ ───

6┴─file_name ─ ────────────────5

5─ ──┬ ┬───────────────── ─────────────────────────────────5 └ ┘ ─WHERE ──condition ─

5─ ──┬ ┬───────────────────────────────────── ─────────────5 │ │┌ ┐─,─────────────────────── └ ┘ ─INCLUDE─ ───

6┴──┬ ┬─table_name ───────────

└ ┘ ─LIKE ──string_constant ─

5─ ──┬ ┬───────────────────────────────────── ─────────────5 │ │┌ ┐─,─────────────────────── └ ┘ ─EXCLUDE─ ───

6┴──┬ ┬─table_name ───────────


5─ ──┬ ┬────────── ────────────────────────────────────────5 └ ┘─REPROCESS ─

5─ ──┬ ┬──────────────────────────────────────── ──────────5 │ │┌ ┐─BUFFER FULL──────────── └ ┘─COMMIT AFTER─ ──┼ ┼─END OF FILE────────────── ├ ┤ ─integer_constant ──RECORDS─

└ ┘─BUFFER FULL ONLY ─────────

5─ ──┬ ┬─────────────────────────── ───────────────────────5 └ ┘ ─BUFFER SIZE──integer_constant ─

5─ ──┬ ┬──────────────────────── ─────────────────────────5% │ │┌ ┐─BREAK─── └ ┘ ─ON OVERFLOW─ ──┴ ┴─CONTINUE ─


COLLECT

Descriptionlog_name

Is the name of a stored log definition. It identifies the type of logto be collected.

FROM file_name, ...Names one or more log files to be collected. The files areprocessed in the order in which they are specified.

WHERE conditionLimits processing to those records for which the condition is true.Any identifiers used in the condition must be names of log headerfields. If there is a log procedure, the condition applies to therecords produced by the log procedure. Otherwise, the conditionis applied to the records from the log. The condition is notapplied to the records produced by record procedures.

INCLUDELimits collect to update only the specified tables. If you specifyINCLUDE, the log collector does not update any other tablesassociated with this log definition.

table_nameIs the name of a table to be included.

LIKE string_constantSpecifies a group of tables to be included. The tables arethose with names matching the pattern specified as thestring_constant. The pattern matching rules are defined in“Pattern Matching” on page 8-17. If the pattern contains aperiod (.), the table prefix must match the part before theperiod, and the rest of the table name must match the partafter the period. For example, the pattern PERFREP.ABCD%includes all tables whose names start with ABCD and havePERFREP as the prefix.

If the pattern does not contain a period, the prefix must be thecurrent user ID, and the rest of the name must match thewhole pattern.

Version 2.010-18

Lan

gu

age S

tatemen

ts

COLLECT

EXCLUDEPrevents collect from updating the specified tables. If you specifyEXCLUDE, the log collector updates all other tables associatedwith this log definition.


LIKE string_constantSpecifies a group of tables to be excluded, using the samerules as for INCLUDE.

REPROCESSInstructs the log collector to collect data from the log data set inits entirety even if that data set has already been partially orcompletely processed.

COMMIT AFTERSpecifies when the log collector should execute COMMIT tomake the database updates permanent. (The log collector alwayswrites its internal buffer to the database before issuing COMMIT,but it may write the buffer to the database without committing theupdates.)

If a collect abends after a commit, at least part of the data set hasbeen successfully processed. The log collector can automaticallyresume collecting data from the log at the point where the logcollector made the commit.

The possible options are:

BUFFER FULLCommit in each of these situations:

■ After the internal buffer was filled and written to thedatabase

■ At the end of each log file■ After the entire input was processed


COLLECT

END OF FILECommit only after the entire input has been processed.

integer_constant RECORDSCommit in each of these situations:

■ After processing the number of records specified by theinteger_constant


■ At the end of each log file■ After the entire input was processed

This option results in the longest execution time, comparedwith other COMMIT AFTER options.

BUFFER FULL ONLYCommit in each of these situations:


■ After the entire input was processed

This option will normally result in a shorter execution timewhen processing concatenated log data sets.

BUFFER SIZE integer_constantSpecifies the size (in bytes) of the internal collect buffer. Thedefault is 10 000 000 bytes. The minimum allowed value is 10 000bytes. The maximum size of the internal collect buffer is limitedby the virtual storage available when the log collector executes. Ifyou specify a BUFFER SIZE that exceeds the available virtualstorage, the log collector abends.

Notice that the log collector sometimes requires more bufferspace than you specify. It terminates if it cannot obtain the extraspace.

ON OVERFLOWSpecifies the action to be taken in case of an overflow. Anoverflow is a situation when a numeric value accumulated in atable column becomes too large for that column. The possibleoptions are:

Version 2.010-20

Lan

gu

age S

tatemen

ts

COLLECT

BREAKStop data collection. Do not update the database.

CONTINUEReset the column to 0, write the lost value to the standarderror output, and continue data collection.

ExampleAssume that you want to update only two tables,NETWORK_SESSIONS and DB2_ACCOUNTING, with data fromSMF log files named logs/file.1 and logs/file.2. You also want towrite the internal buffer to the database and commit the change afterevery 5 000 records in the log data set have been processed.

COLLECT SMF

FROM SMFLOG FILE 'logs/file.1', 'logs/file.2'

WHERE SMFSID = 'MVS1'

INCLUDE NETWORK_SESSIONS, DB2_ACCOUNTING

COMMIT AFTER 5ððð RECORDS;

For more information about using the COLLECT statement, see“Collecting Log Data” on page 6-1.

Usage NotesYou can specify both INCLUDE and EXCLUDE on a COLLECTstatement. For example, INCLUDE LIKE 'PERFREP.ABCD%'EXCLUDE PERFREP.ABCDAPPL includes all ABCD tables exceptPERFREP.ABCDAPPL.


COMMENT ON

COMMENT ONUse the COMMENT ON statement to add or replace comments instored definitions. You can add or replace comments for:

■ Log definitions■ Record definitions■ Record procedure definitions■ Update definitions

Syntax

55──COMMENT ON ─ ──┬ ┬ ─LOG ──log_name ────────────── ───────────5 ├ ┤─RECORD──record_name────────── ├ ┤ ─FIELD ──record_name.field_name─ ├ ┤ ─RECORDPROC ──procedure_name ─── └ ┘─UPDATE──update_name──────────

5──IS ──string_constant ───────────────────────────────────5%

DescriptionLOG log_name

Specifies that the comment applies to the log definitionlog_name.

RECORD record_nameSpecifies that the comment applies to the record definitionrecord_name.

FIELD record_name.field_nameSpecifies that the comment applies to the field field_name in therecord definitionrecord_name.

RECORDPROC procedure_nameSpecifies that the comment applies to the record proceduredefinition procedure_name.

UPDATE update_nameSpecifies that the comment applies to the update definitionupdate_name.

Version 2.010-22

Lan

gu

age S

tatemen

ts

COMMENT ON

IS string_constantSpecifies the comment text, which can be any character string upto 254 characters long.

ExamplesAssume you want to add a comment to the field WRKLD in therecord type HOUR_REC. Use this COMMENT ON statement to addthe comment:

COMMENT ON FIELD HOUR_REC.WRKLD

IS 'New definition for the WRKLD field';

Usage Notes■ The comments stored using the COMMENT ON statement can

be viewed using the administration dialog. (See the TME 10Reporter Installation and Administrationmanual.)

■ To store comments for the database tables and their columns,use the COMMENT ON statement that is part of SQL.

■ Notice that the double minus sign (--) comments and the slashasterisk (/\) asterisk slash (\/) comments are not stored withyour definitions.


DEFINE LOG

DEFINE LOGUse the DEFINE LOG statement to define a log type.

Syntax

55──DEFINE LOG ──log_name ─ ──┬ ┬─────────────────────── ──────5 └ ┘ ─VERSION──string_constant ─

5─ ──┬ ┬──────────────────────── ──────────────────────────5 │ │┌ ┐─,───── └ ┘ ─HEADER──(─ ───

6┴─field ─ ─)─

5─ ──┬ ┬───────────────────── ──┬ ┬────────────────── ───────5 └ ┘ ─TIMESTAMP ──expression ─ └ ┘ ─SOURCE──expression ─

5─ ──┬ ┬────────────────────── ──┬ ┬───────────────────── ───5 └ ┘ ─FIRST RECORD──condition ─ └ ┘ ─LAST RECORD──condition ─

5─ ──┬ ┬───────────────────────────────────────── ────────5% └ ┘ ─LOGPROC──procedure_name ──┤ procedure_parms ├─

procedure_parms:├─ ──┬ ┬───────────────── ──┬ ┬───────────────── ────────────┤ │ │┌ ┐─C── └ ┘ ─PARM ──expression ─ └ ┘ ─LANGUAGE ─ ──┴ ┴─CL ─

field:├─ ──┬ ┬─field_name ─ ──┬ ┬─────────────────────── ────────────5 └ ┘─\───────── └ ┘ ─OFFSET──integer_constant ─

5─ ──┬ ┬─────────────────────────── ─field_format────────────┤ └ ┘ ─LENGTH─ ──┬ ┬─integer_constant ─ └ ┘─\──────────────

Descriptionlog_name

The name of the log type being defined. It must be an identifier,at most 16 bytes long. All log types defined to the log collectormust have distinct names.

Version 2.010-24

Lan

gu

age S

tatemen

ts

DEFINE LOG

VERSION string_constantThe string specified by the string_constant is stored together withthe definition, to identify the statement that was used to create thedefinition. The string can be at most 18 bytes long. OmittedVERSION means the same as specifyingVERSION ''.

If the stored definition is later altered by means of an ALTERLOG statement, its version identification is changed to'ALTERED'.

HEADER (field, ... )Defines the fields that are common to all records. There is a limitof 2 000 fields in a header definition.

fieldDefines one field.

This general rule applies to all fields:

The LENGTH and OFFSET (explicit or default) define a fieldas an area so many bytes long, starting at a specific place inthe record. If the record is too short to contain ALL bytes of afield, the field is considered absent and a reference to itproduces null value.

The above rule has one exception: LENGTH *. The asterisklength means that the field extends up to the end of therecord. The field is absent if the record is too short to containthe first byte of the field.

field_nameThe name of the field. It can be any identifier. Fieldnames must be unique within a header.

OFFSET integer_constantDefines the offset of the field in the record.

If you omit OFFSET, the field starts at the end of thefield defined just before it. The preceding field cannothave an asterisk length. If you omit the offset for the firstfield in the list, that field begins at offset 0.


DEFINE LOG

LENGTH integer_constantDefines the length of the field in bytes. The allowedlengths depend on the format of the field. See Table 42on page 10-37; the Length column states the possiblelength(s) of the field.

If you omit LENGTH, the log collector uses the defaultlength depending on the field format. If the Lengthcolumn in Table 42 on page 10-37 specifies a singlevalue, this is the default. Otherwise the default is stated inthe column.

LENGTH *Indicates that the field extends up to the end of the record.

field_formatSpecifies the format of the data contained in the field. Thepossible values of field_format are listed in Table 42 onpage 10-37, in the Field format column. The Data typecolumn states the data type to which the log collectorautomatically converts the content of the field when ituses that field.

TIMESTAMP expressionDescribes how the timestamp of the records is derived from thefields in the header. The log collector prints the timestamp of thefirst and last processed records in the log file (and saves thesetimestamps in a system table) to identify which time period thelog covers.

The result of expression must be a timestamp. Any identifiersused in the expression must be names of log header fields.

SOURCE expressionDescribes how the source of the log is derived from the fields inthe header. The log collector prints the source obtained from thefirst record in the log file (and saves it in a system table) toidentify the file.

The result of expression must be a character string. Anyidentifiers used in the expression must be names of log headerfields.

Version 2.010-26

Lan

gu

age S

tatemen

ts

DEFINE LOG

FIRST RECORD conditionSpecifies a condition that the first record in the log data setshould satisfy. If this condition is not met, the log collector givesa warning message.

Any identifiers used in the condition must be names of log headerfields.

LAST RECORD conditionSpecifies a condition that the last record in the log data set shouldsatisfy. If this condition is not met, the log collector gives awarning message.

Any identifiers used in the condition must be names of log headerfields.

LOGPROC procedure_nameIdentifies the log procedure for the log. The log procedure mustbe present in one of the directories listed in the default librarypath.

LANGUAGESpecifies the interface to the procedure: the language, linkageconvention, and parameters.

C The procedure is written in C and is called using Clinkage conventions. It returns length of the output recordin a field within the record (no length parameter).

CL The procedure is written in C and is called using Clinkage conventions. It returns length of the output recordin a variable supplied as a parameter.

See “Using Log and Record Procedures” on page A-1 fordetails.

PARM expressionSpecifies an expression that the log collector evaluates andpasses to the log procedure the first time it is called. Theprocedure must understand the format and interpret the valuederived from the expression.


DEFINE LOG

The expression cannot contain identifiers. The result ofexpression must be an integer, a floating-point number, or acharacter string.

ExampleDefine a log type named XMP, identifying fields where the logcollector can obtain timestamp information. Also, tell the logcollector how to determine the first and last records in this log.

DEFINE LOG XMP

HEADER(XMPRTY LENGTH 1 EXTERNAL INTEGER,

XMPTME TIME(HHMMSS),

XMPDTE DATE(YYMMDD),

XMPSID CHAR(4),

XMPSSI CHAR(4),

XMPSTY LENGTH 2 EXTERNAL INTEGER)

TIMESTAMP TIMESTAMP(XMPDTE,XMPTME)

FIRST RECORD XMPRTY = 2

LAST RECORD XMPRTY = 3;

For more information about using the DEFINE LOG statement, see“Describing the Log File and Its Records” on page 2-4 and“Verifying Log Data Sets During Data Collection” on page 6-5.

For more information about using log procedures, see “Using Logand Record Procedures” on page A-1.

Version 2.010-28

Lan

gu

age S

tatemen

ts

DEFINE PURGE

DEFINE PURGEUse the DEFINE PURGE statement to store a purge condition. Thestored condition is used by the PURGE statement to determine whichdata should be purged (see “PURGE” on page 10-68).

Syntax

55──DEFINE PURGE─ ──┬ ┬─────────────────────── ─FROM ─────────5 └ ┘ ─VERSION──string_constant ─

5──table_name ─ ──┬ ┬──────────────────── ──────────────────5% └ ┘ ─WHERE ──sql_condition ─

DescriptionVERSION string_constant

The string specified by the string_constant is stored together withthe purge condition, to identify the statement that was used tocreate the condition. The string can be at most 18 bytes long.Omitted VERSION means the same as specifyingVERSION ''.

FROM table_nameSpecifies the name of the table to which the purge conditionapplies.

WHERE sql_conditionSpecifies which data in the table should be deleted by PURGE.The sql_condition is executed by the database manager.

The sql_condition must be a valid SQL search condition for thetabletable_name, and its individual tokens must be recognized bythe log collector.

ExampleWrite a DEFINE PURGE statement to define conditions so that thelog collector deletes data in the PERFREP.TRANSACTIONS_H tablewhen the APPLICATION is not equal to ACCT and the date in thedata is more than 7 days old, or when the APPLICATION is ACCTand the data is more than 14 days old:


DEFINE PURGE

DEFINE PURGE

FROM PERFREP.TRANSACTIONS_H

WHERE APPLICATION <> 'ACCT' AND DTE < CURRENT DATE - 7 DAYS

OR APPLICATION = 'ACCT' AND DTE < CURRENT DATE - 14 DAYS;

Notice that the syntax of sql_condition in the WHERE clause may bedifferent for different database managers. The above example assumesDB2/6000. If you are using ORACLE as the database manager, youhave to use this WHERE clause instead:

WHERE APPLICATION <> 'ACCT' AND DTE < SYSDATE - 7OR APPLICATION = 'ACCT' AND DTE < SYSDATE - 14;

Usage NotesYou can have at most one purge condition for each table. If youexecute a DEFINE PURGE statement for a table that already has apurge condition, the new condition replaces the old condition.

Version 2.010-30

Lan

gu

age S

tatemen

ts

DEFINE RECORD

DEFINE RECORDUse the DEFINE RECORD statement to define a record type.

Syntax

55──DEFINE RECORD ──record_name─ ──┬ ┬─────────────────────── ──5 └ ┘ ─VERSION──string_constant ─

5─ ─IN LOG──log_name ─ ──┬ ┬─────────────────────── ───────────5 └ ┘ ─BUILT BY ──procedure_name ─

5─ ──┬ ┬─────────────────────── ───────────────────────────5 └ ┘ ─IDENTIFIED BY ──condition ─

5─ ──┬ ┬──────────────────────────── ──────────────────────5 │ │┌ ┐─,───────── └ ┘ ─FIELDS──(─ ───

6┴─┤ field ├─ ─)─

┌ ┐────────────────────────5─ ───

6┴┬ ┬──────────────────── ───────────────────────────5%

└ ┘ ─SECTION──┤ section ├─

section:├──section_name─ ──┬ ┬─────────────────────── ───────────────5 └ ┘─IN SECTION ──section_name─

5─ ──┬ ┬───────────────────── ──┬ ┬────────────────── ───────5 └ ┘─PRESENT IF ──condition ─ └ ┘ ─OFFSET──expression ─

5─ ──┬ ┬────────────────── ──┬ ┬────────────────────── ──────5 └ ┘ ─LENGTH──expression ─ └ ┘ ─NUMBER─ ──┬ ┬─expression ─ └ ┘─\─────────

5─ ──┬ ┬───────── ──┬ ┬──────────────────────────── ─────────┤ └ ┘─REPEATED ─ │ │┌ ┐─,───────── └ ┘ ─FIELDS──(─ ───

6┴─┤ field ├─ ─)─

field:├─ ──┬ ┬─field_name ─ ──┬ ┬─────────────────────── ────────────5 └ ┘─\───────── └ ┘ ─OFFSET──integer_constant ─

5─ ──┬ ┬─────────────────────────── ─field_format────────────┤ └ ┘ ─LENGTH─ ──┬ ┬─integer_constant ─ └ ┘─\──────────────


DEFINE RECORD

Descriptionrecord_name

The name of the record type being defined. It can be anyidentifier, except that it cannot both start and end with an asterisk(*). All record types defined to the log collector must havedistinct names.


If the stored definition is later altered by means of an ALTERRECORD statement, its version identification is changed to'ALTERED'.

IN LOG log_nameIndicates that this record is encountered when processing log filesof type log_name (and only such logs). The record is one of therecords in the log, or is built by a record procedure from one ofthe records in the log (or from other records built from these).

BUILT BY procedure_nameIndicates that this record does not appear in the log file, but isbuilt by the record procedure procedure_name. An omittedBUILT BY clause means that the record appears in the log file.

IDENTIFIED BY conditionTells how to distinguish records of this type from other records.A record is of the type record_name if the condition is true. Aspecific record may satisfy the IDENTIFIED BY condition ofseveral record definitions. The log collector uses then only one ofthese definitions (undefined which one).

Any identifiers used in the condition must be names of fieldsdefined directly in the record (not in the sections within therecord).

An omitted IDENTIFIED BY clause is equivalent to specifying acondition that is true for every record.

Version 2.010-32

Lan

gu

age S

tatemen

ts

DEFINE RECORD

SECTION sectionDefines one section. There is a limit of 300 sections in a record.These clauses describe a section:

section_nameThe name of the section. It can be any identifier. Sectionnames must be unique within a record type.

IN SECTION section_nameIndicates that the section being defined is a subsection of thesection named section_name. If you omit the IN clause, thesection is a section of the record. The section section_namemust be defined earlier in this record definition.

PRESENT IF conditionIndicates that the section is optional. The section is absent ifthe condition is not true. The section may be absent even ifthe condition is true, if the containing section (or record) istoo short to contain the first byte of the section.

Any identifiers used in the condition must be names of fieldsin the section being defined, in the containing sections, in therecord, or in previously defined nonrepeated subsections ofthese.

OFFSET expressionDefines the offset of the section within the containing section(or record).

The expression must specify an integer ≥ 0. Any identifiersused in the expression must be names of fields in thecontaining sections, in the record, or in previously definednonrepeated subsections of these.

If you omit OFFSET, the section starts at the end of the mostrecently defined section with the same IN SECTION attribute.That section cannot be a repeated section. If no section withthe same IN SECTION attribute has been previously defined,an omitted OFFSET means offset 0.


DEFINE RECORD

LENGTH expressionDefines the length of the section.

The expression must specify an integer > 0. Any identifiersused in the expression must be names of fields in the sectionbeing defined, in the containing sections, in the record, or inpreviously defined nonrepeated subsections of these.

If you omit LENGTH, the log collector assumes the minimumlength needed to contain all named fields specified for thissection.

If the containing section (or record) is too short to contain thewhole section, the log collector assumes that the sectionextends up to the end of the containing section (or record). Ifthe containing section (or record) is too short to contain thefirst byte of the section, the section is absent.

NUMBER expressionDefines the number of occurrences of the section.

The expression must specify an integer ≥ 0. Any identifiersused in the expression must be names of fields in thecontaining sections, in the record, or in previously definednonrepeated subsections of these.

An omitted NUMBER clause means the same as NUMBER 1.

NUMBER *Defines the number of occurrences of the section to be asmany occurrences as the containing section (or record) canhold.

REPEATEDMeans that the section is repeated. If you omit REPEATED,the section is not repeated.

FIELDS ( field, ... ) Defines all fields of the record or section. There is a limit of2 000 fields in a record.

Version 2.010-34

Lan

gu

age S

tatemen

ts

DEFINE RECORD

fieldDefines one field.

This general rule applies to all fields:

The LENGTH and OFFSET (explicit or default) define a field asan area so many bytes long, starting at a specific place in therecord (or section). If the record (or section) is too short tocontain ALL bytes of a field, the field is considered absent and areference to it produces null value.

The above rule has one exception: LENGTH *. The asterisklength means that the field extends up to the end of the record (orsection). The field is absent if the record (or section) is too shortto contain the first byte of the field.

field_nameThe name of the field. It can be any identifier. Field namesmust be unique within a record type.

OFFSET integer_constantDefines the offset, in bytes, of the field in the record (orsection).

If you omit OFFSET, the field starts at the end of the fielddefined just before it. The preceding field cannot have anasterisk length. If you omit the offset for the first field in thelist, that field begins at offset 0.

LENGTH integer_constantDefines the length of the field in bytes. The allowed lengthsdepend on the format of the field. See Table 42 onpage 10-37; the Length column states the possible length(s)of the field.

If you omit LENGTH, the log collector uses the default lengthdepending on the field format. If the Length column inTable 42 on page 10-37 specifies a single value, this is thedefault. Otherwise the default is stated in the column.

LENGTH *Indicates that the field extends up to the end of the containingstructure (record or section).


DEFINE RECORD

field_formatSpecifies the format of the data contained in the field. Thepossible values of field_format are listed in Table 42 onpage 10-37, in the Field format column. The Data typecolumn states the data type to which the log collectorautomatically converts the content of the field when it usesthat field.

Version 2.010-36

Lan

gu

age S

tatemen

ts

DEFINE RECORD

Table 42. Field Formats

Field format Contents Lengthin bytes

Data type

EXTERNALINTEGER

A string of characters, representingan integer in the same format asfor integer constants. Optionalsign, leading and trailing blanksare allowed.

1 - 32default8

Integer

EXTERNAL FLOAT A string of characters expressing afloating-point number in the sameformat as for floating-pointconstants. Leading and trailingblanks are allowed.

1 - 32default8

Floating-point

CHAR A string of characters. Can containmultiple-byte characters.

1 - 254default1

String

CHAR(n)

where 1 ≤ n ≤ 254

A string of characters occupying nbytes. Can contain multiple-bytecharacters.

n String

CHAR(*) A string of characters, extendingup to the end of the containingstructure. Can containmultiple-byte characters. If thestring is longer than 254 bytes, itis truncated; the truncation canoccur within a multiple-bytecharacter. This format is onlyallowed with LENGTH *.

*(1-254)

String

DATE(YYMMDD) Date as character string yymmdd,whereyy is the year.mm is themonth,dd is the day.yy≥50 meansyear 19yy; yy<50 means year 20yy.

6 Date

TIME(HHMMSS) Time as character string hhmmss,wherehh is hours,mm is minutes,andss is seconds.

6 Time


DEFINE RECORD

ExampleDefine a simple record without sections.

DEFINE RECORD

IN LOG VMACCT

IDENTIFIED BY XMPCODE='ð1'

FIELDS

(XMPUSER OFFSET ð LENGTH 8 CHAR,

XMPNUM OFFSET 8 LENGTH 8 CHAR,

XMPDATE OFFSET 16 LENGTH 6 DATE(YYMMDD),

XMPTIM OFFSET 22 LENGTH 6 TIME(HHMMSS),

XMPCONT OFFSET 28 LENGTH 4 EXTERNAL INTEGER,

XMPCODE OFFSET 78 LENGTH 2 CHAR);

For more information about using the DEFINE RECORD statement,see “Getting Started With the Log Collector Language” on page 2-1and “Defining a Record Containing a Section” on page 3-4.

Usage NotesUsing facilities of the log collector language, you can processdate/time formats other than those supported in the DEFINERECORD statement. As an example, suppose that your recordscontain date in the form of a character string yyddd, where yy are thelast two digits of year, and ddd is day number within the year. Thedate starts at offset 36 within the record. To process the date, specifythese fields in your DEFINE RECORD statement:

YY OFFSET 36 LENGTH 2 CHAR,

DDD OFFSET 38 LENGTH 3 EXTERNAL INTEGER,

Use this expression to obtain the date in your DEFINE UPDATEstatement:

DATE('19' || YY || '-ð1-ð1') + (DDD-1) DAYS

Another example of processing an unsupported field format is givenin “Using Log and Record Procedures” on page A-1.

Version 2.010-38

Lan

gu

age S

tatemen

ts

DEFINE RECORDPROC

DEFINE RECORDPROCUse the DEFINE RECORDPROC statement to specify recordprocedure, that is, a procedure that the log collector calls each time itprocesses a record of a particular type.

Syntax

55──DEFINE RECORDPROC──procedure_name ────────────────────────5

┌ ┐─,─────────5─ ──┬ ┬─────────────────────── ─FOR ─ ───

6┴─record_name─ ───────5

└ ┘ ─VERSION──string_constant ─

5──┤ procedure_parms ├───────────────────────────────────5%

procedure_parms:├─ ──┬ ┬───────────────── ──┬ ┬───────────────── ────────────┤ │ │┌ ┐─C── └ ┘ ─PARM ──expression ─ └ ┘ ─LANGUAGE ─ ──┴ ┴─CL ─

Descriptionprocedure_name

The name of the record procedure. The record procedure must bepresent in one of the directories listed in the default library path.


If the stored definition is later altered by means of an ALTERRECORDPROC statement, its version identification is changed to'ALTERED'.

FOR record_name , ...Enumerates record types that this record procedure processes.

LANGUAGESpecifies the interface to the procedure: the language, linkageconvention, and parameters.


DEFINE RECORDPROC

C The procedure is written in C and is called using C linkageconventions. It returns length of the output record in a fieldwithin the record (no length parameter).

CL The procedure is written in C and is called using C linkageconventions. It returns length of the output record in avariable supplied as a parameter.

See “Using Log and Record Procedures” on page A-1 for details.

PARM expressionSpecifies an expression that the log collector evaluates and passesto the procedure the first time it is called. The procedure mustunderstand the format and interpret the value derived from theexpression.

The expression cannot contain identifiers. The result of expressionmust be an integer, a floating-point number, or a character string.

ExampleIdentify a procedure named xconfig that processes record typesXCONFIG_HW and XCONFIG_SW. The program requires aparameter that is supplied via a variable XCONFIG_OPT. Use thisDEFINE RECORDPROC statement to identify the record procedure:

DEFINE RECORDPROC "xconfig"

FOR XCONFIG_HW, XCONFIG_SW

PARM :XCONFIG_OPT;

Notice that a lowercase procedure name must be coded as a delimitedword, in quotation marks.

For more information about using the DEFINE RECORDPROCstatement, see “Using Log and Record Procedures” on page A-1.

Version 2.010-40

Lan

gu

age S

tatemen

ts

DEFINE UPDATE

DEFINE UPDATEUse the DEFINE UPDATE statement to specify how to process datafrom a given record type or a given data table (the source of theupdate), and how to store the result in another data table (the targetof the update).

Syntax

55──DEFINE UPDATE ──update_name─ ──┬ ┬─────────────────────── ──5 └ ┘ ─VERSION──string_constant ─

5─ ─FROM ─ ─source_name─ ──┬ ┬──────────────────── ─────────────5 └ ┘ ─SECTION──section_name─

5─ ──┬ ┬───────────────── ─TO ──table_name ───────────────────5 └ ┘ ─WHERE ──condition ─

5─ ──┬ ┬──────────────────── ──┬ ┬──────────────── ──────────5 └ ┘ ─apply_schedule_clause ─ └ ┘ ─distribute_clause─

5─ ──┬ ┬─────────── ──┬ ┬─────────────── ──┬ ┬──────────── ───5% └ ┘ ─let_clause ─ └ ┘ ─group_by_clause ─ ├ ┤─set_clause ── └ ┘─merge_clause─

Descriptionupdate_name

The name of the update being defined. It can be any identifier.All updates defined to the log collector must have distinct names.


If the stored definition is later altered by means of an ALTERUPDATE statement, its version identification is changed to'ALTERED'.


DEFINE UPDATE

FROM source_nameIdentifies the source for the update definition. Must be a recordtype name or a table name.

SECTION section_nameSpecifies that the source of the update is a repeated sectionsection_name of the record source_name. As explained in“Using Repeated Sections Within Records” on page 5-23, thelog collector then generates an internal record for eachoccurrence of the repeated section. The source of the update isthat internal record.

If the record source_name has repeated sections, and you omitthe SECTION clause, the update can only use the data that isoutside the repeated sections.

WHERE conditionLimits the update to only those source records or rows for whichthe condition is true. Any identifier used in the condition must bethe name of a field in the source record or of a column in thesource table.

TO table_nameNames the table to be updated.

apply_schedule_clausedistribute_clauselet_clausegroup_by_clauseset_clausemerge_clause

These clauses specify the processing to be done. You can think ofthem as instructions, executed in the order they appear in thestatement. They are described in detail in separate sections.

You will normally use only two or three of these clauses in oneupdate definition. For the update definition to make sense, youmust specify at least one of these: GROUP BY clause, SETclause, or MERGE clause.

The first clause that you specify uses as its input the sourcerecords or rows from the table source_name. Each of the

Version 2.010-42

Lan

gu

age S

tatemen

ts

DEFINE UPDATE

subsequent clauses uses the result of the preceding clause as itsinput.

The result of the APPLY SCHEDULE and DISTRIBUTE clausesis a temporary internal table. The LET clause only defines morenames, and passes the internal table (if any) to the next clause.The result of GROUP BY clause are groups of records or rows.The result of SET and MERGE clauses are updates to the targettable.

Any identifier used in an expression in any of the clauses must bethe name of a field (or column) in the source record (or table), ora name introduced in one of the preceding clauses. Notice that theAPPLY SCHEDULE clause introduces one name (that of periodcolumn), the DISTRIBUTE introduces two names (these oftimestamp and interval column), and the LET clause canintroduce any number of names.


DEFINE UPDATE

ExampleDefine how to enter data from records of type VMACCT_01 intotable PERFREP.VM_ACCOUNTING_D.

DEFINE UPDATE MKTVACC_ð1D

FROM VMACCT_ð1

TO PERFREP.VM_ACCOUNTING_D

GROUP BY

(DATE = ACODATE,

USER_ID = ACOUSER,

ACCOUNT_NUMBER = ACONUM)

SET

(CONNECT_TIME = SUM(ACOCONT),

PROCESSOR_TIME = SUM(ACOTIME/1ððð),

VIRTPROC_TIME = SUM(ACOVTIM/1ððð),

PAGE_READS = SUM(ACOPGRD),

PAGE_WRITES = SUM(ACOPGWT),

IO_COUNT = SUM(ACOIOCT),

PUNCH_CARDS = SUM(ACOPNCH),

PRINT_LINES = SUM(ACOLINS),

READER_CARDS = SUM(ACOCRDS),

VECTOR_TIME = SUM(ACOVECTM/1ððð),

VECTOR_OVERHEAD = SUM(ACOVECTT/1ððð));

Version 2.010-44

Lan

gu

age S

tatemen

ts

DEFINE UPDATE

APPLY SCHEDULE ClauseThis clause applies a specified schedule to the source. The sourcemay be a record type or a table. For the purpose of this description, itis assumed to be a table.

The source must contain availability data. That means each row mustrepresent an interval described by three items: interval type, intervalstart, and interval end. The row can also contain other data.

The schedules are defined by the system table CAL_DAY_PERIOD.This table should be set up when the product is installed. (For moreinformation, refer to theTME 10 Reporter Installation andAdministration manual.)

As explained under “PERIOD” on page 9-20, the tableCAL_DAY_PERIOD defines one schedule for each calendar used byyour installation. A schedule divides each day into named intervals(such as shifts). These intervals are called periods. The partition of aday into periods depends on theday type of the day. The day typesare defined by the system tables CAL_DAY_OF_WEEK andCAL_SPECIAL_DAY, as explained under “DAYTYPE” onpage 9-7. The calendars are internally identified by integers, such as0 or 5.

The result of the APPLY SCHEDULE clause is a temporary internaltable. It is a copy of the source table, with these modifications:

■ The intervals are split on boundaries between the periods. Therows resulting from the split contain the same data as theoriginal row, except the interval type, interval start, and intervalend, which are modified.

■ A period column is added. The column contains the name of theperiod containing the interval. If the interval is not contained inany period, the column contains blanks; this can only happen ifone, or both, of the tables CAL_DAY_OF_WEEK andCAL_DAY_PERIOD is incomplete.

See “Summarizing Availability by Schedule Period” on page 5-19 formore information about using the APPLY SCHEDULE clause.


DEFINE UPDATE

The syntax of the APPLY SCHEDULE clause is:

55──APPLY SCHEDULE ─ ──┬ ┬─────────────────────── ────────────5 └ ┘ ─FOR CALENDAR──expression ─

5─ ──TO column_name_1 , column_name_2 , column_name_3 ────────────5

5──PERIOD──identifier ────────────────────────────────────5%

FOR CALENDAR expressionIdentifies the schedule by its calendar number. The expressionmust specify an integer. Omitted FOR CALENDAR meanscalendar 0.

column_name_1Names the source column that contains interval type code. It mustbe a character column of length 3.

column_name_2Names the source column that contains the interval start. It mustbe a timestamp column.

column_name_3Names the source column that contains the interval end. It mustbe a timestamp column.

PERIOD identifierSpecifies the name for the period column in the resulting internaltable.

DISTRIBUTE ClauseThis clause distributes input values over specified time periods. Theinput to this clause is the source record type, or source table, or theinternal table that is the result of the preceding APPLY SCHEDULEclause. For the purpose of this description, it is assumed to be a table.

Each input row must contain data related to a time interval.

The result of the DISTRIBUTE clause is a temporary internal table.It is a copy of the source, with these modifications:

■ The intervals are split on boundaries between the time periods.The rows resulting from the split contain the same data as the

Version 2.010-46

Lan

gu

age S

tatemen

ts

DEFINE UPDATE

original row, except for the columns specified to be distributed.The data in these columns is distributed in proportion to thelength of the interval.

■ A timestamp and interval columns are added. The timestampcolumn contains the start of the interval represented by the row.The interval column contains the length of the interval inseconds.

See “Distributing Measurements” on page 5-7 for more informationabout using the DISTRIBUTE clause.

The syntax of the DISTRIBUTE clause is:

┌ ┐─,─────────────55──DISTRIBUTE ─ ───

6┴──┬ ┬─field_name ─ ─BY ──expression ─────────5

└ ┘─column_name─

5─ ─START ──expression ──END ──expression ─────────────────────5

5─ ─TIMESTAMP ──identifier ──INTERVAL ──identifier ─────────────5%

field_namecolumn_name

Names a field or column to be distributed. The field or columnmust contain a numeric value. The corresponding column in theresulting internal table contains floating-point numbers.

BY expressionSpecifies the length of the distribution period in seconds. Theperiods start at midnight and are all of the same length, exceptpossibly the last one before next midnight. The expression mustspecify an integer.

START expressionIdentifies the start time of the interval represented by the inputrow. The expression must specify a timestamp.

END expressionIdentifies the end time of the interval represented by the inputrow. The expression must specify a timestamp.


DEFINE UPDATE

TIMESTAMP identifierSpecifies the name of the timestamp column in the resultinginternal table.

INTERVAL identifierSpecifies the name of the interval column in the resulting internaltable.

LET ClauseUsing this clause, you can give names to expressions that arefrequently used in the next clauses. This saves you writing, but alsospeeds up the processing. For example, if you use data from a recordfield, the log collector reads and converts the contents of the fieldevery time you specify the name of that field. If you give a name tothe value from the field, and then use that name, the conversion willbe done only once.

The syntax of the LET clause is:

┌ ┐─,───────────────────55──LET ──(─ ───

6┴identifier = expression ─)─────────────────5%

expressionThe log collector evaluates this expression and assigns thespecified name to the result. The expression can use the namesdefined earlier in the same LET clause.

identifierSpecifies the name assigned to the result of the expression.

The name can be any identifier distinct from the names of fields(or columns) in the source, the name of the status columnspecified by APPLY SCHEDULE (if APPLY SCHEDULE wasused), the names of timestamp and interval columns specified byDISTRIBUTE (if DISTRIBUTE was used), and the namesdefined earlier in the same LET clause.

Version 2.010-48

Lan

gu

age S

tatemen

ts

DEFINE UPDATE

GROUP BY ClauseThis clause groups records or rows by specified grouping values. Theinput to this clause is the source record type, or source table, or theinternal table that is the result of the preceding APPLY SCHEDULEor DISTRIBUTE clause. For the purpose of this description, it isassumed to be a table.

The result of GROUP BY are groups of the input rows, such that allrows within each group have the same grouping values. All groupingvalues must be non-null. A row that has null as any of its groupingvalues is not included in any group.

If you omit the GROUP BY clause, all input rows are treated as onegroup.

See “Understanding the GROUP BY Clause” on page 2-6 for moreinformation about using the GROUP BY clause.

The syntax of the GROUP BY clause is:

┌ ┐─,───────────────────55──GROUP BY ──(─ ───

6┴column_name = expression ─)─────────────5%

expressionSpecifies one grouping value.

column_nameNames the column where to store the grouping value. It must bethe name of a column in the target table. The column cannot be adecimal or long string column.


DEFINE UPDATE

SET ClauseThis clause summarizes groups of records or rows resulting fromGROUP BY. For the purpose of this description, the groups areassumed to consist of rows.

The SET clause represents each group by one row in the target table.In that row, the grouping values are stored in the columns specifiedin the GROUP BY clause. The values of other columns are derivedfrom all rows in the group, as specified in the SET clause. Thecolumns not named in the GROUP BY and SET clauses are set tonull.

See “Understanding the SET Clause” on page 2-6 for moreinformation about using the SET clause.

The syntax of the SET clause is:

┌ ┐─,──────────────────────────────────55──SET ──(─ ───

6┴column_name = ─┤ accumulation ├─ ─)───────────────────────5%

accumulation:├─ ──┬ ┬──SUM (expression ) ─────────────────────────────────────────── ────────┤

├ ┤──MIN (expression ) ───────────────────────────────────────────├ ┤──MAX (expression ) ───────────────────────────────────────────├ ┤──COUNT (expression ) ─────────────────────────────────────────├ ┤──FIRST (expression ) ─────────────────────────────────────────├ ┤──LAST (expression ) ──────────────────────────────────────────├ ┤──AVG (expression , column_name ) ────────────────────────────└ ┘──PERCENTILE (expression , column_name , integer_constant)

column_nameNames a column of the target table. The accumulation specifieshow to derive the value to be stored in that column.

SUM(expression)Evaluates the expression for each row in the group. The value ofSUM is the sum of all non-null values thus obtained. If the valueof expression is null for all records (or rows) in the group, thevalue of SUM is null.

The expression must specify a numeric value. If that value is notof the same type as the columncolumn_name, it is converted tothe type of the column, and the sum is computed for theconverted values.

Version 2.010-50

Lan

gu

age S

tatemen

ts

DEFINE UPDATE

MAX( expression)Evaluates the expression for each row in the group. The value ofMAX is the greatest of all non-null values thus obtained. If thevalue of expression is null for all records (or rows) in the group,the value of MAX is null.

MIN( expression)Evaluates the expression for each row in the group. The value ofMIN is the least of all non-null values thus obtained. If the valueof expression is null for all rows in the group, the value of MINis null.

COUNT(expression)Evaluates the expression for each row in the group. The value ofCOUNT is the number of non-null values thus obtained.

The result is an integer.

FIRST(expression)Evaluates the expression for each row in the group, in the orderthey are processed. The result is the first non-null value ofexpression. If the value of expression is null for all records (orrows) in the group, the value of FIRST is null.

LAST(expression)Evaluates the expression for each row in the group, in the orderthey are processed. The result is the last non-null value ofexpression. If the value of expression is null for all records (orrows) in the group, the value of LAST is null.

AVG(expression,column_name)Evaluates the expression for each row in the group. The result isthe average or weighted average of the values thus obtained,depending on column_name.

The column_name must name a column whose value is specifiedin the same SET clause. The value of column_name must bespecified using either COUNT or SUM.

If column_name is specified by means of COUNT, its value mustbe equal to the number of non-null values of expression. Theresult of AVG is then the average of all non-null values of


DEFINE UPDATE

expression in the group. If the value of expression is null for allrecords in the group, the value of AVG is null.

If column_name is specified by means of SUM, the result ofAVG is the weighted average of all non-null values of expressionin the group. The argument of SUM obtained for the same row isused as the weight. If the value of expression is null for allrecords in the group, or the sum of all weights is 0, the value ofAVG is null.

The expression must specify a numeric value. The result of AVGmust be stored in a floating-point column.

PERCENTILE( expression,column_name,integer_constant)Evaluates the expression for each row in the group. The value ofPERCENTILE is a value p such thatinteger_constant percent ofall non-null values resulting from evaluating the expressions islower than p, and 100−integer_constant percent is higher than p.The integer_constant value must be in the range 1-99.

The column_name must name a column whose value is specifiedin the same SET clause. Its value must be specified usingCOUNT, and must be equal to the number of non-null values ofexpression.

The expression must specify a numeric value. The result ofPERCENTILE must be stored in a floating-point column.

PERCENTILE can be used only if the source of the update is arecord.

If the value of a column is specified by means of PERCENTILE,it can be specified in only one update definition.

Version 2.010-52

Lan

gu

age S

tatemen

ts

DEFINE UPDATE

MERGE ClauseThis clause merges availability intervals. The input to this clause aregroups of records or rows resulting from GROUP BY. For thepurpose of this description, the groups are assumed to consist ofrows.

The parameters of the MERGE clause specify how to derive fromeach row a piece of evidence about availability of some resource. It isdescribed by four parameters: start and end times of a time interval,the interval type that identifies the status of the resource during theinterval, and the quiet period.

The MERGE clause combines this evidence and produces a set ofrows in the target table that describes the status of the resource atdifferent times. Each of these rows represents an interval described bymeans of start and end times, interval type, and quiet period. Besidesthis information, each row contains the grouping values, in thecolumns specified by the GROUP BY clause.

See “Understanding the MERGE Clause” on page 5-17 for moreinformation about using the MERGE clause.

The syntax of the MERGE clause is:

55──MERGE ──(─ ──column_name_1 = expression_1 ─,───────────────5

5─ ──column_name_2 = expression_2 ─,──────────────────────────5

5─ ──column_name_3 = expression_3 ─,──────────────────────────5

5─ ──column_name_4 = expression_4 ─)─────────────────────────5%

expression_1Specifies the interval type. It must be one of the three-characterstrings listed in Table 43 on page 10-54.

expression_2Specifies the start time of the interval. It must be a timestamp.

expression_3Specifies the end time of the interval. It must be a timestampgreater than or equal to the timestamp specified by expression2.


DEFINE UPDATE

expression_4Specifies the quiet period in seconds. It must be a non-negativeinteger.

column_name_1Names the column of the target table where to store the intervaltype. It must be a character column of length 3.

column_name_2Names the column of the target table where to store the starttime. It must be a timestamp column.

column_name_3Names the column of the target table where to store the starttime. It must be a timestamp column.

column_name_4Names the column of the target table where to store the quietperiod. It must be an integer column.

Table 43. Interval Type Codes for Resource Availability

Intervaltype code

Status atstart

Statuswithin

interval

Status atend

=== Up Up Up

|== Started Up Up

==| Up Up Stopped

|=| Started Up Stopped

XXX Down Down Down

|XX Stopped Down Down

XX| Down Down Started

|X| Stopped Down Started

Version 2.010-54

Lan

gu

age S

tatemen

ts

DEFINE UPDATE

How Data Is Stored in Database TablesThese rules apply when the log collector stores data in databasetables:

■ Numbers can be stored in numeric columns. Character stringscan be stored in character columns. Date/time strings can bestored in date/time columns of the corresponding type. Date/timevalues can be stored in date/time columns of the same type, intimestamp columns, and in character columns.

■ When a floating-point number is stored in an integer column,only the integer part of the number is stored. The fractional partis discarded.

■ When a date/time string is stored in a date/time column, it isconverted to the date/time value represented by the string.

■ When a date/time value is stored in a character string column, itis converted to a date/time string representing that value, andpadded with blanks at the end if needed. Truncation is notallowed. The column must be wide enough to hold the wholestring.

■ When a date value or a date string is stored in a timestampcolumn, the date is extended with a time part of00.00.00.000000.

■ When a time value or a time string is stored in a timestampcolumn, the date is extended with a date part of 0001-01-01.

These rules are formulated as if data types in the data base were thesame as those used by the log collector. This is normally not true, butthe log collector interprets different types of database columns as ifthey had one of the data types defined under “Data Types” onpage 8-2. The details are given in “Storing and Retrieving DatabaseData” on page C-1.


DROP

DROPUse the DROP statement to delete a stored definition. You can drop:

■ A log definition■ A record definition■ A record procedure definition■ An update definition■ A purge condition for a table

Syntax

55──DROP ─ ──┬ ┬ ─LOG ──log_name ──────────── ─────────────────5% ├ ┤─RECORD──record_name──────── ├ ┤ ─RECORDPROC ──procedure_name ─ ├ ┤─UPDATE──update_name──────── └ ┘─PURGE FROM ──table_name ────

DescriptionLOG log_name

Specifies to drop the log definition log_name.

RECORD record_nameSpecifies to drop the record definition record_name.

RECORDPROC procedure_nameSpecifies to drop the record procedure definitionprocedure_name.

UPDATE update_nameSpecifies to drop the update definition update_name.

PURGE FROM table_nameSpecifies to drop the purge condition for the table table_name.

Version 2.010-56

Lan

gu

age S

tatemen

ts

DROP

ExampleAssume that you want to delete the log definition namedSOME_LOG, the record type SOME_REC, and the purge conditionfor the data table SOME.DATA_TABLE. Use these DROPstatements to remove the log, record, and purge condition definitions:

DROP LOG SOME_LOG;

DROP RECORD SOME_REC;

DROP PURGE FROM SOME.DATA_TABLE;

For more information about using the DROP statement, see “Usingthe DROP Statement” on page 3-11 and “Using the DROPStatement” on page 5-38.


LIST RECORD

LIST RECORDUse the LIST RECORD statement to produce reports directly from alog data set without going through the collect process. This statementis useful when you want to produce very detailed reports that coveronly a short time period.

The log collector presents the output in the form of a readable file.

You can use LIST RECORD statement to list several record typesfrom the same log. Each record type is then listed in a separateoutput file.

In many ways, LIST RECORD works the same way as updatedefinitions during collect. LIST RECORD has the samesummarization and grouping concepts, and handles repeated sectionsin the same way as collect.

If LIST RECORD needs to summarize or group the data, the logcollector performs data buffering (similar to collect). Otherwise thelog collector writes the result immediately to the output file(s). If thebuffer fills up, the log collector writes the data accumulated so far,and terminates LIST RECORD with a warning message.

LIST RECORD labels the columns in the listing with the field nameif the expression is a single field, or with the first part of theexpression if the expression consists of more than one field.

Version 2.010-58

Lan

gu

age S

tatemen

ts

LIST RECORD

Syntax

┌ ┐────────────────────────── ┌ ┐─,─────────55──LIST─ ───

6┴─┤ list_specification ├─ ─LOGFILE─ ───

6┴─file_name─ ────────5

5─ ──┬ ┬─────────────────────────────── ────────────────────────────────5 └ ┘ ─BUFFER SIZE──integer_constant─

5─ ──┬ ┬─────────────────────────── ───────────────────────────────────5% │ │┌ ┐─BREAK──── └ ┘ ─ON OVERFLOW─ ──┴ ┴─CONTINUE─

list_specification:├─ ─RECORD──record_name─ ──┬ ┬─────────────────────── ───────────────────5 └ ┘ ─SECTION──section_name─

┌ ┐─,────────────────────────5──FIELDS─ ───

6┴─┤ column_specification ├─ ──┬ ┬────────────────── ───────5

└ ┘ ─WHERE──condition─

5─ ──┬ ┬────────────────────────── ─────────────────────────────────────5 │ │┌ ┐─,────────── └ ┘ ─GROUP BY─ ───

6┴─expression─

5─ ──┬ ┬────────────────────────────────────────────── ─────────────────5 │ │┌ ┐─,────────────────────────────── │ ││ │┌ ┐─ASC── └ ┘ ─ORDER BY─ ───

6┴──┬ ┬─integer_constant─ ──┼ ┼──────

└ ┘─field_name─────── └ ┘─DESC─

5──LISTFILE──file_name───────────────────────────────────────────────┤

column_specification:├─ ──┬ ┬─expression─────── ─────────────────────────────────────────────┤

└ ┘─┤ accumulation ├─

accumulation:├─ ──┬ ┬──SUM (expression) ───────────────────────── ────────────────────┤

├ ┤──MIN (expression) ─────────────────────────├ ┤──MAX (expression) ─────────────────────────├ ┤──COUNT (expression) ───────────────────────├ ┤──FIRST (expression) ───────────────────────├ ┤──LAST (expression) ────────────────────────├ ┤──AVG (expression) ─────────────────────────└ ┘──PERCENTILE (expression, integer_constant)


LIST RECORD

Descriptionlist_specification

Specifies how to list one record type. You can think of thedifferent clauses oflist_specification as being interpreted in theorder in which they are described below.

RECORD record_nameNames the record type to be listed. If several records are to belisted (more than one list specification is coded), allrecord_names coded in the RECORD clauses must belong tothe same log. This optional clause is available:

SECTION section_nameSpecifies listing of a repeated section section_name ofrecord record_name. As in the case of update processing,(explained in “Using Repeated Sections Within Records”on page 5-23), the log collector generates an internalrecord for each occurrence of the repeated section. LISTRECORD lists data from that internal record.

If the record record_name has repeated sections and youomit the SECTION clause, you can only list data that isoutside the repeated sections.

Any identifiers used in the expressions and condition withinthis list specification must be names of fields in the recordbeing listed.

FIELDS column_specification, ...Defines one row of the output list. Each column_specificationdefines the value to be listed in one column. As the syntaxdiagram shows, each column_specification is either anexpression or an accumulation.

If you specify GROUP BY, all expressions listed in GROUPBY must appear as column specifications in the FIELDSclause. All the remaining column specifications (if any) mustbe accumulations.

Version 2.010-60

Lan

gu

age S

tatemen

ts

LIST RECORD

If you do not specify GROUP BY, all column specificationsmust be of the same kind, either all expressions or allaccumulations.

expressionSpecifies a value to be listed. If records are not grouped,it is obtained from the record listed in the row. If recordsare grouped, it is a value common to all records in thegroup.

accumulationSpecifies a value obtained from all records in the group.You can use it only if records are grouped. The value isobtained in a similar way as in the SET clause of theDEFINE UPDATE statement (see “SET Clause” onpage 10-50). Note that AVG and PERCENTILE have asyntax that differs from the SET clause:

AVG(expression)Calculates the value of expression for each input rowthat is grouped together to form an output row. LISTRECORD adds these values and divides by thenumber of input rows to the group.

PERCENTILE( expression,integer_constant)Calculates the value of expression for each input rowto a group, places the values in a buffer and sortsthem. Before LIST RECORD writes the groupedoutput row, it determines the output value (percentile)where integer_constant percent of the values in thegroup are smaller than the output value, and100−integer_constant percent of the values are larger.

WHERE conditionLimits the log collector to list only those records for whichthe condition is true.

GROUP BY expression, ...Specifies grouping of records. LIST RECORD produces onerow for each unique combination of values of expressions.


LIST RECORD

If you omit the GROUP BY clause, all list specifications inthe FIELDS clause must be of the same kind: either allexpressions or all accumulations. The result depends on whichis the case:

■ If all list specifications are expressions, LIST RECORDdoes not perform any grouping and produces one row foreach record.

■ If all list specifications are accumulations, LISTRECORD produces one row that summarizes all records.

ORDER BYOrders the output produced by LIST RECORD. If you omitORDER BY, the order remains the same as the records in theinput log data set.

The output is ordered by the values of the columns youidentify. You can identify columns by their numbers. If thevalue of a column is specified by means of an expression (notan accumulation), and this expression is a single field name,you can use that field name to identify the column.

If you identify more than one column, the output is orderedby the values of the first column you identify, then by thevalues of the second column, and so on.

integer_constantIdentifies a column to be used for ordering. It is thenumber of the column, counting from the left.

field_nameIdentifies a column to be used for ordering. Thefield_name must appear as one of column specifications inthe FIELDS clause.

ASCOrders the data in ascending sequence. This is thedefault.

DESCOrders the data in descending sequence.

Version 2.010-62

Lan

gu

age S

tatemen

ts

LIST RECORD

LISTFILE file_nameNames the output file to receive the list. The file_names indifferent list specifications must be different.

LOGFILE file_name, ...Names one or more log files to be listed. The files are processedin the order in which they are specified.

BUFFER SIZE integer_constantSpecifies the size (in bytes) of the internal buffer used if the LISTRECORD statement includes a GROUP BY clause or an ORDERBY clause. The default is 10 000 000 bytes. The minimumallowed value is 10 000 bytes.

ON OVERFLOWSpecifies the action to be taken when an overflow occurs duringLIST RECORD processing when buffering is in use. Theoverflow is a situation when an accumulated value exceeds therange allowed for this type of values. The possible options are:

BREAKStop the processing. The log collector does not produce anyLIST RECORD output.

CONTINUEReset the accumulated value to 0, write the lost value to thestandard error output, and continue the processing.


LIST RECORD

ExampleList the jobs that ran between 2 and 3 p.m.

LIST

RECORD SMF_ð3ð

FIELDS SMF3ðTME, -- Time

SMF3ðJBN, -- Job name

SMF3ðCLS, -- Class

INTEGER(INTERVAL(SMF3ðSIT,SMF3ðTME)), -- Elapsed time (seconds)

(SMF3ðCPT+SMF3ðCPS) / 1ðð.ð -- CPU time (seconds)

WHERE SUBSTR(SMF3ðJNM,1,3) = 'JOB'

AND HOUR(SMF3ðTME) >= 14

AND HOUR(SMF3ðTME) <= 15

LISTFILE 'list1.list'

LOGFILE 'smf.example';

The log collector might write these messages as a result of executingthe LIST RECORD statement:

PRCOL3ððI List started at 1997-ð6-23-14.3ð.12.

PRCOL3ð2I Processing smf.example.

PRCOL341I The first_record timestamp is 1997-ð6-22-ð4.ð2.27.

PRCOL38ðI 1ð2347 records read from the input log.

PRCOL342I The last_record timestamp is 1997-ð6-22-22.35.18.



PRCOL318I -------------------|----------

PRCOL319I SMF_ð3ð | 2489

PRCOL318I -------------------|----------


PRCOL381I 42 records written to the file list1.list.

PRCOL3ð1I List ended at 1997-ð6-23-14.32.15.

Figure 37. Messages from the LIST RECORD Statement

Version 2.010-64

Lan

gu

age S

tatemen

ts

LIST RECORD

The output written to the list1.list file may look like the following:

SMF3ðTME SMF3ðJBN SMF3ðCLS INTEGER(INTERVAL(SMF3 (SMF3ðCPT+SMF3ðCPS) /

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

14.ðð.51 TEST4 A 48 6.2ðððððððððððððE+ðð

14.ð2.14 XYZ123 A 518 3.9ðððððððððððððE+ð2

14.ð2.19 ABBJ C 111 2.2ðððððððððððððE+ð1

:

Figure 38. Results from the LIST RECORD Statement


LOGSTAT

LOGSTATUse the LOGSTAT statement to print the number of records ofdifferent types found in a log file, and the number of records built byrecord procedures.

Syntax

┌ ┐─,────────55──LOGSTAT──log_name ──FILE ─ ───

6┴─file_name ─ ───────────────5%

Descriptionlog_name

Is the name of a stored log definition. It identifies the type of logto be processed.

FILE file_name, ...Names one or more log files. The files are processed in the orderin which they are specified.

Version 2.010-66

Lan

gu

age S

tatemen

ts

LOGSTAT

ExampleAssume that you want to count records of different types in an IMSlog file ims.log1. Use this LOGSTAT statement to count the records:

LOGSTAT IMS FILE 'ims.log1';

The messages written by the log collector may look like this:

PRCOL3ððI Logstat started at 1997-ð6-23-14.29.32.

PRCOL3ð2I Processing ims.log1.

PRCOL341I First record timestamp is 1997-ð6-22-ð4.ð2.27.

PRCOL342I Last record timestamp is 1997-ð6-22-22.35.18.

PRCOLðð3I



PRCOL318I -------------------|----------

PRCOL319I IMS_ððð | ð

PRCOL319I IMS_ðð6 | 191

PRCOL319I IMS_ðð7 | ð

PRCOL319I IMS_ð3ð | 2489

PRCOL319I IMS_ð39 | ð

PRCOL319I IMS_ð7ð | 51

PRCOL319I IMS_ð71 | 51

PRCOL319I IMS_ð72_1 | 918

PRCOL32ðI Unrecognized | 5518

PRCOL318I -------------------|----------


PRCOLðð3I

PRCOL316I Records built by record procedures:


PRCOL318I -------------------|----------

PRCOL319I IMS_X | 36

PRCOL318I -------------------|----------


PRCOL3ð1I Logstat ended at 1997-ð6-23-14.3ð.12.

Figure 39. Messages from the LOGSTAT Statement


PURGE

PURGEUse the PURGE statement to delete data from data tables based onthe stored purge conditions (see “DEFINE PURGE” on page 10-29).Only the tables with specified purge conditions are purged.

Syntax

55──PURGE ─ ──┬ ┬───────────────────────────────────── ─────5 │ │┌ ┐─,─────────────────────── └ ┘ ─INCLUDE─ ───

6┴──┬ ┬─table_name ───────────


5─ ──┬ ┬───────────────────────────────────── ────────────5% │ │┌ ┐─,─────────────────────── └ ┘ ─EXCLUDE─ ───

6┴──┬ ┬─table_name ───────────


DescriptionINCLUDE

Specifies the tables for which the purge applies. If you specifyINCLUDE, the log collector purges only the specified tables.


LIKE string_constantSpecifies a group of tables to be included. The tables arethose with names matching the pattern specified as thestring_constant. The pattern matching rules are defined in“Pattern Matching” on page 8-17. If the pattern contains aperiod (.), the table prefix must match the part before theperiod, and the rest of the table name must match the partafter the period. For example, the pattern PERFREP.ABCD%includes all tables whose names start with ABCD and havePERFREP as a prefix.

If the pattern does not contain a period, the prefix must be thecurrent user ID, and the rest of the name must match thewhole pattern.

Version 2.010-68

Lan

gu

age S

tatemen

ts

PURGE

EXCLUDESpecifies the tables to be excluded from the purge. If you specifyEXCLUDE, the log collector purges all tables with defined purgecondition except the specified tables.

table_nameIs the name of a table to be excluded.

LIKE string_constantSpecifies a group of tables to be excluded, using the samerules as for INCLUDE.

ExampleAssume that you want to apply the purge definition to all tables thathave a prefix of PERFREP and begin with ABCD exceptPERFREP.ABCD_APPL1. Use this PURGE statement to include allABCD tables except PERFREP.ABCD_APPL1:

PURGE INCLUDE PERFREP.ABCD%

EXCLUDE PERFREP.ABCD_APPL1;

For more information about using the PURGE statement, see“Deleting Data” on page 4-12.

Usage NotesYou can specify both INCLUDE and EXCLUDE on a PURGEstatement. For example, INCLUDE LIKE 'PERFREP.ABCD%'EXCLUDE PERFREP.ABCD_APPL_H includes all ABCD tablesexcept PERFREP.ABCD_APPL_H.


RECALCULATE

RECALCULATEUse the RECALCULATE statement to update one or more datatables with information derived from another table.

The table used as the source of data in the RECALCULATEstatement is called the base table. The tables being updated withinformation derived from the base table are called the dependenttables. Each dependent table must have an update definition eitherfrom the base table or from another dependent table. This updatedefinition is used to calculate the new contents of the dependenttable.

You can choose between two alternative ways of updating the tables:

■ Recalculation.

The log collector replaces data in the dependent tables by newvalues, calculated from the current contents of the base table.The contents of the dependent tables after RECALCULATEreflect the contents of the base table (with some exceptionsresulting from the rule that RECALCULATE never deletes rowsfrom dependent tables).

You choose this alternative by specifying RECALCULATEFROM.

■ Propagation of changes.

You specify a change to the base table. The log collector makesthis change and propagates it to the dependent tables. Forexample, you increase by 2 the value in some column of thebase table. If the dependent table contains a sum computed fromthat column, that sum is also increased by 2. But, it need not beequal to the sum of values currently present in the base table(which is the normal situation if data were purged).

You choose this alternative by specifying RECALCULATEDELETE, INSERT, or UPDATE.

Version 2.010-70

Lan

gu

age S

tatemen

ts

RECALCULATE

Syntax

55──RECALCULATE─ ──┬ ┬─────────────── ──┬ ┬─┤ from_clause ├─── ─5% │ │┌ ┐─,───────── ├ ┤─┤ delete_clause ├─ └ ┘ ───

6┴─table_name ─ ├ ┤─┤ insert-clause ├─

└ ┘─┤ update-clause ├─

from_clause:├──FROM ──table_name ─ ──┬ ┬──────────────────── ─────────────┤ └ ┘ ─WHERE ──sql_condition ─

delete_clause:├──DELETE FROM──table_name ─ ──┬ ┬──────────────────── ────────┤ └ ┘ ─WHERE ──sql_condition ─

insert_clause:├──INSERT INTO──table_name ─ ──┬ ┬───────────────────── ───────5 │ │┌ ┐─,───────── └ ┘ ─(─ ───

6┴─column_name─ ─)─

┌ ┐─,───────5──VALUES──(─ ───

6┴─constant ─ ─)─────────────────────────────┤

update_clause: ┌ ┐─,───────────────────├──UPDATE──table_name ──SET ──(─ ───

6┴column_name = expression ───5

5──)─ ──┬ ┬──────────────────── ───────────────────────────┤ └ ┘ ─WHERE ──sql_condition ─

Descriptiontable_name, ...

Lists the dependent tables.

Omitted list means the same as listing all tables that have theircontents derived from the base table by means of updatedefinitions, either direct or cascaded.

FROM table_nameIdentifies the table table_name as the base table. Indicates thatyou want to recalculate the contents of the dependent tables fromthe contents of the base table.


RECALCULATE

The log collector calculates first new rows for all dependenttables that have update definitions from the base table. It usesthese update definitions to calculate the rows. If a new row hasthe same GROUP BY values as a row already present in thetable, the log collector replaces the old row by the new. The datafrom the old row is lost. If the table does not contain a row withthe same GROUP BY values, the log collector inserts the newrow into the table.

The procedure is repeated with tables that have update definitionsfrom the tables thus recalculated, and so on.

No rows are deleted in the process. As a result, an updated tablemay contain old rows that no longer reflect any data from theunderlying table. These old rows are not used to calculate newrows for the next table.

It is possible to calculate the new data using only selected rowsfrom the base table. You select the rows using this clause:

WHERE sql_conditionSpecifies which rows to select. The selected rows are thosefor which the sql_condition is true. If you omit WHERE, allrows are selected. The sql_condition must be a valid SQLsearch condition for the tabletable_name, and its individualtokens must be recognized by the log collector. Notice thatthe syntax of sql_condition may be different for differentdatabase managers.

DELETE FROM table_nameIdentifies the table table_name as the base table. Indicates thatyou want to delete rows from the base table and propagate thechange to the dependent tables.

The change to the dependent tables consists of changing data inthe existing rows. No rows are deleted from the dependent tables.

You specify the rows to be deleted using this clause:

WHERE sql_conditionSpecifies the rows to be deleted from the base table. The logcollector deletes the rows for which the sql_condition is true.

Version 2.010-72

Lan

gu

age S

tatemen

ts

RECALCULATE

If you do not specify a WHERE clause, all rows in the tableare deleted. The sql_condition must be a valid SQL searchcondition for the tabletable_name, and its individual tokensmust be recognized by the log collector. Notice that thesyntax of sql_condition may be different for different databasemanagers.

INSERT INTO table_nameIdentifies the table table_name as the base table. Indicates thatyou want to insert a row into the base table and propagate thechange to the dependent tables.

If the base table already contains a row with the same GROUPBY values as the row being inserted, the log collector does notinsert a new row. It updates instead the existing row with thespecified values. The log collector uses for this purpose theaccumulation functions specified in update definitions for thetable.

The change to the dependent tables can consist of inserting newrows or changing data in the existing rows. No rows are deletedfrom the dependent tables. Insertion of rows with duplicateGROUP BY values follows the same rule as for the base table.

You specify the row to be inserted using these clauses:

(column_name, ... )Lists the columns for which you specify values. Notice thatyou must specify values for all GROUP BY columns.

Omitted list of columns means that you specify values for allcolumns.

VALUES(constant, ... )Specifies the values in the row. If the list of columns ispresent, the constants specify values for the columns in theorder they appear in the list. The number of constants must bethe same as the number of column names.

If the list of columns is omitted, the constants specify valuesfor the columns in the order they appear in the table. The


RECALCULATE

number of constants must be the same as the number ofcolumns in the table.

UPDATE table_nameIdentifies the table table_name as the base table. Indicates thatyou want to change one or more rows in the base table andpropagate the change to the dependent tables.

If one or more GROUP BY values in a row is changed, theresulting row can have the same GROUP BY values as a rowalready present in the table. The log collector merges then the tworows: it uses data from the changed row to update the existingrow and deletes the changed row. In this process, the log collectoruses the accumulation functions specified in update definitions forthe table.

The change to the dependent tables can consist of inserting newrows or changing data in the existing rows. No rows are deletedfrom the dependent tables. Insertion of rows with duplicateGROUP BY values follows the same rule as for INSERT INTO.

You specify the change to the base table using these clauses:

SET (column_name = expression, ... )Specifies new values for the named columns.

WHERE sql_conditionSpecifies the rows to be updated. The log collector updatesonly the rows for which the sql_condition is true. If you donot specify a WHERE clause, all rows in the table areupdated. The sql_condition must be a valid SQL searchcondition for the tabletable_name, and its individual tokensmust be recognized by the log collector. Notice that thesyntax of sql_condition may be different for different databasemanagers.

Version 2.010-74

Lan

gu

age S

tatemen

ts

RECALCULATE

ExampleAssume that you want to change an account number. The accountnumber is stored in the column ACCOUNT_NO of the tableACCOUNT.INFO_TABLE.

Use this RECALCULATE statement to change the account number inthe table:

RECALCULATE

UPDATE ACCOUNT.INFO_TABLE

SET (ACCOUNT_NO = '88ð5ð3')

WHERE ACCOUNT_NO = '88ð5ð2';

Because you omitted the list of dependent tables, your change ispropagated to all tables that contain information based onACCOUNT.INFO_TABLE.

For more information about using the RECALCULATE statement,see “Changing Data Within Tables” on page 4-13.

Usage NotesBe careful when you specify WHERE for a RECALCULATEFROM. Suppose you have three tables:

■ TABLE_H, containing hourly data■ TABLE_D, containing data from TABLE_H summarized by day■ TABLE_M, containing data from TABLE_D summarized by

month.

Suppose you execute this statement:

RECALCULATE TABLE_D,TABLE_M FROM TABLE_H WHERE DATE='1997-ð5-21';

The data for the specified day in TABLE_D is recalculated correctly.But, the rows for other days in TABLE_D are treated as old rows,that are left in the table because of the rule that RECALCULATEdoes not delete rows. They are not used to calculate the data forTABLE_M. As a result, the data for May 1997 in TABLE_M isderived from data for only one day: May 21.

To avoid this problem, use a separate statement for each table:

RECALCULATE TABLE_D FROM TABLE_H WHERE DATE='1997-ð5-21';

RECALCULATE TABLE_M FROM TABLE_D WHERE MONTH=5;


SET

SETUse the SET statement to define a named character string. Such anamed string is called a variable. The string itself is called the valueof the variable.

You can also use the SET statement to change the value of anexisting variable, that is, to replace a named string by another withthe same name.

The variable remains defined until the end of the log collector run.

Syntax

55──SET ─ ──variable_name = string_constant ──────────────────5%

Descriptionvariable_name

The name of the variable.

string_constantThe value of the variable.

ExampleAssume you want to create a variable named PREFIX with a value ofSTROMBK. Use this SET statement to create the variable:

SET PREFIX = 'STROMBK';

If the variable PREFIX already exists, the statement changes its valueto STROMBK.

Usage NotesYou can use variables to modify your statements with the help ofvariable markers (see “Using Variables to Modify Your Text” onpage 7-11) and variable references (see “Obtaining the Value of aVariable” on page 8-8). You can also use variables to control certaindiagnostic functions. (See “Invoking the Log Collector” onpage B-1).

Version 2.010-76

Lan

gu

age S

tatemen

ts

SET

An alternative way to define a variable is by specifying it on thecommand used to invoke the log collector. This is described in“Invoking the Log Collector” on page B-1. As it is indicated there,some variables can only be defined in that way.

Notice that one variable, TABPREFIX, is always defined. If it is notspecified on the invocation of the log collector, it is defined bydefault with the value PERFREP. This variable specifies the prefix ofsystem tables, that is, the tables used by the log collector to store thedefinitions. You should not change the value of TABPREFIX.


SQL

SQLUse the SQL statement to include SQL statements in the log collectorinput stream.

When the log collector encounters the statement SQL, it passes therest of the statement to the database management system forexecution.

Syntax

55──SQL ──sql_statement ───────────────────────────────────5%

Descriptionsql_statement

Any statement written in SQL that the database managementsystem allows in an EXECUTE IMMEDIATE. The log collectormust recognize all its individual tokens.

Notice that the syntax of sql_statement may be different fordifferent database managers..

ExampleDelete a table using a statement written in SQL while running the logcollector.

SQL DROP TABLE PERFREP.VM_ACCOUNTING_D;

For more information about using the log collector SQL statement,see “Creating Table and Storing Definitions” on page 2-8.

Version 2.010-78

Lo

g an

d R

ecord

Pro

cedu

res

AUsing Log and RecordProcedures

Although the log collector provides extensive processing capabilities,you might decide to create your own procedures to process databefore it is processed using the stored definitions.

In particular, you must use own procedures to:

■ Process data in unusual formats.■ Cross-reference data between parallel repeated sections and

between records.

You write these procedures in C. The procedures are of two kinds:

■ Log procedures are invoked for all records read from the logfile.

■ Record procedures are invoked only for the type of records youspecify.

Figure 40 on page A-2 shows an example of the processing thatoccurs when you use log and record procedures.

TME 10 Reporter: Log Collector Guide and Reference A-1

┌─────────┐ ┌┬────────┐

┌──5│ RPROC1 │───5││ RTYPE4 │───5

┌┬────────┐ │ └─────────┘ └┴────────┘

┌──5││ RTYPE1 │──┤

│ └┴────────┘ │

│ └────────────────────────────────5 U

│ P

┌─────────┐ │ ┌┬────────┐ D

Log record───5│ LOGPGM │──┼──5││ RTYPE2 │───────────────────────────────────5 A

└─────────┘ │ └┴────────┘ T

│ ┌─────────┐ ┌┬────────┐ E

│ ┌──5│ RPROC2 │───5││ RTYPE5 │───5 S

│ ┌┬────────┐ │ └─────────┘ └┴────────┘

└──5││ RTYPE3 │──┤

└┴────────┘ │

└────────────────────────────────5

Figure 40. Processing for Log and Record Procedures

As shown in Figure 40, the log procedure LOGPGM processes eachrecord from the log file and produces three internal records of typesRTYPE1, RTYPE2, and RTYPE3, respectively. Each of these recordtypes must be defined to the log collector by means of a DEFINERECORD statement, and can be specified as the source of a DEFINEUPDATE statement. In the example, each of the three record types isso specified, and the data from each of them is used to update thedata tables. (Note that the procedure is not limited to producing onlyone internal record of each type; there can be any number withineach type.)

An internal record produced by one procedure may be used as inputto another record procedure. In the example of Figure 40, the internalrecords of type RTYPE1, besides being used in an update, areprocessed by a record procedure RPROC1. This procedure producesinternal records of type RTYPE4. Again, this record type must bedefined by means of a DEFINE RECORD statement, and the datafrom the record are used to update the data tables via an updatedefinition.

In a similar way, internal records of type RTYPE3 are processed by arecord procedure RPROC2 that produces internal records of typeRTYPE5.

This scheme may be made as complex as needed; however, theoutput of a record procedure must not be used, directly or indirectly,as input to the same procedure.

Version 2.0A-2

Lo

g an

d R

ecord

Pro

cedu

res

Calling Log and Record Procedures

Specifying Log and Record ProceduresYou must define your log and record procedures to the log collectorusing the log collector language. To define a log procedure, use theLOGPROC clause of the DEFINE LOG statement. This is anexample of a log procedure definition:

DEFINE LOG TST_LOG

LOGPROC LOGPGM;

The log procedure LOGPGM is called for every record that occurs inlog type TST_LOG.

To define a record procedure, use the DEFINE RECORDPROCstatement. This is an example of a record procedure definition:

DEFINE RECORDPROC RPROC1

FOR RTYPE1;

The record procedure RPROC1 is called for every record of typeRTYPE1. You must define the record type RTYPE1 before youexecute this DEFINE RECORDPROC statement.

If you want to specify procedure names that contain lowercase lettersor characters other than letters and digits, you must enclose them inquotation marks, for exampleLOGPROC "logpgm". (See section“Identifiers” on page 7-9 for explanation.) Notice that the namesmust not exceed 8 bytes.

When you run the log collector, you must ensure that the specifiedprocedures are present in one of the directories listed in the defaultlibrary path (the environment variable LIBPATH).

Calling Log and Record ProceduresBefore the log collector begins processing a log file, it passes controlto each of the defined log and record procedures. The procedure doesnot read data at this time and no output records are generated.Instead, the procedure performs any required initialization, such asbuffer and work area allocation. The procedure can return the addressof the work area in a parameter. Then, each time the procedure iscalled, the log collector passes this address to it.


Calling Log and Record Procedures

When the log collector processes the log, it calls the log procedurefor each record from the log, and the record procedure for eachrecord of the type specified in the DEFINE RECORDPROCstatement. The procedure processes the record and passes a returncode back to the log collector.

The return code indicates how many records were produced by theprocedure. If the procedure did not produce output records, the logcollector continues processing the next input record. If the procedureproduced one output record, it returns a pointer to it. The logcollector processes the output record, and continues with the nextinput record. If the procedure produced more than one output record,it returns a pointer to the first of them. The log collector processesthe output record, and calls the procedure again with the same input.The procedure returns then a pointer to the next output record. This isrepeated until the procedure indicates that there are no more outputrecords.

The log or record procedures can determine that the input record isnot valid. In which case, the log collector writes information to thestandard error output. The procedure can also immediately terminateprocessing.

The log collector calls each log procedure and record procedure eachtime after committing the database updates.

After processing all records, the log collector calls the procedureagain to perform any required termination tasks (such as freeing workareas). This step occurs even if the procedure specified thatprocessing terminate immediately. During this last call to theprocedure, no input records are provided. But the procedure cangenerate one or more output records.

If you specified a PARM expression in your DEFINE LOG orDEFINE RECORDPROC statement, the procedure receives the valueof that expression as a parameter every time it is called. For example,the log procedure LOGPGM defined by this statement receives thestring that is the current value of the variable UPDT_EXP:

DEFINE LOG TST_LOG

LOGPROC LOGPGM

PARM :UPDT_EXP;

Version 2.0A-4

Lo

g an

d R

ecord

Pro

cedu

res

Interface to Log and Record Procedures

Notice that the PARM expression is evaluated only once, before thefirst call to the procedure. The resulting value is then passed to theprocedure on all calls.

Interface to Log and Record ProceduresYou can use one of two alternative interfaces to call your log orrecord procedures. You choose the interface by specifyingLANGUAGE C or LANGUAGE CL on your DEFINE LOG orDEFINE LOGPROC statement. You are recommended to specifyLANGUAGE CL for new procedures. The interface specified asLANGUAGE C is provided mainly to support procedures written forRelease 1.

The CL InterfaceA log or record procedure using the interface specified asLANGUAGE CL must conform to this declaration:

void name(int call_type,

int \return_code,

in_record \p_in_record,

out_record \\p_out_record,

int \out_length,

work_area \\p_work_area,

char \p_parm)

name

The name of the procedure, as specified by the DEFINE LOG orDEFINE RECORDPROC statement.

call_type

Indicates the type of call. It can have one of these values:

0 First call1 Normal call2 Last call3 Commit call.



\return_code

Receives the return code from the procedure. The return code canhave one of these values:

0 No record has been built.1 A record has been built, and there is no more output for this

input.2 A record has been built, and there are more output records for

this input.3 No record has been built because the input record is not

correct.4 No record has been built and processing should end

immediately.

The values of return code expected from different call types areshown in Table 44 on page A-8 .

p_in_record

A pointer to the input record. It is supplied only on those calltypes that receive an input record. Otherwise it is null.

in_record

A structure representing the layout of the input record. Theprocedure must not modify the input record or the pointer to it.

\p_out_record

Receives a pointer to the output record built by the procedure.The log collector uses this pointer only if return code indicatesthat a record has been built.

The value of \p_out_record on entry to the procedure is undefined.It is normally not the same as set by the preceding call to theprocedure.

out_record

A structure representing the layout of the output record. Thislayout must be independently defined to the log collector bymeans of a DEFINE RECORD statement.

\out_length

Receives length of the output record built by the procedure. Thelog collector uses this length only if return code indicates that arecord has been built.

Version 2.0A-6

Lo

g an

d R

ecord

Pro

cedu

res


The value of \out_length on entry to the procedure is undefined. Itis normally not the same as set by the preceding call to theprocedure.

\p_work_area

Provides a way for preserving information between theconsecutive calls to the procedure. The value returned in thisparameter by the first call is supplied in this parameter on allsubsequent calls to the procedure. You will normally use it as apointer to a work area that contains all data that you want topreserve between the calls.

work_area

A structure containing the data that you want to preserve betweenthe calls to the procedure.

p_parm

A pointer to the result of the expression specified on the PARMoption. The format of the result depends on the expression, andmay be an integer, a floating-point number, or a zero-terminatedcharacter string. Depending on what is expected, this parametershould be declared asint \p_parm, double \p_parm, or char \p_parm.(The designer of the procedure must know what type to expectand how to interpret the value.)

If the result of PARM expression is null, the value passed to theprocedure is a zero or an empty string, depending on the type ofthe expression. If PARM was not specified for the procedure,p_parm is null.

The use of parameters in different types of calls is summarized asfollows.



Table 44. Input and Output of Log and Record Procedures Using CL Interface

Input Outputcall_type p_in_record \p_work_area p_parm \return_code \p_out_record \out_length \p_work_area

0(first)

null null →parm ornull

0 not used not used →work_area


1(normal)

→in_record →work_area →parm ornull


1 →out_record out length →work_area




2(last)

null →work_area →parm ornull




3(commit)

null →work_area →parm ornull



The C InterfaceThe interface specified as LANGUAGE C differs from that specifiedas LANGUAGE CL by the method of returning the length of theoutput record. Instead of being returned in the parameter \out_length,that length is returned in the first two bytes of the output record. Theprocedure is declared like this:

void name(int call_type,

int \return_code,




char \p_parm)

Notice absence of \out_length.

Version 2.0A-8

Lo

g an

d R

ecord

Pro

cedu

res

Example

Example of Log ProcedureSuppose you want to process a log XMP where each record containsa date in the format exemplified by 14MAR97. This date format is notsupported by the log collector. You might define the three parts ofthe date as three fields in CHAR format, use the facilities of the logcollector language to build from them a date string 97-ð3-14, and thenconvert that string to date using the DATE function. You would haveto do this in every update definition that uses the date. If you havemany such update definitions, it may be simpler to convert the dateusing a log procedure.

An example of a log procedure that you might write to perform thisconversion is shown below.

In order to illustrate the use of the parameter specified via PARMclause, the example assumes that the month part of the date in theinput record may sometimes be missing or invalid. In such a case,you want to replace it by a default supplied by means of PARM.Your log definition might look like this:

DEFINE LOG XMP

LOGPROC "XmpProc"

LANGUAGE CL

PARM :DEF_MONTH;

The default month is supplied via the variable DEF_MONTH thatmust be set every time you work with the log XMP. The value of thevariable should be a two-digit string from ð1 through 12. Notice thatthe log procedure is called using the CL interface.

The input record from the log file is represented in the procedure bythe structure in_record. The first seven bytes contain date as describedabove, and the next six bytes contain a transaction count representedas an external integer.

The structure out_record represents a record built by the procedure.The record starts with the converted date in the formatDATE(YYMMDD), followed by a copy of transaction count from theinput record. You define this record to the log collector like this:


Example

DEFINE RECORD XMP_REC

IN LOG XMP

FIELDS


TRANS_COUNT OFFSET 6 LENGTH 6 EXTERNAL INTEGER);

You cannot build the output record in a variable that is local to yourprocedure, because it must be accessible to the log collector after areturn from the procedure. So, the first call to the procedure mustallocate a buffer for the output record that will remain allocated untilit is freed by the last call.

The output buffer is placed in a data area that is allocated by the firstcall and freed by the last call. The layout of this area is representedby the structurework_area. In this example, the work area containsonly the output buffer. In general, you include there all informationthat you need to store between the calls to the procedure.

Other details of the procedure are explained by comments. You cancompile the procedure using this command:

cc XmpProc.c -oXmpProc -eXmpProc -L/lib

Version 2.0A-10

Lo

g an

d R

ecord

Pro

cedu

res

Example

/\==================================================================\/

/\ Example of log procedure \/

/\==================================================================\/

#include <stdio.h>

#include <stdlib.h>

typedef struct /\ Input record \/

{ char day[2]; /\ Day, DD \/

char month[3]; /\ Month, MMM \/

char year[2]; /\ Year, YY \/

char trans_count[6]; /\ Transaction count \/

} in_record;

typedef struct /\ Output record \/

{ char year[2]; /\ Year, YY \/

char month[2]; /\ Month, MM \/

char day[2]; /\ Day, DD \/

char trans_count[6]; /\ Transaction count \/

} out_record;

typedef struct /\ Work area \/

{ out_record out_buffer; /\ Buffer for output record \/

} work_area;

/\==================================================================\/

/\ Start of log procedure \/

/\==================================================================\/

void XmpProc

(int call_type,

int \return_code,



int \out_length,


char \parm)

{


Example

/\----------------------------------------------------------------\/

/\ Local variables \/

/\----------------------------------------------------------------\/

in_record \pi; /\ Local ptr to input record \/

work_area \pw; /\ Local ptr to work area \/

int m; /\ Index in month table \/

char \months[12] = /\ Month codes \/

{

"JAN","FEB","MAR","APR","MAY","JUN",

"JUL","AUG","SEP","OCT","NOV","DEC"

};

char \dec_m[12] = /\ Month number in decimal \/

{

"ð1","ð2","ð3","ð4","ð5","ð6",

"ð7","ð8","ð9","1ð","11","12"

};

switch (call_type)

{

/\----------------------------------------------------------------\/

/\ First call \/

/\----------------------------------------------------------------\/

case (ð):

/\ Allocate work area \/

pw = (work_area \)malloc(sizeof(work_area));

/\ Save work area ptr and return indicating success \/

\p_work_area = pw;

\return_code = ð;

break;

Version 2.0A-12

Lo

g an

d R

ecord

Pro

cedu

res

Example

/\----------------------------------------------------------------\/

/\ Normal call \/

/\----------------------------------------------------------------\/

case (1):

/\ Set local pointer to input record \/

/\ Retrieve pointer to work area \/

pi = p_in_record;

pw = \p_work_area;

/\ Copy year, day, and transaction count to output record \/

/\ Set month to default. \/

strncpy(pw->out_buffer.year,pi->year,2);

strncpy(pw->out_buffer.month,parm,2);

strncpy(pw->out_buffer.day,pi->day,2);

strncpy(pw->out_buffer.trans_count,pi->trans_count,6);

/\ Find the three-letter month code in the table. \/

/\ If found, set corresponding month number in output record. \/

for (m=ð; m<12; m++)

{

if (strncmp(months[m],pi->month,3)==ð)

{

strncpy(pw->out_buffer.month,dec_m[m],2);

break;

}

}

/\ Return pointer to output record and its length. \/

/\ Indicate one record built. \/

\p_out_record = &(pw->out_buffer);

\out_length = sizeof(out_record);

\return_code = 1;

break;

/\----------------------------------------------------------------\/

/\ Last call \/

/\----------------------------------------------------------------\/

case (2):

/\ Free work area \/

free(\p_work_area);

/\ Return indicating no record built \/

\return_code = ð;

break;


Example

/\----------------------------------------------------------------\/

/\ Commit call \/

/\----------------------------------------------------------------\/

case (3):

/\ No action: return indicating success. \/

\return_code = ð;

break;

/\----------------------------------------------------------------\/

/\ Invalid call type \/

/\----------------------------------------------------------------\/

default:

break;

}

}

Version 2.0A-14

Invo

king

Lo

g C

ollecto

r

BInvoking the Log Collector

Invoke the log collector using this command:

55──prlogcol ─ ──┬ ┬─────────────────────────────── ─────────5 │ │┌ ┐───────────────────────────── └ ┘───

6┴──variable_name =string_constant

5─ ──┬ ┬──────────── ──┬ ┬──────────── ──┬ ┬──────────── ─────5% └ ┘──ð< file_name └ ┘──1> file_name └ ┘──2> file_name

variable_name=string_constantDefines a variable variable_name with value specified bystring_constant.As explained under “Using Variables to Modify Your Text” onpage 7-11 and “Obtaining the Value of a Variable” on page 8-8,variables are used to modify the log collector statements beforeexecution. In addition to that, some variables have a specialmeaning to the log collector. These control variables arediscussed under “Control Variables” on page B-3.

As an alternative way of defining variables, you may use the logcollector statement SET, described under “SET” on page 10-76.But, some control variables must be specified on theprlogcol

command to have effect.

0<file_nameSpecifies the file file_name as the standard input. The standardinput contains the log collector statements to be executed.

TME 10 Reporter: Log Collector Guide and Reference B-1

Syntax

If no standard input file is specified, the log collector statementsare read from the terminal.

Alternatively, the log collector statements may be piped to the logcollector.

1>file_nameDirects standard output to the file file_name. The log collectoruses the standard output for messages that report how the inputstatements were executed. In order to relate these messages to thestatements, the log collector copies each executed statement to thestandard output.

If no standard output file is specified, the log collector uses theterminal for standard output.

2>file_nameDirects error output to the file file_name. The log collector usesthe error output for diagnostic information. This information isintended to help in diagnosing the errors reported on standardoutput.

If no error output file is specified, the log collector uses theterminal for error output.

Notice that the above command is processed by an AIX shell, not bythe log collector. Therefore, it has to obey the syntax rules for suchcommands, which are not the same as for the log collectorstatements. In particular:

■ The equations defining the variables, and the specifications offiles must not contain blanks, other than those within stringconstants and file names.

■ A string_constant and a file_name need not be enclosed inapostrophes if they do not contain blanks.

■ A variable_name must be a word as defined under “Words” onpage 7-2 and must not be longer than 18 bytes. The logcollector translates it to uppercase.

Version 2.0B-2

Invo

king

Lo

g C

ollecto

r

Control Variables

Control VariablesThe log collector variables are named strings that can be used tomodify the log collector statements before execution. (See “UsingVariables to Modify Your Text” on page 7-11 and “Obtaining theValue of a Variable” on page 8-8.) Some variables, called controlvariables, are also used to control certain functions of the logcollector. (They can be used to modify the statements as well.)

Some of the control variables can only be defined on the invocationof the log collector (the prlogcol command). The remaining can bedefined either on the invocation or using the SET statement.

Variables That Can Only Be Defined on InvocationThese variables provide information that is used in the initializationof the log collector, and therefore must be supplied with the prlogcol

command. Providing this information by a SET statement is too late.If defined by a SET statement, these variables can still be used tomodify the statements, but have no control function.

DBNODE

Specifies the database node name. It is used only by ORACLEdatabases that use SQL*NET.

If you do not define this variable, or define its value to be theempty string, ORACLE obtains the node name from the node partof the environment variable TWO_TASK.

DBSERVER

Specifies the database server name. It is used only by DB2/6000and SYBASE databases.

If you do not define this variable, or define its value to be theempty string:

■ DB2/6000 obtains the server name from the environmentvariable DB2INSTANCE.

■ SYBASE obtains the server name from the environmentvariable DSQUERY.


Control Variables

DBNAME

Specifies the database name. It is used by DB2/6000, ORACLE,and SYBASE databases.

If you do not define this variable, or define its value to be theempty string:

■ DB2/6000 obtains the database name from the environmentvariable DB2DBDFT;

■ ORACLE obtains the database name from the environmentvariable ORACLE_SID, or, if SQL*Net is used, from thesid part of the environment variable TWO_TASK.

■ SYBASE uses the default database associated with the user.

DBUSER

Specifies the database user. It should only be specified forORACLE-authenticated users and for SYBASE users.

■ For ORACLE-authenticated users, it must be the user nameknown to ORACLE (it can be different than the user’s AIXuser ID).

■ For SYBASE, the value must be the login name (the sameas the user’s AIX user ID).

DBPASSWD

Specifies the database user’s password. It should only be specifiedfor ORACLE-authenticated users and for SYBASE users.

TABPREFIX

Specifies the prefix of system tables. System tables are thedatabase tables where the log collector stores the definitions oflogs, records, updates, record procedures, and purge conditions. Ifyou do not define this variable, it is defined by default with thevalue PERFREP.

SHOWINPUT

By defining this variable with value NO, you suppress copying oflog collector statements to standard output. But, keep in mind thatyou may then have problems in interpreting the messages issuedby the log collector.

Version 2.0B-4

Invo

king

Lo

g C

ollecto

r

Control Variables

The variables DBNODE, DBSERVER, DBNAME, DBUSER, andDBPASSWD can also be defined using flags -n, -S, -D, -U, and -P,respectively (not shown in the syntax diagram).

To hide the password, the variables DBUSER and DBPASSWD canbe defined by means of a protected file. See the TME 10 ReporterInstallation and Administrationmanual for details.

Variables That Can Also Be Defined Using SETThese variables activate and deactivate various diagnostic traces(written to the error output). Defining and redefining them by meansof the SET statement gives you an opportunity to trace the executionof only selected log collector statements.

ZZCOMPSNAP

You use this variable to trace values obtained by evaluatingexpressions that appear in the log collector statements. Theseexpressions are evaluated by internally compiled programs. Eachsuch program has its name. For example, the program thatevaluates all right-hand sides in an update definition has the samename as the update definition.

If the variable is defined, you obtain the trace from all programswith names that are LIKE the value of the variable. For example,by defining ZZCOMPSNAP='%', you obtain the trace of all expressions.By defining ZZCOMPSNAP='ERROR_STAT', you trace the right-hand sidesof the update definitionERROR_STAT. By defining ZZCOMPSNAP='', youturn the trace off.

ZZCOMPPROG

You use this variable to see the internally compiled programs. Ifthe variable is defined, the programs with names that are LIKEthe value of the variable are written to the error output.

ZZCOMPCOMM

You use this variable to improve the readability of programsdisplayed using ZZCOMPPROG. If the variable is defined, theprograms with names that are LIKE the value of the variable arecompiled with comments identifying different parts of theprogram.


Control Variables

ZZCOMPSHOW

You use this variable to see the process of compiling all theinternal programs that have the name LIKE the value of thevariable.

ZZLOOKSNAP

You use this variable to trace the lookup operations. If thevariable is defined, you obtain the trace of all lookup operationsagainst tables whose fully qualified name is LIKE the value ofthe variable. For example, by defining ZZLOOKSNAP='%', you obtainthe trace of all lookup operations. By definingZZLOOKSNAP='\.CAL\', you trace lookup operations against all tableswith any prefix and the name starting with CAL. By definingZZLOOKSNAP='', you turn the trace off.

ZZLOOKSHOW

You use this variable to see how lookup operations are prepared.If the variable is defined, you display the preparations for lookupagainst all tables whose fully qualified name is LIKE the value ofthe variable.

ZZLOOKDATA

You use this variable to see the data involved in preparations forlookup. If the variable is defined, you display the data involved inlookup against all tables whose fully qualified name is LIKE thevalue of the variable.

ZZSQLSHOW

You use this variable to trace operations against the data base. Itsvalue, if defined, is a string of keywords separated by blanks. Thekeywords turn on different kinds of traces, as follows (thekeywords may be in uppercase or lowercase):

STMT Trace all SQL statements being executed or prepared.OPER Trace internal operation codes.DATA Trace data being sent to, or received from, the database.RC Trace return codes from CLI and SQL procedures.CLI Trace all calls to CLI.

For example, by defining ZZSQLSHOW='stmt data', you can see allexecuted SQL statements, and all data exchanged by them.

Version 2.0B-6

Datab

ase DataC

Storing and Retrieving DatabaseData

The data types of database columns are not necessarily the same asthose used by the log collector. However, the log collector treats eachdatabase column as if had one the log collector’s data types describedunder “Data Types” on page 8-2. Because this data type differs fromthat of the column, the log collector performs certain conversionswhen retrieving and storing the data.

Table 45 on page C-2 specifies how the log collector interprets thedata in a DB2/6000 database. Listed under DB2 type are differentcolumn types that can occur in a DB2 table. For each of these types,Log collector typeis the data type assumed for that column by thelog collector. For example, a DB2 column of type DECIMAL isinterpreted by the log collector as containing floating-point numbers.

Conversion on inputis the conversion performed by the log collectorwhen it fetches the data. For example, a value stored in a TIMEcolumn looks like a time value, but does not have the microsecondpart. When the log collector fetches data from a TIME column, itadds a microsecond part of 000000 to obtain a complete time value.

Conversion on outputis the conversion performed by the log collectorwhen it stores the data. For example, when the log collector stores atime value in a TIME column, it discards the microsecond partwithout rounding.

The DB2/6000 data types not shown in the table are not supported bythe log collector.

TME 10 Reporter: Log Collector Guide and Reference C-1

Storing and Retrieving

Table 46 on page C-3 contains similar information for the ORACLEdatabase, and Table 47 on page C-4 for the SYBASE database.

Notice that a column of type DATE is a timestamp column inORACLE, while it is a date column DB2/6000. This might be asource of confusion if you are preparing an application that shouldwork on both DB2/6000 and ORACLE.

Table 45. Correspondence Between DB2/6000 Data Types and Log Collector Data Types

DB2 type Logcollectortype

Conversion on input Conversion on output

SMALLINT Integer No conversion. No conversion.

INTEGER Integer No conversion. No conversion.

FLOAT Floating-pointnumber

No conversion. No conversion.

DECIMALNUMERIC

Floating-pointnumber

Convert to the closest valuethat can be represented as a64-bit floating-point number.

Convert to the closest decimalnumber with the precision andthe scale defined for thecolumn.

CHAR Characterstring

If the string exceeds 254bytes, truncate it to 254 bytes.The truncation can occur inthe middle of a multiple-bytecharacter.

If the string has lengthdifferent from the columnlength, truncate it or extendwith blanks to the columnlength. The truncation canoccur in the middle of amultiple-byte character.

VARCHAR Characterstring


If the string exceeds themaximum length for thecolumn, truncate it to thatlength. The truncation canoccur in the middle of amultiple-byte character.

DATE Date No conversion. No conversion.

TIME Time Add a microsecond part of000000.

Discard the microsecond part(no rounding).

TIMESTAMP Date No conversion. No conversion.

Version 2.0C-2

Datab

ase Data


Table 46. Correspondence Between ORACLE Data Types and Log Collector Data Types

ORACLEtype

Logcollectortype


NUMBERwith scale =0

Integer No conversion. If the value isoutside the range of logcollector integers, convert it toerror null.

No conversion.

NUMBERwith scale ≠0


No conversion. No conversion.



Replace invalid charactercodes by valid ones. (Whichare the valid codes dependson the installation.)If the string has lengthdifferent from the columnlength, truncate it or extendwith blanks to the columnlength. The truncation canoccur in the middle of amultiple-byte character.

VARCHAR2 Characterstring


Replace invalid charactercodes by valid ones. (Whichare the valid codes dependson the installation.)If the string has length 0,convert it to one blank. If thestring exceeds the maximumlength for the column,truncate it to that length. Thetruncation can occur in themiddle of a multiple-bytecharacter.

DATE Timestamp Add a microsecond part of000000. If the value is outsidethe range of log collectortimestamps, convert it to errornull.


TME 10 Reporter: Log Collector Guide and Reference C-3


Table 47. Correspondence Between SYBASE Data Types and Log Collector Data Types

SYBASEtype

Logcollectortype


SMALLINT Integer No conversion. No conversion.

INTEGER Integer No conversion. No conversion.

FLOATDOUBLEREAL


No conversion. No conversion if the columnhas precision of 64 bits. If thecolumn has precision of 32bits, round to the closestvalue representable in 32 bits.

DECIMALNUMERIC


Convert to the closest valuethat can be represented as a64-bit floating-point number.

Convert to the closest decimalnumber with the precision andthe scale defined for thecolumn.



Replace invalid charactercodes by valid ones. (Whichare the valid codes dependson the installation.)If the string has lengthdifferent from the columnlength, truncate it or extendwith blanks to the columnlength. The truncation canoccur in the middle of amultiple-byte character.

VARCHAR Characterstring


Replace invalid charactercodes by valid ones. (Whichare the valid codes dependson the installation.)If the string exceeds themaximum length for thecolumn, truncate it to thatlength. The truncation canoccur in the middle of amultiple-byte character.

DATETIMESMALLDATETIME

Timestamp Add a microsecond part of000000.


Version 2.0C-4

Syn

tax Diag

rams

DHow to Read Syntax Diagrams

The syntax diagrams in “Elements of the Log Collector Language”through “Log Collector Language Statements” graphically illustratethe coding options available for the log collector functions andstatements. These diagrams give you a quick visual method fordetermining whether:

■ An element is a required, optional, or default element.■ A word or value is repeatable.■ An element is fixed or varying.

The lines and arrows in a diagram symbolize the way these elementsare combined to form a valid function or statement. Notice that thesyntax diagrams show the sequence of tokens, not of individualcharacters. For more information, see “How Your Text Is Processed”on page 7-7.

Syntax is described using these conventions:

■ Read the syntax diagrams from left to right, from top to bottom,following the path of the line.

The 55─── symbol indicates the beginning of a statement.

The ────5 symbol indicates that the statement syntax iscontinued on the next line.

The 5──── symbol indicates that a statement is continued fromthe previous line.

The ───5% symbol indicates the end of a statement.

TME 10 Reporter: Log Collector Guide and Reference D-1

Syntax Diagrams

Diagrams of syntactical units other than complete statementsstart with the 5─── symbol and end with the ───5 symbol.

■ Required items appear on the horizontal line (the main path).

55──required_item ────────────────────────────────────5%

■ Optional items appear below the main path.

55──required_item ─ ──┬ ┬───────────── ──────────────────5% └ ┘─optional_item ─

■ If you can choose from two or more items, they appearvertically, in a stack. If you must choose one of the items, oneitem of the stack appears on the main path.

55──required_item ─ ──┬ ┬─required_choice1 ─ ───────────────5% └ ┘─required_choice2 ─

If choosing one of the items is optional, the entire stack appearsbelow the main path.

55──required_item ─ ──┬ ┬──────────────── ───────────────5% ├ ┤─optional_choice1 ─ └ ┘─optional_choice2 ─

If one of the items is the default, it will appear above the mainpath and the remaining choices will be shown below.

┌ ┐─default_choice─55──required_item ─ ──┼ ┼──────────────── ───────────────5% ├ ┤─optional_choice ── └ ┘─optional_choice ──

■ An arrow returning to the left, above the main line, indicates anitem that can be repeated.

┌ ┐─────────────────55──required_item ─ ───

6┴─repeatable_item ─ ────────────────5%

Version 2.0D-2

Syn

tax Diag

rams

Syntax Diagrams

If the repeat arrow contains an item (like a comma), you mustseparate repeated items with that item.

┌ ┐─,─────────────55──required_item ─ ───

6┴─repeatable_item ─ ────────────────5%

A repeat arrow above a stack indicates that you can repeat theitems in a stack.

■ Keywords appear in uppercase (for example, DEFINE RECORD).They must be spelled exactly as shown. Varying parts appear inall lowercase letters (for example, record-name). They representuser-supplied names or values.

55──DEFINE RECORD ──record_name──IN LOG──log_name ─────────5%

■ A fragment contains a large element or group of elements thatappear more than once in the syntax diagram. The fragmentappears at the end of the diagram, before any syntax notes.

All fragment references inside the diagram are enclosed byvertical bars. The text in a fragment reference matches the titleof the fragment it references:

55─ ──ParamNameOne=─┤ FragmentOne ├─ ─────────────────────5

5─ ──ParamNameTwo=─┤ FragmentOne ├─ ─────────────────────5%

FragmentOne:├─ ──┬ ┬─field_name ─ ──┬ ┬─────────────── ────────────────5 └ ┘─\───────── └ ┘ ─OFFSET──integer─

5─ ──┬ ┬─────────────────── ──┬ ┬──────────── ───────────┤ └ ┘ ─LENGTH─ ──┬ ┬─integer─ └ ┘─field_format─ └ ┘─\──────

■ If punctuation marks, parentheses, arithmetic operators, or othersuch symbols are shown, you must enter them as part of thesyntax.

TME 10 Reporter: Log Collector Guide and Reference D-3

Version 2.0D-4

Bibliography

This bibliography lists all publications mentioned in this book as well asother relevant publications.

AIX BooksAIX Version 4.1 Commands Reference (all volumes), SBOF-1851

AIX Version 4.1 Communications Programming Concepts, SC23-2610

AIX Version 4.1 Files Reference, SC23-2512

AIX Versions 3.2 and 4.1 Performance Tuning Guide, SC23-2365

AIX Version 4.1 Quick Reference, SC23-2529

AIX Version 4.1 System Management Guide: Communications andNetworks, SC23-2526

AIX Version 4.1 System Management Guide: Operating System andDevices, SC23-2525

AIX Version 4.1 System User’s Guide: Communications and Networks,SC23-2545

AIX Version 4.1 System User’s Guide: Operating System and Devices,SC23-2544

AIX Documentation Overview, SC23-2456

AIX Hypertext Information Base Library, SC23-2163

AIX Planning for Your System Installation, GC23-2407

AIX Quick Reference, SC23-2401

AIX System Overview, GC23-2406

TME 10 Reporter: Log Collector Guide and Reference Bib-1

Bibliography

AIXwindows Environment/6000 Version 1.2 AIXwindows andAIXwindows Desktop User’s Guide, GC23-2432

AIX Version 3 Commands Reference, GBOF-1802

AIX Version 3 Communication Concepts and Procedures, GBOF-1524

AIX Version 3 Editing Concepts and Procedures, GC23-2212

AIX Version 3 Files Reference, GC23-2200

AIX Version 3 System Management Guide, SC23-2457

AIX Version 3 System User’s Guide, GC23-2377

AIX Version 3 Text Formatting Reference, SC23-2453

AIX Version 3 Topic Index and Glossary, GC23-2201

AIX Version 3.2 Performance Monitoring and Tuning Guide, SC23-2365

DB2 for AIX BooksDB2 for AIX 2.1, Administration Guide, S20H-4580

DB2 for AIX 2.1, Command Reference, S20H-4645

DB2 for AIX 2.1, SQL Reference, S20H-4665

DATABASE 2 AIX/6000, Administration Guide, SC09-1571

DATABASE 2 AIX/6000, Command Reference, SC09-1575

DATABASE 2 AIX/6000, SQL Reference, SC09-1574

ORACLE BooksORACLE7 for AIX-Based Systems Installation & Configuration Guide,Part No. A11366-2

ORACLE7 Server Administrator’s Guide and Reference, Part No.6694-70

ORACLE7 Server SQL Language Reference Manual, Part No. 778-70

SQL*Plus User’s Guide and Reference, Part No. 5142-31-1192

Version 2.0Bib-2

Bibliography

NetView for AIX BooksNetView (4.1) for AIX Programmer’s Guide, SC31-8164

NetView (4.1) for AIX Programmer’s Reference, SC31-8165

NetView for AIX Programmer’s Guide, SC31-6238

NetView for AIX Programmer’s Reference, SC31-6239

SYBASE BooksSYBASE SQL Server Reference Manual, 32401-01-1000

SYBASE SQL Server System Administration Guide, 32500-01-1000

SYBASE SQL Server Transact-SQL User’s Guide, 32300-01-1000

Systems Monitor for AIX BooksSystems Monitor (2.2) for AIX User’s Guide, SC31-8173

Systems Monitor for AIX User’s Guide, SC31-7150

Systems Monitor for HP-UX User’s Guide, SC31-7146

Systems Monitor for Sun Solaris User’s Guide, SC31-7148

XRT/graph BooksXRT/graph for Motif, Widget Programmer’s Guide and ReferenceManual, Version 2.3

TME 10 Reporter: Log Collector Guide and Reference Bib-3

Version 2.0Bib-4

Glossary

This glossary defines TME 10 Reporter terms.

A

administration . A TME 10 Reporter task that includes maintaining thedatabase, updating installation-dependent information, and ensuring theaccuracy of data collected.

agent. In TME 10 Reporter, a set of programs running on a network nodethat gather data about the node and write the data to log files. Agents cangather data by issuing UNIX commands, and by reading files such as UNIXaccounting files and files produced by other programs (such as NetView andSystems Monitor). Agents are controlled by the manager.

C

calendar. The calendar defines day types and divides days into periods. Itis used during collect and reporting.

collect. See log collector.

component. Separately installable definitions that enable TME 10 Reporterto collect and report on data for a particular systems management purpose.

TME 10 Reporter: Log Collector Guide and Reference Gloss-1

Glossary

D

daemon. A long-running agent program that periodically gathers data byissuing commands. The daemon writes the data to a log file.

database. In TME 10 Reporter, a set of relational database tables thatincludes data tables, lookup tables, and system tables.

data collection. In TME 10 Reporter, a process that consists of two stages.Firstly, the transfer of log files from one or more nodes containing an agentto the node containing the manager. Secondly, the running of the logcollector (see log collector).

data table. In TME 10 Reporter, a table in the database that contains datasummarized from log files. Data may be summarized, for example, by hour,day, or month. The data is used to create reports.

G

gather. A process performed by agents in which performance data isentered into log files. The log files are located in the same nodes as theagents.

graphical options file. A file that specifies the default display format for agraphical report.

I

input data source. A file from which the agent gathers the data that itwrites to log files.

K

key columns. The columns of a database table that together constitute thekey.

Version 2.0Gloss-2

Glossary

L

log. The log file type. Examples of logs are conf, perf, and netview. Eachlog can contain certain predefined types of records. Each record has apredefined format and contains specific data.

log collector. A TME 10 Reporter program that processes log files tocreate records in data tables (referred to as collect), and provides otherTME 10 Reporter services.

log collector language. Statements used to supply definitions to and invokeservices of the log collector.

log definition. The description of a log used by the log collector.

log file. Any file that contains data in a predefined format that can becollected into data tables by the log collector.

log procedure. A program that is used to process all record types in certainlog files.

lookup expression. An expression that specifies how a value is obtainedfrom a lookup table.

lookup table. A table in the database that contains user-providedinformation that is used for grouping, translation, or substitution duringcollect or reporting.

M

manager. In TME 10 Reporter, a set of programs that are installed on onenode in the network, and which use the services of one or more agents. Itprovides all user interfaces and functions for administration and reporting.

MIB . Management information base.

N

node. In TME 10 Reporter, a workstation within the network on which amanager and/or agent is installed.

node group. A number of nodes that are grouped together according touser-defined criteria.


Glossary

P

parameter. A named item in the parameter file, with a value associatedwith it.

parameter file. A file that contains values for parameters that controlcertain TME 10 Reporter actions.

primary key . See key columns.

purge condition. The rules that specify which data is deleted from datatables on a regular basis.

Q

query file. A file that contains an SQL SELECT statement, and optionally,additional commands that specify the contents and format of a report.

R

record definition. The description of log file records used by the logcollector, including detailed record format descriptions.

record procedure. A program that is called to process some types of logrecords.

record type. The classification of records in a log file.

report definition . In TME 10 Reporter, the object used to create anddisplay reports. It defines the data to be used in the creation of a report andthe structure and layout of the report.

report group. A collection of TME 10 Reporter reports that can bereferred to by a single name.

retention period. The period of time a TME 10 Reporter data table retainsdata before purging it.

Version 2.0Gloss-4

Glossary

S

SMIT . Systems Management Interface Tool. A menu system forconfiguring AIX computers. In TME 10 Reporter, SMIT provides a set ofwindows for use by the manager.

SNMP. Simple Network Management Protocol. A protocol running abovethe User Datagram Protocol (UDP) used to exchange network managementinformation.

source. In an update definition, the record or table that contains the dataused to update a data table.

system table. A database table that contains information for controllingTME 10 Reporter functions and operation.

T

table definition. The description of a table used to create the table in thedatabase.

target. In an update definition, the data table in which TME 10 Reporterstores data from the source record or table.

U

update definition. Instructions for entering data into a database table froma record or from another database table. Used by the log collector.

user-supplied information. All of the information that is added to the logfile data to create reports. This information can include data such as calendarinformation, node definitions, and information in lookup tables.

V

view. An alternative representation of data from one or more tables. Aview can include all or some of the columns contained in the table on whichit is defined.


Version 2.0Gloss-6

Index

Special Characters; 7-11:variable 8-8*

field length 10-26, 10-35field names 3-2

&variable 7-11% 8-17

Aaccumulation functions

AVG 10-51COUNT 10-51FIRST 10-51LAST 10-51MAX 10-51MIN 10-51PERCENTILE 10-52SUM 10-50

ADD FIELDS clause 10-9ADD SECTION clause 10-9adding rows in a table 4-15ALTER LOG statement 10-2ALTER RECORD statement 3-10,

10-7

ALTER RECORDPROCstatement 10-11

ALTER UPDATE statement 5-37,10-13

ampersand-variable 7-11AND operator 8-18APPLY SCHEDULE clause

in ALTER UPDATEstatement 10-15

in DEFINE UPDATEstatement 10-45

arithmetic operations 8-13assigning values to variables 10-76asterisk

field length 10-26, 10-35field names 3-2

availability, resourcecalculating actual 5-10summarizing by schedule

period 5-19averages, determining 5-1AVG accumulation function 10-51

TME 10 Reporter: Log Collector Guide and Reference Index-1

Bbibliographyblanks 7-5block comments 7-6BUFFER SIZE clause

in COLLECT statement 10-20in LIST RECORD statement 10-63

BUILT BY clausein ALTER RECORD

statement 10-8in DEFINE RECORD

statement 10-32

CC interface 10-27, 10-39, A-8cascaded update definitions 4-6case expressions 8-20CHAR function 9-2character 7-1character string

concatenation 8-15constants 7-3data type 8-3date string 8-9date/time string 8-9matching with a pattern 8-17time string 8-10timestamp string 8-10

CL interface 10-27, 10-40, A-5COLLECT statement 10-17collecting log data

committing changes to databasetable 6-3

from partially-processed logs 6-5including/excluding tables 6-2log collector language

statement 10-17

collecting log data(continued)more than once 6-4overview 1-1

colon-variable 8-8COMMENT ON statement 10-22comments 7-6COMMIT AFTER clause 10-19concatenation, string 8-15condition

precedence of operators 8-29syntax 8-28

constants 7-3controlling data collection

DEFINE LOG statement 6-5EXCLUDE clause of COLLECT

statement 6-2INCLUDE clause of COLLECT

statement 6-2COUNT accumulation function 10-51CURRENT DATE 8-9CURRENT TIME 8-9CURRENT TIMESTAMP 8-9

Ddata

accessingnested sections 5-32record stems 5-26repeated sections 5-27

managingcollecting data 6-1correcting data in a table 4-13deleting and adding rows in a

table 4-15deleting data in a table 4-12

data tablescascaded updates 4-6creating 4-3

Version 2.0Index-2

data tables(continued)managing data in

correcting data 4-13deleting and adding rows 4-15deleting data 4-12modifying data 4-13

storing data from multiple sources insingle table 4-1

data types 8-2character strings 8-3dates 8-3floating-point numbers 8-2in DB2/6000 tables C-2in ORACLE tables C-2, C-3in SYBASE tables C-3integers 8-2times 8-3timestamps 8-3truth values 8-3

datecurrent 8-9data type 8-3incrementing/decrementing 8-14string 8-9

DATE function 9-3DAY function 9-4DAYS function 9-5DAYTYPE function 9-7DBNAME variable B-4DBNODE variable B-3DBPASSWD variable B-4DBSERVER variable B-3DBUSER variable B-4defaults, using to write record

definitions 3-1DEFINE LOG 10-24

using HEADER clause 6-5

DEFINE PURGE 10-29DEFINE RECORD 10-31

defaults 3-1multiple record types 3-7nested sections 5-29repeated sections 5-25sections 3-4

DEFINE RECORDPROC 10-39using A-1

DEFINE UPDATE 5-1, 5-4, 10-41DELETE FIELD clause 10-9DELETE FROM clause 10-72DELETE SECTION clause 10-9deleting data from tables

DEFINE PURGE statement 10-29deleting rows 4-15PURGE statement 10-68

delimited word 7-2delimiter 7-4diagrams, syntax D-1DIGITS function 9-11DISTRIBUTE clause


in DEFINE UPDATEstatement 5-8, 10-46

distributing measurements 5-7DROP

statement 3-11, 5-38, 10-56durations, labeled 8-11

Eelements

blanks 7-5characters 7-1comments 7-6identifiers 7-9input lines 7-5


elements (continued)processing of 7-7statements 7-11table names 7-10tokens 7-2variables 7-11

error handling 8-5EXCLUDE clause

in COLLECT statement 10-19in PURGE statement 10-69

expressionscase 8-20lookup 8-22precedence of operators 8-28syntax 8-27

FFIELD clause 10-22field format

list of 10-37field length 3-3field name 3-2field offset 3-2FIELDS clause

in DEFINE RECORDstatement 10-34

in LIST RECORD statement 10-60FILE clause

in LOGSTAT statement 10-66FIRST accumulation function 10-51FIRST RECORD clause

in ALTER LOG statement 10-4in DEFINE LOG statement 10-27

FLOAT function 9-12floating-point

arithmetic 8-13comparison 8-16constant 7-4

floating-point (continued)data type 8-2

FOR clausein ALTER RECORDPROC

statement 10-11in DEFINE RECORDPROC

statement 10-39FROM clause

in COLLECT statement 10-18,10-66

in DEFINE PURGEstatement 10-29


in RECALCULATEstatement 10-71

functionAVG 10-51CHAR 9-2COUNT 10-51DATE 9-3DAY 9-4DAYS 9-5DAYTYPE 9-7DIGITS 9-11FIRST 10-51FLOAT 9-12HOUR 9-13INTEGER 9-14INTERVAL 9-15LAST 10-51LENGTH 9-16MAX 10-51MICROSECOND 9-17MIN 10-51MINUTE 9-18MONTH 9-19PERCENTILE 10-52

Version 2.0Index-4

function (continued)PERIOD 9-20ROUND 9-25SECOND 9-27SECTNUM 9-28SUBSTR 9-30SUM 10-50TIME 9-31TIMESTAMP 9-32TRANSLATE 9-34VALUE 9-36WORD 9-37YEAR 9-38

GglossaryGROUP BY clause



in LIST statement 10-61using 2-6

HHEADER clause


HOUR function 9-13

IIDENTIFIED BY clause

in ALTER RECORDstatement 10-9


identifier 7-9IN LOG clause



IN SECTION clausein ALTER RECORD


statement 10-33INCLUDE clause

in COLLECT statement 10-18in PURGE statement 10-68

infix operator 8-13input format 7-5INSERT INTO clause 10-73integer

arithmetic 8-13comparison 8-16constant 7-4data type 8-2

INTEGER function 9-14INTERVAL function 9-15invalid data 8-4invoking log collector B-1IS clause 10-23

Llabeled durations 8-11LANGUAGE C 10-27, 10-39, A-8LANGUAGE CL 10-27, 10-40, A-5LANGUAGE clause

in ALTER LOG statement 10-5in ALTER RECORDPROC

statement 10-11in DEFINE LOG statement 10-27in DEFINE RECORDPROC

statement 10-39


LAST accumulation function 10-51LAST RECORD clause


LENGTH function 9-16length, field 3-3LET clause



LIKE operator 8-17line comments 7-6LIST statement 10-58LISTFILE clause 10-63LOG clause

in COMMENT ON statement 10-22in DROP statement 10-56

log datacollecting from partially-processed

logs 6-5collecting more that once 6-4controlling data collection 6-1listing 1-2, 10-58

log definitionchanging 10-2storing 2-12

log procedurecalling A-3changing 10-5creating 10-27parameters A-5using A-1

LOGFILE clause 10-63LOGPROC clause

in ALTER LOG statement 10-5in DEFINE LOG statement 10-27using A-1

LOGSTAT statement 10-66lookup expressions 8-22

MMAX accumulation function 10-51measurements, distributing 5-7MERGE clause



MICROSECOND function 9-17MIN accumulation function 10-51MINUTE function 9-18missing data 8-4missing or invalid 8-4MONTH function 9-19multiple record types, defining 3-9multiple sources data in single data

tables, storing 4-1multiple-byte characters 7-1, 7-3, 7-6,

7-9, 8-3, 8-18, 9-30, 9-35, 9-37, 10-37,C-2, C-3

Nnested sections within records

accessing data in 5-32, 5-33defining a record within 5-31overview 5-29

NOT operator 8-18null value

handling 8-4testing for 8-19

numericconstants 7-4data types 8-2

Version 2.0Index-6

OON OVERFLOW clause

in COLLECT statement 10-20in LIST RECORD statement 10-63

operationsarithmetic 8-13logical 8-18precedence (conditions) 8-29precedence (expressions) 8-28

OR operator 8-18ORDER BY clause 10-62

PPARM clause

in ALTER RECORDPROCstatement 10-11

in DEFINE RECORDPROCstatement 10-40

partially-processed logs, collecting datafrom 6-5

pattern matching 8-17percent sign 8-17PERCENTILE accumulation

function 10-52percentiles, determining 5-4PERIOD function 9-20prefix operator 8-13prlogcol command B-1publicationsPURGE

FROM clause 10-56statement 10-68

RRECALCULATE statement 4-13,

10-70

RECORD clausein COMMENT ON statement 10-22in DROP statement 10-56

record definitionchanging 10-7example 2-4nested sections 5-31repeated sections 5-25sections 3-4storing 2-8using defaults 3-1verifying 2-9

record procedurecalling A-3changing 10-11creating 10-39interface specifications A-5parameters A-5using A-1

record types, multiple 3-9RECORDPROC clause

in COMMENT ON statement 10-22in DROP statement 10-56

repeated sections within recordsaccessing data 5-33accessing data from sections 5-27accessing data from the source

records 5-26defining records for 5-25general discussion 5-23how the log collector

processes 5-33REPROCESS clause 10-19resource availability

calculating actual 5-10general discussion 5-10summarizing by schedule

period 5-19


ROUND function 9-25

SSECOND function 9-27SECTION clause





in LIST RECORD statement 10-60section occurrence number,

obtaining 5-36sections within a record

accessing data 5-33defining nested 5-29defining records for 3-4general discussion 3-4obtaining a section occurrence

number 5-36repeated 5-23

SECTNUM function 9-28semi-colon 7-11SET clause



using 2-6SET statement 10-76SHOWINPUT variableSOURCE clause


SQL statement 10-78sql-condition 10-29, 10-70sql-statement 10-78statements

ALTER LOG 10-2ALTER RECORD 3-10, 10-7ALTER RECORDPROC 10-11ALTER UPDATE 10-13COLLECT 10-17COMMENT ON 10-22DEFINE LOG 6-5, 10-24DEFINE PURGE 10-29DEFINE RECORD 10-31DEFINE RECORDPROC 10-39DEFINE UPDATE 10-41DROP 3-11, 10-56LIST 10-58LOGSTAT 10-66PURGE 10-68RECALCULATE 10-70SET 10-76SQL 10-78

statistics, data collection 7-3, 10-66storing

data from multiple sources in singledata tables 4-1

data in multiple tables 4-6definitions, general discussion 2-8update definitions 2-8

stringconcatenation 8-15constants 7-3data type 8-3date string 8-9date/time string 8-9matching with a pattern 8-17time string 8-10timestamp string 8-10

Version 2.0Index-8

SUBSTR function 9-30SUM accumulation function 10-50syntax diagrams, overview D-1

Ttables

cascaded updates 4-6changing data 4-13deleting and adding rows 4-15naming conventions 7-10retrieving data from C-2, C-3rules for storing data in 10-55, C-2,

C-3updating from another table 4-6updating from multiple sources 4-1

TABPREFIX variable B-4terms, list oftime

current 8-9data type 8-3incrementing/decrementing 8-15string 8-9

TIME function 9-31timestamp

current 8-9data type 8-3incrementing/decrementing 8-15string 8-10TIMESTAMP function 9-32

TIMESTAMP clausein ALTER LOG statement 10-4in ALTER UPDATE

statement 10-26in DEFINE LOG statement 10-26in DEFINE UPDATE

statement 10-48

TO clause 10-42tokens 7-2TRANSLATE function 9-34truth value

applying operators to a 8-18data type 8-3unknown 8-5

Uunknown truth value 8-5UPDATE clause

in COMMENT ON statement 10-22in DROP statement 10-56in RECALCULATE

statement 10-74update definitions

averages, determining 5-1changing

ALTER UPDATEstatement 5-37

DROP statement, deletingwith 5-38

creating cascaded 4-6GROUP BY clauses 2-6measurement, distributing 5-7nested sections within records

accessing data in 5-32defining records with 5-31general discussion 5-29

percentiles, determining 5-4repeated sections within records

defining records for 5-25defining updates for 5-25general discussion 5-23how the log collector

processes 5-33resource availability, determining

calculating actualavailability 5-10


update definitions(continued)resource availability, determining

(continued)comparing actual to

scheduled 5-19general discussion 5-10

SET clauses 2-6storing 2-8writing

records with repeatedsections 5-25

storing data in multiple datatables 4-7

storing multiple source data insingle data tables 4-1

USER keyword 8-9

VVALUE function 9-36variable

marker 7-11reference 8-8values, setting 10-76

verifying record definitions 2-9VERSION clause

in DEFINE LOG statement 10-25in DEFINE PURGE


statement 10-39in DEFINE RECORDPROC

statement 10-32in DEFINE UPDATE

statement 10-41

WWHERE clause


in COLLECT statement 10-18in DEFINE PURGE

statement 10-29in DEFINE UPDATE

statement 10-42in LIST RECORD statement 10-61

worddefinition of 7-2delimited 7-2

WORD function 9-37

YYEAR function 9-38

ZZZCOMPCOMM variable B-5ZZCOMPPROG variable B-5ZZCOMPSHOW variable B-6ZZCOMPSNAP variable B-5ZZLOOKDATA variable B-6ZZLOOKSHOW variable B-6ZZLOOKSNAP variable B-6ZZSQLSHOW variable B-6

Version 2.0Index-10

SH19-4121-ð2