BMC Patrol API

PATROL API
Reference Manual
Version 3.3
September 30, 1999
This document is published by the BMC Software, Inc., Technical Publications Department. Copyright 19941999 BMC Software, Inc. All rights reserved. BMC Software, the BMC Software logos, and all other product or service names are trademarks or registered trademarks of BMC Software, Inc., in the USA and in other select countries. The and indicate USA trademark or USA registration. *IBM and DB2, Acrobat, Computer Associates and CA, Informix, Sequent, Sun Microsystems and Sun, and Sybase are trademarks or registered trademarks of, respectively, International Business Machines Corp.; Adobe Systems, Inc.; Computer Associates Int'l, Inc.; Informix Software, Inc.; Sequent Computer Systems, Inc.; Sun Microsystems, Inc.; and Sybase, Inc. Oracle is a registered trademark, and the Oracle product names are trademarks or registered trademarks of Oracle Corp. All other third-party logos and product/trade names are trademarks or registered trademarks of their respective companies. RESTRICTED RIGHTS LEGEND Use, distribution, or disclosure by the Government is subject to restrictions set forth in subparagraph (c)(1)(ii) of Rights in Technical Data and Computer Software clause in DFARS 252.227-7013. BMC Software, Inc. 2101 CityWest Blvd. Houston, TX 77042-2827 USA
Contacting BMC Software

For information about obtaining technical support, see www.bmc.com/support.html. For all other purposes, contact BMC Software as follows: USA and Canada BMC Software, Inc. 2101 CityWest Blvd. Houston TX 77042-2827 USA Telephone: 800 841 2031 www.bmc.com Outside USA and Canada For a complete list of all BMC Software international ofces and subsidiaries, see the BMC Software home page at www.bmc.com. USA corporate headquarterstelephone: (1) 713 918 8800
BMC Software, Inc., Condential and Proprietary Information
iii
iv
Product
Namefor DBMS
Document Type
Contents
Contents
About This Manual Chapter 1 Overview of the PATROL API
Introduction . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1-2 How the PATROL API Fits Into PATROL . . . . . . . . . . . . . . . . . 1-2 How You Can Interact with PATROL Agents . . . . . . . . . . . . . . . 1-2 How You Can Integrate Applications and Manage the Enterprise 1-3 Accessing the PEM Engine . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1-4 Connecting User Programs to the PATROL Agent . . . . . . . . . . . 1-5 Functions for Retrieving Information from a PATROL Agent . . . . . 1-5 Determining Whether to Use Blocking or Non-blocking (Event-Driven) Functions . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1-6 More Information About Functions for Retrieving Information From a PATROL Agent . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1-7 Functions for Connecting to the PEM Engine . . . . . . . . . . . . . . . . . . 1-8 Benets of Connecting to the PEM Engine using PATROL API Functions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1-9 Receiving Events from the PEM Engine . . . . . . . . . . . . . . . . . . 1-10 Sending Events to the PEM Engine . . . . . . . . . . . . . . . . . . . . . . 1-11 More Information About Functions for Connecting to the PEM Engine . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1-12 Example of a PATROL API Blocking Program . . . . . . . . . . . . . . . . 1-13 Example of a PATROL API Non-Blocking Program . . . . . . . . . . . . 1-17
Contents
Chapter 2
Example Programs
Overview . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .2-2 Sending and Receiving Events From One PATROL Agent . . . . . . . .2-3 Sending and Receiving Events From Multiple PATROL Agents . . .2-9 Sending, Querying and Generating Event Reports in Blocking Mode 2-16 Requesting Information in Blocking Mode . . . . . . . . . . . . . . . . . . . .2-23 Dumping Events Using Blocking Mode . . . . . . . . . . . . . . . . . . . . . .2-31
Chapter 3 Data Structures
Overview of Type Denitions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .3-3 PemnApplAttrArray . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .3-5 PemnApplAttrEnum . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .3-6 PemnApplObjHandle . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .3-7 PemnBDisconnectCallback . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .3-8 PemnClientData . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .3-9 PemnCommCallback . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .3-10 PemnCommHandle . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .3-11 PemnArchiveEventHandler . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .3-12 PemnEventHandle . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .3-13 PemnEventStatusEnum . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .3-14 PemnEventTypeEnum . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .3-15 PemnGetApplObjHandler . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .3-16 PemnGetEventClassHandler . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .3-17 PemnGetEventClassListHandler . . . . . . . . . . . . . . . . . . . . . . . . . . . .3-18 PemnGetInstObjHandler . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .3-19 PemnGetListHandler . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .3-20 PemnGetParamObjHandler . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .3-21 PemnGetVarObjHandler . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .3-22 PemnInstAttrArray . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .3-23 PemnInstAttrEnum . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .3-24 PemnInstObjHandle . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .3-25 PemnParamAttrArray . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .3-26 PemnParamAttrEnum . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .3-27 PemnParamObjHandle . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .3-28 PemnQueryEventHandler . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .3-29 PemnReceiveEventHandler . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .3-30 PemnReportEventHandler . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .3-32 PemnReportHandle . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .3-33 PemnUserMessageHandler . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .3-34
vi
PATROLAPI
Reference Manual
PemnVarObjHandle . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3-35
Chapter 4 Event Access Functions
PemnGetArgs() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 4-2 PemnGetClassName() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 4-3 PemnGetDesc() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 4-4 PemnGetDiary() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 4-5 PemnGetEid() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 4-6 PemnGetEventCatalogName() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 4-7 PemnGetExpectancyStr() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 4-8 PemnGetHandler() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 4-9 PemnGetNode() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 4-10 PemnGetNseverity() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 4-11 PemnGetOrigin() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 4-12 PemnGetOwner() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 4-13 PemnGetSourceID() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 4-14 PemnGetStatus() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 4-15 PemnGetTime() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 4-16 PemnGetType() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 4-17
Chapter 5 Connection Management Functions
PemnBClose() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 5-2 PemnBOpen() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 5-4 PemnBPing() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 5-6 PemnClose() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 5-8 PemnGetCommAttributes() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 5-9 PemnGetLocalPort() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 5-11 PemnLoop() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 5-12 PemnOpen() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 5-13 PemnSetCommAttributes() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 5-16 PemnSetLocalPort() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 5-18
Chapter 6 Security Management Functions
PemnEncrypt() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 6-2 PemnSendIdentity() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 6-3

Chapter 7 Send and Receive Functions
PemnReceive() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 7-2 PemnSend(), PemnBSend() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 7-7
Contents
vii
Chapter 8
Event Management Functions
PemnAddDiary() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .8-2 PemnDeneEventClass() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .8-4 PemnEventArchive(), PemnBEventArchive() . . . . . . . . . . . . . . . . . .8-7 Specifying the Pemn(B)EventArchive() Output Format . . . . . . .8-13 PemnEventManage() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .8-16 PemnEventManageIfMatch(), PemnBEventManageIfMatch() . . . . .8-18 PemnEventQuery(), PemnBEventQuery() . . . . . . . . . . . . . . . . . . . . .8-24 PemnEventRangeManage() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .8-31 PemnEventRangeQuery() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .8-34 PemnEventReport(), PemnBEventReport() . . . . . . . . . . . . . . . . . . . .8-37 PemnFlushEvent() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .8-43 PemnGetEventClass(), PemnBGetEventClass() . . . . . . . . . . . . . . . .8-44 Specifying the PemnGetEventClass() Function Output Format .8-46 PemnGetEventClassList(), PemnBGetEventClassList() . . . . . . . . . .8-48 PemnSetEventClassCmd() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .8-50 PemnSetPersistentFilter(), PemnBSetPersistentFilter() . . . . . . . . . . .8-53
Chapter 9 Application Management Functions
PemnBPslExec() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .9-2 PemnBSetVarObj() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .9-4 PemnGetApplList(), PemnBGetApplList() . . . . . . . . . . . . . . . . . . . .9-6 PemnGetApplObj(), PemnBGetApplObj() . . . . . . . . . . . . . . . . . . . .9-8 PemnGetApplObjAttributes() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .9-11 PemnGetApplObjInfo() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .9-12 PemnGetComputerParamList(), PemnBGetComputerParamList() . .9-14 PemnGetComputerParamObj(), PemnBGetComputerParamObj() . .9-16 PemnGetInstList(), PemnBGetInstList() . . . . . . . . . . . . . . . . . . . . . .9-19 PemnGetInstObj(), PemnBGetInstObj() . . . . . . . . . . . . . . . . . . . . . .9-22 PemnGetInstObjAttributes() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .9-25 PemnGetInstObjInfo() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .9-26 PemnGetParamList(), PemnBGetParamList() . . . . . . . . . . . . . . . . . .9-28 PemnGetParamObj(), PemnBGetParamObj() . . . . . . . . . . . . . . . . . .9-31 PemnGetParamObjAttributes() . . . . . . . . . . . . . . . . . . . . . . . . . . . . .9-34 PemnGetParamObjInfo() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .9-35 PemnGetVarList(), PemnBGetVarList() . . . . . . . . . . . . . . . . . . . . . .9-37 PemnGetVarObj(), PemnBGetVarObj() . . . . . . . . . . . . . . . . . . . . . . .9-40
Chapter 10 Data Management Functions
PemnPutStream(), PemnBPutStream() . . . . . . . . . . . . . . . . . . . . . .10-2

viii
PATROLAPI
Reference Manual
Chapter 11
Miscellaneous Functions
PemnCheckInit() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 11-2 PemnGetLastMessage() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 11-3 PemnRegisterUserMessageHandler() . . . . . . . . . . . . . . . . . . . . . . . 11-4

Chapter 12 Specic Blocking Mode Functions
PemnBExitFunction() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 12-2 PemnBGetTimeout() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 12-3 PemnBSetTimeout() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 12-4

Chapter 13 Extended Security Interface
Overview . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 13-3 ESI Files . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 13-3 ESI Examples . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 13-4 Supported Platforms . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 13-4 ESI Operation . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 13-5 Implementing ESI to Enhance PATROL Security . . . . . . . . . . . . . . 13-7 ESI Data Structures . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 13-14 BMC_Sec_Plugin . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 13-14 esi_Context() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 13-15 ESI Data Type Denitions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 13-15 EsiAcceptProc . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 13-15 EsiConnProc . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 13-17 EsiQueueMessageProc . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 13-18 EsiSendProc . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 13-19 ESI Functions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 13-20 esi_AllocateContext() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 13-20 esi_Connect() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 13-21 esi_FreeContext() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 13-23 esi_GetVersion() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 13-24 esi_IsClient() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 13-25 esi_IsEstablished() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 13-26 esi_IsTrusted() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 13-27 esi_Read() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 13-28 esi_ServerInit() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 13-30 esi_ValidateAccount() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 13-31 esi_Write() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 13-32 SdkInit() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 13-34 PATROL Event Log Messages . . . . . . . . . . . . . . . . . . . . . . . . . . . . 13-35
Contents
ix
Chapter 14
PATROL COM/DCOM Interface
Overview . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .14-3 COM/DCOM Files . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .14-4 Conguring the PATROL COM/DCOM Interface . . . . . . . . . . . . .14-4 Conguring COM Servers . . . . . . . . . . . . . . . . . . . . . . . . . . . . .14-4 Conguring DCOM Clients . . . . . . . . . . . . . . . . . . . . . . . . . . .14-6 Accessing the PATROL Agent COM Server . . . . . . . . . . . . . . . . . .14-6 Through the Dispatch Interface . . . . . . . . . . . . . . . . . . . . . . . . .14-7 Through a Custom Interface Program . . . . . . . . . . . . . . . . . . . .14-8 IPatrolAgent Interface Functions . . . . . . . . . . . . . . . . . . . . . . . . . . .14-10 annotate() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .14-12 annotate_get() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .14-14 blackout() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .14-16 change_state() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .14-18 create() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .14-20 destroy() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .14-22 exists() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .14-24 get() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .14-26 getenv() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .14-28 get_psl_errno() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .14-30 get_ranges() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .14-31 get_vars() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .14-33 history() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .14-35 is_var() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .14-37 PslExecute() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .14-39 print() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .14-41 set() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .14-43 set_alarm_ranges() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .14-45 unset() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .14-47
Appendix A Read-Only Functions
Introduction to Locking and Reading a PATROL Event Log . . . . . A-2 Synchronizing the PATROL Agent and PATROL API Calls . . . A-2 Locking and Unlocking the Event Log for Read Requests . . . . A-3 Sequence of the Functions for Locking and Reading a PATROL Event Log . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . A-3 More Information About Functions for Locking and Reading a PATROL Event Log . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . A-4 PemnEnd() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . A-5 PemnFreeEventBuffer() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . A-6
PATROLAPI
Reference Manual
PemnLock() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . PemnQueryEvents() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . PemnStart() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . PemnUnlock() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . PemrError() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Pemn Message Strings . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .

Appendix B Using Your Own Event Loop
A-7 A-9 A-13 A-15 A-17 A-18
How Your Program Waits for Activities . . . . . . . . . . . . . . . . . . . . . The Library for the Default Event Loop . . . . . . . . . . . . . . . . . . . . . Using the PATROL API from an X Application . . . . . . . . . . . . . . . Using the PATROL API with a Custom Event Loop . . . . . . . . . . . .
Appendix C Hints
B-2 B-2 B-2 B-3
Hint #1Allocating Communication Handles . . . . . . . . . . . . . . . . C-2 Example of Correct Allocation: s_hComm Is Static . . . . . . . . . C-2 Example of Incorrect Allocation: hComm Is Allocated on the Stack C-3 Hint #2Exiting the PATROL API Event Loop Using g_MainLoopInterrupt . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . C-4 Hint#3All Handles to Objects Are Not Stored or Freed . . . . . . . C-4
Appendix D Extending the Power of PATROL
Introduction . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Capabilities for Knowledge Module Developers . . . . . . . . . . . . . . . Interacting with a KMTwo-Way Communication . . . . . . . . Application MonitoringBeyond the Physical Barrier . . . . . . Custom Browser of PATROL Objects . . . . . . . . . . . . . . . . . . . . Event Knowledge Broker . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Capabilities for Application Integrators . . . . . . . . . . . . . . . . . . . . . Event Translation . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Event Correlation . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Event Routing . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Event Synchronization . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . What Does the PATROL API Provide? . . . . . . . . . . . . . . . . . . . . . . PATROL API Availability . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Conclusion . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
D-2 D-4 D-5 D-8 D-9 D-10 D-11 D-12 D-13 D-15 D-17 D-19 D-20 D-21
Contents
xi
Appendix E
ESI Examples
BMC Example: esiapi_impl.h . . . . . . . . . . . . . . . . . . . . . . . . . . . . . E-2 BMC Example: esiapi_impl.c . . . . . . . . . . . . . . . . . . . . . . . . . . . . . E-4

Appendix F Example of annotate() Function
annotate() Example . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . F-2

Glossary Index
xii
PATROLAPI
Reference Manual
Figures
Figures
Figure 1-1 Figure D-1 Figure D-2 Figure D-3 Figure D-4 Figure D-5 Figure D-6 Figure D-7 Figure D-8 Figure D-9 Figure D-10 Figure D-11 Functions in the PATROL API . . . . . . . . . . . . . . . . . . . . . . . . . . 1-5 Event Management Architecture in PATROL . . . . . . . . . . . . . . D-3 Program-Extended Data Collector . . . . . . . . . . . . . . . . . . . . . . D-5 Two-Way Communication in Interacting with a KM . . . . . . . . D-6 Remote Psl Execution . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . D-7 Application Monitoring Beyond the Physical Barrier . . . . . . . D-8 Custom View of the PATROL Object Browser . . . . . . . . . . . . . D-9 Event Knowledge Broker . . . . . . . . . . . . . . . . . . . . . . . . . . . . . D-10 Event Translator . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . D-12 Event Correlation . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . D-14 Event Forwarding . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . D-16 Example of Event Synchronization . . . . . . . . . . . . . . . . . . . . . . D-18
Figures
xiii
xiv
PATROLAPI
Reference Manual
Tables
Tables
Table 5-1 Table 13-1 Table 13-2 Table 13-3 Table 13-4 Table 13-5 Table 13-6 Table 14-1 Table 14-2 Table D-1 Table D-2 Return Values for Blocking Functions . . . . . . . . . . . . . . . . . . . . 5-3 ESI Files. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 13-3 ESI Examples. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 13-4 Mandatory ESI Functions . . . . . . . . . . . . . . . . . . . . . . . . . . . . 13-8 Optional ESI Functions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 13-9 patrol.conf File Location . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 13-10 ESI Message in PATROL Event Log . . . . . . . . . . . . . . . . . . . . 13-35 PATROL COM/DCOM Files . . . . . . . . . . . . . . . . . . . . . . . . . . 14-4 PATROL Agent COM Variables . . . . . . . . . . . . . . . . . . . . . . . 14-5 PATROL API Examples for Knowledge Module Developers . . D-4 PATROL API Examples for Application Integrators . . . . . . . . . D-11
Tables
xv
xvi
PATROLAPI
Reference Manual
About . . .
About This Manual

The PATROL API Reference Manual describes the following interfaces: The PATROL Application Program Interface (API), a series of functions dened in a C header le that allow a user-written, non-PATROL program to connect to a PATROL Event Manager or read a PATROL event log circular le. The PATROL Extended Security Interface (ESI), a series of functions that allows implementation of security enhancements based on the Massachusetts Institute of Technology (MIT) Kerberos network encryption protocol. The PATROL Component Object Model/Distributed Component Object Model (COM/DCOM) Interface, a series of functions that allows collection of data from PATROL Agents through COM-compatible applications.
Note
This book assumes that you are familiar with your host operating system, the C or C++ programming language and/or Visual Basic; the PATROL Event Manager event catalogs, event types, and persistent lter; Kerberos network authentication protocol; and COM/DCOM protocol.
About This Manual
xvii
How This Book Is Organized

This book is organized as follows. In addition, a glossary of terms and an index appear at the end of the book.
Chapter/Appendix Number and Title
Overview of the PATROL API
Description
Describes how the PATROL API ts into PATROL and what you can do with the PATROL API. This chapter also provides an overview of functions and two example programs. Provides example programs written with the PATROL API and tells you where to nd the electronic copies of the examples. You can use the examples as templates for your own programs. Describes the data structures used within the PATROL API function denitions. Describes the event access function calls that return the details of a PATROL event. Describes the connection management functions that open, close, and manage the connection between your program and the PATROL Agent. Describes the security management functions that provide for account information encryption and identication. Describes the send and receive functions that send PATROL events to, and receive PATROL events from, the PATROL Agent. Describes the event management function calls.The event management calls contact the PEM engine logic. Describes the application management function calls that return information about PATROL computer, application class, instance, parameter, and variable objects. Describes the data management function calls that are used to send a stream of bytes to a PATROL Agent. Describes the Pemn miscellaneous function calls. Describes the blocking mode functions for specic purposes such as exiting a function call and PATROLAPI Reference Manualretrieving the current blocking function default waiting time.
Example Programs
Data Structures Event Access Functions Connection Management Functions Security Management Functions Send and Receive Functions
Event Management Functions Application Management Functions Data Management Functions Miscellaneous Functions Specic Blocking Mode Functions
xviii
PATROLAPI
Reference Manual
Chapter/Appendix Number and Title

Extended Security Interface PATROL COM/DCOM Interface
Description
Describes the PATROL ESI and its capabilities for enhancing the security of PATROL. Describes the PATROL COM/DCOM interface and describes its capabilities for accessing data from PATROL Agents through COM applications. Contains the read-only function calls. The read-only calls access a PATROL Event Manager log le. This appendix also denes the error strings returned by the PemnError(), PemnLock(), PemnQueryEvents(), and PemnUnlock() read-only functions. The messages strings are presented in alphabetical order. Contains instructions on using your own event loop. Contains hints on allocating communication handles and exiting the PATROL API event loop. Provides an overview of the PATROL API, describes its capabilities for extending the power of PATROL by linking to user-created programs, and provides illustrations and brief examples of how the PATROL API can be used to provide comprehensive event management. Provides an example of the context data structure required by PATROL for implementation of security enhancements and an example of a full ESI implementation. Provides an example of how to use the annotate() function in a custom interface.
Appendix A, Read-Only Functions
Appendix B, Using Your Own Event Loop Appendix C, Hints Appendix D, Extending the Power of PATROL
Appendix E, ESI Examples
Appendix F, Example of annotate() Function
Related Documentation
BMC Software products offer several types of documentation: online and printed books online Help release notes
About This Manual
xix
Online and Printed Books

The books that accompany BMC Software products are available in online format and printed format. You can view online books with Acrobat Reader from Adobe Systems. The reader is provided at no cost, as explained in To Access Online Books. You can also obtain additional printed books from BMC Software, as explained in To Request Additional Printed Books.
To Access Online Books
You can access online books from the documentation compact disc (CD) that accompanies your product or from the World Wide Web.
Accessing Books with Acrobat Reader
Online books are formatted as Portable Document Format (PDF) les. You can view them, print them, or copy them to your computer by using Acrobat Reader 3.0 or later.
Note
In some cases, installation of Acrobat Reader and downloading the online books is an optional part of the product-installation process. For information about downloading the free reader from the Web, go to the Adobe Systems site at http://www.adobe.com. For information about installing the reader from the documentation CD, see the readme.txt le on the CD.
Accessing Books on the Web
To access any online book that BMC Software offers, visit the support page of the BMC Software Web site at http://www.bmc.com/support.
Note
To use the support page, you must be a registered user or have a temporary user name and a password. If you are a registered user, proceed as follows:
xx
PATROLAPI
Reference Manual
1. Click Log in to Support. 2. Enter your user name and password. 3. To view books for a particular product, click the product name in the Product Directory. 4. Select the book that you want to view. If you are not a registered user, choose one of the following options: To register, click Request UserID, complete the form, and click Send
Request.
To request a temporary user name and a password, contact your BMC Software sales representative.
To Request Additional Printed Books
BMC Software provides a core set of printed books with your product order. To request additional books, go to http://www.bmc.com/support.
Online Help
You can access Help for a product through the products Help menu. The online Help provides information about the products graphical user interface (GUI) and provides instructions for completing tasks.
Release Notes
Printed release notes accompany each BMC Software product. Release notes provide up-to-date information such as updates to the installation instructions last-minute product information
About This Manual
xxi
The latest versions of the release notes are also available on the Web at http://www.bmc.com/support.
Conventions
The following conventions are used in this book: This book includes special elements called notes, warnings, examples, and tips:
Note
Notes provide additional information about the current subject.
Warning
Warnings alert you to situations that can cause problems, such as loss of data, if you do not follow instructions carefully.
Example
An example claries a concept discussed in text.
Tip
A tip provides useful information that may improve product performance or make procedures easier to follow. All syntax, operating system terms, and literal examples are presented in this typeface. In instructions, boldface type highlights information that you enter. File names, directories, and Web addresses also appear in boldface type.
xxii
PATROLAPI
Reference Manual
The symbol => connects items in a menu sequence. For example, Actions => Create Test instructs you to choose the Create Test command from the Actions menu. The symbol
denotes one-step instructions.
In syntax, path names, or system messages, italic text represents a variable, as shown in the following examples: The table table_name is not available.
system/instance/le_name
In syntax, the following additional conventions apply: A vertical bar ( | ) separating items indicates that you must choose one item. In the following example, you would choose a, b, or c: a | b | c An ellipsis ( . . . ) indicates that you can repeat the preceding item or items as many times as necessary. Square brackets ( [ ] ) around an item indicate that the item is optional.
About This Manual
xxiii
The following table shows equivalent mouse buttons for Unix users and Windows NT users:
Unix Button
MB1
Windows NT Button
left mouse button
Description
Click this button on an icon or menu command to select that icon or command. Click MB1 on a command button to initiate action. Double-click an icon to open its container. Click this button on an icon to display the InfoBox for the icon. To simulate MB2 on a two-button mouse, simultaneously press the two buttons (MB1 and MB3). Click this button on an icon to display its pop-up menu.
MB2
not applicable
MB3
right mouse button
Note
If you have a one-button mouse (such as an Apple Macintosh mouse), assign MB1 to that button. You should also dene a user-selectable combination of option and arrow keys to simulate MB2 and MB3. For details, refer to the documentation for your emulation software.
xxiv
PATROLAPI
Reference Manual
1
1PATROLAPI Reference Manual 1
This chapter describes how the PATROL API ts into PATROL and what you can do with the PATROL API. It also provides an overview of functions and two example programs. Introduction . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1-2 How the PATROL API Fits Into PATROL . . . . . . . . . . . . . . . . . . 1-2 How You Can Interact with PATROL Agents . . . . . . . . . . . . . . . 1-2 How You Can Integrate Applications and Manage the Enterprise . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1-3 Accessing the PEM Engine . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1-4 Connecting User Programs to the PATROL Agent . . . . . . . . . . . 1-5 Functions for Retrieving Information from a PATROL Agent. . . . . . 1-5 Determining Whether to Use Blocking or Non-blocking (Event-Driven) Functions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1-6 More Information About Functions for Retrieving Information From a PATROL Agent . . . . . . . . . . . . . . . . . . . . 1-7 Functions for Connecting to the PEM Engine . . . . . . . . . . . . . . . . . . 1-8 Benets of Connecting to the PEM Engine using PATROL API Functions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1-9 Receiving Events from the PEM Engine . . . . . . . . . . . . . . . . . . . 1-10 Sending Events to the PEM Engine . . . . . . . . . . . . . . . . . . . . . . . 1-11 More Information About Functions for Connecting to the PEM Engine . . . . . . . . . . . . . . . . . . . . . . . . 1-12 Example of a PATROL API Blocking Program . . . . . . . . . . . . . . . . . 1-13 Example of a PATROL API Non-Blocking Program . . . . . . . . . . . . . 1-17
1-1
Introduction
The PATROL API, as dened in the C header le pemapi.h, allows your C programs to retrieve information from the agent about PATROL application instances, parameters, and variable objects. register with the PEM engine in the agent to access all event management services.
How the PATROL API Fits Into PATROL

PATROL uses autonomous and intelligent agents to monitor databases and applications over the network. Agents provide the application monitoring and management infrastructure. The application knowledge is loaded from a Knowledge Module written in a scripting language called PATROL Scripting Language (PSL). Event management is handled by a part of the agent called the PATROL Event Manager engine (PEM engine). The PEM engine manages events originating from the agent, knowledge modules running on the agent, or any application that is linked to the agent through the PATROL Application Program Interface (PATROL API).
How You Can Interact with PATROL Agents

You can write programs that interact with PATROL Agents and extend the Knowledge Module capabilities using the PATROL API. For example, using the PATROL API, you can write programs that interact with a Knowledge Module in a bidirectional way. appear as single monitored entities to the user despite being distributed physically on different hosts. load event knowledge from a knowledge broker and broadcast it to all interested hosts.
1-2
PATROLAPI
Reference Manual
act as specialized application browsers of PATROL.

Warning
The PATROL API is not presently thread safe. Unpredictable results may result if your application includes multiple requests through the same connection. Requests should be channeled one at a time through a single thread.
How You Can Integrate Applications and Manage the Enterprise

You can write programs that integrate applications and manage the enterprise using the PATROL API. For example, using the PATROL API, you can write programs that: translate PATROL events into third party vendor events. correlate events from different hosts, Knowledge Modules, and sources into a new compound event which initiates further actions by the PATROL Agent. route events from one agent to another agent or to a custom program. The destination agent or program can provide specialized services (for example, archiving, capacity planning, event consolidation). synchronize events so an event translated into a peer vendor object can be tracked.
1-3
Accessing the PEM Engine

PEM engine features are accessible from any of several sources. Each source has its unique advantages according to the task you want to perform. The table below shows the source to use for the task you want.
Task You Want to Perform
Access PATROL from the command line Monitor a system using an interactive, user-friendly access
Source of Access to Use

The PATROL Command Line Interface (CLI) A GUI such as the PATROL Console or the PATROL Event Manager Console
Additional Information
The PATROL Developer Console allows you to dene the conditions and actions that incoming events can trigger in a PATROL Agent. You can access events through function calls such as event_query() and
Write PSL scripts that access events and objects
The PATROL Script Language (PSL)
event_trigger()
You can access objects through function calls such as create(), get(), and
destroy()
These functions are designed for use by Knowledge Module programmers writing PSL scripts. (Refer to the PATROL Script Language Reference Manual for details about PSL.) Write C programs that include PATROL object monitoring and event management functionality This Application Program Interface (API)
1-4
PATROLAPI
Reference Manual
Connecting User Programs to the PATROL Agent

Figure 1-1 is a block diagram that represents the functions in the PATROL API that provide connections between a program and the PEM engine and PATROL event log. The topics that follow provide a more detailed introduction to the functions.
User Program PATROL Agent pemapi.h

The functions in the PATROL API allow a user program to: Return information from the PEM engine object table Connect with multiple PATROL Event Managers to send and receive event information
PATROL Object Table
PATROL Event Manager Engine
Figure 1-1
Functions in the PATROL API
Functions for Retrieving Information from a PATROL Agent

The PATROL API provides the ability to retrieve information from the PATROL Agent object table for the active computer and application classes, instances, parameters, and variables. Through function calls, a user-written (non-PATROL) program has read access to the information collected and maintained by the PATROL Agent.
1-5
Determining Whether to Use Blocking or Non-blocking (Event-Driven) Functions

The functions provided in the PATROL API support two different programming models, blocking and non-blocking (event driven). The following table gives instructions for determining whether to use blocking functions or non-blocking functions.
If You Want Your Program to...
Continue executing statements
Then Use These Functions...

PemnGet (Non-blocking)
Additional Information
When the return value arrives from the PATROL Agent, the API calls the handler specied in the PemnGet call to process the return value. The PemnGet functions were designed for event-driven programming, where the return value is large, asynchronous, or both, or when the execution speed of the user-written program is a design goal. Programs written using PemnGet function calls execute quickly and can address multiple agents at once (multiplex). However, they are harder to program because of the inability to predict how many program statements might execute before the return value arrives. See Example of a PATROL API Non-Blocking Program on page 1-17 for a simple example of a program written with PemnGet function calls. The PemnBGet return value is passed to the user-written program. The PemnBGet functions were designed for situations where the return value is quickly returned, or when the execution speed of the user-written program is not a design goal. Programs written using PemnBGet function calls are easier to program because of their synchronous nature. However, they execute more slowly than event-driven programs, and they cannot multiplex among agents. See Example of a PATROL API Blocking Program on page 1-13 for a simple example of a program written with PemnBGet function calls.
Wait for the information from the PATROL Agent before executing any more statements
PemnBGet (Blocking)
1-6
PATROLAPI
Reference Manual
More Information About Functions for Retrieving Information From a PATROL Agent
The following table tells you the function to use for the task you want to perform and provides a cross reference for nding detailed information.
Non-blocking
Information You Want to Retrieve

Open a connection with the PATROL Agent so you can retrieve information
Blocking
Function to Use
PemnOpen() PemnBOpen() PemnGetApplList() PemnBGetApplList()
For More Information, See

PemnOpen() on page 5-13 PemnBOpen() on page 5-4 PemnGetApplList(), PemnBGetApplList() on page 9-6 PemnGetApplObj(), PemnBGetApplObj() on page 9-8 PemnGetApplObjInfo() on page 9-12 PemnGetInstList(), PemnBGetInstList() on page 9-19 PemnGetInstObj(), PemnBGetInstObj() on page 9-22 PemnGetInstObjInfo() on page 9-26 PemnGetParamList(), PemnBGetParamList() on page 9-28 PemnGetParamObj(), PemnBGetParamObj() on page 9-31
Application class list
Application class object
PemnGetApplObj() PemnBGetApplObj()
Application class object summary Application instance list
PemnGetApplObjInfo() PemnGetInstList() PemnBGetInstList()
Application instance object
PemnGetInstObj() PemnBGetInstObj()
Application instance object summary Instance parameter list
PemnGetInstObjInfo() PemnGetParamList() PemnBGetParamList()
Instance parameter object
PemnGetParamObj() PemnBGetParamObj()
1-7
Information You Want to Retrieve

Instance parameter object summary Parameter variable list
Non-blocking
Blocking
Function to Use
PemnGetParamObjInfo() PemnGetVarList() PemnBGetVarList()

PemnGetParamObjInfo () on page 9-35 PemnGetVarList(), PemnBGetVarList() on page 9-37 PemnGetVarObj(), PemnBGetVarObj() on page 9-40 PemnGetComputer ParamList(), PemnBGetComputer ParamList()on page 9-14 PemnGetComputer ParamObj(), PemnBGetComputer ParamObj() on page 9-16 PemnClose() on page 5-8 PemnBClose() on page 5-2
Parameter variable object
PemnGetVarObj() PemnBGetVarObj()
Computer instance parameter list
PemnGetComputerParam List() PemnBGetComputerPara mList()
Computer parameter object
PemnGetComputerParam Obj() PemnBGetComputerPara mObj()
Close the connection with the PATROL Agent
PemnClose() PemnBClose()
Functions for Connecting to the PEM Engine

The PATROL API provides an application integration tool that allows user-written (non-PATROL) programs to establish a connection with a PEM engine.
1-8
PATROLAPI
Reference Manual
Each connection to the agent has its own handle, so the PATROL API functions allow a non-PATROL program to connect to any number of agents either on a single computer system or on multiple computer systems. The network transport layer used by the PATROL API functions is compatible with the Universal Datagram Protocol (UDP) and the Transmission Control Protocol (TCP).
Benets of Connecting to the PEM Engine using PATROL API Functions

The benets of using the PATROL API functions to connect a non-PATROL program to the PEM engine are as follows: You can integrate program-specic events from the non-PATROL program into the PATROL event space. You can view events generated by the non-PATROL program in the same way you view PATROL-generated events, that is, using any PATROL or PATROL Event Manager Console. You can close, acknowledge, or delete the events generated by the non-PATROL program. You can trigger application recovery actions in the PATROL Agent by associating the action with an event class and then sending an event of that class from the non-PATROL program. The PATROL Agent will execute the recovery action dened for the event.The recovery action may be any executable command or program. You can send events to the PATROL Event Manager from the non-PATROL program, and when those events escalate, the PATROL Agent will execute the escalation actions dened for their escalation. A non-PATROL program can receive events from the PEM engine and can process the events (for example, dump or record them, or integrate them with a third-party product) in a way that is specic to the non-PATROL program.
1-9
You can send events from the non-PATROL program to the Event Manager that the PATROL Agent will correlate with events from other PATROL and non-PATROL sources. The ability to correlate events from non-PATROL sources customizes and enhances the PATROL Agents ability to detect, diagnose, and correct enterprise-wide warning and alarm conditions. You can use a non-PATROL program to correlate events from different agents and different Knowledge Modules.
Receiving Events from the PEM Engine

The PATROL API functions allow your program to receive events from the PEM engine. The PEM engine treats the PATROL API request for events as it would any other requestor, delivering all events that pass through its persistent lter. A second lter in your PATROL API functions allows you to further lter events, discarding those that dont match the lter, and calling an event handler routine for those that do.
1-10
PATROLAPI
Reference Manual
Sending Events to the PEM Engine

Using the PATROL API functions, your program can trigger any event dened in a PATROL event catalog, including the standard catalog and any user-dened catalogs. The PEM engine does not distinguish between events received from the PATROL API functions and events it receives through processing its own Knowledge Modules. Events that the PATROL Event Manager receives through the PATROL API functions that are viewable from any PATROL or PATROL Event Manager console. can be closed, acknowledged, or deleted. will trigger notications when notication actions are dened. will trigger event escalation when escalation actions are dened. will trigger the Acknowledge action when an event is acknowledged.
1-11
More Information About Functions for Connecting to the PEM Engine

PemnGetCommAttributes() on page 5-9 PemnSetCommAttributes() on page 5-16 PemnEncrypt() on page 6-2 PemnOpen() on page 5-13 PemnSendIdentity() on page 6-3 PemnSetPersistentFilter(), PemnBSetPersistentFilter() on page 8-53 PemnDeneEventClass() on page 8-4 PemnGetEventClass(), PemnBGetEventClass() on page 8-44 PemnGetEventClassList(), PemnBGetEventClassList() on page 8-48 PemnSend(), PemnBSend() on page 7-7 PemnReceive() on page 7-2 PemnFlushEvent() on page 8-43 PemnEventManage() on page 8-16

Return connection attributes Set connection attributes Encrypt a password Open a connection with PATROL Event Manager Send user name and encrypted password to PATROL Agent Set persistent lter for session
Function to Use
PemnGetCommAttributes() PemnSetCommAttributes() PemnEncrypt() PemnOpen() PemnSendIdentity()
PemnSetPersistentFilter()
Add an event class to a PATROL event catalog Return elds from an event class denition Return a list of event classes from a PATROL event catalog Send event to the PATROL Event Manager Filter events from the PATROL Event Manager Flush events to the PATROL event log Change the status of an event
PemnDeneEventClass() PemnGetEventClass()
PemnGetEventClassList()
PemnSend() PemnReceive() PemnFlushEvent() PemnEventManage()
1-12
PATROLAPI
Reference Manual

Add text to the diary of an event Return events that match the lter Change event status in an ID range Return events in an ID range Close the connection with PATROL Event Manager Monitor the connection for activity
Function to Use
PemnAddDiary() PemnEventQuery()

PemnAddDiary() on page 8-2 PemnEventQuery(), PemnBEventQuery() on page 8-24 PemnEventRangeManage() on page 8-31 PemnEventRangeQuery() on page 8-34 PemnClose() on page 5-8 PemnLoop() on page 5-12
PemnEventRangeManage() PemnEventRangeQuery() PemnClose() PemnLoop()
Example of a PATROL API Blocking Program

The following program is an example of a simple PATROL API program using the blocking model. This example program is quite basic and limited. It is meant to show you the basic structure of a PATROL API program so you can begin to write your own. The steps of the program are explained below. The sample code follows the explanations. Refer to the sample code as you read through the explanation of each step. For more involved examples, see Chapter 2, Example Programs
Explanation of Step 1: Encrypt the Password

The Password is sent to the agents encrypted.
1-13
Explanation of Step 2: Open the Connection with the PATROL Agent

PemnBOpen() returns successfully if both of these conditions are met (a boolean AND): The connection is established The username/password is validated.
(Contrast this with the event driven programming shown in Example of a PATROL API Non-Blocking Program on page 1-17). You can specify a retry counter and a disconnect callback which can be executed if the session disconnects before PemnBOpen() completes.
Note
Step 2 (Open Connection) in the blocking mode merges step 1 (Request to Open) and step 3 (Validation) in event driven programming.
Explanation of Step 3: Do the Work

Request an operation to be performed by the agent and wait until the agent sends back the results or a timeout occurs. You can use the default timeout or specify your own (in milliseconds). You can repeat step 3 as often as you want.
Note
Step 3 (Do the Work) in the blocking mode merges step 4 (Request an Operation) and step 5 (Process the Answer Received from the PATROL Agent) in event driven programming.
Note
While waiting for results in step 3 (Do the Work) to return from one agent in the blocking mode, you cannot initiate or process any results from another agent. Processing results or initiating request from/to many agents is possible in event-driven programming.
1-14
PATROLAPI
Reference Manual
Explanation of Step 4: Close the Connection with the PATROL Agent when Finished
PemnBClose() closes the connection.
Hint Regarding Transport Protocols

With blocking mode it may be better to use TCP protocol as a transport. The default transport protocol is UDP but can be changed to TCP using PemnSetCommAttribute()
1-15
Sample Code for a Blocking Mode Program

/* * File: simple.c *------------------------------------------------------------* Description: The hello World equivalent of the blocking-mode API. * (see simple_nb.c for the non-blocking mode example). * All this program does is to connect * to a PATROL agent then dump the application list. * * API routines used: * PemnBOpen, PemnBClose, PemnBGetApplList, PemnEncrypt *------------------------------------------------------------* Author : * Creation date : * * Last check-in date: $Date:$ * * BMC Software, Inc. *------------------------------------------------------------*/ #include <time.h> #include <string.h> #include <stdlib.h> #include <pemapi.h> staticPemnCommHandle s_hComm =NULL;
int main(int argc, char *argv[]) { char *pcOpenResult; charcEncryptedPwd[126+1]; char *pcPlainTextPwd = mypassword;/* put here your password */ char*pcUser = user;/* put here your user name */ char*pcHost = nanou;/* put here your host name */ int iPort = 1234;/* put here your port nb. */ /* * * * if Step 1: encrypt password password is sent encrypted to agents: encrypt the plain text password and store it in the buffer cEncryptedPwd */ ( ! PemnEncrypt(cEncryptedPwd, 126, pcPlainTextPwd)){ printf(Could not encrypt password\n); exit(1);
} /* Step 2: Open the connection with agent */ pcOpenResult = PemnBOpen(& s_hComm, pcHost, iPort,/* agent details */ pcUser,/* account to log in the agent: * user name and encrypted password*/ cEncryptedPwd, 5, /* Loggin retry Counter */ NULL, /* NO disconnect callback */ NULL /* NO disconnect client data */ ); if (strcmp(PEMA_OK, pcOpenResult)!=0) { printf(Cannot connect to PATROL agent (%s,%d): %s\n, pcHost, iPort, pcOpenResult ); exit(1); }
1-16
PATROLAPI
Reference Manual
/* * * if
Step 3: do the work Request the application list and wait until the agent sends back the results OR timeout */ (s_hComm){ printf(Application List of PATROL agent (%s,%d)\n%s\n, pcHost, iPort, PemnBGetApplList(s_hComm, USE_DEFAULT_TIMEOUT) );
} /* Step 4: Close the connection */ if (s_hComm) { PemnBClose(s_hComm); s_hComm = NULL; } return (0); }
Example of a PATROL API Non-Blocking Program

The following program is an example of a simple PATROL API program using the non-blocking model. This example program is quite basic and limited. It is meant to show you the basic structure of a PATROL API program so you can begin to write your own. The steps of the program are explained below. The sample code follows the explanations. Refer to the sample code as you read through the explanation of each step. For more involved examples, see Chapter 2, Example Programs.
Explanation of Step 1: Request to Open a Connection with the PATROL Agent

When the connection is established, the Open Callback will be executed asynchronously. However, if the connection could not be established, the Close Callback will be executed.
1-17
Explanation of Step 2: Encrypt the Password

The password is sent to the agents encrypted.
Explanation of Step 3: Validate Username and Password

Send the username/encrypted password to agent using PemnSendIdentity(). You should send your account to the agent as a rst task in the Open Callback; otherwise, the agent will not be able to authenticate you and the connection will drop.
Explanation of Step 4: Request an Operation To Be Done

Request one or more operations to be performed by the agent. You can request as many operations as you want without having to wait for the results. When the agent sends back the results, the handlers you dened for the operation will be executed.
Note
The API remembers only the last handler you dened for each operation.
Explanation of Step 5: Process the Answer Received from the PATROL Agent
The answer received from the agent is processed.
Explanation of Step 6: Disconnect from the PATROL Agent(s) Using PemnClose()

Use the PemnClose() function to disconnect from the agent.
1-18
PATROLAPI
Reference Manual
Sample Code for a Non-Blocking (Event Driven) Mode Program

/* * File: simple_nb.c *------------------------------------------------------------* Description: The hello World equivalent of the non-blocking API. * (see simple.c for the blocking mode example). * All this program does is to connect * to a PATROL agent then dump the application list. * * API routines used: * PemnClose, PemnOpen, PemnEncrypt, PemnLoop, PemnGetApplList, * PemnSendIdentity, PemnGetLastMessage *------------------------------------------------------------* Author : * Creation date : * * Last check-in date: $Date$ * * BMC Software, Inc. *------------------------------------------------------------*/ #include <time.h> #include <string.h> #include <stdlib.h> #ifdef _WIN32 # define strcasecmp_stricmp #endif #include <pemapi.h> static PemnCommHandle s_hComm;
static void _GetApplListHandler( PemnCommHandle hComm, char *pcList ) { /* Step 5 - process the list received from the agent then disconnect */ printf(Application List:\n %s\n, (pcList)?pcList:NIL); PemnClose(hComm); }
static void _OpenCallback( void *pTheObject,/* reserved for future use */ PemnClientData pClientData, PemnCommHandle hComm ) { char cEncryptedPwd[126+1]; char *pcPlainTextPwd = my_password;/* put here your password */ char *pcUser = user;/* put here your user name */ /* * * * * * Step 2: encrypt password This is the first thing you do in the Open callback. Password is sent encrypted to agents: encrypt the plain text password and store it in the buffer cEncryptedPwd */
1-19
if (! PemnEncrypt(cEncryptedPwd, 126, pcPlainTextPwd)){ printf(Could not encrypt password\n); exit(1); } /* Step 3: send the username/encrypted password to agent */ PemnSendIdentity(hComm, pcUser, cEncryptedPwd);
/* Step 4: do the work * Request the application list. Whenthe agent will * sends back the result _GetApplListHandler will be executed. */ if (PemnGetApplList(hComm, _GetApplListHandler)){ printf(request application List from the agent\n); } else { printf(Could not request application List from the agent\n); } } static void _CloseCallback( void* pTheObject,/* reserved for future use */ PemnClientData pClientData, PemnCommHandle hComm ) { printf(Connection closed\n); exit(0); } int main(int argc, char *argv[]) { char *pcHost = nanou;/* put here your host name */ int iPort = 1234; /* put here your port nb. */ /* Step 1: Request to Open a connection with agent * when the connection is established _OpenCallback will be executed * if the connection could not be established then _CloseCallback will be executed */ PemnOpen( iPort, pcHost,/* Port nb/ Host Node name */ _CloseCallback,/* Comm Close Callback */ (PemnClientData) NULL,/* NO Comm Close ClientData */ _OpenCallback,/* Comm Open Callback */ (PemnClientData) NULL,/* NO Comm Open Client Data */ & s_hComm ); if (s_hComm == NULL){ printf(Error -> %s\n, PemnGetLastMessage()); exit(1); } PemnLoop(); return (0); }
1-20
PATROLAPI
Reference Manual
2
2 2
Example Programs
This chapter provides example programs written with the PATROL API and tells you where to nd the electronic copies of the examples. You can use the examples as templates for your own programs. Overview. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2-2 Where to Find the Examples . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2-2 Sending and Receiving Events From One PATROL Agent . . . . . . . . 2-3 Sending and Receiving Events From Multiple PATROL Agents . . . . 2-9 Sending, Querying and Generating Event Reports in Blocking Mode . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2-16 Requesting Information in Blocking Mode . . . . . . . . . . . . . . . . . . . . 2-23 Dumping Events Using Blocking Mode. . . . . . . . . . . . . . . . . . . . . . . 2-31
Example Programs
2-1
Overview
The examples in this chapter are designed to provide a framework for you to follow when writing programs. Each example performs a common task. You can tailor each of these examples into a program that suits your specic needs.
Where to Find the Examples

The examples are shipped in electronic format with PATROL. You can nd the examples in the $PATROL_HOME/pemapi directory. The following table lists the tasks for which the example programs are written and provides the names of the example programs and the sections in this chapter where you can nd them. You must use an ANSI C compiler to compile these programs.
Dump events using blocking mode Send and Receive events from one PATROL Agent Send and Receive events from three (more than one) PATROL Agents (This example is very similar to send_receive except it connect with multiple agents instead of one.) Send, query and generate event reports in blocking mode. Use the blocking mode of the PATROL API to: request the agent for application list, instance list, parameter and variable list request the agent for object's attribute: application, instance list, parameter and variable list.
Program to Use
dump_events.c send_receive.c
Section to Go to
Dumping Events Using Blocking Mode on page 2-31 Sending and Receiving Events From One PATROL Agent on page 2-3 Sending and Receiving Events From Multiple PATROL Agents on page 2-9
multi_host.c
blocking_mode.c
Sending, Querying and Generating Event Reports in Blocking Mode on page 2-16 Requesting Information in Blocking Mode on page 2-23
patrol_obj.c
2-2
PATROLAPI
Reference Manual
Sending and Receiving Events From One PATROL Agent

The following example is a program that sends and receives events from one PATROL Agent. Use this example as a framework as you write your program. You can nd this example in electronic format in $PATROL_HOME/pemapi/send_receive.c. You must use an ANSI C compiler to compile this program.
/* * File: send_receive.c *------------------------------------------------------------* Description: - Send and Receive events from one PATROL agent * * keywords: event driven, mono-agent connections * * API routines used: * PemnReceive, PemnSend * PemnEncrypt, PemnSendIdentity * PemnRegisterUserMessageHandler, PemnGetLastMessage * PemnOpen, PemnClose * PemnLoop * PemrGetEid, PemrGetNode, PemrGetOrigin, PemrGetType * PemrGetStatus, PemrGetDesc *------------------------------------------------------------* Author : * Creation date : * * Last check-in date: $Date:$ * * BMC Software, Inc. *------------------------------------------------------------*/ #include <time.h> #include <string.h> #include <stdlib.h> #include <pemapi.h> #define PROGNAME send_receive
static static static static static static static static
int s_iPort = 0; int s_iMaxEventToReceive = 0; int s_iEventReceived = 0; char s_cHostName[512]; char s_cUserName[512]; char s_cPassword[512]; char s_cPortNb[56]; PemnCommHandle s_hComm =NULL;
/* forward declaration */ static void _SendEvent( PemnCommHandle hComm); static void _MyMessageHandler(char *pcMessageToDisplay, int iMsgType);
Example Programs
2-3
/* * Function: _ProcessInput *-----------------------------------------------------------------* Purpose : * Process -h -p -u -w mandatory input arguments *-----------------------------------------------------------------*/ static void _ProcessInput(int argc, char *argv[]) { int i; for (i = 1; i < argc; i++) { int cond = (argv[i][0] == - && argv[i][1]); if (!cond) continue; switch (argv[i][1]) { case h: case H:{ if(argv[i+1] == NULL){ _MyMessageHandler( Host name missing, PEMN_MSG_ERROR); exit(1); } strcpy(s_cHostName,argv[i+1]); break; } case P: case p:{ if(argv[i+1] == NULL){ _MyMessageHandler( Port nb. missing, PEMN_MSG_ERROR); exit(1); } strcpy(s_cPortNb,argv[i+1]); s_iPort = atoi( s_cPortNb); break; } case u: case U:{ if(argv[i+1] == NULL) { _MyMessageHandler( Username missing, PEMN_MSG_ERROR); exit(1); } strcpy(s_cUserName,argv[i+1]); break; } case w: case W:{ if(argv[i+1] == NULL) { _MyMessageHandler( Password missing, PEMN_MSG_ERROR); exit(1); } strcpy(s_cPassword,argv[i+1]); break; }
2-4
PATROLAPI
Reference Manual
} } if ( (strcmp(s_cHostName,)==0)){ _MyMessageHandler( Should provide agent host name, PEMN_MSG_ERROR); } if ( s_iPort <= 0){ _MyMessageHandler( Should provide agent port number, PEMN_MSG_ERROR); } } #define EVENT_TRACE_STR \ Event received (real-time) nb=%d id=%d node=%s origin=%s type=%d status=%d\n\ -->Description=%s\n\ -----------------------------------------------------------------\n /* * Function: _ReceiveEventHandler *-----------------------------------------------------------------* Purpose : * This handler is called when an event is received. *-----------------------------------------------------------------*/ static void _ReceiveEventHandler( PemnCommHandle hComm, PemrEventHandle oHEvent) { printf(EVENT_TRACE_STR, s_iEventReceived++, PemrGetEid (oHEvent), (PemrGetNode (oHEvent)) ? PemrGetNode(oHEvent) : NIL, (PemrGetOrigin(oHEvent)) ? PemrGetOrigin(oHEvent) : NIL, PemrGetType (oHEvent), PemrGetStatus(oHEvent), (PemrGetDesc (oHEvent)) ? PemrGetDesc(oHEvent) : NIL ); if (s_iEventReceived == s_iMaxEventToReceive) { printf(%d events received- close connection\n, s_iEventReceived ); PemnClose( hComm); } else { _SendEvent(hComm); } } /* * Function: _RegisterToReceiveEvents *-----------------------------------------------------------------* Purpose : * Register to receive any event. When an event is received * the handler _ReceiveEventHandler will be called *-----------------------------------------------------------------*/ static void _RegisterToReceiveEvents(void) { PemnReceive( , /* StartTime: any */ , /* EndTime: any */ O,A,C,E,D, /* Status: any */ I,S,E,W,A,R, /* Type: any */ , /* Severity: any */ , /* Node: any */ , /* Origin: any */ , /* Pattern: any */ , /* Range:any */
Example Programs
2-5
, /* EvClass any _ReceiveEventHandler ); }
*/
/* * Function: _SendEvent *-----------------------------------------------------------------* Purpose : * Trigger Event 41 in Standard Event Catalog. * Provide 1 argument to event description *-----------------------------------------------------------------*/ static void _SendEvent(PemnCommHandle hComm) { PemnSend( hComm, /* Communication Handle to agent*/ STD_EVENT_CATALOG,/* event catalog name */ 41, /* Event Class name */ MyOrigin, /* Event Origin */ NULL, NULL, /* No state change */ EV_TYPE_INFORMATION,/* event type */ 3, /* event Severity */ PEMN_ARG_STRING,MyArg,/* Argument to event description */ NULL); } /* * Function: _CommOpenCallback *-----------------------------------------------------------------* Purpose : * Called when the API framework open the connection *-----------------------------------------------------------------*/ static void _CommOpenCallback( void *pTheObject,/* reserved for future use */ void *pClientData, PemnCommHandle hComm ) { char cEncryptedPassword[126]; /* Set the static variable: maximum number of event to receive */ s_iMaxEventToReceive = (int) pClientData; /* Send the username/encrypted password to agent */ if ( ! PemnEncrypt(cEncryptedPassword, 126, s_cPassword)){ printf(Could not encrypt password\n); exit(1); } PemnSendIdentity(hComm, s_cUserName, cEncryptedPassword); /* before we send our first event. Register the filter * which defines the events we want to receive */ _RegisterToReceiveEvents(); _SendEvent(hComm); }
2-6
PATROLAPI
Reference Manual
/* * Function: _CommCloseCallback *-----------------------------------------------------------------* Purpose : * Called when the API framework disconnect or after * I call PemnClose() *-----------------------------------------------------------------*/ static void _CommCloseCallback( void *pTheObject,/* reserved for future use */ void *pClientData,/* not used */ PemnCommHandle hComm ) { printf(Close connection\n); printf(Exiting %s\n, PROGNAME); exit(0); }
/* * Function: _MyMessageHandler *-----------------------------------------------------------------* Purpose : * My error/info/warning display routine *-----------------------------------------------------------------*/ static void _MyMessageHandler(char *pcMessageToDisplay, int iMsgType) { switch(iMsgType){ case PEMN_MSG_WARN: printf(WARNING: %s\n, pcMessageToDisplay); break; case PEMN_MSG_ERROR: printf(ERROR: %s\n, pcMessageToDisplay); break; default: printf(INFORMATION: %s\n, pcMessageToDisplay); } }
#define SYNTAX_STR \ Syntax:\n%s -h<hostname> -p<port-nb> -u<username> -w<password>\n \ Username /password is needed to log to the PATROL agent\n\n
Example Programs
2-7
/* * Function: main *-----------------------------------------------------------------* Purpose : * Registers message handler * Try to open connection to agent *-----------------------------------------------------------------*/ int main(int argc, char *argv[]) { /* display syntax */ printf(SYNTAX_STR, PROGNAME); /* Process -h -p -u -w mandatory options */ _ProcessInput(argc, argv); /* Register my own message handler to be called * by the API framework when error, information or warning * is displayed */ PemnRegisterUserMessageHandler(_MyMessageHandler); /* Open the connection and register the two callbacks: * _CommCloseCallback - called when disconnect is detected * _CommOpenCallback - called when connection complete * To the open callback we pass the number of events to send. */ PemnOpen( s_iPort, s_cHostName,/* Port nb/Agent Node name */ _CommCloseCallback,/* Comm. Close Callback */ (PemnClientData) NULL, /* No Close ClientData */ _CommOpenCallback,/* Comm. Open Callback */ (PemnClientData) 10,/* Open Client Data: 10 events */ & s_hComm/* Where to store the comm. handle */ ); /* NOTE: * s_hComm should be a static varaible in your program. * The API framework stores internally the address * of s_hComm and set it to NULL when disconnecting from the * the agent. * */ if (s_hComm == NULL) { char cMsg[256]; sprintf(cMsg, PemnOpen: %s\n, PemnGetLastMessage() ); _MyMessageHandler(cMsg, PEMN_MSG_ERROR); exit(0); } /* Enter the main loop (e.g select) */ PemnLoop(); return (0); }
2-8
PATROLAPI
Reference Manual
Sending and Receiving Events From Multiple PATROL Agents

The following example is a program that sends and receives events from multiple PATROL Agents. Use this example as a framework as you write your program. You can nd this example in electronic format in the le $PATROL_HOME/pemapi/multi_host.c. You must use an ANSI C compiler to compile this program.
/* * File: multi_host.c *------------------------------------------------------------* Description: - Send and Receive events from 3 PATROL agents * This example is very similar to send_receive * except it connect with 3 agents instead of one. * keywords: event driven, multi-agent connections * * API routines used: * PemnReceive, PemnSend * PemnEncrypt, PemnSendIdentity * PemnRegisterUserMessageHandler, PemnGetLastMessage * PemnOpen, PemnClose * PemnLoop * PemrGetEid, PemrGetNode, PemrGetOrigin, PemrGetType * PemrGetStatus, PemrGetDesc * *------------------------------------------------------------* Author : * Creation date : * * Last check-in date: $Date:$ * * BMC Software, Inc. *------------------------------------------------------------*/ #include <time.h> #include <string.h> #include <stdlib.h> #include <pemapi.h> typedef struct _HostInfo { char cHostName[512]; char cUserName[126]; char cPassword[126]; int iPortNb; int iEventReceived; int iMaxEventToReceive; int iNormalExit; int iMaxRetry; int iRetry; PemnCommHandle hComm; } HostInfo, *HostInfoPt; #define MAX_HOSTS 3 static static static HostInfo hosts[MAX_HOSTS]; char s_cUserName[512]; char s_cPassword[512];
Example Programs
2-9
/* forward declaration */ static void _SendEvent( PemnCommHandle hComm); static void _MyMessageHandler(char *pcMessageToDisplay, int iMsgType); /* * Function: _FindHost *-----------------------------------------------------------------* Purpose : * Given a communication handle find the host description *-----------------------------------------------------------------*/ static HostInfoPt _FindHost(PemnCommHandle hComm) { int i; for (i=0; i <MAX_HOSTS; i++){ if (hosts[i].hComm == hComm) return & hosts[i]; } return NULL; } /* * Function: _InitPatrolAgentDetails *-----------------------------------------------------------------* Purpose : * Encrypt the common password and store all agent details * in the sattic array hosts[]. * In real life: * The agent details will be read from a configuration file. * Also every agent may have differnet user name/password *-----------------------------------------------------------------*/ static void _InitPatrolAgentDetails(void) { int i; char cEncryptedPassword[126]; /* Encrypt password */ if ( ! PemnEncrypt(cEncryptedPassword, 126, s_cPassword)){ printf(Could not encrypt password\n); exit(1); } /* common details */ for (i=0; i < MAX_HOSTS; i++){ strcpy(hosts[i].cUserName, s_cUserName); strcpy(hosts[i].cPassword, cEncryptedPassword); hosts[i].iEventReceived = 0; hosts[i].iMaxEventToReceive = 10; hosts[i].iNormalExit = 0; hosts[i].iMaxRetry = 3; hosts[i].iRetry = 0; } /* specific details to each hosts */ strcpy(hosts[0].cHostName,nanou); hosts[0].iPortNb = 1234; strcpy(hosts[1].cHostName,belize); hosts[1].iPortNb = 5678; strcpy(hosts[2].cHostName,nanou); hosts[2].iPortNb =5678; }
2-10
PATROLAPI
Reference Manual
/* * Function: _SendEvent *-----------------------------------------------------------------* Purpose : * Trigger Event 41 in Standard Event Catalog. * Provide 1 argument to event description *-----------------------------------------------------------------*/ static void _SendEvent(PemnCommHandle hComm) { PemnSend( hComm, /* Communication Handle to agent*/ STD_EVENT_CATALOG,/* event catalog name */ 41, /* Event Class name */ MyOrigin, /* Event Origin */ NULL, NULL, /* No state change */ EV_TYPE_INFORMATION,/* event type */ 3, /* event Severity */ PEMN_ARG_STRING,MyArg,/* Argument to event description */ NULL); }
#define EVENT_TRACE_STR \ Event received (real-time) from agent %s %d\n\ nb=%d id=%d node=%s origin=%s type=%d status=%d\n\ -->Description=%s\n\ -----------------------------------------------------------------\n /* * Function: _ReceiveEventHandler *-----------------------------------------------------------------* Purpose : * This handler is called when an event is received. *-----------------------------------------------------------------*/ static void _ReceiveEventHandler( PemnCommHandle hComm, PemrEventHandle oHEvent) { HostInfoPt pHost= _FindHost(hComm); if (pHost == NULL){ _MyMessageHandler( _ReceiveEventHandler: Event received from unknown host, PEMN_MSG_ERROR); exit(1); } printf(EVENT_TRACE_STR, pHost->cHostName, pHost->iPortNb, (pHost->iEventReceived)++, PemrGetEid (oHEvent), (PemrGetNode (oHEvent)) ? PemrGetNode(oHEvent) : NIL, (PemrGetOrigin(oHEvent)) ? PemrGetOrigin(oHEvent) : NIL, PemrGetType (oHEvent), PemrGetStatus(oHEvent), (PemrGetDesc (oHEvent)) ? PemrGetDesc(oHEvent) : NIL ); if (pHost->iEventReceived > pHost->iMaxEventToReceive) { printf(%d events received- close connection\n, pHost->iEventReceived );
Example Programs
2-11
/* We want to exit normaly*/ pHost->iNormalExit = 1; PemnClose( hComm); } else { _SendEvent(hComm); } }
/* * Function: _RegisterToReceiveEvents *-----------------------------------------------------------------* Purpose : * Register to receive any event. When an event is received * the handler _ReceiveEventHandler will be called *-----------------------------------------------------------------*/ static void _RegisterToReceiveEvents(void) { PemnReceive( , /* StartTime: any */ , /* EndTime: any */ O,A,C,E,D, /* Status: any */ I,S,E,W,A,R, /* Type: any */ , /* Severity: any */ , /* Node: any */ , /* Origin: any */ , /* Pattern: any */ , /* Range:any */ , /* EvClass any */ _ReceiveEventHandler ); }
/* * Function: _CommOpenCallback *-----------------------------------------------------------------* Purpose : * Called when the API framework open the connection *-----------------------------------------------------------------*/ static void _CommOpenCallback( void *pTheObject,/* reserved for future use */ void *pClientData, PemnCommHandle hComm ) { HostInfoPt pHostInfo = (HostInfoPt) pClientData; PemnSendIdentity(hComm, pHostInfo->cUserName, pHostInfo->cPassword); _SendEvent(hComm); }
2-12
PATROLAPI
Reference Manual
/* * Function: _CommCloseCallback *-----------------------------------------------------------------* Purpose : * Called when the API framework disconnects or after * I call PemnClose() *-----------------------------------------------------------------*/ static void _CommCloseCallback( void *pTheObject,/* reserved for future use */ void *pClientData, PemnCommHandle hComm ) { HostInfoPt pHostInfo = (HostInfoPt) pClientData; char *pcMyHostName = pHostInfo->cHostName; int iMyPortNb = pHostInfo->iPortNb; if (pHostInfo->iNormalExit){ printf(Normal exit from %s %d\n,pcMyHostName,iMyPortNb); return; } if (pHostInfo->iRetry >= pHostInfo->iMaxRetry){ printf(Max retry reached for %s %d\n,pcMyHostName, iMyPortNb); return; } (pHostInfo->iRetry)++; /* hMyComm should be equal hComm */ printf(Detect a disconnect on host %s port %d\n, pcMyHostName, iMyPortNb); printf( Attempt # %d to re-establish the connection\n, (pHostInfo->iRetry)); PemnOpen( iMyPortNb, pcMyHostName,/* Port nb/ Host Node name */ _CommCloseCallback,/* Comm Close Callback */ (void*) pHostInfo, /* Comm Close ClientData */ _CommOpenCallback,/* Comm Open Callback */ (void*) pHostInfo,/* Comm Open Client Data */ & pHostInfo->hComm ); }
Example Programs
2-13
/* * Function: _ProcessInput *-----------------------------------------------------------------* Purpose : * Process -u -w: * common username/password to all agents we want to connect *-----------------------------------------------------------------*/ static void _ProcessInput(int argc, char *argv[]) { int i; for (i = 1; i < argc; i++) { int cond = (argv[i][0] == - && argv[i][1]); if (!cond) continue; switch (argv[i][1]) { case u: case U:{ if(argv[i+1] == NULL){ _MyMessageHandler( Username missing, PEMN_MSG_ERROR); exit(1); } strcpy(s_cUserName,argv[i+1]); break; } case w: case W:{ if(argv[i+1] == NULL){ _MyMessageHandler( Username missing, PEMN_MSG_ERROR); exit(1); } strcpy(s_cPassword,argv[i+1]); break; } } } }
2-14
PATROLAPI
Reference Manual
#define SYNTAX_STR \ Syntax:\n%s -u<username> -w<password>\n \ Username /password is needed to log to the PATROL agent\n\n #define PROGNAME multi_host /* * Function: main *-----------------------------------------------------------------* Purpose : * Registers message handler * Build agent details and store them in hosts[] * Try to open connection to agents *-----------------------------------------------------------------*/ int main(int argc, char *argv[]) { int i; /* display syntax */ printf(SYNTAX_STR, PROGNAME); /* Process -u -w: * common username/password to all agents we want to connect */ _ProcessInput(argc, argv); /* Register my own message handler to be called * by the API framework when error, information or warning * is displayed */ PemnRegisterUserMessageHandler(_MyMessageHandler); /* Build the hosts array from agent details */ _InitPatrolAgentDetails(); for (i=0; i < MAX_HOSTS; i++){ PemnOpen( hosts[i].iPortNb, hosts[i].cHostName, /* Port nb/ Host Node name */ _CommCloseCallback, /* Comm Close Callback */ (PemnClientData)&hosts[i], /* Comm Close ClientData _CommOpenCallback, /* Comm Open Callback */ (PemnClientData)&hosts[i], /* Comm Open Client Data & hosts[i].hComm ); if (hosts[i].hComm == NULL) { char cMsg[256]; sprintf(cMsg, Agent (%s,%d): %s\n, hosts[i].cHostName, hosts[i].iPortNb, PemnGetLastMessage() ); _MyMessageHandler(cMsg, PEMN_MSG_ERROR); } } /* Register to receive events for all agents*/ _RegisterToReceiveEvents(); /* Enter the main loop (e.g select) */ PemnLoop(); return (0); }
*/ */
Example Programs
2-15
Sending, Querying and Generating Event Reports in Blocking Mode

The following example is a program that illustrates sending, querying, and generating event reports in blocking mode. Use this example as a framework as you write your program. You can nd this example in electronic format in $PATROL_HOME/pemapi/blocking_mode.c. You must use an ANSI C compiler to compile this program.
/* * File: blocking_mode.c *------------------------------------------------------------* Description: - Illustrate the blocking mode API: * ->send, query and generate event reports. * * keywords: blocking mode, mono-agent connections * * API routines used: * PemnBOpen, PemnBClose * PemnBEventReport, PemnBSend, PemnBEventQuery, * PemnRegisterUserMessageHandler * PemnEncrypt *------------------------------------------------------------* Author : * Creation date : * * Last check-in date: $Date:$ * * BMC Software, Inc. *------------------------------------------------------------*/ #include <time.h> #include <string.h> #include <stdlib.h> #include <pemapi.h> #define PROGNAME blocking_mode static static static static static static static int s_iPort=0; int s_iIteration = 10; char s_cHostName[512]; char s_cUserName[512]; char s_cPassword[512]; char s_cPortNb[56]; PemnCommHandle s_hComm =NULL;
2-16
PATROLAPI
Reference Manual
/* * Function: _ProcessInput *-----------------------------------------------------------------* Purpose : * Process -h -p -u -w mandatory input arguments *-----------------------------------------------------------------*/ static void _ProcessInput(int argc, char *argv[]) { int i; for (i = 1; i < argc; i++) { int cond = (argv[i][0] == - && argv[i][1]); if (!cond) continue; switch (argv[i][1]) { case h: case H:{ if(argv[i+1] == NULL){ _MyMessageHandler( Host name missing, PEMN_MSG_ERROR); exit(1); } strcpy(s_cHostName,argv[i+1]); break; } case P: case p:{ if(argv[i+1] == NULL){ _MyMessageHandler( Port nb. missing, PEMN_MSG_ERROR); exit(1); } strcpy(s_cPortNb,argv[i+1]); s_iPort = atoi( s_cPortNb); break; } case I: case i:{
Example Programs
2-17
if(argv[i+1] != NULL){ s_iIteration = atoi( argv[i+1]); } if (s_iIteration <= 0) s_iIteration =10; break; } case u: case U:{ if(argv[i+1] == NULL) { _MyMessageHandler( Username missing, PEMN_MSG_ERROR); exit(1); } strcpy(s_cUserName,argv[i+1]); break; } case w: case W:{ if(argv[i+1] == NULL) { _MyMessageHandler( Password missing, PEMN_MSG_ERROR); exit(1); } strcpy(s_cPassword,argv[i+1]); break; } } } if ( (strcmp(s_cHostName,)==0)){ _MyMessageHandler( Should provide agent host name, PEMN_MSG_ERROR); } if ( s_iPort <= 0){ _MyMessageHandler( Should provide agent port number, PEMN_MSG_ERROR); } } #define SYNTAX_STR \ Syntax:\n\ %s -h<hostname> -p<port-nb> -u<username> -w<password> [-i<iteration\n\ Username/password is needed to log to the PATROL agent\n\n
/* * Function: _BlockingSend *-----------------------------------------------------------------* Purpose : * Send an event and block a maximum 1000 millisec * until the agent acknowldge receiving it. * *-----------------------------------------------------------------*/ static void _BlockingSend(void) { char *pcSourceId; printf(>Send started----------------------------------------------\n); pcSourceId =PemnBSend( s_hComm, 1000, /* Max Waiting time in millisec */ STD_EVENT_CATALOG, /* event catalog name */ 41, /* Event Class name */ MyOrigin, /* Event Origin*/
2-18
PATROLAPI
Reference Manual
NULL, NULL, /* No state change */ EV_TYPE_INFORMATION, /* event type */ 3, /* event Severity */ PEMN_ARG_STRING,MyArg,/* Argument to event description*/ NULL); printf(>Send done %s\n, pcSourceId); } static char* Id Status Type Severity Time Node Origin Catalog Class Args Description g_DEFAULT_EVENT_FORMAT = : %{EV_ID}\n : %{EV_STATUS}\n : %{EV_TYPE}\n : %{EV_NSEVERITY}\n : %{EV_TIME}\n : %{EV_NODE}\n : %{EV_ORIGIN}\n : %{EV_CATALOG}\n : %{EV_CLASS_NAME}\n : %{EV_ARGS}\n : %{EV_DESC}\n;
/* * Function: _BlockingQuery *-----------------------------------------------------------------* Purpose : * Query the event repository and use default waiting time * (USE_DEFAULT_TIMEOUT) to block for results. * *-----------------------------------------------------------------*/ static void _BlockingQuery(void) { char *pc; printf(>Query started --------------------------------------------\n); pc = PemnBEventQuery(s_hComm, 12, /* Max count in query */ \n\n, /* events seperator */ g_DEFAULT_EVENT_FORMAT,/* event print format */ , /* StartTime: any */ , /* EndTime: any */ O,A,C,E,D, /* Status: any */ W,A, /* Type: only alarm and warning */ 1, /* Severity: 1 or higher */ , /* Node: any */ , /* Origin: any */ , /* Pattern: any */ , /* Range:any */ , /* EvClass any */ USE_DEFAULT_TIMEOUT ); printf(>Query done %s\n, pc); }
Example Programs
2-19
/* * Function: _BlockingReport *-----------------------------------------------------------------* Purpose : * Request an event repository report and * wait a maximum of 3000 milliseconds for * results. * *-----------------------------------------------------------------*/ static void _BlockingReport(void) { char *pc; printf(>Report started -------------------------------------------\n); pc = PemnBEventReport(s_hComm, , /* Reserved for future use */ , /* StartTime: any */ , /* EndTime: any */ O,A,C,E,D, /* Status: any */ W,A,I, /* Type: only alarm, warning and info */ 1, /* Severity: 1 or higher */ , /* Node: any */ , /* Origin: any */ , /* Pattern: any */ , /* Range:any */ , /* EvClass any */ 3000 /* 3 seconds */ ); printf(>Report done %s\n, pc); } /* * Function: _MyDisconnectCallback *-----------------------------------------------------------------* Purpose : * Called if agent disconnect happens in * in the middle of PemnBOpen. * *-----------------------------------------------------------------*/ static void _MyDisconnectCallback( PemnCommHandle hComm, PemnClientData pClientData ) { printf(_MyDisconnectCallback called: s_hComm is now invalid\n); }
2-20
PATROLAPI
Reference Manual
/* * Function: _BlockingModeExec *-----------------------------------------------------------------* Purpose : * Open connection und block until success * Send event until it is received by agent. * Start a query and block until results arrive * Ask for a event report and block for results. * *-----------------------------------------------------------------*/ static void _BlockingModeExec(char * pcEncryptedPassword) { char *pcOpenResult; pcOpenResult = PemnBOpen(& s_hComm, s_cHostName,s_iPort,/* agent details */ s_cUserName,/* account to log in the agent: * user name and encrypted password*/ pcEncryptedPassword, 5, /* Loggin retry Counter */ _MyDisconnectCallback, /* Called if agent disconnect happens in * in the middle of PemnBOpen */ NULL ); if (strcmp(PEMA_OK, pcOpenResult)==0) { printf(PemnBOpen done: %s\n, pcOpenResult); if (s_hComm) _BlockingSend(); if (s_hComm) _BlockingQuery(); if (s_hComm) _BlockingReport(); if (s_hComm) { PemnBClose(s_hComm); s_hComm = NULL; printf(PemnBClose done\n\n); } } else { printf(PemnBOpen failed %s\n, pcOpenResult); } }
Example Programs
2-21
/* * Function: main *-----------------------------------------------------------------* Purpose : * Registers message handler. * Encrypt password. * execute <iteration> time the blocking mode opeartions *-----------------------------------------------------------------*/ int main(int argc, char *argv[]) { int i=0; char cEncryptedPassword[126+1]; /* display syntax */ printf(SYNTAX_STR, PROGNAME); /* Process -h -p -u -w mandatory options */ _ProcessInput(argc, argv); /* Register my own message handler to be called * by the API framework when error, information or warning * is displayed */ PemnRegisterUserMessageHandler(_MyMessageHandler); /* passwords are sent encrypted to agents */ if ( ! PemnEncrypt(cEncryptedPassword, 126, s_cPassword)){ printf(Could not encrypt password\n); exit(1); } while( (++i) <= s_iIteration){ _BlockingModeExec(cEncryptedPassword); } return (0); }
2-22
PATROLAPI
Reference Manual
Requesting Information in Blocking Mode

The following example is a program that illustrates using blocking mode to perform these tasks: Request the agent for application list, instance list, parameter and variable list Request the agent for an object's attribute: application, instance list, parameter and variable list
Use this example as a framework as you write your program. You can nd this example in electronic format in $PATROL_HOME/pemapi/patrol_obj.c. You must use an ANSI C compiler to compile this program.
/* * File: patrol_obj.c *------------------------------------------------------------* Description: Illustrate the blocking mode API: * ->request the agent for application list, instance list, * parameter and variable list. * ->request the agent for objects attribute: * application , instance list, parameter and variable list. * -> Execute remote PSL function. * NOTE: * The agent is assumed to run a UNIX KM. Modify * the program to access the list of objects in your KM. * * keywords: blocking mode, mono-agent connections * * API routines used: * PemnBOpen, PemnBClose * PemnBGetApplList, PemnBGetParamList, PemnBGetInstList, PemnBGetVarList * PemnBGetApplObj, PemnBGetParamObj, PemnBGetInstObj, PemnBGetVarObj * PemnRegisterUserMessageHandler * PemnEncrypt * PemnBPslExec *------------------------------------------------------------* Author : * Creation date : * * Last check-in date: $Date:$ * * BMC Software, Inc. *------------------------------------------------------------*/ #include <time.h> #include <string.h> #include <stdlib.h> #include <pemapi.h> #define PROGNAME patrol_obj
Example Programs
2-23
static static static static static static static
int s_iPort=0; int s_iIteration = 10; char s_cHostName[512]; char s_cUserName[512]; char s_cPassword[512]; char s_cPortNb[56]; PemnCommHandle s_hComm =NULL;
/* * Function: _ProcessInput *-----------------------------------------------------------------* Purpose : * Process -h -p -u -w mandatory input arguments *-----------------------------------------------------------------*/ static void _ProcessInput(int argc, char *argv[]) { int i; for (i = 1; i < argc; i++) { int cond = (argv[i][0] == - && argv[i][1]); if (!cond) continue; switch (argv[i][1]) { case h: case H:{ if(argv[i+1] == NULL){ _MyMessageHandler( Host name missing, PEMN_MSG_ERROR); exit(1); } strcpy(s_cHostName,argv[i+1]); break; } case P: case p:{ if(argv[i+1] == NULL){ _MyMessageHandler( Port nb. missing, PEMN_MSG_ERROR);
2-24
PATROLAPI
Reference Manual
exit(1); } strcpy(s_cPortNb,argv[i+1]); s_iPort = atoi( s_cPortNb); break; } case I: case i:{ if(argv[i+1] != NULL){ s_iIteration = atoi( argv[i+1]); } if (s_iIteration <= 0) s_iIteration =10; break; } case u: case U:{ if(argv[i+1] == NULL) { _MyMessageHandler( Username missing, PEMN_MSG_ERROR); exit(1); } strcpy(s_cUserName,argv[i+1]); break; } case w: case W:{ if(argv[i+1] == NULL) { _MyMessageHandler( Password missing, PEMN_MSG_ERROR); exit(1); } strcpy(s_cPassword,argv[i+1]); break; } } } if ( (strcmp(s_cHostName,)==0)){ _MyMessageHandler( Should provide agent host name, PEMN_MSG_ERROR); } if ( s_iPort <= 0){ _MyMessageHandler( Should provide agent port number, PEMN_MSG_ERROR); } } #define SYNTAX_STR \ Syntax:\n\ %s -h<hostname> -p<port-nb> -u<username> -w<password> [-i<iteration\n\ Username/password is needed to log to the PATROL agent\n\n
static int _OK(PemnCommHandle hComm, char *pcMsg) { if (! hComm) { printf(Connection is broken return from: %s\n, pcMsg); return 0; } return 1; }
Example Programs
2-25
/* * Function: _BlockingGetList *-----------------------------------------------------------------* Purpose : * Request the list of applications, instances, parameters and variables * *-----------------------------------------------------------------*/ static void _BlockingGetList(void) { char *pc; printf(>Get Appl. List started -----------------------------------\n); pc = PemnBGetApplList(s_hComm, USE_DEFAULT_TIMEOUT); printf(>Get Appl. List done %s\n, pc); if (! _OK(s_hComm,_BlockingGetList 1)) return; printf(>Get Inst. List started -----------------------------------\n); pc = PemnBGetInstList(s_hComm, FILESYSTEM, USE_DEFAULT_TIMEOUT ); printf(>Get Inst. List done %s\n, pc); if (! _OK(s_hComm,_BlockingGetList 2)) return; printf(>Get Param. List started -------------------------- -------\n); pc = PemnBGetParamList(s_hComm, FILESYSTEM, usr, USE_DEFAULT_TIMEOUT ); printf(>Get Param. List done %s\n, pc); if (! _OK(s_hComm,_BlockingGetList 3)) return; printf(>Get Var. List started -------------------------- -------\n); pc = PemnBGetVarList(s_hComm, /,, USE_DEFAULT_TIMEOUT ); printf(>Get Var. List done %s\n, pc); }
/* * Function: _BlockingGetObj *-----------------------------------------------------------------* Purpose : * Request the objects attributes fo an application, an * instance, a parameter and a variable * *-----------------------------------------------------------------*/ static void _BlockingGetObj(void) { PemnApplObjHandle hApplObj; PemnInstObjHandle hInstObj; PemnParamObjHandle hParamObj; PemnVarObjHandle hVarObj; int i; PemnApplAttrArray *pApplAttr; PemnInstAttrArray *pInstAttr; PemnParamAttrArray *pParamAttr;
2-26
PATROLAPI
Reference Manual
printf(>Get Appl. Obj started ----------------------------------------\n); hApplObj = PemnBGetApplObj(s_hComm, FILESYSTEM, USE_DEFAULT_TIMEOUT ); pApplAttr = PemnGetApplObjAttributes(hApplObj); if (pApplAttr) { for (i=0; i < (int) PEMN_APPL_MAX_ATTR; i++){ printf(attribute[%d]=<%s>\n, i, ((*pApplAttr)[i])?(*pApplAttr)[i]:NIL); } } else { printf(Could not read objects attributes\n); } printf(>Get Appl. Obj done\n); if (! _OK(s_hComm,_BlockingGetObj 1)) return; printf(>Get Inst. Obj started ----------------------------------------\n); hInstObj = PemnBGetInstObj(s_hComm, FILESYSTEM, usr, USE_DEFAULT_TIMEOUT ); pInstAttr = PemnGetInstObjAttributes(hInstObj); if (pInstAttr) { for (i=0; i < (int) PEMN_INST_MAX_ATTR; i++){ printf(attribute[%d]=<%s>\n, i, ((*pInstAttr)[i])?(*pInstAttr)[i]:NIL); } } else { printf(Could not read objects attributes\n); } printf(>Get Inst. Obj done\n--------------------------------------------); if (! _OK(s_hComm,_BlockingGetObj 2)) return; printf(>Get Param. Obj started ---------------------------------------\n); hParamObj = PemnBGetParamObj(s_hComm, FILESYSTEM, usr, FSCapacity, USE_DEFAULT_TIMEOUT ); pParamAttr = PemnGetParamObjAttributes(hParamObj); if (pParamAttr) { for (i=0; i < (int) PEMN_PARAM_MAX_ATTR; i++){ printf(attribute[%d]=<%s>\n, i, ((*pParamAttr)[i])?(*pParamAttr)[i]:NIL); } } else { printf(Could not read objects attributes\n); } printf(>Get Param. Obj done-------------------------------------------\n); if (! _OK(s_hComm,_BlockingGetObj 3)) return; printf(>Get Var. Obj started ---------------------------------------\n); hVarObj = PemnBGetVarObj(s_hComm, /sysBootTime, USE_DEFAULT_TIMEOUT );
Example Programs
2-27
printf(>Get var. Obj done: %s\n, hVarObj); if (! _OK(s_hComm,_BlockingGetObj 1)) return; printf(>Get Var. Obj started ---------------------------------------\n); hVarObj = PemnBGetVarObj(s_hComm, /serverLogPath, USE_DEFAULT_TIMEOUT ); printf(>Get var. Obj done: %s\n, hVarObj); }
static {
void _BlockingExecPsl(PemnCommHandle hComm) char *pcResult; printf(>Exec. PSL started --------------------------------------------\n); pcResult = PemnBPslExec(hComm, USE_DEFAULT_TIMEOUT, 1, get_vars(\/\); ); printf(> Exec. PSL cmd %s\n, (pcResult) ? pcResult : NIL ); if (! _OK(s_hComm,_BlockingExecPsl)) return; printf(>Exec. OS cmd started -----------------------------------------\n); pcResult = PemnBPslExec(hComm, USE_DEFAULT_TIMEOUT, 1, system(\cat /tmp/blago\); ); printf(> Exec. OS cmd %s\n, (pcResult) ? pcResult : NIL );
} /* * Function: _MyDisconnectCallback *-----------------------------------------------------------------* Purpose : * Called if agent disconnect happens in * in the middle of PemnBOpen. * *-----------------------------------------------------------------*/ static void _MyDisconnectCallback( PemnCommHandle hComm, PemnClientData pClientData ) { printf(_MyDisconnectCallback called: s_hComm is now invalid\n); }
2-28
PATROLAPI
Reference Manual
/* * Function: _BlockingModeExec *-----------------------------------------------------------------* Purpose : * Open connection und block until success * Send event until it is received by agent. * Start a query and block until results arrive * Ask for a event report and block for results. * *-----------------------------------------------------------------*/ static void _BlockingModeExec(char * pcEncryptedPassword) { char *pcOpenResult; pcOpenResult = PemnBOpen(& s_hComm, s_cHostName,s_iPort,/* agent details */ s_cUserName,/* account to log in the agent: * user name and encrypted password*/ pcEncryptedPassword, 5, /* Loggin retry Counter */ _MyDisconnectCallback, /* Called if agent disconnect happens in * in the middle of PemnBOpen */ NULL ); if (strcmp(PEMA_OK, pcOpenResult)==0) { printf(PemnBOpen done: %s\n, pcOpenResult); if (s_hComm) _BlockingGetList(); if (s_hComm) _BlockingGetObj(); if (s_hComm) _BlockingExecPsl(s_hComm); if (s_hComm) { PemnBClose(s_hComm); s_hComm = NULL; printf(PemnBClose done\n\n); } } else { printf(PemnBOpen failed %s\n, pcOpenResult); } }
Example Programs
2-29
/* * Function: main *-----------------------------------------------------------------* Purpose : * Registers message handler. * Encrypt password. * execute <iteration> time the blocking mode opeartions *-----------------------------------------------------------------*/ int main(int argc, char *argv[]) { int i=0; char cEncryptedPassword[126+1]; /* The first thing we do is to init the PATROL API explicitly since we want to return large amount of data in PemnBExecPsl(). In this release: the maximum result returned by PemnBExecPsl() is 32000 bytes. If PemnInit() is not called the default for the API is 10K. */ PemnInit(32000); * * * * /* display syntax */ printf(SYNTAX_STR, PROGNAME); /* Process -h -p -u -w mandatory options */ _ProcessInput(argc, argv); /* Register my own message handler to be called * by the API framework when error, information or warning * is displayed */ PemnRegisterUserMessageHandler(_MyMessageHandler); /* passwords are sent encrypted to agents */ if ( ! PemnEncrypt(cEncryptedPassword, 126, s_cPassword)){ printf(Could not encrypt password\n); exit(1); } while( (++i) <= s_iIteration){ _BlockingModeExec(cEncryptedPassword); } return (0); }
2-30
PATROLAPI
Reference Manual
Dumping Events Using Blocking Mode

The following example is a program that dumps events using blocking mode. Use this example as a framework as you write your program. You can nd this example in electronic format in $PATROL_HOME/pemapi/dump_events.c. You must use an ANSI C compiler to compile this program.
/* * File: dump_events.c *------------------------------------------------------------* Description: - Use blocking mode operations to dump events * keywords: blocking mode, mono-agent connections * * API routines used: * PemnBOpen, PemnBClose * PemnBEventArchive * PemnRegisterUserMessageHandler * PemnEncrypt *------------------------------------------------------------* Author : * Creation date : * * Last check-in date: $Date:$ * * BMC Software, Inc. *------------------------------------------------------------*/ #include <time.h> #include <string.h> #include <stdlib.h> #include <pemapi.h> #define PROGNAME dump_events static static static static static static static int s_iPort=0; char s_cHostName[512]; char s_cUserName[512]; char s_cPassword[512]; char s_cDestination[512]; char s_cPortNb[56]; PemnCommHandle s_hComm =NULL;
/* * Function: _MyMessageHandler *-----------------------------------------------------------------* Purpose : * My error/info/warning display routine *-----------------------------------------------------------------*/ static void _MyMessageHandler(char *pcMessageToDisplay, int iMsgType) { switch(iMsgType){ case PEMN_MSG_WARN: printf(WARNING: %s\n, pcMessageToDisplay); break; case PEMN_MSG_ERROR: printf(ERROR: %s\n, pcMessageToDisplay); break; default: printf(INFORMATION: %s\n, pcMessageToDisplay);
Example Programs
2-31
} }
/* * Function: _ProcessInput *-----------------------------------------------------------------* Purpose : * Process -h -p -u -w mandatory input arguments * Process -d optional destination *-----------------------------------------------------------------*/ static void _ProcessInput(int argc, char *argv[]) { int i; strcpy(s_cDestination,/tmp/PEM.txt); for (i = 1; i < argc; i++) { int cond = (argv[i][0] == - && argv[i][1]); if (!cond) continue; switch (argv[i][1]) { case d: case D:{ if(argv[i+1] == NULL){ _MyMessageHandler( Destination file missing, PEMN_MSG_ERROR); exit(1); } strcpy(s_cDestination,argv[i+1]); break; } case h: case H:{ if(argv[i+1] == NULL){ _MyMessageHandler( Host name missing, PEMN_MSG_ERROR); exit(1); } strcpy(s_cHostName,argv[i+1]); break; } case P: case p:{ if(argv[i+1] == NULL){ _MyMessageHandler( Port nb. missing, PEMN_MSG_ERROR); exit(1); } strcpy(s_cPortNb,argv[i+1]); s_iPort = atoi( s_cPortNb); break; } case u: case U:{ if(argv[i+1] == NULL) { _MyMessageHandler( Username missing, PEMN_MSG_ERROR); exit(1); } strcpy(s_cUserName,argv[i+1]);
2-32
PATROLAPI
Reference Manual
break; } case w: case W:{ if(argv[i+1] == NULL) { _MyMessageHandler( Password missing, PEMN_MSG_ERROR); exit(1); } strcpy(s_cPassword,argv[i+1]); break; } } } if ( (strcmp(s_cHostName,)==0)){ _MyMessageHandler( Should provide agent host name, PEMN_MSG_ERROR); } if ( s_iPort <= 0){ _MyMessageHandler( Should provide agent port number, PEMN_MSG_ERROR); } } #define SYNTAX_STR \ Syntax:\n\ %s -h<hostname> -p<port-nb> -u<username> -w<password> [-d <destination>]\n\ Username/password is needed to log to the PATROL agent\n\n
static char* Id Status Type Severity Time Node Origin Catalog Class Args Description
g_DEFAULT_EVENT_FORMAT = : %{EV_ID}\n : %{EV_STATUS}\n : %{EV_TYPE}\n : %{EV_NSEVERITY}\n : %{EV_TIME}\n : %{EV_NODE}\n : %{EV_ORIGIN}\n : %{EV_CATALOG}\n : %{EV_CLASS_NAME}\n : %{EV_ARGS}\n : %{EV_DESC}\n;
Example Programs
2-33
/* * Function: _BlockingDump *-----------------------------------------------------------------* Purpose : * Dump events matching the filter and use 1 min for finishing * *-----------------------------------------------------------------*/ static void _BlockingDump(void) { char *pc; printf(>Dump events on %s started --------------------------------\n, s_cDestination ); pc = PemnBEventArchive(s_hComm, g_DEFAULT_EVENT_FORMAT,/* event print format */ \n\n, /* events seperator */ s_cDestination, PEMN_WRITE, , /* StartTime: any */ , /* EndTime: any */ O,A,C,E,D, /* Status: any */ W,A, /* Type: only alarm and warning */ 1, /* Severity: 1 or higher */ , /* Node: any */ , /* Origin: any */ , /* Pattern: any */ , /* Range:any */ , /* EvClass any */ 1*60*1000 ); printf(>Dump events done %s\n, pc); } /* * Function: _MyDisconnectCallback *-----------------------------------------------------------------* Purpose : * Called if agent disconnect happens in * in the middle of PemnBOpen. * *-----------------------------------------------------------------*/ static void _MyDisconnectCallback( PemnCommHandle hComm, PemnClientData pClientData ) { printf(_MyDisconnectCallback called\n); }
2-34
PATROLAPI
Reference Manual
/* * Function: _DoDump *-----------------------------------------------------------------* Purpose : * Open connection und block until success * Send event until it is received by agent. * Start a query and block until results arrive * Ask for a event report and block for results. * *-----------------------------------------------------------------*/ static void _DoDump(char * pcEncryptedPassword) { char *pcOpenResult; pcOpenResult = PemnBOpen(& s_hComm, s_cHostName,s_iPort,/* agent details */ s_cUserName,/* account to log in the agent: * user name and encrypted password*/ pcEncryptedPassword, 5, /* Loggin retry Counter */ _MyDisconnectCallback, /* Called if agent disconnect happens in * in the middle of PemnBOpen */ NULL ); if (strcmp(PEMA_OK, pcOpenResult)==0) { printf(PemnBOpen done: %s\n, pcOpenResult); if (s_hComm) _BlockingDump(); if (s_hComm) { PemnBClose(s_hComm); s_hComm = NULL; printf(PemnBClose done\n\n); } } else { printf(PemnBOpen failed %s\n, pcOpenResult); } }
Example Programs
2-35
/* * Function: main *-----------------------------------------------------------------* Purpose : * Registers message handler. * Encrypt password. * execute <iteration> time the blocking mode opeartions *-----------------------------------------------------------------*/ int main(int argc, char *argv[]) { int i=0; char cEncryptedPassword[126+1]; /* display syntax */ printf(SYNTAX_STR, PROGNAME); /* Process -h -p -u -w mandatory options */ _ProcessInput(argc, argv); /* Register my own message handler to be called * by the API framework when error, information or warning * is displayed */ PemnRegisterUserMessageHandler(_MyMessageHandler); /* passwords are sent encrypted to agents */ if ( ! PemnEncrypt(cEncryptedPassword, 126, s_cPassword)){ printf(Could not encrypt password\n); exit(1); } _DoDump(cEncryptedPassword); return (0); }
2-36
PATROLAPI
Reference Manual
3
3 3
Data Structures
This chapter describes the data structures used within the PATROL API function denitions. Overview of Type Denitions. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3-3 PemnApplAttrArray . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3-5 PemnApplAttrEnum . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3-6 PemnApplObjHandle . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3-7 PemnBDisconnectCallback . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3-8 PemnClientData . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3-9 PemnCommCallback . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3-10 PemnCommHandle. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3-11 PemnArchiveEventHandler . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3-12 PemnEventHandle . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3-13 PemnEventStatusEnum . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3-14 PemnEventTypeEnum . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3-15 PemnGetApplObjHandler . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3-16 PemnGetEventClassHandler . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3-17 PemnGetEventClassListHandler . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3-18 PemnGetInstObjHandler . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3-19 PemnGetListHandler . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3-20 PemnGetParamObjHandler . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3-21 PemnGetVarObjHandler. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3-22 PemnInstAttrArray . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3-23 PemnInstAttrEnum . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3-24 PemnInstObjHandle . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3-25 PemnParamAttrArray . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3-26 PemnParamAttrEnum. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3-27 PemnParamObjHandle . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3-28
Data Structures
3-1
PemnQueryEventHandler . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .3-29 PemnReceiveEventHandler. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .3-30 PemnReportEventHandler. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .3-32 PemnReportHandle . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .3-33 PemnUserMessageHandler . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .3-34 PemnVarObjHandle . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .3-35
3-2
PATROLAPI
Reference Manual
Overview of Type Denitions

The following table summarizes the type denitions in the pemapi.h header.
Denition Page
Routine Callback:
PemnBDisconnectCallback PemnCommCallback 3-8 3-10
Enumeration:
PemnEventStatusEnum PemnEventTypeEnum 3-14 3-15
Miscellaneous:
PemnClientData 3-9
Routine Handler:
The routine handlers dene the routines that execute upon receiving a response from the agent. Contrast these with the object handles that dene formal references to specic object types. PemnArchiveEventHandler PemnGetApplObjHandler PemnGetEventClassHandler PemnGetEventClassListHandler PemnGetInstObjHandler PemnGetListHandler PemnGetParamObjHandler PemnGetVarObjHandler PemnQueryEventHandler PemnReceiveEventHandler PemnReportEventHandler PemnUserMessageHandler 3-12 3-16 3-17 3-18 3-19 3-20 3-21 3-22 3-29 3-30 3-32 3-34
Object Handles:
The object handles dene formal references to specic object types. Contrast these with the routine handlers that dene the routines that execute upon receiving a response from the agent.
Data Structures
3-3
Denition
PemnApplObjHandle PemnCommHandle PemnEventHandle PemnInstObjHandle PemnParamObjHandle PemnReportHandle PemnVarObjHandle
Page
3-7 3-11 3-13 3-25 3-28 3-33 3-35
Array Type and Indexes:

PemnApplAttrArray PemnApplAttrEnum PemnInstAttrArray PemnInstAttrEnum PemnParamAttrArray PemnParamAttrEnum 3-5 3-6 3-23 3-24 3-26 3-27
3-4
PATROLAPI
Reference Manual
PemnApplAttrArray
Dene the read-only attributes of an application object.
Synopsis
typedef char* PemnApplAttrArray[PEMN_APPL_MAX_ATTR];
Data Structures
3-5
PemnApplAttrEnum
Dene the index to the read-only attributes of an application object.
Synopsis
typedef enum { PEMN_APPLNAME=0, PEMN_APPLWORSTINST, PEMN_APPLSTATE, PEMN_APPLMASTER, PEMN_APPLMINOR, PEMN_APPL_MAX_ATTR } PemnApplAttrEnum;
/* should be always ZERO */
/* should be always last */
3-6
PATROLAPI
Reference Manual
PemnApplObjHandle
Dene the PATROL application object handle.
Synopsis
typedef void *PemnApplObjHandle;
Description
The PemnApplObjHandle type is the abstract application type handle returned by the PemnGetApplObj() function. Use the PemnGetApplObjAttributes() function to access the application object attributes.
Data Structures
3-7
PemnBDisconnectCallback
Dene the disconnect callback type.
Synopsis
typedef void (*PemnBDisconnectCallback) ( PemnCommHandle hComm, PemnClientData pClientData );
Parameters
Parameter
hComm pClientData
Description
The communication handle. The client data.
Description
The PemnBDisconnectCallback denes the C routine that the API will call when a disconnect occurs during PemnBOpen() function execution.
3-8
PATROLAPI
Reference Manual
PemnClientData
Dene the generic client data type.
Synopsis
typedef void * PemnClientData;
Data Structures
3-9
PemnCommCallback
Dene the communication callback type.
Synopsis
typedef void (*PemnCommCallback)( void *pTheObject, /* reserved */ void *pClientData, PemnCommHandle hComm );
Description
The API calls the programmers dened callback when the connection to the PATROL Agent is opened or closed.
3-10
PATROLAPI
Reference Manual
PemnCommHandle
Dene the communication handle type.
Synopsis
typedef void *PemnCommHandle;
Description
The PemnCommHandle communication handle is returned by the PemnOpen() function and is used in all subsequent calls to the PATROL Agent.
Data Structures
3-11
PemnArchiveEventHandler
Dene the event archive handler type.
Synopsis
typedef void (*PemnArchiveEventHandler) ( PemnCommHandle hComm, char *pcResult );
Parameters
Parameter
hComm pcResult
Description
The communication handle. The event dump text.
Description
When the PATROL API receives the result of event archiving from the agent, it calls the PemnArchiveEventHandler registered by PemnEventArchive.
3-12
PATROLAPI
Reference Manual
PemnEventHandle
Dene the event handle type.
Synopsis
typedef void* PemnEventHandle;
Description
The PemnEventHandle is used by the program to access any event attributes.
Data Structures
3-13
PemnEventStatusEnum
Dene the status values type.
Synopsis
typedef enum { EV_TYPE_OPEN = 1, /*! should be one*/ EV_TYPE_ACKNOWLEDGED, EV_TYPE_CLOSED, EV_TYPE_ESCALATED, EV_TYPE_DELETED } PemnEventStatusEnum;
3-14
PATROLAPI
Reference Manual
PemnEventTypeEnum
Dene the event type.
Synopsis
typedef enum { EV_TYPE_INFORMATION = 1, /*! should be one*/ EV_TYPE_CHANGE_STATUS, EV_TYPE_ERROR, EV_TYPE_WARNING, EV_TYPE_ALARM, EV_TYPE_RESPONSE, EV_TYPE_ACK, EV_TYPE_MAX } PemnEventTypeEnum;
Data Structures
3-15
PemnGetApplObjHandler
Dene the application object type handler.
Synopsis
typedef void (*PemnGetApplObjHandler)( PemnCommHandle hComm, PemaApplObjHandle hObj );
Parameters
Parameter
hComm hObj
Description
The communication handle. The application object handle.
Description
PemnGetApplObjHandler denes the application object handler that
the API calls whenever it receives an application object from the PEM engine.
3-16
PATROLAPI
Reference Manual
PemnGetEventClassHandler
Dene the event class handler type.
Synopsis
typedef void (*PemnGetEventClassHandler)( PemnCommHandle hComm, char *pcEventClassText );
Parameters
Parameter
hComm oEventHandle
Description
The communication handle. A text string returned by the PATROL Agent that contains all the elds from the event catalog.
Description
PemnGetEventClassHandler denes the get event class handler type.
The API calls the get event class list handler when it receives a response to a PemnGetEventClass() function call.
See Also
PemnGetEventClass() on page 8-44 uses the PemnGetEventClassHandler type to return the event handler.
Data Structures
3-17
PemnGetEventClassListHandler
Dene the event class list handler type.
Synopsis
typedef void (*PemnGetEventClassListHandler)( PemnCommHandle hComm, char* pcEventClassList );
Parameters
Parameter
hComm pcEventClassList
Description
The communication handle. A text string returned by the PATROL Agent that contains the list of event classes or ERROR if the event catalog could not be found NONE if no event classes exist
Description
PemnGetEventClassListHandler denes the get event class list
handler type. The API calls the get event class list handler when it receives the response to a PemnGetEventClassList() function call.
See Also
PemnGetEventClassList() on page 8-48 uses the PemnGetEventClassListHandler type to return the list of event
classes from the event catalog.
3-18
PATROLAPI
Reference Manual
PemnGetInstObjHandler
Dene the instance object handler.
Synopsis
typedef void (*PemnGetInstObjHandler)( PemnCommHandle hComm, PemaInstObjHandle hObj );
Parameters
Parameter
hComm hObj
Description
The communication handle. The application instance object handle.
Description
PemnGetInstObjHandler denes the application instance handler that
the API calls whenever it receives an application instance object from the PATROL Agent.
Data Structures
3-19
PemnGetListHandler
Dene the get list object handler.
Synopsis
typedef void (*PemnGetListHandler)( PemnCommHandle hComm, char *pcList );
Parameters
Parameter
hComm pcList
Description
The communication handle. A text string list that can have one of the following formats: successful: full-object-name\n comp1\n
comp2\n
...
compn\n successful with empty list: full-object-name\n "NULL_OBJ"\n error (object not found): full-object-name\n "ERROR"\n
Description
PemnGetListHandler denes the list handler that the API calls whenever it receives a list object from the PEM engine.
3-20
PATROLAPI
Reference Manual
PemnGetParamObjHandler
Dene the parameter object handler.
Synopsis
typedef void (*PemnGetParamObjHandler)( PemnCommHandle hComm, PemaParamObjHandle hObj );
Parameters
Parameter
hComm hObj
Description
The communication handle. The parameter object handle.
Description
PemnGetParamObjHandler denes the parameter object handler that
the API calls whenever it receives a parameter object from the PATROL Agent.
Data Structures
3-21
PemnGetVarObjHandler
Dene the variable object type handler.
Synopsis
typedef void (*PemnGetVarObjHandler)( PemnCommHandle hComm, PemaVarObjHandle hObj );
Parameters
Parameter
hComm hObj
Description
The communication handle. The variable object handle.
Description
The API calls the PemnGetVarObjHandler type when it receives a variable object from the PATROL Agent.
3-22
PATROLAPI
Reference Manual
PemnInstAttrArray
Dene the read-only attributes of an application instance object.
Synopsis
typedef char* PemnInstAttrArray[PEMN_INST_MAX_ATTR];
Data Structures
3-23
PemnInstAttrEnum
Dene the Pemn function application instance attribute type.
Synopsis
typedef enum { PEMN_APPLINSTNAME=0, /* should be always ZERO */ PEMN_APPLINSTWORSTPARAM, PEMN_APPLINSTSTATUS, PEMN_APPLINSTRULESTATE, PEMN_INSTCREATEICON, PEMN_APPLINSTPARENT, PEMN_INST_MAX_ATTR /* should be always last */ } PemnInstAttrEnum;
Description
The PemnInstAttrEnum type denes the index to the read-only attributes of an application instance object.
3-24
PATROLAPI
Reference Manual
PemnInstObjHandle
Dene the application instance object handle type.
Synopsis
typedef void *PemnInstObjHandle;
Description
The PemnInstObjHandle type is the abstract application instance handle that is returned by the PemnGetInstObj() function. Use the PemnGetInstObjAttributes() function to access the attributes of the application instance object.
Data Structures
3-25
PemnParamAttrArray
Dene the read-only attributes of a parameter object.
Synopsis
typedef char* PemnParamAttrArray[PEMN_PARAM_MAX_ATTR];
3-26
PATROLAPI
Reference Manual
PemnParamAttrEnum
Dene the parameter attribute type.
Synopsis
typedef enum { PEMN_PARAMNAME=0, /* should be always ZERO */ PEMN_PARAMCURRENTTIME, PEMN_PARAMPOLLINGINT, PEMN_PARAMRETRIES, PEMN_PARAMCURRENTVALUE, PEMN_PARAMSTATE, PEMN_PARAMOUTPUTMODE, PEMN_PARAMAUTOSCALE, PEMN_PARAM_Y_AXIS_MIN, PEMN_PARAM_Y_AXIS_MAX, PEMN_PARAM_MAX_ATTR /* should be always last */ } PemnParamAttrEnum;
Description
The PemnParamAttrEnum type denes the index to the read-only attributes of a parameter object.
Data Structures
3-27
PemnParamObjHandle
Dene the Pemn function parameter object handle type.
Synopsis
typedef void *PemnParamObjHandle;
Description
The PemnParamObjHandle type is the abstract parameter handle returned by the PemnGetParamObj() or PemnGetComputerParamObj() functions. Use the PemnGetParamObjAttributes() functions to access the attributes of the parameter object.
3-28
PATROLAPI
Reference Manual
PemnQueryEventHandler
Dene the query event handler type.
Synopsis
typedef PemnReceiveEventHandler PemnQueryEventHandler;
Description
PemnQueryEventHandler denes the query event handler type. The PemnQueryEventHandler type is a synonym of the PemnReceiveEventHandler type. The API calls the query event
handler when it receives a response to a query that matches its user-dened lter criteria. The API differentiates between events received normally and those received as the result of a query.
See Also
PemnEventQuery() on page 8-24 uses the PemnQueryEventHandler
type to return events that match a specied lter.

PemnEventRangeQuery() on page 8-34 uses the PemnQueryEventHandler type to return events from a specied event
ID range.
PemnReceiveEventHandler type on page 3-30 is the data type to which PemnQueryEventHandler is a synonym.
Data Structures
3-29
PemnReceiveEventHandler
Dene the Pemn function receive event handler type.
Synopsis
typedef void (*PemnReceiveEventHandler)( PemnCommHandle hComm, PemnEventHandle oEventHandle ); Note
The following synonyms are provided for reference to prior versions only. Please do not use them; use PemnReceiveEventHandler instead. Synonyms for backward compatibility:
typedef PemnReceiveEventHandler PemnEventHandler; typedef PemnReceiveEventHandler PemnEventReceivedHandler;
Parameters
Parameter
hComm oEventHandle
Description
The communication handle. The event handle.
3-30
PATROLAPI
Reference Manual
Description
PemnReceiveEventHandler denes the receive event handler type.
The API calls the receive event handler when it receives an event that matches its user-dened lter was not in response to a query
Data Structures
3-31
PemnReportEventHandler
Dene the event report handler type.
Synopsis
typedef void (*PemnReportEventHandler) ( PemnCommHandle hComm, char *pcReport );
Parameters
Parameter
hComm pcReport
Description
The communication handle. The event report text.
3-32
PATROLAPI
Reference Manual
PemnReportHandle
Dene the report handle type.
Synopsis
typedef char* PemnReportHandle;
Description
PemnReportHandle is the abstract PATROL variable type handle returned by the PemnGetVarObj() function.
Note
Programmers should use PemnReportHandle as an abstract type instead of a character type (char *) because the denition may change in future releases of the PATROL API.
Data Structures
3-33
PemnUserMessageHandler
Dene the message handler type.
Synopsis
typedef void (*PemnUserMessageHandler) ( char *pcMessageToDisplay, int iMsgType );
Parameters
Parameter
pcMessageToDisplay iMsgType
Description
The message text The integer message type. The types dened in the pemapi.h header are: 0 PEMN_MSG_WARN 1 PEMN_MSG_INFO 2 PEMN_MSG_ERROR
Description
PemnUserMessageHandler denes the user message handler type for the Pemn functions. The API calls the message handler when it receives a
message from the PATROL Agent. The programmer can dene his or her own message handler (see PemnRegisterUserMessageHandler() on page 11-4 for more information).
3-34
PATROLAPI
Reference Manual
PemnVarObjHandle
Dene the variable object handle.
Synopsis
typedef char *PemnVarObjHandle;
Description
The PemnVarObjHandle is the abstract PATROL variable type handle returned by the PemnGetVarObj() function.
Note
Programmers should use PemnVarObjHandle as an abstract type instead of a character type (char *) because the denition may change in future releases of the PATROL API.
Data Structures
3-35
3-36
PATROLAPI
Reference Manual
4
4 4
Event Access Functions
This chapter describes the event access function calls that return the details of a PATROL event. PemnGetArgs(). . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 4-2 PemnGetClassName() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 4-3 PemnGetDesc(). . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 4-4 PemnGetDiary() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 4-5 PemnGetEid() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 4-6 PemnGetEventCatalogName() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 4-7 PemnGetExpectancyStr() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 4-8 PemnGetHandler() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 4-9 PemnGetNode() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 4-10 PemnGetNseverity() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 4-11 PemnGetOrigin() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 4-12 PemnGetOwner() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 4-13 PemnGetSourceID() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 4-14 PemnGetStatus(). . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 4-15 PemnGetTime() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 4-16 PemnGetType(). . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 4-17
4-1
PemnGetArgs()
Return the list of event parameters.
Synopsis
#include <pemapi.h> char* PemnGetArgs(PemnEventHandle pEhandle);
Parameter
Parameter
pEhandle
Description
The handle for the event whose arguments should be returned.
Description
The PemnGetArgs() function returns a read-only text string that is a list of the arguments for the event identied by pEhandle. The elds in the list of event arguments are separated by the tab string literal (\t).
4-2
PATROLAPI
Reference Manual
PemnGetClassName()
Return the event class name for the event.
Synopsis
#include <pemapi.h> char* PemnGetClassName(PemnEventHandle pEhandle);
Parameter
Parameter
pEhandle
Description
The handle for the event whose event class should be returned.
Description
The PemnGetClassName() function returns the read-only name of the event class for the event identied by pEhandle.
4-3
PemnGetDesc()
Return the event description.
Synopsis
#include <pemapi.h> char *PemnGetDesc(PemnEventHandle pEhandle);
Parameter
Parameter
pEhandle
Description
The handle for the event whose description should be returned.
Description
The PemnGetDesc() function returns the read-only event description string for the event identied by pEhandle.
4-4
PATROLAPI
Reference Manual
PemnGetDiary()
Return the content of the PATROL event diary.
Synopsis
#include <pemapi.h> char* PemnGetDiary(PemnEventHandle pEhandle);
Parameter
Parameter
pEhandle
Description
The handle for the event whose event diary should be returned.
Description
The PemnGetDiary() function returns a read-only event diary string for the event identied by pEhandle. The event diary consists of text that is added by a user to annotate, clarify, or further describe the event.
4-5
PemnGetEid()
Return the PATROL event identier.
Synopsis
#include <pemapi.h> int PemnGetEid(PemnEventHandle pEhandle);
Parameter
Parameter
pEhandle
Description
The handle for the event whose event identier should be returned.
Description
The PemnGetEid() function returns the integer PATROL event identier for the event identied by pEhandle. The PATROL event identier is assigned sequentially by the PATROL Event Manager as events are created.
4-6
PATROLAPI
Reference Manual
PemnGetEventCatalogName()
Return the PATROL event catalog name for the event.
Synopsis
#include <pemapi.h> char* PemnGetEventCatalogName( PemnEventHandle pEhandle );
Parameter
Parameter
pEhandle
Description
The handle for the event whose event catalog name should be returned.
Description
The PemnGetEventCatalogName() function returns the read-only name of the PATROL event catalog to which the event identied by pEhandle belongs.
4-7
PemnGetExpectancyStr()
Return the life expectancy of the event.
Synopsis
#include <pemapi.h> char* PemnGetExpectancyStr(PemnEventHandle pEhandle);
Parameter
Parameter
pEhandle
Description
The handle for the event whose expectancy string should be returned.
Description
The PemnGetExpectancyStr() function returns the read-only life expectancy string for the event identied by pEhandle. The possible expectancy strings are:
STORED DEL_IF_CLOSED DEL_IF_INFO DO_NOT_STORE
4-8
PATROLAPI
Reference Manual
PemnGetHandler()
Return the user identier of the event handler.
Synopsis
#include <pemapi.h> char* PemnGetHandler(PemnEventHandle pEhandle);
Parameter
Parameter
pEhandle
Description
The handle for the event whose last event handler user ID should be returned.
Description
The PemnGetHandler() function returns the user identier of the last person to modify the event diary of, or perform an ACKNOWLEDGE, CLOSE, or DELETE action on, the event identied by pEhandle.
4-9
PemnGetNode()
Return the host name that reported the PATROL event.
Synopsis
#include <pemapi.h> char *PemnGetNode(PemnEventHandle pEhandle);
Parameter
Parameter
pEhandle
Description
The handle for the event whose originating host name should be returned.
Description
The PemnGetNode() function returns a pointer to the host name character string for the event identied by pEhandle. The host name identies the computer system that created the PATROL event.
4-10
PATROLAPI
Reference Manual
PemnGetNseverity()
Return the numeric severity of the event.
Synopsis
#include <pemapi.h> int PemnGetNseverity(PemnEventHandle pEhandle);
Parameter
Parameter
pEhandle
Description
The handle for the event whose numeric severity should be returned.
Description
The PemnGetNseverity() function returns the numeric severity of the event identied by pEhandle. The numeric severity is an integer from 1 to 5, 5 being the highest severity.
4-11
PemnGetOrigin()
Return the PATROL application name that reported the event.
Synopsis
#include <pemapi.h> char *PemnGetOrigin(PemnEventHandle pEhandle);
Parameter
Parameter
pEhandle
Description
The handle for the event whose originating application, instance, or parameter name should be returned.
Description
The PemnGetOrigin() function returns a pointer to the originating application character string for the event identied by pEhandle. The originating application is the PATROL computer or application class that reported the event to the PATROL Event Manager.
4-12
PATROLAPI
Reference Manual
PemnGetOwner()
Return the user identier that owns the event.
Synopsis
#include <pemapi.h> char* PemnGetOwner(PemnEventHandle pEhandle);
Parameter
Parameter
pEhandle
Description
The handle for the event whose owner user ID should be returned.
Description
The PemnGetOwner() function returns a text string that is the user identier for the owner of the event identied by pEhandle. The event owner is usually a user account.
4-13
PemnGetSourceID()
Return the PATROL event source identier.
Synopsis
#include <pemapi.h> char* PemnGetSourceId(PemnEventHandle pEhandle);
Parameter
Parameter
pEhandle
Description
The handle for the event whose source ID should be returned.
Description
The PemnGetSourceID() function returns a string that is the source identier for the PATROL event.
4-14
PATROLAPI
Reference Manual
PemnGetStatus()
Return the PATROL Event Manager event status.
Synopsis
#include <pemapi.h> int PemnGetStatus(PemnEventHandle pEhandle);
Parameter
Parameter
pEhandle
Description
The handle for the event whose status should be returned.
Description
The PemnGetStatus() function returns the integer PATROL status assigned to the event identied by pEhandle. The status values are:
Value
1 2 3 4 5
Status
EV_TYPE_OPEN EV_TYPE_ACKNOWLEDGED EV_TYPE_CLOSED EV_TYPE_ESCALATED EV_TYPE_DELETED
Meaning
Open Acknowledged Closed Escalated Deleted
See Also
For information on dening the status values, see PemnEventStatusEnum on page 3-14.
4-15
PemnGetTime()
Return the event timestamp.
Synopsis
#include <pemapi.h> time_t PemnGetTime(PemnEventHandle pEhandle);
Parameter
Parameter
pEhandle
Description
The handle for the event whose timestamp should be returned.
Description
The PemnGetTime() function returns the integer timestamp for the event identied by pEhandle. The timestamp is expressed as the number of seconds that have elapsed since 00:00:00 GMT, January 1, 1970.
4-16
PATROLAPI
Reference Manual
PemnGetType()
Return the PATROL event type.
Synopsis
#include <pemapi.h> int PemnGetType(PemnEventHandle pEhandle);
Parameter
Parameter
pEhandle
Description
The handle for the event whose type should be returned.
Description
The PemnGetType() function returns the integer PATROL type assigned to the event identied by pEhandle. The type values are:
Value
1 2 3 4 5 6 7
Event Type
EV_TYPE_INFORMATION EV_TYPE_CHANGE_STATUS EV_TYPE_ERROR EV_TYPE_WARNING EV_TYPE_ALARM EV_TYPE_RESPONSE EV_TYPE_ACK
Meaning
Information State change Error Warning Alarm Response Acknowledgment
4-17
See Also
For information on dening the event types, see PemnEventTypeEnum on page 3-15.
4-18
PATROLAPI
Reference Manual
5
5 5 6
Connection Management Functions 5

This chapter describes the connection management functions that open, close, and manage the connection between your program and the PATROL Agent. PemnBClose(). . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 5-2 PemnBOpen() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 5-4 PemnBPing() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 5-6 PemnClose() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 5-8 PemnGetCommAttributes() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 5-9 PemnGetLocalPort(). . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 5-11 PemnLoop() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 5-12 PemnOpen() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 5-13 PemnSetCommAttributes() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 5-16 PemnSetLocalPort() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 5-18
Connection Management Functions
5-1
PemnBClose()
Close a connection to a PATROL Agent and block until it is done.
Synopsis
#include <pemapi.h> char* PemnBClose(PemnCommHandle hComm);
Parameter
Parameter
hComm
Description
The communication handle for the connection which the PemnBClose() function should close. The PemnBOpen() function sets the handle when the communication connection successfully opens.
Description
The PemnBClose() function closes the communication session to a PATROL Agent represented by hComm. The PemnBClose() function blocks and waits for the session to close. The PemnBClose() function returns a pointer to a character string that is set to one of the strings dened in the pemapi DLL. See the following table for a listing of these strings.
5-2
PATROLAPI
Reference Manual
Table 5-1
Return Values for Blocking Functions
Symbol / Return Value

PEMN_ERROR
Description
Returned if the function is unable to proceed due to invalid data input, such as a NULL pointer, corrupt handle, an attempt to use a previously closed handle, and so forth). Returned if an error occurs during a data management operation. Returned when the blocking function waits for iMsMaxTimeToWait milliseconds without receiving the results from the PATROL Agent. Returned if the requested object does not exist. Returned if the blocking function is interrupted before completion. Returned if the connection with the PATROL Agent is disconnected while in the blocking function. Returned if the operation successfully completed. Processing completed successfully. Corrupt handle, NULL handle pointer, or handle already closed.
PEMN_FILE_ERROR PEMN_TIMEOUT
PEMN_NULL PEMN_INTERRUPT PEMN_DISCONNECT
PEMN_OK PEMA_OK "OK\n" PEMN_ERROR "<error>\n"
5-3
PemnBOpen()
Open a connection to a PATROL Agent and wait for it to be established.
Synopsis
#include <pemapi.h> char* PemnBOpen( PemnCommHandle char int char char int PemnBDisconnectCallback PemnClientData );
*phComm, *pcHostName, iPort, *pcUserName, *pcEncryptedPassword, iMaxRetry, pDisconnectCallback, pClientData
Parameters
Parameter
phComm
Description
A pointer to a pointer to the handle for this communication connection. The PATROL API stores the communication handle at the address pointed to by *phComm when the connection to the PATROL Agent successfully opens. IMPORTANT: A variable holding the communication handle should be either statically dened in the user program or allocated on the heap. It should never be allocated on the stack. Host name on which the PATROL Agent you wish to connect to is running. Port number to which the PATROL Agent you wish to connect to is listening.
pcHostName iPort
5-4
PATROLAPI
Reference Manual
Parameter
pcUserName
Description
User name used to start the PATROL Agent session. The pcUserName and pcEncryptedPassword values together must be a valid account for the PATROL Agent. Password generated by the PemnEncrypt() function that is used to start the PATROL Agent session. The pcEncryptedPassword and pcUserName values together must be a valid account for the PATROL Agent. The maximum number of times that the PemnBOpen() function will retry to connect to the PATROL Agent. Pointer to a programmer-dened callback routine that the PATROL API will call if the PATROL Agent disconnects during the blocking open session. Data to be passed to
pcEncryptedPassword
iMaxRetry
pDisconnectCallback
pClientData
pDisconnectCallback.
Description
The PemnBOpen() function opens a session under pcUserName and pcEncryptedPassword with the PATROL Agent on pcHostName using port iPort. The PemnBOpen() function is a blocking call that waits until the session connection is open and authenticated by the PATROL Agent. The PemnBOpen() function returns the read-only PATROL API message string indicating the status of the function call.
5-5
PemnBPing()
Ping a PATROL Agent.
Synopsis
#include <pemapi.h> char* PemnBPing( char int int );
*pcHostName, iPort, iMsMaxTimeToWait
Parameters
Parameter
pcHostName iPort iMsMaxTimeToWait
Description
Name of the host to which the PATROL Agent ping is to be sent. Port number on pcHostName to which the PATROL Agent ping is to be sent. Number of milliseconds to wait for a response to the PATROL Agent ping, excluding time for DNS lookup.
5-6
PATROLAPI
Reference Manual
Description
The PemnBPing() function determines whether a PATROL Agent is running on pcHostName port number iPort. The PemnBPing() function will wait up to iMsMaxTimeToWait milliseconds for a response from the PATROL Agent. If the PemnBPing() function receives a response from the PATROL Agent within the wait time interval, it returns the status of the agent as follows: OK\n WARN\n ALARM\n OFFLINE\n VOID\n
Otherwise, it returns the string PEMN_INTERRUPT.
Example
The following is an example of the PemnBPing() function:
(void) PemnCheckInit(); for (i = 0; i < 12; i++) { printf("ping to %s on port %d is: %s\n", "myhost", 100 + i, PemnBPing("myhost",100+i,300) ); }
5-7
PemnClose()
Close the connection with the PATROL Agent.
Synopsis
#include <pemapi.h> void PemnClose(PemnCommHandle hComm);
Parameter
Parameter
hComm
Description
The communication handle for the connection that the PemnClose() function should close. The PemnOpen() function sets the handle value when the communication connection successfully opens.
Description
The PemnClose() function requests to close the connection to the PATROL Agent that is specied by the communication handle hComm. After the connection is closed, the close callback dened in PemnOpen() is called.
Warning
An attempt to use a hComm communication handle that has been closed using the PemnClose() function will produce unpredictable results.
See Also
PemnOpen() on page 5-13 to open a connection to a PATROL Agent.
5-8
PATROLAPI
Reference Manual
PemnGetCommAttributes()
Return communication connection attributes.
Synopsis
#include <pemapi.h> char* PemnGetCommAttributes( int *piHeartbeat, int *piTimeout, int *piRetries );
Parameters
Parameter
piHeartbeat
Description
A pointer to the storage location for the output of the integer millisecond (ms) value of the communication connection heartbeat. Valid range: 5000 ms (5 seconds) 18000000 ms (5 hours). The pointer can be NULL if no output value is required. Default: 600000 ms (10 minutes) A pointer to the storage location for the output of the integer millisecond value of the communication connection timeout. Valid range: 300 ms (0.3 seconds) 180000 ms (3 minutes). The pointer can be NULL if no output value is required. Default: 2000 ms (2 seconds) A pointer to the storage location for the output of the integer value of the communication connection retries. Valid range: 3 10 The pointer can be NULL if no output value is required. Default: 5
piTimeout
piRetries
5-9
Description
The PemnGetCommAttributes() function returns pointers to the current heartbeat, timeout, retries, and transport values for communication connections to PATROL Agents. The returned string is a pointer to the string that species the type of network transport protocol in use for the PATROL Agent communication session. The network transport protocol can be one of the following: PEMN_TCP_TRANSPORT PEMN_UDP_TRANSPORT
The default value is PEMN_UDP_TRANSPORT.
See Also
PemnSetCommAttributes() on page 5-16 to modify the communication connection attributes
5-10
PATROLAPI
Reference Manual
PemnGetLocalPort()
Return the current local port number for communicating with a PATROL Agent across a rewall.
Synopsis
#include <pemapi.h> int PemnGetLocalPort(void);
Description
The PemnGetLocalPort() function returns the local port number used to communicate with a PATROL Agent across a rewall.
5-11
PemnLoop()
Place the program in a loop waiting on activity from the communication connection or from timer-related activity.
Synopsis
#include <pemapi.h> void PemnLoop(void);
Description
The PemnLoop() function places the program into a wait loop on activity coming from the communication connection. Refer to Appendix B, Using Your Own Event Loop, for information on using your own event loops.
5-12
PATROLAPI
Reference Manual
PemnOpen()
Open a connection to a PATROL Event Manager or PATROL Agent.
Synopsis
#include <pemapi.h> void PemnOpen( int char PemnCommCallback PemnClientData PemnCommCallback PemnClientData PemnCommHandle
iPort, *pcRemoteHost, pCloseCallback, pCloseClientData, pOpenCallback, pOpenClientData, *phComm);
Parameters
Parameter
iPort pcRemoteHost
Description
The integer port number on which the PATROL Agent is listening. The character string that is the name of the computer system on which the PATROL Event Manager is active. A callback routine that the PemnOpen() function calls if the connection attempt is unsuccessful. The data for pCloseCallback. A callback routine that the PemnOpen() function calls when the connection successfully opens.
pCloseCallback pCloseClientData pOpenCallback
5-13
Parameter pOpenClientData phComm
Description
The data for pOpenCallback. A pointer to a pointer to the handle for this communication connection. The PATROL API stores the communication handle at the address pointed to by *phComm when the connection to the PATROL Agent successfully opens. PemnOpen() returns NULL if the connection fails. When the agent session connection fails, results will vary depending on whether the connection was attempted using UDP or TCP: With UDP, the agent session connection returns a 0 and all callback functions are registered. With TCP, the agent session connection returns an error and no callback functions are registered. IMPORTANT: A variable holding the communication handle should be either statically dened in the user program or allocated on the heap. It should never be allocated on the stack.
Description
The PemnOpen() function attempts to open a communication connection to a PATROL Event Manager or PATROL Agent on the host referenced by *pcRemoteHost using the port number iPort. If the connection is successful, the PemnOpen() function places the output value of the communication handle address into the storage location that is pointed to by *phComm and calls the callback routine pOpenCallback with pOpenClientData. The callback routine pOpenCallback should immediately call the PemnSendIdentity() function to authenticate the connection. If the connection is unsuccessful, the PemnOpen() function calls the callback routine pCloseCallback with pCloseClientData.
5-14
PATROLAPI
Reference Manual
See Also
PemnClose() on page 5-8 to close the connection with the PATROL Event Manager or PATROL Agent.
5-15
PemnSetCommAttributes()
Set communication connection attributes.
Synopsis
#include <pemapi.h> void PemnSetCommAttributes( int iHeartbeat, int iTimeout, int iRetries char *pcTransport );
Parameters
Parameter
iHeartbeat
Description
An integer millisecond (ms) value of the communication connection heartbeat. Valid range: 5000 ms (5 seconds) 18000000 ms (5 hours). The pointer can be NULL if no value is to be returned. Default: 600000 ms (10 minutes) NOTE: The value will be rounded to the nearest second unless it falls between 0 and 100 ms, exclusively; in that case, it will be rounded up to one second. The special value of 0 can be used to disable this parameter. An integer millisecond value of the communication connection timeout. Valid range: 300 ms (0.3 seconds) 180000 ms (3 minutes) Default: 2000 ms (2 seconds) The special value of zero can be used to disable this parameter. If 0 is specied for this parameter, the existing setting will not be changed.
iTimeout
5-16
PATROLAPI
Reference Manual
Parameter
iRetries
Description
An integer value of the communication connection retries. Valid range: 3 10 Default: 5 If 0 is specied for this parameter, the existing setting will not be changed. A string specifying the type of network transport protocol used for the PATROL Agent communication session. Valid range: PEMN_TCP_TRANSPORT PEMN_UDP_TRANSPORT Default: PEMN_UDP_TRANSPORT
pcTransport
Description
The PemnSetCommAttributes() function sets the heartbeat, timeout, retries, an transport attributes for the communication connections to PATROL Agents.
See Also
PemnGetCommAttributes() on page 5-9 to return the current communication connection attributes.
5-17
PemnSetLocalPort()
Set the local port number used to communicate with a PATROL Agent across a rewall.
Synopsis
#include <pemapi.h> void PemnSetLocalPort(int ilocalPort);
Parameter
Parameter
iLocalPort
Description
Integer port number that is to be used as a local port when communicating with a PATROL Agent across a rewall.
Description
The PemnSetLocalPort() function sets the local port number iLocalPort used to communicate with a PATROL Agent across a rewall.
5-18
PATROLAPI
Reference Manual
6
6 7
Security Management Functions
This chapter describes the security management that provide for account information encryption and identication. PemnEncrypt() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 6-2 PemnSendIdentity() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 6-3
6-1
PemnEncrypt()
Encrypt a password.
Synopsis
#include <pemapi.h> int PemnEncrypt( char *buff, int iLen, char *pcPasswd);
Parameters
Parameter
buff iLen pcPasswd
Description
The buffer that will contain the encrypted password. The length of the password. This value should be iLen 50. The password that is to be encrypted.
Description
The PemnEncrypt() function encrypts the password pcPasswd. The result can be stored in a conguration le.
6-2
PATROLAPI
Reference Manual
PemnSendIdentity()
Send user name and encrypted password to the PATROL Agent.
Synopsis
#include <pemapi.h> int PemnSendIdentity( PemnCommHandle hComm, char *pcUserName, char *pcEncryptedPasswd);
Parameters
Parameter
hComm
Description
The handle of the communication session to which the PemnSendIdentity() function is issued. The PemnOpen() function returns the communication handle when the connection successfully opens. User name for access to the PATROL Agent. Encrypted password for access to the PATROL Event Manager or PATROL Agent. You can encrypt a password using the PemnEncrypt() function. (See page 6-2 for more information about the PemnEncrypt() function.)
pcUserName pcEncryptedPasswd
6-3
Description
The PemnSendIdentity() function send the user name pcUserName and the encrypted password pcEncryptedPasswd to the PATROL Agent using the communication handle hComm. The PemnSendIdentity() function should be executed immediately after the PemnOpen() function to validate access to the PATROL Agent. The PATROL Agent will not accept event requests otherwise. The PemnSendIdentity() function returns TRUE if the identity information is sent to the PATROL Agent. The function returns false if the identity information is not sent to the PATROL Agent.
See Also
PemnOpen() on page 5-13 to open a connection to a PATROL Agent.
6-4
PATROLAPI
Reference Manual
7
7 8
Send and Receive Functions
This chapter describes the send and receive functions that send PATROL events to, and receive PATROL events from, the PATROL Agent. PemnReceive() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 7-2 PemnSend(), PemnBSend() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 7-7
7-1
PemnReceive()
Register to receive events from the PATROL Event Manager that match the lter criteria.
Synopsis
#include <pemapi.h> void PemnReceive( char char char char char char char char char char PemnEventReceivedHandler );
*pcStartTimeFilter, *pcEndTimeFilter, *pcStatusMaskFilter, *pcTypeMaskFilter, *pcNseverityFilter, *pcNodeFilter, *pcOriginFilter, *pcPatternFilter, *pcEidrange, *pcEvClass, pEventHandler
7-2
PATROLAPI
Reference Manual
Parameters
Parameter
pcStartTimeFilter
Description
A string that is the timestamp that denes the lower (least recent) bound of the event lter. Format is one of the following strings: PSL backward compatible: MMddhhmmyyyy RFC-822: day, date month year hh:mm:ss UNIX: day month date hh:mm:ss yyyy PSL date(): day month date hh:mm:ss yyyy where the valid ranges of the parameters are as follows: day Sun Mon Tue Wed Thu Fri Sat MM 01 to 12 month Jan Feb Mar Apr May Jun Jul Aug Sep Oct Nov Dec dd or date01 to 31 hh 00 to 23 mm and ss00 to 59 yyyy 1902 to 2037. In the PSL compatibility format the current year is used when yyyy is omitted. A string that is the timestamp that denes the upper (most recent) bound of the event lter. Format is one of the following strings: PSL backward compatible: MMddhhmmyyyy RFC-822: day, date month year hh:mm:ss UNIX: day month date hh:mm:ss yyyy PSL date(): day month date hh:mm:ss yyyy where the valid ranges of the parameters are as follows: day Sun Mon Tue Wed Thu Fri Sat MM 01 to 12 month Jan Feb Mar Apr May Jun Jul Aug Sep Oct Nov Dec dd or date01 to 31 hh 00 to 23 mm and ss00 to 59 yyyy 1902 to 2037. In the PSL compatibility format the current year is used when yyyy is omitted.
pcEndTimeFilter
7-3
Parameter
pcStatusMaskFilter
Description
A string of one or more status tags that are separated by commas. Valid range: O OPEN A ACKNOWLEDGED E ESCALATED C CLOSED D DELETED For example: "O,A,C,D" matches all statuses except ESCALATED. "O,A,C,E,D" matches all statuses. "O,C" matches only statuses OPEN and CLOSED.
pcTypeMaskFilter
A string of one or more event type tags that are separated by commas. Valid range: I INFORMATION S STATE_CHANGE E ERROR W WARNING A ALARM R RESPONSE For example: "S,E,W,A,R" matches all event types except INFORMATION. "I,S,E,W,A,R" matches all event types. "W,A" matches only event types WARNING and ALARM.
pcNseverityFilter
A string that is the event severity. Valid range: a number 1 5 with 5 being the most severe, or "" matching every event severity. A string that is the event host name lter. The "" string will match every host name. A string that is the event origin lter. The origin can be an application or a host name. The "" string will match every PATROL application class. A string that is the event description lter. The "" string will match any event description. A string that denes the range of PATROL event IDs that are eligible for this PemnReceive() function. Specify the pcEidrange character string as follows: x event ID x x/y event IDs between and including x and y -/y event IDs less than and including y x/- event IDs greater than and including x -/- all events
pcNodeFilter pcOriginFilter
pcPatternFilter pcEidrange
7-4
PATROLAPI
Reference Manual
Parameter
pcEvClass pEventHandler
Description
A string that is the event class lter. Valid range: an event class name, or "" indicating all event classes. The name of the event handler that the PATROL API calls when it receives an event matching the lter criteria.
Description
The PemnReceive() function registers a lter to receive events from the PATROL Agent. The API calls the event handler pEventHandler for those that match the lter criteria. (Non-matching events are discarded.) In effect, events that reach pEventHandler are double ltered in that the agent only sends events over the communication connection that pass its own persistent lter.
Note
You can use the PemnSetPersistentFilter() function to set the persistent lter that the PEM engine uses for a session that was opened by the PemnOpen() or PemnBOpen() function. The persistent lter is lost when you execute PemnClose() to end the session.
7-5
See Also
PemnSend() on page 7-7 to send a PATROL event to the PATROL Event Manager. PemnSetPersistentFilter() on page 8-53 to set the PATROL Event Manager persistent lter for this session.
7-6
PATROLAPI
Reference Manual
PemnSend(), PemnBSend()
Send a PATROL event to the PATROL Event Manager.
Synopsis
#include <pemapi.h> int PemnSend( PemnCommHandle char char char char char PemEventTypeEnum int Event parameters ); char* PemnBSend( PemnCommHandle int char char char char char PemEventTypeEnum int Event parameters );
hComm, *pcEventCatalogName, *pcEventClassName, *pcEventOrigin, *pcOldState, *pcNewState, eEventType, iEventNseverity,
hComm, iMsMaxTimeToWait *pcEventCatalogName, *pcEventClassName, *pcEventOrigin, *pcOldState, *pcNewState, eEventType, iEventNseverity,
7-7
Parameters
Parameter
hComm
Description
The communication handle of the connection to the Event Manager to which the event is sent. The PemnOpen() or PemnBOpen() function returns the handle when the communication connection successfully opens. Integer number of milliseconds that the PemnBSend() function will wait for a reply from the PATROL Agent before posting an error condition and resuming program execution with the next statement. A character string that identies the event catalog to which this event belongs. The PATROL Event Manager maintains a default event catalog called the standard event catalog STD. Additionally, each application class can have its own event catalog and event types. A character string that identies the event class to which the event is sent. A character string that identies the application instance or class that produced this event. A character string that identies the state of the application instance or class prior to the event. Valid range: NULL "VOID" "OFFLINE" "OK" "WARN" "ALARM"
iMsMaxTimeToWait
pcEventCatalogName
pcEventClassName pcEventOrigin pcOldState
7-8
PATROLAPI
Reference Manual
Parameter
pcNewState
Description
A character string that identies the state of the application instance or class after the event. Valid range: NULL "VOID" "OFFLINE" "OK" "WARN" "ALARM" The type of event that is being sent. Valid range: EV_TYPE_INFORMATION EV_TYPE _CHANGE_STATUS EV_TYPE_ERROR EV_TYPE_WARNING EV_TYPE_ALARM EV_TYPE_RESPONSE An integer that identies the event severity. Valid range: 1 (lowest) 5 (highest) Parameters passed to the event to form the event description. The last parameter should be NULL. Valid range: 0 20 parameters
eEventType
iEventNseverity
Event parameters
Description
The PemnSend() and PemnBSend() functions send a PATROL event with the specied information to the PATROL Agent whose communication handle is hComm. The PemnSend() and PemnBSend() functions allow you to include a dynamic number of event parameters. The PemnSend() function does not wait for an acknowledgment from the PATROL Agent that it received the event.
7-9
The PemnBSend() function causes the API to loop while waiting for an acknowledgment from the PATROL Agent. If iMsMaxTimeToWait is specied, the PemnBSend() function waits up to iMsMaxTimeToWait milliseconds. Then one of the following occurs: If a response arrives, the API resumes execution at the statement that follows the PemnBSend() function call. If the PemnBSend() function wait time expires, the PemnBSend() function returns an error message and the API resumes execution with the statement that follows the PemnBSend() function call. The PemnSend() function returns the event source ID. The PemnBSend() function returns the event source ID as a read only string.
See Also
PemnReceive() on page 7-2 to register to receive events from the PATROL Event Manager log that match the lter criteria.
7-10
PATROLAPI
Reference Manual
8
8 9

This chapter describes the event management function calls. These function calls contact the PEM engine logic:
PemnAddDiary() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 8-2 PemnDeneEventClass() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 8-4 PemnEventArchive(), PemnBEventArchive() . . . . . . . . . . . . . . . . . . 8-7 PemnEventManage() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 8-16 PemnEventManageIfMatch(), PemnBEventManageIfMatch() . . . . . 8-18 PemnEventQuery(), PemnBEventQuery() . . . . . . . . . . . . . . . . . . . . . 8-24 PemnEventRangeManage() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 8-31 PemnEventRangeQuery(). . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 8-34 PemnEventReport(), PemnBEventReport() . . . . . . . . . . . . . . . . . . . . 8-37 PemnFlushEvent() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 8-43 PemnGetEventClass(), PemnBGetEventClass() . . . . . . . . . . . . . . . . 8-44 PemnGetEventClassList(), PemnBGetEventClassList() . . . . . . . . . . 8-48 PemnSetEventClassCmd() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 8-50 PemnSetPersistentFilter(), PemnBSetPersistentFilter() . . . . . . . . . . . 8-53
8-1
PemnAddDiary()
Add text to the diary of a PATROL event.
Synopsis
#include <pemapi.h> int PemnAddDiary( PemnCommHandle PemnEventHandle char
hComm, pEh, *pcTextToAdd);
Parameters
Parameter
hComm
Description
The communication handle for the connection to which the PemnAddDiary() function is submitted. The PemnOpen() or PemnBOpen() function returns the handle when the communication connection successfully opens. The handle for the event to which the diary text is added. The character string that contains the text that is to be added to the event diary.
pEh pcTextToAdd
8-2
PATROLAPI
Reference Manual
Description
The PemnAddDiary() function sends a request to the PEM engine to add the content of character string pcTextToAdd to the diary for the event with handle pEh. The PEM engine is identied by the communication handle hComm. The PemnAddDiary() function returns a 1 if the request was sent successfully to the PEM engine and a 0 if it was not.
See Also
PemnEventManage() on page 8-16 to change the status of an event.
8-3
PemnDeneEventClass()
Dene an event class for a PATROL event catalog.
Synopsis
#include <pemapi.h> int PemnDefineEventClass( PemnCommHandle char char char char char char char char char );
hComm, *pcEventCatalog, *pcEventClass, *pcOwner, *pcDesc, *pcExpertAdvice, *pcReserved1, *pcReserved2, *pcReserved3, *pcOperation
8-4
PATROLAPI
Reference Manual
Parameters
Parameter
hComm
Description
Communication handle for the connection to which the PemnDefineEventClass() function is submitted. The PemnOpen() or PemnBOpen() function returns the handle when the communication connection successfully opens. String that contains the name of the event catalog in which the event class should be created. String that contains the name of the event class that should be created. String that contains the owner of the event class. String that contains the text that appears in the Event Description eld. String that contains the text that appears in the Expert Advice eld. String reserved for future use. String reserved for future use. String reserved for future use. String indicating the type of event class operation that the PemnDefineEventClass() function should perform. Valid Range: PEMN_EC_OPERATIONS_ADD add the event class if it does not exist PEMN_EC_OPERATIONS_REPLACE replace the event class PEMN_EC_OPERATIONS_DELETE delete the event class
pcEventCatalog pcEventClass pcOwner pcDesc pcExpertAdvice pcReserved1 pcReserved2 pcReserved3 pcOperation
8-5
Description
The PemnDefineEventClass() function manages the creation and deletion of event classes:
If pcOperation = ADD Then . . .
The PemnDefineEventClass() function adds event class pcEventClass to catalog pcEventCatalog only if it does not already exist. (It does nothing otherwise). The PemnDefineEventClass() function replaces event class pcEventClass in catalog pcEventCatalog if it exists, or adds it if it does not exist. The PemnDefineEventClass() function deletes event class pcEventClass from pcEventCatalog.
REPLACE
DELETE
The PemnDefineEventClass() function returns 1 if it was successfully sent to the PATROL Agent and 0 if it was not.
Note
The resulting event class will be lost when the Agent exits the denition.
8-6
PATROLAPI
Reference Manual
PemnEventArchive(), PemnBEventArchive()
Archive PATROL events that match the specied lter criteria to a le.
Syntax
#include <pemapi.h> int PemnEventArchive( PemnCommHandlehComm, char*pcEvFormat, char*pcEvSep, char*pcFileName, char*pcFileOperation, char*pcStartTimeFilter, char*pcEndTimeFilter, char*pcStatusFilter, char*pcTypeFilter, char*pcNseverityFilter, char*pcNodeFilter, char*pcOriginFilter, char*pcPatternFilter, char*pcEidrange, char*pcEvClass, PemnArchiveEventHandlerpArchiveEventHandler ); char* PemnBEventArchive( PemnCommHandlehComm, char*pcEvFormat, char*pcEvSep, char*pcFileName, char*pcFileOperation, char*pcStartTimeFilter, char*pcEndTimeFilter, char*pcStatusFilter, char*pcTypeFilter, char*pcNseverityFilter, char*pcNodeFilter, char*pcOriginFilter, char*pcPatternFilter, char*pcEidrange, char*pcEvClass, int iMsMaxTimeToWait );
8-7
Parameters
Parameter
hComm
Denition
The communication handle for the connection to which the PemnEventArchive() and PemnBEventArchive() functions are issued. The PemnOpen() or PemnBOpen() function returns the handle when the communication connection successfully opens. Format string used to present each event entry. For more information, see Specifying the Pemn(B)EventArchive() Output Format on page 8-13. Default: "" is equivalent to the string
pcEvFormat
"%s %s %s %s %s %s %s %s\n"
where the eight strings returned are (in order): event ID assigned by the PEM event status event type event timestamp host name that produced the event application class or instance that produced the event text string from the event description eld text string from the event diary eld pcEvSep Character string used to separate events in the archive le. If "" is specied, the PemnBEventArchive() or PemnEventArchive() function uses the newline character (\n) to separate events. String that is the name of the le where the archived events should be written. If the le name begins with a path separator / or \ (depending on the operating system), the event_archive() function assumes that the path name is a full path name. Otherwise, the event_archive() function assumes that the le name is a le in the $PATROL_HOME/log directory.
pcFileName
8-8
PATROLAPI
Reference Manual
Parameter
pcFileOperation
Denition
String that species the le access used for archiving events. Valid range: PEMN_WRITE overwrites existing le contents (if any) PEMN_APPEND appends to existing le contents (if any)
FILTER:
pcStartTimeFilter Time end-point that species the oldest event timestamp that is valid for the event archival. Valid range is "" indicating January 1, 1970 at 00:00:00, or one of the following strings: PSL backward compatible: MMddhhmmyyyy RFC-822: day, date month year hh:mm:ss UNIX: day month date hh:mm:ss yyyy PSL date(): day month date hh:mm:ss yyyy where the valid ranges of the parameters are as follows: day Sun Mon Tue Wed Thu Fri Sat MM 01 to 12 month Jan Feb Mar Apr May Jun Jul Aug Sep Oct Nov Dec dd or date01 to 31 hh 00 to 23 mm and ss00 to 59 yyyy 1902 to 2037. In the PSL compatibility format the current year is used when yyyy is omitted.
8-9
Parameter
pcEndTimeFilter
Denition
Time end-point that species the most recent event timestamp that is valid for the event archival. Valid range is "" indicating all event timestamps in the repository, or one of the following strings: PSL backward compatible: MMddhhmmyyyy RFC-822: day, date month year hh:mm:ss UNIX: day month date hh:mm:ss yyyy PSL date(): day month date hh:mm:ss yyyy where the valid ranges of the parameters are as follows: day Sun Mon Tue Wed Thu Fri Sat MM 01 to 12 month Jan Feb Mar Apr May Jun Jul Aug Sep Oct Nov Dec dd or date01 to 31 hh 00 to 23 mm and ss00 to 59 yyyy 1902 to 2037. In the PSL compatibility format the current year is used when yyyy is omitted. Event status that is valid for the event archival. Valid range: O OPEN A ACKNOWLEDGED C CLOSED E ESCALATED D DELETED For example: "O,A,C,D" matches all statuses except ESCALATED. "O,A,C,E,D" or "" matches all statuses. "O,C" matches only statuses OPEN and CLOSED.
pcStatusFilter
8-10
PATROLAPI
Reference Manual
Parameter
pcTypeFilter
Denition
Event type that is valid for the event archival. Valid range: I INFORMATION S CHANGE_STATUS E ERROR W WARNING A ALARM R RESPONSE For example: "S,E,W,A,R" matches all event types except INFORMATION. "I,S,E,W,A,R" or "" matches all event types. "W,A" matches only event types WARNING and ALARM.
pcNseverityFilter
A string that is the event severity. Valid range: a number 1 5 with 5 being the most severe, or "" matching every event severity.. Computer system name that is valid for the event archival. Valid range is "", indicating all computer systems listed in the PEM repository or a host name character string. Application instance or class name that is valid for the event archival. Valid range is "" for all application classes or a character string, indicating a specic application instance or class. Character string within the event description eld that is valid for the event archival. Valid range is "", indicating any characters or a character string. String that denes the range of PATROL event IDs that are valid for the event archival. Valid range: x event ID x x/y event IDs between and including x and y -/y event IDs less than and including y x/- event IDs greater than and including x -/- all events where x and y are integers such that 0 x y 2,147,483,647
pcNodeFilter
pcOriginFilter
pcPatternFilter
pcEidrange
8-11
Parameter
pcEvClass
Denition
Event class that is valid for the event archival. Valid range is "", indicating all event classes or a character string specifying a specic event class. The name of the handler that the PemnEventArchive() function calls when it receives a response from the PATROL Agent. Integer number of milliseconds that the PemnBEventArchive() function will wait for a reply from the PATROL Agent before posting an error condition and resuming program execution with the next statement.
pArchive EventHandler iMsMaxTimeToWait
Description
The PemnEventArchive() and PemnBEventArchive() functions write PATROL events that match the lter criteria from the PATROL event repository to the le identied by pcFileName using pcEvFormat and pcEvSep. The PemnEventArchive() function does not wait for an acknowledgment from the PATROL Agent that the archival is complete. When a response arrives, the API calls pArchiveEventHandler. The PemnBEventArchive() function causes the API to loop while waiting for an acknowledgment from the PATROL Agent. If iMsMaxTimeToWait is specied, the PemnBEventArchive() function waits up to iMsMaxTimeToWait milliseconds. Then one of the following occurs: If a response arrives, the API resumes execution at the statement that follows the PemnBEventArchive() function call. If the PemnBEventArchive() function wait time expires, the PemnBEventArchive() function returns an error message and the API resumes execution with the statement that follows the PemnBEventArchive() function call.
8-12
PATROLAPI
Reference Manual
The PemnEventArchive() function returns 1 if the event archival request was successfully sent to the PATROL Agent and 0 if it was not. The PemnBEventArchive() function returns the string PEMN_OK if the request was successfully processed by the PATROL Agent, and returns an API message string otherwise.
Specifying the Pemn(B)EventArchive() Output Format

The PemnEventArchive() and PemnBEventArchive() function pcEvFormat parameter is similar to the specication string used for the standard C library printf() function. The pcEvFormat parameter can contain alphanumeric characters for use as titles and eld names, and string literals for spacing, tabbing, and carriage control. PATROL macro variables within the pcEvFormat parameter identify the elds that the PemnEventArchive() or PemnBEventArchive() function returns. The following table describes the marco variables that are available to the PemnEventArchive() and PemnBEeventArchive() functions.
PEM Macro %{EV_ID} %{EV_STATUS} Denition
A sequential integer identier assigned by the PATROL Event Manager upon receipt of the event. Event status. Valid range: OPEN ACKNOWLEDGED CLOSED ESCALATED DELETED Event type. Valid range: INFORMATION STATE_CHANGE ERROR WARNING ALARM RESPONSE
%{EV_TYPE}
8-13
PEM Macro %{EV_TIME}
Denition
Time stamp indicating the system clock time at the moment the event was produced. The timestamp is a 24-character string with the format: day month date hh:mm:ss yyyy For example, Sun Sep 16 01:03:52 1973 Host name that produced the event. Application instance or class that produced the event. The text string description that was produced for the event. The text string that was entered into the diary for the event. The user ID of the person who performed the last acknowledge, close, or delete action on the event. User ID that owns the event. Default: PATROL account user ID Name of the event within the PATROL event class. Name of the PATROL event class within the PATROL event catalog to which the event belongs. Life expectancy and disposition of the event. Valid range: STORED DEL_IF_CLOSED DEL_IF_INFO DO_NOT_STORE Numeric severity of the event. Event severity is predened for all event classes in the STANDARD catalog. Character string that presents the event parameters separated by tab characters (\t). PATROL Event Manager rst dynamic parameter. PATROL Event Manager second dynamic parameter. Name of the PATROL event catalog to which the event belongs. Text string from the Expert Advice edit window for this event catalog and class. Text string from the SNMP Support eld for this event catalog and class. Valid range: NO_TRAP SEND_TRAP
%{EV_NODE} %{EV_ORIGIN} %{EV_DESC} %{EV_DIARY} %{EV_HANDLER} %{EV_OWNER} %{EV_NAME} %{EV_CLASS_NAME} %{EV_EXPECTANCY}
%{EV_NSEVERITY} %{EV_ARGS} %{EV_ARG1} %{EV_ARG2} %{EV_CATALOG} %{EV_EXPERT_ADVICE} %{EV_SNMP_SUPPORT}
8-14
PATROLAPI
Reference Manual
PEM Macro %{EV_CTG_DESC} %{EV_ESCL_TEXT} %{EV_NOTIFY_TEXT} %{EV_ACK_TEXT}
Denition
Text string from the Description edit window for this event catalog and class. Text string from the Escalation Command edit window for this event catalog and class. Text string from the Notication Command edit window for this event catalog and class. Text string from the Acknowledge Command edit window for this event catalog and class.
8-15
PemnEventManage()
Change the status of a PATROL event.
Synopsis
#include <pemapi.h> int PemnEventManage( PemnCommHandle PemnEventHandle char
hComm, pEh, *pcNewStatus);
Parameters
Parameter
hComm
Description
The communication handle for the connection to which the PemnEventManage() function is submitted. The PemnOpen() or PemnBOpen() function returns the handle when the communication connection successfully opens. The handle for the event whose status is to be changed. The character string that contains the new status that is to be assigned to the event. Valid range: PEMN_ACKNOWLEDGED PEMN_CLOSED PEMN_DELETED
pEh pcNewStatus
8-16
PATROLAPI
Reference Manual
Description
The PemnEventManage() function sends a request to the PEM engine to change the status of the event with handle pEh to the new state dened in pcNewStatus. The PEM engine is identied by the communication handle hComm. The PemnEventManage() function returns a 1 if the request was sent successfully to the PEM engine and 0 if it was not. Managing events using the PemnEventManage() function follows the same rules used for managing events from the PATROL Console or the PATROL Event Manager (PEM). For example, you cannot acknowledge an event that is closed.
See Also
PemnAddDiary() on page 8-2 to add text to the diary of a PATROL event.
8-17
PemnEventManageIfMatch(), PemnBEventManageIfMatch()
Request the PATROL Agent to acknowledge, close, or delete events that match the specied lter criteria.
Syntax
#include <pemapi.h> int PemnEventManageIfMatch( PemnCommHandlehComm, int iMaxCount, char*pcNewStatus, char*pcStartTimeFilter, char*pcEndTimeFilter, char*pcStatusFilter, char*pcTypeFilter, char*pcNseverityFilter, char*pcNodeFilter, char*pcOriginFilter, char*pcPatternFilter, char*pcEidrange, char*pcEvClass ); char* PemnBEventManageIfMatch( PemnCommHandlehComm, int iMaxCount, char*pcNewStatus, char*pcStartTimeFilter, char*pcEndTimeFilter, char*pcStatusFilter, char*pcTypeFilter, char*pcNseverityFilter, char*pcNodeFilter, char*pcOriginFilter, char*pcPatternFilter, char*pcEidrange, char*pcEvClass, int iMsMaxTimeToWait );
8-18
PATROLAPI
Reference Manual
Parameters
Parameter
hComm
Denition
The communication handle for the connection to which the PemnEventManageIfMatch() and PemnBEventManageIfMatch() functions are issued. The PemnOpen() or PemnBOpen() function returns the handle when the communication connection successfully opens. An integer that limits the number of events that will be managed. Specifying iMaxCount = 0 causes iMaxCount to default to 10. The character string that contains the new status that is to be assigned to events that match the lter criteria. Valid range: PEMN_ACKNOWLEDGED PEMN_CLOSED PEMN_DELETED
iMaxCount
pcNewStatus
FILTER:
8-19
Parameter
pcEndTimeFilter
Denition
Time end-point that species the most recent event timestamp that is valid for the event archival. Valid range is "" indicating all event timestamps in the repository, or one of the following strings: PSL backward compatible: MMddhhmmyyyy RFC-822: day, date month year hh:mm:ss UNIX: day month date hh:mm:ss yyyy PSL date(): day month date hh:mm:ss yyyy where the valid ranges of the parameters are as follows: day Sun Mon Tue Wed Thu Fri Sat MM 01 to 12 month Jan Feb Mar Apr May Jun Jul Aug Sep Oct Nov Dec dd or date01 to 31 hh 00 to 23 mm and ss00 to 59 yyyy 1902 to 2037. In the PSL compatibility format the current year is used when yyyy is omitted. Event status that is valid for the event archival. Valid range: O OPEN A ACKNOWLEDGED C CLOSED E ESCALATED D DELETED For example: "O,A,C,D" matches all statuses except ESCALATED. "O,A,C,E,D" or "" matches all statuses. "O,C" matches only statuses OPEN and CLOSED.
pcStatusFilter
8-20
PATROLAPI
Reference Manual
Parameter
pcTypeFilter
Denition
Event type that is valid for the event archival. Valid range: I INFORMATION S CHANGE_STATUS E ERROR W WARNING A ALARM R RESPONSE For example: "S,E,W,A,R" matches all event types except INFORMATION. "I,S,E,W,A,R" or "" matches all event types. "W,A" matches only event types WARNING and ALARM.
pcNseverityFilter
A string that is the event severity. Valid range: a number 1 5 with 5 being the most severe, or "" matching every event severity. Computer system name that is valid for the event archival. Valid range is "", indicating all computer systems listed in the PEM repository or a host name character string. Application instance or class name that is valid for the event archival. Valid range is "" for all application classes or a character string, indicating a specic application instance or class. Character string within the event description eld that is valid for the event archival. Valid range is "", indicating any characters or a character string. String that denes the range of PATROL event IDs that are valid for the event archival. Valid range: x event ID x x/y event IDs between and including x and y -/y event IDs less than and including y x/- event IDs greater than and including x -/- all events where x and y are integers such that 0 x y 2,147,483,647
pcNodeFilter
pcOriginFilter
pcPatternFilter
pcEidrange
8-21
Parameter
pcEvClass
Denition
Event class that is valid for the event archival. Valid range is "", indicating all event classes or a character string specifying a specic event class. Integer number of milliseconds that the PemnBEventArchive() function will wait for a reply from the PATROL Agent before posting an error condition and resuming program execution with the next statement.
iMsMaxTimeToWait
8-22
PATROLAPI
Reference Manual
Description
The PemnEventManageIfMatch() and PemnBEventManageIfMatch() functions send a request to the PATROL Agent identied by the session handle hComm to change the status of the next iMaxCount events that match the specied lter criteria to pcNewStatus.
Note
Choose the value of iMaxCount with care. Large iMaxCount values cause more work for the PATROL Agent and can impact its performance. The PemnEventManageIfMatch() function does not wait for a response from the PATROL Agent. The PemnBEventManageIfMatch() function causes the API to loop while waiting for a response from the PATROL Agent. If iMsMaxTimeToWait is specied, the PemnBEventManageIfMatch() function will wait up to iMsMaxTimeToWait milliseconds. Then one of the following occurs: If a response arrives, the API resumes execution at the statement that follows the PemnBEventManageIfMatch() function call. If the PemnBEventManageIfMatch() function wait time expires, the PemnBEventManageIfMatch() function returns an error message and the API resumes execution with the statement that follows the PemnBEventManageIfMatch() function call.
The PemnEventManageIfMatch() function returns 1 if the event management request was successfully sent to the PATROL Agent and 0 if it was not. The PemnBEventManageIfMatch() function returns the string PEMN_OK if the request was successfully executed by the PATROL Agent and an API message string if it was not.
8-23
PemnEventQuery(), PemnBEventQuery()
Return PATROL events that match the specied lter.
Synopsis
#include <pemapi.h> int PemnEventQuery( PemnCommHandle int char char char char char char char char char char PemnQuryEventHandler ); char PemnBEventQuery( PemnCommHandle int char char char char char char char char char char char char int );
hComm, iQueryLength, *pcStartTimeFilter, *pcEndTimeFilter, *pcStatusFilter, *pcTypeFilter, *pcNseverityFilter *pcNodeFilter, *pcOriginFilter, *pcPatternFilter *pcEidrange, *pcEvClass, pQueryEventHandler
hComm, iQueryLength, *pcEvSep, *pcEvFormat, *pcStartTimeFilter, *pcEndTimeFilter, *pcStatusFilter, *pcTypeFilter, *pcNseverityFilter *pcNodeFilter, *pcOriginFilter, *pcPatternFilter *pcEidrange, *pcEvClass, iMsMaxTimeToWait
8-24
PATROLAPI
Reference Manual
Parameters
Parameter
hComm
Description
The communication handle for the connection to which the PemnEventManageIfMatch()is submitted. The PemnOpen() or PemnBOpen() function returns the handle when the communication connection successfully opens. An integer that limits the number of events that will be returned. Specifying iQueryLength=0 causes iQueryLength to default to 10. A string that is used to separate each event in the list of events returned by the event query. Valid range: "" indicating that a newline character \n will separate the entries any valid characters including string literals Format string used to present each event entry. For more information, see Specifying the Pemn(B)EventArchive() Output Format on page 8-13. Default: "" is equivalent to the string
iQueryLength
pcEvSep
pcEvFormat
"%s %s %s %s %s %s %s %s\n"
where the eight strings returned are (in order): event ID assigned by the PEM event status event type event timestamp host name that produced the event application class or instance that produced the event text string from the event description eld text string from the event diary eld
8-25
Parameter
Description
FILTER:
8-26
PATROLAPI
Reference Manual
Parameter
pcEndTimeFilter
Description
Time end-point that species the most recent event timestamp that is valid for the event archival. Valid range is "" indicating all event timestamps in the repository, or one of the following strings: PSL backward compatible: MMddhhmmyyyy RFC-822: day, date month year hh:mm:ss UNIX: day month date hh:mm:ss year PSL date(): day month date hh:mm:ss yyyy where the valid ranges of the parameters are as follows: day Sun Mon Tue Wed Thu Fri Sat MM 01 to 12 month Jan Feb Mar Apr May Jun Jul Aug Sep Oct Nov Dec dd or date01 to 31 hh 00 to 23 mm and ss00 to 59 yyyy 1902 to 2037. In the PSL compatibility format the current year is used when yyyy is omitted. Event status that is valid for the event archival. Valid range: O OPEN A ACKNOWLEDGED C CLOSED E ESCALATED D DELETED For example: "O,A,C,D" matches all statuses except ESCALATED. "O,A,C,E,D" or "" matches all statuses. "O,C" matches only statuses OPEN and CLOSED.
pcStatusFilter
8-27
Parameter
pcTypeFilter
Description
A string of one or more event type tags that are separated by commas. Valid range: I INFORMATION S STATE_CHANGE E ERROR W WARNING A ALARM R RESPONSE For example: "S,E,W,A,R" matches all event types except INFORMATION "I,S,E,W,A,R" matches all event types "W,A" matches only event types WARNING and ALARM A string that is the event severity. Valid range: a number 1 5 with 5 being the most severe, or "" matching every event severity. A string that is the event host name lter. The "" string will match every host name. A string that is the event origin lter. The origin can be an application or host name. The "" string will match every PATROL application class. A string that is the event description lter. The "" string will match any event description. A string that denes the range of PATROL event IDs that are eligible for this pemnEventQuery() function. Specify the pcEidrange character string as follows: x event ID x x/y event IDs between and including x and y -/y event IDs less than and including y x/- event IDs greater than and including x -/- all events A string that is the event class lter. Valid range: an event class name or "" indicating all event classes.
pcNseverityFilter
pcEvClass
8-28
PATROLAPI
Reference Manual
Parameter
pQueryEventHandler
Description
The name of the event handler that the PemnEventQuery() function calls when its lter criteria matches an event from the PATROL Event Manager. Integer number of milliseconds that the PemnBEventQuery() function will wait for a reply from the PATROL Agent before posting an error condition and resuming program execution with the next statement.
iMsMaxTimeToWait
Description
The PemnEventQuery() and PemnBEventQuery() functions send a request to the PATROL Agent to return up to iQueryLength events that match the specied lter parameters. The PemnEventQuery() function does not wait for a response from the PATROL Agent. When a response arrives, the API calls pQueryEventHandler. The PemnBEventQuery() function causes the API to loop while waiting for a response from the PATROL Agent. If iMsMaxTimeToWait is specied, the PemnBEventQuery() function will wait up to iMsMaxTimeToWait milliseconds: If a response arrives, the API resumes execution at the statement that follows the PemnBEventQuery() function call If the PemnBEventQuery() function wait time expires, the PemnBEventQuery() function returns an error message and the API resumes execution with the statement that follows the PemnBEventQuery() function call
8-29
The PemnEventQuery() function returns a 1 if the query was sent successfully to the PEM engine and 0 if it was not.The PemnBEventQuery() function returns up to iQueryLength events formatted using pcEvSep and pcEvFormat if the query was successful and an API message string if it was not.
Note
Choose the value of iQueryLength with care. Large iQueryLength values cause more work for the PEM engine and can impact its performance.
See Also
PemnEventRangeQuery() on page 8-34 to return PATROL events from
a specied event ID range.
8-30
PATROLAPI
Reference Manual
PemnEventRangeManage()
Change the status of PATROL events within a specied event ID range.
Synopsis
#include <pemapi.h> int PemnEventRangeManage( PemnCommHandle hComm, char *pcEidRange, char *pcNewStatus, char *pcUsrName, int iMaxCount);
Parameters
Parameter
hComm
Description
The communication handle for the connection to which the PemnEventRangeManage() and PemnBEventRangeManage() functions are issued. The PemnOpen() or PemnBOpen() function returns the handle when the communication connection successfully opens. A character string that denes the range of PATROL event IDs that are eligible for this PemnEventRangeManage() function. Specify the pcEidRange character string as follows: x event ID x x/y event IDs between and including x and y -/y event IDs less than and including y x/- event IDs greater than and including x -/- all events
pcEidRange
8-31
Parameter
pcNewStatus
Description
The character string that contains the new status that is to be assigned to the event range. Valid range: PEMN_ACKNOWLEDGED PEMN_CLOSED PEMN_DELETED A character string that contains the user name of the person or process changing the event status. The content of character string pcUsrName is placed in the event diary of each event whose status is changed. An integer that limits the number of events that will be affected by the status change. Specifying iMaxCount = 0 causes iMaxCount to default to 10.
pcUsrName
iMaxCount
Description
The PemnEventRangeManage() function sends a request to the PEM engine to assign pcNewStatus as the new event status for up to iMaxCount events whose event IDs are within the range specied by the content of the character string pcEidRange. The PemnEventRangeManage() function also requests that the content of the character string pcUsrName be added to the event diary of each modied event. All the events belong to the PEM engine whose communication handle is hComm. The PemnEventRangeManage() function returns a 1 if the request was sent successfully to the PEM engine and a 0 if it was not.
Note
Choose the value of iMaxCount with care. Large iMaxCount values cause more work for the PEM engine and can impact its performance.
8-32
PATROLAPI
Reference Manual
Managing events using the PemnEventRangeManage() function follow the same rules used for managing events from the PATROL Console or the PATROL Event Manager (PEM) Console. For example, you cannot acknowledge an event that is closed.
Note
To query the event repository le (that is the PEM.log le) without affecting PATROL Agent performance, use the PemnQueryEvents() function (see PemnQueryEvents() on page A-9).
8-33
PemnEventRangeQuery()
Return PATROL events from a specied event ID range.
Synopsis
#include <pemapi.h> int PemnEventRangeQuery( PemnCommHandle char int PemnQueryEventHandler
hComm, *pcEidRange, iQueryLength pQueryEventHandler);
Parameters
Parameter
hComm
Description
The communication handle for the connection to which the PemnEventRangeQuery() function is submitted. The PemnOpen() or PemnBOpen() function returns the handle when the communication connection successfully opens. A character string that denes the range of PATROL event IDs that are eligible for this PemnEventRangeQuery() function. Specify the pcEidRange character string as follows: x event ID x x/y event IDs between and including x and y -/y event IDs less than and including y x/- event IDs greater than and including x -/- all events
pcEidRange
8-34
PATROLAPI
Reference Manual
Parameter
iQueryLength
Description
An integer that limits the number of events that will be affected by the status change. Specifying iQueryLength = 0 causes iQueryLength to default to the pemMaxQuery value dened for the PATROL Event Manager in its config.default le. (The default pemMaxQuery value is 10). The name of the event handler that the PemnEventRangeQuery() function calls when its lter criteria matches an event returned from the PATROL Event Manager.
pQueryEventHandler
Description
The PemnEventRangeQuery() function requests the PEM engine to return up to iQueryLength PATROL events whose event IDs are within the range specied by the content of the character string pcEidRange. The events are sent by the PATROL Agent and those that match the event ID range criteria are received by the event handler pQueryEventHandler. The PemnEventRangeQuery() function returns a 1 if the query was sent successfully to the PATROL Agent a 0 if it was not.
Note
Choose the value of iQueryLength with care. Large iQueryLength values cause more work for the PATROL Agent and can impact its performance.
Note
To query the event repository le (that is the PEM.log le) without affecting PATROL Agent performance, use the PemnQueryEvents() function (see PemnQueryEvents() on page A-9).
8-35
See Also
PemnEventQuery() on page 8-24 to return PATROL events that match
the specied lter.
8-36
PATROLAPI
Reference Manual
PemnEventReport(), PemnBEventReport()
Return a report summarizing all events that match the specied lter criteria.
Synopsis
int PemnEventReport( PemnCommHandle char char char char char char char char char char char PemnReportEventHandler ); hComm, *pcFormat, /* reserved */ *pcStartTimeFilter, *pcEndTimeFilter, *pcStatusFilter, *pcTypeFilter, *pcNseverityFilter, *pcNodeFilter, *pcOriginFilter, *pcPatternFilter, *pcEidrange, *pcEvClass, pReportEventHandler
char* PemnBEventReport( PemnCommHandle hComm, char *pcFormat, /* reserved */ char *pcStartTimeFilter, char *pcEndTimeFilter, char *pcStatusFilter, char *pcTypeFilter, char *pcNseverityFilter, char *pcNodeFilter, char *pcOriginFilter, char *pcPatternFilter, char *pcEidrange, char *pcEvClass, int iMsMaxTimeToWait );
8-37
Parameters
Parameter
hComm
Description
The communication handle for the connection to which the PemnEventReport() function is submitted. The PemnOpen() or PemnBOpen() function returns the handle when the communication connection successfully opens. Field reserved for future use. (The event report format will be user-denable.) A string that is the timestamp that denes the lower (least recent) bound of the event lter. Format: one of the following strings: PSL backward compatible: MMddhhmmyyyy RFC-822: day, date month year hh:mm:ss UNIX: day month date hh:mm:ss yyyy PSL date(): day month date hh:mm:ss yyyy where the valid ranges of the parameters are: day Sun Mon Tue Wed Thu Fri Sat MM 01 to 12 month Jan Feb Mar Apr May Jun Jul Aug Sep Oct Nov Dec dd or date 01 to 31 hh 00 to 23 mm and ss 00 to 59 yyyy 1902 to 2037. In the PSL compatibility format the current year is used when yyyy is omitted.
pcFormat pcStartTimeFilter
8-38
PATROLAPI
Reference Manual
Parameter
pcEndTimeFilter
Description
A string that is the timestamp that denes the upper (most recent) bound of the event lter. Format: one of the following strings: PSL backward compatible: MMddhhmmyyyy RFC-822: day, date month year hh:mm:ss UNIX: day month date hh:mm:ss yyyy PSL date(): day month date hh:mm:ss yyyy where the valid ranges of the parameters are: day Sun Mon Tue Wed Thu Fri Sat MM 01 to 12 month Jan Feb Mar Apr May Jun Jul Aug Sep Oct Nov Dec dd or date 01 to 31 hh 00 to 23 mm and ss 00 to 59 yyyy 1902 to 2037. In the PSL compatibility format the current year is used when yyyy is omitted. A string of one or more status tags that are separated by commas. Valid range: O OPEN A ACKNOWLEDGED E ESCALATED C CLOSED D DELETED For example: "O,A,C,D" matches all statuses except ESCALATED "O,A,C,E,D" matches all statuses "O,C" matches only statuses OPEN and CLOSED
pcStatusFilter
8-39
Parameter
pcTypeFilter
Description
A string of one or more event type tags that are separated by commas. Valid range: I INFORMATION S STATE_CHANGE E ERROR W WARNING A ALARM R RESPONSE For example: "S,E,W,A,R" matches all event types except INFORMATION "I,S,E,W,A,R" matches all event types "W,A" matches only event types WARNING and ALARM A string that is the event severity. Valid range: a number 1 5 with 5 being the most severe, or "" matching every event severity.. A string that is the event host name lter. The "" string will match every host name. A string that is the event origin lter. The origin can be an application or host name. The "" string will match every PATROL application class. A string that is the event description lter. The "" string will match any event description. A string that denes the range of PATROL event IDs that are eligible for this pemnEventQuery() function. Specify the pcEidrange character string as follows: x event ID x x/y event IDs between and including x and y -/y event IDs less than and including y x/- event IDs greater than and including x -/- all events A string that is the event class lter. Valid range: an event class name or "" indicating all event classes.
pcNseverityFilter
pcEvClass
8-40
PATROLAPI
Reference Manual
Parameter
nb
Description
The name of the event handler that the PemnEventReport() function calls when its lter criteria matches an event from the PATROL Event Manager. This parameter is used in nonblocking mode only. Integer number of milliseconds that the PemnBEventReport() function will wait for a reply from the PATROL Agent before posting an error condition and resuming program execution with the next statement. This parameter is used in blocking mode only.
pReportEventHandler
iMsMaxTimeToWait
Description
The PemnEventReport() and PemnBEventReport() functions cause the PATROL Agent to generate a report summarizing events that match the specied lter criteria. The PemnEventReport() function does not wait for a response from the PATROL Agent. When a response arrives, the API calls pReportEventHandler. The PemnBEventReport() function causes the API to loop while waiting for a response from the PATROL Agent. If iMsMaxTimeToWait is specied, the PemnBEventReport() function will wait up to iMsMaxTimeToWaitmilliseconds: If a response arrives, the API resumes execution at the statement that follows the PemnBEventReport() function call If the PemnBEventReport() function wait time expires, the PemnBEventReport() function returns a timeout error message and the API resumes execution with the statement that follows the PemnBEventReport() function call
8-41
The PemnEventReport() function returns 1 if the event report request was successfully sent to the PATROL Agent and 0 if it was not. The PemnBEventReport() function returns the event report if successful, or an API message string if not. The following is an example of the text string returned from the PATROL Agent using the PemnEventReport() and PemnBEventReport() functions.
---------------------------------------------------------------------Number of events in the Repository: 821 Number of events in cache: 134 Number of events on disk: 687 Status OPEN: 821 ACKNOWLEDGED: 0 CLOSED: 0 ESCALATED: 0 DELETED: 0 Type ALARM: 3 WARNING: 10 ERROR: 0 STATE_CHANGE: 806 INFORMATION: 2 RESPONSE: 0 Time First event: Tue Mar 19 03:34:43 1996 Last event: Tue Mar 19 08:25:51 1996 Event Id Smallest Id: 14595 Greatest Id: 16069 Event size: Average event size: 225 bytes Maximum event size: 287 bytes
8-42
PATROLAPI
Reference Manual
PemnFlushEvent()
Flush PATROL events to the event log on disk.
Synopsis
#include <pemapi.h> void PemnFlushEvent(PemnCommHandle hComm);
Parameter
Parameter
hComm
Description
The handle of the communication connection to which the PemnFlushEvent() function is issued. The PemnOpen() or PemnBOpen() function returns the communication handle when the connection successfully opens.
Description
The PemnFlushEvent() function instructs the PEM engine on the connection hComm to write all the events accumulated in its internal buffers to the log le, usually PEM.log.
Note
You do not need to ush events in order to use the PemnReceive() function.
8-43
PemnGetEventClass(), PemnBGetEventClass()
Return selected elds from the event class.
Synopsis
#include <pemapi.h> int PemnGetEventClass( PemnCommHandle char char char PemnGetEventClassHandler ); char* PemnBGetEventClass( PemnCommHandle char char char int );
hComm, *pcEventCatalog, *pcEventClass, *pcEvFormat, pEventClassHandler
hComm, *pcEventCatalog, *pcEventClass, *pcEvFormat, iMsMaxTimeToWait
Parameters
Parameter
hComm
Description
The handle of the communication connection to which the PemnGetEventClass() function is issued. The PemnOpen() or PemnBOpen() function returns the communication handle when the connection successfully opens. The string that is the name of the event catalog (usually an application name) to which the event class belongs. The string that is the event class name.
pcEventCatalog
pcEventClass
8-44
PATROLAPI
Reference Manual
Parameter
pcEvFormat
Description
Format string used to present event class information. See Specifying the PemnGetEventClass() Function Output Format on page 8-46 for more information. The name of the event handler that the PemnGetEventClass() function calls when it receives a response from the PATROL Event Manager. Integer number of milliseconds that the PemnBGetEventClass() function will wait for a reply from the PATROL Agent before posting an error condition and resuming program execution with the next statement.
pEventClassHandler
iMsMaxTimeToWait
Description
The PemnGetEventClass() and PemnBGetEventClass() functions request that the PEM engine return a character string containing elds from the event class pcEventClass in catalog pcEventCatalog. The returning character string is formatted as specied in pcEvFormat. The PemnGetEventClass() function does not wait for a response from the PATROL Agent. When a response arrives, the API calls pEventClassHandler. The PemnBGetEventClass() function causes the API to loop while waiting for a response from the PATROL Agent. If iMsMaxTimeToWait is specied, the PemnBGetEventClass() function will wait up to iMsMaxTimeToWait milliseconds: If a response arrives, the API resumes execution at the statement that follows the PemnBGetEventClass() function call If the PemnBGetEventClass() function wait time expires, the PemnBGetEventClass() function returns an error message and the API resumes execution with the statement that follows the PemnBGetEventClass() function call
Event Management Functions 8-45
The PemnGetEventClass() function returns 1 if the event class eld request was successfully sent to the PEM engine and 0 if it was not. The PemnBGetEventClass() function returns the event class information formatted using pcEvFormat if successful and an API message string if not.
Specifying the PemnGetEventClass() Function Output Format

The PemnGetEventClass() and PemnBGetEventClass() functions pcEvFormat parameter is similar to the specication string for the standard C library printf() function. The pcEvFormat parameter can contain alphanumeric characters for use as titles and eld names, and string literals for spacing, tabbing, and carriage control. PATROL macro variables within the pcEvFormat parameter identify the elds that the PemnGetEventClass() or PemnBGetEventClass() functions return.
Note
The PATROL macro variables for the PemnGetEventClass() and PemnBGetEventClass() functions return information from the event catalog. To view this information from the PATROL Developer Console you can open the Event Editor dialog box.
Macro Variable
%{EV_EXPERT_ADVICE} %{EV_SNMP_SUPPORT}
Denition
Text string from the Expert Advice edit window for this event catalog and class. Text from the SNMP Support eld for this event catalog and class. Valid range: NO_TRAP SEND_TRAP Text string from the Description edit window for this event catalog and class. Text string from the Escalation Command edit window for this event catalog and class.
%{EV_CTG_DESC} %{EV_ESCL_TEXT}
8-46
PATROLAPI
Reference Manual
Macro Variable
%{EV_NOTIFY_TEXT} %{EV_ACK_TEXT}
Denition
Text string from the Notication Command edit window for this event catalog and class. Text string from the Acknowledge Command edit window for this event catalog and class.
8-47
PemnGetEventClassList(), PemnBGetEventClassList()
Return the list of event classes from an event catalog.
Synopsis
#include <pemapi.h> int PemnGetEventClassList( PemnCommHandle char PemnGetEventClassListHandler ); char* PemnBGetEventClassList( PemnCommHandle char int );
hComm, *pcEventCatalog, pEventClassListHandler
hComm, *pcEventCatalog, iMsMaxTimeToWait
Parameters
Parameter
hComm
Description
The handle of the communication connection to which the event class list function is issued. The PemnOpen() or PemnBOpen() function returns the communication handle when the connection successfully opens. The string that is the name of the event catalog (usually an application name) whose event classes should be returned.
pcEventCatalog
8-48
PATROLAPI
Reference Manual
Parameter
pEventClassListHandler
Description
The name of the event handler that the PemnGetEventClassList() function calls when it receives a response from the PATROL Event Manager. Integer number of milliseconds that the PemnBGetEventClassList() function will wait for a reply from the PATROL Agent before posting an error condition and resuming program execution with the next statement.
iMsMaxTimeToWait
Description
The PemnGetEventClassList() and PemnBGetEventClassList() functions request that the PEM engine return a list of event classes from the event catalog pcEventCatalog. The PemnGetEventClassList() function does not wait for a response from the PATROL Agent. When a response arrives, the API calls pEventClassListHandler. The PemnBGetEventClassList() function causes the API to loop while waiting for a response from the PATROL Agent. If iMsMaxTimeToWait is specied, the PemnBGetEventClassList() function waits up to iMsMaxTimeToWait milliseconds: If a response arrives, the API resumes execution at the statement that follows the PemnBGetEventClassList() function call If the PemnBGetEventClassList() function wait time expires, the PemnBGetEventClassList() function returns an error message and the API resumes execution with the statement that follows the PemnBGetEventClassList() function call
The PemnGetEventClassList() function returns 1 if the event class eld request was successfully sent to the PEM engine and 0 if it was not. The PemnBGetEventClassList() function returns the requested list of event classes if successful and an API message string if it was not.
8-49
PemnSetEventClassCmd()
Dene a command in an event class.
Synopsis
#include <pemapi.h> int PemnSetEventClassCmd( PemnCommHandle hComm, char *pcEventCatalog, char *pcEventClass, char *pcCmdType, char *pcCmdText, char *pcOperation char *pcSpecificData );
Parameters
Parameter
hComm
Description
The handle of the communication session to which the PemnSetPersistentFilter() function is issued. The PemnOpen() or PemnBOpen() function returns the communication handle when the connection successfully opens. String that is the name of the event catalog (usually an application name) that contains pcEventClass. String that is the name of the event class to which a command is to be added. Command type that is being dened. Valid range:
PEMN_OS_NOTIFICATIONPEMN_PSL_NOTIFICATION PEMN_OS_ESCALATIONPEMN_PSL_ESCALATION PEMN_OS_MGT PEMN_PSL_MGT
pcEventCatalog
pcEventClass pcCmdType
pcCmdText
The statements of the OS or PSL command.
8-50
PATROLAPI
Reference Manual
Parameter
pcOperation
Description
String indicating the type of event class operation that the PemnDefineEventClass() function should perform. Valid Range: PEMN_EC_OPERATIONS_ADD add the command if it does not exist PEMN_EC_OPERATIONS_REPLACE replace the command PEMN_EC_OPERATIONS_DELETE delete the command String containing additional data specic to the command.
pcSpecicData
8-51
Description
The PemnSetEventClassCmd() function manages the creation and deletion of event class commands: If pcOperation = ADD, the PemnSetEventClassCmd() function adds a pcCmdType command with pcCmdText to pcEventClass and pcEventCatalog only if it does not already exist (it does nothing otherwise). If pcOperation = REPLACE, the PemnSetEventClassCmd() function replaces event class pcCmdType with pcCmdText in pcEventClass and pcEventCatalog if it exists, or adds it if it does not exist. If pcOperation = DELETE, the PemnSetEventClassCmd() function deletes event class pcCmdType from pcEventClass and
pcEventCatalog. Note
Commands added using the PemnSetEventClassCmd() function remain while the PATROL Agent is running but are not saved as part of the PATROL Agent and will be lost when the PATROL Agent is restarted. The PemnSetEventClassCmd() function returns 1 if it was successfully sent to the PATROL Agent and 0 if it was not.
8-52
PATROLAPI
Reference Manual
PemnSetPersistentFilter(), PemnBSetPersistentFilter()
Set the PATROL Event Manager persistent lter for this session.
Synopsis
#include <pemapi.h> int PemnSetPersistentFilter( PemnCommHandle hComm char *pcStartTimeFilter, char *pcEndTimeFilter, char *pcStatusMaskFilter, char *pcTypeMaskFilter, char *pcNseverityFilter, char *pcNodeFilter, char *pcOriginFilter, char *pcPatternFilter, char *pcEidrange, char *pcEvClass ); char* PemnBSetPersistentFilter( PemnCommHandle hComm char *pcStartTimeFilter, char *pcEndTimeFilter, char *pcStatusFilter, char *pcTypeFilter, char *pcNseverityFilter, char *pcNodeFilter, char *pcOriginFilter, char *pcPatternFilter, char *pcEidrange, char *pcEvClass, int iMsMaxTimeToWait );
8-53
Parameters
Parameter
hComm
Description
The handle of the communication session to which the PemnSetPersistentFilter() function is issued. The PemnOpen() or PemnBOpen() function returns the communication handle when the connection successfully opens. A string that is the timestamp that denes the lower (least recent) bound of the event lter. Format: one of the following strings: PSL backward compatible: MMddhhmmyyyy RFC-822: day, date month year hh:mm:ss UNIX: day month date hh:mm:ss yyyy PSL date(): day month date hh:mm:ss yyyy where the valid ranges of the parameters are: day Sun Mon Tue Wed Thu Fri Sat MM 01 to 12 month Jan Feb Mar Apr May Jun Jul Aug Sep Oct Nov Dec dd or date 01 to 31 hh 00 to 23 mm and ss 00 to 59 yyyy 1902 to 2037. In the PSL compatibility format the current year is used when yyyy is omitted. A string that is the timestamp that denes the upper (most recent) bound of the event lter. Format: one of the following strings: PSL backward compatible: MMddhhmmyyyy RFC-822: day, date month year hh:mm:ss UNIX: day month date hh:mm:ss yyyy PSL date(): day month date hh:mm:ss yyyy where the valid ranges of the parameters are: day Sun Mon Tue Wed Thu Fri Sat MM 01 to 12 month Jan Feb Mar Apr May Jun Jul Aug Sep Oct Nov Dec dd or date 01 to 31 hh 00 to 23 mm and ss 00 to 59 yyyy 1902 to 2037. In the PSL compatibility format the current year is used when yyyy is omitted.
pcStartTimeFilter
pcEndTimeFilter
8-54
PATROLAPI
Reference Manual
Parameter
pcStatusFilter
Description
A string of one or more status tags that are separated by commas. Valid range: O OPEN A ACKNOWLEDGED E ESCALATED C CLOSED D DELETED For example: "O,A,C,D" matches all statuses except ESCALATED "O,A,C,E,D" matches all statuses "O,C" matches only statuses OPEN and CLOSED A string of one or more event type tags that are separated by commas. Valid range: I INFORMATION S STATE_CHANGE E ERROR W WARNING A ALARM R RESPONSE For example: "S,E,W,A,R" matches all event types except INFORMATION "I,S,E,W,A,R" matches all event types "W,A" matches only event types WARNING and ALARM A string that is the event severity. Valid range: a number 1 5 with 5 being the most severe, or "" matching every event severity. A string that is the event host name lter. The "" string will match every host name. A string that is the event origin lter. The origin can be an application or host name. The "" string will match every PATROL application class. A string that is the event description lter. The "" string will match any event description.
pcTypeFilter
pcNseverityFilter
pcPatternFilter
8-55
Parameter
pcEidrange
Description
A string that denes the range of PATROL event IDs that should be passed by the lter. Specify the pcEidrange character string as follows: x event ID x x/y event IDs between and including x and y -/y event IDs less than and including y x/- event IDs greater than and including x -/- all events A string that is the event class lter. Valid range: an event class name or "" indicating all event classes. Integer number of milliseconds that the PemnBSetPersistentFilter() function will wait for a reply from the PATROL Agent before posting an error condition and resuming program execution with the next statement.
pcEvClass
iMsMaxTimeToWait
Description
The PemnSetPersistentFilter() and PemnBSetPersistenFilter() functions set the persistent lter that the PEM engine will use to lter events that it sends to this session using the communication handle hComm. The PemnSetPersistentFilter() function does not wait for a response from the PATROL Agent.
8-56
PATROLAPI
Reference Manual
The PemnBSetPersistentFilter() function causes the API to loop while waiting for a response from the PATROL Agent. If iMsMaxTimeToWait is specied, the PemnBSetPersistentFilter() function will wait up to iMsMaxTimeToWait milliseconds: If a response arrives, the API resumes execution at the statement that follows the PemnBSetPersistentFilter() function call If the PemnBSetPersistentFilter() function wait time expires, the PemnBSetPersistentFilter() function returns an error message and the API resumes execution with the statement that follows the PemnBSetPersistenFilter() function call
The PemnSetPersistentFilter() function returns 1 if the new lter was successfully sent to the PEM engine and 0 if it was not. The PemnBSetPersistenFilter() function returns the string PEMN_OK if the new lter was successfully set in the PATROL Agent and an API message string if it was not. Changing the persistent lter for one hComm handle will not change the persistent lter for other hComm handles. When the PemnClose() function closes the communication connection with the PEM engine, the persistent lter settings for the session are lost.
See Also
PemnReceive() on page 7-2 to register to receive events from the
PATROL Event Manager log that match the lter criteria.
8-57
8-58
PATROLAPI
Reference Manual
9
9 10
Application Management Functions 9

This chapter describes the application management function calls that return information about PATROL computer, application class, instance, parameter, and variable objects. PemnBPslExec(). . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 9-2 PemnBSetVarObj() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 9-4 PemnGetApplList(), PemnBGetApplList() . . . . . . . . . . . . . . . . . . . . 9-6 PemnGetApplObj(), PemnBGetApplObj() . . . . . . . . . . . . . . . . . . . . 9-8 PemnGetApplObjAttributes(). . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 9-11 PemnGetApplObjInfo() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 9-12 PemnGetComputerParamList(), PemnBGetComputerParamList() . . 9-14 PemnGetComputerParamObj(), PemnBGetComputerParamObj() . . 9-16 PemnGetInstList(), PemnBGetInstList() . . . . . . . . . . . . . . . . . . . . . . 9-19 PemnGetInstObj(), PemnBGetInstObj() . . . . . . . . . . . . . . . . . . . . . . 9-22 PemnGetInstObjAttributes(). . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 9-25 PemnGetInstObjInfo() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 9-26 PemnGetParamList(), PemnBGetParamList() . . . . . . . . . . . . . . . . . . 9-28 PemnGetParamObj(), PemnBGetParamObj() . . . . . . . . . . . . . . . . . . 9-31 PemnGetParamObjAttributes(). . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 9-34 PemnGetParamObjInfo() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 9-35 PemnGetVarList(), PemnBGetVarList(). . . . . . . . . . . . . . . . . . . . . . . 9-37 PemnGetVarObj(), PemnBGetVarObj() . . . . . . . . . . . . . . . . . . . . . . . 9-40
Application Management Functions
9-1
PemnBPslExec()
Execute the specied PSL script.
Synopsis
#include <pemapi.h> char* PemnBPslExec( PemnCommHandle hComm, int iMsMaxTimeToWait, int iWaitForResults, char *pcText );
Parameters
Parameter
hComm
Description
The communication handle for the connection to which the PSL script is sent. The PemnOpen() or PemnBOpen() function returns the handle when the communication connection successfully opens. Number of milliseconds to wait for a response from the PATROL Agent. The minimum permitted value is 100. Default: The value specied by the PemnBSetTimeout() function call or 60000 milliseconds (1 minute). Flag specifying whether the PemnBPslExec() function should wait for the result of the PSL script execution. Valid range: 0 Wait only for acknowledgment that the PATROL Agent received the PSL script 1 Wait for the result of the PSL script execution (blocking) Text of the PSL script that is to be executed by the PATROL Agent.
iMsMaxTimeToWait
iWaitForResults
pcText
9-2
PATROLAPI
Reference Manual
Description
The PemnBPslExec() function sends the PSL script pcText to the PATROL Agent identied by the communication handle hComm. If iWaitForResults = 1, the PemnBPslExec() function will wait for, and return, the read-only result of the PSL script execution. Otherwise, the PemnBPslExec() function will return a read-only API message string indicating the status of the operation. The PemnBPslExec() function and the API do not perform any compilation or syntax checks on pcText before sending it to the PATROL Agent. That is the users responsibility. (Hint: use the PATROL Console to edit the PSL script and verify the syntax.)
9-3
PemnBSetVarObj()
Request the PATROL Agent to set a PATROL variable value.
Synopsis
#include <pemapi.h> PemnVarObjHandle PemnBSetVarObj( PemnCommHandle hComm, char *pcVarName, char *pcVarValue, int iMsMaxTimeToWait );
Parameters
Parameter
hComm
Description
The handle of the communication connection to which the PemnBSetVarObj() function is issued. The PemnOpen() function returns the communication handle when the connection successfully opens. Name of the PATROL variable whose value is to be set. Value to which the PSL variable is to be set. The maximum number of milliseconds that the PemnBSetVarObj() function will wait for a response from the PATROL Agent.
pcVarName pcVarValue iMsMaxTimeToWait
9-4
PATROLAPI
Reference Manual
Description
The PemnBSetVarObj() function requests that the PATROL Agent identied by the connection handle hComm set variable pcVarName to the value pcVarValue. The PemnBSetVarObj() function will wait iMsMaxTimeToWait milliseconds for a response from the PATROL Agent. The PemnBSetVarObj() returns the API message string indicating the status of the operation.
9-5
PemnGetApplList(), PemnBGetApplList()
Return a list of a computers application classes from the PEM engine.
Synopsis
#include <pemapi.h> int PemnGetApplList( PemnCommHandle PemnGetListHandler );
hComm, pGetListHandler
char* PemnBGetApplList( PemnCommHandle hComm, int iMsMaxTimeToWait );
Parameters
Parameter
hComm
Description
The handle of the communication connection to which the PemnGetApplList() or PemnBGetApplList() function is issued. The PemnOpen() function returns the communication handle when the connection successfully opens. The name of the handler that the PemnGetApplList() function calls when it receives a response from the PEM engine. This parameter is used in nonblocking mode only. Integer number of milliseconds that the PemnBGetApplList() function will wait for a reply from the PEM engine before posting an error condition and resuming program execution with the next statement. This parameter is used in blocking mode only.
nb
pGetListHandler
iMsMaxTimeToWait
9-6
PATROLAPI
Reference Manual
Description
The PemnGetApplList() and PemnBGetApplList() functions request that the PEM engine return a list of the application classes from the computer system connected to handle hComm. The PemnGetApplList() function does not wait for a response from the PEM engine. When a response arrives, the API calls pGetListHandler. The PemnBGetApplList() function causes the API to loop while waiting for a response from the PEM engine. If iMsMaxTimeToWait is specied, the PemnBGetApplList() function will wait up to iMsMaxTimeToWait milliseconds: If a response arrives, the API resumes execution at the statement that follows the PemnBGetApplList() function call If the PemnBGetApplList() function wait time expires, the PemnBGetApplList() function returns an error message and the API resumes execution with the statement that follows the PemnBGetApplList() function call
The PemnGetApplList() function returns 1 if the application class list request was successfully sent to the PEM engine and 0 if it was not. The PemnBGetApplList() function returns the requested application list if successful and an API message string if it was not.
9-7
PemnGetApplObj(), PemnBGetApplObj()
Return an application object from the PEM engine.
Synopsis
#include <pemapi.h> int PemnGetApplObj( PemnCommHandle char PemnGetApplObjHandler );
hComm, *pcApplTypeName, pGetObjHandler
PemnApplObjHandle PemnBGetApplObj( PemnCommHandle hComm, char *pcApplTypeName, int iMsMaxTimeToWait );
Parameters
Parameter
hComm
Description
The handle of the communication connection to which the PemnGetApplObj() or PemnBGetApplObj() function is issued. The PemnOpen() function returns the communication handle when the connection successfully opens. String that is the name of the application class to be returned.
pcApplTypeName
9-8
PATROLAPI
Reference Manual
Parameter
nb
Description
The name of the handler that the PemnGetApplObj() function calls when it receives a response from the PEM engine. This parameter is used in nonblocking mode only. Integer number of milliseconds that the PemnBGetApplObj() function will wait for a reply from the PEM engine before posting an error condition and resuming program execution with the next statement. This parameter is used in blocking mode only.
pGetObjHandler
iMsMaxTimeToWait
Description
The PemnGetApplObj() and PemnBGetApplObj() functions request that the PEM engine return the application class object identied by pcApplTypeName. Once the application object handle (hObj) is received, use the PemnGetApplObjAttributes() function to access the attributes of the application object. The PemnGetApplObj() function does not wait for a response from the PEM engine. When a response arrives, the API calls pGetObjHandler. The PemnBGetApplObj() function causes the API to loop while waiting for a response from the PEM engine. If iMsMaxTimeToWait is specied, the PemnBGetApplObj() function will wait up to iMsMaxTimeToWait milliseconds: If a response arrives, the API resumes execution at the statement that follows the PemnBGetApplObj() function call If the PemnBGetApplObj() function wait time expires, the PemnBGetApplObj() function returns an error message and the API resumes execution with the statement that follows the PemnBGetApplObj() function call
9-9
The PemnGetApplObj() function returns 1 if the application class list request was successfully sent to the PEM engine and 0 if it was not. The PemnBGetApplObj() function returns the requested application object handle if successful and an API message string if it was not.
9-10
PATROLAPI
Reference Manual
PemnGetApplObjAttributes()
Return the attributes of an application.
Synopsis
PemnApplAttrArray *PemnGetApplObjAttributes( PemnApplObjHandle hObj );
Parameter
Parameter
hObj
Description
The handle for the application object for which the attributes should be returned.
Description
The PemnGetApplObjAttributes() function returns the attributes of the application class object identied by the object handle hObj. The returned attributes are in the form of a structure dened by the PemnApplAttrEnum type denition (see PemnApplAttrEnum on page 3-6 for more information). The application class attributes include the following: worst instance state master revision minor revision
Note
The returned information is read-only. Do not try to free it or write to it.
9-11
PemnGetApplObjInfo()
Return a PATROL application information string.
Synopsis
#include <pemapi.h> char *PemnGetApplObjInfo( PemnApplObjHandle hObj, char *pcFormatString );
Parameter
Parameter
hObj pcFormatString
Description
The handle for the application object for which an information string should be returned. String reserved for future use.
Description
The PemnGetApplObjInfo() function returns a character string that contains information about the PATROL application object identied by the handle hObj. The PemnGetApplObjInfo() function return value is formatted as follows:
appname\tworstinstance\tstate\tmasterrev\tminorrev
9-12
PATROLAPI
Reference Manual
Note
The format of the returned string may change in future PATROL API releases.
Field appname worstinstance state
Description
Full object name of the application. Full object name of the instance of this application that has the worst object state. The state of the application object. Valid range: OFFLINE OK WARN ALARM Major version number of the Knowledge Module for this application. Minor version number of the Knowledge Module for this application.
masterrev minorrev
9-13
PemnGetComputerParamList(), PemnBGetComputerParamList()
Return a list of the computer parameter names from the PEM engine.
Synopsis
#include <pemapi.h> int PemnGetComputerParamList( PemnCommHandle hComm, PemnGetListHandler pGetListHandler, ); char* PemnBGetComputerParamList( PemnCommHandle hComm, int iMsMaxTimeToWait );
Parameters
Parameter
hComm
Description
The handle of the communication connection to which the PemnGetComputerParamList() or PemnBGetComputerParamList() function is issued. The PemnOpen() function returns the communication handle when the connection successfully opens. The name of the handler that the PemnGetComputerParamList() function calls when it receives a response from the PEM engine. This parameter is used in nonblocking mode only. Integer number of milliseconds that the PemnBGetComputerParamList() function will wait for a reply from the PEM engine before posting an error condition and resuming program execution with the next statement. This parameter is used in blocking mode only.
nb
pGetListHandler
iMsMaxTimeToWait
9-14
PATROLAPI
Reference Manual
Description
The PemnGetComputerParamList() and PemnBGetComputerParamList() functions request that the PEM engine return a list of the computer parameters from the computer system connected to handle hComm. The PemnGetComputerParamList() function does not wait for a response from the PEM engine. When a response arrives, the API calls pGetListHandler. The PemnBGetComputerParamList() function causes the API to loop while waiting for a response from the PEM engine. If iMsMaxTimeToWait is specied, the PemnBGetComputerParamList() function will wait up to iMsMaxTimeToWait milliseconds: If a response arrives, the API resumes execution at the statement that follows the PemnBGetComputerParamList() function call If the PemnBGetComputerParamList() function wait time expires, the PemnBGetComputerParamList() function returns an error message and the API resumes execution with the statement that follows the PemnBGetComputerParamList() function call
The PemnGetComputerParamList() function returns 1 if the application class list request was successfully sent to the PEM engine and 0 if it was not. The PemnBGetComputerParamList() function returns the requested computer parameter list if successful and an API message string if it was not.
9-15
PemnGetComputerParamObj(), PemnBGetComputerParamObj()
Return a computer parameter object from the PEM engine.
Synopsis
#include <pemapi.h> int PemnGetComputerParamObj( PemnCommHandle hComm, char *pcParamName, PemnGetParamObjHandler pGetObjHandler, ); PemnParamObjHandle PemnCommHandle char int ); PemnBGetComputerParamObj( hComm, *pcParamName, iMsMaxTimeToWait
Parameters
Parameter
hComm
Description
The handle of the communication connection to which the PemnGetComputerParamObj() or PemnBGetComputerParamObj() function is issued. The PemnOpen() function returns the communication handle when the connection successfully opens. String that is the name of the computer parameter to be returned.
pcParamName
9-16
PATROLAPI
Reference Manual
Parameter
nb
Description
The name of the handler that the PemnGetComputerParamObj() function calls when it receives a response from the PEM engine. This parameter is used in nonblocking mode only. Integer number of milliseconds that the PemnBGetComputerParamObj() function will wait for a reply from the PEM engine before posting an error condition and resuming program execution with the next statement. This parameter is used in blocking mode only.
pGetObjHandler
iMsMaxTimeToWait
Description
The PemnGetComputerParamObj() and PemnBGetComputerParamObj() functions request that the PEM engine return the computer parameter object identied by pcParamName. Once the computer parameter object handle (hObj) is received, use the PemnGetParamObjAttributes() function to access the attributes of the computer parameter object. The PemnGetComputerParamObj() function does not wait for a response from the PEM engine. When a response arrives, the API calls pGetObjHandler. The PemnBGetComputerParamObj() function causes the API to loop while waiting for a response from the PEM engine. If iMsMaxTimeToWait is specied, the PemnBGetComputerParamObj() function will wait up to iMsMaxTimeToWait milliseconds: If a response arrives, the API resumes execution at the statement that follows the PemnBGetComputerParamObj() function call If the PemnBGetComputerParamObj() function wait time expires, the PemnBGetComputerParamObj() function returns an error message and the API resumes execution with the statement that follows the PemnBGetComputerParamObj() function call
9-17
The PemnGetComputerParamObj() function returns 1 if the application class list request was successfully sent to the PEM engine and 0 if it was not. The PemnBGetComputerParamObj() function returns the requested computer parameter object handle if successful and an API message string if it was not.
9-18
PATROLAPI
Reference Manual
PemnGetInstList(), PemnBGetInstList()
Return a list of application instance names from the PEM engine.
Synopsis
#include <pemapi.h> int PemnGetInstList( PemnCommHandle char PemnGetListHandler );
hComm, *pcApplTypeName, pGetListHandler,
char* PemnBGetInstList( PemnCommHandle hComm, char *pcApplTypeName, int iMsMaxTimeToWait );
Parameters
Parameter
hComm
Description
The handle of the communication connection to which the PemnGetInstList() or PemnBGetInstList() function is issued. The PemnOpen() function returns the communication handle when the connection successfully opens. String that is the name of the application class from which the instance list is to be returned.
pcApplTypeName
9-19
Parameter
nb
Description
The name of the handler that the PemnGetInstList() function calls when it receives a response from the PEM engine. This parameter is used in nonblocking mode only. Integer number of milliseconds that the PemnBGetInstList() function will wait for a reply from the PEM engine before posting an error condition and resuming program execution with the next statement. This parameter is used in blocking mode only.
pGetListHandler
iMsMaxTimeToWait
Description
The PemnGetInstList() and PemnBGetInstList() functions request that the PEM engine return a list of the application instances for the application class pcApplTypeName from the computer system connected to handle hComm. The PemnGetInstList() function does not wait for a response from the PEM engine. When a response arrives, the API calls pGetListHandler. The PemnBGetInstList() function causes the API to loop while waiting for a response from the PEM engine. If iMsMaxTimeToWait is specied, the PemnBGetInstList() function will wait up to iMsMaxTimeToWait milliseconds: If a response arrives, the API resumes execution at the statement that follows the PemnBGetInstList() function call If the PemnBGetInstList() function wait time expires, the PemnBGetInstList() function returns an error message and the API resumes execution with the statement that follows the PemnBGetInstList() function call
9-20
PATROLAPI
Reference Manual
The PemnGetInstList() function returns 1 if the application class list request was successfully sent to the PEM engine and 0 if it was not. The PemnBGetInstList() function returns the requested instance list if successful and an API message string if it was not.
9-21
PemnGetInstObj(), PemnBGetInstObj()
Return an application instance object from the PEM engine.
Synopsis
#include <pemapi.h> int PemnGetInstObj( PemnCommHandle char char PemnGetInstObjHandler );
hComm, *pcApplTypeName, *pcApplInstName, pGetObjHandler
PemnInstObjHandle PemnBGetInstObj( PemnCommHandle hComm, char *pcApplTypeName, char *pcApplInstName, int iMsMaxTimeToWait );
Parameters
Parameter
hComm
Description
The handle of the communication connection to which the PemnGetInstObj() or PemnBGetInstObj() function is issued. The PemnOpen() function returns the communication handle when the connection successfully opens. String that is the name of the application class from which the instance is to be returned. String that is the name of the application instance to be returned.
pcApplTypeName pcApplInstName
9-22
PATROLAPI
Reference Manual
Parameter
nb
Description
The name of the handler that the PemnGetInstObj() function calls when it receives a response from the PEM engine. This parameter is used in nonblocking mode only. Integer number of milliseconds that the PemnBGetInstObj() function will wait for a reply from the PEM engine before posting an error condition and resuming program execution with the next statement. This parameter is used in blocking mode only.
pGetObjHandler
iMsMaxTimeToWait
Description
The PemnGetInstObj() and PemnBGetInstObj() functions request that the PEM engine return the application instance object for application class pcApplTypeName and instance pcApplInstName. Once the application instance object handle (hObj) is received, use the PemnGetInstObjAttributes() function to access the attributes of the application instance object. The PemnGetInstObj() function does not wait for a response from the PEM engine. When a response arrives, the API calls pGetObjHandler. The PemnBGetInstObj() function causes the API to loop while waiting for a response from the PEM engine. If iMsMaxTimeToWait is specied, the PemnBGetInstObj() function will wait up to iMsMaxTimeToWait milliseconds: If a response arrives, the API resumes execution at the statement that follows the PemnBGetInstObj() function call If the PemnBGetInstObj() function wait time expires, the PemnBGetInstObj() function returns an error message and the API resumes execution with the statement that follows the PemnBGetInstObj() function call
9-23
The PemnGetInstObj() function returns 1 if the application class list request was successfully sent to the PEM engine and 0 if it was not. The PemnBGetInstObj() function returns the requested instance object handle if successful and an API message string if it was not.
9-24
PATROLAPI
Reference Manual
PemnGetInstObjAttributes()
Return the attributes of an application instance.
Synopsis
PemnInstAttrArray *PemnGetInstObjAttributes( PemnInstObjHandle hObj );
Parameter
Parameter
hObj
Description
The handle for the application instance object for which the attributes should be returned.
Description
The PemnGetInstObjAttributes() function returns the attributes of the application instance object identied by the object handle hObj. The returned attributes are in the form of a structure dened by the PemnInstAttrEnum type denition (see PemnInstAttrEnum on page 3-24 for more information). The application instance attributes include the following: worst parameter status rule state create icon parent name
Note
The returned information is read-only. Do not try to free it or write to it.
9-25
PemnGetInstObjInfo()
Return a PATROL application instance information string.
Synopsis
#include <pemapi.h> char *PemnGetInstObjInfo( PemnInstObjHandle hObj char *pcFormatString );
Parameter
Parameter
hObj pcFormatString
Description
The handle for the application object for which an information string should be returned. String reserved for future use.
Description
The PemnGetInstObjInfo() function returns a character string that contains information about the PATROL application instance object identied by the handle hObj. The PemnGetInstObjInfo() function return value is formatted as follows:
instancename\tworstparam\tstatus\trulestate\tcreateicon\tparent
9-26
PATROLAPI
Reference Manual
Note
The format of the returned string may change in future PATROL API releases.
Field appname worstparam status
Description
Full object name of the application. Full object name of the parameter of this application that has the worst object state. The state of the application instance object. Valid range: VOID OFFLINE OK WARN ALARM The state of the rule. Flag that indicates whether an icon should be created and displayed for this instance. Valid range: 0 do not create an icon 1 create an icon Name of the object that is the parent of this instance. Valid range: instance name or NULL string.
rulestate createicon
parent
9-27
PemnGetParamList(), PemnBGetParamList()
Return a list of the application instance parameter names from the PEM engine.
Synopsis
#include <pemapi.h> int PemnGetParamList( PemnCommHandle char char PemnGetListHandler );
hComm, *pcApplTypeName, *pcApplInstName, pGetListHandler,
char* PemnBGetParamList( PemnCommHandle hComm, char *pcApplTypeName, char *pcApplInstName, int iMsMaxTimeToWait );
Parameters
Parameter
hComm
Description
The handle of the communication connection to which the PemnGetParamList() or PemnBGetParamList() function is issued. The PemnOpen() function returns the communication handle when the connection successfully opens. String that is the name of the application class from which the parameter list is to be returned. String that is the application instance name from which the parameter list is to be returned.
9-28
PATROLAPI
Reference Manual
Parameter
nb
Description
The name of the handler that the PemnGetParamList() function calls when it receives a response from the PEM engine. This parameter is used in nonblocking mode only. Integer number of milliseconds that the PemnBGetParamList() function will wait for a reply from the PEM engine before posting an error condition and resuming program execution with the next statement. This parameter is used in blocking mode only.
pGetListHandler
iMsMaxTimeToWait
Description
The PemnGetParamList() and PemnBGetParamList() functions request that the PEM engine return a list of parameters for application class pcApplTypeName and instance pcApplInstName from the computer system connected to handle hComm. The PemnGetParamList() function does not wait for a response from the PEM engine. When a response arrives, the API calls pGetListHandler. The PemnBGetParamList() function causes the API to loop while waiting for a response from the PEM engine. If iMsMaxTimeToWait is specied, the PemnBGetParamList() function will wait up to iMsMaxTimeToWait milliseconds: If a response arrives, the API resumes execution at the statement that follows the PemnBGetParamList() function call If the PemnBGetParamList() function wait time expires, the PemnBGetParamList() function returns an error message and the API resumes execution with the statement that follows the PemnBGetParamList() function call
9-29
The PemnGetParamList() function returns 1 if the application class list request was successfully sent to the PEM engine and 0 if it was not. The PemnBGetParamList() function returns the requested parameter list if successful and an API message string if it was not.
9-30
PATROLAPI
Reference Manual
PemnGetParamObj(), PemnBGetParamObj()
Return a application instance parameter object from the PEM engine.
Synopsis
#include <pemapi.h> int PemnGetParamObj( PemnCommHandle char char char PemnGetParamObjHandler ); PemnParamObjHandle PemnCommHandle char char char int );
hComm, *pcApplTypeName, *pcApplInstName, *pcParamName, pGetObjHandler
PemnBGetParamObj( hComm, *pcApplTypeName, *pcApplInstName, *pcParamName, iMsMaxTimeToWait
Parameters
Parameter
hComm
Description
The handle of the communication connection to which the PemnGetParamObj() or PemnBGetParamObj() function is issued. The PemnOpen() function returns the communication handle when the connection successfully opens. String that is the name of the application class from which the parameter is to be returned. String that is the application instance name from which the parameter is to be returned.
9-31
Parameter
pcParamName pGetObjHandler
Description
String that is the name of the application instance parameter to be returned. The name of the handler that the PemnGetParamObj() function calls when it receives a response from the PEM engine. Integer number of milliseconds that the PemnBGetParamObj() function will wait for a reply from the PEM engine before posting an error condition and resuming program execution with the next statement.
iMsMaxTimeToWait
Description
The PemnGetParamObj() and PemnBGetParamObj() functions request that the PEM engine return the application instance parameter object identied by application class pcApplTypeName, instance pcApplInstName, and parameter pcParamName. Once the parameter object handle (hObj) is received, use the PemnGetParamObjAttributes() function to access the attributes of the parameter object. The PemnGetParamObj() function does not wait for a response from the PEM engine. When a response arrives, the API calls pGetObjHandler. The PemnBGetParamObj() function causes the API to loop while waiting for a response from the PEM engine. If iMsMaxTimeToWait is specied, the PemnBGetParamObj() function will wait up to iMsMaxTimeToWait milliseconds: If a response arrives, the API resumes execution at the statement that follows the PemnBGetParamObj() function call If the PemnBGetParamObj() function wait time expires, the PemnBGetParamObj() function returns an error message and the API resumes execution with the statement that follows the PemnBGetParamObj() function call
9-32
PATROLAPI
Reference Manual
The PemnGetParamObj() function returns 1 if the application class list request was successfully sent to the PEM engine and 0 if it was not. The PemnBGetParamObj() function returns the requested parameter object handle if successful and an API message string if it was not.
9-33
PemnGetParamObjAttributes()
Return the attributes of a parameter.
Synopsis
PemnParamAttrArray *PemnGetParamObjAttributes( PemnParamObjHandle hObj );
Parameter
Parameter
hObj
Description
The handle for the parameter object for which the attributes should be returned.
Description
The PemnGetParamObjAttributes() function returns the attributes of the parameter object identied by the object handle hObj. The returned attributes are in the form of a structure dened by the PemnParamAttrEnum type denition (see PemnParamAttrEnum on page 3-27 for more information). The parameter attributes include the following: timestamp polling interval retries current value state output mode auto scale setting y-axis minimum y-axis maximum
9-34
PATROLAPI
Reference Manual
PemnGetParamObjInfo()
Return a PATROL parameter information string.
Synopsis
#include <pemapi.h> char *PemnGetParamObjInfo( PemnParamObjHandle hObj char *pcFormatString );
Parameter
Parameter
hObj pcFormatString
Description
The handle for the parameter object for which an information string should be returned. String reserved for future use.
Description
The PemnGetParamObjInfo() function returns a character string that contains information about the PATROL parameter object identied by the handle hObj. The PemnGetInstObjInfo() function return value is formatted as follows:
paramname\ttime\tpollintvl\tretries\tvalue\tstate\toutmode\t autoscale\txaxis\tyaxis
9-35
Field paraname time pollintvl retries
Description
Full object name of the parameter. 24-character time stamp of the most current parameter value. Number of seconds between successive polls of this parameter. Number of times the PATROL Agent will attempt to poll the parameter (unsuccessfully) before reporting an error. Most recent value reported by the parameter. Most recent state of the parameter. Valid range: OK, WARN, or ALARM. Parameter output type. Valid range: GRAPH, GAUGE, TEXT, NONE, or N/A for collector parameters. State of the ag that allows the PATROL Console to automatically scale the parameter graph or gauge based on the parameter value. X axis value for the parameter. Y axis for the parameter.
value state outmode
autoscale
xaxis yaxis
9-36
PATROLAPI
Reference Manual
PemnGetVarList(), PemnBGetVarList()
Return a list of a computers variables from the PEM engine.
Synopsis
#include <pemapi.h> int PemnGetVarList( PemnCommHandle char char PemnGetListHandler );
hComm, *pcNode, *pcKeyword, pGetListHandler,
char* PemnBGetVarList( PemnCommHandle hComm, char *pcNode, char *pcKeyword, int iMsMaxTimeToWait );
Parameters
Parameter
hComm
Description
The handle of the communication connection to which the PemnGetVarList() or PemnBGetVarList() function is issued. The PemnOpen() function returns the communication handle when the connection successfully opens. String that is the object name whose variable list should be returned.
pcNode
9-37
Parameter
pcKeyword
Description
Keyword that species the information that is to be returned for the object. Valid range: nodes return node list only subnodes return a node and subnode list leaves return a list of only leaves (this option is equivalent to the PATROL Version 3.0 get_vars(object) function) all return a list of all children (this option is equivalent to the PATROL Version 3.1 get_vars(object,1) function) The name of the handler that the PemnGetVarList() function calls when it receives a response from the PEM. Integer number of milliseconds that the PemnBGetVarList() function will wait for a reply from the PEM before posting an error condition and resuming program execution with the next statement.
pGetListHandler
iMsMaxTimeToWait
9-38
PATROLAPI
Reference Manual
Description
The PemnGetVarList() and PemnBGetVarList() functions request that the PEM return a list of variables for the computer system identied by pcNode. The PemnGetVarList() function does not wait for a response from the PEM. When a response arrives, the API calls pGetListHandler. The PemnBGetVarList() function causes the API to loop while waiting for a response from the PEM. If iMsMaxTimeToWait is specied, the PemnBGetVarList() function will wait up to iMsMaxTimeToWait milliseconds: If a response arrives, the API resumes execution at the statement that follows the PemnBGetVarList() function call. If the PemnBGetVarList() function wait time expires, the PemnBGetVarList() function returns an error message and the API resumes execution with the statement that follows the PemnBGetVarList() function call.
The PemnGetVarList() function returns 1 if the application class list request was successfully sent to the PEM and 0 if it was not. The PemnBGetVarList() function returns the requested variable list if successful and an API message string if it was not.
9-39
PemnGetVarObj(), PemnBGetVarObj()
Return a variable object from the PEM.
Synopsis
#include <pemapi.h> int PemnGetVarObj( PemnCommHandle char PemnGetVarObjHandler );
hComm, *pcVarName, pGetObjHandler,
PemnVarObjHandle PemnBGetVarObj( PemnCommHandle hComm, char *pcVarName, int iMsMaxTimeToWait );
Parameter
Parameter
hComm
Description
The handle of the communication connection to which the PemnGetVarObj() or PemnBGetVarObj() function is issued. The PemnOpen() function returns the communication handle when the connection successfully opens. String that is the name of the variable to be returned.
pcVarName
9-40
PATROLAPI
Reference Manual
Parameter
pGetObjHandler
Description
The name of the handler that the PemnGetVarObj() function calls when it receives a response from the PEM. Integer number of milliseconds that the PemnBGetVarList() function will wait for a reply from the PEM before posting an error condition and resuming program execution with the next statement.
iMsMaxTimeToWait
Description
The PemnGetVarObj() and PemnBGetVarObj() functions request that the PEM return the variable object identied by pcVarName. The PemnGetVarObj() function does not wait for a response from the PEM . When a response arrives, the API calls pGetObjHandler. The PemnBGetVarObj() function causes the API to loop while waiting for a response from the PEM. If iMsMaxTimeToWait is specied, the PemnBGetVarObj() function will wait up to iMsMaxTimeToWait milliseconds: If a response arrives, the API resumes execution at the statement that follows the PemnBGetVarObj() function call If the PemnBGetVarObj() function wait time expires, the PemnBGetVarObj() function returns an error message and the API resumes execution with the statement that follows the PemnBGetVarObj() function call
The PemnGetVarObj() function returns 1 if the application class list request was successfully sent to the PEM and 0 if it was not. The PemnBGetVarObj() function returns the requested variable object handle if successful and an API message string if it was not.
9-41
9-42
PATROLAPI
Reference Manual
10
10 11
Data Management Functions
10
This chapter describes the data management function calls that are used to send a stream of bytes to a PATROL Agent. PemnPutStream(), PemnBPutStream(). . . . . . . . . . . . . . . . . . . . . . . 10-2
10-1
PemnPutStream(), PemnBPutStream()
Send a character stream to a PATROL Agent.
Synopsis
#include <pemapi.h> int PemnPutStream( PemnCommHandle int char char char int char char char char );
hComm, iStreamSize, *pcStreamData, *pcCatalogName, *pcClassName, iTag, /* reserved for future use*/ *pcFileName, *pcOperation, *pcStreamId, *pcKey4 /* reserved for future use*/
char* PemnBPutStream( PemnCommHandle hComm, int iStreamSize, char *pcStreamData, char *pcCatalogName, char *pcClassName, int iTag, /* reserved for future use*/ char *pcFileName, char *pcOperation, char *pcStreamId, char *pcKey4, /* reserved for future use*/ int iMsMaxTimeToWait );
10-2
PATROLAPI
Reference Manual
Parameter
Parameter
hComm
Description
The handle of the communication connection to which the PemnPutStream() or PemnBPutStream() function is issued. The PemnOpen() or PemnBOpen() function returns the communication handle when the connection successfully opens. Integer number of characters that will be sent to the PATROL Agent in the character stream. Valid range: 0 8096 Character string containing the character stream. Optional event catalog name for the event generated by the character stream operation. Valid range: PATROL event catalog name or "". If pcCatalogName = pcClassName = "" then no event is generated. If pcCatalogName = "" or pcClassName = "", an event with the standard catalog and RemProcess class is generated. Optional event class name for the event generated by the character stream operation. Valid range: PATROL event class name or "". If pcCatalogName = pcClassName = "" then no event is generated. If pcCatalogName = "" or pcClassName = "", an event with the standard catalog and RemProcess class is generated. Integer reserved for future use. Character le name in which the PATROL Agent will buffer the character stream it receives. String indicating the type of stream operation that the PemnPutStream() or PemnBPutStream() function should perform. Valid range: PEMN_WRITE PATROL Agent will write character stream to pcFileName PEMN_APPEND PATROL Agent will append character stream to pcFileName Character identier for the character stream.
iStreamSize
pcStreamData pcCatalogName
pcClassName
iTag pcFileName pcOperation
pcStreamId
10-3
Parameter
pcKey4 iMsMaxTimeToWait
Description
String reserved for future use. Integer number of milliseconds that the PemnBPutStream() function will wait for a response from the PATROL Agent before posting an error condition and resuming program execution with the next statement.
Description
The PemnPutStream() and PemnBPutStream() functions send a character stream pcStreamData of size iStreamSize to the PATROL Agent identied by hComm with the instruction pcOperation that the PATROL Agent either write or append the character stream to the le pcFileName. The PemnPutStream() and PemnBPutStream() function call can generate an optional event (either PATROL- or user-dened) using event catalog pcCatalogName and pcClassName. The PemnPutStream() function does not wait for a response from the PATROL Agent. The PemnBPutStream() function causes the API to loop while waiting for a response from the PATROL Agent. If iMsMaxTimeToWait is specied, the PemnBPutStream() function will wait up to iMsMaxTimeToWait milliseconds: If a response arrives, the API resumes execution at the statement that follows the PemnBPutStream() function call If the PemnBPutStream() function wait time expires, the PemnBPutStream() function returns an error message and the API resumes execution with the statement that follows the PemnBPutStream() function call.
10-4
PATROLAPI
Reference Manual
The PemnPutStream() function returns 1 if the character stream was successfully sent to the PATROL Agent and 0 if it was not. The PemnBPutStream() function returns the string PEMN_OK if the character stream was successfully sent to the PATROL Agent and an API message string if it was not.
10-5
10-6
PATROLAPI
Reference Manual
11
11 12
This chapter describes the Pemn miscellaneous function calls.
11
PemnCheckInit(). . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 11-2 PemnGetLastMessage() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 11-3 PemnRegisterUserMessageHandler(). . . . . . . . . . . . . . . . . . . . . . . . 11-4
11-1
PemnCheckInit()
Verify initialization, or initialize the PEM library.
Synopsis
include <pemapi.h> int PemnCheckInit(void);
Description
The PemnCheckInit() function veries that the PEM library is initialized and initializes it if it is not. The PemnCheckInit() function returns 1 if it found the PEM library was initialized, and 0 if it found that it was not initialized.
11-2
PATROLAPI
Reference Manual
PemnGetLastMessage()
Return the last message issued by the API.
Synopsis
char * PemnGetLastMessage(void)
Description
The PemnGetLastMessage() function returns the last error, warning, or information message string issued by the API.
11-3
PemnRegisterUserMessageHandler()
Register a message processing function with the API.
Synopsis
void PemnRegisterUserMessageHandler( PemnUserMessageHandler pMessageHandler );
Parameter
Parameter
pMessageHandler
Description
Character string name of the message handling routine.
Description
The PemnRegisterUserMessageHandler() function registers a user-created routine with the API that the API will call to process information, warning, and error messages. The message handler uses the type denition PemnUserMessageHandler (see PemnUserMessageHandler on page 3-34 for more information.)
11-4
PATROLAPI
Reference Manual
12
12 13
Specic Blocking Mode Functions 12

This chapter describes the blocking mode functions for specic purposes such as exiting a function call and retrieving the current blocking function default waiting time. PemnBExitFunction(). . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 12-2 PemnBGetTimeout(). . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 12-3 PemnBSetTimeout() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 12-4
Specic Blocking Mode Functions
12-1
PemnBExitFunction()
Exit a function that is blocked awaiting a response.
Synopsis
#include <pemapi.h> void PemnBExitFunction(void);
Description
The PemnBExitFunction() function can be called from the program signal handler (for example, SIGINT) to abort a blocking mode operation.
12-2
PATROLAPI
Reference Manual
PemnBGetTimeout()
Return the default waiting time in milliseconds for blocking operations.
Synopsis
#include <pemapi.h> int PemnBGetTimeout(void);
Description
The PemnBGetTimeout() function returns the integer value in milliseconds that is currently in use as the default waiting time for blocking mode operations.
Specic Blocking Mode Functions
12-3
PemnBSetTimeout()
Set the default waiting time in milliseconds for blocking operations.
Synopsis
#include <pemapi.h> void PemnBSetTimeout(int iNewDefaultTimeout);
Parameter
Parameter
iNewDefaultTimeout
Description
Number of milliseconds that blocking mode functions will wait for a response from the PATROL Agent. The minimum permitted value is 100. Default: If no iNewDefaultTimeout has been specied, the blocking functions use 60000 milliseconds, or 1 minute.
Description
The PemnBSetTimeout() function sets the default timeout value used by the blocking functions to wait for a response from the PATROL Agent.
Example
The following example shows how the default wait time is used in a function that executes a PSL statement in the PATROL Agent:
PemnBPslExec(hComm,USE_DEFAULT_TIMEOUT,0,"GET_VARS(\"/\");")
12-4
PATROLAPI
Reference Manual
13
13 14
Extended Security Interface
13
This chapter describes the extended security interface (ESI) for PATROL and its capabilities for enhancing PATROL security. The following topics are discussed: Overview. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 13-3 ESI Files . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 13-3 ESI Examples . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 13-4 Supported Platforms . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 13-4 ESI Operation . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 13-5 Implementing ESI to Enhance PATROL Security . . . . . . . . . . . . . . 13-7 Creating the ESI Library . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 13-7 Building Shared Libraries on Unix . . . . . . . . . . . . . . . . . . . . . . 13-10 Conguring ESI on OpenVMS, OS/2, and Unix Systems. . . . . 13-11 Conguring ESI on a Windows NT System . . . . . . . . . . . . . . . 13-13 ESI Data Structures . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 13-15 BMC_Sec_Plugin . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 13-15 esi_Context() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 13-16 ESI Data Type Denitions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 13-16 EsiAcceptProc . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 13-16 EsiConnProc . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 13-18 EsiQueueMessageProc. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 13-19 EsiSendProc . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 13-20 ESI Functions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 13-21 esi_AllocateContext() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 13-21 esi_Connect() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 13-22 esi_FreeContext(). . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 13-24 esi_GetVersion() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 13-25 esi_IsClient() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 13-26
13-1
esi_IsEstablished() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .13-27 esi_IsTrusted() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .13-28 esi_Read(). . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .13-29 esi_ServerInit() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .13-31 esi_ValidateAccount() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .13-32 esi_Write() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .13-33 SdkInit() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .13-35 PATROL Event Log Messages . . . . . . . . . . . . . . . . . . . . . . . . . . . . .13-36
13-2
PATROLAPI
Reference Manual
Overview
The extended security interface (ESI) provides you with the option of implementing security enhancements. ESI is an interface denition provided to allow you to implement a shared library. This shared library is loaded by PATROL at startup to provide varying degrees of user authentication and message encryption according to your needs.
ESI Files
The ESI les listed in Table 13-1 are provided you on the PATROL product CD.
Table 13-1 ESI Files
File name
esiapi.h
Description
This le denes functions to be used in the ESI implementation, their respective return codes, and the data types to be used by PATROL for run-time function resolution. Both PATROL and the ESI library use this le. This le denes types of functions to be passed by PATROL to the ESI library for internal invocation; it also denes the data structure to be used as a mandatory eld in the data structure that denes the security context. Both PATROL and the ESI library use this le.
esitypes.h
13-3
ESI Examples
The ESI examples listed in Table 13-2 are provided in Appendix E, ESI Examples to help you develop your ESI implementation.
Table 13-2 ESI Examples
File name
esiapi_impl.h
Description
This le denes the context data structure that contains the mandatory eld required by PATROL. The mandatory eld can neither be modied nor initialized by a customer. This le is used by the ESI library only (see the BMC example in Appendix E, ESI Examples ). This text le is the BMC example le and represents a full ESI library implementation based on MIT Kerberos version 5. (see the BMC example in Appendix E, ESI Examples ).
esiapi_impl.c
Supported Platforms
ESI is available on all PATROL Agent platforms that are supported in the current PATROL release. However, building ESI libraries and implementing ESI varies on different platforms.
13-4
PATROLAPI
Reference Manual
ESI Operation
PATROL interacts with ESI as follows: At startup, PATROL loads the ESI library and calls esi_GetVersion(). If this call returns a satisfactory result (a match of at least major version numbers of the ESI library), PATROL proceeds with use of the library-provided functions. PATROL calls esi_ServerInit(). If this call returns a satisfactory result, the PATROL Agent is ready for further communication. The client (PATROL Console, PATROL Command Line Interface, or PATROLWATCH) attempts to obtain a context for a connection with the server (PATROL Agent) by calling esi_AllocateContext(). If the call returns a satisfactory result, the context is established. The client calls esi_Connect() to establish communication. If this call returns a satisfactory result, the client connects to the server. When esi_Connect() discovers that the connection has been successfully established, it calls the application connect callback (provided as a parameter) to notify the client application of the established connection. Once the server has accepted the connection, it calls esi_AllocateContext(). If this call returns a satisfactory result, PATROL populates the BMC elds of the allocated context and proceeds. Both the client and the server call esi_Read() and esi_Write() while establishing the connection. If esi_Read() returns ESI_CONTINUE, then PATROL assumes that negotiation is still taking place. If esi_Read() returns ESI_OK, then the incoming data is passed to the application. If esi_Read() returns ESI_ERR, the connection will be terminated. If esi_Write() returns a satisfactory result, the message is successfully placed in the PATROL outbound queue. If esi_Write() returns an unsatisfactory result, communication will be terminated.
13-5
When a transport-level connection has been established, the client attempts to log in. The server receives the login information and checks whether the connection over which information arrived is trusted by calling esi_IsTrusted(). If this call returns a satisfactory result, the client makes the next call. The server calls esi_GetPeerName() and allows login under the name provided by this function. If this call returns a satisfactory result, PATROL is ready for regular message exchange using only the esi_Read() and esi_Write() functions. PATROL calls esi_ValidateAccount() (only when this optional function is implemented) if the client submits an execution request under a user name or password combination other than the one originally used to log in.
13-6
PATROLAPI
Reference Manual
Implementing ESI to Enhance PATROL Security

To activate the enhanced security mode in PATROL, you must create an ESI library that implements the ESI functions and congure PATROL to load the ESI library.
Creating the ESI Library

To create an ESI library to implement the ESI functions consists of the following tasks:
ESI Functions
determine what functions you need create the source les and build the library
The functions to include in the ESI library can be either mandatory or optional. You must implement either all or none of the mandatory functions, and you can implement the optional functions as your needs dictate.
Mandatory ESI Functions
Mandatory functions are used in negotiations for communication and for the message exchange that follows. In addition, although the esi_GetVersion() function cannot be relayed to any of these groups of functions, it is mandatory because it is used by PATROL to verify that the version of the ESI library that is supported by PATROL and the version of the library that is provided by a user match. The mandatory functions are listed in Table 13-3. For detailed explanations of each function, see ESI Functions on page 13-21.
13-7
Table 13-3
Mandatory ESI Functions
Function
esi_AllocateContext() esi_Connect() esi_FreeContext() esi_GetVersion() esi_IsClient() esi_IsEstablished() esi_IsTrusted() esi_Read() esi_ServerIni()t esi_Write()
Description
allocates the connection context receives call from a client that is attempting to connect releases connection context veries the version number of the ESI library determines whether the context belongs to the client or to the server conrms that the secured connection is established conrms that the connection is trusted receives call from read callback provides for initialization on the server side receives call from write callback
Mandatory functions must be included or excluded from your ESI implementation as a whole. When you implement all mandatory functions, PATROL operates in extended security mode. When you implement none of the mandatory functions, PATROL presumes that the entire functionality represented by the mandatory functions is not supported, and it will proceed with partial extended security support in which only the optional functions you implemented, if any, are provided. If you attempt to implement only some of the mandatory functions, PATROL will stop loading the ESI library, and the PATROL Agent will terminate. Even if you need the functionality provided by only some of the mandatory functions, you must implement the all of the mandatory functions and use the appropriate stubs as indicated in the following example for the functions you do not need:
esi_Write ( . . .) { return ESI_OK; }
13-8
PATROLAPI
Reference Manual
Optional ESI Functions
You can use the optional functions for some initialization, cleanup, and account verication. Table 13-4 lists the optional functions. For detailed explanations of each function, see ESI Functions on page 13-21.
Table 13-4 Optional ESI Functions
Function
esi_ValidateAccount() SdkInit()
Description
provides for user name and password validation provides for custom initialization
You can include or exclude optional functions from your implementation according to your needs.
ESI Library Source
Create an appropriate source le, or source les, to implement the ESI functions using the BMC examples provided in Appendix E, ESI Examples as a model.
13-9
Building Shared Libraries on Unix

To implement ESI for PATROL on Unix, you must build your shared library on a specic platform. Your build platform will depend on your target platform and component (PATROL Agent or Console). For example, to build an ESI library for an HP 11 (32 bit) agent and console, you must build the library on HP 10.20. Table 13-5 lists the build platform that is required for specic target platforms and components:
Table 13-5 Unix Build Platforms for Shared Libraries
Target Platform Build Platform

AIX 4.1
Agents
AIX 4.1 AIX 4.2 AIX 4.3 (32 bit) AIX 4.3 (64 bit) HP 10.20 HP 11(32 bit) HP 11 (64 bit) Solaris 2.5 Solaris 2.51
Consoles
AIX 4.1 AIX 4.2 AIX 4.3 (32 bit) AIX 4.3 (64 bit)
AIX 4.3 (64 bit) HP 10.20
HP 10.20 HP 11 (32 bit) HP 11 (64 bit)
HP 11 (64 bit) Solaris 2.5
Solaris 2.5 Solaris 2.51 Solaris 2.6 Solaris 7
Solaris 2.6 UNIXWARE 2.1 Solaris-intel 2.6 DYNX/ptx 4.2 IRIX 6.2
Solaris 2.6 Solaris 7 UNIXWARE 2.1 UNIXWARE 7.0 Solaris-intel 2.6 Solaris-intel 2.7 DYNX/ptx 4.2 DYNX/ptx 4.4 IRIX 6.2 IRIX 6.4 IRIX 6.5
13-10
PATROLAPI
Reference Manual
Conguring ESI on OpenVMS, OS/2, and Unix Systems Summary:

In this task, you will activate extended security mode on a OpenVMS, OS/2, or Unix system by setting the appropriate conguration variable and by placing the path and name of your ESI library in the patrol.conf le.
Before you begin
Verify the path to and the name of the ESI library you created. Determine which machines must be congured to use ESI.
To congure your machine to use the ESI Library Step 1
Access the patrol.conf le and edit it to include path to and the name of the le you created to provide the ESI library implementation, as shown in the following example: esi_lib = /usr/users/username/lib/esi.so
Warning
The spaces before and after the equal sign (=) are required.
Step 2
Place the patrol.conf le on the machine where the PATROL Agent, the PATROL Console, or any PATROL client runs. Table 13-6 lists the required location of the patrol.conf le on each operating system:
Table 13-6 patrol.conf File Location
System
OpenVMS OS/2 Unix
File Location
sys$system:PATROL.CONF
boot_directory\os2\system\patrol.conf
/etc
13-11
Step 3
Check, and if necessary, set the ExtendedSecurityEnabled ag under AgentSetup in the conguration database. At either the session initialization stage or the user validation stage, or both, PATROL will attempt to load and use the ESI library, based on the information in the patrol.conf le and the setting of the ExtendedSecurityEnabled ag: If the information in the patrol.conf le is correct and the library is in place, PATROL will load the library and operate in extended security mode, without verifying the ExtendedSecurityEnabled ag setting. If the information in the patrol.conf le is incorrect or the library is not in place, PATROL will verify the ExtendedSecurityEnabled ag setting: If the ag is set to no (the default), PATROL, will proceed in regular security mode. If the ag is set to yes, the PATROL Agent will log an error and terminate.
Tip
To ensure that PATROL will not run without the ESI library, set the ExtendedSecurityEnabled ag to yes.
13-12
PATROLAPI
Reference Manual
Conguring ESI on a Windows NT System Summary:

In this task, you will activate extended security mode on a Windows NT system by setting the appropriate conguration variable and by placing the name and location of the ESI library in the Windows NT registry using the PATROL Client Conguration Utility.
Before you begin
Verify the path to and the name of the ESI library you created. Make sure you have administrator privileges before running the PATROL Client Conguration Utility. The utility requires administrator-level permissions to modify the machine registry. Determine which machines must be congured to use ESI.
To congure your machine to use the ESI Library on Windows NT Step 1
From either the Start Menu shortcut in the BMC Software program group or Windows NT Explorer, start the PATROL Client Conguration Utility (PCCFG.EXE). (The executable is located in the \bin directory under %PATROL_HOME%.) The PATROL Client Conguration dialog box displays:
Figure 13-1 PATROL Client Conguration Dialog Box

13-13
Step 2
Click the ESI Library tab. PATROL displays the currently registered ESI Library le (if any).
Step 3
Click Browse and navigate to the directory containing the ESI Library le. Click Register to update your machine registry. Click Close. Check, and if necessary set, the ExtendedSecurityEnabled ag under AgentSetup in the conguration database. At either the session initialization stage or the user validation stage, or both, PATROL will attempt to load and use the ESI library, based on the information in the Windows NT registry and the setting of the ExtendedSecurityEnabled ag: If the information in the Windows NT registry is correct and the library is in place, PATROL will load the library and operate in extended security mode, without verifying the ExtendedSecurityEnabled ag setting. If the information in the Windows NT registry is incorrect or the library is not in place, PATROL will verify the ExtendedSecurityEnabled ag setting: If the ag is set to no (the default), PATROL, will proceed in regular security mode. If the ag is set to yes, the PATROL Agent will log an error and terminate.
Tip
Step 4 Step 5 Step 6
To ensure that PATROL will not run without the ESI library, set the ExtendedSecurityEnabled ag to yes.
13-14
PATROLAPI
Reference Manual
ESI Data Structures

This section describes the data structures used within the ESI function denitions.
BMC_Sec_Plugin
This structure is to be used as the mandatory eld in the context data structure.
Synopsis typedef struc_BMC_Sec_Plugin{ ...... ...... }BMC_Sec_Plugin; Description
The BMC_Sec_Plugin structure is used by PATROL and must be part of the esi_Context() structure (See esi_Context() on page 13-16.). You should not initialize or modify this structure.
13-15
esi_Context()
The esi_Context() structure denes the security context associated with a PATROL communication session.
Synopsis struct esi_Context{ /*mandatory BMC field*/ BMC_Sec_Plugin plugin: /*Customers portion of context if needed*/ /*INSERT CODE HERE.*/ }; Description
The esi_Context() structure must include the BMC data structure, which cannot be modied or initialized, in the mandatory BMC eld.
ESI Data Type Denitions

This section describes the data type denitions to be used by PATROL for run-time function resolution.
EsiAcceptProc
This data type denition noties PATROL that the nal connection on the server side has been accepted.
Synopsis typedef int (EsiAcceptProc)(int Handle, void* ClientData, void* InfoRec /* unused */);
13-16
PATROLAPI
Reference Manual
Parameters
The following table describes the parameters that EsiAcceptProc contains.

Parameter
Handle
Description
Represents the PATROL session handle, which includes information supplied and used by PATROL to identify the connection Represents the PATROL data, which includes information supplied and used by PATROL to identify the connection Not used
ClientData
InfoRec
Description
The ESI implementation uses EsiAcceptProc to notify PATROL about acceptance of the nal connection on the server side.
13-17
EsiConnProc
Noties PATROL that the connection has been established on the client side.
Synopsis typedef int (*EsiConnProc)(int SesHandle, void* ClientData, void* InfoRec/*unused*/); Parameters
The following table describes the parameters that EsiConnProc contains.

Parameter
SesHandle
Description
Represents the session handle, which includes information supplied and used by PATROL to identify the connection Represents PATROL data, which includes information supplied and used by PATROL to identify the connection Not used
ClientData
InfoRec
Description
An ESI implementation uses EsiConnProc to notify PATROL that the connection has been established on the client side.
13-18
PATROLAPI
Reference Manual
EsiQueueMessageProc
Returns a changed buffer to PATROL.
Synopsis typedef int (*EsiQueueMessageProc)(void* ClientData, const char* Buffer, usigned int Len); Parameters
The following table describes the parameters that EsiMessageProc contains.

Parameter
ClientData
Description
Represents PATROL data, which includes information supplied and used by PATROL to identify the connection A pointer to a buffer that contains a PATROL message A pointer to the length of the PATROL message
Buffer Len
Description
An ESI implementation uses EsiMessageProc to return a changed buffer to PATROL by placing the passed buffer into the PATROL outbound queue. This structure is used primarily in lters. (See esi_Write() on page 13-33..)
Note
When an ESI implementation must send its own data, such as a security token, use EsiSendProc.
13-19
EsiSendProc
Sends data to the communication peer.
Synopsis typedef int (*EsiAcceptProc)(int Handle, void* ClientData, void* InfoRec /*unused */); Parameters
The following table describes the parameters that EsiSendProc contains.

Parameter
Handle
Description
Represents the PATROL session handle, which includes information supplied and used by PATROL to identify the connection Represents PATROL data, which includes information supplied and used by PATROL to identify the connection Not used
ClientData
InfoRec
Description
An ESI implementation uses EsiSendProc to send its own data, such as security tokens, to the peer.
13-20
PATROLAPI
Reference Manual
ESI Functions
This section describes the functions to be provided by an ESI implementation.
esi_AllocateContext()
This mandatory function allocates and initializes the user-dened portion of the connection context.
Synopsis esi_ContextPtr esi_AllocateContext(int client_server); Parameters
The following table describes the parameters that esi_AllocateContext() contains.

Parameter
client_server
Description
Denes whether a request for context allocation is coming from server or client. (The BMC example stores this information in the user-dened portion of context structure for later use.)
Description
PATROL calls the esi_AllocateContext() function to allocate the context for each connection and initialize the user-dened portion of the context. This function returns either a pointer to an allocated context if it is successful or NULL if it fails.
13-21
esi_Connect()
PATROL calls this mandatory function on the client side when the transport-level connection is established.
Synopsis esi_RetCode esi_Connect(EsiSendProc Send_f , int Handle , esi_ContextPtr ctx , void* connectClientData , EsiConnProc connect_cb); Parameters
The following table describes the parameters that esi_Connect() contains.

Parameter
Send_f
Description
The parameter that can be used for direct data transmission that bypasses the application level. This function must be called as follows: (*Send_f)(Handle, buffer_2_send, len_of_buffer_2_send); (In the BMC example, Send_f is used during initial negotiation for establishing the connection.) The PATROL session handle necessary when calling to Send_f and to application-level callback connect_cb. The context allocated and returned by esi_AllocateContext. The PATROL data to be passed to application-level connect_cb as is. The application-level callback that noties PATROL when the transport-level connection is successfully established. This function must be called as follows: (*connect_cb)(Handle, connectClientData, NULL);
Handle
ctx connectClientData connect_cb
13-22
PATROLAPI
Reference Manual
Description
The esi_Connect() function is called by application-level connect callback in order to provide a custom interface for connection negotiation. This function returns ESI_OK if connected and ESI_ERR if it is not.
13-23
esi_FreeContext()
This mandatory function releases the context allocated by esi_AllocateContext().
Synopsis void esi_FreeCtx(esi_ContextPtr ctx); Parameters
The following table describes the parameters that esi_FreeContext() contains.

Parameter
ctx
Description
The context allocated and returned by esi_AllocateContext()
Description
When the client-server connection terminates, PATROL uses the esi_FreeContext() function to release the security context associated with a session. The ESI implementation should provide this function in such a way that PATROL will be able to release the memory allocated for each connection in esi_AllocateContext(). The esi_FreeContext() function returns Void.
13-24
PATROLAPI
Reference Manual
esi_GetVersion()
This mandatory function veries the version of the ESI library as dened in the esiapi.h le.
Synopsis int esi_GetVersion(int major); Parameters
The following table describes the parameters that esi_GetVersion() contains.

Parameter
major
Description
The major or minor version dened in esiapi.h.
Description
In order to implement the esi_GetVersion() function, you must use the macro denition ESI_VERSION_IMPL from the esiapi.h le. (See the BMC example in Appendix E, ESI Examples ). According to the major parameter, this function will return the major version number if the value of major is ESI_TRUE and will return the minor version number if the value of major is ESI_FALSE.
13-25
esi_IsClient()
This mandatory function veries whether the context belongs to the client or the server.
Synopsis int esi_IsClient (esi_ContextPtr ctx); Parameters
The following table describes the parameters that esi_IsClient() contains.

Parameter
ctx
Description
Description
PATROL uses the esi_IsClient() function for internal purposes. This function returns 1 for the client and 0 for the server. In the BMC example, it returns the value of the eld from within the context structure. This eld holds the ag passed to an ESI library by PATROL during initial connection negotiation.
13-26
PATROLAPI
Reference Manual
esi_IsEstablished()
This mandatory function veries whether the secured connection is actually established.
Synopsis int esi_IsEstablished (esi_ContextPtr ctx ); Parameters
The following table describes the parameters that esi_IsEstablished() contains.

Parameter
ctx
Description
Description
PATROL uses the esi_IsEstablished() function for internal purposes. This function returns ESI_TRUE if the connection is established and ESI_FALSE if it is not. In the BMC example, it returns the value of the eld from within the context structure, which is set if connection negotiation is successfully completed.
13-27
esi_IsTrusted()
This mandatory function veries that the connection is trusted.
Synopsis int esi_IsTrusted(esi_ContextPtr ctx); Parameters
The following table describes the parameters that esi_IsTrusted() contains.

Parameter
ctx
Description
The pointer to the context that was initiated by esi_Allocate() and that is associated with the particular client-server connection
Description
PATROL calls the esi_IsTrusted() function to determine whether the connection is trusted. If the connection is trusted, the PATROL Agent will not verify the user name or password but will provide the client with the account to which the client is connecting. In this case, the agent will call esi_GetPeerName() for the account name. The esi_IsTrusted() function returns 1 if the connection is trusted and 0 if it is not.
13-28
PATROLAPI
Reference Manual
esi_Read()
This function is mandatory. Have PATROL call this function after a message has been read from the network, but before it is passed to the PATROL application code.
Synopsis esi_RetCode esi_Read (char** buffer, int* len, esi_ContextPtr ctx , EsiSendProc Send_f, int Handle, void* connectClientData, EsiConnProc connect_cb, int* flag); Parameters
The following table describes the parameters that esi_Read() contains.

Parameter
buffer
Description
A pointer to the buffer provided by PATROL. The buffer receives nonencrypted incoming messages (an encrypted message traveling across the network must be decrypted before it is passed on to PATROL). A pointer to the length of the buffer returned in buffer. The buffer must have the valid length of the nonencrypted message when the function returns. The context allocated and returned by esi_AllocateContext(). The function that can be used for direct data transmission that bypasses the application level. The function must be called in the following manner: (*Send_f)(Handle, buffer_2_send, len_of_buffer_2_send); (In the BMC example, this parameter is used during initial negotiation for establishing the connection.) The PATROL session handle required when calling to Send_f and to application-level callback connect_cb.
len
ctx Send_f
Handle
13-29
Parameter
connect_cb
Description
Application-level callback that is called to notify PATROL that a transport-level connection has been established; connect_cb must be called as follows: (*connect_cb)(Handle, connectClientData, NULL); The PATROL data to be passed to application-level connect_cb as is. A pointer to a ag that indicates to PATROL whether the buffer in buffer must be released by PATROL (the buffer could be dynamic or static, and each type requires different treatment).
connectClientData ag
Description
The esi_Read() function is used in the following ways: For security negotiation during the ESI handshake. In the BMC example, Send_f is used at the negotiation stage for direct token exchange. Send_f returns ESI_CONTINUE if the token exchange is successful or ESI_ERR if it is not. For trafc decryption during the regular PATROL protocol. In this case, the function must place a decrypted message in the buffer, with the message length indicated in len. The buffer will be copied by PATROL. The ESI library is responsible for releasing all buffers associated with internal message handling. If a message in the buffer was dynamically allocated and PATROL must release it, the ag should be set to ESI_TRUE. Otherwise, PATROL assumes that freeing this buffer is the responsibility of ESI. In this case, esi_Read() returns ESI_OK if it is successful or ESI_ERR if it is not.
13-30
PATROLAPI
Reference Manual
esi_ServerInit()
This function is mandatory. Use this function to initialize the server side, if necessary.
Synopsis esi_RetCode esi_ServerInit(char* serverName); Parameters
The following table describes the parameters that esi_ServerInit() contains.

Parameter
serverName
Description
The name of the service
Description
PATROL calls the esi_ServerInit() function when PATROL initializes its communication in security extended mode. In the BMC example, this function is used for building the service name and obtaining service credentials. The esi_ServerInit() function returns ESI_OK if successful or ESI_ERR if not.
13-31
esi_ValidateAccount()
This optional function validates user names and passwords.
Synopsis esi_RetCode esi_ValidateAccount(const char* name, const char* password ); Parameters
The following table describes the parameters that esi_ValidateAccount() contains.

Parameter
name password
Description
The name of the user trying to connect The password provided by the user
Description
PATROL uses the esi_ValidateAccount() function for user authentication. This function returns the following codes: ESI_OK if the user is authenticated and no further validation is required. ESI_ERR if the user is not authenticated and the connection fails. ESI_CONTINUE if the user was not authenticated but PATROL is continuing its attempt to authenticate the user on the OS level.
13-32
PATROLAPI
Reference Manual
esi_Write()
This function is mandatory. Have PATROL call this function after creating a protocol message but before transmitting it to a network.
Synopsis esi_RetCode esi_Write (unsigned char** buffer, int* len, esi_ContextPtr ctx , void* data, EsiQueueMessageProc queue_msg_fn); Parameters
The following table describes the parameters that esi_Write() contains.

Parameter
buffer len ctx data queue_msg_fn
Description
A pointer to a buffer containing a PATROL message A pointer to the length of the PATROL message The context allocated and returned by esi_AllocateContext() PATROL data to be passed to queue_msg_fn as is A function for sending a message from PATROL and using the PATROL outbound message queue. This function must be called as follows:(*queue_msg_fh)(data, buffer_2_send, len_of_buffer_2_send);
13-33
Description
The esi_Write() function can be used for establishing a connection or during regular data exchange. In the BMC example, it is used for initial connection negotiation, and, in this case, the message in the buffer is sent out with no change. During regular data ow, the message in the buffer is encrypted before it is placed in the PATROL outbound queue by queue_msg_fn. The ESI library is responsible for releasing all dynamic buffers associated with internal message handling. The esi_Write() function returns ESI_OK if it is successful and ESI_ERR if it is not.
13-34
PATROLAPI
Reference Manual
SdkInit()
This optional function performs custom initialization.
Synopsis void SdkInit (void) Description
If SkdInit() is included in the ESI implementation, it is called by called by PATROL, normally for initialization requested by the user.
13-35
PATROL Event Log Messages

Table 13-7 lists the ESI-related messages that can appear in the PATROL event log and the reasons for those messages.
Table 13-7 ESI Message in PATROL Event Log
Message
Version mismatch MAJOR Version mismatch MINOR
Description
The major part of the version identier between the PATROL and the ESI library does not match. PATROL will not load the library. The minor part of the version identier between the PATROL and the ESI library does not match. PATROL loads the ESI library and logs this warning. PATROL could not parse the patrol.conf le, and the ESI library name is not resolved. The esi_lib name may be missing or misplaced. PATROL could not parse the patrol.conf le, and the ESI library name is not resolved; possibly the equal sign (=) sign is missing or misplaced. PATROL could not parse the patrol.conf le, and the ESI library name is not resolved. The path to or the name of the ESI library is missing or has the wrong syntax. PATROL could not resolve a function in the ESI library that was loaded. This may cause termination of the PATROL Agent. PATROL could not load the ESI library, and the ExtendedSecurityEnabled ag is set to yes. This results in termination of the PATROL Agent. After successfully loading the ESI library, PATROL has detected that some of the mandatory functions are provided and some are not. This results in termination of the PATROL Agent.
Context: Bad object name Context: Bad operation - should be ' = ' Context: Bad value
Function <name> ... not resolved Could not load Extended Security Library! Exiting... PATROL Agent will terminate due to unresolved functions that are mandatory in the ESI library
13-36
PATROLAPI
Reference Manual
14
14 15
14
This chapter provides information about accessing the PATROL Agent through the Component Object Model/Distributed Component Object Model (COM/DCOM) interface. The following topics are discussed: Overview. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 14-3 COM/DCOM Files . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 14-4 Conguring the PATROL COM/DCOM Interface . . . . . . . . . . . . . . 14-4 Conguring COM Servers . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 14-4 Conguring DCOM Clients . . . . . . . . . . . . . . . . . . . . . . . . . . . . 14-6 Accessing the PATROL Agent COM Server . . . . . . . . . . . . . . . . . . 14-6 Through the Dispatch Interface . . . . . . . . . . . . . . . . . . . . . . . . . 14-7 Through a Custom Interface Program . . . . . . . . . . . . . . . . . . . . 14-8 IPatrolAgent Interface Functions . . . . . . . . . . . . . . . . . . . . . . . . . . . 14-10 annotate() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 14-12 annotate_get() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 14-14 blackout() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 14-16 change_state() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 14-18 create() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 14-20 destroy() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 14-22 exists() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 14-24 get() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 14-26 getenv() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 14-28 get_psl_errno() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 14-30 get_ranges() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 14-31 get_vars() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 14-33 history() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 14-35
14-1
is_var() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 14-37 PslExecute() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 14-39 print() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 14-41 set() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 14-43 set_alarm_ranges() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 14-45 unset() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 14-47
14-2
PATROLAPI
Reference Manual
Overview
This chapter describes the Component Object Model/Distributed Component Object Model (COM/DCOM) programming interface. The COM/DCOM interface, which is available for Windows NT only, provides developers of COM-compatible applications access to data collected by one or more PATROL Agents. The PATROL Agent for Windows NT is a local COM server. The agent provides COM\DCOM functionality through the IPatrolAgent, an interface that allows you to access and use PATROL data through COM-compatible applications. For additional information about programming using the COM/DCOM protocol, refer to the Microsoft World Wide Web site at http://www.microsoft.com. An application can access the IPatrolAgent Interface by two methods: Through the agents dispatch interface using a VisualBasic (VB) script or another script that supports OLE automation. Through a custom interface using a C++/C program.
This chapter describes The les provided to support COM functionality Accessing the IPatrolAgent interface using either a dispatch interface or a custom interface The functions that comprise the COM API
Note
Because most of the functions in the COM/DCOM API are based on PSL functions, you should use this chapter along with the PATROL Script Language Reference Manual.
14-3
COM/DCOM Files
PATROL provides the COM/DCOM les listed in Table 14-1.
Table 14-1 PATROL COM/DCOM Files
File name
ipa.h ipa_i.c
Description
This le denes the IPatrolAgent interface. It is installed in the $PATROL_HOME/com directory. This le denes the UUID for the agent COM server. It is installed in the $PATROL_HOME/com directory. This le is the type library. If you use this le, you must place it in the $PATROL_HOME/bin directory on the server machine. In addition, on client machines, you must set the location of the le in the Windows NT registry using the PATROL Client Conguration utility (PCCFG.EXE).
ipa.tlb
Conguring the PATROL COM/DCOM Interface

Before you can use your application (DCOM client) to access data on one or more PATROL Agents (COM servers), you must congure the machines hosting PATROL Agents (COM servers) and the machines hosting your application (DCOM clients).
Conguring COM Servers

You congure the machines hosting PATROL Agents (COM servers) either by setting the PATROL Agent COM conguration variables and/or by running the Microsoft DCOM conguration utility (DCOMCFG.EXE).
PATROL Agent COM Conguration Variables
The two PATROL Agent conguration variables described in Table 14-2 apply to the COM server:
14-4
PATROLAPI
Reference Manual
Table 14-2
PATROL Agent COM Variables
Variable
comUserAllowed
Description
Controls who can access the PATROL Agent COM server. Listed users, members of groups, and the user who started the agent may access the agent COM server. The following values are valid: Empty String (default) Group Names User Names Each entry must be separated by the pipe character (|) and no space because a space is a valid character for group and user names. Example: Patrol|Domain Users|patrol-adm This variable, supported only on Windows NT 4.0, takes precedence over any security set by the Microsoft DCOM Conguration Utility. If you set this variable to the empty string, security is set by the DCOM Conguration Utility. NOTE: If you set this variable, it is not necessary to run the DCOM conguration utility. Controls the level of information provided by the PATROL Agent to the DCOM client. The following values are valid: N - No DCOM interface allowed (default) R - DCOM client can receive data from the client W - DCOM client can receive and change data on the client F - DCOM client can receive and change data and use PslExecute() to run OS commands. NOTE: You must this variable if you want to use the COM interface.
comSecurityLevel
For detailed information about these variables and procedures for setting them, refer to the PATROL Agent Reference Manual.
Microsoft DCOM Conguration Utility
You run the Microsoft DCOM Utility on each PATROL Agent with which your DCOM application needs to communicate but only if you do not set the comUserAllowed variable. The comUserAllowed variable takes precedence over conguration set by the Microsoft DCOM Utility.
14-5
For information on obtaining the Microsoft DCOM Utility and instructions for using it to congure PATROL Agents, refer to the PATROL Agent Reference Manual.
Conguring DCOM Clients

You congure the machines hosting your application (DCOM clients) to communicate with the PATROL Agent by running the PATROL Client Conguration Utility (PCCFG.EXE). You do not need to do so, however, if the PATROL Agent is installed on the same machine that is running your DCOM application. For instructions on conguring your machine using the PATROL Client Conguration Utility, refer to the PATROL Agent Reference Manual
Accessing the PATROL Agent COM Server

You access the PATROL Agent COM server through the IPatrolAgent interface. Denition of the IPatrolAgent interface (in the ipa.h le) includes 18 functions that are based on PSL functions:
14-6 PATROLAPI
annotate() annotate_get() blackout() change_state() create() destroy() exists() get() getenv() get_ranges() get_vars() history() is_var() print() PslExceute() set()
Reference Manual
set_alarm_ranges() unset()
In addition to the functions based on PSL functions, the IPatrolAgent interface also includes the following function that allows you to get the error number of the PSL process: get_psl_errno()
How you invoke the IPatrolAgent interface functions and the format of their return values depends on whether you access the PATROL Agent COM server with a dispatch interface, such as a VB script, or with custom interface, such as a C++/C program. For detailed information about the IPatrolAgent interface functions see IPatrolAgent Interface Functions on page 14-10.
Through the Dispatch Interface

A client can access the PATROL Agent COM server through the dispatch interface using any script that supports OLE automation, such as a VB script. The dispatch interface is the same interface through which a PSL script accesses the PATROL Agent using PSL functions. Therefore, your script must invoke the IPatrolAgent interface functions in the same manner as a PSL script invokes PSL functions. When you develop your script, observe the following guidelines: For the IPatrolAgent interface functions that are based on PSL functions, use strings for the parameters. (These functions will also take strings as their return values.) Do not include a parameter with the [out, retval] attribute; this is the return value this is the return value used by a custom interface. You do not need to include a parameter with an [optional] attribute.
The result is in the same format as returned from PSL function calls. See the PATROL Script Language Reference Manual for detailed descriptions of the functionality, parameters, return values, and return value formats of the PSL functions on which the IPatrolAgent interface functions are based.
14-7
Through a Custom Interface Program

A client can also access the PATROL Agent COM server through a custom interface, such as a C++/C program, that invokes the PSL-based interface functions. A custom interface must invoke the IPatrolAgent interface functions as they are dened. Therefore, when you develop your program, observe the following guidelines: To conform with PSL function prototype, each the PSL-based IPatrolAgent interface functions must take Unicode BSTR strings as its parameters. If a parameter has the [optional] attribute, you cannot omit it from the string, but you can pass NULL to the parameter. If a parameter is required, you cannot pass NULL to it; if you do, the function will return E_INVALIDARG.
IPatrolAgent interface functions will always return HRESULT, which indicates whether the call to the PSL function was successful. HRESULT does not reect the result of the PSL function. HRESULT will return one of the following values: S_OKthe IPatrolAgent interface function call to the PSL function was successful. (You must check the return value in the parameter pbstrResult for the result of the PSL functions execution.) E_POINTERthe IPatrolAgent interface function encountered the NULL pointer and cannot return a value from the PSL function to pbstrResult. E_INVALIDARGone or more of the required parameters is NULL or invalid. E_ACCESSDENIEDthe COM security level set in comSecurityLevel parameter of the agent conguration database does not permit execution of the requested the action.
14-8
PATROLAPI
Reference Manual
The last parameter of the IPatrolAgent interface is a Unicode string dened as BSTR * pbstrResult. This parameter, which has the [out, retval] attribute, usually holds the return value from the PSL function. See the PATROL Script Language Reference Manual for detailed descriptions of the functionality, parameters, return values, and return value formats of the PSL functions on which the IPatrolAgent interface functions are based.
14-9
IPatrolAgent Interface Functions

This section provides the following information about each of the IPatrolAgent interface functions: A brief description of the function An example of how to invoke the function using a custom interface (a C++/C program) A table listing parameters of the functions using the dispatch interface and custom interface names, the attributes dened for each parameter, and brief description of the parameter A table listing the codes returned by HRESULT in a custom interface
For details about invoking a function using a dispatch interface (VB script), detailed information about the parameters for each PSL-based function, and details about the return values of PSL functions, consult the PATROL Script Language Reference Manual.
Examples of Invoking IPatrolAgent Interface Functions
To illustrate the differences between invoking an IPatrolAgent interface function from a dispatch interface and a custom interface, this section shows how to invoke the history() function from both types of interface.
Dispatch Interface
You invoke the history() function through the dispatch interface as you would in a PSL script: Result=object.history(parameter,format,number); Because they are optional, you can omit format and number.
14-10
PATROLAPI
Reference Manual
Custom Interface
You invoke the history() function through a custom interface as follows:

HRESULT history(BSTR bstrItem, BSTR bstrFormat, BSTR bstrCount, BSTR* pbstrResult);
In a custom interface, you cannot omit the optional parameters, but you can pass NULL to them.
14-11
annotate()
This function provides contextual information for a PATROL parameter.
Synopsis HRESULT annotate(BSTR bstrName, BSTR bstrFormat, VARIANT* pvarData, BSTR* pbstrResult); Parameters
The following table describes the parameters that annotate() contains.

Parameter Custom Interface
bstrName bstrFormat pvarData
Dispatch Interface
parameter format datan
Attributes*
[in] [in, optional] [in, optional]
Description
The name of the parameter for which annotation information is specied. A mnemonic indicating the type of display for the specied annotation information. A safe array of VARIANT. The type of each VARIANT element is the Unicode BSTR string. See Appendix F, Example of annotate() Function, for an example of how to construct this argument for a custom interface. The result of the call to the PSL function. The parameter will contain NULL if annotate() is successful and an error message if it is not.
pbstrResult
NA
[out, retval]
*Attributes are included in the denition of the IPatrolAgent interface.
Refer to the PATROL Script Language Reference Manual for details about the values contained in pbstrResult.
14-12
PATROLAPI
Reference Manual
Return Values
HRESULT for this function returns the following codes:

Return Value
S_OK
Description
The call to the PSL function was successful. Check the parameter pbstrResult for the return value from the PSL function. The parameter pbstrResult is a NULL pointer. The parameter pvarData is invalid. The user is not permitted to access the COM server. Check the comUserAllowed setting in the agent conguration le or use the DCOMCFG.EXE utility to determine whether the user has access. The security level does not permit the requested action. Check the comSecurityLevel setting in the agent conguration le.
E_POINTER E_INVALIDARG E_ACCESSDENIED
14-13
annotate_get()
This function returns the annotation for a parameter value.
Synopsis HRESULT annotate_get(BSTR bstrName, BSTR bstrTimestamp, BSTR* pbstrValue); Parameters
The following table describes the parameters that annotate_get() contains.

bstrName bstrTimestamp
Dispatch Interface
parameter timestamp
Attributes*
[in] [in, optional]
Description
The name of the parameter for which annotation information is specied. The BSTR string that identies the timestamp of the parameter value for which annotation information should be returned. The result of the call to the PSL function. The parameter will contain the annotation for the parameter value at timestamp.
pbstrValue
NA
[out, retval]
14-14
PATROLAPI
Reference Manual
Return Values

Return Value
S_OK
Description
The call to the PSL function was successful. Check the parameter pbstrResult for the return value from the PSL function. The parameter pbstrResult is a NULL pointer. The parameter bstrName is invalid. The user is not permitted to access the COM server. Check the comUserAllowed setting in the agent conguration le or use the DCOMCFG.EXE utility to determine whether the user has access. The security level does not permit the requested action. Check the comSecurityLevel setting in the agent conguration le.
14-15
blackout()
This function hides PATROL object state changes for a specic period of time.
Synopsis HRESULT blackout(BSTR bstrInst, BSTR bstrPeriod, BSTR* pbstrResult); Parameters
The following table describes the parameters that blackout() contains. Parameter
Custom Interface
bstrInst bstrPeriod pbstrResult
Dispatch Interface
object period NA
Attributes*
[in, optional] [in, optional] [out, retval]
Description
The name of the PATROL object whose state changes are to be hidden. The length of time the PATROL object is to remain blacked out. The result of the call to the PSL function. The way you specify the bstrInst and bstrPeriod determines the result: The parameter pbstrResult will contain, separated by new line characters, a list of all PATROL objects that are currently blacked out if bstrInst and bstrPeriod are NULL. It will contain the blackout status for the bstrInst if bstrInst is not NULL, and bstrPerid is NULL. The parameter pbstrResult will contain OK if either bstrInst and bstrPeriod is not NULL.
14-16
PATROLAPI
Reference Manual
Return Values

Return Value
S_OK
Description
The call to the PSL function was successful. Check the parameter pbstrResult for the return value from the PSL function. The parameter pbstrResult is a NULL pointer The user is not permitted to access the COM server. Check the comUserAllowed setting in the agent conguration le or use the DCOMCFG.EXE utility to determine whether the user has access. The security level does not permit the requested action. Check the comSecurityLevel setting in the agent conguration le.
E_POINTER E_ACCESSDENIED
14-17
change_state()
This function changes the rule state of a PATROL application instance.
Synopsis HRESULT change_state(BSTR bstrName, BSTR bstrState, BSTR bstrDescr, BSTR* pbstrResult); Parameters
The following table describes the parameters that change_state() contains.

BstrName bstrState bstrDescr pbstrResult
Dispatch Interface
object state description NA
Attributes*
[in] [in] [in, optional] [out, retval]
Description
The name of the application instance whose state is to be changed. The operational state to which bstrName will be set. An optional text string that can be used to explain the state change action. The result of the call to the PSL function. The parameter will contain either the new state or NULL if the function returns an error.
14-18
PATROLAPI
Reference Manual
Return Values

Return Value
S_OK
Description
The call to the PSL function was successful. Check the parameter pbstrResult for the return value from the PSL function. The parameter pbstrResult is a NULL pointer. The parameter bstrName or bstrState is invalid. The user is not permitted to access the COM server. Check the comUserAllowed setting in the agent conguration le or use the DCOMCFG.EXE utility to determine whether the user has access. The security level does not permit the requested action. Check the comSecurityLevel setting in the agent conguration le.
14-19
create()
This function creates a PATROL object.
Synopsis HRESULT create(BSTR bstrName, BSTR bstrLabel, BSTR bstrState BSTR bstrDescr, BSTR bstrParent BSTR* pbstrResult); Parameters
The following table describes the parameters that create() contains.

bstrName bstrLabel
Dispatch Interface
object
Attributes*
[in] [in, optional]
Return Values
The alphanumeric identier for the object to be created. An optional text string that can be used to identify the object. Label appears below the objects icon. The optional state of the object that is assigned at its creation. An optional text string that can be used to introduce the newly created object. An optional text string that species the parent to which the created object will belong The result of the call to the PSL function. The parameter will contain the bstrName if it creates the instance or NULL if an error occurs.
bstrState bstrDescr bstrParent
[in, optional] [in, optional] [in, optional]
pbstrResult
NA
[out, retval]
14-20
PATROLAPI
Reference Manual
Return Values

Return Value
S_OK
Description
14-21
destroy()
This function destroys a PATROL object.
Synopsis HRESULT destroy(BSTR bstrName, BSTR bstrDescr, BSTR* pbstrResult); Parameters
The following table describes the parameters that destroy() contains.

bstrName bstrDescr pbstrResult
Dispatch Interface
object description NA
Attributes*
[in] [in, optional] [out, retval]
Return Values
The alphanumeric identier for the object to be destroyed. An optional text string that can be used to explain why the object was destroyed. The result of the call to the PSL function. The parameter will contain TRUE if destroy() is successful and FALSE if the function returns an error.
14-22
PATROLAPI
Reference Manual
Return Values

Return Value
S_OK
Description
14-23
exists()
This function veries the existence of a PSL object.
Synopsis HRESULT exists(BSTR bstrName, BSTR bstrInherit, BSTR* pbstrResult); Parameters
The following table describes the parameters that exists() contains.

bstrName bstrInherit
Dispatch Interface
object inherit
Attributes*
[in] [in, optional]
Description
The alphanumeric identier for the object whose existence is being veried. The string to control whether it will search inheritance in the agent object hierarchy to verify the existence of the object. For TRUE do not search the inheritance hierarchy; for FALSE search the inheritance hierarchy. The result of the call to the PSL function. The parameter contains TRUE if the object exists, and FALSE if it does not.
pbstrResult
NA
[out, retval]
14-24
PATROLAPI
Reference Manual
Return Values

Return Value
S_OK
Description
14-25
get()
This function returns the current value of a variable.
Synopsis HRESULT get(BSTR bstrVariable, BSTR *pbstrResult); Parameters
The following table describes the parameters that get() contains.

bstrVariable pbstrResult
Dispatch Interface
variable NA
Attributes*
[in] [out, retval]
Description
The name of the variable whose current value will be returned. The result of the call to the PSL function. The parameter will contain the value for bstrVariable.
14-26
PATROLAPI
Reference Manual
Return Values

Return Value
S_OK
Description
The call to the PSL function was successful. Check the parameter pbstrResult for the return value from the PSL function. The parameter pbstrValue is NULL pointer. The parameter bstrName is invalid. The user is not permitted to access the COM server. Check the comUserAllowed setting in the agent conguration le or use the DCOMCFG.EXE utility to determine whether the user has access. The security level does not permit the requested action. Check the comSecurityLevel setting in the agent conguration le.
14-27
getenv()
This function returns the string value of a PSL environment variable.
Synopsis HRESULT getenv(BSTR bstrName, BSTR* pbstrResult); Parameters
The following table describes the parameters that getenv() contains.

bstrName pbstrResult
PSL Function
variable NA
Attributes*
[in] [out, retval]
Description
The name of object whose value is to be returned The result of the call to the PSL function. The parameter will contain the string value of the variable in the environment of the PSL script.
14-28
PATROLAPI
Reference Manual
Return Values

Return Value
S_OK
Description
14-29
get_psl_errno()
This function returns the error number of the PSL process. This is a help function; there is no PSL function for it.
Synopsis HRESULT get_psl_errno(long* plRet); Parameters
The following table describes the parameters that get_psl_errno() contains.

Parameter
plRet
Attribute*
[out, retval]
Description
The error number for the PSL process.
*Attributes are dened in the le ipa.c
Return Values

Return Value
S_OK
Description
The call to the PSL function was successful. Check the parameter pbstrResult for the return value from the PSL function. The parameter plRet is a NULL pointer. The user is not permitted to access the COM server. Check the comUserAllowed setting in the agent conguration le or use the DCOMCFG.EXE utility to determine whether the user has access. The security level does not permit the requested action. Check the comSecurityLevel setting in the agent conguration le.
14-30
PATROLAPI
Reference Manual
get_ranges()
This function returns the Border, Alarm1, and Alarm2 range settings for a PATROL parameter.
Synopsis HRESULT get_ranges(BSTR bstrName, BSTR* pbstrResult); Parameters
The following table describes the parameters that get_ranges() contains.

bstrName
Dispatch Interface
param
Attributes*
[in, optional]
Description
The name of the PATROL parameter whose Border, Alarm1, and Alarm2 range settings are to be returned. The result of the call to the PSL function. The parameter will contain the current setting for Border, Alarm1, or Alarm2 range settings for a PATROL parameter.
pbstrResult
NA
[out, retval]
14-31
Return Values

Return Value
S_OK
Description
The call to the PSL function was successful. Check the parameter pbstrResult for the return value from the PSL function. The parameter pbstrResult is a NULL pointer. The user is not permitted to access the COM server. Check the comUserAllowed setting in the agent conguration le or use the DCOMCFG.EXE utility to determine whether the user has access. The security level does not permit the requested action. Check the comSecurityLevel setting in the agent conguration le.
14-32
PATROLAPI
Reference Manual
get_vars()
This function returns the list of variables for a PSL object.
Synopsis HRESULT get_vars(BSTR bstrObj, BSTR bstrKeyword , BSTR* pbstrResult); Parameters
The following table describes the parameters that get_vars() contains.

bstrObj
Dispatch Interface
Object
Attributes*
[in, optional]
Description
The optional name of the object whose variables are to be listed. The default is the current object. An optional keyword that species the information that is to be returned for bstrObj. The result of the call to the PSL function. The parameter will contain the list of the variables of bstrObj or the list of variables for the current object if bstrObj is omitted. The parameter will contain NULL if bstrObj does not exist.
bstrKeyword pbstrResult
Keyword NA
[in, optional] [out,retval]
14-33
Return Values

Return Value
S_OK
Description
The call to the PSL function was successful. Check the parameter pbstrResult for the return value from the PSL function. The parameter pbstrResult is a NULL pointer. The user is not permitted to access the COM server. Check the comUserAllowed setting in the agent conguration le or use the DCOMCFG.EXE utility to determine whether the user has access. The security level does not permit the requested action. Check the comSecurityLevel setting in the agent conguration le.
14-34
PATROLAPI
Reference Manual
history()
This function returns history information from the PATROL history database.
Synopsis HRESULT history(BSTR bstrItem, BSTR bstrFormat, BSTR bstrCount, BSTR* pbstrResult); Parameters
The following table describes the parameters that history() contains.

bstrItem bstrFormat bstrCount
Dispatch Interface
parameter format number
Attributes*
[in, optional] [in, optional] [in, optional]
Description
The name of the object whose history is to be returned. An optional string to specify the format of each history() function entry. An optional string to limit the number of entries the history function will return. The default is 50. The result of the call to the PSL function. The parameter will contain a list of data points followed by a number of entries separated by new line characters.
pbstrResult
NA
[out, retval]
14-35
Return Values

Return Value
S_OK
Description
The call to the PSL function was successful. Check the parameter pbstrResult for the return value from the PSL function. The parameter pbstrResult always contains a NULL pointer. The user is not permitted to access the COM server. Check the comUserAllowed setting in the agent conguration le or use the DCOMCFG.EXE utility to determine whether the user has access. The security level does not permit the requested action. Check the comSecurityLevel setting in the agent conguration le.
14-36
PATROLAPI
Reference Manual
is_var()
This function veries that a PSL object variable exists.
Synopsis HRESULT is_var(BSTR bstrName, BSTR* pbstrResult); Parameters
The following table describes the parameters that is_var() contains.

Dispatch Interface
object NA
Attributes*
[in] [out, retval]
Description
The name of the object that is to be veried as a variable The result of the call to the PSL function. The parameter will contain TRUE if the object exists and is a variable, and FALSE if the object does not exist or is not a variable.
14-37
Return Values

Return Value
S_OK
Description
14-38
PATROLAPI
Reference Manual
PslExecute()
This function starts a PSL process. PslExecute() will return its result before the script nishes running.
Synopsis HRESULT PslExceute(BSTR bstrName, BSTR bstrScript, BSTR *pbstrErrlist, BSTR *pbstrWarnlist, BSTR* pbstrResult); Parameters
The following table describes the parameters that PslExecute() contains.

bstrName bstrScript pbstrErrlist
Dispatch Interface
name PslScript errorlist
Attributes*
[in] [in] [out, optional]
Description
The BSTR string that provides a descriptive identier for the new PSL process. The string that contains the PSL commands to be executed. An optional variable to which the PSL interpreter or compiler will return error messages created while compiling the PSL script. An optional variable to which the PSL interpreter/compiler will return warning messages generated while compiling the PSL script. The result of the call to the PSL function. The parameter will contain 0 if the script has been successfully created and is executing, 1 for compilation errors, and 2 for a process creation error.
pbstrWarnlist
warninglist
[out, optional]
pbstrResult
NA
[out, retval]
14-39
Return Values

Return Value
S_OK
Description
The call to the PSL function was successful. Check the parameter pbstrResult for the return value from the PSL function. The parameter pbstrResult is a NULL pointer. One of the required parameters bstrName and bstrScript is not provided. The user is not permitted to access the COM server. Check the comUserAllowed setting in the agent conguration le or use the DCOMCFG.EXE utility to determine whether the user has access. The security level does not permit the requested action. Check the comSecurityLevel setting in the agent conguration le.
14-40
PATROLAPI
Reference Manual
print()
This function prints text to a computer output window on the PATROL console.
Synopsis HRESULT print(BSTR bstrMsg); Parameters
The following table describes the parameters that print() contains.

bstrMsg
Dispatch Interface
text1...textn
Attributes*
[in]
Description
The text to be printed.
14-41
Return Values

Return Value
S_OK
Description
The call to the PSL function was successful. Check the parameter pbstrResult for the return value from the PSL function. The user is not permitted to access the COM server. Check the comUserAllowed setting in the agent conguration le or use the DCOMCFG.EXE utility to determine whether the user has access. The security level does not permit the requested action. Check the comSecurityLevel setting in the agent conguration le.
E_ACCESSDENIED
14-42
PATROLAPI
Reference Manual
set()
This function assigns a value to a variable.
Synopsis HRESULT set(BSTR bstrObj, BSTR pbstrValue); Parameters
The following table describes the parameters that set() contains.

bstrObj pbstrResult
Dispatch Interface
variable value
Attributes*
[in] [in]
Description
The name of a variable in the PATROL Agent object hierarchy to which value is assigned. The result of the call to the PSL function. The parameter will contain the value that is assigned to pbstrValue The result of the call to the PSL function. The parameter will contain NULL if set() is successful or it will contain an error message if not.
pbstrResult
NA
[out, retval]
14-43
Return Values

Return Value
S_OK
Description
The call to the PSL function was successful. Check the parameter pbstrResult for the return value from the PSL function. One of the parameters is invalid. The user is not permitted to access the COM server. Check the comUserAllowed setting in the agent conguration le or use the DCOMCFG.EXE utility to determine whether the user has access. The security level does not permit the requested action. Check the comSecurityLevel setting in the agent conguration le.
E_INVALIDARG E_ACCESSDENIED
14-44
PATROLAPI
Reference Manual
set_alarm_ranges()
This function sets the ranges for the alarm conditions for a particular application or PATROL parameter.
Synopsis
HRESULT set_alarm_ranges(BSTR bstrAlarmRangeValue, BSTR bstrGlobalParamClassName, BSTR bstrApplName, BSTR bstrParamOid, BSTR bstrParamFullPath, BSTR* pbstrResult);
Parameters
The following table describes the parameters that set_alarm_ranges() contains.

BstrAlarmRangeValue bstrGlobalParamClassName bstrApplName bstrParamOid bstrParamFullPath pbstrResult
Dispatch Interface
new_ranges param appl param_oid path NA
Attributes*
[in] [in] [in, optional] [in, optional] [in, optional] [out, retval]
Description
A list of alarm range settings separated by new line characters. The name of the PATROL parameter to be monitored. An optional string for the name of the application. An optional string for the PATROL parameter object ID. An optional string for the name of the path to the PATROL parameter. The result of the call to the PSL function. The parameter will contain NULL if the function is successful or will contain an error message if the function is unsuccessful.
14-45
Return Values

Return Value
S_OK
Description
The call to the PSL function was successful. Check the parameter pbstrResult for the return value from the PSL function. The parameter pbstrResult is a NULL pointer. One of the required parameters, bstrAlarmRangeValue or bstrGlobalParamClassName, is not provided. The user is not permitted to access the COM server. Check the comUserAllowed setting in the agent conguration le or use the DCOMCFG.EXE utility to determine whether the user has access. The security level does not permit the requested action. Check the comSecurityLevel setting in the agent conguration le.
E_POINTER E_INVALIDARG
E_ACCESSDENIED
14-46
PATROLAPI
Reference Manual
unset()
This function removes a PATROL object that was previously assigned by the set() function.
Synopsis HRESULT unset(BSTR bstrName, BSTR* pbstrResult); Parameters
The following table describes the parameters that unset() contains.

Parameter
Description
[in] the name of PATROL object that is to be removed by unset() function. [out, retval] The result of the call to the PSL function. It will always contain NULL.
Return Values

Return Value
S_OK
Description
The call to the PSL function was successful. Check the parameter pbstrResult for the return value from the PSL function. The parameter pbstrResult is a NULL pointer.
E_POINTER
14-47
Return Value
E_INVALIDARG E_ACCESSDENIED
Description
The parameter bstrName is invalid. The user is not permitted to access the COM server. Check the comUserAllowed setting in the agent conguration le or use the DCOMCFG.EXE utility to determine whether the user has access. The security level does not permit the requested action. Check the comSecurityLevel setting in the agent conguration le.
14-48
PATROLAPI
Reference Manual
A
A A
Read-Only Functions
This appendix contains the read-only function calls. The read-only calls access a PATROL Event Manager log le. This appendix provides an overview of the read-only functions and then presents the functions in alphabetical order. This appendix also denes the error strings returned by the PemnError(), PemnLock(), PemnQueryEvents(), and PemnUnlock() read-only functions. This appendix discusses the following topics: Introduction to Locking and Reading a PATROL Event Log. . . . . . A-2 Synchronizing the PATROL Agent and PATROL API Calls . . . A-2 Locking and Unlocking the Event Log for Read Requests . . . . A-3 Sequence of the Functions for Locking and Reading a PATROL Event Log . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . A-3 More Information About Functions for Locking and Reading a PATROL Event Log . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . A-4 PemnEnd() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . A-5 PemnFreeEventBuffer() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . A-6 PemnLock() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . A-7 PemnQueryEvents() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . A-9 PemnStart(). . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . A-13 PemnUnlock(). . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . A-15 PemrError(). . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . A-17 Pemn Message Strings . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . A-18
Read-Only Functions
A-1
Introduction to Locking and Reading a PATROL Event Log

The PATROL API functions provide the ability to lock and read a PATROL event log circular le. The PATROL API functions can read a log le when a PATROL Agent has write-locked the le and is writing new events, or it can read the log le when no PATROL Agent is active. Chapter 2, Example Programs, presents sample C programs that uses the PATROL API calls.
Synchronizing the PATROL Agent and PATROL API Calls

The PATROL Agent inserts events into the circular log le. The PATROL API functions allow you to read and lter events from the log le. When the PATROL Agent and the PATROL API functions are both active, they are synchronized to work in a consistent way to prevent the PATROL API functions from attempting to read an event record that the PATROL Agent is writing. A PATROL Agent write request takes precedence over a PATROL API function read request. The PATROL Agent can make the PATROL API function read request wait as long as 500 write events. On the other hand, the PATROL API function read request can make a PATROL Agent write request wait only a single read event. A PATROL API function read request must relinquish control to a pending PATROL Agent write request after reading a single event. The precedence given to PATROL Agent write requests guarantees optimum performance of the PATROL Agent.
A-2
PATROLAPI
Reference Manual
Locking and Unlocking the Event Log for Read Requests

The PATROL event log circular le permits one read lock. A read request from a PATROL Agent or a second PATROL API call receives the error status PEMN_ONE_READER. BMC Software recommends that you encapsulate PATROL API function read requests such as the PemnEventQuery() function within the PemnLock() and PemnUnlock() functional pair to minimize the time that the log le is read-locked. Failure to unlock the le makes it unavailable to any other reader process.
Sequence of the Functions for Locking and Reading a PATROL Event Log
Following is a brief description of the functions for Locking and Reading a PATROL Event Log. The functions are listed in the order that you might execute them in a program.
PemnStart() initialize the API PemnLock() lock the circular file for reading PemnQueryEvents() read from event log into buffer PemnUnlock() unlock the circular file PemnFreeEventBuffer() free buffer created during query PemnError() return the most recent operation status message PemnEnd() terminate the API
Read-Only Functions
A-3
More Information About Functions for Locking and Reading a PATROL Event Log
Initialize the API Lock the circular le for reading Read from event log into buffer Unlock the circular le Free buffer created during query Return the most recent operation status message Terminate the API
Function to Use
PemnStart() PemnLock() PemnQueryEvents() PemnUnlock() PemnFreeEventBuffer() PemrError() PemnEnd()

PemnStart() on page A-13 PemnLock() on page A-7 PemnQueryEvents() on page A-9 PemnUnlock() on page A-15 PemnFreeEventBuffer() on page A-6 PemrError() on page A-17 PemnEnd() on page A-5
A-4
PATROLAPI
Reference Manual
PemnEnd()
Terminate the read-only API to the PATROL event log.
Synopsis
#include <pemapi.h> void PemnEnd(void);
Description
The PemnEnd() function terminates the read-only API to the PATROL event log. Issue the PemnEnd() function when the program nishes with the API.
Read-Only Functions
A-5
PemnFreeEventBuffer()
Free event buffer memory that was allocated by the API.
Synopsis
#include <pemapi.h> void PemnFreeEventBuffer( PemnEventHandle *, int iCount);
Parameters
Parameter
* iCount
Description
A pointer to a buffer that contains the event handles that are to be freed. An integer that indicates the number of memory bytes that the PemnFreeEventBuffer() function freed.
Description
The PemnFreeEventBuffer() function returns all memory that was allocated by the API for events. The API allocates event buffer memory for PemnEventQuery() function calls.
A-6
PATROLAPI
Reference Manual
PemnLock()
Read-lock the PATROL event log circular le.
Synopsis
#include <pemapi.h> void* PemnLock( char PemnReadEnum
*pcLogFileName, *peStatus);
Parameters
Parameter
*pcLogFileName
Description
A pointer to the character string that is the le name of the PATROL event log. The default PATROL Event Manager log is: $PATROLHOME/log/PEM.log A pointer to the character string that is the return status of the PemnLock() function. Valid range: PEMN_CORRUPT_CONTROL PEMN_CORRUPT_LOCK PEMN_EMPTY PEMN_ERROR PEMN_NO_FILE PEMN_OK PEMN_ONLY_ONE_READER PEMN_WRONG _VERSION
*peStatus
Read-Only Functions
A-7
Description
The PemnLock() function places a read lock on the circular PATROL event log le pcLogFileName in the directory LogFileDirName specied in the PemnStart() function. The PemnLock() function return value is the handle to pcLogFileName that must be used for all subsequent operations to the PATROL Event Manager log. A PATROL Event Manager log permits exactly one writer, the PATROL Event Manager, and one reader. While you have a read lock on a PATROL Event Manager log, no other reader process can access it.
See Also
PemnQueryEvents() on page A-9 to query the event log PemnUnlock() on page A-15 to remove the read lock from the PATROL Event Manager log PemnError() on page A-17 to retrieve messages returned by API
functions The PemnGet functions described in Chapter 4, Event Access Functions, for retrieving specic details from events returned by the PemnQueryEvents() function
A-8
PATROLAPI
Reference Manual
PemnQueryEvents()
Query a PATROL Event Manager log.
Synopsis
#include <pemapi.h> PemnEventHandle *PemnQueryEvents( void *pCfhandle, int iReqCount, int *piCount, /* Filter criteria */ time_t iStartTimeFilter, time_t iEndTimeFilter, char *pcStatusFilter, char *pcTypeFilter, char *pcNodeFilter, char *pcOriginFilter, char *pcPatternFilter, PemnReadEnum *peStatus);
Parameters
Parameter
pCfhandle
Description
The le handle that identies the PATROL Event Manager log that is queried. pCfhandle is returned when the PemnLock() function sets the read lock. An positive integer that limits the number of events the PemnEventQuery() function will return. If iReqCount = 1, the PemnQueryEvents() function will return all matching events from the log le. A pointer to the integer returned by the PemnQueryEvents() function indicating the number of matching events that it returned.
iReqCount
*piCount
Read-Only Functions
A-9
Parameter
Description
Filter Criteria:
iStartTimeFilter A timestamp that denes the lower (least recent) bound of the event lter expressed as the number of seconds that have elapsed since 00:00:00 GMT, January 1, 1970. If iStartTimeFilter = 0, events are not ltered by start time. A timestamp that denes the upper (most recent) bound of the event lter expressed as the number of seconds that have elapsed since 00:00:00 GMT, January 1, 1970. If iEndTimeFilter = 0, events are not ltered by end time. A string that is the event status lter. Valid range: ANY OPEN ACKNOWLEDGED CLOSED ESCALATED DELETED A string that is the event type lter. Valid range: ANY INFORMATION STATE_CHANGE ERROR WARNING ALARM RESPONSE A string that is the event host name lter. The "" string matches every host name. A string that is the event originating application class lter. The "" string matches every application class name. A string that is the event description lter. This string can match any part of the event description text. The pattern lter is case-sensitive. A string that is the return status of the PemnLock() function. Valid range: PEMN_ERROR PEMN_LOCK_WRITE_ERROR PEMN_NO_FILE PEMN_OK
iEndTimeFilter
pcStatusFilter
pcTypeFilter
pcPatternFilter
peStatus
A-10
PATROLAPI
Reference Manual
Description
The PemnQueryEvents() function parses the PATROL Event Manager circular log le specied by pCfhandle. The PemnQueryEvents() function returns the rst iReqCount number of events that match the lter criteria, or all matching events in the log if iReqCount = 1. The PemnQueryEvents() function also records the number of events it returned in piCount, and its completion status in peStatus. The PemnQueryEvents() function allocates memory for events it returns. BMC Software recommends that you execute the PemnFreeEventBuffer() function to release this memory after you have nished processing the events.
Limitations
PATROL Event Manager log les allow a single CF-reader. The API will not allow more than one reader to read a log le at the same time. The user program should run on the same host as the PATROL Agent because both must use the lock le for the PATROL Event Manager log. The default lock le name is PEM.log.lock located in the /tmp/patrol directory of the PATROL Agent host.
Read-Only Functions
A-11
Files
The PemnQueryEvents() function uses the following les: The PATROL Event Manager log lock le. The default PATROL lock le is /tmp/patrol/PEM.log.lock.
Note
This directory /tmp/patrol should not be NFS-mounted as this will cause the PemnLock() function to fail when attempting to lock the log le for read-only access. The PATROL Event Manager circular log le. The default PATROL log le is $PATROL_HOME/log/PEM.log. An ASCII le PEM.txt that is reserved for future enhancement.
See Also
PemnFreeEventBuffer() on page A-6 to free memory allocated by the PemnQueryEvents() function
A-12
PATROLAPI
Reference Manual
PemnStart()
Initialize the PEM read-only API.
Synopsis
#include <pemapi.h> void PemnStart( char *pcProgName, char *pcLogDirName, char *pcLockDirName, char *pcTextDirName);
Parameters
Parameter
pcPrgName
Description
A string that is the name of the program calling the PemnStart() function. The Pemn API uses the program name to correctly label messages generated in by Pemn API calls. A string that identies the path to the PATROL Event Manager log le PEM.log that the PemnQueryEvents() function will query. Default if not specied: $PATROL_HOME/log/PEM.log. A string that identies the path to the PATROL Event Manager log lock le PEM.log.lock that the PemnLock() function must access to set a read lock on the log le. Default if not specied: /tmp/patrol/PEM.log.lock. A string that identies the path to the text le PEM.txt. Default if not specied: /tmp/patrol/PEM.txt.
pcLogDirName
pcLockDirName
pcTextDirName
Read-Only Functions
A-13
Description
The PemnStart() function initializes the read API for the PATROL Event Manager log and sets the directories that subsequent API calls will use for the log, lock and text le directories. You should call the PemnStart() function before any other Pemn API call.
Files
The PemnStart() sets the paths for the following les: The PATROL Event Manager log lock le. The default PATROL lock le is /tmp/patrol/PEM.log.lock.
Note
This directory /tmp/patrol should not be NFS-mounted as this will cause the PemnLock() function to fail when attempting to lock the log le for read-only access. The PATROL Event Manager circular log le. The default PATROL log le is $PATROL_HOME/log/PEM.log. An ASCII le PEM.txt that is reserved for future enhancements.
A-14
PATROLAPI
Reference Manual
PemnUnlock()
Terminate the read lock on the PATROL Event Manager circular log le.
Synopsis
#include <pemapi.h> void PemnUnlock( void *pCfHandle, PemnReadEnum *peStatus);
Parameters
Parameter
*pCfHandle
Description
The handle for the PATROL Event Manager log le that is locked. The PemnLock() function returns pCfHandle when it sets the lock. A pointer to the return status of the PemnLock() function. Valid range: PEMN_LOCK_WRITE_ERROR PEMN_OK
*peStatus
Description
The PemnUnlock() function terminates the read-lock operation whose handle is pCfHandle. Terminating the lock allows other readers to interrogate the circular le.
Warning
An attempt to use a pCfhandle le handle that has been unlocked using the PemnUnlock() function will produce unpredictable results.
Read-Only Functions
A-15
See Also
PemnLock() on page A-7 to set the read lock on the PATROL Event
Manager log
PemnQueryEvents() on page A-9 to query the event log PemnError() on page A-17 to retrieve messages returned by API
functions The PemnGet functions in Chapter 4, Event Access Functions, for retrieving specic details from events returned by the PemnQueryEvents() function
A-16
PATROLAPI
Reference Manual
PemrError()
Return a pointer to the API error message string.
Synopsis
#include <pemapi.h> char *PemrError(PemrReadEnum eErr);
Parameter
Parameter
eErr
Description
A read-only character string returned from the API. Valid range: PEMR_BUFF_OVERFLOW PEMR_CORRUPT_CONTROL PEMR_CORRUPT_LOCK PEMR_EMPTY PEMR_ERROR PEMR_LOCK_WRITE_ERROR PEMR_MEMORY_ERROR PEMR_NO_FILE PEMR_ONLY_ONE_READER PEMR_WRONG _VERSION
Description
The PEMRError() function returns a pointer a read-only character string containing the error message that corresponds to the variable eErr.
Read-Only Functions
A-17
Pemn Message Strings

This section denes the error strings returned by the PemnError(), PemnLock(), PemnQueryEvents(), and PemnUnlock() read-only functions. The messages strings are presented in alphabetical order.
PEMN_BUFF_OVERFLOW
The PemnQueryEvents() function overowed the preallocated buffer that it uses to hold events it retrieves from the PATROL event log. Call the PemnFreeEventBuffer() to free the current buffer then retry the function.
PEMN_CORRUPT_CONTROL
The PemnLock() function detected that the PATROL event log header is corrupt.
PEMN_CORRUPT_LOCK
The PemnLock() function detected that the PATROL log lock le is corrupt.
PEMN_EMPTY
The Pemn function detected that the specied PATROL event log is empty.
PEMN_ERROR
The PemnQueryEvents() function encountered an error while attempting to read the PATROL event log lock le or the PATROL event log.
A-18
PATROLAPI
Reference Manual
PEMN_LOCK_WRITE_ERROR
The Pemn function encountered an error while trying to access and write the PATROL event log lock le. (The default log lock le name is /tmp/patrol/PEM.log.lock.)
PEMN_MEMORY_ERROR
The Pemn function encountered a memory error during execution.
PEMN_NO_FILE
The Pemn function could not locate one or more specied le names.
PEMN_NO_NULL_HANDLE
The Pemn function detected that the le handle name passed to it contained the NULL string. The NULL string is an illegal le handle.
PEMN_OK
The Pemn function operation completed with normal status.
PEMN_ONLY_ONE_READER
The PemnLock() function detected that the specied log le already has a read lock set against it.
Read-Only Functions
A-19
PEMN_WRONG _VERSION
The PemnLock() function detected that the format of the specied PATROL event log is not a PATROL Version 3 format. The PemnLock() function cannot read a log le that is not formatted for PATROL Version 3.
A-20
PATROLAPI
Reference Manual
B
B B
Using Your Own Event Loop
This appendix contains instructions on using your own event loop. For most applications, the event loop provided by the PATROL API is simple and sufcient. However, if you are trying to use the PATROL API from a program with an existing event loop (X, WIN32 or custom event loop) you may wish to use your own. The following topics are discussed: How Your Program Waits for Activities. . . . . . . . . . . . . . . . . . . . . . The Library for the Default Event Loop. . . . . . . . . . . . . . . . . . . . . . Using the PATROL API from an X Application . . . . . . . . . . . . . . . Using the PATROL API with a Custom Event Loop . . . . . . . . . . . . B-2 B-2 B-2 B-3
B-1
How Your Program Waits for Activities

At the lower level, the program using the API loops waits for activities happening on communication sockets or timers ring off. At the higher level the program is waiting for agent response to some solicited requests (for example, PemGetApplList()) or to registered PATROL events. Please note the high level term PATROL event and don't confuse it with the low level term in event loop.
The Library for the Default Event Loop

The PATROL API default event loop is provided in a separate library called libhandlers.a or handlers.lib. The header le associated with this library is called handlers.h.
Using the PATROL API from an X Application

To use the PATROL API from an X-based program: 1. Make sure libxhandlers.a and libpemapi.a are installed in the same directory. 2. Link with libxhandlers.a, which is shipped with your agent, instead of linking with libhandlers.a. 3. Create your application context and assign it (or copy it) to the global variable g_AppContext (see the header le handlers.h).
B-2
PATROLAPI
Reference Manual
Using the PATROL API with a Custom Event Loop

To use the PATROL API from an application with a custom event loop: 1. Don't link your program with libhandlers.a shipped with the agent. 2. Read the handlers.h header le and implement the routines dened in the header le using your own custom event loop routine. Timers in handlers.h re only once (the Xt model) while in some systems (for example, Win32) timers keep ring continuously.
B-3
B-4
PATROLAPI
Reference Manual
C
C C
Hints
C
This appendix contains the following hints on allocating communication handles and exiting the PATROL API event loop: Hint #1Allocating Communication Handles . . . . . . . . . . . . . . . . C-2 Example of Correct Allocation: s_hComm Is Static . . . . . . . . . C-2 Example of Incorrect Allocation: hComm Is Allocated on the Stack C-3 Hint #2Exiting the PATROL API Event Loop Using g_MainLoopInterrupt . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . C-4 Hint#3All Handles to Objects Are Not Stored or Freed. . . . . . . . C-4
Hints
C-1
Hint #1Allocating Communication Handles

The communication handles passed by address to by PemnOpen() should never be allocated on the stack. They should be static or allocated on the heap.
Example of Correct Allocation: s_hComm Is Static

In this example of correct allocation, s_hComm is static and will remain in memory while the program is running.
static PemnCommHandle s_hComm =NULL;
PemnOpen(1234, "MyHostName", /* Port nb/ Host Node name */ _CommCloseProc, /* Comm Close Callback */ (PemnClientData) NULL, /* No Comm Close ClientData */ sCommOpenProc, /* Comm Open Callback */ (PemnClientData) NULL, /* No Comm Open Client Data */ & s_hComm );
C-2
PATROLAPI
Reference Manual
Example of Incorrect Allocation: hComm Is Allocated on the Stack

In this example of incorrect allocation, hComm is allocated on the stack and will be deallocated when we exit the scope of f(). When the connection is broken, the PATROL API tries to put NULL in hComm but hComm is no longer in the program memory. A crash is likely.
void f() { PemnCommHandle hComm =NULL; PemnOpen(1234, "MyHostName", /* Port nb/ Host Node name _CommCloseProc, /* Comm Close Callback */ (PemnClientData) NULL, /* No Comm Close ClientData sCommOpenProc, /* Comm Open Callback */ (PemnClientData) NULL, /* No Comm Open Client Data & hComm ); } */ */ */
Hints
C-3
Hint #2Exiting the PATROL API Event Loop Using g_MainLoopInterrupt

To exit the PATROL API event loop, use the g_MainLoopInterrupt function dened in handlers.h. You can control your event processing using the function OneEvent(). To implement the function g_MainLoopInterrupt within the MainLoop() function in handlers.h, follow this example.
void MainLoop (void) { while (!g_MainLoopInterrupt) { OneEvent(ALL_EVENTS); } }
Hint#3All Handles to Objects Are Not Stored or Freed

All handles are dened in the context of a function handler. Outside the scope of the handler, the handle is not dened.
C-4
PATROLAPI
Reference Manual
D
D D
Extending the Power of PATROL
This appendix provides a white paper of the PATROL Application Programming Interface (PATROL API), describes its capabilities for extending the power of PATROL by linking to user-created programs, and provides illustrations and brief examples of how the PATROL API can be used to provide comprehensive event management. This appendix assumes a familiarity with PATROL concepts and terms. The term program is used to indicate the in-house software you write using the PATROL API. This appendix discusses the following topics: Introduction . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Capabilities for Knowledge Module Developers . . . . . . . . . . . . . . . Interacting with a KMTwo-Way Communication . . . . . . . . . Application MonitoringBeyond the Physical Barrier . . . . . . Custom Browser of PATROL Objects . . . . . . . . . . . . . . . . . . . . Event Knowledge Broker . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Capabilities for Application Integrators . . . . . . . . . . . . . . . . . . . . . . Event Translation . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Event Correlation . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Event Routing . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Event Synchronization . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . What Does the PATROL API Provide? . . . . . . . . . . . . . . . . . . . . . . PATROL API Availability . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Conclusion . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . D-2 D-4 D-5 D-8 D-9 D-10 D-11 D-12 D-13 D-15 D-17 D-19 D-20 D-21
D-1
Introduction
PATROL is a powerful application management tool. It uses autonomous and intelligent agents to monitor databases and applications over the network. While agents provide the application monitoring and management infrastructure, the application knowledge itself is loaded from a Knowledge Module (KM) written in a scripting language called the PATROL Script Language (PSL). Event management is handled by a sub-module of the agent called the PATROL Event Manager (PEM), The PEM manages events originating from the Agent, a KM running on the Agent, or any application that is linked to the agent through the PATROL API. Figure D-1 on page D-3 illustrates how the PEM manages events.
D-2
PATROLAPI
Reference Manual
C Programs PATROL API Library
(3)
PATROL Agent (PEM) PATROL Event Manager providing event management services
(4)
KM
(2)
Event Catalog(s) + StdEvents
(1)
PSL Processes
(2)
Event History Repository
PATROL Console
PEM Console on UNIX
PEM Console on Windows

(5)
PEM view
PEM view
PEM view
Figure D-1
Event Management Architecture in PATROL
The source of events can be one of the following: the Agent (1) the Knowledge Module (2) any application using the PATROL API (3)
Events are stored and managed in the PEM (4) but can be viewed and accessed from different consoles (5).
D-3
Capabilities for Knowledge Module Developers

The rst part of this appendix is of interest to KM developers. It shows how you can interact with PATROL Agents and extend the KM capabilities using the PATROL API. Table D-1 lists several examples that illustrate this interaction:
Table D-1 PATROL API Examples for Knowledge Module Developers
Example
Interacting with a KMTwo-Way Communication Application MonitoringBeyond the Physical Barrier Custom Browser of PATROL Objects Event Knowledge Broker
Description
Shows how a custom written application interacts in a bidirectional way with a KM. Shows how an application distributed physically on different hosts appears as a single monitored entity to the user. Shows how you can write your own specialized application browser of PATROL. Shows how event knowledge (sub-set of a KM) can be loaded from a knowledge broker and broadcasted to all interested hosts.
See Page...
D-5 D-8
D-9 D-10
D-4
PATROLAPI
Reference Manual
Interacting with a KMTwo-Way Communication

PSL is a very powerful scripting language. In most situations, PSL can express and capture the whole of the application knowledge. However, in some situations, using a C/C++ program can add value to PSL. In a way, the PATROL API allows a KM to be extended using a C/C++ program. For example, Figure D-2 illustrates how the program can act as an extended collector of data. First, A program allows the KM to obtain richer data, data from other APIs, or data with ner granularity. For simple data, the program can use the PSL set() function to set KM variables. (For more information on the PSL set() function, refer to the PATROL Script Language Reference Manual.) For complex data, data is collected and sent to the PATROL Agent where it will be further processed by the PSL notication command belonging to the KM. The Notication command can create new parameters, increment the value of some variables, etc. Second, the program can act as event originator and request the KM to execute PSL/OS commands on behalf of the event.
PATROL Agent (4) (5) PSL Notication Command (6) PSL Set()
Figure D-2
(3) complex data E (2) simple data
ProgramExtended Collector
(1)
Program-Extended Data Collector
D-5
Figure D-2 illustrates the program ow that occurs when the program serves as an extended collector of data: 1. The extended collector program collects granular or pertinent data. 2. Simple data are passed to the KM using the PSL Set() function. 3. Complex data E is sent in an INFO event to the PATROL Agent. 4. The PATROL Agent fetches in the KM the Notication command of complex data E. 5. The agent executes the PSL Notication command. 6. The PSL Notication command increments counters or sets variables in the KM, etc. Finally, the program can be heavily synchronized with the knowledge as described in Figure D-3.
PATROL Agent E1 Knowledge Module 3 4 E1 Notication Command E2 (2)
Program
(1)
5 Results
Figure D-3
Two-Way Communication in Interacting with a KM
1. Application sends an event E1. 2. Agent fetches in the KM the Notication command of E. 3. The agent executes the PSL Notication command.
D-6
PATROLAPI
Reference Manual
4. The PSL Notication command calls variables and objects in the KM, execute other PSL functions then stores any results in event E2 and sends it back to the program. 5. The program listens to event E2 and captures back the results. As a nal example of program and KM interaction, a remote PSL or OS execution can be initiated by the program. The command executes on the agent and results returned to the program. For convenience, the PATROL API provides a wrapper function called PemnBPslExec() which allows the program to dispatch a PSL statement to the remote agent for execution and wait for results.
PATROL Agent RemPsl Knowledge Module (2) (3) RemPsl Notication Command Result
Program
(1)
(4) Results
Figure D-4
Remote Psl Execution
1. A special event called RemPsl is sent to the agent. This event contains as an argument the PSL statement to be executed. 2. The agent receives the RemPsl event and executes its notication command. The notication command does noting other than reading the PSL statement from RemPsl and executing it. 3. The results are captured and returned to the program using another event called Result. 4. The program receives the Result event and extracts the PSL command results.
D-7
Application MonitoringBeyond the Physical Barrier

An application can be spread over different machines. As an example, a user may access information in three replicated databases over three hosts. From a user perspective, the application is down (alarm) when the user cannot access the information. One database could be down or temporarily unavailable but this is not an alarming condition to the user as it is always possible to access the same information from the other databases. One KM running on one agent (instead of three) can detect this kind of situation. The notion of ONE application running on ONE host is being replaced by an application that is a container accessing the services of other applications on same or different machines.
The distributed application A is running on three hosts. host1
Distributed application A host2

(1)
host3
PATROL agent KM
(4) (3) (2)
Program
Single view to the user User is not aware (and should not) that application A is split over three machines.
Figure D-5 Application Monitoring Beyond the Physical Barrier
1. 2. 3. 4.
The program interact with a all components of application A. The program massages and unies information. The program interacts with the KM. User is managing a single object not three different objects.
D-8
PATROLAPI
Reference Manual
Custom Browser of PATROL Objects

A program can recreate the PATROL object hierarchy and view it in a custom way. The list of applications, instances, parameters or variables can be obtained directly by the API in addition to object attributes: status and value. Figure D-6 shows a custom view of PATROL where agents are structured into domains.
node
inst2 app2 inst1 par2 par1 inst2 app1 inst1 PATROL agent 2
par3 par2 par1
Domain node1
inst2 app2 inst1 par2 par1 inst2 app1 inst1
par3 par2 par1
node
inst2 app2 inst1 par2 par1 inst2 app1 inst1 PATROL agent 1
Figure D-6
par3 par2 par1 Program
node2
inst2 app2 inst1 par2 par1 inst2 app1 inst1
par3 par2 par1
Custom View of the PATROL Object Browser
The program can reconstruct the whole PATROL hierarchy and display it in a custom hierarchy (e.g domain, node, application, instance, parameter) or in a third party software format.
D-9
Event Knowledge Broker

KMs contain the static knowledge of an application. However, in some situations it makes sense to create the knowledge dynamically by the program. This event knowledge is volatile in the sense it will disappear once the agent exits. This dynamic knowledge (compared to the traditional static knowledge) can be used in event forwarding, routing, translation or synchronization. As an example, a program acting as an event router can interrogate an agent looking for the event catalog used for routing events. When the knowledge is found, it is sent to some other relevant agents (client agents). The program then disconnects with the original agent and interacts with the client agents to route events.
PATROL Agent 1
PATROL Agent 2
PATROL Agent 3
(5)
KM
PATROL Agent 1
KM
KM
(4)
KM
(1) (2)
(6)
(3)
Program = Knowledge Broker
Figure D-7
Event Knowledge Broker
1. Agent 1 is interrogated by the program for a particular set of event knowledge. 2. Event knowledge is read from the KM in Host 1.
D-10
PATROLAPI
Reference Manual
3. The program creates any additional event knowledge needed for functioning. The program fetches the list of all agents requiring this knowledge. 4. The program send them the new event knowledge. 5. The volatile knowledge is used to control events. 6. The connection with agent 1 is disconnected.
Capabilities for Application Integrators

The second part of this appendix is of interest to application integrators. It shows how the PATROL API can be used for application integration and enterprise management. Table D-2 lists several examples that illustrate this interaction:
Table D-2 PATROL API Examples for Application Integrators
Example
Event Translation
Description
See Page...
D-12
Illustrates how PATROLVIEW translates PATROL events into third party vendor events. Shows how events from different hosts, KMs and sources are correlated into a new compound event which initiates further PATROL agent actions. Shows how events can be routed from one agent to another agent or to a custom program. The destination agent or program provides specialized services: e.g archiving, capacity planning, event consolidation, etc. Shows how an event translated into a peer vendor object can be tracked. Whenever this event changes status the peer vendor object can be modied to reect the change synchronously.
Event Correlation
D-13
Event Routing
D-15
Event Synchronization
D-17
D-11
Event Translation
PATROL events can be re-mapped and formatted for management framework (see Figure D-8). A PATROL Event Translator (PET) listens to events coming from the agents. If an event matches certain criteria, it will be formatted and re-mapped to be inserted as an event of the management framework.
.
PATROL agents
(1) PET for TIVOLI and HP OperationCenter
Conguration Files
(2)
(3) User Integration Options (4)
TIVOLI
HP Operation Center
Figure D-8
Event Translator
As exemplied in Figure D-6, a PET can be used to translate PATROL events into HP Operation Center or TIVOLI events. First, events are collected from PATROL Agents (1). Then, based on conguration (2) and user integration options (3), events are translated into events that are specic to TIVOLI or HP OpC (4).
D-12
PATROLAPI
Reference Manual
Event Correlation
The PATROL API provides the necessary infrastructure for event correlation. Simple event correlation can be done in-house using an event correlation (see Figure D-9) program: Correlate events originated from different hosts. Correlate events originated in different KMs. Correlate events originated from other programs (for example, the PET and event routers). Correlate events where the correlation logic is not complex.
Complex correlation may necessitate the integration with existing products: For complicated correlation logic, the program may use the service of a correlation engine. For rule based correlation, the program may use the services of an expert system.
D-13
PET
PATROL Agent
PATROL Agent KM (6)
Other Programs
(5) Correlation Engine (3) (2) Expert System/Rule (4)
(1)
Program - Event Correlation
Figure D-9
Event Correlation
(1) Events are originated from PATROL agents, PET or other programs. (2) The program lters, massages and events and correlates event from different hosts, KM or other programs. For complex correlation it may use the services of (3) a correlation engineer (4) an expert system. (5) The Event Correlation program triggers new events resulting from the correlation and send these events to PATROL agents. (6) These compound events may trigger new actions by PSL notication commands. For example: Assuming that the KM denes three event classes EvClass1, EvClass2 and EvClass3. The event correlator program can evaluate this boolean condition:
D-14
PATROLAPI
Reference Manual
if ( ((EvClass1) && (EvClass2.origin == ORACLE)) || (EvClass3.cardinality==5))
In other words the program can detect the condition when one event (EvClass3) has occurred 5 times or that event (EvClass1) has occurred and also event (EvClass2) has occurred in the ORACLE KM.
Event Routing
The PEM engine in the agent processes and manages all events that are local to the agent. In some situations, it may be judicious to centralize the processing and management of events. Events are sent to a local consolidation program where they will be stored in a relation database for history, capacity planning or archiving. Assuming that the user wants archiving of all alarm and warning events in a single relational database, the program registers to receive alarms and warnings from PATROL agents then it calls an embedded SQL statement to insert the events in the RDBMS. The program may do further event aggregation and send the new event to an agent with an Event Consolidation KM. The KM in this case will execute the pertinent SQL statements.
D-15
Event Event Event Repository Repository Repository PATROL agent PATROL agent PATROL agent (1) Program -Event Router (2) (3) Consolidate Event Database
Event Consolidation KM PATROL-Agent Loaded

Figure D-10 Event Forwarding
1. Events managed by different agents are sent to the program. 2. The event router lters, consolidate and store events in a company-wide database for archiving, capacity planning or future analysis. 3. The consolidated events are sent to an agent with a special KM which executes Notication commands generating report and possibly triggering new events.
D-16
PATROLAPI
Reference Manual
Event Synchronization
Translating a PATROL event into a peer object belonging to other applications allows easy integration. However, sometimes there is a need to track the state of the event or the peer object to enrich the integration. Tracking the state of the peer object and keeping it synchronized with the state of the original event is called event synchronization. For Example: After translating a PATROL event into a Remedy trouble ticket, the user wants to avoid the situation where an operator using PATROL Console closes the event but the peer trouble ticket remains unchanged. The user wants the trouble ticket to be closed as well. This is how event synchronization resolves the problem: The program translating the event registers the event with the PATROL agent and marks it as Remedy Integrated. Later when the event changes status, the program detects the fact that a trouble ticket has already been created and has changed status; it then noties Remedy of the new status. The program can also poll the status of the Remedy trouble ticket and updates the status of the peer PATROL event when the trouble ticket changes status.
D-17
PATROL agent 1
PATROL agent 2
PATROL agent 3
Event Repository
(4) (9) (10) (3) (5) (2)
Event Repository (1)
Event Repository
Program-Event Synchronization
Remedy Database (2)
(7)
(8)
PATROL user
Remedy Server
Figure D-11 Example of Event Synchronization
Remedy User
(6)
1. A sub- set of PATROL event is captured by the Program. 2. For every interesting event create a peer Remedy trouble ticket. 3. A PATROL user closes the event on agent 1. 4. The program is notied of the change. 5. Remedy is notied of the new status. 6. The Remedy user is notied. 7. Going the other direction, the Remedy user changes 1the status of the trouble ticket.
1. Steps 1 to 6 are provided by the current version of PEM Console for Remedy. Steps 7 to 10 may be provided in a future version.
D-18
PATROLAPI
Reference Manual
8. The Program (reading log les in a periodical fashion) detects the new status of the trouble ticket. 9. The program closes/acknowledges the PATROL event using the API. 10. The PATROL user is notied of the change.
What Does the PATROL API Provide?

The following services are provided by the PATROL API: Connection Management Connection and disconnection with PATROL Agents Password and user name authentication and encryption. Event Management Send events to agent.Receive events from agent Close/Acknowledge/Delete or add diary to events Generate reports Query past events from agent
PATROL Objects Access Get PATROL object list: list of applications, instances, parameters or variables Get PATROL object attributes: applications, instances, parameters or variables. As an example, the value of a parameter, the status of any objects, the name of the worst parameter in an instance can be returned by the PATROL API
Event Knowledge Get the list of event classes in the KM Dene dynamically a new event class
D-19
Get the description of an event class: the text of PSL/OS notication commands, the expert advice text Event Synchronization Register an event with the agent to track and update its status in the integrated product Event Driven and Blocking Mode For every service provided by the PATROL API, there is a blocking mode version and an event driven version. In the blocking mode version the program callers waits for the results until they are received or a time-out occurs. In the event driven version the program registers callback which are executed when the results arrive. In general, blocking mode programming is easier to write while event driven programming is better in performance and multi-host connection support.
PATROL API Availability

The PATROL API has been used already in PATROLVIEW to integrate with TIVOLI and HP Operation Center. PATROL Event Translator (PET) registers with one or more agents and then translates PATROL events to TIVOLI or HP Operation center events. The PATROL Command Line Interface (CLI), which is character based, also uses the PATROL API to access and manage PATROL objects and events in the Agent. Connection and event management services (see Section ) are already provided in PATROL v3.0. PATROL object access and event knowledge services are implemented for v3.1. Event synchronization services are used only internally in the PEM for Remedy products. The PATROL API is available on all PATROL Agent platforms: UNIX, NT, and so forth.
D-20
PATROLAPI
Reference Manual
Conclusion
PATROL Application Management strength resides in its KM coverage and depth. The API adds to this strength by extending the power and inter-operability of KMs. The API is offered to KM developers and customers alike. Today applications interact more and more with each other. The API provides the mechanisms to open and integrate PATROL agent technology with potentially any other product. Customers always prefer a nished solution, but in a changing world with emerging new technologies and products, an open API allows the customer to develop in-house solutions. The PATROL API gives them the tools.
D-21
D-22
PATROLAPI
Reference Manual
E
E E
ESI Examples
This appendix provides the following examples of source les that implement ESI functions: BMC Example: esiapi_impl.h . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .E-2 BMC Example: esiapi_impl.c . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .E-4
ESI Examples
E-1
BMC Example: esiapi_impl.h

The following example, eshiapi_impl.h, illustrates how to dene the context data structure for an ESI implementation. The context data structures contains the mandatory BMC eld required by PATROL. This eld must neither be modied nor inititalized. You may use this example as a model for dening the context data structure of your ESI implementation.
#ifndef __secdata_h__ #define __secdata_h__
#ifdef CYBERSAFE_GSS /* CyberSafe GSS Implementation */ #include <gssapi/gssapi.h> #define _GSS_DEFAULT_QOP NULL #define _GSS_WRAP gss_seal #define _GSS_UNWRAP gss_unseal #define _GSS_SERVICE_PRINCIPAL GSS_KRB5_NT_HOSTBASED_SERVICE_NAME #else /* MIT Generic implementation */ #include <gssapi/gssapi_generic.h> #include <krb5.h> #define #define #define #define #endif _GSS_SERVICE_PRINCIPAL (gss_OID)gss_nt_service_name _GSS_DEFAULT_QOP (gss_qop_t *) NULL _GSS_WRAP gss_wrap _GSS_UNWRAP gss_unwrap
struct _esi_Context { /* mandatory BMC field */ BMC_Sec_Plugin plugin; /* Customer's portion if needed */ unsigned intestablished:1;/* 0 if security is not established yet, * 1 if security context is already * established */ unsigned int client:1;/* client or server: 1 for client 0 for server. * Client and server behave differently while * establishing security context */
E-2
PATROLAPI
Reference Manual
gss_ctx_id_t
gss_context;/* security context - keys, etc. */
/* Client side only */ gss_buffer_desc* token_ptr;/* security token, passed between peers */ gss_name_t target_name;/* server's name */ /* Server side only */ #ifdef CYBERSAFE_GSS gss_name_t client_name; /* who is connecting. This is redundant and needed for CYBERSAFE lack of gss_inquire_context */ #endif /* CYBERSAFE_GSS */ };
/* aix specifics for building a shared library on aix 4.1 */ #if defined(aix) /* Keep a list of all of the functions exported by the shared library. * This table is searched at run-time to resolve function names to their * addresses. */ typedef void (*PslCleanupFunction)(void *); typedef char *(*PslExportFunction)(void *, void *, void *); typedef struct { char *name;/* Function name */ PslExportFunction address; /* SHL function */ PslCleanupFunction cleanup;/* Cleanup function (if SHL is cancelled) */ } EsiExport; EsiExport esiExports[]; #define BEGIN_ESI_EXPORTS EsiExport esiExports[] = { #define ESI_EXPORT(name, addr, cleanup) { (char *)(name), (PslExportFunction)(addr), (PslCleanupFunction)(cleanup) }, #define END_ESI_EXPORTS { NULL, NULL, NULL } };
extern PslExportFunction EsiFindProc(char *funcName); #endif /* aix */
ESI Examples
E-3
BMC Example: esiapi_impl.c

The following example, esiapi.c, illustrates a full ESI library implementation based on MIT Kerberos version 5.0. You may use this example as a model when you create your ESI implementation.
#include <stdio.h> #include <string.h> /* memset, strdup, strchr */ #include <stdlib.h> /* malloc, free */ #include <esiapi.h> #include "esiapi_impl.h"
#define CONTEXT_ESTABLISHED(ctx) (ctx && esi_IsEstablished(ctx)) #define IS_CLIENT(ctx) (ctx && esi_IsClient(ctx)) #define SES_DOMAIN_SERVICE_NAME "patrolagent" /* used to extract user name from Kerberos Principal */ #define KRB_NAME_SEPARATOR '@' /* Server's credentials. Actually Server Credentials should be per-server, * based on the services provided. For now I'm keeping 1 credentials for * only 1 service name (SES_DOMAIN_SERVICE_NAME) */ static gss_cred_id_t s_server_creds = NULL; static int server_establish_context(EsiSendProc, int, esi_ContextPtr, gss_cred_id_t); static int client_establish_context(EsiSendProc, int, esi_ContextPtr, void*, EsiConnProc); static int esi_seal (unsigned int*, unsigned int*, gss_ctx_id_t*, gss_buffer_desc*, gss_buffer_desc*, int*); static int esi_unseal (unsigned int*, unsigned int*, gss_ctx_id_t*, gss_buffer_desc*, gss_buffer_desc*, int*); static int build_server_name(char* name, esi_ContextPtr ctx); static void convert_gss_name(gss_buffer_t, char*, int);
E-4
PATROLAPI
Reference Manual
static void display_status(char*,OM_uint32, OM_uint32); static void display_status_1(char*, char*, OM_uint32, int); #if defined(aix) /* Routine to resolve a function name to it's address using * the esiFuncs[] array. This routine must be specified as the entry * point to the library when linking. */ PslExportFunction EsiFindProc(char *funcName) { EsiExport *exp; for (exp = esiExports; exp->name; exp++) { if (!strcmp(funcName, exp->name)) return(exp->address); } return(NULL); } #endif/* aix */ ESI_VERSION_IMPL /* * Function: esi_ServerInit * * Purpose: imports a service name and acquires credentials for it *The service name is imported with gss_import_name, and service *credentials are acquired with gss_acquire_cred. If either opertion *fails, an error message is displayed and -1 is returned; otherwise, *0 is returned. * * Returns: ESI_OK on success, ESI_ERR on failure * */ esi_RetCode esi_ServerInit(char* service_name /* the ASCII service name */) { gss_buffer_desc name_buf; gss_name_t server_name; OM_uint32 maj_stat, min_stat;
ESI Examples
E-5
/* ATTENTION: currently we are using 1 credentials per server executable. In the future we may want to have the same execuatble providing different services, each authenticated by it's own credentials */ if (s_server_creds) return ESI_OK; name_buf.value = service_name; name_buf.length = strlen(name_buf.value) + 1; maj_stat = gss_import_name(&min_stat, &name_buf, _GSS_SERVICE_PRINCIPAL, &server_name); if (maj_stat != GSS_S_COMPLETE) { return ESI_ERR; } maj_stat = gss_acquire_cred(&min_stat, server_name, 0, GSS_C_NULL_OID_SET, GSS_C_ACCEPT, &s_server_creds, NULL, NULL); if (maj_stat != GSS_S_COMPLETE) { return ESI_ERR; } (void) gss_release_name(&min_stat, &server_name); return ESI_OK; } /* end of esi_ServerInit */
/* Returns ESI_OK if context was established */ int esi_IsTrusted(esi_ContextPtr ctx) { if (CONTEXT_ESTABLISHED(ctx)) return ESI_OK; return ESI_ERR; } /* Allocate per-session Context object and initiate it */ esi_ContextPtr esi_AllocateContext(int client) {
E-6
PATROLAPI
Reference Manual
int size = sizeof(esi_Context); esi_ContextPtr ctx = (esi_ContextPtr)malloc(size); if (!ctx) { return (0); } memset((void*) ctx, 0, size); ctx->gss_context = GSS_C_NO_CONTEXT; ctx->established = 0; ctx->client ctx->token_ptr return ctx; } /* end of esi_AllocateContext */ /* Releases security context associated with a session: * NOTE: some security mechanisms (but not Kerberos) require * the call to gss_delete_sec_context to return a token to be * passed to the peer. This is the 3d arg to the gss_delete_sec_context() * We do not provide this support (yet), and it's not recommended * in GSS API version 2 anyway */ void esi_FreeCtx(esi_ContextPtr ctx) { OM_uint32 maj_stat; OM_uint32 min_stat; = client; = GSS_C_NO_BUFFER;
if (!ctx) return; if (CONTEXT_ESTABLISHED(ctx)) { maj_stat = gss_delete_sec_context(&min_stat, &ctx->gss_context, GSS_C_NO_BUFFER); if (GSS_ERROR(maj_stat)) { /* do not show it to customer, in the worst case * this one would be a leak. * Show it to developers though */ } }
ESI Examples
E-7
free(ctx); } /* end of esi_FreeCtx */
/* Functions: esi_GetPeerName * * Purpose: returns malloc-ed user name of the peer * (i.e. the first part of Kerberos principal name) or NULL. */ char* esi_GetPeerName(esi_ContextPtr context) { OM_uint32 maj_stat, min_stat; gss_name_t src_name; char src_n[1024]; gss_buffer_desc sname; char* s; /* Get context information */ maj_stat = gss_inquire_context(&min_stat, ((esi_ContextPtr)context)->gss_context, &src_name, NULL, /* don't care about target */ NULL, /* don't care about lifetime */ NULL, /* don't care about mechanism */ NULL, /* don't care about ctx flags */ NULL, /* don't care about locality */ NULL);/* don't care about open flag */ if (maj_stat != GSS_S_COMPLETE) { display_status("inquiring context", maj_stat, min_stat); return NULL; } maj_stat = gss_display_name(&min_stat, src_name, &sname, (gss_OID *) NULL); if (maj_stat != GSS_S_COMPLETE) { display_status("displaying target name", maj_stat, min_stat); return NULL; } convert_gss_name(&sname, src_n, 1023); s = strchr(src_n, KRB_NAME_SEPARATOR); if (s) *s = '\0'; /* dbgPrnt(IDENTITY_DEBUG,(IDENTITY_DEBUG_MASK,"User='%s'\n", src_n));*/
E-8
PATROLAPI
Reference Manual
(void) gss_release_buffer(&min_stat, &sname); (void) gss_release_name(&min_stat, &src_name);
return strdup(src_n); } /* end of esi_GetPeerName */ int esi_IsClient(esi_ContextPtr ctx) { return (ctx->client); } int esi_IsEstablished(esi_ContextPtr ctx) { return (ctx->established); }
/* * Functions: esi_ValidateAccount * * Purpose: Kerberos account verification. * Returns: ESI_OK for success, ESI_CONTINUE for continuing OS validation * ESI_ERR for failure * * NOTE: This function does not actually belong with sessions. I'm *leaving it here since it's the place where the GSS/Kerberos *security is exposed, and also sess_gss_stubs.c file is a natural *place to provide a stub for non-Kerberized executable. * NOTE1: This function is using Kerberos 5 APIs because GSS-API does *not expose password verification functionality. */ esi_RetCode esi_ValidateAccount(const char* name, const char* password) { static krb5_data tgtname = { 0, KRB5_TGS_NAME_SIZE, KRB5_TGS_NAME }; krb5_contextcontext; krb5_error_codecode; krb5_principalme; krb5_principalserver; krb5_credscreds;
ESI Examples
E-9
krb5_address**addrs = (krb5_address **)0; intoptions = 0; /* default options */ code = krb5_init_context(&context); if (code) { /* Can't initialize Kerberos connection. */ return ESI_CONTINUE; /* PATROL will continue user validation on the OS level */ } /* Parse the requested name */ if ((code = krb5_parse_name (context, (char*)name, &me))) { /* Can't convert the user's names into Kerberos internal name. */ krb5_free_context(context); return ESI_CONTINUE; /* PATROL will continue user validation on the OS level */ } /* Start filling in credentials */ memset((char *)&creds, 0, sizeof(creds)); creds.client = me; /* Build principal name for TGT service. */ code = krb5_build_principal_ext(context, &server, krb5_princ_realm(context, me)->length, krb5_princ_realm(context, me)->data, tgtname.length, tgtname.data, krb5_princ_realm(context, me)->length, krb5_princ_realm(context, me)->data, 0); if (code) { /* Can't build TGT principal name. */ krb5_free_principal(context, me); krb5_free_context(context); return ESI_CONTINUE; /* PATROL will continue user validation on the OS level */ } creds.server = server; /* Verify the password. */ code = krb5_get_in_tkt_with_password(context, options, addrs,
E-10
PATROLAPI
Reference Manual
NULL, NULL, /* no preauth */ (char*)password, 0, &creds, 0); if (code == KRB5KRB_AP_ERR_BAD_INTEGRITY || code ) { /* Bad password (BAD_INTEGRITY) or no such user known (code). */ krb5_free_principal(context, me); krb5_free_principal(context, server); krb5_free_context(context); return ESI_CONTINUE; /* PATROL will continue user validation on the OS level */ } /* We verified it ! * free_cred_contents krb5_will also release both principals */ krb5_free_cred_contents(context, &creds); krb5_free_context(context); return ESI_OK;
} /* end of Krb_ValidateAccount */
/* * Function: convert_gss_name * * Purpose: Puts a gss NAME in the buffer as a string */ static void convert_gss_name(gss_buffer_t name, char* buffer, int len) { if (len > name->length) len = (int) name->length;/* use lesser of 2 lengths to avoid buffer overflow */ sprintf(buffer, "%.*s", len, (char *)name->value); }
static int build_server_name(char* name, esi_ContextPtr ctx) { gss_buffer_desc name_buffer; unsigned int maj_stat, min_stat;
ESI Examples
E-11
name_buffer.value = name; name_buffer.length = strlen(name) + 1; maj_stat = gss_import_name(&min_stat, &name_buffer, (gss_OID)gss_nt_service_name, /* we are constructing the server's name */ &ctx->target_name); if (maj_stat != GSS_S_COMPLETE) return ESI_ERR; return ESI_OK; } /* end of build_server_name */
static int esi_unseal (unsigned int* maj_stat, unsigned int* min_stat, gss_ctx_id_t* gss_context,gss_buffer_desc* recv_tok, gss_buffer_desc* data_buf, int* state ) { *maj_stat = _GSS_UNWRAP(min_stat, gss_context, recv_tok, data_buf, state, _GSS_DEFAULT_QOP); if (*maj_stat != GSS_S_COMPLETE && *maj_stat != GSS_S_CONTEXT_EXPIRED) { /* if the decryption failed, drop the message. It happens only if the message was forged */ return ESI_ERR; } return ESI_OK; } /* end of esi_unseal */ static int esi_seal (unsigned int* maj_stat, unsigned int* min_stat, gss_ctx_id_t* gss_context, gss_buffer_desc* in_buf, gss_buffer_desc* out_buf, int* state) { *maj_stat =_GSS_WRAP(min_stat, gss_context, 1 /* both confidentialy and integrity are requested */, GSS_C_QOP_DEFAULT, in_buf,
E-12
PATROLAPI
Reference Manual
state, out_buf); if (*maj_stat != GSS_S_COMPLETE && *maj_stat != GSS_S_CONTEXT_EXPIRED) { return ESI_ERR; } return ESI_OK; } /* end of esi_seal */
/* * Function: server_establish_context * * Purpose: establishes a GSS-API context as a specified service with *an incoming client, and returns the context handle and associated *client name. *Any valid client request is accepted. If a context is established, *its handle is returned in context and the client name is returned *in client_name and 0 is returned. If unsuccessful, an error *message is displayed and -1 is returned. * * Returns: ESI_OK on success, ESI_ERR on failure */ static int server_establish_context(EsiSendProc Send_f, int Handle, esi_ContextPtr ctx, gss_cred_id_t server_creds /* server credentials, from gss_acquire_cred */ ) { gss_buffer_desc send_tok; gss_name_t client; gss_OID doid; OM_uint32 maj_stat, min_stat; OM_uint32 ret_flags; /* esi_ContextPtr ctx = (esi_ContextPtr)DomainContext; */
maj_stat = gss_accept_sec_context(&min_stat, &ctx->gss_context, server_creds, ctx->token_ptr,

ESI Examples
E-13
GSS_C_NO_CHANNEL_BINDINGS, &client, &doid, &send_tok, &ret_flags, NULL, /* ignore time_rec */ NULL); /* ignore del_cred_handle */ if (maj_stat!=GSS_S_COMPLETE && maj_stat!=GSS_S_CONTINUE_NEEDED) { display_status("accepting context", maj_stat, min_stat); return ESI_ERR; } if (send_tok.length != 0) { if ((*Send_f)(Handle, send_tok.value, send_tok.length) != 0) { return ESI_ERR; } (void) gss_release_buffer(&min_stat, &send_tok); } if (maj_stat == GSS_S_CONTINUE_NEEDED) return ESI_CONTINUE; /* keep negotiating */ /* SECURITY CONTEXT ESTABLISHED ! */ ctx->established = 1;
/* invoke application callback */ if ( !ctx->plugin.accept_cb(Handle, ctx->plugin.accept_data, NULL)) { return ESI_ERR; }
return ESI_OK; } /* end of server_establish_context */
/* * Purpose: establishes a GSS-API context with a specified service and *returns the context handle * * Returns: 0 on success, -1 on failure * * Executes 1 step in security context establishing. If the context is OK,
E-14
PATROLAPI
Reference Manual
* sets "established" flag so the further operations will be delegated to * the application layer. * The default GSS-API mechanism is used, and mutual authentication * and replay detection are requested. * * If successful, the context handle is returned in context. If * unsuccessful, the GSS-API error messages are displayed on stderr * and -1 is returned. *-------------------------------------------------------------------*/ static int client_establish_context(EsiSendProc Send_f, int Handle, esi_ContextPtr ctx, void* connectClientData, EsiConnProc connect_cb ) { gss_buffer_desc send_tok; OM_uint32 ret_flags; OM_uint32 maj_stat;/* latest results from GSS calls */ OM_uint32 min_stat;
/* * Execute the context-establishement step. * * Token_ptr points to the token * to send to the server (or GSS_C_NO_BUFFER on the first pass). * Every generated token is stored in send_tok which is then * transmitted to the server; every received token is stored in * ctx->token_ptr by the read Callback, to be processed by * the next call to gss_init_sec_context. * * GSS-API guarantees that send_tok's length will be non-zero * if and only if the server is expecting another token from us, * and that gss_init_sec_context returns GSS_S_CONTINUE_NEEDED if * and only if the server has another token to send us. */ maj_stat = gss_init_sec_context(&min_stat, GSS_C_NO_CREDENTIAL, &ctx->gss_context, ctx->target_name, GSS_C_NULL_OID, GSS_C_MUTUAL_FLAG|GSS_C_REPLAY_FLAG , 0, NULL,/* no channel bindings */
ESI Examples
E-15
ctx->token_ptr, NULL,/* ignore mech type */ &send_tok, &ret_flags, NULL);/* ignore time_rec */ /* if the token recieved from the server is still kept, release it */ if (ctx->token_ptr != GSS_C_NO_BUFFER) { /* We do not need to release the buffer here since it is not dynamically allocated. The first time it is GSS_C_NO_BUFFER, and the next times(s) it is set in ReadFilter and uses the space passed from the Session layer */ ctx->token_ptr = GSS_C_NO_BUFFER; } if (maj_stat!=GSS_S_COMPLETE && maj_stat!=GSS_S_CONTINUE_NEEDED) { display_status("initializing context", maj_stat, min_stat); return ESI_ERR; } if (send_tok.length != 0) { if ((*Send_f)(Handle, send_tok.value , send_tok.length) != 0) { /* send faild, release buffers */ (void) gss_release_buffer(&min_stat, &send_tok); return ESI_ERR; } } (void) gss_release_buffer(&min_stat, &send_tok); if (maj_stat == GSS_S_COMPLETE) { /* We've established the context. Let's inform the application ! */ ctx->established = 1; /* application "connect" callback */ (*connect_cb)(Handle, connectClientData, NULL); } return ESI_OK;
E-16
PATROLAPI
Reference Manual
} /* end of client_establish_context */
esi_RetCode esi_Connect(EsiSendProc Send_f, int Handle, esi_ContextPtr ctx, void* connectClientData, EsiConnProc connect_cb ) { if (build_server_name (SES_DOMAIN_SERVICE_NAME, ctx) == ESI_ERR) { /* failed to translate target name into GSS format */ return ESI_ERR; }
/* Phase 2. Start context establishment. It will be done async. */ if (client_establish_context(Send_f, Handle, ctx, connectClientData, connect_cb ) == ESI_ERR ) { return ESI_ERR; } return ESI_OK; /* connected */ }
esi_RetCode esi_Read (char** buffer, int* len, esi_ContextPtr ctx, EsiSendProc Send_f, int Handle, void* connectClientData, EsiConnProc connect_cb, int* flag ) { gss_buffer_desc recv_tok;/* received message */ gss_buffer_desc data_buf;/* decrypted data from the message */ OM_uint32 maj_stat, min_stat;/* GSS API call statuses */ int state;/* set to 1 by GSS if the message was encrypted */ int ret;
/* put the recieved token in a GSS native buffer */ recv_tok.value = (void*) *buffer;
ESI Examples
E-17
recv_tok.length = *len; if (!CONTEXT_ESTABLISHED(ctx)) { if (IS_CLIENT(ctx)) { /* CLIENT SIDE context establishement */ ctx->token_ptr = &recv_tok; /* We just recieved a token from the server. Use it for context establishing loop */ if (client_establish_context(Send_f, Handle, ctx, connectClientData, connect_cb ) == ESI_ERR ) { return ESI_ERR; } } else { /* SERVER SIDE: context establishement */ ctx->token_ptr = &recv_tok; if (server_establish_context(Send_f, Handle, ctx, s_server_creds) == ESI_ERR) { return ESI_ERR; } } return ESI_CONTINUE; } /* Regular data exchange */ /* unseal the data */ ret = esi_unseal (&maj_stat, &min_stat, ctx->gss_context, &recv_tok, &data_buf, &state); if (ret == ESI_ERR) { display_status("unsealing message", maj_stat, min_stat); return ESI_ERR; }
E-18
PATROLAPI
Reference Manual
/* Send the data to application layer * ---------------------------------*/ /* 'state' indicates if the message was encrypted. It depends on the QOP (Quality Of Protection) for the current security context */ *buffer = (char *)malloc(data_buf.length); if (!*buffer) return (ESI_ERR); memcpy (*buffer, (char *)data_buf.value, data_buf.length); /*buffer = data_buf.value;*/ *len = data_buf.length; *flag = 1; /* free the buffer, if it is 0 it means application does not have to free it */ (void) gss_release_buffer(&min_stat, &data_buf);
return ESI_OK; }
esi_RetCode esi_Write (unsigned char** buffer, int* len, esi_ContextPtr ctx, void* data, EsiQueueMessageProc queue_msg_fn) { OM_uint32 maj_stat; OM_uint32 min_stat; gss_buffer_desc in_buf, out_buf; int state; /* set to 1 by GSS if the message was encrypted */ int ret;
if (!CONTEXT_ESTABLISHED(ctx)) { /* Security Context is not established yet, just send * the data without any conversion */ queue_msg_fn(data, (char*)*buffer, *len); return ESI_OK; }
ESI Examples
E-19
/* Regular data exchange */ /* Seal the data */ in_buf.value = *buffer; in_buf.length= *len; ret = esi_seal (&maj_stat, &min_stat, ctx->gss_context, &in_buf, &out_buf, &state); if (ret == ESI_ERR) { /* if the encryption failed, drop the session. Something is wrong ! */ display_status("sealing message", maj_stat, min_stat); return ESI_ERR; } *buffer = out_buf.value; *len = out_buf.length; /* queue the data */ queue_msg_fn(data, (char*)*buffer, *len); /* release the local buffer; */ (void) gss_release_buffer(&min_stat, &out_buf); return ESI_OK; } /* end of esi_Write */ /* * This function displays on stderr and in the error log * the GSS-API messages associated with maj_stat and min_stat, * each preceeded by "GSS-API error <msg>: " and followed by a newline. */ void display_status(char* msg,/* a string to be displayed with the message */ OM_uint32 maj_stat, /* the GSS-API major status code */ OM_uint32 min_stat) /* the GSS-API minor status code */ { display_status_1("(GSS) " , msg, maj_stat, GSS_C_GSS_CODE); display_status_1("(MECH)", msg, min_stat, GSS_C_MECH_CODE); } /* prints GSS Message accosiated with CODE and TYPE on stderr and error log */ static void display_status_1(char* subsystem, char *m, OM_uint32 code, int type)
E-20
PATROLAPI
Reference Manual
{ OM_uint32 maj_stat, min_stat; gss_buffer_desc msg; OM_uint32 msg_ctx; msg_ctx = 0; while (1) { maj_stat = gss_display_status(&min_stat, code, type, GSS_C_NULL_OID, &msg_ctx, &msg); fprintf(stderr, "GSS-API %s error %s: %s\n", subsystem, m, (char *)msg.value); printf ("GSS-API %s error %s: %s\n",subsystem, m, (char *)msg.value); (void) gss_release_buffer(&min_stat, &msg); if (!msg_ctx) break; } } #if defined(aix) BEGIN_ESI_EXPORTS ESI_EXPORT("SdkInit", SdkInit, NULL) ESI_EXPORT("SdkFini", SdkFini, NULL) ESI_EXPORT("esi_ServerInit",esi_ServerInit, NULL) ESI_EXPORT("esi_ValidateAccount",esi_ValidateAccount, NULL) ESI_EXPORT("esi_GetVersion", esi_GetVersion, NULL) ESI_EXPORT("esi_IsTrusted", esi_IsTrusted, NULL) ESI_EXPORT("esi_AllocateContext", esi_AllocateContext, NULL) ESI_EXPORT("esi_FreeCtx", esi_FreeCtx, NULL) ESI_EXPORT("esi_GetPeerName", esi_GetPeerName, NULL) ESI_EXPORT("esi_IsClient", esi_IsClient, NULL) ESI_EXPORT("esi_IsEstablished", esi_IsEstablished, NULL) ESI_EXPORT("esi_Connect", esi_Connect, NULL) ESI_EXPORT("esi_Read", esi_Read, NULL) ESI_EXPORT("esi_Write", esi_Write, NULL) END_ESI_EXPORTS #endif /*aix*/
Note
Add the -Daix compilation ag to the AIX make les for AIX 4.1 platform to activate the AIX code.
ESI Examples
E-21
E-22
PATROLAPI
Reference Manual
F
F F
Example of annotate() Function

This appendix provides an the following example:
annotate() Example. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . F-2
F-1
annotate() Example
The following example shows of how to use the annotate() function in a custom interface.
// the following 3 functions are helper functions to show you // how to use annotate() function in IPatrolAgent interface HRESULT CreateVariant4BSTR(VARIANT *pvar, BSTR bstr) { VariantInit (pvar); V_VT(pvar) = VT_BSTR; V_BSTR(pvar) = bstr; return S_OK; } HRESULT CreateSafeArray(SAFEARRAY **ppsa, int numElements, BSTR* pbstr) { SAFEARRAYBOUND rgsabound[1]; VARIANT var; long ix[1]; if (NULL == ppsa || 0 == numElements) return E_FAIL;
rgsabound[0].lLbound = 0; rgsabound[0].cElements = numElements; *ppsa = SafeArrayCreate(VT_VARIANT, 1, rgsabound); if (NULL == *ppsa) return E_OUTOFMEMORY; for (int i=0; i<numElements; i++) { CreateVariant4BSTR(&var, pbstr[i]); ix[0] = i; SafeArrayPutElement(*ppsa, ix, &var); } return S_OK; }
HRESULT AnnotateArg(VARIANT* pvar) { int count=3;

F-2
PATROLAPI
Reference Manual
BSTR pbstr[3]; SAFEARRAY *psa; pbstr[0]= SysAllocString (L"progarg1\n100"); pbstr[1]= SysAllocString (L"progarg2\n200"); pbstr[2]= SysAllocString (L"progarg3\n300"); CreateSafeArray(&psa, count, pbstr); VariantInit (pvar); V_VT(pvar) = VT_ARRAY | VT_VARIANT; V_ARRAY(pvar) = psa;
return S_OK; } void main() { BSTR bstrRet=0, bstrName, bstrFormat; VARIANT v; ..... /*get an interface pointer of IPatrolAgent, setup bstrName, bstrFormat*/ ...... ....... /* prepare for the pvarData*/ AnnotateArg(&v); hr = pIPatrolAgent->annotate(bstrName,bstrFormat,&v,&bstrRet); ..... }
F-3
F-4
PATROLAPI
Reference Manual
Glossary
1 1Review copyRrr
Glossary
access control list
A list set up by a PATROL Agent conguration variable and used to restrict PATROL Console access to a PATROL Agent. A PATROL Console can be assigned access rights to perform PATROL Developer Console, Agent conguration, PATROL Operator Console, or event manager activities. See PATROL Agent namespace. A PATROL Console feature that constructs SQL statements to query PATROL Agents connected to the Console. Agent Query produces a tabular report containing information about requested objects and can be used to perform some object management activities, such as disconnecting and reconnecting computers. Queries can be saved, reissued, added, or changed. PATROL offers some built-in queries in the Quick Query item on the Tools menu from the PATROL Console main menu bar. See also Quick Query. An indication that either a parameter for an object has returned a value within the alarm range or that application discovery has discovered a missing le or process since the last application check. The alarm state of the object is indicated by a red, ashing icon. See also warning. A range of values that serve as thresholds for a warning state or an alarm state; alert range values cannot fall outside border range values, if set. See also border range, border action, and recovery action.
Glossary 1
Agent namespace Agent Query
alarm
alert range
ALL_ COMPUTERS class
The highest computer class level in PATROL. Attributes assigned to this class will be inherited by all computer classes known to PATROL. See also computer class. A specially marked point on a parameter graph that provides detailed information about a parameter at a particular point in time. The associated data is accessed by double-clicking the data point, which is represented by a user-specied character (the default is an asterisk). See also parameter. An account that you dene at KM setup; can be changed for an application class or instance. An application account is commonly used to connect to an RDBMS on a server where the database resides or to run SQL commands. The interval at which application discovery occurs. The PATROL Agent process cache (as opposed to the system process cache) is checked to ensure that all application instances and les previously discovered still exist there. See also application discovery, application discovery rules, prediscovery, process cache refresh, PSL discovery, and simple discovery. The object class to which an application instance belongs; also, its representation as a container (Unix) or folder (Windows NT) on the PATROL Console. You can use a PATROL Developer Console to add or change application classes. See also class. A PATROL Agent procedure carried out at preset intervals on each monitored computer to discover application instances. When instances are discovered, an icon appears on your desktop. The application class includes rules for discovering processes and les by using simple process and le matching or PSL commands. Application denition information is checked against the information in the PATROL Agent process cache, which is periodically updated. Each time the PATROL Agent process cache is refreshed, application discovery is triggered. See also application check cycle, application discovery rules, PATROL Agent process cache, prediscovery, PSL discovery, and simple discovery.
annotated data point
application account
application check cycle
application class
application discovery
PATROLAPI
Reference Manual
application discovery rules
A set of rules stored by the PATROL Agent and periodically evaluated to nd out whether a specic instance of an application class exists in the monitored environment. The rules describe how a PATROL Agent can detect instances of the application on a machine. There are two types of application discovery: simple and PSL; PSL discovery can include prediscovery rules as well as discovery rules. See also application check cycle, application discovery, simple discovery, prediscovery, and PSL discovery. A feature used from the PATROL Console to hide all instances of selected application classes for a particular computer. The PATROL Agent continues to monitor the application instances by running parameter commands and recovery actions. See also unload a KM. A system resource discovered by PATROL. Contains the information and attributes of the application class that it belongs to. See also application class, and instance. The condition of an application class or an application instance. The most common application states are OK, warning, and alarm. An application class or instance icon can also show an ofine condition. See also computer state and parameter state. A characteristic that is assigned to a PATROL object (computer class, computer instance, application class, or application instance) and that you can use to monitor and manage that object. An attribute can be a command type, parameter, menu command, InfoBox command, PATROL setup command, state change action, or environment variable. An attribute can be dened globally for all instances of a class or locally for a particular computer or application instance. An instance inherits attributes from a class; however, an attribute dened at the instance level overrides inherited attributes. See also global level and local level.
application lter
application instance
application state
attribute
Glossary
border action
A command or recovery action associated with a parameter border range and initiated when that range has been breached. Border actions can be initiated immediately when the parameter returns a value outside the border range, after a warning or alarm has occurred a specied number of times, or after all other recovery actions have failed. See also border range. A range of values that serve as thresholds for a third-level alert condition when it is possible for a parameter to return a value outside of the alarm range limits. When a border range is breached, border actions can be initiated. See also border action. An internal command available from the PATROL Agent that manages and monitors functions such as resetting the state of an object, refreshing parameters, and echoing text; identied by the naming convention %command_name. See also built-in macro variable. An internal variable created and maintained by PATROL for use in built-in commands and PSL; identied by the naming convention %{variable_name}. See also built-in command. A plot of parameter data values made by the PATROL Console Charting Server. See multigraph container and PATROL Console Charting Server. See PATROL Console Charting Server. The object classication in PATROL where global attributes can be dened; these attributes are then inherited by instances of this class. An instance belongs to a computer class or an application class. See also application class, computer class, and event class. A type of parameter that contains instructions for gathering values for consumer parameters to display. A collector parameter does not display any value, issue alarms, or launch recovery actions. (A standard parameter can have collector properties.) See also consumer parameter, parameter, and standard parameter.
border range
built-in command
built-in macro variable
chart
Charting Server class
collector parameter
PATROLAPI
Reference Manual
command line argument
An option for starting a PATROL Agent or a PATROL Console at the operating system command line. PATROL Agent arguments include names of KMs to load and port numbers for Agent-Console connection. PATROL Console arguments include connection mode (Developer or Operator), user ID to start the PATROL Console, names of KMs to load, and names of the desktop les to use. See PATROL Command Line Interface (CLI). The component that provides basic text editing functions for a PATROL Developer Console. It is commonly used to add or change commands (menu commands, parameter data collection and recovery actions, InfoBox, setup commands, and state change actions). The designation assigned to a command according to its manner of execution. This attribute must be dened for a parameter command, a parameter recovery action, a menu command, an InfoBox command, a setup command, or a state change action. The PATROL Console provides two command types: operating system and PSL. PATROL KMs provide other command types. Only a PATROL Developer Console can be used to add or change command types. The process of saving to PATROL Agent machines the changes that have been made to a KM by a PATROL Developer Console. A PATROL user can disable a PATROL Consoles ability to commit KM changes. The basic object class to which computer instances of the same type belong. Examples include Solaris, OSF1, HP, and RS6000. PATROL provides computer classes for all supported machines and operating systems; a PATROL Developer Console can add or change computer classes. A computer running in a PATROL-managed environment and represented by an icon on the PATROL Desktop. Contains the information and attributes of the computer class that it belongs to. See also instance.
Glossary 5
command line interface command text editor
command type
commit
computer class
computer instance
computer state
The condition of a computer. The main computer states are OK, warning, and alarm. A computer icon can show additional conditions that include no output messages pending, output messages pending, void because a connection cannot be established, and void because a connection was previously established but now is broken. See also state. See KM conguration le. See PATROL Agent conguration le. The mode in which the PATROL Console is connected to the PATROL Agent: Developer or Operator. A property of the Add Host dialog box. See also PATROL Developer Console and PATROL Operator Console. A type of parameter that only displays a value that was gathered by a collector parameter or a standard parameter with collector properties. A consumer parameter never issues commands and is not scheduled for execution; however, it has alarm denitions and can run recovery actions. See also collector parameter, parameter, and standard parameter. A custom object that you can create to hold any other objects that you selectsuch as computers, applications, and parametersin a distributed environment. In Windows NT, a container is referred to as a folder. You can drag and drop an object into and out of any container icon at any time. Once a container is dened, the object hierarchy applies at each level of the container. That is, a container icon found within a container icon assumes the variable settings of the container in which it is displayed. See also object hierarchy and PATROL Console Charting Server. To modify properties or attributes locally or globally. See also global level and local level.
conguration le, KM conguration le, PATROL Agent connection mode
consumer parameter
container
customize KM
PATROLAPI
Reference Manual
deactivate a parameter
To stop running a parameter for selected computer or application instances. In the PATROL Console for Windows NT, deactivating a parameter stops parameter commands and recovery actions and deletes the parameter icon from the application instance window without deleting the parameter denition in the KM tree. A deactivated parameter can be reactivated at any time. See also snooze an alarm and suspend a parameter. To stop monitoring an application class and all of its instances on selected computer instances. In the PATROL Console for Windows NT, deactivating an application class deletes the application class and all of its instance icons from the computer window without deleting the application class or denition in the KM tree. A deactivated application class can be reactivated at any time. See also application lter and deactivate a parameter. A le that stores your desktop layout, the computers you monitor, the KMs you loaded, and your PATROL Console user accounts for monitored objects. You can create multiple desktop les for any number of PATROL Consoles. By default, desktop les always have a .dt extension. See also desktop template le. A le that stores information about the desktop setup of one computer. You can create multiple desktop template les for any number of PATROL Consoles. Each PATROL Console user can apply a template to selected computers on the desktop. By default, desktop template les always have a .dtm extension. See also desktop le. A feature of PATROL for Windows NT only. One of the two views of folders available with PATROL for Windows NT. The Desktop tree displays the object hierarchy. See also KM tree. See PATROL Developer Console.
deactivate an application class
desktop le
desktop template le
Desktop tree
Developer Console
Glossary
disable a KM
To temporarily or permanently block an application or KM from loading and to block the PATROL Agent from using that KM. When a KM is disabled (added to the disabled list) in the Agent conguration le, the KM les are not deleted from the PATROL Agent machines, but the PATROL Agent stops using the KM to collect parameter data and run recovery actions. The default is that no KMs are disabled. See also preloaded KM, static KM, and unload a KM. See disable a KM. (Most KMs are composed of individual application les with a .km extension.) See application discovery. A CD or tape containing a copy of one or more BMC Software products; includes software and documentation (user guides and online help systems). A variable used to specify settings, such as directories, for the environment in which PATROL runs. You can set environment variables for computer classes, computer instances, application classes, application instances, and parameters. The occurrence of a change, such as the appearance of a task icon, the launch of a recovery action, the connection of a Console to an Agent, or a state change in a monitored object (computer class, computer instance, application class, application instance, or parameter). Events are captured by the PATROL Agent, stored in an event repository le, and forwarded to an event manager (PEM) if an event manager is connected. The types of events forwarded by the Agent are governed by a persistent lter for each event manager connected to a PATROL Agent. A command that is triggered by the PATROL Agent when an event is acknowledged in an event manager (PEM). See also event escalation command and event notication command.
disabled application
discovery distribution CD or tape
environment variable
event
event acknowledgment command
PATROLAPI
Reference Manual
event catalog
A collection of event classes associated with a particular application. PATROL provides a Standard Event Catalog that contains predened Standard Event Classes for all computer classes and application classes. You can add, customize, and delete an application event catalog only from a PATROL Developer Console. See also event catalog, event class, and Standard Event Catalog. A category of events that you can create according to how you want the events to be handled by an event manager and what actions you want to be taken when the event occurs. Event classes are stored in event catalogs and can be added, modied, or deleted only from a PATROL Developer Console. PATROL provides a number of event classes in the Standard Event Catalog, such as worst application and registered application. See also event catalog and Standard Event Catalog. A command run by the PATROL Agent when certain events occur; used in conjunction with an event manager (PEM). The commands are specied for the event class that the event is associated with. A command can be one of three types: escalation, notication, or acknowledgment. See also event acknowledgment command, event escalation command, and event notication command. The part of an event manager (PEM) where you can store or change comments about any event in the event log. You can do this at any time by accessing the PATROL Event Manager Details window. A command that is triggered by the PATROL Agent when an event is not acknowledged, closed, or deleted within an event manager (PEM) by the end of the escalation period. See also event escalation period, event acknowledgment command, and event notication command.
event class
event class command
Event Diary
event escalation command
Glossary
event escalation period
A period during which an increase occurs in the severity of an event as the result of its persistence. Escalation actions are dened as part of escalation command denitions for event classes and can be triggered only by the PATROL Agent. See also event escalation command. A circular le where events are stored by the PATROL Agent and accessed by an event manager, such as PEM. The le resides on the PATROL Agent machine and retains a limited number of events. When the maximum number of events is reached and a new event is stored, the oldest event is removed in a cyclical fashion. See also parameter history repository. A graphical user interface for monitoring and managing events; can be used with or without the PATROL Console. See also PATROL Event Manager (PEM). A command that is triggered by the PATROL Agent when an event is logged into an event manager (PEM). See also event acknowledgment command and event escalation command. The PATROL-provided category for an event according to a ltering mechanism in an event manager; types include information, state change, error, warning, alarm, and response. See view lter. A kind of scheduling that starts a parameter when certain conditions are met. See also periodic scheduling. Comments about or instructions for dealing with PATROL events as reported by the agent. Expert advice is dened in the Event Properties dialog box in the PATROL Developer Console. PATROL Operator Consoles view expert advice in the PATROL Event Manager. See application lter. See view lter.
event history repository
event manager
event notication command
event type
event view lter event-driven scheduling expert advice
lter, application lter, event view
10
PATROLAPI
Reference Manual
lter, persistent global channel
See persistent lter. A single dedicated connection through which PATROL monitors and manages a specic program or operating system. The PATROL Agent maintains this connection to minimize the consumption of program or operating system resources. In PATROL hierarchy, the level at which object properties and attributes are dened for all instances of an object or class. An object's characteristics (properties) and attributes are inherited from the next higher level on the object hierarchy. See also local level. The interval (in seconds) at which the PATROL Console checks to see if the PATROL Agent is still running. The longer the interval, the lower the network trafc. See also message retries, message time-out, and reconnect polling. Parameter and event values that are collected and stored on each monitored computer. Parameter values are stored in compressed binary les for a specied period of time; events are stored in circular log les until the maximum size is reached. The size and location of parameter history les is specied through either the PATROL Console or the PATROL Agent; size and location of event history les is specied through an event manager, such as PEM, or the PATROL Agent. A compressed binary le in which parameter values (except those that are displayed as text) are stored by the PATROL Agent and accessed by the PATROL Console for a specied number of days (the default is one day). When the number of storage days is reached, those values are removed in a cyclical fashion. The specied level for the parameter history retention period for an object: either inherited from the next higher level in the object hierarchy or set at the local level. If the history retention level is local, the number of days that history is stored (retention period) must be set. See also history retention period.
global level
heartbeat
history
history repository
history retention level
Glossary
11
history retention period
The number of days that parameter values are stored in the history database before they are automatically purged by PATROL. The period can be specied at the class (global) or instance (local) level. History retention can be set for all parameters of a computer class, a computer instance, an application class, or an application instance. History for an individual parameter on an application instance can be manually cleared at any time by a PATROL Console. See also history retention level. The combined settings for a parameter history retention level and period. See also history retention level and history retention period. A window that contains static elds and displays current information about an object, such as the version number of an RDBMS and whether the object is online or ofine. Commands are run when the InfoBox is opened. Information can be manually updated if the InfoBox remains open for a period of time. PATROL provides a number of commands for obtaining and displaying object information in an InfoBox. Only a PATROL Developer Console can be used to add or change commands. Any event that is not a state change or an error. Typical information events occur when a parameter is activated or deactivated, a parameter is suspended or resumed, or application discovery is run. The default setting for PATROL is to prevent this type of event from being stored in the event repository. To store and display this type of event, you must modify the persistent lter setting in the PATROL Agent conguration le. A computer or discovered application that is running in the PATROL-managed environment. An instance has all the attributes of the class that it belongs to. A computer instance is a monitored computer that has been added to the PATROL Console. An application instance is discovered by PATROL. See application discovery, application instance, and computer instance.
history span
InfoBox
information event
instance
12
PATROLAPI
Reference Manual
KM KM conguration le
See Knowledge Module (KM). A le in which the characteristics of a KM are dened through KM menu commands during KM installation and setup (if setup is required). See also Knowledge Module (KM) and PATROL Agent conguration le. A list of KMs to be loaded by a PATROL Agent. See also Knowledge Module (KM). See PATROL KM Migrator and Knowledge Module (KM). See Knowledge Module Package A feature of PATROL for Windows NT only. One of two views of folders available in Windows NT. The KM tree displays computer classes, application classes, and their customized instances in the knowledge hierarchy and also displays the Standard Event Catalog. A PATROL Operator Console can only view the KM tree; only the PATROL Developer Console can change KM properties and attributes. See also Desktop tree and Knowledge Module (KM). The rules by which objects inherit or are assigned attributes. (In the PATROL Console for Windows NT, classes of objects are represented in the Computer Classes and Application Classes sets of folders on the KM tree.) Properties and attributes of a customized instance override those dened for the class to which the instance belongs.
KM list
KM Migrator KM package KM tree
knowledge hierarchy
Glossary
13
Knowledge Module (KM)
A set of les from which a PATROL Agent receives information about resources running on a monitored computer. A KM le can contain the actual instructions for monitoring objects or simply a list of KMs to load. KMs are loaded by a PATROL Agent and a PATROL Console. KMs provide information for the way monitored computers are represented on the PATROL Desktop, for the discovery of application instances and the way they are represented, for parameters that are run under those applications, and for the options available on object pop-up menus. A PATROL Developer Console can change KM knowledge for its current session, save knowledge for all of its future sessions, and commit KM changes to specied PATROL Agent computers. See also commit, KM conguration le, KM list, KM Migrator, KM tree, load KMs, and version arbitration.
Knowledge Module Package
A set of les that compose a PATROL Knowledge Module (KM) and has a .pkg le extension. KM packages are created in a PATROL Developer Console and are stored in the PATROL KMDS Manager. See also Knowledge Module (KM), PATROL Developer Console, PATROL Knowledge Module Deployment Server (PATROL KMDS), and PATROL Knowledge Module Deployment Server Manager. Same as load KMs; most KMs are composed of application les with a .km extension. To place KM les into memory for execution. After conguration and during startup, the PATROL Agent loads the KM les that are listed in its conguration le and that reside on the PATROL Agent machine. When a PATROL Console connects to the PATROL Agent, the KM versions that the Agent executes depend on whether the Console is an Operator Console or a Developer Console. See also Knowledge Module (KM) and version arbitration. The history (stored parameter values) for an object or instance. See also global level and local level.
load applications
load KMs
local history
14
PATROLAPI
Reference Manual
local history retention period local level
The length of time set by the user during which stored parameter values for an object or instance are retained. The hierarchical level of a computer instance or an application instance. Object properties and attributes that are dened globally for all instances of a class can be customized locally for an individual instance. See also global level. See PATROL Master Agent. A feature of UDP only. The number of times that the PATROL Console will resend a message to the PATROL Agent. The greater the number of message retries, the more time the PATROL Console will give the PATROL Agent to respond before deciding that the Agent connection is down and timing out. The number of message retries multiplied by message time-out (in seconds) is the approximate time allowed for a connection verication. See also heartbeat, message time-out, and reconnect polling. A feature of UDP only. The time interval (in seconds) that the PATROL Console will give the PATROL Agent to respond to a connection verication before deciding that the Agent connection is down. The number of message retries multiplied by message time-out is the approximate time allowed for a connection verication. See also heartbeat, message retries, and reconnect polling. A window that displays command output and error messages from the PATROL Console graphical user interface. See also response window, system output window, and task output window. A custom object into which you can drop parameter objects to be plotted as charts. See also PATROL Console Charting Server.
Master Agent message retries
message time-out
message window
multigraph container
Glossary
15
object
A computer class, computer instance, application class, application instance, parameter, or container (folder) in the PATROL-managed environment. Objects have properties and are assigned attributes (command types, parameters, menu commands, InfoBox commands, setup commands, state change actions, and environment variables). Parameter objects have commands and values that are assigned to classes and instances. See also object class, object hierarchy, object icon, and object window. A computer class or application class. See also class, object, and object hierarchy. The structure of object levels in PATROL. On the PATROL Desktop, computers contain application folders (containers) representing a loaded KM, application folders contain one or more application instances, and application instances contain parameters. A graphic that represents a computer instance, application class, application instance, parameter, or container (folder) in the PATROL-managed environment. See also object, object hierarchy, and object window. An open object container (folder) that may contain application class icons, application instance icons, parameter icons, custom containers (folders), and shortcuts. The object window is displayed when you double-click the object icon. See also application instance, computer instance, object, and object icon. Icons that show the state of a PATROL object. An OK icon represents an object in an OK state; a Not OK icon represents an object in a warning or an alarm state. Warning and alarm states are differentiated from each other by not ashing or ashing and by the color of the Not OK icon. See also instance, object, and state. See PATROL Operator Console.
object class
object hierarchy
object icon
object window
OK and Not OK icons
Operator Console
16
PATROLAPI
Reference Manual
OS account
An account that is set up for the PATROL Agent at installation and that is used or can be changed in a conguration utility. All OS commands executed by the PATROL Agent use this account. To disable or change the behavior of a local PATROL application parameter. The changes to the parameter are local to the host running the parameter, and are stored in the agent conguration database. You must be granted specic permissions by a PATROL Administrator through the PATROL User Roles le (ptrlroles.txt) in order to override parameters. See also PATROL roles. The monitoring component of PATROL; run by the PATROL Agent. A parameter periodically uses data collection commands to obtain data on a system resource and then parses, processes, and stores that data on the computer running the PATROL Agent. Parameter data can be accessed from a PATROL Console, PATROLVIEW, or an SNMP console. Parameters have thresholds and can trigger warnings and alarms. If the value returned by the parameter triggers a warning or an alarm, the PATROL Agent noties the PATROL Console and runs any recovery actions associated with the parameter. See also parameter history repository and parameter state. The memory location where current parameter data is kept. In the PATROL Agent's conguration le, you can set the size of the cache, the maximum number of data points that can be stored, and the interval (in seconds) for emptying the cache. Also known as parameter history le. See history repository. See override parameter. The condition of a parameter. The most common parameter states are OK, warning, and alarm. A parameter icon can show additional conditions that include no history, ofine, snoozed, and suspended. A parameter can also be deactivated; when deactivated, no icon is displayed. See also state.
override parameter
parameter
parameter cache
parameter history repository parameter override parameter state
Glossary
17
PATROL Agent
The core component of PATROL architecture; used to monitor and manage host computers. The PATROL Agent can communicate with the PATROL Console, a stand-alone event manager (PEM), PATROLVIEW, and SNMP consoles. From the command line, the PATROL Agent is congured by the pconfig utility; from a graphical user interface, it is congured by the xpconfig utility for Unix or the wpconfig utility for Windows NT). See also PATROL Master Agent. A le in which you can dene the characteristics of the PATROL Agent by setting PATROL Agent conguration variables. You can edit this le by using the pconfig utility, the wpconfig utility, or the xpconfig utility. See also KM conguration le, PATROL Agent conguration variable, pcong, wpcong, and xpcong. The means by which the characteristics of a PATROL Agent are dened. PATROL provides default variable values that can be customized. Conguration variables determine such things as how errors are handled, which KMs are loaded and how, how SNMP support is congured, and how events trigger SNMP traps. See also PATROL Agent conguration le. A feature of PATROL for Windows NT only. Graphical user interface used to install and run the PATROL Agent. A memory array that contains an internal representation of the PATROL object hierarchy. Values in the Agent namespace are available to PSL scripts, eliminating the need to develop code to collect this data. A copy of the process cache of the operating system on a monitored computer; updated periodically. A periodic PATROL Agent process that issues a platform-dependent system query to obtain a list of the active processes. This data is used to update the PATROL Agent process cache.
PATROL Agent conguration le
PATROL Agent conguration variable
PATROL Agent Manager PATROL Agent namespace
PATROL Agent process cache PATROL Agent process cache refresh
18
PATROLAPI
Reference Manual
PATROL Agent run queue PATROL Command Line Interface (CLI)
The order of poll times at which the PATROL Agent executes parameters. See also PSL run queue. An interface program that you can access from the command line of a monitored computer and through which you can run some PATROL products and utilities. With the CLI, you can monitor the state of PATROL Agents remotely, execute PSL functions, and query and control events. The CLI is used in place of the PATROL Console when memory and performance constraints exist. The graphical user interface from which you launch commands and manage the distributed environment monitored by PATROL. The PATROL Console displays all of the monitored computer instances and application instances as icons. It also interacts with the PATROL Agent and runs commands and tasks on each monitored computer. The dialog is event-driven so that messages reach the PATROL Console only when a specic event causes a state change on the monitored computer. See also PATROL Developer Console and PATROL Operator Console. A PATROL function that creates charts and graphs of actual values returned by more than one parameter. Charts and graphs are created by dragging and dropping various parameters into a multigraph container (folder) and plotting the results into a chart. Parameter data is plotted either in real time or from history sets and can be presented in a number of chart styles, including line graphs, pie charts, 3-D bar charts, and area plots. Charts can be viewed through the PATROL Console and printed to a local printer or postscript le. A feature of PATROL for Windows NT only. Graphical user interface used to install and run the PATROL Console. The graphical interface to PATROL that administrators can use to monitor and manage computer instances and application instances and to customize, create, and delete locally loaded Knowledge Modules and commit these changes to selected PATROL Agent machines.
PATROL Console
PATROL Console Charting Server
PATROL Console Manager PATROL Developer Console
Glossary
19
PATROL Event Manager (PEM)
The PATROL event manager that runs under the Unix operating system. You can use the PEM to view and manage events that occur on monitored system resources and that are sent by PATROL Agents. You can access the PEM from the PATROL Console or use it as a stand-alone facility. It works with the PATROL Agent and user-specied lters to provide a customized view of events. See also event manager. A PATROL utility used to convert PATROL history data into an ASCII data le or to store history data directly into a particular relational database management system. See PATROL Knowledge Module Deployment Server. See PATROL Knowledge Module Deployment Server Manager. A PATROL utility used to propagate KM user customizations to newly released versions of PATROL Knowledge Modules. A repository for storage of PATROL KMs and changes to those KMs. The graphical interface for the PATROL KMDS that can be used to manage and enable deployment or distribution KM changes in the production environment. The agent through which a PATROL Agent interacts with an SNMP agent and SNMP manager. The PATROL Master Agent conguration le contains the community name and port number for all agents in such a multiple-agent architecture. The graphical interface to PATROL that operators can use to monitor and manage computer instances and application instances but not to customize or create KMs, commands, and parameters.
PATROL History Loader KM
PATROL KMDS PATROL KMDS Manager PATROL KM Migrator
PATROL Knowledge Module Deployment Server PATROL Knowledge Module Deployment Server Manager PATROL Master Agent
PATROL Operator Console
20
PATROLAPI
Reference Manual
PATROL roles
A set of permissions that grant or remove the ability of a PATROL Console to perform certain functions. PATROL roles are dened in the ptrlroles.txt le, which is read when the console starts. The interpreted and compiled programming language for writing application discovery procedures, parameters, recovery actions, commands, and tasks for monitored computers within the PATROL environment. A feature of PATROL for Windows NT only. A domain group that can be set up by a Windows NT system administrator to restrict user access to a PATROL Developer Console. When a user tries to start a PATROL Developer Console, PATROL checks whether the user is in the patroldev group. If the user is not in the group, a PATROL Operator Console is started instead. An integration package used to link the PATROL Console with network management and other external programs. An integration package used to view events and to monitor and display all the parameters provided by the PATROL Agents and KMs in a network or enterprise management console. The command line utility for setting PATROL Agent conguration variables. See also PATROL Agent conguration le, PATROL Agent conguration variable, wpcong, and xpcong. A kind of scheduling that starts a parameter at a certain time and reruns the parameter at certain intervals. See also event-driven scheduling. A lter maintained by the PATROL Agent for each PATROL Console or event manager that connects to it; used to minimize network trafc by limiting the number and types of events that are forwarded from a PATROL Agent to a PATROL Console or an event manager (PEM).
PATROL Script Language (PSL)
patroldev
PATROLINK
PATROLVIEW
pcong
periodic scheduling
persistent lter
Glossary
21
polling cycle
The schedule on which a parameter starts running and the intervals at which it reruns; the cycle is expressed in seconds. See also event-driven scheduling and periodic scheduling. The menu of commands for a monitored object; accessed by right-clicking for Windows NT or using MB3 for Unix. A quick one-time test written in PSL to determine whether a resource that you want to monitor is installed or running on a monitored computer. The test must include the set("active",2) command. If the results are afrmative, the PATROL Agent runs the discovery script. Prediscovery helps reduce PATROL Agent processing requirements. A KM that is loaded by the PATROL Agent at startup and run as long as the Agent runs. See also disable a KM and static KM. See PATROL Agent process cache refresh. A dialog that contains commands and scripts that dene attributes and other characteristics such as icons. See PATROL Script Language (PSL). A PATROL utility that checks PSL syntax in PATROL commands and tasks. The PSL Compiler is accessed through the dialog boxes for InfoBox commands, menu commands, parameter commands, parameter recovery actions, PATROL setup commands, and state change actions. The compiler can also be run as a command line utility. A PATROL Console utility that debugs PSL scripts; accessed through a computer's pop-up menu. A type of application discovery in which the discovery rules are dened by using PSL. PSL discovery can consist of prediscovery and discovery PSL scripts.
pop-up menu
prediscovery
preloaded KM
process cache refresh property
PSL PSL Compiler
PSL Debugger
PSL discovery
22
PATROLAPI
Reference Manual
PSL Proler
A PATROL utility that helps a PATROL Developer Console tune the CPU usage and minimize child processes or le operations of a newly created KM. When the PSL Proler is enabled, the PATROL Agent starts accumulating and recording prole statistics. A list of the currently executing PSL processes. An item on the Tools menu from the PATROL Console main menu bar that contains built-in predened commands that you can use to query the Agent for frequently needed information. For example, you can query the Agent regularly about all computer instances, application instances, and parameters that are in a warning or alarm state. See also Agent Query. The time interval (in seconds) at which the PATROL Console will try to reconnect to a PATROL Agent that has dropped the previous connection. The longer the interval, the lower the network trafc. See also heartbeat, message retries, message time-out. A procedure that xes a problem that caused a warning or alarm condition. An action dened within a parameter by a user or by PATROL and triggered when the returned parameter value falls within a dened alarm range. An action that forces the PATROL Agent to run one or more parameters immediately, regardless of their polling cycle. Refreshing does not reset the polling cycle but gathers a new data point between polling cycles. The lter used by the PATROL Agent when transmitting events to consoles (event cache) from the event repository (located at the Agent) for statistical reports. An input and output display for many KM menu items that provides a customizable layout of the information (for example, the sort method for outputting system process IDs). See also system output window and task output window.
PSL run queue Quick Query
reconnect polling
recovery action
refresh parameter
reporting lter
response window
Glossary
23
run queue self-polling parameter
See PATROL Agent run queue. A standard parameter that starts a process that runs indenitely and regularly polls itself to check whether the started process is still running; differs from most other parameters that run scripts for a short time and then terminate until the next poll time. Data collection commands for a self-polling parameter must be written in PSL. Any of the les that are saved when changes are made and saved during the current PATROL Console session; includes the le containing changes to KMs loaded on your console (session1.km) and the le containing user preferences (session1.prefs). A command that is initiated by the PATROL Console and run by the PATROL Agent when the PATROL Console connects or reconnects to the Agent. For example, a setup command can initialize an application log le to prepare it for monitoring. PATROL provides some setup commands for computer classes. Only a PATROL Developer Console can add or change setup commands. An alias or copy of an object icon in the PATROL hierarchy. A type of application discovery that uses simple pattern matching for identifying and monitoring les and processes. Simple Network Management Protocol. The communications protocol that is supported in the PATROL Agent and PSL and that is designed for network management systems running on TCP/IP networks. The messages are typically very short and can be just code numbers that the recipient is expected to translate into the desired action. A condition which, when satised, results in an SNMP agent issuing a trap message to other SNMP agents and clients. Within PATROL, all PATROL event class commands can be enabled as SNMP traps.
session le
setup command
shortcut simple discovery
SNMP
SNMP trap
24
PATROLAPI
Reference Manual
snooze an alarm
To temporarily suspend an alarm so that a parameter does not exhibit an alarm state. During the user-set snooze period, the parameter continues to run commands and recovery actions, and the parameter icon appears to be in an OK state. See also deactivate a parameter and suspend a parameter. A PATROL-provided collection of predened event classes for all computer classes and application classes. To add, modify, or delete event classes and commands in the Standard Event Catalog, you must use a PATROL Developer Console. See also event catalog and event class. A type of parameter that collects and displays data as numeric values or text. Standard parameters can also execute commands and gather data for consumer parameters to display. See also collector parameter, consumer parameter, and parameter. See setup command. The condition of a PATROL-monitored object (computer instance, application instance, or parameter). The most common states are OK, warning, and alarm. Object icons can show additional conditions. See also application state, computer state, parameter state, and state change action. A parameter output style that represents the on or yes state of a monitored object as a check mark and the off or no state as the letter x. Parameters with this output style can have alerts (warning and alarm) and recovery actions. Numeric data output for the monitored object can be displayed as a graph. See also stoplight. An action that is stored, maintained, and initiated by the PATROL Console when notied by the PATROL Agent that a monitored object has changed state.
Standard Event Catalog
standard parameter
startup command state
state Boolean
state change action
Glossary
25
static KM
A KM that is not loaded by the PATROL Agent until a PATROL Console with a loaded KM of the same name connects to the Agent. If all PATROL Consoles with a registered interest disconnect from the PATROL Agent, the KMs continue to execute as long as the Agent runs. If the PATROL Agent stops, those static KMs will not be reloaded. See also disable a KM and preloaded KM. A parameter output style that displays OK, warning, and alarm states as green, yellow, and red lights, respectively, on a trafc light. Parameters with this output style can have alerts (warning and alarm) and recovery actions. Numeric data output for the monitored object can be displayed as a graph. See also state Boolean. To stop running a parameter for selected computers or application instances. Suspending a parameter stops parameter commands and recovery actions but does not delete the parameter icon from the application instance window and does not delete the parameter denition from the KM tree in the PATROL Console for Windows NT. A suspended parameter can be resumed at any time. You can suspend a parameter from its pop-up menu. See also deactivate a parameter and snooze an alarm. A message window that displays the output of operating system (OS) and PSL commands and tasks that the PATROL Console and the PATROL Agent submit to a particular computer. PATROL displays a yellow triangle when there are unread messages in the system output window. You can enter OS and PSL commands in the bottom part of the window. A command or group of commands that can execute on one object or several objects simultaneously. A task runs in the background and is not part of the PATROL Agent run queue; a task icon is displayed for each running task.
stoplight
suspend a parameter
system output window
task
26
PATROLAPI
Reference Manual
task output window
A window that contains command output generated by a task (for example, a KM menu command or a parameter warning or alarm); while executing, each task has its own icon, which usually appears in the PATROL Desktop or main window but may appear in an appropriate object window. A point or points that dene a range of values, outside of which a parameter is considered to be in a warning or alarm range. To delete a KM from a PATROL Console session in order to stop monitoring the KM-dened objects on all computers. The KM les are not deleted from the directories on the PATROL Console or the PATROL Agent machines, and the PATROL Agent may continue to collect parameter data and run recovery actions. To prevent the PATROL Agent machine from collecting parameter data and running recovery actions for a KM, disable the KM. See also disable a KM, preloaded KM, and static KM. A protocol selection for the Connection Setup portion of the Customize Properties dialog box for computer instances. The PATROL Console settings that designate the account you want to use to connect to monitored hosts, prevent a Developer Console from downloading its version of a KM to a PATROL Agent upon connection, disable the commit process for a Developer Console, determine certain window and icon display characteristics, specify the event cache size, and indicate whether startup and shutdown commands are enabled; both a Developer and an Operator Console can change user preferences. The KM version comparison that PATROL makes when a PATROL Console connects to a PATROL Agent. By default, PATROL Developer Console KM versions are loaded rather than PATROL Agent KM versions, and PATROL Agent KM versions are loaded rather than PATROL Operator Console KM versions. A lter that can be created in an event manager (PEM) and that screens events forwarded from PATROL Agents. Views can be created, stored, and reapplied to host computers.
threshold
unload a KM
User Datagram Protocol (UDP) user preferences
version arbitration
view lter
Glossary
27
warning
An indication that a parameter has returned a value that falls within the warning range. See also alarm. A feature of PATROL for Windows NT only. The graphical user interface utility for setting PATROL Agent conguration variables. The wpconfig utility can be accessed from a PATROL Agent machine or from a PATROL Developer Console machine from the pop-up menu for a particular computer. See also PATROL Agent conguration le and PATROL Agent conguration variable. A feature of PATROL for Unix only. The graphical user interface utility for setting PATROL Agent conguration variables. You can access the xpconfig utility from a PATROL Agent machine at an xterm session command line or from a PATROL Developer Console machine in the pop-up menu for a particular computer or at an xterm session command line. See also PATROL Agent conguration le and PATROL Agent conguration variable.
wpcong
xpcong
28
PATROLAPI
Reference Manual
Index
Index
A
accessing PATROL Agent COM server through dispatch interface 14-7 annotate() 14-12 annotate_get() 14-14 application management functions PemnBGetApplList() return application class list (blocking) 9-6 PemnBGetApplObj() return application class object (blocking) 9-8 PemnBGetComputerParamList() return computer parameter list (blocking) 9-14 PemnBGetComputerParamObj() return computer parameter (blocking) 9-16 PemnBGetInstList() return application instance list (blocking) 9-19 PemnBGetInstObj() return application instance object (blocking) 9-22 PemnBGetParamList() return instance parameter list (blocking) 9-28 PemnBGetParamObject() return parameter object 9-31 PemnBGetVarList() return variable list (blocking) 9-37 PemnBGetVarObj() return variable object (blocking) 9-40
PemnBPslExec() execute PSL script (blocking) 9-2 PemnBSetVarObj() set PATROL variable (blocking) 9-4 PemnGetApplInstObjAttributes() return instance object attributes 9-25 PemnGetApplList() return application class list 9-6 PemnGetApplObj() return application class object 9-8 PemnGetApplObjAttributes() return application class object attributes 9-11 PemnGetApplObjInfo() return application object info 9-12 PemnGetComputerParamList() return computer parameter list 9-14 PemnGetComputerParamObj() return computer parameter object 9-16 PemnGetInstList() return application instance list 9-19 PemnGetInstObj() return application instance object 9-22 PemnGetInstObjInfo() return instance object information 9-26 PemnGetParamList() return instance parameter list 9-28 PemnGetParamObj() return parameter object 9-31
Index
PemnGetParamObjAttributes() return parameter object attributes 9-34 PemnGetParamObjInfo() return parameter object info 9-35 PemnGetVarList() return variable list 9-37 PemnGetVarObj() return variable object 9-40 array type and index denitions typedef PemnApplAttrArray 3-5 typedef PemnApplAttrEnum 3-6 typedef PemnInstAttrArray 3-23 typedef PemnInstAttrEnum 3-24 typedef PemnParamAttrArray 3-26, 3-27
B
blackout() 14-16
PemnBPing() ping PATROL Agent 5-6 PemnClose() close connection 5-8 PemnGetCommAttributes() get connection attributes 5-9 PemnGetLocalPort() return local port number 5-11 PemnLoop() monitor for connection activity 5-12 PemnOpen() open connection 5-13 PemnSetCommAttributes() set connection attributes 5-16 PemnSetLocalPort() set local port number 5-18 conventions,document xxii create() 14-20 custom interface example of invoking function in 14-11 to access PATROL Agent COM server 14-8
C
change_state() 14-18 COM/DCOM les descriptions of 14-4 COM/DCOM protocol 14-3 comSecurityLevel description of 14-5 comUserAllowed description of 14-5 conguring COM servers COM servers conguring 14-4 Conguring DCOM clients 14-6 conguring PATROL to use ESI on Unix 13-10 conguring PATROL to use ESI on Windows NT 13-12 connection functions
PATROLAPI
D
data management functions PemnBPutStream() send character stream (blocking) 10-2 PemnPutStream() send character stream 10-2 data structures overview 3-3 type denitions (table) 3-3 data type denitions ESI 13-15 DCOM clients conguring 14-6 DCOMCFG.EXE Microsoft DCOM conguration utility 14-4 destroy() 14-22 dispatch interface example of invoking function in 14-10
Reference Manual
guidelines for using 14-7 to access PATROL Agent COM server 14-7 document conventions xxii
E
enumeration denitions typedef PemnEventStatusEnum 3-14 typedef PemnEventTypeEnum 3-15 error messages related to ESI 13-35 ESI 13-3 and PATROL 13-5 and Windows NT registry 13-13 ESI data structures data structures ESI 13-14 esi_Context() 13-15 ESI data type denitions 13-15 EsiAcceptProc 13-15 EsiConnProc 13-17 EsiQueueMessageProc 13-18 EsiSendProc 13-19 ESI Examples descriptions of 13-4 ESI les descriptions of 13-3 ESI functions 13-20 esi_AllocateContext() 13-20 esi_Connect() 13-21 esi_FreeContext() 13-23 esi_GetVersion() 13-24 esi_IsClient() 13-25 esi_IsEstablished() 13-26 esi_IsTrusted() 13-27 esi_Read() 13-28 esi_ServerInit() 13-30 esi_ValidateAccount() 13-31 esi_Write() 13-32
for account verication 13-9 for cleanup 13-9 for initialization 13-9 for message exchange 13-8 for negotiationing communications 13-8 implementing 13-7 mandatory 13-8 optional 13-9 SdkInit() 13-34 ESI library 13-12 ESI operation 13-5 esi_AllocateContext() 13-20 esi_Connect() 13-21 esi_Context() 13-15 esi_FreeContext() 13-23 esi_GetVersion() 13-24 esi_IsClient() 13-25 esi_IsEstablished() 13-26 esi_IsTrusted() 13-27 esi_Read() 13-28 esi_ServerInit() 13-30 esi_ValidateAccount() 13-31 esi_Write() 13-32 EsiAcceptProc 13-15 esiapi.h description of le 13-3 esiapi_impl.c description of example 13-4 esiapi_impl.h description of example 13-4 EsiConnProc 13-17 EsiQueueMessageProc 13-18 ESI-related error messages 13-35 EsiSendProc 13-19 esitypes.h description of le 13-3 event access functions PemnGetArgs() return event arguments 4-2
Index
PemnGetClassName() return event class 4-3 PemnGetDesc() return event description 4-4 PemnGetDiary() get event diary 4-5 PemnGetEid return PATROL event identier 4-6 PemnGetEventCatalogName() return event catalog name 4-7 PemnGetExpectancyStr() return event life expectancy 4-8 PemnGetHandler() return event last user ID 4-9 PemnGetNode() return event host name 4-10 PemnGetNSeverity() return numeric severity 4-11 PemnGetOrigin() return event application class 4-12 PemnGetOwner() return owner user ID 4-13 PemnGetSourceID() return event source ID 4-14 PemnGetStatus() return event status 4-15 PemnGetTime() return event timestamp 4-16 PemnGetType() return event type 4-17 event management functions PemnAddDiary() add text to event diary 8-2 PemnBEventArchive() write events to a le (blocking) 8-7 PemnBEventManageIfMatch() change matching event status 8-18 PemnBEventQuery() return ltered events (blocking) 8-24 PemnBEventReport() summarize ltered events (blocking) 8-37
PemnBGetEventClass() return event class info (blocking) 8-44 PemnBGetEventClassList() list event classes (blocking) 8-48 PemnBSetPersistentFilter() set session event lter (blocking) 8-53 PemnDeneEventClass() dene event class 8-4 PemnEventManage() change event status 8-16 PemnEventManageIfMatch() change matching event status 8-18 PemnEventQuery() return ltered events 8-24 PemnEventRangeManage() change event range status 8-31 PemnEventRangeQuery() return range of events 8-34 PemnEventReport() summarize ltered events 8-37 PemnEvnetArchive() write events to a le 8-7 PemnFlushEvent() ush events to log 8-43 PemnGetEventClass() return event class info 8-44 PemnGetEventClassList() list event classes 8-48 PemnSetEventClassCmd() dene event class command 8-50 PemnSetPersistentFilter() set session event lter 8-53 exists() 14-24 Extended Security Interface 13-3 ExtendedSecurityEnabled ag 13-11, 13-13
F
functions ESI 13-20
PATROLAPI
Reference Manual
PemnAddDiary() add text to event diary 8-2 PemnBEventArchive() write events to a le (blocking) 8-7 PemnBEventManageIfMatch() change matching event status (blocking) 8-18 PemnBEventQuery() return ltered events (blocking) 8-24 PemnBEventReport() summarize ltered events (blocking) 8-37 PemnBExitFunction() exit blocked function 12-2 PemnBGetApplList() return application class list (blocking) 9-6 PemnBGetApplObj() return application class object (blocking) 9-8 PemnBGetComputerParamList() return computer parameter list (blocking) 9-14 PemnBGetEventClass() return event class info (blocking) 8-44 PemnBGetEventClassList() list event classes (blocking) 8-48 PemnBGetInstList() return application instance list (blocking) 9-19 PemnBGetInstObj() return application instance object (blocking) 9-22 PemnBGetParamList() return instance parameter list (blocking) 9-28 PemnBGetParamObj() return parameter object (blocking) 9-31 PemnBGetTimeout() return max wait time default 12-3 PemnBGetVarList() return variable list (blocking) 9-37 PemnBGetVarObj() return variable object (blocking) 9-40 PemnBPing() ping PATROL Agent 5-6 PemnBPslExec() execute PSL script (blocking) 9-2
PemnBPutStream() send character stream (blocking) 10-2 PemnBSend() send PATROL event (blocking) 7-7 PemnBSetPersistentFilter() set session event lter (blocking) 8-53 PemnBSetTimeout() set max wait time default 12-4 PemnBSetVarObj() set PATROL variable (blocking) 9-4 PemnCheckInit() check PEM initialization 11-2 PemnClose() close connection 5-8 PemnDeneEventClass() dene event class 8-4 PemnEncrypt() encrypt password 6-2 PemnEnd() terminate read-only API A-5 PemnError() return last Pemn message A-17 PemnEventArchive() write events to a le 8-7 PemnEventManage() change event status 8-16 PemnEventManageIfMatch() change matching event status 8-18 PemnEventQuery() return ltered events 8-24 PemnEventRangeManage() change event range status 8-31 PemnEventRangeQuery() return range of events 8-34 PemnEventReport() summarize ltered events 8-37 PemnFlushEvent() ush events to log 8-43 PemnFreeEventBuffer() free buffer memory A-6 PemnGetApplInstObjAttributes() return instance object attributes 9-25
Index
PemnGetApplList() return application class list 9-6 PemnGetApplObj() return application class object 9-8 PemnGetApplObjAttributes() return application class object attributes 9-11 PemnGetApplObjInfo() return application class object info 9-12 PemnGetArgs() return event arguments 4-2 PemnGetClassName() return event class 4-3 PemnGetCommAttributes() get connection attributes 5-9 PemnGetComputerParamList() return computer parameter list 9-14 PemnGetComputerParamObj() return computer parameter (blocking) 9-16 PemnGetComputerParamObj() return computer parameter object 9-16 PemnGetDesc() return event description 4-4 PemnGetDiary() get event diary 4-5 PemnGetDourceID() return event source ID 4-14 PemnGetEid() return PATROL event identier 4-6 PemnGetEventCatalogName() return event catalog name 4-7 PemnGetEventClass() return event class info 8-44 PemnGetEventClassList() list event classes 8-48 PemnGetExpectancyStr() return event life expectancy 4-8 PemnGetHandler() return event last user ID 4-9 PemnGetInstList() return application instance list 9-19
PemnGetInstObj() return application instance object 9-22 PemnGetInstObjInfo() return instance information 9-26 PemnGetLastMessage() return last API message 11-3 PemnGetLocalPort() return local port number 5-11 PemnGetNode() return event host name 4-10 PemnGetNSeverity() return numeric severity 4-11 PemnGetOrigin() return event application class 4-12 PemnGetOwner() return owner user ID 4-13 PemnGetParamList() return instance parameter list 9-28 PemnGetParamObj() return parameter object 9-31 PemnGetParamObjAttributes() return parameter object attributes 9-34 PemnGetParamObjInfo() return parameter object info 9-35 PemnGetStatus() return event status 4-15 PemnGetTime() return event timestamp 4-16 PemnGetType() return event type 4-17 PemnGetVarList() return variable list 9-37 PemnGetVarObj() return variable object 9-40 PemnLock() read lock event log A-7 PemnLoop() monitor for connection activity 5-12 PemnOpen() open connection 5-13 PemnPutStream() send character stream 10-2
PATROLAPI
Reference Manual
PemnQueryEvents() query event log A-9 PemnReceive() lter incoming events 7-2 PemnRegisterUserMessageHandler() register user message process 11-4 PemnSend() send PATROL event 7-7 PemnSendIdentity() send account info 6-3 PemnSetCommAttributes() set connection attributes 5-16 PemnSetEventClassCmd() dene event class command 8-50 PemnSetLocalPort() set local port number 5-18 PemnSetPersistentFilter() set session event lter 8-53 PemnStart() start read-only API A-13 PemnUnlock() release log le read lock A-15
G
get() 14-26 get_psl_errno() 14-30 get_ranges() 14-31 get_vars() 14-33 getenv() 14-28
ipa.h description of le 14-4 ipa.tlb description of le 14-4 ipa_i.c description of le 14-4 IPatrolAgent interface 14-3 IPatrolAgent interface function annotate() 14-12 annotate_get() 14-14 blackout() 14-16 change_state() 14-18 create() 14-20 destroy() 14-22 exists() 14-24 get() 14-26 get_psl_errno() 14-30 get_ranges() 14-31 get_vars() 14-33 getenv() 14-28 is_var() 14-37 print() 14-41 PslExecute() 14-39 set() 14-43 set_alarm_ranges() 14-45 unset() 14-47 is_var() 14-37
M
Mandatory ESI functions 13-8 Microsoft DCOM conguration utility 14-4, 14-5 miscellaneous denitions typedef PemnClientData 3-9 miscellaneous functions PemnCheckInit() check PEM initialization 11-2 PemnGetLastMessage() return last API message 11-3
Index 7
H
HRESULT 14-8
I
implementing ESI functions 13-7 interface for COM/DCOM 14-3 Introduction to the API 1-2
PemnRegisterUserMessageHandler() register user message process 11-4
O
object handle denitions PemnEventHandle 3-13 typedef PemnApplObjHandle 3-7 typedef PemnCommHandle 3-11 typedef PemnInstObjHandle 3-25 typedef PemnParamObjHandle 3-28 typedef PemnReportHandle 3-33 typedef PemnVarObjHandle 3-35 online documentation xxi optional ESI functions 13-9
P
PATROL and ESI 13-5 conguring to use ESI on Unix 13-10 on Windows NT 13-12 PATROL Agent COM server accessing through custom interface 14-8 PATROL Agent COM variables comSecurityLevel 14-5 comUserAllowed 14-5 descriptions of 14-5 PATROL COM/DCOM les descriptions of 14-4 PATROL event log locking and unlocking A-3 synchronizing read/write actions A-2 PATROL Event Manager receiving events from 1-10 sending events to 1-11 patrol.conf le 13-10 PCCFG.EXE
PATROLAPI
using to congure ESI 13-12 Pema functions execution sequence A-4 Pemn functions benets of 1-9 execution sequence 1-7, 1-12 introduction 1-8 models blocking 1-6 event-driven 1-6 PEMN_BUFF_OVERFLOW A-18 PEMN_CORRUPT_CONTROL A-18 PEMN_CORRUPT_LOCK A-18 PEMN_EMPTY A-18 PEMN_ERROR A-18 PEMN_LOCK_WRITE_ERROR A-19 PEMN_MEMORY_ERROR A-19 PEMN_NO_FILE A-19 PEMN_NO_NULL_HANDLE A-19 PEMN_OK A-19 PEMN_ONLY_ONE_READER A-19 PEMN_WRONG_VERSION A-20 PemnAddDiary() add text to event diary 8-2 PemnBEventArchive() write events to a le (blocking) 8-7 PemnBEventManageIfMatch() change matching event status (blocking) 8-18 PemnBEventQuery() return ltered events (blocking) 8-24 PemnBEventReport() summarize ltered events (blocking) 8-37 PemnBExitFunction() exit blocked function 12-2 PemnBGetApplList() return application class list (blocking) 9-6 PemnBGetApplObj() return application class object (blocking) 9-8 PemnBGetComputerParamList() return computer parameter list (blocking) 9-14
Reference Manual
PemnBGetComputerParamObj() return computer parameter (blocking) 9-16 PemnBGetEventClass() return event class info (blocking) 8-44 PemnBGetEventClassList() list event classes (blocking) 8-48 PemnBGetInstList() return application instance list (blocking) 9-19 PemnBGetInstObj() return application instance object (blocking) 9-22 PemnBGetInstObjInfo() return instance information 9-26 PemnBGetParamList() return instance parameter list (blocking) 9-28 PemnBGetParamObj() return parameter object (blocking) 9-31 PemnBGetTimeout() return max wait time default 12-3 PemnBGetVarList() return variable list (blocking) 9-37 PemnBGetVarObj() return variable object (blocking) 9-40 PemnBPing() ping PATROL Agent 5-6 PemnBPslExec() execute PSL script (blocking) 9-2 PemnBPutStream() send character stream (blocking) 10-2 PemnBSend() send PATROL event (blocking) 7-7 PemnBSetPersistentFilter() set session event lter (blocking) 8-53 PemnBSetTimeout() set max wait time default 12-4 PemnBSetVarObj() set PATROL variable (blocking) 9-4 PemnCheckInit() check PEM initialization 11-2 PemnClose() close connection 5-8 PemnDeneEventClass() dene event class 8-4
PemnEncrypt() encrupt password 6-2 PemnEnd() terminate read-only API A-5 PemnError() return last Pemn message A-17 PemnEventArchive() write events to a le 8-7 PemnEventManage() change event status 8-16 PemnEventManageIfMatch() change matching event status 8-18 PemnEventQuery() return ltered events 8-24 PemnEventRangeManage() change event range status 8-31 PemnEventRangeQuery() return range of events 8-34 PemnEventReport() summarize ltered events 8-37 PemnFlushEvent() ush events to log 8-43 PemnFreeEventBuffer() free buffer memory A-6 PemnGetApplList() return application class list 9-6 PemnGetApplObj() return application class object 9-8 PemnGetApplObjAttributes() return application class object attributes 9-11 PemnGetApplObjInfo() return application object info 9-12 PemnGetArgs() return event arguments 4-2 PemnGetClassName() return event class 4-3 PemnGetCommAttributes() get connection attributes 5-9 PemnGetComputerParamList() return computer parameter list 9-14 PemnGetComputerParamObj() return computer parameter object 9-16 PemnGetDesc() return event description 4-4 PemnGetDiary() get event diary 4-5 PemnGetEid() return PATROL event identier 4-6
Index
PemnGetEventCatalogName() return event catalog name 4-7 PemnGetEventClass() return event class info 8-44 PemnGetEventClassList() list event classes 8-48 PemnGetExpectancyStr() return event life expectancy 4-8 PemnGetHandler() return event last user ID 4-9 PemnGetInstList() return application instance list 9-19 PemnGetInstObj() return application instance object 9-22 PemnGetInstObjAttributes() return instance object attributes 9-25 PemnGetLastMessage() return last API message 11-3 PemnGetLocalPort() return local port number 5-11 PemnGetNode() return event host name 4-10 PemnGetNSeverity() return numeric severity 4-11 PemnGetOrigin() return event application class 4-12 PemnGetOwner() return owner user ID 4-13 PemnGetParamList() return instance parameter list 9-28 PemnGetParamObj() return parameter object 9-31 PemnGetParamObjAttributes() return parameter object attributes 9-34 PemnGetParamObjInfo() return parameter object info 9-35 PemnGetSourceID() return event source ID 4-14 PemnGetStatus() return event status 4-15 PemnGetTime() return event timestamp 4-16
PemnGetType() return event type 4-17 PemnGetVarList() return variable list 9-37 PemnGetVarObj() return variable object 9-40 PemnLock() read lock event log A-7 PemnLoop() monitor for connection activity 5-12 PemnOpen() open connection 5-13 PemnPutStream() send character stream 10-2 PemnQueryEvents() query event log A-9 PemnReceive() lter incoming events 7-2 PemnRegisterUserMessageHandler() register user message process 11-4 PemnSend() send PATROL event 7-7 PemnSendIdentity() send account info 6-3 PemnSetCommAttributes() set connection attributes 5-16 PemnSetEventClassCmd() dene event class command 8-50 PemnSetLocalPort() set local port number 5-18 PemnSetPersistentFilter() set session event lter 8-53 PemnStart() start read-only API A-13 PemnUnlock() release log le read lock A-15 Pemr functions execution sequence A-3 introduction A-2 print() 14-41 PslExecute() 14-39
R
read-only functions PemnEnd() terminate read-only API A-5 PemnError() return last Pemn message A-17
10
PATROLAPI
Reference Manual
PemnFreeEventBuffer() free buffer memory A-6 PemnLock() read lock event log A-7 PemnQueryEvents() query event log A-9 PemnUnlock() release log le read lock A-15 PemrStart() start read-only API A-13 read-only messages PEMN_BUFF_OVERFLOW A-18 PEMN_CORRUPT_CONTROL A-18 PEMN_CORRUPT_LOCK A-18 PEMN_EMPTY A-18 PEMN_ERROR A-18 PEMN_LOCK_WRITE_ERROR A-19 PEMN_MEMORY_ERROR A-19 PEMN_NO_FILE A-19 PEMN_NO_NULL_HANDLE A-19 PEMN_OK A-19 PEMN_ONLY_ONE_READER A-19 PEMN_WRONG_VERSION A-20 related documentation xxi release notes xxi routine callback denitions typedef PemnBDisconnectCallback 3-8 typedef PemnCommCallback 3-10 routine handler denitions typedef PemnDumpEventHandler 3-12 typedef PemnGetApplObjHandler 3-16 typedef PemnGetEventClassHandler 3-17 typedef PemnGetEventClassListHandler 3-18 typedef PemnGetInstObjHandler 3-19 typedef PemnGetListHandler 3-20 typedef PemnGetParamObjHandler 3-21 typedef PemnGetVarObjHandler 3-22 typedef PemnQueryEventHandler 3-29 typedef PemnReceiveEventHandler 3-30 typedef PemnReportEventHandler 3-32
typedef PemnUserMessage Handler 3-34
S
SdkInit() 13-34 security functions PemnEncrypt() encrypt password 6-2 PemnSendIdentity() send account info 6-3 send/receive functions PemnBSend() sendPATROL event (blocking) 7-7 PemnReceive() lter incoming events 7-2 PemnSend() send PATROL event 7-7 set() 14-43 set_alarm_ranges() 14-45 special blocking functions PemnBExitFunction() exit blocked function 12-2 PemnBGetTimeout() return max wait time default 12-3 PemnBSetTimeout() set max wait time default 12-4
T
type denitions PemnCommCallback 3-10 PemnGetEventClassHandler 3-17 typedef PemaGetInstObjHandler 3-19 typedef PemnApplAttrArray 3-5 typedef PemnApplAttrEnum 3-6 typedef PemnApplObjHandle 3-7 typedef PemnApplObjHandler 3-16 typedef PemnBDisconnectCallback 3-8 typedef PemnClientData 3-9 typedef PemnCommHandle 3-11
Index
11
typedef PemnDumpEventHandle 3-12 typedef PemnEventHandle 3-13 typedef PemnEventStatusEnum 3-14 typedef PemnEventTypeEnum 3-15 typedef PemnGetEventClassListHandler 3-18 typedef PemnGetListHandler 3-20 typedef PemnGetParamObjHandler 3-21 typedef PemnGetVarObjHandler 3-22 typedef PemnInstAttrArray 3-23 typedef PemnInstAttrEnum 3-24 typedef PemnInstObjHandle 3-25 typedef PemnParamAttrArray 3-26 typedef PemnParamAttrEnum 3-27 typedef PemnParamObjHandle 3-28 typedef PemnQueryEventHandler 3-29 typedef PemnReceiveEventHandler 3-30 typedef PemnReportEventHandler 3-32 typedef PemnReportHandle 3-33 typedef PemnUserMessageHandler 3-34 typedef PemnVarObjHandle 3-35 type denitions (table) 3-3 typedef PemaGetInstObjHandler 3-19 typedef PemnApplAttrArray 3-5 typedef PemnApplAttrEnum 3-6 typedef PemnApplObjHandle 3-7 typedef PemnBDisconnectCallback 3-8 typedef PemnClientData 3-9 typedef PemnCommCallback 3-10 typedef PemnCommHandle 3-11 typedef PemnDumpEventHandle 3-12 typedef PemnEventHandle 3-13 typedef PemnEventStatusEnum 3-14 typedef PemnEventTypeEnum 3-15 typedef PemnGetApplObjHandler 3-16 typedef PemnGetEventClassHandler 3-17 typedef PemnGetEventClassListHandler 3-18 typedef PemnGetListHandler 3-20 typedef PemnGetParamObjHandler 3-21
typedef PemnGetVarObjHandler 3-22 typedef PemnInstAttrArray 3-23 typedef PemnInstAttrEnum 3-24 typedef PemnInstObjHandle 3-25 typedef PemnParamAttrArray 3-26 typedef PemnParamAttrEnum 3-27 typedef PemnParamObjHandle 3-28 typedef PemnQueryEventHandler 3-29 typedef PemnReceiveEventHandler 3-30 typedef PemnReportEventHandler 3-32 typedef PemnReportHandle 3-33 typedef PemnUserMessageHandler 3-34 typedef PemnVarObjHandle 3-35
U
Unicode string 14-9 unset() 14-47
W
Windows NT registry and ESI 13-13
12
PATROLAPI
Reference Manual
Notes
*100024888* *100024888* *100024888* *100024888*

*100024888*
PATROLAPI
Reference Manual

BMC Patrol API

Încărcat de

Informații document

Descriere originală:

Titlu original

Drepturi de autor

Formate disponibile

Partajați acest document

Partajați sau inserați document

Opțiuni de partajare

Vi se pare util acest document?

Este necorespunzător acest conținut?

Drepturi de autor:

Formate disponibile

BMC Patrol API

Încărcat de

Drepturi de autor:

Formate disponibile

PATROL API

September 30, 1999

Contacting BMC Software

BMC Software, Inc., Condential and Proprietary Information

BMC Software, Inc., Condential and Proprietary Information

BMC Software, Inc., Condential and Proprietary Information

PemnEncrypt() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 6-2 PemnSendIdentity() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 6-3

PemnReceive() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 7-2 PemnSend(), PemnBSend() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 7-7

BMC Software, Inc., Condential and Proprietary Information

Event Management Functions

PemnPutStream(), PemnBPutStream() . . . . . . . . . . . . . . . . . . . . . .10-2

PemnCheckInit() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 11-2 PemnGetLastMessage() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 11-3 PemnRegisterUserMessageHandler() . . . . . . . . . . . . . . . . . . . . . . . 11-4

PemnBExitFunction() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 12-2 PemnBGetTimeout() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 12-3 PemnBSetTimeout() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 12-4

BMC Software, Inc., Condential and Proprietary Information

PATROL COM/DCOM Interface

A-7 A-9 A-13 A-15 A-17 A-18

B-2 B-2 B-2 B-3

BMC Software, Inc., Condential and Proprietary Information

BMC Example: esiapi_impl.h . . . . . . . . . . . . . . . . . . . . . . . . . . . . . E-2 BMC Example: esiapi_impl.c . . . . . . . . . . . . . . . . . . . . . . . . . . . . . E-4

annotate() Example . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . F-2

BMC Software, Inc., Condential and Proprietary Information

BMC Software, Inc., Condential and Proprietary Information

BMC Software, Inc., Condential and Proprietary Information

BMC Software, Inc., Condential and Proprietary Information

BMC Software, Inc., Condential and Proprietary Information

About This Manual

BMC Software, Inc., Condential and Proprietary Information

About This Manual

How This Book Is Organized

BMC Software, Inc., Condential and Proprietary Information

Chapter/Appendix Number and Title

Appendix A, Read-Only Functions

Appendix E, ESI Examples

Appendix F, Example of annotate() Function

BMC Software, Inc., Condential and Proprietary Information

About This Manual

Online and Printed Books

To Request Additional Printed Books

BMC Software, Inc., Condential and Proprietary Information

About This Manual

Notes provide additional information about the current subject.

An example claries a concept discussed in text.

BMC Software, Inc., Condential and Proprietary Information

denotes one-step instructions.

BMC Software, Inc., Condential and Proprietary Information

About This Manual

right mouse button

BMC Software, Inc., Condential and Proprietary Information

Overview of the PATROL API

BMC Software, Inc., Condential and Proprietary Information

Overview of the PATROL API

How the PATROL API Fits Into PATROL

How You Can Interact with PATROL Agents

act as specialized application browsers of PATROL.

How You Can Integrate Applications and Manage the Enterprise

BMC Software, Inc., Condential and Proprietary Information

Overview of the PATROL API

Accessing the PEM Engine

Source of Access to Use

Write PSL scripts that access events and objects

The PATROL Script Language (PSL)

BMC Software, Inc., Condential and Proprietary Information