Unisys: Clearpath Enterprise Servers

unisys
imagine it. done.
ClearPath Enterprise Servers

Operations Sentinel Event Server C/C++ Application Program Interface Programming Guide
Operations Sentinel Level 12.0
February 2011 7844 8107008
NO WARRANTIES OF ANY NATURE ARE EXTENDED BY THIS DOCUMENT. Any product or related information described herein is only furnished pursuant and subject to the terms and conditions of a duly executed agreement to purchase or lease equipment or to license software. The only warranties made by Unisys, if any, with respect to the products described in this document are set forth in such agreement. Unisys cannot accept any financial or other responsibility that may be the result of your use of the information in this document or software material, including direct, special, or consequential damages. You should be very careful to ensure that the use of this information and/or software material complies with the laws, rules, and regulations of the jurisdictions with respect to which it is used. The information contained herein is subject to change without notice. Revisions may be issued to advise of such changes and/or additions. Notice to U.S. Government End Users: This is commercial computer software or hardware documentation developed at private expense. Use, reproduction, or disclosure by the Government is subject to the terms of Unisys standard commercial license for the products, and where applicable, the restricted/limited rights provisions of the contract data rights clauses.
Unisys and ClearPath are registered trademarks of Unisys Corporation in the United States and other countries. All other brands and products referenced in this document are acknowledged to be the trademarks or registered trademarks of their respective holders.
Contents
Section 1. Introduction 1.1. 1.2. 1.3. 1.4. 1.5. 1.6. Section 2. Documentation Considerations ............................................... 1---1 Documentation Updates .......................................................... 1---1 Purpose .................................................................................... 1---1 Audience .................................................................................. 1---2 Notation Conventions .............................................................. 1---2 Terminology ............................................................................. 1---2
Quick Start 2.1. 2.2. What You Need to Get Started ................................................ 2---1 Integrating the API with the Windows Event Loop ................. 2---5
Section 3.
Concepts and Definitions 3.1. 3.2. Architecture ............................................................................. 3---1 How to Use Clients with Operations Sentinel ......................... 3---4
Section 4.
Library and Header Files 4.1. 4.2. 4.3. Files on the Server ................................................................... 4---1 API Files on Managed UNIX Systems ..................................... 4---2 API Files on Managed Windows Systems............................... 4---2
Section 5.
Client Uses 5.1. 5.2. 5.3. 5.4. 5.5. 5.6. 5.7. Sending Events ........................................................................ 5---1 Receiving Events ..................................................................... 5---2 Requesting Outstanding Events .............................................. 5---3 Submitting Commands ............................................................ 5---3 Event Loop Functions .............................................................. 5---4 Distributing Clients ................................................................... 5---5 Using Resilient Operations Sentinel Servers ........................... 5---5
Section 6.
Client Examples 6.1. 6.2. 6.3. 6.4. Alert Recipient ......................................................................... 6---1 Alert Source ............................................................................. 6---3 Logging .................................................................................... 6---5 Events for Operations Sentinel Console .................................. 6---7
7844 8107---008
iii
Contents
6.5. 6.6. 6.7. 6.8. Section 7.
Timers ...................................................................................... 6---8 Input Monitoring ...................................................................... 6---9 Command Submission .......................................................... 6---10 Monitoring Event State .......................................................... 6---13
Client Features 7.1. 7.2. 7.3. 7.4. 7.5. 7.6. 7.7. 7.8. 7.9. 7.10. 7.11. 7.12. 7.13. 7.14. 7.15. 7.16. 7.17. 7.18. 7.19. 7.20. SPD_AckAlarm......................................................................... 7---1 SPD_AddInput ......................................................................... 7---3 SPD_AddTimeOut.................................................................... 7---4 SPD_ClearAlarm ...................................................................... 7---5 SPD_Command ....................................................................... 7---8 SPD_DeleteObject ................................................................. 7---10 SPD_GetErrorMessage ......................................................... 7---12 SPD_HandleEvent.................................................................. 7---12 SPD_InitClient ........................................................................ 7---14 SPD_LogMessage ................................................................. 7---16 SPD_MainLoop ...................................................................... 7---17 SPD_MonitorEventState ........................................................ 7---18 SPD_ProcessEvents .............................................................. 7---19 SPD_RemoveInput ................................................................ 7---20 SPD_RemoveTimeOut .......................................................... 7---20 SPD_ReportValue .................................................................. 7---21 SPD_RequestEvents ............................................................. 7---23 SPD_SendAlarm .................................................................... 7---24 SPD_SendUserAlarm ............................................................. 7---27 SPD_Terminate ...................................................................... 7---30
Section 8.
Data Definitions 8.1. 8.2. Typedefs .................................................................................. 8---1 Callbacks ................................................................................ 8---12
Appendix A. Permuted Index Index ............................................................................................. 1
iv
7844 8107---008
Section 1 Introduction
1.1. Documentation Considerations
This revision incorporates C/C++ in the documents title to differentiate this document from the Event Server C# API Programming Guide. It also updates the Operations Sentinel product names. No other changes were made to the content of this document.
1.2. Documentation Updates

This document contains all the information that was available at the time of publication. Changes identified after release of this document are included in problem list entry (PLE) 18780216. To obtain a copy of the PLE, contact your Unisys representative or access the current PLE from the Unisys Product Support Web site: http://www.support.unisys.com/all/ple/18780216 Note: If you are not logged into the Product Support site, you will be asked to do so.
1.3. Purpose
The Event Server is an Operations Sentinel service that runs on each Operations Sentinel server, receives event reports, and distributes them to clients that have registered for this type of event. It provides a set of application programming interfaces (the Event Server API) for clients. This guide explains how to program and administer clients for the Operations Sentinel Event Server API. The Event Server API of Operations Sentinel is supported on U 6000, HP-UX, Sun Solaris, AIX, UnixWare, Linux, Windows Server 2008, Windows Vista, Windows Server 2003, Windows XP, Windows 2000, and Windows NT systems. Operations Sentinel provides a set of tools you can use to build client programs. These client programs (or clients) can access information from or provide information to Operations Sentinel servers. You use the Event Server API functions described in this document to build client programs.
7844 8107---008
1---1
Introduction
1.4. Audience
This guide is for system programmers who are responsible for programming and administering Operations Sentinel.
1.5. Notation Conventions

Portions of input syntax, directory names, or output messages that refer to variable information are shown in italics. For example SPD=installation-directory. The terms host and host system refer to the systems that you want to monitor and control. These systems are connected to the Operations Sentinel server over a network. In this guide, UNIX systems include systems running U 6000, HP, Sun, AIX, UnixWare, or Linux. Windows systems include systems running Windows Server 2008, Windows Vista, Windows Server 2003, Windows XP, Windows 2000, or Windows NT.
1.6. Terminology
See the Operations Sentinel Master Glossary (7847 4244) for terminology definitions.
1---2
7844 8107---008
Section 2 Quick Start

This section provides a detailed example of how to program a simple client that uses the Event Server API. You can incorporate this client into your implementation of Operations Sentinel and modify it to meet the needs of your site.
2.1. What You Need to Get Started

To get started, you need A client coded in C or C++ language, such as the example in this section. A make file, based on the sample make file in this section (UNIX systems only). The files in the Event Server API library. See Section 4 for the location of the Event Server API files.
In This Example
In this example, the client raises an alert, which is displayed in an Alerts window of Operations Sentinel Console.
7844 8107---008
2---1
Quick Start
How to Code the Example

The example uses a client that is coded in C language, as follows: main( int argc, char **argv ) { /* Initialize the API. Application name = "alarm sender" No application qualifier. */ SPD_InitClient("alarm sender", NULL); /* client processing... */ /* Send an alarm: System is UNIX system named host02 (in the configuration). Alarm identifier is "alarm01". No alarm qualifier. Alarm text is "Emergency...". No alarm help text (default help file is "alarm01"). External action is "plan9". Severity is critical. Application name and qualifier are defaults specified for SPD_InitClient. No time stamp. */ SPD_SendAlarm("host", "host02", "alarm01", NULL, "Emergency in computer center", NULL, "plan9", SPD_criticalCN, NULL, NULL, 0); /* no event loop required if events are only sent, but not received. */ }
2---2
7844 8107---008
Quick Start
Using a Make File

For a client that runs on a UNIX system, in addition to the coded client program, you must use a make file similar to the following to complete the programming of your client.
CAUTION
Use tabs instead of spaces before commands in a make file. A command is any executable line following a target/dependency specification. Using spaces results in program failures.
#************************************************************************ # * # This is the sample Makefile for API client programs. * # * #************************************************************************ ############################################################ ### MACRO DEFINITIONS ### ############################################################ SHELL = /bin/sh # API location SPD=API-installation-directory # C compiler CC = cc STDH = /usr/include # INCLUDES INCLUDE = -I$(SPD) -I$(STDH) # LIBRARIES UCBDIR = /usr/ucblib UCBLIB = -L $(UCBDIR) -lucb SPDLIB = -L $(SPD) -lspd SYSLIBS = -lsocket -lnsl -lc -lm # The -lucb library must be linked last STDLIB = $(SPDLIB) $(SYSLIBS) $(UCBLIB) # FLAGS # debugging on/off DBGFLG = -g -DDEBUG # common C flags CFLAGS = -c $(DBGFLG) $(INCLUDE)
7844 8107---008
2---3
Quick Start
# additional C flags CPPFLAGS = -P $(INCLUDE) -DDEBUG
############################################################ ### OBJECT FILE DEFINITIONS ### ############################################################ APISAMPLE = \ apisample.o
############################################################ ### TARGETS ### ############################################################ all: apisample
apisample: $(APISAMPLE) $(CC) $(DBGFLG) $(APISAMPLE) \ $(STDLIB) && mv a.out $@ apisample.o: \ apisample.c $(CC) $(CFLAGS) apisample.c
Customizing the Make File

Customize the make file to reflect the location of your Operations Sentinel files and directories. Change API-installation-directory to the name of the directory or folder in which the Event Server API library and header files are located. See Section 4.
Effect of the Client on Operations Sentinel

The client sends an alert through the Event Server API to the Operations Sentinel server. On Operations Sentinel workstations, the Operations Sentinel Console application then displays the alert in one of its Alerts windows. The Operations Sentinel workstation operator can view the contents of the Alerts window by clicking the highlighted alert icon, the exclamation point in the main window of Operations Sentinel Console. The text of the message reads, Emergency in computer center. The operator can then respond to the emergency in the computer center and clear the alert from the Alerts window.
2---4
7844 8107---008
Quick Start
if (!m_wndToolBar.CreateEx(this, TBSTYLE_FLAT, WS_CHILD | WS_VISIBLE | CBRS_TOP | CBRS_GRIPPER | CBRS_TOOLTIPS | CBRS_FLYBY | CBRS_SIZE_DYNAMIC) || !m_wndToolBar.LoadToolBar(IDR_MAINFRAME)) { TRACE0("Failed to create toolbar\n"); return -1; // fail to create } if (!m_wndStatusBar.Create(this) || !m_wndStatusBar.SetIndicators(indicators, sizeof(indicators)/sizeof(UINT))) { TRACE0("Failed to create status bar\n"); return -1; // fail to create } m_wndToolBar.EnableDocking(CBRS_ALIGN_ANY); EnableDocking(CBRS_ALIGN_ANY); DockControlBar(&m_wndToolBar); // // Initialize the API with application name = "MyApp" // application qualifier = "MyQual" SPD_InitClient("MyApp", "MyQual"); // // Create a timer to process events. Every second (arbitrary interval) // a WM_TIMER message will be received with an event id of ID_SPD_PROCESS // SetTimer( ID_SPD_PROCESS, 1000, NULL ); return 0; } ... // // WM_TIMER message handler // // The SetTimer() call made during initialization causes a WM_TIMER message with // ID_SPD_PROCESS as the event number to be issued every second (arbitrary // interval). // When the message is received, SPD_ProcessEvents is called. // void CMainFrame::OnTimer(UINT nIDEvent) { SPD_errorTP spdErr; if (nIDEvent == ID_SPD_PROCESS) { spdErr = SPD_ProcessEvents(); if (spdErr != SPD_normalCN)
2---6
7844 8107---008
Quick Start
{ // error processing AfxMessageBox("I forgot to call SPD_InitClient()!"); } } else CFrameWnd::OnTimer(nIDEvent); }
7844 8107---008
2---7
Quick Start
2---8
7844 8107---008
Section 3 Concepts and Definitions

This section provides concepts and definitions to help you understand the Operations Sentinel Event Server API and the development of clients.
3.1. Architecture
This subsection provides a graphical representation of the Event Server API and describes how clients communicate information to each other. Clients can both send information to and receive information from other clients. As senders, clients are "sources" of information; as receivers, clients are "users" of information. All information that is sent to and from clients passes through the Event Server. The Event Server API serves as the interface from a sender client to the Event Server, and from the Event Server to a targeted receiver client. Once received by the client, the information is used in ways that are specific to the client.
Diagram of Architecture
This two-page illustration shows the architecture of clients that use the Event Server API.
7844 8107---008
3---1
Quick Start
Data Flow Diagram of the Example

This illustration shows the architecture underlying this example. The diagram shows how the client sends the alert through the Event Server API. From the Event Server API, the alert is sent to the Operations Sentinel server. The Operations Sentinel Console application displays the alert to the operator on an Operations Sentinel workstation in one of its Alerts windows.
2.2. Integrating the API with the Windows Event Loop

Several examples throughout this book use the function SPD_MainLoop() to process events. If you are creating an application that contains a separate event loop, you must use SPD_ProcessEvents() instead to allow the two to coexist. The example below shows how to process the SPD event loop in a Windows MFC application. You must use this method as a replacement for the calls to SPD_MainLoop() in examples in 6.1 and 6.6. ... #include "spd.h" ... #define ID_SPD_PROCESS 5000 ... BEGIN_MESSAGE_MAP(CMainFrame, CFrameWnd) //{{AFX_MSG_MAP(CMainFrame) ON_WM_CREATE() ON_WM_TIMER() //}}AFX_MSG_MAP ON_UPDATE_COMMAND_UI_RANGE(AFX_ID_VIEW_MINIMUM, AFX_ID_VIEW_MAXIMUM, OnUpdateViewStyles) ON_COMMAND_RANGE(AFX_ID_VIEW_MINIMUM, AFX_ID_VIEW_MAXIMUM, OnViewStyle) END_MESSAGE_MAP() ... int CMainFrame::OnCreate(LPCREATESTRUCT lpCreateStruct) { if (CFrameWnd::OnCreate(lpCreateStruct) == -1) return -1;
7844 8107---008
2---5
Concepts and Definitions
3---2
7844 8107---008
7844 8107---008
3---3
3.2. How to Use Clients with Operations Sentinel

This subsection describes some general ideas for incorporating clients into your Operations Sentinel environment.
Using Alerts
Operations Sentinel Console displays alerts to the operator through its Alerts windows. The alerts can also be sent to a client for the attention of another user, or to archive them. The client that receives the alert event can use the information in any way.
Using Log Files

Operations Sentinel includes a logging capability that automatically logs information from the systems you are monitoring. In addition, you can use a client to send information to a log file. If you are running an application on a managed system, and you want to track data produced by that application, you can send it to that systems log. The client sends the information through the Event Server using the Event Server API, where it is written to the specified log file. Although a client can register to receive log events, the client only receives those log events that were sent by user-supplied API clients. It does not receive the standard log events recorded by Operations Sentinel logging, because these events are not communicated using event reports.
Sending Information to Operations Sentinel Console

You can use a client to send information to Operations Sentinel Console that changes an attribute value or deletes an instance of an object.
Sending Commands to Hosts

You can use a client to submit a command to a managed system that has an active console connection. Command Security (discussed in the Operations Sentinel Administration and Configuration Guide) lets the administrator allow or prevent crosssystem commands from an API client.
3---4
7844 8107---008
Section 4 Library and Header Files

This section describes the location of the Event Server API files on the Operations Sentinel server and on managed systems. The Event Server API file names are spd.h The header file for the Event Server API. libspd.a The Event Server API library, for UNIX only. libspd.lib Multithreaded DLL version of the Event Server API library, for Windows only. libsdd.lib Debug multithreaded DLL version of the Event Server API library, for Windows only. Note: Although libspd.lib and libsdd.lib were built to run with the multithread version of the runtime libraries, the API itself is not thread-safe.
4.1. Files on the Server

The files for the Event Server API are located in the following folders on the Operations Sentinel server: sp-installation-folder\API\Windows\api\spd------Windows version sp-installation-folder\API\U6000\api\spd------U 6000 version sp-installation-folder\API\UNIX7WARE\api\spd------UnixWare 7 version sp-installation-folder\API\SUN\api\spd------Sun version sp-installation-folder\API\HP\api\spd------HP version sp-installation-folder\API\AIX\api\spd------IBM version for AIX operating system
7844 8107---008
4---1
Library and Header Files
sp-installation-folder\API\LINUX\api\spd1------LINUX Kernel 2.4.19 version or earlier, and United LINUX sp-installation-folder\API\LINUX\api\spd2------Red Hat Kernel 2.4.20 version only
where sp-installation-folder is the folder in which the server version of Operations Sentinel was installed. The default name of this folder for Operations Sentinel 11.x is C:\Program Files\Unisys\Operations Sentinel\x.y.z.
4.2. API Files on Managed UNIX Systems

The Event Server API files can be installed remotely from the Operations Sentinel server to a managed UNIX system. See the Operations Sentinel Administration and Configuration Guide for details on using the Operations Sentinel Configuration application to install the Event Server API library. The Operations Sentinel Configuration application installs the Event Server API files to the following default directory: /opt/SPO-agent/type/api/spd where type is U6000, UNIXWARE, SUN, HP, or AIX. For LINUX systems, the default directory for the Event Server API files is /opt/SPO-agent/LINUX/api/spd1 /opt/SPO-agent/LINUX/api/spd2 (for LINUX kernel 2.4.19 or earlier and United LINUX) (for Red Hat 9 kernel 2.4.20)
4.3. API Files on Managed Windows Systems

The Event Server API files are installed with the Operations Sentinel Windows agent on each managed Windows system. See the Operations Sentinel Administration and Configuration Guide for details on installing the Operations Sentinel Windows agent. The Operations Sentinel Windows agent installation places the Event Server API files into the following folder by default: agent-installation-folder\API\Windows\api\spd where agent-installation-folder is the folder in which the Operations Sentinel Windows agent is installed.
4---2
7844 8107---008
Section 5 Client Uses

This section describes the following uses of Event Server API clients: Sending an event Receiving events Requesting outstanding events Submitting a command Creating an event loop Distributing client programs Using resilient Operations Sentinel servers
5.1. Sending Events

You can design a client to send events to the Operations Sentinel Event Server for distribution to other clients, notably Operations Sentinel Console.
Sending Events to Operations Sentinel Console

Operations Sentinel Console displays alerts in an Alerts window, from which the operator can control their disposition. Alerts are associated with systems and partitions that are displayed as icons in clusters in Operations Sentinel Console. When an alert is displayed in an Alerts window, the color, shape, and/or size of the associated icon changes, indicating to the operator that the system requires attention. Operations Sentinel Console provides the ability to track attribute changes in monitored objects, where an object may be a host or console, or a component of a host, such as a disk drive or a process.
7844 8107---008
5---1
Client Uses
Events You Can Send

You can send the following events with the indicated Event Server API functions:
To Send This Event:
Use This Function:
SPD_alarmEventCN
Any of the following functions:

SPD_attributeChangeEventCN SPD_deleteObjectEventCN SPD_logEventCN
SPD_SendAlarm (see 7.18) SPD_SendUserAlarm (see 7.19) SPD_ClearAlarm (see 7.4) SPD_AckAlarm (see 7.1)
SPD_ReportValue (see 7.16) SPD_DeleteObject (see 7.6) SPD_LogMessage (see 7.10)
5.2. Receiving Events

A client can register a callback function that is invoked when the Event Server receives a new event. The client does this with the function SPD_HandleEvent (see 7.8). Since these events are reported asynchronously, the client must be event-driven. For clients running on UNIX systems, the function SPD_MainLoop (see 7.11) is provided for this purpose. For clients running on Windows systems, use the technique illustrated in 2.2.
Registering to Receive Events

The client program must register a callback routine for each type of event you want it to receive. Clients can register to receive the following types of events: Alert events Attribute change events Delete object events Log events
Typically, a client uses the SPD_HandleEvent function during its initialization phase to register a callback routine for each event it is to receive. Once the initialization has completed, and the callbacks have been registered, a UNIX client should call the function SPD_MainLoop. In client programs on UNIX systems, the function SPD_MainLoop suspends the execution of the client program while waiting for an event to occur. When the Event Server receives an event for which the client has registered, the Event Server invokes the callback routine that was specified by SPD_HandleEvent.
5---2
7844 8107---008
Client Uses
If your client program has its own event loop, as Windows client programs typically do, the program must periodically interrupt its event loop and call function SPD_ProcessEvents to process SPD events. See 2.2 for illustration.
Data Structure of SPD_eventTP

The callback routine receives a description of the event in the data structure SPD_eventTP (see 8.1). This data structure has an area for data that is common to all events (for example, object class and object name) and a separate area for event-specific data. The latter area is a C union of data structures in which each data structure represents data that is specific to a single type of event. Since some events, such as SPD_attributeChangeEventCN, have variable amounts of data, a variable data area is provided in the event-specific area.
5.3. Requesting Outstanding Events

When a client is initialized, it can request to be informed of all outstanding alert events. It does this using the function SPD_RequestEvents (see 7.17). When a client requests all events with SPD_RequestEvents, these events are reported as a series of individual events. Thus, the receipt of events requested in this manner requires no special processing on the part of the client, other than what is required for the normal receipt of an event.
5.4. Submitting Commands

A client can submit commands and keyins to host systems that are being monitored by the Operations Sentinel server. The host must be active and connected to the Operations Sentinel server. An OS 2200 system console must have passed the state of being booted so that the systems operation session is available and running. Sending commands to a Windows system or a Service Processor is not supported.
Logon Requirements for a Managed UNIX System

If a managed system requires the user to log in, as with a UNIX system, then a user must be logged in to the system before a client can submit a command. Operations Sentinel does not check that a user has logged in, so a client can submit a command without detection of an error. Alternatively, you can design your client to send the login command, or to respond to prompts at boot time.
7844 8107---008
5---3
Client Uses
Identifying the Host

A client must identify the host system that is to receive the command by specifying the same host name that was specified when the host was configured using the Operations Sentinel Configuration application. If an unrecognizable host name is specified, the command is discarded and an error is returned on the command acknowledgment.
Submitting a Command Using SPD_Command

A client uses the function SPD_Command to send a command to any managed system except a Windows system (see 6.7 and 7.5). At the time the command is submitted, there is no way to know if the host or console is being actively monitored by the Operations Sentinel server, or if the host or console is active. The command is received by the Event Server, which attempts to forward it to the specified host or console. Once the attempt is made, a status is returned to the requesting client. The command acknowledgment callback specified with SPD_Command is then invoked with this status.
Using Passback Data

The client should use the passback data of the function SPD_Command to correlate a command with its acknowledgment. A unique value can be associated with each individual command in this way.
5.5. Event Loop Functions

Clients that register to receive asynchronous notification of events are inherently eventdriven. Event-driven programs are typically built using an event loop, which is executed after program initialization. The event loop is never exited, but invokes program callbacks as events occur. The Event Server API provides its own event loop through the function SPD_MainLoop (see 7.11). If your client program has its own event loop, as Windows client programs typically do, the program must periodically interrupt its event loop and call function SPD_ProcessEvents to process SPD events. See 2.2 for illustration.
Events and Event Callbacks

An event can be any of the following: Receipt of an event from the Event Server An expired timer An input/output event on a specific file descriptor
Clients specify event callbacks by calling SPD_HandleEvent (see 7.8).
5---4
7844 8107---008
Client Uses
Timers
Clients specify timers with the functions SPD_AddTimeOut (see 7.3) and SPD_RemoveTimeOut (see 7.15). There is no limit to the number of timers that can be active at any one time.
Input/Output Handlers
Clients specify input/output handlers with the functions SPD_AddInput (see 7.2) and SPD_RemoveInput (see 7.14). There is no limit to the number of I/O handlers that can be active at any one time.
5.6. Distributing Clients

Client programs must be located on the managed systems. To specify the location of the Operations Sentinel server in a distributed environment, set the environment variable SPO_EVENT before starting the client program. For the value of this environment variable, use the name or IP address of the server (as specified in the /etc/hosts file, the Domain Name Server, or the Windows Internet Naming Service). The default value for the location of the server is localhost.
5.7. Using Resilient Operations Sentinel Servers

Two Operations Sentinel servers can be configured for use in a resilient monitoring environment. Each client program must establish a connection to the secondary server to use this feature. All events generated by the client are normally sent to the primary server. If the client has registered for event callbacks, only events from the primary server are reported to the client in a resilient server environment. If a client loses connection with the primary server, all events generated by the client are sent to the secondary server. In addition, the client callbacks begin receiving events from the secondary server. When the primary server is once again available, all events are sent to the primary server and the client callbacks are again received only from the primary Operations Sentinel server.
Specifying a Secondary Server

Set the environment variable SPO_EVENT_SECONDARY to specify the location of the secondary server before a client is started. As the value of this variable, use the name or IP address of the secondary server (as specified in the /etc/hosts file, the Domain Name Server, or the Windows Internet Naming Service). If this environment variable is not specified, the client will not connect to a secondary server. See the Operations Sentinel Administration and Configuration Guide for details on using the Operations Sentinel Configuration application to specify a secondary server.
7844 8107---008
5---5
Client Uses
After the Operations Sentinel administrator has specified the secondary server, you can display its name and network address using the Configuration application. Use this information to set the environment variable SPO_EVENT_SECONDARY to ensure consistency with the agents supplied by Unisys that support a secondary server. Click Applications in the main menu bar, and then click Specify Secondary SPO Server. The dialog box that appears includes the server name and its network address. Click Cancel to close this dialog box. Alternatively, you see the name and network address of the secondary server in the file sp-data-folder\data\SPO-secondary where sp-data-folder is the data folder specified during installation of the server version of Operations Sentinel. If the administrator uses the default data folder, the location of this file is C:\Documents and Settings\All Users\Application Data\Unisys\Operations Sentinel\x.y.z\data (level 11.x) where x.y.z is the release level of Operations Sentinel. Note: You must use the Operations Sentinel Configuration application to create or alter the SPO-secondary file.
File Format for SPO-Secondary

The format of the file is: secondary-name secondary-addr reserved secondary-name is the name of the secondary Operations Sentinel server. secondary-addr is the network address of the secondary Operations Sentinel server. reserved is any text or special characters. This field is reserved for future use. Each field in this file appears on a line by itself.
Event Report for Switch of Servers

When a switch between servers occurs, the Event Server API sends an alert event report on behalf of the client, reporting that the Event Server switched to the primary or secondary server, whichever is the case. The API (linked with the client application) sends this event report to any Operations Sentinel server that is connected.
5---6
7844 8107---008
Client Uses
The following fields are included in this event report:

TYPE = AL SEV = major APPL=spues (Single Point Universal Event Server) APPLQUAL=application-name (as specified for SPD_InitClient) ALARMID=_SwitchToPrimary (or _SwitchToSecondary, depending on which case applies)
This alert must be manually cleared. Like any alert event report, an alert raised when servers are switched is logged by Operations Sentinel. This alert is recorded in the logs named SPO and SP-SPALS, but is not recorded in the log of each monitored system. If several client applications report the switch of servers, only one alert appears in the Alerts windows of Operations Sentinel Console, because subsequent alerts are treated as duplicates. Any subsequent alerts (before the first alert has been cleared) are recorded as discarded raises (type DR) in the logs. If an operator clears this alert before all clients have raised it, the alert reappears when another client sends the event report raising it. You can examine the SPO and SP-SPALS logs using the Operations Sentinel Log Viewer. See the Operations Sentinel Console User Guide.
7844 8107---008
5---7
Client Uses
5---8
7844 8107---008
Section 6 Client Examples

This section contains eight examples of Event Server API clients. You can use these examples as is for your own site, or you can modify them to suit the specific needs of your site. Except as noted, these examples can run on both UNIX and Windows systems.
6.1. Alert Recipient

Purpose of Alert Recipient Client
This example illustrates a UNIX client that receives notification of alert events from the Event Server. This requires an event loop because events are received asynchronously. A single client can send as well as receive events. See 6.2 for other details that you can incorporate into this program. Note: You cannot use the API function SPD_MainLoop in client programs developed for Windows systems. For clients on Windows systems, use SPD_ProcessEvents, as illustrated in 2.2.
Code
void eventCallback ( SPD_eventTypeTP, SPD_eventTP *, SPD_passbackTP ); main( int argc, char **argv ) { /* Initialize the API. Application name = "alarm recipient" No application qualifier. */ SPD_InitClient("alarm recipient", NULL); /* Register a callback to handle alarm events.
7844 8107---008
6---1
Client Examples
No passback data is specified. */ SPD_HandleEvent(SPD_alarmEventCN, eventCallback, NULL); /* Enter the SPD main loop to wait for the receipt of alarm events. */ SPD_MainLoop(); } /* Callback which handles alarm events */ void eventCallback( SPD_eventTypeTP type, /* event type */ SPD_eventTP *event, /* event info */ SPD_passbackTP passback ) { char *severity; int i; /* Handle alarm events */ if (type == SPD_alarmEventCN) { /* Display data that is common to all events */ printf("class=%s name=%s appl=%s applqual=%s\n", event->objectClass, event->objectName, event->applicationName, event->applicationQualifier); /* Convert severity type to string */ switch (event->eventData.alarm.severity) { case SPD_criticalCN: severity = "critical"; break; case SPD_majorCN: severity = "major"; break; /* etc. */ } /* Display alarm event information */ printf("id=%s qual=%s severity=%s text=%s\n", event->eventData.alarm.alarmIdentifier, event->eventData.alarm.alarmQualifier, severity, event->eventData.alarm.alarmText);
6---2
7844 8107---008
Client Examples
/* Display user defined attributes and their values */ for(i=0;<event-> variableCount; i++){ printf("Attribute name:%s\n",event->variableData[i].attribute); printf("Attribute value:%s\n\n",event->variableData[i].value); } else { /* Process other event types (or error if none registered) */ } }
Data Flow Diagram

This illustration shows the flow of information for the alert recipient client.
6.2. Alert Source

Purpose of Alert Source Client
This example shows how a client can raise and clear an alert without requesting notification of alert events. No event loop is required since asynchronous event notification is not needed to accomplish this.
Code
main( int argc, char **argv ) { /* Initialize the API. Application name = "alarm source" No application qualifier. */ SPD_InitClient("alarm source", NULL); /* client processing... */ /* Send an alarm:
7844 8107---008
6---3
Client Examples
System is UNIX system named host02 (in the configuration). Alarm identifier is "alarm01". No alarm qualifier. Alarm text is "Emergency...". No alarm help text (default help file is "alarm01"). External action is "plan9". Severity is critical. Application name and qualifier are the defaults. No time stamp. */ SPD_SendAlarm("host", "host02", "alarm01", NULL, "Emergency in computer center", NULL, "plan9", SPD_criticalCN, NULL, NULL, 0); /* more client processing... */ /* Clear the previously raised alarm: System is UNIX system named host02 (in the configuration). Alarm identifier is "alarm01". No alarm qualifier. No clear text No external action list Application name and qualifier are the defaults. No time stamp. */ SPD_ClearAlarm("host", "host02", "alarm01", NULL, NULL, NULL, NULL, NULL, 0); /* /* */ } no event loop required if events are only sent, but not received. still more client processing... */
6---4
7844 8107---008
Client Examples
Data Flow Diagram

This illustration shows the flow of information for the alert source client.
6.3. Logging
Purpose of Logging Client
The logging example shows how a client can log a message by sending a log event to the Event Server. No event loop is required since asynchronous event notification is not needed to accomplish this.
Code
main( int argc, char **argv ) { /* Initialize the API. Application name = "log message" No application qualifier. */ SPD_InitClient("log message", NULL); /* client processing... */ /* Log a message: The message "An important..." is written to "logfile" as a normal ("NO") message. Application name and qualifier are the defaults. No time stamp. */ SPD_LogMessage("logfile", "NO", "An important event has occurred", NULL, NULL, 0); /* more client processing... */ /* no event loop required if events are only sent,
7844 8107---008
6---5
Client Examples
but not received. */ }
Data Flow Diagram

This illustration shows the flow of information for the logging client.
6---6
7844 8107---008
Client Examples
6.4. Events for Operations Sentinel Console

Purpose of Status Feeder Client
This example shows how a client can send attribute changes for Operations Sentinel Console to the Event Server. This client does not request notification of events.
Code
main( int argc, char **argv ) { char *attr[] = {"MYATTR"}; char *value[] = {"myvalue"}; /* Initialize the API. Application name = "Status feeder" No application qualifier. */ SPD_InitClient("Status feeder", NULL); /* client processing... */ /* Report a change in value of an attribute of an object being monitored by the Status application: The class is "disk". The instance is "disk01". The host on which the instance resides is "HOST1". The application name and qualifier are set to NULL. This causes the default values to be used (i.e., "Status feeder" for the name and NULL for the qualifier). No time stamp. One attribute is updated. Its name (from the attr array) is "MYATTR" and its new value (from the value array) is "myvalue". */ SPD_ReportValue("disk", "disk01", "HOST1", NULL, NULL, 0, 1, attr, value); /* more client processing... */ /* no event loop required if events are only sent, but not received. */ }
7844 8107---008
6---7
Client Examples
Data Flow Diagram

This illustration shows the flow of information for the Status Feeder client.
6.5. Timers
Purpose of Timer Client
This example illustrates a client that creates a timer. This requires an event loop because timer expiration is an asynchronous event. Note: You cannot use the API function SPD_MainLoop in client programs developed for Windows systems. For clients on Windows systems, use SPD_ProcessEvents, as illustrated in 2.2.
Code
void timerCallback ( SPD_timeoutTP, SPD_passbackTP ); main( int argc, char **argv ) { /* Initialize the API. Application name = "timer example" No application qualifier. */ SPD_InitClient("timer example", NULL); /* Create the timer. The interval is 10 seconds. No passback data is specified. */ SPD_AddTimeOut(10000, timerCallback, NULL);
6---8
7844 8107---008
Client Examples
/* Enter the SPD main loop to wait for the expiration of the timer. */ SPD_MainLoop(); } /* Callback which handles timer expiration */ void timerCallback( SPD_timeoutTP id, /* timer handle */ SPD_passbackTP passback ) { /* Client processing... */ /* The timer is gone. It must be recreated if we want it to go off again in the future. */ SPD_AddTimeOut(10000, timerCallback, NULL); }
6.6. Input Monitoring

Purpose of Input Monitoring Client
This example illustrates a UNIX client that monitors a file descriptor for input events. This requires an event loop because input events occur asynchronously. Note: This example does not apply for clients on Windows systems, where SPD_AddInput is not supported.
Code
void input Callback ( SPD_inputTP, SPD_passbackTP ); /* global file descriptor variable */ int fd main( int argc, char **argv ) { /* Initialize the API. Application name = "input monitor example" No application qualifier. */ SPD_InitClient("input monitor example", NULL);
7844 8107---008
6---9
Client Examples
/* Create the I/O handler. The file descriptor in the global variable "fd". We are only interested in input events. No passback data is specified. */ SPD_AddInput(fd, SPD_readCN, inputCallback, NULL); /* Enter the SPD main loop to wait for the receipt of data. */ SPD_MainLoop(); } /* Callback which handles input events */ void inputCallback( SPD_inputTP id, /* I/O handler handle */ SPD_passbackTP passback ) { /* Client processing... */ /* The I/O handler remains active until it is removed. */ }
6.7. Command Submission

Purpose of Command Submission Client
This example illustrates a client that submits a command to a host system in response to an attribute change event. Note: You cannot use the API function SPD_MainLoop in client programs developed for Windows systems. For clients on Windows systems, use SPD_ProcessEvents, as illustrated in 2.2. However, the destination of the command submitted by SPD_Command cannot be a Windows host.
Code
void commandCallback ( char *, char *, char *, void *, SPD_commandStatusTP, SPD_passbackTP ); void eventCallbackTP ( SPD_eventTypeTP, SPD_eventTP *,
6---10
7844 8107---008
Client Examples
SPD_passbackTP ); main( int argc, char **argv ) { /* Initialize the API. Application name = "command submission example" No application qualifier. */ SPD_InitClient("command submission example", NULL); /* Register a callback to handle attribute change events. No passback data is specified. */ SPD_HandleEvent(SPD_attributeChangeEventCN, eventCallback, NULL); /* Enter the SPD main loop to wait for the receipt of data. */ SPD_MainLoop(); } /* Callback which handles attribute change events */ void eventCallback( SPD_eventTypeTP type, /* event type */ SPD_eventTP *event, /* event info */ SPD_passbackTP passback ) { char *severity; /* Handle attribute change events */ if (type == SPD_attributeChangeEventCN) { /* Determine if attribute change means a command should be sent /* Send a "who" command to the host that reported the attribute change. Register callback for command ack */ SPD_Command("host", event->host, "who", SPD_reservedValueCN, commandCallback, NULL, NULL, NULL, 0); } else { /* Process other event types (or error if none registered) */ } */
7844 8107---008
6---11
Client Examples
/* Callback for command acknowledgment */ void commandCallback( char *class, /* class of the destination host */ char *host, /* destination of the command */ char *command, /* the command */ void *res, /* reserved for future use */ SPD_commandStatusTP status, /* command submission status */ SPD_passbackTP passback /* passback data */ ) { switch (status) { case SPD_commandSuccessCN: /* command was submitted */ break; case SPD_unknownHostCN: case SPD_unreachableHostCN: /* something went wrong - command did not make it */ break; } }
Data Flow Diagram

This illustration shows the flow of information for the command submission client.
Other Client
Sends AC event
(source of attribute change events) 2 Receives AC event
Command Submission Client
Event Server
Host receives command
Sends command
Sends acknowledgment of command
6---12
7844 8107---008
7844-8107-6-15 09/17/02
Client Examples
6.8. Monitoring Event State

Purpose of Monitoring Event State Client
This example illustrates a client that monitors the state of the Event Server for specific events. The Event Server has various internal components that handle the routing of events. A client program can register a callback to track the availability of these internal components based upon the event type.
Code
void eventStateCallback ( SPD_eventTypeTP, SPD_eventStateTP, SPD_passbackTP ); main ( int argc, char **argv ) { /* Initialize the API. Application name = "event state example". No application qualifier. */ SPD_InitClient("event state example", NULL); /* Monitor the state of alarm events */ SPD_MonitorEventState(SPD_alarmEventCN, eventStateCallback, NULL); /* Monitor the state of log events */ SPD_MonitorEventState(SPD_logEventCN, eventStateCallback, NULL); } /* Callback which handles event state changes */ void eventStateCallback( SPD_eventTypeTP event, /* Type of event */ SPD_eventStateTP state, /* New state of event */ SPD_passbackTP passback /* Passback data */ ) { switch (event) { case SPD_alarmEventCN: switch (state) {
7844 8107---008
6---13
Client Examples
case SPD_eventUpCN: /* Alarm events are up, i.e., they may be sent and received. */ break; case SPD_eventDownCN: /* Alarm events are down, i.e., it is not possible to send or receive them. */ break; } case SPD_logEventCN: switch (state) { case SPD_eventUpCN: /* Log events are up, i.e., it is possible to log a message with Operations Sentinel (SPO) logging. */ break; case SPD_eventDownCN: /* Log events are down, i.e., it is not possible to log a message with Operations Sentinel (SPO) logging. */ break; } } }
6---14
7844 8107---008
Section 7 Client Features

This section contains detailed information for each Event Server API function. This information, complemented by the data definitions in Section 8, provides you with reference information for creating Event Server API client programs.
7.1. SPD_AckAlarm
Purpose
Format and send an acknowledge alert event to the Event Server. Acknowledging an alert causes any pending external actions for the alert to be terminated, and initiates any external actions associated with alert acknowledgement.
Syntax
#include "spd.h" SPD_errorTP SPD_AckAlarm( char *objectClass, char *objectName, char *alarmIdentifier, char *alarmQualifier, char *acknowledgeText, char *externalActionList, char *application, char *applicationQualifier, time_t timeValue );
Description
objectClass identifies the object that is the source of the alert (for example, a system or application). objectClass must match the objectClass specified when the alert was raised (see 7.18 and 7.19). objectName identifies the instance of the object class that is the source of the alert (for example, a system or application name). objectName must match the objectName specified when the alert was raised.
7844 8107---008
7---1
Client Features
alarmIdentifier identifies the type of alert being acknowledged. alarmIdentifier must match the alarmIdentifier specified when the alert was raised. alarmQualifier further qualifies the type of alert when multiple instances of the alert are raised and must be kept distinct from one another. alarmQualifier must match the alarmQualifier specified when the alert was raised. This parameter is optional. Specify NULL if the alert is not further qualified. acknowledgeText is an optional explanation of why the alert is being acknowledged. Specify NULL if no text is supplied. externalActionList is the identifier of the external action list that is associated with acknowledging this alert. External action lists are defined in alert policies. If no external action list is associated with acknowledging this alert, or if the external action list is the same as alarmIdentifier, specify NULL. application identifies the application that raised the alert. The value must match the application name that was specified when the alert was raised. Specify NULL if the application is the same as the application that was specified on the call to SPD_InitClient. applicationQualifier further qualifies the application in the case where more than one instance of the application may be present. Specify NULL if the application qualifier is the same as the application qualifier specified on the call to SPD_InitClient. timeValue is the local time to be associated with acknowledgment of the alert. Specify the result of the C time function, or 0 if you want no local time to be associated with the acknowledgment of the alert.
Return Value
The return value indicates whether an error occurred, as follows:
Return
Indication
SPD_normalCN SPD_notInitializedCN SPD_badClassCN SPD_badNameCN SPD_badAlarmIdCN SPD_commFailureCN
No error SPD_InitClient not called previously Bad objectClass parameter Bad objectName parameter Bad alarmIdentifier parameter Communications problem
7---2
7844 8107---008
Client Features
See Also
See also the following functions: SPD_ClearAlarm (see 7.4) SPD_HandleEvent (see 7.8) SPD_InitClient (see 7.9) SPD_SendAlarm (see 7.18) SPD_SendUserAlarm (see 7.19)
7.2. SPD_AddInput
Purpose
Allow a UNIX client to register a file descriptor, socket, or port as an input source. A callback is registered to be invoked when an event occurs on that specified file descriptor. Note: This function is not supported in the Windows implementation of the Event Server API.
Syntax
#include "spd.h" SPD_inputTP SPD_AddInput( int fd, SPD_inputTypeTP type, SPD_inputCallbackTP callback, SPD_passbackTP passback );
Description
fd is the file descriptor to be registered as an input source. type is the type of event for which the callback is to be invoked. This type definition is described in 8.1. callback is the callback function that is invoked when an I/O event occurs on a file descriptor. This callback function is described in 8.2. passback is a value passed to the callback function.
7844 8107---008
7---3
Client Features
Return Value
This function returns an identifier for the input source, which is supplied when the callback is invoked and which you may use to remove the input source in calls to SPD_RemoveInput. This function returns NULL if no callback could be registered.
See Also
See also the following client functions: SPD_MainLoop (see 7.11) SPD_ProcessEvents (see 7.13) SPD_RemoveInput (see 7.14)
Use of this function is illustrated in 6.6.
7.3. SPD_AddTimeOut
Purpose
Register a callback that is invoked after a specified period of time has elapsed.
Syntax
#include "spd.h" SPD_timeoutTP SPD_AddTimeOut( int interval, SPD_timeoutCallbackTP callback, SPD_passbackTP passback );
Description
interval is the time in milliseconds that must elapse before the callback is invoked. callback is the callback function that is invoked after the timeout period has elapsed. The callback function is described in 8.2. passback is a value passed to the callback function.
7---4
7844 8107---008
Client Features
Return Value
This function returns an identifier for the timer, which is supplied as a parameter to the callback when it is invoked, and which you may use to remove the timer in a call to SPD_RemoveTimeOut. This function returns NULL if it could not register a callback.
See Also
See also the following client functions: SPD_MainLoop (see 7.11) SPD_ProcessEvents (see 7.13) SPD_RemoveTimeOut (see 7.15)
7.4. SPD_ClearAlarm
Purpose
Format and send an event to the Event Server that clears an alert. Clearing an alert causes any pending external actions to be terminated, initiates any external actions associated with clearing the alert, and removes the alert from the Event Server.
Syntax
#include "spd.h" SPD_errorTP SPD_ClearAlarm( char *objectClass, char *objectName, char *alarmIdentifier, char *alarmQualifier, char *clearText, char *externalActionList, char *application, char *applicationQualifier, time_t timeValue );
7844 8107---008
7---5
Client Features
Description
objectClass identifies the type of object that is the source of the alert (for example, a system or application). objectClass must match the objectClass specified when the alert was raised (see 7.18 and 7.19). objectName identifies the instance of the object class that is the source of the alert (for example, a system or application name). objectName must match the objectName specified when the alert was raised. alarmIdentifier identifies the type of alert being cleared. alarmIdentifier must match the alarmIdentifier specified when the alert was raised. alarmQualifier further qualifies the type of alert when multiple instances of the alert are raised and must be kept distinct from one another. alarmQualifier must match the alarmQualifier specified when the alert was raised. This parameter is optional. Specify NULL if the alert is not further qualified. clearText is an optional string that explains why the alert is being cleared. Specify NULL to supply no text. externalActionList is the identifier of the external action list that is associated with clearing this alert. External action lists are defined in alert policies. If no external action list is associated with clearing this alert, or if the external action list is the same as alarmIdentifier, specify NULL. application identifies the application that raised the alert. application must match the application specified when the alert was raised. Specify NULL if the application is the same as the application that you specified on the call to SPD_InitClient. applicationQualifier further qualifies the application in the case where more than one instance of the application may be present. Specify NULL if the application qualifier is the same as the application qualifier that you specified on the call to SPD_InitClient. timeValue is the local time to be associated with clearing the alert. Specify the result of the C time function, or 0 if you want no local time to be associated with clearing the alert.
7---6
7844 8107---008
Client Features
Return Value
Return
Indication
SPD_normalCN SPD_notInitializedCN SPD_badClassCN SPD_badNameCN SPD_badAlarmIdCN SPD_commFailureCN
No error SPD_InitClient not called previously Bad objectClass parameter Bad objectName parameter Bad alarmIdentifier parameter Communications problem
See Also
See also the following client functions: SPD_AckAlarm (see 7.1) SPD_HandleEvent (see 7.8) SPD_InitClient (see 7.9) SPD_SendAlarm (see 7.18) SPD_SendUserAlarm (see 7.19)
7844 8107---008
7---7
Client Features
7.5. SPD_Command
Purpose
Send a command to the Event Server, which will forward the command to the host system identified by objectClass and objectName. The destination of the command submitted by SPD_Command cannot be a Windows host.
Syntax
#include "spd.h" SPD_errorTP SPD_Command( char *objectClass, char *objectName, char *command, void *reservedValue, SPD_commandCallbackTP callback, SPD_passbackTP passback, char *application, char *applicationQualifier, time_t timeValue );
Description
objectClass is the class of the host system that is to receive the command. You can specify "host" if you do not need to further qualify the type of host system. objectName is the name of the host system that is to receive the command. command is the command being submitted to the host and must be in a format that the host expects. reservedValue is provided for future use. Specify SPD_reservedValueCN for this parameter. callback is the callback function that is invoked to return a status from the host system regarding the submission of the command. This callback function is described in 8.2. Specify NULL if you do not want a callback function to be invoked.
7---8
7844 8107---008
Client Features
passback is a value passed to the callback function. You can use it to correlate the command submission with the callback function. Specify NULL if you specify NULL for callback, or if there is no value. application identifies the application that is submitting the command. Specify NULL if the application is the same as the application that you specified on the call to SPD_InitClient. applicationQualifier further qualifies the application in the case where more than one instance of the application may be present. Specify NULL if the application qualifier is the same as the application qualifier that you specified on the call to SPD_InitClient. timeValue is the local time to be associated with the command. Specify the result of the C time function or 0 if no local time is to be associated with the command. The host is actively managed if it has an active console connection. This eliminates Windows hosts, systems monitored using spo_ping, and UNIX systems that do not have a console to which an Operations Sentinel user is logged in. In addition, the configured Command Security for the host must allow an API client to submit commands to the host. If any active Operations Sentinel configuration has a value other than Unlimited Access for the host, the command is rejected. If more than one path exists to a host, the command is sent along only one of these paths. The path is selected on a first-connected, first-selected basis: The path that is set up first by Operations Sentinel is the one selected. Multiple paths occur for UNIX hosts when more than one connection exists to the host. Multiple paths occur for OS 2200 hosts when more than one console is connected to the host, and each console is actively connected with the Operations Sentinel server. For a UNIX system, the command has no effect unless the systems console is accepting input (this normally requires that the console be logged in). Operations Sentinel cannot determine whether the console is accepting input, so the command callback is invoked with a successful status, even though an error occurs. If the console is not logged in, the UNIX system interprets the command as a response to the login prompt. For more information about login requirements, see 5.4.
7844 8107---008
7---9
Client Features
Return Value
Return
Indication
SPD_normalCN SPD_notInitializedCN SPD_badClassCN SPD_badHostCN SPD_badCommandCN SPD_badReservedValueCN SPD_commFailureCN
No error SPD_InitClient not called previously Bad objectClass parameter Bad objectName parameter Bad command parameter Value other than SPD_reservedValueCN specified for reservedValue Communications problem
Note: The return status does not tell the client program if the command was actually sent to the specified host or console. The callback function informs the client of this information.
See Also
7.6. SPD_DeleteObject
Purpose
Format and send a delete object event to the Event Server.
Syntax
#include "spd.h" SPD_errorTP SPD_DeleteObject( char *objectClass, char *objectName, char *hostName, char *application, char *applicationQualifier, time_t timeValue );
7---10
7844 8107---008
Client Features
Description
objectClass identifies the class of the object being deleted (for example, a disk drive or application). objectName identifies the instance of the object class (for example, a disk drive name or application name). hostName identifies the name of the host on which the object instance resides. application identifies the application that is deleting the object. Specify NULL if the application is the same as the application that you specified on the call to SPD_InitClient. applicationQualifier further qualifies the application in the case where more than one instance of the application may be present. Specify NULL if the application qualifier is the same as the application qualifier that you specified on the call to SPD_InitClient. timeValue is the local time to be associated with deletion of the object. Specify the result of the C time system function, or 0 if no local time is to be associated with deletion of the object.
Return Value
Return
Indication
SPD_normalCN SPD_notInitializedCN SPD_badClassCN SPD_badHostCN SPD_badNameCN SPD_commFailureCN
No error SPD_InitClient not called previously Bad objectClass parameter Bad hostName parameter Bad objectName parameter Communications problem
7844 8107---008
7---11
Client Features
7.7. SPD_GetErrorMessage
Purpose
Return a text description of an error status.
Syntax
#include "spd.h" char *SPD_GetErrorMessage( SPD_errorTP error );
Description
error identifies the type of error. See 8.1 for the list of possible errors.
Return Value
This function returns a pointer to the error message text if the input argument is a valid error type. It returns a pointer to a default error message if the error type is invalid. The pointer that is returned points to a static buffer.
7.8. SPD_HandleEvent
Purpose
Register a callback function for events. The callback function is called whenever an event of the specified type occurs.
Syntax
#include "spd.h" SPD_errorTP SPD_HandleEvent( SPD_eventTypeTP type, SPD_eventCallbackTP callback, SPD_passbackTP passback );
7---12
7844 8107---008
Client Features
Description
type is the type of event that causes the callback function to be called. This value will be supplied as an argument to the callback function. See 8.1 for the list of possible types. callback is the callback function that is invoked when an event of the specified type is received by the client. See 8.2 for a description of the callback function. passback is a value that the client wants passed to the callback function when it is invoked.
Return Value
Return
Indication
SPD_normalCN SPD_notInitializedCN SPD_invalidTypeCN SPD_commFailureCN
No error SPD_InitClient not called previously Bad type parameter Communications problem
See Also
See also the following client functions: SPD_AckAlarm (see 7.1) SPD_ClearAlarm (see 7.4) SPD_DeleteObject (see 7.6) SPD_LogMessage (see 7.10) SPD_MainLoop (see 7.11) SPD_ProcessEvents (see 7.13) SPD_ReportValue (see 7.16) SPD_RequestEvents (see 7.17) SPD_SendAlarm (see 7.18) SPD_SendUserAlarm (see 7.19)
Use of this function is illustrated in 6.1 and 6.7.
7844 8107---008
7---13
Client Features
7.9. SPD_InitClient
Purpose
Initialize the Event Server API. A client application must call this function before calling any other SPD function.
Syntax
#include "spd.h" SPD_errorTP SPD_InitClient( char *applicationName, char *applicationQualifier );
Description
applicationName is the name that identifies the client application to the Event Server. This is the name that will be associated with events generated by the client. applicationQualifier further qualifies the client application in the case where more than one instance of the client may be present. This is an optional parameter. Specify NULL if the client is not further qualified.
Library Levels
In some situations, installing a newer level of Operations Sentinel may cause incompatibilities in Event Server API library levels. Client applications that are linked with older levels of the Event Server API library may no longer function properly. The client application is informed about incompatibility in software levels in one of the following ways: If the Event Server is active when the client calls the function SPD_InitClient The function returns the status SPD_versionMismatchCN Any calls to other API functions return an error status
If the Event Server is not active when the client calls the function SPD_InitClient and an incompatible version of the Event Server later becomes active The function returns the status SPD_normalCN The client is terminated when it connects to the Event Server An error message is sent to standard output (stdout)
In either of these cases, you must recompile and relink the client application with the new Event Server API library and header files.
7---14
7844 8107---008
Client Features
Return Value
Return
Indication
SPD_normalCN SPD_alreadyInitializedCN SPD_badApplicationCN SPD_versionMismatchCN
No error. SPD_InitClient has already been called. Bad value for applicationName parameter. The client application is linked with a version of the Event Server API library that is incompatible with the Event Server of the currently installed level of Operations Sentinel. Communications problem.
SPD_commFailureCN
See Also
See also the client function SPD_Terminate (see 7.20).
7844 8107---008
7---15
Client Features
7.10. SPD_LogMessage
Purpose
Format and send a log event to the Event Server.
Syntax
#include "spd.h" SPD_errorTP SPD_LogMessage( char *logName, char *messageType, char *message, char *application, char *applicationQualifier, time_t timeValue );
Description
logName is the name of the log where the message should be logged. It is written to the current days file for that log. messageType is a two-character identifier for the message. This is an optional parameter. If you specify NULL, the message type is set to NO (normal). message is the message to be logged. application identifies the application that logged the message. Specify NULL if the application is the same as the application that you specified on the call to SPD_InitClient. applicationQualifier further qualifies the application in the case where more than one instance of the application may be present. Specify NULL if the application qualifier is the same as the application qualifier that you specified on the call to SPD_InitClient. timeValue is the local time to be associated with the logged message. Specify the result of the C time function or 0 if no local time is to be associated with the message.
7---16
7844 8107---008
Client Features
Return Value
Return
Indication
SPD_normalCN SPD_notInitializedCN SPD_badFileNameCN SPD_badTextCN SPD_commFailureCN
No error SPD_InitClient not called previously Bad logFileName parameter Bad message parameter Communications problem
See Also
See also the client function SPD_HandleEvent (7.8). Use of this function is illustrated in 6.3.
7.11. SPD_MainLoop
Purpose
Enter an event loop waiting for SPD events. The function never returns unless there is an error. This function is intended for UNIX systems, but you can use it in clients on Windows systems, although the results are limited since this function does not handle Windows events. Use SPD_ProcessEvents as an alternative on Windows.
Syntax
#include "spd.h" SPD_errorTP SPD_MainLoop(void);
Return Value
A return value of SPD_notInitializedCN indicates that the SPD_InitClient client function was not previously called.
See Also
Contrast with the corresponding client function SPD_ProcessEvents for Windows systems (7.13). Use of this function is illustrated in 6.1, 6.5, 6.6, and 6.7.
7844 8107---008
7---17
Client Features
7.12. SPD_MonitorEventState
Purpose
Register a callback function that is invoked when the availability of a type of event changes state. Calling this function also causes the callback to be invoked immediately to report the event type's current state of availability.
Syntax
#include "spd.h" SPD_errorTP SPD_MonitorEventState( SPD_eventTypeTP eventType, SPD_eventStateCallbackTP callback, SPD_passbackTP passback );
Description
eventType is the type of event whose availability is to be monitored. See 8.1 for the list of possible types. callback is the name of the function that is invoked when an event state change is detected, for example, when the source of the event type goes online or offline. See 8.2 for a description of the callback function. Specify NULL to turn off event state reporting for the event type for this client. passback is a value passed to the callback function when it is invoked.
Return Value
Return
Indication
SPD_normalCN SPD_notInitializedCN SPD_badTypeCN SPD_commFailureCN
No error SPD_InitClient not called Bad eventType parameter Communications problem
See Also
7---18
7844 8107---008
Client Features
7.13. SPD_ProcessEvents
Purpose
For clients on Windows systems only. Enter an event loop and process all outstanding SPD events. Once all events have been processed, this function returns to the caller. Use of this function allows you to merge the SPD event loop with a Windows event loop. You should use it instead of SPD_MainLoop for a client that runs on a Windows system. For example, the Windows event loop can be periodically interrupted via a timer event. The handler for the timer event can call SPD_ProcessEvents to process all outstanding SPD events before returning to the Windows event loop. This is illustrated in 2.2.
Syntax
#include "spd.h"
SPD_errorTP SPD_ProcessEvents(void);
Return Value
A return value of SPD_notInitializedCN indicates that the SPD_InitClient client function was not previously called.
See Also
Contrast with the corresponding client function SPD_MainLoop for UNIX systems (7.11). Use of this function is illustrated in 2.2.
7844 8107---008
7---19
Client Features
7.14. SPD_RemoveInput
Purpose
Remove an input source that was created by calling SPD_AddInput. Note: This function is not supported in the Windows implementation of the Event Server API.
Syntax
#include "spd.h" SPD_errorTP SPD_RemoveInput( SPD_inputTP id );
Description
id is the identifier of the event source returned by the call to SPD_AddInput.
Return Value
Return
Indication
SPD_normalCN SPD_notInitializedCN SPD_badInputCN
No error SPD_InitClient not called previously Bad id parameter
See Also
See also the client function SPD_AddInput (7.2).
7.15. SPD_RemoveTimeOut
Purpose
Remove a timer that was created by calling SPD_AddTimeOut.
Syntax
#include "spd.h" SPD_errorTP SPD_RemoveTimeOut( SPD_timeoutTP timer );
7---20
7844 8107---008
Client Features
Description
timer is the identifier of the timer returned by the call to SPD_AddTimeOut.
Return Value
Return
Indication
SPD_normalCN SPD_notInitializedCN SPD_badTimerCN
No error SPD_InitClient not called previously Bad timer parameter
See Also
See also the client function SPD_AddTimeOut (7.3).
7.16. SPD_ReportValue
Purpose
Format and send an attribute change event to the Event Server.
Syntax
#include "spd.h" SPD_errorTP SPD_ReportValue( char *objectClass, char *objectName, char *hostName, char *application, char *applicationQualifier, time_t timeValue, int attrCount, char *attrNames[], char *attrValues[] );
7844 8107---008
7---21
Client Features
Description
objectClass identifies the class of the object that contains the attributes whose values are being reported (for example, a disk drive or application). objectName identifies the instance of the object class (for example, a disk drive name or application name). hostName identifies the name of the host on which the object instance resides. application identifies the application that is reporting the attribute value. Specify NULL if the application is the same as the application that you specified on the call to SPD_InitClient. applicationQualifier further qualifies the application in the case where more than one instance of the application may be present. Specify NULL if the application qualifier is the same as the application qualifier that you specified on the call to SPD_InitClient. timeValue is the local time to be associated with reporting of the value. Specify the result of the C time function, or 0 if no local time is to be associated with reporting of the value. attrCount is the number of attributes whose values are being reported for the specified object. attrNames is an array of the attribute names whose values are being reported. There must be attrCount entries in this array. It is the responsibility of the calling program to allocate the memory for this array. There is a one-to-one correspondence between the entries in the attrNames and attrValues arrays, such that the first entry in the attrNames array corresponds to the first entry of the attrValues array. Names in this array cannot be NULL. attrValues is an array of the attribute values being reported. There must be attrCount entries in this array. It is the responsibility of the calling program to allocate the memory for this array. There is a one-to-one correspondence between the entries in the attrNames and attrValues arrays, such that the first entry in the attrNames array corresponds to the first entry of the attrValues array. Values in this array can be NULL.
7---22
7844 8107---008
Client Features
Return Value
Return
Indication
SPD_normalCN SPD_notInitializedCN SPD_badClassCN SPD_badNameCN SPD_badAttributeCN SPD_badHostCN SPD_commFailureCN
No error SPD_InitClient not called previously Bad objectClass parameter Bad objectName parameter Bad attrNames parameter Bad hostName parameter Communications problem
See Also
See also the client function SPD_HandleEvent (7.8). Use of this function is illustrated in 6.4.
7.17. SPD_RequestEvents
Purpose
Request information for all alert events from the Event Server. Outstanding events are reported individually through the normal event callback function, registered by SPD_HandleEvent.
Syntax
#include "spd.h" SPD_errorTP SPD_RequestEvents( SPD_eventTypeTP eventType );
Description
eventType identifies the type of event being requested. This function currently supports only events of type SPD_alarmEventCN.
7844 8107---008
7---23
Client Features
Return Value
Return
Indication
SPD_normalCN SPD_invalidTypeCN SPD_notInitializedCN SPD_commFailureCN
No error Bad eventType parameter SPD_InitClient not called previously Communications problem
See Also
See also the client function SPD_HandleEvent (7.8).
7.18. SPD_SendAlarm
Purpose
Format and send an alert event to the Event Server. The alert cannot include userdefined attributes. Use SPD_SendUserAlarm instead if the alert includes user-defined attributes.
Syntax
#include "spd.h" SPD_errorTP SPD_SendAlarm( char *objectClass, char *objectName, char *alarmIdentifier, char *alarmQualifier, char *alarmText, char *helpText, char *externalActionList, SPD_alarmSeverityTP severity, char *application, char *applicationQualifier, time_t timeValue );
7---24
7844 8107---008
Client Features
Description
objectClass identifies the object that is the source of the alert (for example, a system or application). objectName identifies the instance of the object class that is the source of the alert (for example, a system name or application name). alarmIdentifier identifies the type of alert being raised. This value can also be the name of the optional help text file for the alert, if the value you specify for parameter helpText is NULL. This value can also be the identifier of the external action list that is associated with raising this alert, if the value you specify for parameter externalActionList is NULL. alarmQualifier further qualifies the type of alert when multiple alerts with the same alarmIdentifier are raised and must be kept distinct from one another. This parameter is optional. Specify NULL if the alert is not further qualified. alarmText is a description of the alert condition. helpText is used to provide help text for this alert. Help text is identified for this alert using the following set of rules: If the value of helpText represents a file name in the Operations Sentinel help text folder, the contents of that file is the help text. Otherwise, if the value of helpText is not NULL, the value of helpText is the actual help text. Otherwise, if the value of helpText is NULL and the value of the parameter alarmIdentifier represents a file name in the Operations Sentinel help text folder, then the contents of that file is the help text. Otherwise, there is no help text for this alert.
externalActionList is the identifier of the external action list that is associated with raising this alert. External action lists are defined in alert policies. If no external action list is associated with raising this alert, or if the identifier of the external action list is the same as the value specified for parameter alarmIdentifier, specify NULL. severity indicates the severity of the alert. See 8.1 for a list of values for the severity of an alert. Do not specify either SPD_clearCN or SPD_acknowledgeCN. Instead, use the function SPD_ClearAlarm to clear an alert, or the function SPD_AckAlarm to acknowledge an alert.
7844 8107---008
7---25
Client Features
application identifies the application that is raising the alert. Specify NULL if the application is the same as the application that you specified on the call to SPD_InitClient. applicationQualifier further qualifies the application in the case where more than one instance of the application may be present. Specify NULL if the application qualifier is the same as the application qualifier that you specified on the call to SPD_InitClient. timeValue is the local time to be associated with the alert. Specify the result of the C time function, or 0 if you want no local time raising to be associated with the alert.
Return Value
Return
Indication
SPD_normalCN SPD_notInitializedCN SPD_badClassCN SPD_badNameCN SPD_badAlarmIdCN SPD_badAlarmQualifierCN SPD_badTextCN SPD_badSeverityCN SPD_commFailureCN
No error SPD_InitClient not called previously Bad objectClass parameter Bad objectName parameter Bad alarmIdentifier parameter Bad alarmQualifier parameter Bad alarmText parameter Bad severity parameter Communications problem
See Also
See also the following client functions: SPD_AckAlarm (see 7.1) SPD_ClearAlarm (see 7.4) SPD_HandleEvent (see 7.8) SPD_SendUserAlarm (see 7.19)
7---26
7844 8107---008
Client Features
7.19. SPD_SendUserAlarm
Purpose
Format and send an alert event to the Event Server. The event can specify names and values for one or more user-defined attributes.
Syntax
#include "spd.h" SPD_errorTP SPD_SendUserAlarm( char *objectClass, char *objectName, char *alarmIdentifier, char *alarmQualifier, char *alarmText, char *helpText, char *externalActionList, SPD_alarmSeverityTP severity, char *application, char *applicationQualifier, time_t timeValue int attrCount, char*attrNames[] char*attrValues[] );
Description
objectClass identifies the object that is the source of the alert (for example, a system or application). objectName identifies the instance of the object class that is the source of the alert (for example, a system name or application name). alarmIdentifier identifies the type of alert being raised. This value can also be the name of the optional help text file for the alert, if the value you specify for parameter helpText is NULL. This value can also be the identifier of the external action list that is associated with raising this alert, if the value you specify for parameter externalActionList is NULL. alarmQualifier further qualifies the type of alert when alerts with the same alarmIdentifier are raised and must be kept distinct from one another. This parameter is optional. Specify NULL if the alert is not further qualified.
7844 8107---008
7---27
Client Features
alarmText is a description of the alert condition. helpText is used to provide help text for this alert. Help text is identified for this alert using the following set of rules: If the value of helpText represents a file name in the Operations Sentinel help text folder, the contents of that file is the help text. Otherwise, if the value of helpText is not NULL, the value of helpText is the actual help text. Otherwise, if the value of helpText is NULL and the value of the parameter alarmIdentifier represents a file name in the Operations Sentinel help text folder, then the contents of that file is the help text. Otherwise, there is no help text for this alert.
externalActionList is the identifier of the external action list that is associated with raising this alert. External action lists are defined in alert policies. If no external action list is associated with raising this alert, or if the identifier of the external action list is the same as the value specified for parameter alarmIdentifier, specify NULL. severity indicates the severity of the alert. See 8.1 for a list of values for the severity of an alert. Do not specify either SPD_clearCN or SPD_acknowledgeCN. Instead, use the function SPD_ClearAlarm to clear an alert, or the function SPD_AckAlarm to acknowledge an alert. application identifies the application that is raising the alert. Specify NULL if the application is the same as the application that you specified on the call to SPD_InitClient. applicationQualifier further qualifies the application in the case where more than one instance of the application may be present. Specify NULL if the application qualifier is the same as the application qualifier that you specified on the call to SPD_InitClient. timeValue is the local time to be associated with the alert. Specify the result of the C time function, or 0 if you want no local time to be associated with raising the alert. attrCount is the number of user-defined attributes specified by the parameters attrNames and attrValues. attrNames is an array of names of any user-defined attributes you want to specify for the alert. There must be attrCount entries in this array. It is the responsibility of the calling program to allocate the memory for this array. There is a one-to-one correspondence between the entries in the arrays attrNames and attrValues. Names in this array cannot be NULL or null strings.
7---28
7844 8107---008
Client Features
attrValues is an array of values of any user-defined attributes you want to specify for the alert. There must be attrCount entries in this array. It is the responsibility of the calling program to allocate the memory for this array. There is a one-to-one correspondence between the entries in the arrays attrNames and attrValues. Values in this array can be NULL or null strings, in which case a null string is reported as the attribute value to the receiver of the event report.
Return Value
Return
Indicates
SPD_normalCN SPD_notInitializedCN SPD_badClassCN SPD_badNameCN SPD_badAlarmIdCN SPD_badAlarmQualifierCN SPD_badAttributeCN SPD_badTextCN SPD_badSeverityCN SPD_commFailureCN
No error SPD_InitClient not called previously Bad objectClass parameter Bad objectName parameter Bad alarmIdentifier parameter Bad alarmQualifier parameter NULL user-defined attribute name Bad alarmText parameter Bad severity parameter Communications problem
See Also
See also the following client functions: SPD_AckAlarm (see 7.1) SPD_ClearAlarm (see 7.4) SPD_HandleEvent (see 7.8) SPD_SendAlarm (see 7.18)
7844 8107---008
7---29
Client Features
7.20. SPD_Terminate
Purpose
Terminate all connections to event services.
Syntax
#include "spd.h" SPD_errorTP SPD_Terminate(void);
Description
This function terminates all connections to the Event Server, freeing the file descriptors associated with those connections and releasing system resources. Use this function in clients that intermittently send events to Event Server but are not registered to receive events from Event Server. Since the number of connected clients is limited by available system resources, you should use this function in clients wherever possible. To reestablish a connection to the Event Server, call a function that sends an event, for example, SPD_SendAlarm. There is no need to call SPD_InitClient again, nor should the client attempt to do so. If the client does, the error SPD_alreadyInitializedCN results.
Return Value
Return
Indication
SPD_normalCN SPD_notInitializedCN
no error SPD_InitClient not called previously
7---30
7844 8107---008
Section 8 Data Definitions

This section describes two types of data definitions used in client functions: typedefs and callbacks. This section lists the possible values for each data definition. For usage of these definitions, refer to the client function descriptions in Section 7. All definitions shown in this section are defined in header file spd.h.
8.1. Typedefs
This subsection lists the members and possible values for each typedef data definition, arranged in alphabetical order.
SPD_alarmEventTP
Purpose Defines the portion of an event report that is specific to alert event reports. This structure is contained in SPD_eventTP, defined elsewhere in this section. Syntax typedef struct { SPD_alarmSeverityTP severity; char *alarmIdentifier; char *alarmQualifier; char *alarmText; char *helpText; char *externalActionList; } SPD_alarmEventTP; Description severity indicates the severity of the alert. SPD_alarmSeverityTP is defined elsewhere in this section. alarmIdentifier identifies the type of alert. This value can also be the name of the optional help text file for the alert, if the value returned for helpText is NULL. This value can also be the name of the optional external action list, if the value returned for externalActionList is NULL.
7844 8107---008
8---1
Data Definitions
alarmQualifier further qualifies the type of alert when multiple alerts with the same alarmIdentifier are raised and must be kept distinct from one another. This value may be NULL. alarmText explains the alert condition. helpText provides help text for this alert. Help text is identified for an alert using the following set of rules: If the value of helpText is the name of a file name in the Operations Sentinel help text folder, the contents of that file is the help text. Otherwise, if the value of helpText is not NULL, the value of helpText is the actual help text. Otherwise, if the value of helpText is NULL and the value of alarmIdentifier is the name of a file in the Operations Sentinel help text folder, then the contents of that file is the help text. Otherwise, there is no help text for the alert.
externalActionList identifies the external action list that is associated with this alert. External action lists are defined in alert policies. This value may be NULL.
SPD_alarmSeverityTP
Purpose Defines the set of possible values for the severity of an alert event report. Syntax typedef enum { SPD_criticalCN, SPD_majorCN, SPD_minorCN, SPD_warningCN, SPD_informationalCN, SPD_indeterminateCN, SPD_clearCN, SPD_acknowledgeCN } SPD_alarmSeverityTP; Description SPD_criticalCN indicates an alert of critical severity. SPD_majorCN indicates an alert of major severity.
8---2
7844 8107---008
Data Definitions
SPD_minorCN indicates an alert of minor severity. SPD_warningCN indicates an alert of warning severity. SPD_informationalCN indicates an alert of informational severity. SPD_indeterminateCN indicates an alert of indeterminate severity. SPD_clearCN indicates an alert that has been cleared. SPD_acknowledgeCN indicates an alert that has been acknowledged, but not cleared.
SPD_commandStatusTP
Purpose Defines the set of possible values for the status of submission of a command to a host (managed system). It is passed to the callback function specified for SPD_Command. See 7.5. Syntax typedef enum { SPD_unknownStatusCN, SPD_commandSuccessCN, SPD_illegalCommandCN, SPD_unknownHostCN, SPD_unreachableHostCN, SPD_hostNotReadyCN, SPD_accessDeniedCN } SPD_commandStatusTP; Description SPD_commandSuccessCN means that, as far as the Event Server can detect, the command was successfully sent to the specified host. SPD_illegalCommandCN means that an error in the format of the command was detected. This value is only reported for commands to OS 2200 consoles. SPD_unknownHostCN means that the Event Server does not know about the specified host. This typically means that the Operations Sentinel server is not currently managing the host or the host name is in error.
7844 8107---008
8---3
Data Definitions
SPD_unreachableHostCN means that the specified host name is valid, but the command could not be sent. This could be because the host is down or the connection to the host is down. Retrying the command at a future time may or may not be successful. SPD_hostNotReadyCN means that the specified host is not in a state to receive another command (that is, it is still processing the last command). This status is returned for OS 2200 hosts only. SPD_unknownStatusCN means something went wrong during reporting of the status. (This status should never be returned.) SPD_accessDeniedCN means the specified host system is not configured to receive commands. The site administrator can limit command submission to each host system using the Operations Sentinel Configuration application. Unlimited access, automation access (the default), or no access can be specified. This status is returned if the host is configured for automation access or for no access. See the Operations Sentinel Administration and Configuration Guide for further information.
SPD_errorTP
Purpose Defines the set of possible values that are returned by calls to the Event Server API functions. See Section 7. A value of this type can be passed to SPD_GetErrorMessage. See 7.7. Syntax typedef enum { SPD_normalCN, SPD_notInitializedCN, SPD_alreadyInitializedCN, SPD_versionMismatchCN, SPD_invalidTypeCN, SPD_commFailureCN, SPD_badTimerCN, SPD_badInputCN, SPD_badFormatCN, SPD_badClassCN, SPD_badNameCN, SPD_badApplicationCN, SPD_badAlarmIdCN, SPD_badAlarmQualifierCN, SPD_badTypeCN, SPD_badTextCN, SPD_badAttributeCN, SPD_badValueCN, SPD_badFileNameCN,
8---4
7844 8107---008
Data Definitions
SPD_badSeverityCN, SPD_badHostCN, SPD_badCommandCN, SPD_badCallbackCN, SPD_badReservedValueCN, SPD_badTimeCN, SPD_obsoleteInterfaceCN } SPD_errorTP; Description SPD_normalCN means that no error occurred. SPD_notInitializedCN means that the SPD_InitClient function was not previously called. SPD_alreadyInitializedCN means that the SPD_InitClient function has already been called. SPD_versionMismatchCN means that the client is linked with a version of the Event Server API that is incompatible with the Event Server included with the level of Operations Sentinel running on the Operations Sentinel server. SPD_invalidTypeCN means that an invalid type parameter was specified. SPD_commFailureCN means that a communications problem occurred. SPD_badTimerCN means that an invalid timer parameter was specified. SPD_badInputCN means that an invalid ID parameter was specified. SPD_badFormatCN means that an invalid event report format was specified. SPD_badClassCN means that an invalid objectClass parameter was specified. SPD_badNameCN means that an invalid objectName parameter was specified. SPD_badApplicationCN means that an invalid applicationName parameter was specified. SPD_badAlarmIdCN means that an invalid alarmIdentifier parameter was specified.
7844 8107---008
8---5
Data Definitions
SPD_badAlarmQualifierCN means that an invalid alarmQualifier parameter was specified. SPD_badTypeCN means that an invalid type parameter was specified. SPD_badTextCN means that an invalid message parameter was specified. SPD_badAttributeCN means that an invalid attrNames parameter was specified. SPD_badValueCN means that an invalid attrValues parameter was specified. SPD_badFileNameCN means that an invalid logFileName parameter was specified. SPD_badSeverityCN means that an invalid severity parameter was specified. SPD_badHostCN means that an invalid hostName parameter was specified. SPD_badCommandCN means that an invalid command parameter was specified. SPD_badCallbackCN means that an invalid callback parameter was specified. SPD_badReservedValueCN means that SPD_reservedValueCN was not specified as the reserved value. SPD_badTimeCN means that an invalid senderTime attribute was specified. SPD_obsoleteInterfaceCN means that a normal status was returned from the obsolete command, SPD_SendCommand. Use SPD_Command instead. See 7.5
8---6
7844 8107---008
Data Definitions
SPD_eventTP
Purpose Defines the basic structure for all event reports. A structure of this type is passed to the callback function for SPD_HandleEvent. See 7.8. Syntax typedef struct { SPD_eventTypeTP type; char *objectClass; char *objectName; char *applicationName; char *applicationQualifier; char *host; time_t senderTime; time_t serverTime; int variableCount; SPD_variableDataTP *variableData; union { SPD_alarmEventTP alarm; SPD_logEventTP log; } eventData; } SPD_eventTP; Description type is the type of event. SPD_eventTypeTP is defined elsewhere in this subsection. objectClass identifies the class of the object that is the source of the event, for example, a disk drive name or application. objectName identifies the instance of the object class that is the source of the event, for example, a disk drive name or application name. applicationName is the name of the application that sent the event. applicationQualifier further qualifies the applicationName in case more than one instance of the application may be present. This value can be null. host identifies the host system to which the event applies, as used by attribute-change and delete-object events.
7844 8107---008
8---7
Data Definitions
senderTime is the optional time stamp specified by the event sender. senderTime can be 0 (zero). serverTime is the optional time stamp added by the Event Server. serverTime can be 0 (zero). variableCount is the number of items in the variableData array. This item is used only for alert and attribute-change events. For other events, the variableCount is 0 (zero). variableData is a variable data area for alert and attribute-change events. SPD_variableDataTP is described elsewhere in this section. alarm describes the portion of the parsed event report that is specific to alert event reports. SPD_alarmEventTP is described elsewhere in this subsection. log describes the portion of the parsed event report that is specific to log event reports. SPD_logEventTP is described elsewhere in this subsection.
SPD_eventStateTP
Purpose Defines the set of possible event states as reported by the event state callback, which is registered by SPD_MonitorEventState (see 7.12). Also see SPD_eventStateCallbackTP in 0. Syntax typedef enum { SPD_eventUnknownCN, SPD_eventDownCN, SPD_eventUpCN } SPD_eventStateTP; Description SPD_eventUnknown is a state that never occurs. SPD_eventDownCN means that the Event Server is not currently handling the event in question. If there are two Operations Sentinel servers configured (see 5.7), then neither is handling the event. SPD_eventUpCN means that the Event Server is currently handling the event type in question. The Event Server can be located on the primary or the secondary Operations Sentinel server.
8---8
7844 8107---008
Data Definitions
SPD_eventTypeTP
Purpose Defines the set of possible event types. You must specify a parameter with this data type when calling SPD_MonitorEventState (see 7.12). A value of this type is passed to the callback function registered by SPD_MonitorEventState (see SPD_eventStateCallbackTP in 8.2). Syntax typedef enum { SPD_unknownEventCN, SPD_alarmEventCN, SPD_attributeChangeEventCN, SPD_deleteObjectEventCN, SPD_logEventCN } SPD_eventTypeTP; Description SPD_unknownEventCN is an illegal event type. SPD_alarmEventCN identifies an alert event. SPD_attributeChangeEventCN identifies an attribute-change event. SPD_deleteObjectEventCN identifies a delete-object event. SPD_logEventCN identifies a log event.
SPD_inputTP
Purpose A handle for an I/O handler that a client can use to uniquely identify the I/O handler. SPD_inputTPstruct is an undefined data type that hides the real structure of the handle from the calling program. A value of this data type is returned by SPD_AddInput (see 7.2), and is supplied as a parameter to SPD_RemoveInput (see 7.14). Syntax typedef struct SPD_inputTPstruct *SPD_inputTP;
7844 8107---008
8---9
Data Definitions
SPD_inputTypeTP
Purpose Defines the set of possible I/O events that can be monitored through calls to SPD_AddInput (see 7.2). Syntax typedef enum { SPD_readCN, SPD_writeCN } SPD_inputTypeTP;
SPD_logEventTP
Purpose Defines the portion of a parsed event report that is specific to log event reports. This structure is contained in SPD_eventTP, described elsewhere in this section. Syntax typedef struct { char *messageType; char *logText; } SPD_logEventTP; Description messageType is the optional message type specified by the sender. messageType can be a NULL string. logText is the message to be logged.
SPD_passbackTP
Purpose A handle for passback data that the Event Server API uses to declare passback data in a type-independent fashion. SPD_passbackTPstruct is an undefined data type that hides the real structure of the handle from the calling program. Each function that registers a passback function supplies a value of this data type. Each invocation of a passback function (see 0) is passed the value that was specified by the function that registered it. Syntax typedef struct SPD_passbackTPstruct *SPD_passbackTP;
8---10
7844 8107---008
Data Definitions
SPD_timeoutTP
Purpose A handle for a timer handler that a client can use to uniquely identify the timer handler. SPD_timeoutTPstruct is an undefined value that hides the real structure of the handle from the calling program. A value of this type is returned by SPD_AddTimeOut (see 7.3), and is supplied as a parameter to SPD_RemoveTimeOut (see 7.15). Syntax typedef struct SPD_timeoutTPstruct *SPD_timeoutTP;
SPD_variableDataTP
Purpose Defines the structure of free format data for an event. This is used for alert and attribute-change event reports where you can specify any number of attributes. This structure is contained in SPD_eventTP, described elsewhere in this section. Syntax typedef struct { char *attribute; char *value; } SPD_variableDataTP;
7844 8107---008
8---11
Data Definitions
8.2. Callbacks
This subsection describes callback functions, listed in alphabetical order. One of these client functions is called by the Event Server when an event for which the client has registered occurs. Each callback function defined by a client program must follow the format defined in this subsection.
SPD_commandCallbackTP
Purpose Called when a client receives a command acknowledgment. You can optionally specify this callback when you call the function SPD_Command (see 7.5). This callback is used since the command may or may not be submitted to the host system by the Event Server. The Event Server asynchronously returns a command status to the client using this callback. Syntax typedef void (*SPD_commandCallbackTP)( char *hostClass, char *host, char *command, void *reservedValue, SPD_commandStatusTP status, SPD_passbackTP passback ); Description hostClass is the value for the objectClass parameter that you specified on the call to SPD_Command. host is the value for the objectName parameter that you specified on the call to SPD_Command. command is the value for the command parameter that you specified on the call to SPD_Command. reservedValue is provided for future use and is always set to SPD_reservedValueCN. status is the status indicating what happened when the Event Server tried to submit the command to the host. SPD_commandStatusTP is described in 8.1. passback is the value for the passback parameter that you specified on the call to SPD_Command. SPD_passbackTP is described in 8.1.
8---12
7844 8107---008
Data Definitions
SPD_eventCallbackTP
Purpose Called when a client receives an event from the Event Server. Register this callback by calling SPD_HandleEvent (see 7.8). Syntax typedef void (*SPD_eventCallbackTP)( SPD_eventTypeTP type, SPD_eventTP *event, SPD_passbackTP passback ); Description type is the type of event. SPD_eventTypeTP is described in 8.1. event is a data structure that returns all available information on the event. This structure is described in 8.1. passback is the value that the client specified for the passback parameter when it called SPD_HandleEvent.
SPD_eventStateCallbackTP
Purpose Called for a client when a change is detected regarding the source of an event type within the Event Server. Register this callback by calling SPD_MonitorEventState (see 7.12). Syntax typedef void (*SPD_eventStateCallbackTP)( SPD_eventTypeTP event, SPD_eventStateTP status, SPD_passbackTP passback ); Description event identifies the type of event whose state is being reported. SPD_eventTypeTP is described in 8.1 status is the new event state. SPD_eventStateTP is described in 8.1.
7844 8107---008
8---13
Data Definitions
passback is the value that the client specified for the passback parameter when it called SPD_MonitorEventState.
SPD_inputCallbackTP
Purpose Called when an I/O event occurs on a file descriptor that is being monitored by a client. Register this callback by calling SPD_AddInput (see 7.2). Syntax typedef void (*SPD_inputCallbackTP)( SPD_inputTP id, SPD_passbackTP passback ); Description id is the value returned by the call to SPD_AddInput. SPD_inputTP is described in 8.1. passback is the value that the client specified for the passback parameter when it called SPD_AddInput.
SPD_timeoutCallbackTP
Purpose Called when a timer expires for a client. Register this callback by calling SPD_AddTimeOut (see 7.3). Syntax typedef void (*SPD_timeoutCallbackTP)( SPD_timeoutTP id, SPD_passbackTP passback ); Description id is the value returned by the call to SPD_AddTimeOut. SPD_timeoutTP is described in 8.1. passback is the value that the client specified for the passback parameter when it called SPD_AddTimeOut.
8---14
7844 8107---008
Appendix A Permuted Index

Using the Permuted Index
To use the permuted index, first look in the second column for a key word. Note that the second column is alphabetically organized. When you have found the key word, look in the first column for any additional information. When you have found a match for the information you seek, check the third column for the name of the function. The number in parentheses is the number of the subsection in which you will find the information.
Index
Additional Information Keyword Function Name
format and send an format and send an format and send an format and send an register a register a register a register a
acknowledge-alert event to the Event Server alert event to the Event Server alert event with user defined attributes to the event server attribute-change event to the Event Server callback for event state changes callback for events callback that is invoked after a timeout period has elapsed callback that is invoked when an I/O event occurs on a file descriptor clear-alert event to the Event Server client command to the Event Server, which forwards the command to a host system connections to event services
SPD_AckAlarm (7.1) SPD_SendAlarm (7.18) SPD_SendUserAlarm (7.19) SPD_ReportValue (7.16) SPD_MonitorEventState (7.12) SPD_HandleEvent (7.8) SPD_AddTimeOut (7.3) SPD_AddInput (7.2)
format and send a initialize a send a
SPD_ClearAlarm (7.4) SPD_InitClient (7.9) SPD_Command (7.5)
terminate all
SPD_Terminate (7.20)
7844 8107---008
A---1
Permuted Index
Additional Information
Keyword
Function Name
format and send a
delete-object event to the Event Server enter an event loop, waiting for SPD events
SPD_DeleteObject (7.6) SPD_MainLoop (7.11) SPD_GetErrorMessage (7.7) SPD_MainLoop (7.11) SPD_Terminate (7.20) SPD_MonitorEventState (7.12) SPD_HandleEvent (7.8) SPD_RequestEvents (7.17) SPD_ClearAlarm (7.4) SPD_DeleteObject (7.6) SPD_LogMessage (7.10) SPD_AckAlarm (7.1)
Return a text description of an enter an terminate all connections to register a callback for register a callback for request information for all
error status event loop, waiting for SPD events event services event state changes events events of a specific type from the Event Server format and send a clear-alert event to the Event Server format and send a delete-object event to the Event Server format and send a log event to the Event Server format and send an acknowledge-alert event to the Event Server format and send an alert event to the Event Server format and send an attribute-change event to the Event Server forward a command to a host
SPD_SendAlarm (7.18) SPD_SendUserAlarm (7.19) SPD_ReportValue (7.16)
SPD_Command (7.5) SPD_AddInput (7.2) SPD_RemoveInput (7.14) SPD_InitClient (7.9) SPD_LogMessage (7.10) SPD_AddTimeOut (7.3) SPD_AddInput (7.2)
callback that is invoked when an remove an
I/O event occurs on a file descriptor I/O handler initialize a client
format and send a
log event to the Event Server register a callback that is invoked after a timeout period has elapsed register a callback that is invoked when an I/O event occurs on a file descriptor register a callback for events register a callback for event state changes
SPD_HandleEvent (7.8) SPD_MonitorEventState (7.12)
A---2
7844 8107---008
Permuted Index
Additional Information
Keyword
Function Name
remove a timer remove an I/O handler request information for all events of a specific type from the Event Server return a text description of an error status format and send a clear-alert event to the Event Server send a command to the Event Server, which forwards the command to a host system format and format and format and send a delete-object event to the Event Server send a log event to the Event Server send an acknowledge-alert event to the Event Server send a raise-alert event to the Event Server format and enter an event loop, waiting for send an attribute-change event to the Event Server SPD events terminate all connections to event services return a register a callback that is invoked after a remove a format and send a raise-alert event with text description of an error status timeout period has elapsed timer user defined attributes to the event server
SPD_RemoveTimeOut (7.15) SPD_RemoveInput (7.14) SPD_RequestEvents (7.17)
SPD_GetErrorMessage (7.7) SPD_ClearAlarm (7.4) SPD_Command (7.5)
SPD_DeleteObject (7.6) SPD_LogMessage (7.10) SPD_AckAlarm (7.1) SPD_SendAlarm (7.18) SPD_SendUserAlarm (7.19) SPD_ReportValue (7.16) SPD_MainLoop (7.11) SPD_Terminate (7.20) SPD_GetErrorMessage (7.7) SPD_AddTimeOut (7.3) SPD_RemoveTimeOut (7.15) SPD_SendUserAlarm (7.19)
7844 8107---008
A---3
Permuted Index
A---4
7844 8107---008
Index
A
alert recipient client, 6-1 source client, 6-3 using clients with, 3-4 architecture, Event Server application program interface, 3-1 attribute change client, 6-7 sending events to Operations Sentinel Console, 5-1 submitting commands and keyins, 5-3 timers, 6-8 command submission client, 5-3, 6-10
D
data definitions callbacks, 8-12 typedefs, 8-1 dataflow diagram, quick start example, 2-5
C
callback, 5-4 function, 5-2 SPD_commandCallbackTP, 8-12 SPD_eventCallbackTP, 8-13 SPD_eventStateCallbackTP, 8-13 SPD_inputCallbackTP, 8-14 SPD_timeoutCallbackTP, 8-14 client alert recipient, 6-1 alert source, 6-3 attribute change, 6-7 command submission, 6-10 distribution, 5-5 event state monitoring, 6-13 examples, 6-1 function SPD_AckAlarm, 7-1 SPD_DeleteObject, 7-10 SPD_GetErrorMessage, 7-12 SPD_LogMessage, 7-16 SPD_RemoveInput, 7-20 SPD_ReportValue, 7-21 SPD_SendAlarm, 7-24 SPD_SendUserAlarm, 7-27 SPD_Terminate, 7-30 input monitoring, 6-9 logging, 6-5
E
environment variable SPO_EVENT, 5-5 SPO_EVENT_SECONDARY, 5-5 event loop, 5-4 Event Server application program interface architecture, 3-1 client functions, 7-1 functions for sending events SPD_AckAlarm, 5-2 SPD_ClearAlarm, 5-2 SPD_DeleteObject, 5-2 SPD_LogMessage, 5-2 SPD_ReportValue, 5-2 SPD_SendAlarm, 5-2 location of files, 4-1 events callback, 5-4 receiving, 5-2 requesting outstanding, 5-3 sending, 5-1 state, monitoring, 6-13 example, quick start, 2-1
7844 8107---008
Index---1
Index
F
function SPD_AckAlarm, 7-1 SPD_Command, 7-8 SPD_DeleteObject, 7-10 SPD_GetErrorMessage, 7-12 SPD_InitClient, 7-14 SPD_LogMessage, 7-16 SPD_RemoveInput, 7-20 SPD_RemoveTimeOut, 7-20 SPD_ReportValue, 7-21 SPD_RequestEvents, 7-23 SPD_SendAlarm, 7-24 SPD_SendUserAlarm, 7-27 SPD_Terminate, 7-30
P
passback data with SPD_Command function, 5-4 permuted index, A-1
Q
quick start coding of example, 2-2 dataflow diagram, 2-5 effect of client on Operations Sentinel Console, 2-4 example, 2-1
I
identifying the host, 5-4 index, permuted, A-1 input monitoring client, 6-9 input/output handlers, 5-5 integrating Windows Event Loop, 2-5
R
receiving events, 5-2 resilient server environments, 5-5
S
sending events Event Server API functions for, 5-2 SPD_alarmEventCN, 5-2 SPD_attributeChangeEventCN, 5-2 SPD_deleteObjectEventCN, 5-2 SPD_logEventCN, 5-2 SPD_AckAlarm function, 7-1 SPD_AddInput function input/output handlers, 5-5 SPD_AddTimeOut function timers, 5-5 SPD_alarmEventTP typedef, 8-1 SPD_alarmSeverityTP typedef, 8-2 SPD_Command function, 5-4, 7-8, 8-12 passback data, 5-4 SPD_commandCallbackTP callback, 8-12 SPD_commandStatusTP typedef, 8-3 SPD_DeleteObject function, 7-10 SPD_errorTP typedef, 8-4
K
keyin submission with client, 5-3
L
log using clients with, 3-4 logging client, 6-5 logon requirements for submitting commands and keyins with client, 5-3
M
monitoring event state client, 6-13
Index---2
7844 8107---008
Index
SPD_eventCallbackTP callback, 8-13 SPD_eventStateCallbackTP callback, 8-13 SPD_eventStateTP typedef, 8-8 SPD_eventTP data structure, 5-3 SPD_eventTP typedef, 8-7 SPD_eventTypeTP typedef, 8-9 SPD_GetErrorMessage function, 7-12 SPD_HandleEvent event callback, 5-4 function, 5-2 SPD_InitClient function, 7-14 SPD_inputCallbackTP callback, 8-14 SPD_inputTP typedef, 8-9 SPD_inputTypeTP typedef, 8-10 SPD_logEventTP typedef, 8-10 SPD_LogMessage function, 7-16 SPD_MainLoop event loop function, 5-4 function, 5-2 SPD_passbackTP typedef, 8-10 SPD_RemoveInput function description, 7-20 input/output handler, 5-5 SPD_RemoveTimeOut function description, 7-20 timers, 5-5 SPD_ReportValue function, 7-21 SPD_RequestEvents function, 5-3, 7-23 SPD_SendAlarm function, 7-24 SPD_SendUserAlarm function, 7-27 SPD_Terminate function, 7-30 SPD_timeoutCallbackTP callback, 8-14
SPD_timeoutTP typedef, 8-11 SPD_variableDataTP typedef, 8-11 Status using clients with, 3-4 submitting commands and keyins with client, 5-3
T
timers client, 5-5, 6-8 typedef SPD_alarmEventTP, 8-1 SPD_alarmSeverityTP, 8-2 SPD_commandStatusTP, 8-3 SPD_errorTP, 8-4 SPD_eventStateTP, 8-8 SPD_eventTP, 8-7 SPD_eventTypeTP, 8-9 SPD_inputTP, 8-9 SPD_inputTypeTP, 8-10 SPD_logEventTP, 8-10 SPD_passbackTP, 8-10 SPD_timeoutTP, 8-11 SPD_variableDataTP, 8-11
W
Windows Event Loop integrating, 2-5
7844 8107---008
Index---3
Index
Index---4
7844 8107---008
2011 Unisys Corporation. All rights reserved.
*78448107-008*
7844 8107008

Unisys: Clearpath Enterprise Servers

Uploaded by

Document Information

Original Description:

Original Title

Copyright

Available Formats

Share this document

Share or Embed Document

Sharing Options

Did you find this document useful?

Is this content inappropriate?

Copyright:

Available Formats

Unisys: Clearpath Enterprise Servers

Uploaded by

Copyright:

Available Formats

unisys

imagine it. done.

ClearPath Enterprise Servers

6.5. 6.6. 6.7. 6.8. Section 7.

Appendix A. Permuted Index Index ............................................................................................. 1

1.2. Documentation Updates

1.5. Notation Conventions

Section 2 Quick Start

2.1. What You Need to Get Started

How to Code the Example

Using a Make File

# additional C flags CPPFLAGS = -P $(INCLUDE) -DDEBUG

############################################################ ### OBJECT FILE DEFINITIONS ### ############################################################ APISAMPLE = \ apisample.o

############################################################ ### TARGETS ### ############################################################ all: apisample

Customizing the Make File

Effect of the Client on Operations Sentinel

{ // error processing AfxMessageBox("I forgot to call SPD_InitClient()!"); } } else CFrameWnd::OnTimer(nIDEvent); }

Section 3 Concepts and Definitions

Data Flow Diagram of the Example

2.2. Integrating the API with the Windows Event Loop

Concepts and Definitions

Concepts and Definitions

Concepts and Definitions

3.2. How to Use Clients with Operations Sentinel

Using Log Files

Sending Information to Operations Sentinel Console

Sending Commands to Hosts

Section 4 Library and Header Files

4.1. Files on the Server

Library and Header Files

4.2. API Files on Managed UNIX Systems

4.3. API Files on Managed Windows Systems

Section 5 Client Uses

5.1. Sending Events

Sending Events to Operations Sentinel Console

Events You Can Send

To Send This Event:

Use This Function:

Any of the following functions:

SPD_ReportValue (see 7.16) SPD_DeleteObject (see 7.6) SPD_LogMessage (see 7.10)

5.2. Receiving Events

Registering to Receive Events

Data Structure of SPD_eventTP

5.3. Requesting Outstanding Events

5.4. Submitting Commands

Logon Requirements for a Managed UNIX System

Identifying the Host

Submitting a Command Using SPD_Command

Using Passback Data

5.5. Event Loop Functions

Events and Event Callbacks

Clients specify event callbacks by calling SPD_HandleEvent (see 7.8).

5.6. Distributing Clients

5.7. Using Resilient Operations Sentinel Servers

Specifying a Secondary Server

File Format for SPO-Secondary

Event Report for Switch of Servers

The following fields are included in this event report:

Section 6 Client Examples

6.1. Alert Recipient

Data Flow Diagram

6.2. Alert Source